Control API

Examples

This topic includes some examples of using the Control API with Curl.

In the code examples, you will need to set the following variables by any convenient method (such as setting the variables in a script, or copying and pasting suitable values directly into the code):

Variable Description
ACCOUNT_ID Your Ably Account ID (see here)
ACCESS_TOKEN Your Ably access token for the Control API (see here)
APP_ID The ID of the application you want to modify or retrieve information about (see here)

Development status

Control API is currently in Beta.

Applications

You can use the Control API to perform tasks such as listing and creating Ably applications. Operations available include:

  • Get a list of applications
  • Create an application
  • Update an application
  • Delete an application
  • Update an application’s APNs info

List your applications

To list all the Ably applications associated with your Ably account:

curl "https://control.ably.net/v1/accounts/${ACCOUNT_ID}/apps" \
     -H "Authorization: Bearer ${ACCESS_TOKEN}" \
     -H "Accept: application/json"

Sample response:

[
    {
        "accountId": "VgQpOZ",
        "id": "28GY6a",
        "name": "Default",
        "status": "enabled",
        "tlsOnly": true,
        "apnsUseSandboxEndpoint": false,
        "created": 1602844091113,
        "modified": 1602844093051
    },
    ...
]

Create an app

To create an app:

curl --location --request POST 'https://control.ably.net/v1/accounts/${ACCOUNT_ID}/apps' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ${ACCESS_TOKEN}' \
--data-raw '{
    "name": "Created App 222",
    "status": "enabled",
    "tlsOnly": true
}'

See the API reference for information on the request body.

Sample response:

{
    "accountId": "VgQpOZ",
    "id": "bh4QSw",
    "name": "Created App 222",
    "status": "enabled",
    "tlsOnly": true,
    "apnsUseSandboxEndpoint": false,
    "created": 1625813276973,
    "modified": 1625813276973
}

Queues

You can use the Control API to manage Ably queues. The main operations are:

  • List all Ably queues
  • Create a queue
  • Delete a queue

List queues

To list all queues associated with an application ID:

curl --location --request GET 'https://control.ably.net/v1/apps/${APP_ID}/queues' \
--header 'Authorization: Bearer ${ACCESS_TOKEN}'

Sample response:

[
    {
        "id": "28GY6a:us-east-1-a:Test",
        "appId": "28GY6a",
        "name": "Test",
        "region": "us-east-1-a",
        "amqp": {
            "uri": "amqps://us-east-1-a-queue.ably.io:5671/shared",
            "queueName": "28GY6a:Test"
        },
        "stomp": {
            "uri": "stomp://us-east-1-a-queue.ably.io:61614",
            "host": "shared",
            "destination": "/amqp/queue/28GY6a:Test"
        },
        "state": "Running",
        "messages": {
            "ready": 0,
            "unacknowledged": 0,
            "total": 0
        },
        "stats": {
            "publishRate": null,
            "deliveryRate": null,
            "acknowledgementRate": null
        },
        "ttl": 60,
        "maxLength": 10000,
        "deadletter": false,
        "deadletterId": "28GY6a:us-east-1-a:deadletter"
    },
    ...
]

Create a queue

To create a queue for an app:

curl --location --request POST 'https://control.ably.net/v1/apps/${APP_ID}/queues' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ${ACCESS_TOKEN}' \
--data-raw '{
    "name": "Queue 123",
    "ttl": 60,
    "maxLength": 10000,
    "region": "eu-west-1-a"
}'

See the API reference for information on the request body.

Sample response:

{
    "id": "28GY6a:eu-west-1-a:Queue 123",
    "appId": "28GY6a",
    "name": "Queue 123",
    "region": "eu-west-1-a",
    "amqp": {
        "uri": "amqps://eu-west-1-a-queue.ably.io:5671/shared",
        "queueName": "28GY6a:Queue 123"
    },
    "stomp": {
        "uri": "stomp://eu-west-1-a-queue.ably.io:61614",
        "host": "shared",
        "destination": "/amqp/queue/28GY6a:Queue 123"
    },
    "state": "Unknown",
    "messages": {
        "ready": 0,
        "unacknowledged": 0,
        "total": 0
    },
    "stats": {
        "publishRate": null,
        "deliveryRate": null,
        "acknowledgementRate": null
    },
    "ttl": 60,
    "maxLength": 10000,
    "deadletter": false,
    "deadletterId": "28GY6a:eu-west-1-a:deadletter"
}

See also


API reference
Documentation

Need help?

If you need any help with your implementation or if you have encountered any problems, do get in touch. You can also quickly find answers from our knowledge base, and blog.