openapi: 3.0.1
info:
  title: Control API v1 apps namespaces API
  version: 1.0.32
  description: 'Use the Control API to manage your applications, namespaces, keys, queues, rules, and more.


    Detailed information on using this API can be found in the Ably <a href="https://ably.com/docs/account/control-api">Control API docs</a>.


    Control API is currently in Preview.

    '
servers:
- url: https://control.ably.net/v1
tags:
- name: namespaces
paths:
  /apps/{app_id}/namespaces:
    get:
      summary: Lists namespaces
      description: List the <a href="https://ably.com/docs/channels#namespaces">namespaces</a> for the specified application ID.
      tags:
      - namespaces
      parameters:
      - name: app_id
        description: The application ID.
        in: path
        required: true
        schema:
          type: string
      security:
      - bearer_auth: []
      responses:
        '200':
          description: Namespace list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/namespace_response'
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: App not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '504':
          description: Gateway timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
    post:
      summary: Creates a namespace
      description: Creates a <a href="https://ably.com/docs/channels#namespaces">namespace</a> for the specified application ID.
      tags:
      - namespaces
      parameters:
      - name: app_id
        description: The application ID.
        in: path
        required: true
        schema:
          type: string
      security:
      - bearer_auth: []
      responses:
        '201':
          description: Namespace created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/namespace_response'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: App not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '422':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/namespace_post'
  /apps/{app_id}/namespaces/{namespace_id}:
    patch:
      summary: Updates a namespace
      description: Updates the <a href="https://ably.com/docs/channels#namespaces">namespace</a> with the specified ID, for the application with the specified application ID.
      tags:
      - namespaces
      parameters:
      - name: app_id
        description: The application ID.
        in: path
        required: true
        schema:
          type: string
      - name: namespace_id
        description: The namespace ID.
        in: path
        required: true
        schema:
          type: string
      security:
      - bearer_auth: []
      responses:
        '200':
          description: Namespace updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/namespace_response'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '504':
          description: Gateway timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/namespace_patch'
    delete:
      summary: Deletes a namespace
      description: Deletes the <a href="https://ably.com/docs/channels#namespaces">namespace</a> with the specified ID, for the specified application ID.
      tags:
      - namespaces
      parameters:
      - name: app_id
        description: The application ID.
        in: path
        required: true
        schema:
          type: string
      - name: namespace_id
        description: The namespace ID.
        in: path
        required: true
        schema:
          type: string
      security:
      - bearer_auth: []
      responses:
        '204':
          description: Namespace deleted
          content: {}
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '504':
          description: Gateway timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
