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>.