openapi: 3.1.0
info:
  title: Queues API
  description: |-
    Queues is a managed messaging service provided by Scaleway. It supports the API developed by Amazon with its Simple Queue Service, or **Amazon SQS**.
    If you're new to Queues, you can learn more about it on our [Queues overview](https://www.scaleway.com/en/docs/queues/reference-content/queues-overview/) page.

    (switchcolumn)
    <Message type="tip">
    If Queues is not the service you're looking for, check out our [NATS](https://www.scaleway.com/en/developers/api/nats/nats-api/) or [Topics and Events](https://www.scaleway.com/en/developers/api/topics-and-events/sns-api/) services.
    </Message>
    (switchcolumn)

    ## Concepts

    Refer to our [dedicated concepts page](https://www.scaleway.com/en/docs/queues/concepts/) to find definitions of all terminology related to Queues.

    (switchcolumn)
    (switchcolumn)

    ## Quickstart

    1. Configure your environment variables

       <Message type="note">
       This is an optional step that seeks to simplify your usage of the API.
       </Message>

        ```bash
        export SCW_SECRET_KEY="<API secret key>"
        export SCW_PROJECT_ID="<Scaleway Project ID>"
        ```

    2. Activate the Queues protocol on your Scaleway Project:

        ```bash
        curl --silent -X POST \
          -H "X-Auth-Token: $SCW_SECRET_KEY" \
          -H "Content-Type: application/json" \
          "https://api.scaleway.com/mnq/v1beta1/regions/fr-par/activate-sqs" \
            -d '{
              "project_id": "'$SCW_PROJECT_ID'"
            }' | jq

        curl --silent -X GET \
          -H "X-Auth-Token: $SCW_SECRET_KEY" \
          -H "Content-Type: application/json" \
          "https://api.scaleway.com/mnq/v1beta1/regions/fr-par/sqs-info?project_id=$SCW_PROJECT_ID" \
            | tee my-sqs-account.json | jq
        ```

        <Message type="tip">
        - `| tee my-sqs-account.json` saves the JSON object returned by the API to a file (used by next steps)
        - `| jq` displays the output nicely
        </Message>

    3. **Create credentials**. Credentials are necessary to authenticate a client to your Queues service. Their permissions should be specified and adapted according to your needs, using `true` or `false` for each type of permission.

        ```bash
        curl --silent -X POST \
          -H "X-Auth-Token: $SCW_SECRET_KEY" \
          -H "Content-Type: application/json" \
          "https://api.scaleway.com/mnq/v1beta1/regions/fr-par/sqs-credentials" \
            -d '{
              "name": "my-credentials",
              "permissions": {
                "can_publish": true,
                "can_receive": true,
                "can_manage": true
              },
              "project_id": "'$SCW_PROJECT_ID'"
            }' | tee my-sqs-credentials.json | jq
        ```

    4. **Export credentials**: Export the credentials to your environment:

        ```bash
        export AWS_ENDPOINT_URL=$(jq -r .sqs_endpoint_url my-sqs-account.json)
        export AWS_ACCESS_KEY_ID=$(jq -r .access_key my-sqs-credentials.json)
        export AWS_SECRET_ACCESS_KEY=$(jq -r .secret_key my-sqs-credentials.json)
        ```

    5. **Start creating queues and messages**. The following commands show you how to create a queue, and send, receive and delete a message

        ```bash
        aws sqs create-queue --queue-name my-queue | tee my-queue.json
        ```

        ```bash
        aws sqs send-message --queue-url "$(jq -r .QueueUrl my-queue.json)" \
          --message-body 'Hello world!'
        ```

        ```bash
        aws sqs receive-message --queue-url "$(jq -r .QueueUrl my-queue.json)" \
          > my-sqs-message.json
        ```

        ```bash
        aws sqs delete-message --queue-url "$(jq -r .QueueUrl my-queue.json)" \
          --receipt-handle "$(jq -r '.Messages[0].ReceiptHandle' my-sqs-message.json)"
        ```

    6. Disable Queues

        <Message type="important">
        Disabling Queues deletes all queues and messages stored in your Queues service.
        </Message>

        ```bash
        curl --silent -X POST \
          -H "X-Auth-Token: $SCW_SECRET_KEY" \
          -H "Content-Type: application/json" \
            "https://api.scaleway.com/mnq/v1beta1/regions/fr-par/deactivate-sqs" \
            -d '{
              "project_id": "'$SCW_PROJECT_ID'"
            }' | jq
        ```

    (switchcolumn)
    <Message type="requirement">
    - You have a [Scaleway account](https://console.scaleway.com/)
    - You have created an [API key](https://www.scaleway.com/en/docs/iam/how-to/create-api-keys/) and that the API key has sufficient [IAM permissions](https://www.scaleway.com/en/docs/iam/reference-content/permission-sets/) to perform the actions described on this page
    - You have [installed `curl`](https://curl.se/download.html)
    - You have installed [awscli v1](https://pypi.org/project/awscli/) (version >= 1.29.0) or [awscli v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) (version >= 2.13.0)
    - You have installed [jq](https://stedolan.github.io/jq/download/)
    </Message>
    (switchcolumn)

    ## Technical limitations

    Scaleway Queues does not support the entire set of AWS SQS actions or parameters.
    See the [compatibility matrix](https://www.scaleway.com/en/docs/queues/reference-content/queues-support/) for more information.

    Also note that:

    - The maximum message size is 256 kB.
    - The maximum storage capacity for all queues of a project is 100 MB.

    ## Technical information

    ### Regional availability

    Scaleway Queues is currently available in the following regions:

    - Paris, France (`fr-par`)
    - Amsterdam, Netherlands (`nl-ams`)

    ### Queues credentials

    Credentials use a simplified permissions system with 3 permissions:

    - `can_publish` : allows to send messages to a Queue.
    - `can_receive` : allows to receive and acknowledge (delete) messages.
    - `can_manage`  : allows all other actions (Creating, Listing, Updating, Deleting Queues).

    Each set of credentials gives access to all queues.
    Isolation can be handled by using several [Scaleway Projects](https://www.scaleway.com/en/developers/api/account/project-api/).

    ## Going further

    For more help using Scaleway Queues, check out the following resources:

    - Our [main documentation](https://www.scaleway.com/en/docs/queues/)
    - The `#messaging-queuing` channel on our [Slack community](https://www.scaleway.com/en/docs/tutorials/scaleway-slack-community/)
    - Our [support ticketing system](https://www.scaleway.com/en/docs/account/how-to/open-a-support-ticket/)

    You can also read the [AWS SQS documentation](https://docs.aws.amazon.com/sqs).
  version: v1beta1
servers:
- url: https://api.scaleway.com
tags:
- name: Queues
  description: |
    Queues provides a queuing service. It must be activated per Project before being used
- name: Queues credentials
  description: |
    Queues credentials give access to the Queues service
components:
  schemas:
    scaleway.mnq.v1beta1.ListSqsCredentialsResponse:
      type: object
      properties:
        total_count:
          type: integer
          description: Total count of existing credentials (matching any filters specified).
          format: uint64
        sqs_credentials:
          type: array
          description: Queues credentials on this page.
          items:
            $ref: '#/components/schemas/scaleway.mnq.v1beta1.SqsCredentials'
      x-properties-order:
      - total_count
      - sqs_credentials
    scaleway.mnq.v1beta1.SqsCredentials:
      type: object
      properties:
        id:
          type: string
          description: ID of the credentials.
        name:
          type: string
          description: Name of the credentials.
        project_id:
          type: string
          description: Project ID of the Project containing the credentials.
        region:
          type: string
          description: Region where the credentials exists.
        created_at:
          type: string
          description: Credentials creation date. (RFC 3339 format)
          format: date-time
          example: "2022-03-22T12:34:56.123456Z"
          nullable: true
        updated_at:
          type: string
          description: Credentials last modification date. (RFC 3339 format)
          format: date-time
          example: "2022-03-22T12:34:56.123456Z"
          nullable: true
        access_key:
          type: string
          description: Access key ID.
        secret_key:
          type: string
          description: Secret key ID (Only returned by **Create Queues Credentials**
            call).
        secret_checksum:
          type: string
          description: Checksum of the Secret key.
        permissions:
          type: object
          description: Permissions associated with these credentials.
          properties:
            can_publish:
              type: boolean
              description: Defines whether the credentials bearer can publish messages
                to the service (send messages to Queues queues).
              nullable: true
            can_receive:
              type: boolean
              description: Defines whether the credentials bearer can receive messages
                from Queues queues.
              nullable: true
            can_manage:
              type: boolean
              description: Defines whether the credentials bearer can manage the associated
                Queues queues.
              nullable: true
          x-properties-order:
          - can_publish
          - can_receive
          - can_manage
      x-properties-order:
      - id
      - name
      - project_id
      - region
      - created_at
      - updated_at
      - access_key
      - secret_key
      - secret_checksum
      - permissions
    scaleway.mnq.v1beta1.SqsInfo:
      type: object
      properties:
        project_id:
          type: string
          description: Project ID of the Project containing the service.
        region:
          type: string
          description: Region of the service.
        created_at:
          type: string
          description: Queues creation date. (RFC 3339 format)
          format: date-time
          example: "2022-03-22T12:34:56.123456Z"
          nullable: true
        updated_at:
          type: string
          description: Queues last modification date. (RFC 3339 format)
          format: date-time
          example: "2022-03-22T12:34:56.123456Z"
          nullable: true
        status:
          type: string
          description: Queues activation status.
          enum:
          - unknown_status
          - enabled
          - disabled
          x-enum-descriptions:
            values:
              unknown_status: Unknown status
              enabled: Enabled status
              disabled: Disabled status
          default: unknown_status
        sqs_endpoint_url:
          type: string
          description: Endpoint of the Queues service for this region and project.
      x-properties-order:
      - project_id
      - region
      - created_at
      - updated_at
      - status
      - sqs_endpoint_url
  securitySchemes:
    scaleway:
      in: header
      name: X-Auth-Token
      type: apiKey
paths:
  /mnq/v1beta1/regions/{region}/activate-sqs:
    post:
      tags:
      - Queues
      operationId: ActivateSqs
      summary: Activate Queues
      description: Activate Queues for the specified Project ID. Queues must be activated
        before any usage such as creating credentials and queues. Activating Queues
        does not trigger any billing, and you can deactivate at any time.
      parameters:
      - in: path
        name: region
        description: The region you want to target
        required: true
        schema:
          type: string
          enum:
          - fr-par
          - nl-ams
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.mnq.v1beta1.SqsInfo'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                project_id:
                  type: string
                  description: Project on which to activate the Queues service.
              x-properties-order:
              - project_id
      security:
      - scaleway: []
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -X POST \
            -H "X-Auth-Token: $SCW_SECRET_KEY" \
            -H "Content-Type: application/json" \
            -d '{"project_id":"string"}' \
            "https://api.scaleway.com/mnq/v1beta1/regions/{region}/activate-sqs"
      - lang: HTTPie
        source: |-
          http POST "https://api.scaleway.com/mnq/v1beta1/regions/{region}/activate-sqs" \
            X-Auth-Token:$SCW_SECRET_KEY \
            project_id="string"
  /mnq/v1beta1/regions/{region}/deactivate-sqs:
    post:
      tags:
      - Queues
      operationId: DeactivateSqs
      summary: Deactivate Queues
      description: Deactivate Queues for the specified Project ID. You must delete
        all queues and credentials before this call or you need to set the force_delete
        parameter.
      parameters:
      - in: path
        name: region
        description: The region you want to target
        required: true
        schema:
          type: string
          enum:
          - fr-par
          - nl-ams
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.mnq.v1beta1.SqsInfo'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                project_id:
                  type: string
                  description: Project on which to deactivate the Queues service.
              x-properties-order:
              - project_id
      security:
      - scaleway: []
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -X POST \
            -H "X-Auth-Token: $SCW_SECRET_KEY" \
            -H "Content-Type: application/json" \
            -d '{"project_id":"string"}' \
            "https://api.scaleway.com/mnq/v1beta1/regions/{region}/deactivate-sqs"
      - lang: HTTPie
        source: |-
          http POST "https://api.scaleway.com/mnq/v1beta1/regions/{region}/deactivate-sqs" \
            X-Auth-Token:$SCW_SECRET_KEY \
            project_id="string"
  /mnq/v1beta1/regions/{region}/sqs-credentials:
    get:
      tags:
      - Queues credentials
      operationId: ListSqsCredentials
      summary: List Queues credentials
      description: List existing Queues credentials in the specified region. The response
        contains only the metadata for the credentials, not the credentials themselves.
      parameters:
      - in: path
        name: region
        description: The region you want to target
        required: true
        schema:
          type: string
          enum:
          - fr-par
          - nl-ams
      - in: query
        name: project_id
        description: Include only Queues credentials in this Project.
        schema:
          type: string
      - in: query
        name: page
        description: Page number to return.
        schema:
          type: integer
          format: int32
      - in: query
        name: page_size
        description: Maximum number of credentials to return per page.
        schema:
          type: integer
          format: uint32
      - in: query
        name: order_by
        description: Order in which to return results.
        schema:
          type: string
          enum:
          - created_at_asc
          - created_at_desc
          - updated_at_asc
          - updated_at_desc
          - name_asc
          - name_desc
          x-enum-descriptions:
            values:
              created_at_asc: Order by creation date (ascending chronological order)
              created_at_desc: Order by creation date (descending chronological order)
              updated_at_asc: Order by last update date (ascending chronological order)
              updated_at_desc: Order by last update date (descending chronological
                order)
              name_asc: Order by name (ascending alphabetical order)
              name_desc: Order by name (descending alphabetical order)
          default: created_at_asc
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.mnq.v1beta1.ListSqsCredentialsResponse'
      security:
      - scaleway: []
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -X GET \
            -H "X-Auth-Token: $SCW_SECRET_KEY" \
            "https://api.scaleway.com/mnq/v1beta1/regions/{region}/sqs-credentials"
      - lang: HTTPie
        source: |-
          http GET "https://api.scaleway.com/mnq/v1beta1/regions/{region}/sqs-credentials" \
            X-Auth-Token:$SCW_SECRET_KEY
    post:
      tags:
      - Queues credentials
      operationId: CreateSqsCredentials
      summary: Create Queues credentials
      description: Create a set of credentials for Queues, specified by a Project
        ID. Credentials give the bearer access to queues, and the level of permissions
        can be defined granularly.
      parameters:
      - in: path
        name: region
        description: The region you want to target
        required: true
        schema:
          type: string
          enum:
          - fr-par
          - nl-ams
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.mnq.v1beta1.SqsCredentials'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                project_id:
                  type: string
                  description: Project containing the Queues credentials.
                name:
                  type: string
                  description: Name of the credentials.
                permissions:
                  type: object
                  description: Permissions associated with these credentials.
                  properties:
                    can_publish:
                      type: boolean
                      description: Defines whether the credentials bearer can publish
                        messages to the service (send messages to Queues queues).
                      nullable: true
                    can_receive:
                      type: boolean
                      description: Defines whether the credentials bearer can receive
                        messages from Queues queues.
                      nullable: true
                    can_manage:
                      type: boolean
                      description: Defines whether the credentials bearer can manage
                        the associated Queues queues.
                      nullable: true
                  x-properties-order:
                  - can_publish
                  - can_receive
                  - can_manage
              required:
              - project_id
              x-properties-order:
              - project_id
              - name
              - permissions
      security:
      - scaleway: []
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -X POST \
            -H "X-Auth-Token: $SCW_SECRET_KEY" \
            -H "Content-Type: application/json" \
            -d '{"name":"string","project_id":"string"}' \
            "https://api.scaleway.com/mnq/v1beta1/regions/{region}/sqs-credentials"
      - lang: HTTPie
        source: |-
          http POST "https://api.scaleway.com/mnq/v1beta1/regions/{region}/sqs-credentials" \
            X-Auth-Token:$SCW_SECRET_KEY \
            name="string" \
            project_id="string"
  /mnq/v1beta1/regions/{region}/sqs-credentials/{sqs_credentials_id}:
    get:
      tags:
      - Queues credentials
      operationId: GetSqsCredentials
      summary: Get Queues credentials
      description: Retrieve an existing set of credentials, identified by the `credentials_id`.
        The credentials themselves, as well as their metadata (name, project ID etc),
        are returned in the response.
      parameters:
      - in: path
        name: region
        description: The region you want to target
        required: true
        schema:
          type: string
          enum:
          - fr-par
          - nl-ams
      - in: path
        name: sqs_credentials_id
        description: ID of the Queues credentials to get.
        required: true
        schema:
          type: string
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.mnq.v1beta1.SqsCredentials'
      security:
      - scaleway: []
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -X GET \
            -H "X-Auth-Token: $SCW_SECRET_KEY" \
            "https://api.scaleway.com/mnq/v1beta1/regions/{region}/sqs-credentials/{sqs_credentials_id}"
      - lang: HTTPie
        source: |-
          http GET "https://api.scaleway.com/mnq/v1beta1/regions/{region}/sqs-credentials/{sqs_credentials_id}" \
            X-Auth-Token:$SCW_SECRET_KEY
    patch:
      tags:
      - Queues credentials
      operationId: UpdateSqsCredentials
      summary: Update Queues credentials
      description: Update a set of Queues credentials. You can update the credentials'
        name, or their permissions.
      parameters:
      - in: path
        name: region
        description: The region you want to target
        required: true
        schema:
          type: string
          enum:
          - fr-par
          - nl-ams
      - in: path
        name: sqs_credentials_id
        description: ID of the Queues credentials to update.
        required: true
        schema:
          type: string
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.mnq.v1beta1.SqsCredentials'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Name of the credentials.
                  nullable: true
                permissions:
                  type: object
                  description: Permissions associated with these credentials.
                  properties:
                    can_publish:
                      type: boolean
                      description: Defines whether the credentials bearer can publish
                        messages to the service (send messages to Queues queues).
                      nullable: true
                    can_receive:
                      type: boolean
                      description: Defines whether the credentials bearer can receive
                        messages from Queues queues.
                      nullable: true
                    can_manage:
                      type: boolean
                      description: Defines whether the credentials bearer can manage
                        the associated Queues queues.
                      nullable: true
                  x-properties-order:
                  - can_publish
                  - can_receive
                  - can_manage
              x-properties-order:
              - name
              - permissions
      security:
      - scaleway: []
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -X PATCH \
            -H "X-Auth-Token: $SCW_SECRET_KEY" \
            -H "Content-Type: application/json" \
            -d '{}' \
            "https://api.scaleway.com/mnq/v1beta1/regions/{region}/sqs-credentials/{sqs_credentials_id}"
      - lang: HTTPie
        source: |-
          http PATCH "https://api.scaleway.com/mnq/v1beta1/regions/{region}/sqs-credentials/{sqs_credentials_id}" \
            X-Auth-Token:$SCW_SECRET_KEY
    delete:
      tags:
      - Queues credentials
      operationId: DeleteSqsCredentials
      summary: Delete Queues credentials
      description: Delete a set of Queues credentials, specified by their credentials
        ID. Deleting credentials is irreversible and cannot be undone. The credentials
        can then no longer be used to access Queues.
      parameters:
      - in: path
        name: region
        description: The region you want to target
        required: true
        schema:
          type: string
          enum:
          - fr-par
          - nl-ams
      - in: path
        name: sqs_credentials_id
        description: ID of the credentials to delete.
        required: true
        schema:
          type: string
      responses:
        "204":
          description: ""
      security:
      - scaleway: []
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -X DELETE \
            -H "X-Auth-Token: $SCW_SECRET_KEY" \
            "https://api.scaleway.com/mnq/v1beta1/regions/{region}/sqs-credentials/{sqs_credentials_id}"
      - lang: HTTPie
        source: |-
          http DELETE "https://api.scaleway.com/mnq/v1beta1/regions/{region}/sqs-credentials/{sqs_credentials_id}" \
            X-Auth-Token:$SCW_SECRET_KEY
  /mnq/v1beta1/regions/{region}/sqs-info:
    get:
      tags:
      - Queues
      operationId: GetSqsInfo
      summary: Get Queues info
      description: Retrieve the Queues information of the specified Project ID. information
        include the activation status and the Queues API endpoint URL.
      parameters:
      - in: path
        name: region
        description: The region you want to target
        required: true
        schema:
          type: string
          enum:
          - fr-par
          - nl-ams
      - in: query
        name: project_id
        description: Project to retrieve Queues info from.
        required: true
        schema:
          type: string
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.mnq.v1beta1.SqsInfo'
      security:
      - scaleway: []
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -X GET \
            -H "X-Auth-Token: $SCW_SECRET_KEY" \
            "https://api.scaleway.com/mnq/v1beta1/regions/{region}/sqs-info?project_id=string"
      - lang: HTTPie
        source: |-
          http GET "https://api.scaleway.com/mnq/v1beta1/regions/{region}/sqs-info" \
            X-Auth-Token:$SCW_SECRET_KEY \
            project_id==string