openapi: 3.1.0
info:
  title: NATS API
  description: |-
    The Neural Autonomic Transport System, or **NATS**, is an open-source messaging system written in Go. It is part of the Cloud Native Computing Foundation (CNCF) and has more than 40 client language implementations. The application has been designed with performance, scalability, and ease of use in mind.
    If you're new to NATS, you can learn more about it on our [NATS overview](https://www.scaleway.com/en/docs/nats/reference-content/nats-overview/) page.

    (switchcolumn)
    <Message type="tip">
    If NATS is not the service you're looking for, check out our [Queues](https://www.scaleway.com/en/developers/api/queues/sqs-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/nats/concepts/) to find definitions of all terminology related to NATS.

    (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. **Create a NATS account.** A NATS account provides a scope for your NATS streams, messages and credentials.

        ```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/nats-accounts" \
            -d '{
              "name": "my-nats-account",
              "project_id": "'$SCW_PROJECT_ID'"
            }' | tee my-nats-account.json | jq
        ```

        <Message type="tip">
        - `| tee my-nats-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 the NATS service. The `nats_account_id` field is automatically set to the value of `id` returned by the previous command:

        ```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/nats-credentials" \
            -d '{
              "name": "my-credentials",
              "nats_account_id": "'$(jq -r .id my-nats-account.json)'"
            }' | tee my-nats-credentials.json | jq
        ```

    4. **Extract the credentials** you created in the previous step:

        ```bash
        jq -r .credentials.content my-nats-credentials.json > nats.creds
        ```

    5. **Publish your first message with the NATS CLI**. Open two terminals for this purpose.

        - On terminal 1: subscribe to a subject

             ```bash
            nats sub -s $(jq -r .endpoint my-nats-account.json) --creds nats.creds my-subject
            ```

        - On terminal 2: publish a message to this subject:

            ```bash
            nats pub -s $(jq -r .endpoint my-nats-account.json) --creds nats.creds my-subject 'Hi there!'
            ```

        The "Hi there!" message should appear on the terminal 1.
        You can now abort the subscription by typing "CTRL+C" on terminal 1.

    6. **Delete the NATS account**

        ```bash
        curl --silent -X DELETE \
          -H "X-Auth-Token: $SCW_SECRET_KEY" \
          -H "Content-Type: application/json" \
            "https://api.scaleway.com/mnq/v1beta1/regions/fr-par/nats-accounts/$(jq -r .id my-nats-account.json)" | 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 [natscli](https://github.com/nats-io/natscli/#installation) (choose your installation method between `go install`, `.zip` download or `.deb` installation)
    - You have installed [jq](https://stedolan.github.io/jq/download/)

    </Message>
    (switchcolumn)

    ## Technical limitations

    The maximum storage capacity of a NATS account is 300 MB.
    Be aware that replicates are counted into this quota.

    ## Technical information

    ### Regional availability

    Scaleway NATS is currently available in the following regions:

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

    ### NATS credentials

    Credentials give full access to the NATS account.
    Isolation can be handled by using several NATS accounts.

    ### TLS

    Note that the Scaleway NATS server is configured with TLS, and as such will require all clients to connect with TLS. In the case of the NATS SDK however, the SDK abstracts this and handles the TLS connection itself.

    ## Going further

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

    - Our [main documentation](https://www.scaleway.com/en/docs/nats/)
    - 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 official NATS documentation:

    - [What is NATS](https://docs.nats.io/nats-concepts/what-is-nats)
    - [Installing & using the NATS CLI](https://docs.nats.io/using-nats/nats-tools/nats_cli)
    - [JetStream official documentation](https://docs.nats.io/nats-concepts/jetstream) (JetStream is enabled with [quotas](https://www.scaleway.com/en/docs/organizations-and-projects/additional-content/organization-quotas/#nats) on our servers)
    - [Official NATS GitHub](https://github.com/nats-io): official client library for many languages ([golang](https://github.com/nats-io/nats.go), [python](https://github.com/nats-io/nats.py), [rust](https://github.com/nats-io/nats.rs) etc.) and many other coding resources
    - [NATS community Slack channel](https://www.scaleway.com/en/docs/tutorials/scaleway-slack-community/).
  version: v1beta1
servers:
- url: https://api.scaleway.com
tags:
- name: NATS accounts
  description: |
    A NATS account allows you to interact with a NATS cluster
- name: NATS credentials
  description: |
    NATS credentials give services and platforms access to the NATS cluster using any standard NATS client
components:
  schemas:
    scaleway.mnq.v1beta1.ListNatsAccountsResponse:
      type: object
      properties:
        total_count:
          type: integer
          description: Total count of existing NATS accounts (matching any filters
            specified).
          format: uint64
        nats_accounts:
          type: array
          description: NATS accounts on this page.
          items:
            $ref: '#/components/schemas/scaleway.mnq.v1beta1.NatsAccount'
      x-properties-order:
      - total_count
      - nats_accounts
    scaleway.mnq.v1beta1.ListNatsCredentialsResponse:
      type: object
      properties:
        total_count:
          type: integer
          description: Total count of existing credentials (matching any filters specified).
          format: uint64
        nats_credentials:
          type: array
          description: Credentials on this page.
          items:
            $ref: '#/components/schemas/scaleway.mnq.v1beta1.NatsCredentials'
      x-properties-order:
      - total_count
      - nats_credentials
    scaleway.mnq.v1beta1.NatsAccount:
      type: object
      properties:
        id:
          type: string
          description: NATS account ID.
        name:
          type: string
          description: NATS account name.
        endpoint:
          type: string
          description: Endpoint of the NATS service for this account.
        project_id:
          type: string
          description: Project ID of the Project containing the NATS account.
        region:
          type: string
          description: Region where the NATS account is deployed.
        created_at:
          type: string
          description: NATS account creation date. (RFC 3339 format)
          format: date-time
          example: "2022-03-22T12:34:56.123456Z"
          nullable: true
        updated_at:
          type: string
          description: NATS account last modification date. (RFC 3339 format)
          format: date-time
          example: "2022-03-22T12:34:56.123456Z"
          nullable: true
      x-properties-order:
      - id
      - name
      - endpoint
      - project_id
      - region
      - created_at
      - updated_at
    scaleway.mnq.v1beta1.NatsCredentials:
      type: object
      properties:
        id:
          type: string
          description: ID of the credentials.
        name:
          type: string
          description: Name of the credentials.
        nats_account_id:
          type: string
          description: NATS account containing the credentials.
        region:
          type: string
          description: Region where the NATS account is deployed.
        created_at:
          type: string
          description: NATS credentials creation date. (RFC 3339 format)
          format: date-time
          example: "2022-03-22T12:34:56.123456Z"
          nullable: true
        updated_at:
          type: string
          description: NATS credentials last modification date. (RFC 3339 format)
          format: date-time
          example: "2022-03-22T12:34:56.123456Z"
          nullable: true
        credentials:
          type: object
          description: Object containing the credentials file (Only returned by **Create
            Nats Credentials** call).
          properties:
            name:
              type: string
              description: File name.
            content:
              type: string
              description: File content.
          x-properties-order:
          - name
          - content
        checksum:
          type: string
          description: Checksum of the credentials file.
      x-properties-order:
      - id
      - name
      - nats_account_id
      - region
      - created_at
      - updated_at
      - credentials
      - checksum
  securitySchemes:
    scaleway:
      in: header
      name: X-Auth-Token
      type: apiKey
paths:
  /mnq/v1beta1/regions/{region}/nats-accounts:
    get:
      tags:
      - NATS accounts
      operationId: ListNatsAccounts
      summary: List NATS accounts
      description: List all NATS accounts in the specified region, for a Scaleway
        Organization or Project. By default, the NATS accounts returned in the list
        are ordered by creation date in ascending order, though this can be modified
        via the `order_by` field.
      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 NATS accounts 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 NATS accounts 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.ListNatsAccountsResponse'
      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}/nats-accounts"
      - lang: HTTPie
        source: |-
          http GET "https://api.scaleway.com/mnq/v1beta1/regions/{region}/nats-accounts" \
            X-Auth-Token:$SCW_SECRET_KEY
    post:
      tags:
      - NATS accounts
      operationId: CreateNatsAccount
      summary: Create a NATS account
      description: Create a NATS account associated with a Project.
      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.NatsAccount'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: NATS account name.
                project_id:
                  type: string
                  description: Project containing the NATS account.
              x-properties-order:
              - name
              - 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 '{"name":"string","project_id":"string"}' \
            "https://api.scaleway.com/mnq/v1beta1/regions/{region}/nats-accounts"
      - lang: HTTPie
        source: |-
          http POST "https://api.scaleway.com/mnq/v1beta1/regions/{region}/nats-accounts" \
            X-Auth-Token:$SCW_SECRET_KEY \
            name="string" \
            project_id="string"
  /mnq/v1beta1/regions/{region}/nats-accounts/{nats_account_id}:
    get:
      tags:
      - NATS accounts
      operationId: GetNatsAccount
      summary: Get a NATS account
      description: Retrieve information about an existing NATS account identified
        by its NATS account ID. Its full details, including name and endpoint, 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: nats_account_id
        description: ID of the NATS account to get.
        required: true
        schema:
          type: string
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.mnq.v1beta1.NatsAccount'
      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}/nats-accounts/{nats_account_id}"
      - lang: HTTPie
        source: |-
          http GET "https://api.scaleway.com/mnq/v1beta1/regions/{region}/nats-accounts/{nats_account_id}" \
            X-Auth-Token:$SCW_SECRET_KEY
    patch:
      tags:
      - NATS accounts
      operationId: UpdateNatsAccount
      summary: Update the name of a NATS account
      description: Update the name of a NATS account, specified by its NATS account
        ID.
      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: nats_account_id
        description: ID of the NATS account to update.
        required: true
        schema:
          type: string
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.mnq.v1beta1.NatsAccount'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: NATS account name.
                  nullable: true
              x-properties-order:
              - name
      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}/nats-accounts/{nats_account_id}"
      - lang: HTTPie
        source: |-
          http PATCH "https://api.scaleway.com/mnq/v1beta1/regions/{region}/nats-accounts/{nats_account_id}" \
            X-Auth-Token:$SCW_SECRET_KEY
    delete:
      tags:
      - NATS accounts
      operationId: DeleteNatsAccount
      summary: Delete a NATS account
      description: Delete a NATS account, specified by its NATS account ID. Note that
        deleting a NATS account is irreversible, and any credentials, streams, consumer
        and stored messages belonging to this NATS account will also be deleted.
      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: nats_account_id
        description: ID of the NATS account 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}/nats-accounts/{nats_account_id}"
      - lang: HTTPie
        source: |-
          http DELETE "https://api.scaleway.com/mnq/v1beta1/regions/{region}/nats-accounts/{nats_account_id}" \
            X-Auth-Token:$SCW_SECRET_KEY
  /mnq/v1beta1/regions/{region}/nats-credentials:
    get:
      tags:
      - NATS credentials
      operationId: ListNatsCredentials
      summary: List NATS credentials
      description: List existing credentials in the specified NATS account. The response
        contains only the metadata for the credentials, not the credentials themselves,
        which are only returned after a **Create Credentials** call.
      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 NATS accounts in this Project.
        schema:
          type: string
      - in: query
        name: nats_account_id
        description: Include only credentials for this NATS account.
        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.ListNatsCredentialsResponse'
      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}/nats-credentials"
      - lang: HTTPie
        source: |-
          http GET "https://api.scaleway.com/mnq/v1beta1/regions/{region}/nats-credentials" \
            X-Auth-Token:$SCW_SECRET_KEY
    post:
      tags:
      - NATS credentials
      operationId: CreateNatsCredentials
      summary: Create NATS credentials
      description: Create a set of credentials for a NATS account, specified by its
        NATS account ID.
      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.NatsCredentials'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                nats_account_id:
                  type: string
                  description: NATS account containing the credentials.
                name:
                  type: string
                  description: Name of the credentials.
              required:
              - nats_account_id
              x-properties-order:
              - nats_account_id
              - name
      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","nats_account_id":"string"}' \
            "https://api.scaleway.com/mnq/v1beta1/regions/{region}/nats-credentials"
      - lang: HTTPie
        source: |-
          http POST "https://api.scaleway.com/mnq/v1beta1/regions/{region}/nats-credentials" \
            X-Auth-Token:$SCW_SECRET_KEY \
            name="string" \
            nats_account_id="string"
  /mnq/v1beta1/regions/{region}/nats-credentials/{nats_credentials_id}:
    get:
      tags:
      - NATS credentials
      operationId: GetNatsCredentials
      summary: Get NATS credentials
      description: Retrieve an existing set of credentials, identified by the `nats_credentials_id`.
        The credentials themselves are NOT returned, only their metadata (NATS account
        ID, credentials name, 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: nats_credentials_id
        description: ID of the credentials to get.
        required: true
        schema:
          type: string
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.mnq.v1beta1.NatsCredentials'
      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}/nats-credentials/{nats_credentials_id}"
      - lang: HTTPie
        source: |-
          http GET "https://api.scaleway.com/mnq/v1beta1/regions/{region}/nats-credentials/{nats_credentials_id}" \
            X-Auth-Token:$SCW_SECRET_KEY
    delete:
      tags:
      - NATS credentials
      operationId: DeleteNatsCredentials
      summary: Delete NATS credentials
      description: Delete a set of credentials, specified by their credentials ID.
        Deleting credentials is irreversible and cannot be undone. The credentials
        can no longer be used to access the NATS account, and active connections using
        this credentials will be closed.
      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: nats_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}/nats-credentials/{nats_credentials_id}"
      - lang: HTTPie
        source: |-
          http DELETE "https://api.scaleway.com/mnq/v1beta1/regions/{region}/nats-credentials/{nats_credentials_id}" \
            X-Auth-Token:$SCW_SECRET_KEY