components:
  schemas:
    namespace_response:
      type: object
      additionalProperties: false
      properties:
        authenticated:
          type: boolean
          default: false
          description: If `true`, clients will not be permitted to use (including to attach, publish, or subscribe) any channels within this namespace unless they are identified, that is, authenticated using a client ID. See the documentation for <a href="https://ably.com/docs/auth/identified-clients">identified clients</a> for more details.
          example: false
        created:
          type: integer
          description: Unix timestamp representing the date and time of creation of the namespace.
          example: 1602844091815
        modified:
          type: integer
          description: Unix timestamp representing the date and time of last modification of the namespace.
          example: 1614679682091
        id:
          type: string
          description: The namespace or channel name that the channel rule will apply to. For example, if you specify `namespace` the namespace will be set to `namespace` and will match with channels `namespace:*` and `namespace`.
          example: namespace
        persisted:
          type: boolean
          default: false
          description: If `true`, all messages on a channel will be stored for 24 hours. You can access stored messages via the History API. Please note that for each message stored, an additional message is deducted from your monthly allocation.
          example: false
        persistLast:
          type: boolean
          default: false
          description: If `true`, the last message published on a channel will be stored for 365 days. You can access the stored message only by using the channel rewind mechanism and attaching with rewind=1. Please note that for each message stored, an additional message is deducted from your monthly allocation.
          example: false
        pushEnabled:
          type: boolean
          default: false
          description: If `true`, publishing messages with a push payload in the extras field is permitted and can trigger the delivery of a native push notification to registered devices for the channel.
          example: false
        batchingEnabled:
          type: boolean
          default: false
          description: If `true`, channels within this namespace will start batching inbound messages instead of sending them out immediately to subscribers.
          example: false
        batchingPolicy:
          type: string
          default: simple
          description: If `true`, groups multiple incoming messages into a single batch.
          example: simple
        batchingInterval:
          type: integer
          default: 20
          description: If `true`, the batching interval, configurable from 20ms to 1s, temporarily holds and aggregates incoming messages. These messages are then combined and delivered as a single batch once the interval elapses or a size limit is reached (before the interval elapses).
          example: 20
        tlsOnly:
          type: boolean
          default: false
          description: If `true`, only clients that are connected using TLS will be permitted to subscribe to any channels within this namespace.
          example: false
        exposeTimeserial:
          type: boolean
          description: If `true`, messages received on a channel will contain a unique `timeserial` that can be referenced by later messages for use with message interactions.
    namespace_post:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          description: The namespace or channel name that the channel rule will apply to. For example, if you specify `namespace` the namespace will be set to `namespace` and will match with channels `namespace:*` and `namespace`.
          example: namespace
        authenticated:
          type: boolean
          default: false
          description: If `true`, clients will not be permitted to use (including to attach, publish, or subscribe) any channels within this namespace unless they are identified, that is, authenticated using a client ID. See the documentation for <a href="https://ably.com/docs/auth/identified-clients">identified clients</a> for more details.
          example: false
        persisted:
          type: boolean
          default: false
          description: If `true`, all messages on a channel will be stored for 24 hours. You can access stored messages via the History API. Please note that for each message stored, an additional message is deducted from your monthly allocation.
          example: false
        persistLast:
          type: boolean
          default: false
          description: If `true`, the last message published on a channel will be stored for 365 days. You can access the stored message only by using the channel rewind mechanism and attaching with rewind=1. Please note that for each message stored, an additional message is deducted from your monthly allocation.
          example: false
        pushEnabled:
          type: boolean
          default: false
          description: If `true`, publishing messages with a push payload in the extras field is permitted and can trigger the delivery of a native push notification to registered devices for the channel.
          example: false
        batchingEnabled:
          type: boolean
          default: false
          description: If `true`, channels within this namespace will start batching inbound messages instead of sending them out immediately to subscribers.
          example: false
        batchingPolicy:
          type: string
          default: simple
          description: If `true`, groups multiple incoming messages into a single batch.
          example: simple
        batchingInterval:
          type: integer
          default: 20
          description: If `true`, the batching interval, configurable from 20ms to 1s, temporarily holds and aggregates incoming messages. These messages are then combined and delivered as a single batch once the interval elapses or a size limit is reached (before the interval elapses).
          example: 20
        tlsOnly:
          type: boolean
          default: false
          description: If `true`, only clients that are connected using TLS will be permitted to subscribe to any channels within this namespace.
          example: false
        exposeTimeserial:
          type: boolean
          default: false
          description: If `true`, messages received on a channel will contain a unique `timeserial` that can be referenced by later messages for use with message interactions.
      required:
      - id
    namespace_patch:
      type: object
      additionalProperties: false
      properties:
        authenticated:
          type: boolean
          default: false
          description: If `true`, clients will not be permitted to use (including to attach, publish, or subscribe) any channels within this namespace unless they are identified, that is, authenticated using a client ID. See the documentation for <a href="https://ably.com/docs/auth/identified-clients">identified clients</a> for more details.
          example: false
        persisted:
          type: boolean
          default: false
          description: If `true`, all messages on a channel will be stored for 24 hours. You can access stored messages via the History API. Please note that for each message stored, an additional message is deducted from your monthly allocation.
          example: false
        persistLast:
          type: boolean
          default: false
          description: If `true`, the last message published on a channel will be stored for 365 days. You can access the stored message only by using the channel rewind mechanism and attaching with rewind=1. Please note that for each message stored, an additional message is deducted from your monthly allocation.
          example: false
        pushEnabled:
          type: boolean
          default: false
          description: If `true`, publishing messages with a push payload in the extras field is permitted and can trigger the delivery of a native push notification to registered devices for the channel.
          example: false
        batchingEnabled:
          type: boolean
          default: false
          description: If `true`, channels within this namespace will start batching inbound messages instead of sending them out immediately to subscribers.
        batchingPolicy:
          type: string
          default: simple
          description: If `true`, groups multiple incoming messages into a single batch.
          example: simple
        batchingInterval:
          type: integer
          default: 20
          description: If `true`, the batching interval, configurable from 20ms to 1s, temporarily holds and aggregates incoming messages. These messages are then combined and delivered as a single batch once the interval elapses or a size limit is reached (before the interval elapses).
          example: 20
        tlsOnly:
          type: boolean
          default: false
          description: If `true`, only clients that are connected using TLS will be permitted to subscribe to any channels within this namespace.
          example: false
        exposeTimeserial:
          type: boolean
          description: If `true`, messages received on a channel will contain a unique `timeserial` that can be referenced by later messages for use with message interactions.
    error:
      type: object
      additionalProperties: false
      properties:
        message:
          type: string
          description: The error message.
        code:
          type: integer
          description: The HTTP status code returned.
        statusCode:
          type: integer
          description: The Ably error code.
        href:
          type: string
          description: The URL to documentation about the error code.
        details:
          type: object
          nullable: true
          description: Any additional details about the error message.
      required:
      - message
      - code
      - statusCode
      - href
  securitySchemes:
    bearer_auth:
      type: http
      scheme: bearer
      description: Control API uses bearer authentication. You need to generate an access token for use with this API. More details can be found in the <a href="https://ably.com/docs/account/control-api/#authentication">Ably docs</a>.