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

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

    ## Concepts

    Refer to our [dedicated concepts page](https://www.scaleway.com/en/docs/topics-and-events/concepts/) to find definitions of all terminology related to Topics and Events.

    (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 Topics and Events 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-sns" \
            -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/sns-info?project_id=$SCW_PROJECT_ID" \
            | tee my-sns-account.json | jq
        ```

        <Message type="tip">
        - `| tee my-sns-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 Topics and Events 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/sns-credentials" \
            -d '{
              "name": "my-credentials",
              "permissions": {
                "can_publish": true,
                "can_receive": true,
                "can_manage": true
              },
              "project_id": "'$SCW_PROJECT_ID'"
            }' | tee my-sns-credentials.json | jq
        ```

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

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

    5. **Start creating topics and publishing messages**. The following commands show you how to create a topic, subscribe to a [Scaleway Serverless function](https://www.scaleway.com/en/developers/api/serverless-functions/), and send, receive and delete a message.

        ```bash
        aws sns create-topic --name my-topic | tee my-topic.json
        ```

        ```bash
        aws sns subscribe --topic-arn "$(jq -r .TopicArn my-topic.json)" \
          --protocol lambda --notification-endpoint <YOUR-FUNCTION-ENDPOINT>
        ```

        ```bash
        aws sns publish --topic-arn "$(jq -r .TopicArn my-topic.json)" \
          --message 'Hello world!'
        ```

    6. Disable Topics and Events

        <Message type="important">
        Disabling Topics and Events deletes all topics and messages stored in your Topics and Events 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-sns" \
            -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 Topics and Events does not support the entire set of AWS SNS actions or parameters.
    See the [compatibility matrix](https://www.scaleway.com/en/docs/topics-and-events/reference-content/topics-and-events-support/) for more information.

    Also note that:

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

    ## Technical information

    ### Regional availability

    Scaleway Topics and Events is currently available in the following regions:

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

    ### Topics and Events credentials

    Credentials use a simplified permissions system with 3 permissions:

    - `can_publish` : allows to publish messages to a Topic.
    - `can_receive` : allows to subscribe to a topic.
    - `can_manage`  : allows all other actions (Creating, Listing, Updating, Deleting Topics).

    Each set of credentials gives access to all topics.
    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 Topics and Events, check out the following resources:

    - Our [main documentation](https://www.scaleway.com/en/docs/topics-and-events/)
    - 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 SNS documentation](https://docs.aws.amazon.com/sns).
  version: v1beta1
servers:
- url: https://api.scaleway.com
tags:
- name: Topics and Events
  description: |
    Topics and Events provides a notification service. It must be activated per Project before being used
- name: Topics and Events credentials
  description: |
    Topics and Events credentials give access to the Topics and Events service
components:
  schemas:
    scaleway.mnq.v1beta1.ListSnsCredentialsResponse:
      type: object
      properties:
        total_count:
          type: integer
          description: Total count of existing credentials (matching any filters specified).
          format: uint64
        sns_credentials:
          type: array
          description: Topics and Events credentials on this page.
          items:
            $ref: '#/components/schemas/scaleway.mnq.v1beta1.SnsCredentials'
      x-properties-order:
      - total_count
      - sns_credentials
    scaleway.mnq.v1beta1.SnsCredentials:
      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 Topics and Events
            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 (publish to Topics and Events topics).
              nullable: true
            can_receive:
              type: boolean
              description: Defines whether the credentials bearer can receive messages
                from the service (configure subscriptions).
              nullable: true
            can_manage:
              type: boolean
              description: Defines whether the credentials bearer can manage the associated
                Topics and Events topics or subscriptions.
              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.SnsInfo:
      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: Topics and Events creation date. (RFC 3339 format)
          format: date-time
          example: "2022-03-22T12:34:56.123456Z"
          nullable: true
        updated_at:
          type: string
          description: Topics and Events last modification date. (RFC 3339 format)
          format: date-time
          example: "2022-03-22T12:34:56.123456Z"
          nullable: true
        status:
          type: string
          description: Topics and Events activation status.
          enum:
          - unknown_status
          - enabled
          - disabled
          x-enum-descriptions:
            values:
              unknown_status: Unknown status
              enabled: Enabled status
              disabled: Disabled status
          default: unknown_status
        sns_endpoint_url:
          type: string
          description: Endpoint of the Topics and Events service for this region and
            project.
      x-properties-order:
      - project_id
      - region
      - created_at
      - updated_at
      - status
      - sns_endpoint_url
  securitySchemes:
    scaleway:
      in: header
      name: X-Auth-Token
      type: apiKey
paths:
  /mnq/v1beta1/regions/{region}/activate-sns:
    post:
      tags:
      - Topics and Events
      operationId: ActivateSns
      summary: Activate Topics and Events
      description: Activate Topics and Events for the specified Project ID. Topics
        and Events must be activated before any usage. Activating Topics and Events
        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.SnsInfo'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                project_id:
                  type: string
                  description: Project on which to activate the Topics and Events
                    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-sns"
      - lang: HTTPie
        source: |-
          http POST "https://api.scaleway.com/mnq/v1beta1/regions/{region}/activate-sns" \
            X-Auth-Token:$SCW_SECRET_KEY \
            project_id="string"
  /mnq/v1beta1/regions/{region}/deactivate-sns:
    post:
      tags:
      - Topics and Events
      operationId: DeactivateSns
      summary: Deactivate Topics and Events
      description: Deactivate Topics and Events for the specified Project ID. You
        must delete all topics 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.SnsInfo'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                project_id:
                  type: string
                  description: Project on which to deactivate the Topics and Events
                    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-sns"
      - lang: HTTPie
        source: |-
          http POST "https://api.scaleway.com/mnq/v1beta1/regions/{region}/deactivate-sns" \
            X-Auth-Token:$SCW_SECRET_KEY \
            project_id="string"
  /mnq/v1beta1/regions/{region}/sns-credentials:
    get:
      tags:
      - Topics and Events credentials
      operationId: ListSnsCredentials
      summary: List Topics and Events credentials
      description: List existing Topics and Events 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 Topics and Events 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.ListSnsCredentialsResponse'
      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}/sns-credentials"
      - lang: HTTPie
        source: |-
          http GET "https://api.scaleway.com/mnq/v1beta1/regions/{region}/sns-credentials" \
            X-Auth-Token:$SCW_SECRET_KEY
    post:
      tags:
      - Topics and Events credentials
      operationId: CreateSnsCredentials
      summary: Create Topics and Events credentials
      description: Create a set of credentials for Topics and Events, specified by
        a Project ID. Credentials give the bearer access to topics, 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.SnsCredentials'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                project_id:
                  type: string
                  description: Project containing the Topics and Events 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 (publish to Topics and Events topics).
                      nullable: true
                    can_receive:
                      type: boolean
                      description: Defines whether the credentials bearer can receive
                        messages from the service (configure subscriptions).
                      nullable: true
                    can_manage:
                      type: boolean
                      description: Defines whether the credentials bearer can manage
                        the associated Topics and Events topics or subscriptions.
                      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}/sns-credentials"
      - lang: HTTPie
        source: |-
          http POST "https://api.scaleway.com/mnq/v1beta1/regions/{region}/sns-credentials" \
            X-Auth-Token:$SCW_SECRET_KEY \
            name="string" \
            project_id="string"
  /mnq/v1beta1/regions/{region}/sns-credentials/{sns_credentials_id}:
    get:
      tags:
      - Topics and Events credentials
      operationId: GetSnsCredentials
      summary: Get Topics and Events 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: sns_credentials_id
        description: ID of the Topics and Events credentials to get.
        required: true
        schema:
          type: string
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.mnq.v1beta1.SnsCredentials'
      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}/sns-credentials/{sns_credentials_id}"
      - lang: HTTPie
        source: |-
          http GET "https://api.scaleway.com/mnq/v1beta1/regions/{region}/sns-credentials/{sns_credentials_id}" \
            X-Auth-Token:$SCW_SECRET_KEY
    patch:
      tags:
      - Topics and Events credentials
      operationId: UpdateSnsCredentials
      summary: Update Topics and Events credentials
      description: Update a set of Topics and Events 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: sns_credentials_id
        description: ID of the Topics and Events credentials to update.
        required: true
        schema:
          type: string
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.mnq.v1beta1.SnsCredentials'
      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 (publish to Topics and Events topics).
                      nullable: true
                    can_receive:
                      type: boolean
                      description: Defines whether the credentials bearer can receive
                        messages from the service (configure subscriptions).
                      nullable: true
                    can_manage:
                      type: boolean
                      description: Defines whether the credentials bearer can manage
                        the associated Topics and Events topics or subscriptions.
                      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}/sns-credentials/{sns_credentials_id}"
      - lang: HTTPie
        source: |-
          http PATCH "https://api.scaleway.com/mnq/v1beta1/regions/{region}/sns-credentials/{sns_credentials_id}" \
            X-Auth-Token:$SCW_SECRET_KEY
    delete:
      tags:
      - Topics and Events credentials
      operationId: DeleteSnsCredentials
      summary: Delete Topics and Events credentials
      description: Delete a set of Topics and Events credentials, specified by their
        credentials ID. Deleting credentials is irreversible and cannot be undone.
        The credentials can then no longer be used to access Topics and Events.
      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: sns_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}/sns-credentials/{sns_credentials_id}"
      - lang: HTTPie
        source: |-
          http DELETE "https://api.scaleway.com/mnq/v1beta1/regions/{region}/sns-credentials/{sns_credentials_id}" \
            X-Auth-Token:$SCW_SECRET_KEY
  /mnq/v1beta1/regions/{region}/sns-info:
    get:
      tags:
      - Topics and Events
      operationId: GetSnsInfo
      summary: Get Topics and Events info
      description: Retrieve the Topics and Events information of the specified Project
        ID. information include the activation status and the Topics and Events 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 Topics and Events info from.
        required: true
        schema:
          type: string
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.mnq.v1beta1.SnsInfo'
      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}/sns-info?project_id=string"
      - lang: HTTPie
        source: |-
          http GET "https://api.scaleway.com/mnq/v1beta1/regions/{region}/sns-info" \
            X-Auth-Token:$SCW_SECRET_KEY \
            project_id==string