Ably Control API
The Ably Control API manages accounts, apps, API keys, namespaces, queues, integration rules, and webhooks. Used to provision and operate Ably resources programmatically. Authentication via personal access token (PAT).
OpenAPI Specification
---
openapi: 3.0.1
info:
title: Control API v1
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
paths:
"/accounts/{account_id}/apps":
get:
summary: Lists account apps
description: List all Ably applications for the specified account ID.
tags:
- apps
parameters:
- name: account_id
in: path
required: true
description: The account ID for which to retrieve the associated applications.
schema:
type: string
security:
- bearer_auth: []
responses:
'200':
description: List of apps for the specified account are returned
content:
application/json:
schema:
type: array
items:
"$ref": "#/components/schemas/app_response"
'401':
description: Authentication failed
content:
application/json:
schema:
"$ref": "#/components/schemas/error"
'404':
description: Account not found
content:
application/json:
schema:
"$ref": "#/components/schemas/error"
'500':
description: Internal server error
content:
application/json:
schema:
"$ref": "#/components/schemas/error"
post:
summary: Creates an app
description: Creates an application with the specified properties.
tags:
- apps
parameters:
- name: account_id
description: The account ID of the account in which to create the application.
in: path
required: true
schema:
type: string
security:
- bearer_auth: []
responses:
'201':
description: App created
content:
application/json:
schema:
"$ref": "#/components/schemas/app_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: Account 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/app_post"
"/apps/{id}":
patch:
summary: Updates an app
description: Updates the application with the specified application ID.
tags:
- apps
parameters:
- name: id
description: The ID of application to be updated.
in: path
required: true
schema:
type: string
security:
- bearer_auth: []
responses:
'200':
description: App updated
content:
application/json:
schema:
"$ref": "#/components/schemas/app_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 resource
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/app_patch"
delete:
summary: Deletes an app
description: Deletes the application with the specified application ID.
tags:
- apps
parameters:
- name: id
description: The ID of the application to be deleted.
in: path
required: true
schema:
type: string
security:
- bearer_auth: []
responses:
'204':
description: App deleted
content: {}
'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"
"/apps/{id}/pkcs12":
post:
summary: Updates app's APNs info from a `.p12` file
description: Updates the application's Apple Push Notification service (APNs) information.
tags:
- apps
parameters:
- name: id
description: The application ID.
in: path
required: true
schema:
type: string
security:
- bearer_auth: []
responses:
'200':
description: App updated
content:
application/json:
schema:
"$ref": "#/components/schemas/app_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"
'500':
description: Internal server error
content:
application/json:
schema:
"$ref": "#/components/schemas/error"
requestBody:
content:
multipart/form-data:
schema:
"$ref": "#/components/schemas/app_pkcs12"
"/apps/{app_id}/keys":
get:
summary: Lists app keys
description: Lists the API keys associated with the application ID.
tags:
- keys
parameters:
- name: app_id
description: The application ID.
in: path
required: true
schema:
type: string
security:
- bearer_auth: []
responses:
'200':
description: Key list
content:
application/json:
schema:
type: array
items:
"$ref": "#/components/schemas/key_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 key
description: Creates an API key for the application specified.
tags:
- keys
parameters:
- name: app_id
description: The application ID.
in: path
required: true
schema:
type: string
security:
- bearer_auth: []
responses:
'201':
description: Key created
content:
application/json:
schema:
"$ref": "#/components/schemas/key_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/key_post"
"/apps/{app_id}/keys/{key_id}":
patch:
summary: Updates a key
description: Update the API key with the specified key ID, for the application with the specified application ID.
tags:
- keys
parameters:
- name: app_id
description: The application ID.
in: path
required: true
schema:
type: string
- name: key_id
description: The API key ID.
in: path
required: true
schema:
type: string
security:
- bearer_auth: []
responses:
'200':
description: Key updated
content:
application/json:
schema:
"$ref": "#/components/schemas/key_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"
'504':
description: Gateway timeout
content:
application/json:
schema:
"$ref": "#/components/schemas/error"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/key_patch"
"/apps/{app_id}/keys/{key_id}/revoke":
post:
summary: Revokes a key
description: Revokes the API key with the specified ID, with the Application ID. This deletes the key.
tags:
- keys
parameters:
- name: app_id
description: The application ID.
in: path
required: true
schema:
type: string
- name: key_id
description: The key ID.
in: path
required: true
schema:
type: string
security:
- bearer_auth: []
responses:
'200':
description: Key revoked
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"
"/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"
"/apps/{app_id}/queues":
get:
summary: Lists queues
description: Lists the <a href="https://ably.com/docs/general/queues">queues</a> associated with the specified application ID.
tags:
- queues
parameters:
- name: app_id
description: The application ID.
in: path
required: true
schema:
type: string
security:
- bearer_auth: []
responses:
'200':
description: Queue list
content:
application/json:
schema:
type: array
items:
"$ref": "#/components/schemas/queue_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"
'503':
description: 503 Service unavailable
content:
application/json:
schema:
"$ref": "#/components/schemas/error"
'504':
description: Gateway timeout
content:
application/json:
schema:
"$ref": "#/components/schemas/error"
post:
summary: Creates a queue
description: Creates a <a href="https://ably.com/docs/general/queues">queue</a> for the application specified by application ID. The properties for the queue to be created are specified in the request body.
tags:
- queues
parameters:
- name: app_id
description: The application ID.
in: path
required: true
schema:
type: string
security:
- bearer_auth: []
responses:
'201':
description: Queue created
content:
application/json:
schema:
"$ref": "#/components/schemas/queue_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/queue"
"/apps/{app_id}/queues/{queue_id}":
delete:
summary: Deletes a queue
description: Delete the <a href="https://ably.com/docs/general/queues">queue</a> with the specified queue name, from the application with the specified application ID.
tags:
- queues
parameters:
- name: app_id
description: The application ID.
in: path
required: true
schema:
type: string
- name: queue_id
description: The queue ID.
in: path
required: true
schema:
type: string
security:
- bearer_auth: []
responses:
'204':
description: Queue deleted
content: {}
'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"
'500':
description: Internal server error
content:
application/json:
schema:
"$ref": "#/components/schemas/error"
'503':
description: 503 Service unavailable
content:
application/json:
schema:
"$ref": "#/components/schemas/error"
"/apps/{app_id}/rules":
get:
summary: Lists rules
description: Lists the <a href="https://ably.com/docs/general/webhooks">rules</a> for the application specified by the application ID.
tags:
- rules
parameters:
- name: app_id
description: The application ID.
in: path
required: true
schema:
type: string
security:
- bearer_auth: []
responses:
'200':
description: Rule list
content:
application/json:
schema:
type: array
items:
"$ref": "#/components/schemas/rule_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 rule
description: Creates a <a href="https://ably.com/docs/general/webhooks">rule</a> for the application with the specified application ID.
tags:
- rules
parameters:
- name: app_id
description: The application ID.
in: path
required: true
schema:
type: string
security:
- bearer_auth: []
responses:
'201':
description: Rule created
content:
application/json:
schema:
"$ref": "#/components/schemas/rule_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"
'504':
description: Gateway timeout
content:
application/json:
schema:
"$ref": "#/components/schemas/error"
requestBody:
description: The rule properties.
content:
application/json:
schema:
"$ref": "#/components/schemas/rule_post"
"/apps/{app_id}/rules/{rule_id}":
get:
summary: Gets a rule using a rule ID
description: Returns the <a href="https://ably.com/docs/general/webhooks">rule</a> specified by the rule ID, for the application specified by application ID.
tags:
- rules
parameters:
- name: app_id
description: The application ID.
in: path
required: true
schema:
type: string
- name: rule_id
description: The rule ID.
in: path
required: true
schema:
type: string
security:
- bearer_auth: []
responses:
'200':
description: Rule
content:
application/json:
schema:
"$ref": "#/components/schemas/rule_response"
'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"
patch:
summary: Updates a Rule
description: Updates the <a href="https://ably.com/docs/general/webhooks">rule</a> specified by the rule ID, for the application specified by application ID.
tags:
- rules
parameters:
- name: app_id
description: The application ID.
in: path
required: true
schema:
type: string
- name: rule_id
description: The rule ID.
in: path
required: true
schema:
type: string
security:
- bearer_auth: []
responses:
'200':
description: Rule updated
content:
application/json:
schema:
"$ref": "#/components/schemas/rule_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"
'504':
description: Gateway timeout
content:
application/json:
schema:
"$ref": "#/components/schemas/error"
requestBody:
description: Properties for the rule.
content:
application/json:
schema:
"$ref": "#/components/schemas/rule_patch"
delete:
summary: Deletes a rule
description: Deletes the <a href="https://ably.com/docs/general/webhooks">rule</a> specified by the rule ID, for the application specified by application ID.
tags:
- rules
parameters:
- name: app_id
description: The application ID.
in: path
required: true
schema:
type: string
- name: rule_id
description: The rule ID.
in: path
required: true
schema:
type: string
security:
- bearer_auth: []
responses:
'204':
description: Rule deleted
content: {}
'401':
description: Authentication failed
content:
application/json:
schema:
"$ref": "#/components/schemas/error"
'404':
description: App not found
content:
application/json:
# --- truncated at 32 KB (210 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ably/refs/heads/main/openapi/ably-control-api-openapi.yml