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 Ably app you want to modify or retrieve information about (see app ID) docs for more details

Development status

Control API is currently in Beta.

Apps

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

  • Get a list of apps
  • Create an app
  • Update an app
  • Delete an app
  • Update an app’s APNs info

List your apps

To list all the Ably apps 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 app 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"
}

Keys

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

  • List all Ably API keys for an app
  • Create a key
  • Update a key
  • Revoke a key

Control API enables you to create a key that has different capabilities for different channels.

List API keys

To list all keys associated with an app ID:

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

Sample response:

[
    {
        "appId": "28GY6a",
        "id": "-frw5Q",
        "name": "Control API Key",
        "key": "28GY6a.-frw5Q:ZHTaEUGGJWJtHSkZ",
        "capability": {
            "channel-1": [
                "publish"
            ]
        },
        "created": 1630074457007,
        "modified": 1630074457007
    },
    ...
]

Create a key

The following example demonstrates how to create an Ably API key:

curl --location --request POST 'https://control.ably.net/v1/apps/${APP_ID}/keys' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ${ACCESS_TOKEN}' \
--data-raw '{
    "name": "My key name",
    "capability": {
        "channel1": [
            "publish",
            "subscribe"
        ],
        "channel2": [
            "history"
        ]
    }
}'

This request creates an API key with the key name My key name. Note that this key specifies different capabilities for each channel, for example, on channel1 this key has publish and subscribe capabilities. On channel2 the key only has the history capability.

Sample response:

{
    "appId": "28GY6a",
    "id": "Eg063g",
    "name": "My key name",
    "key": "28GY6a.Eg063g:Dp9ZNfK6Qr8aWy-q",
    "capability": {
        "channel1": [
            "publish",
            "subscribe"
        ],
        "channel2": [
            "history"
        ]
    },
    "created": 1630506079278,
    "modified": 1630506079278
}

Update a key

The following request updates the key name, and also adds the history capability to channel1:

curl --location --request PATCH 'https://control.ably.net/v1/apps/${APP_ID}/keys/${KEY_ID}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ${ACCESS_TOKEN}' \
--data-raw '{
    "name": "My key name UPDATED",
    "capability": {
        "channel1": [
            "publish",
            "subscribe",
            "history"
        ],
        "channel2": [
            "history"
        ]
    }
}'

Sample response:

{
    "appId": "28GY6a",
    "id": "RCSMrg",
    "name": "My key name UPDATED",
    "key": "28GY6a.RCSMrg:z8HkAtY7rMtnpcGq",
    "capability": {
        "channel1": [
            "history",
            "publish",
            "subscribe"
        ],
        "channel2": [
            "history"
        ]
    },
    "created": 1630507628335,
    "modified": 1630507811349
}

Revoke a key

To revoke a specific key for a specific app:

curl --location --request POST 'https://control.ably.net/v1/apps/${APP_ID/keys/${KEY_ID}/revoke' \
--header 'Authorization: Bearer ${ACCESS_TOKEN}'

In this case there is only a status code returned (200), or an error code.

Rules

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

  • List all rules for an app
  • List details of a specific rule using rule ID
  • Create a rule
  • Update a rule
  • Delete a rule

List rules

To list the rules for an app:

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

Sample response:

[
    {
        "id": "oO-Tug",
        "appId": "28GY6a",
        "ruleType": "http",
        "requestMode": "single",
        "status": "disabled",
        "source": {
            "channelFilter": "",
            "type": "channel.message"
        },
        "target": {
            "url": "https://example.com/webhooks",
            "signingKeyId": null,
            "enveloped": true,
            "format": "json",
            "headers": [
                {
                    "name": "User-Agent",
                    "value": " user-agent-name"
                }
            ]
        },
        "version": "1.0",
        "created": 1626893758695,
        "modified": 1626894987810,
        "_links": {
            "self": "https://control.ably.net/v1/apps/28GY6a/rules/oO-Tug"
        }
    },
    ...
]

List a rule by rule ID

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

The rule details are returned for the specified rule.

Create a rule

The following example creates a rule with the following configuration:

Parameter Value Description
ruleType http The type of rule, in this case a webhook rule
requestMode single Request mode can be single or batched
channelFilter ^my-channel.* An optional regular expression that allows the rule to be applied to the specified channel set
type channel.message Source type. This means that the source event that will trigger this rule is any message on the channel
url https://example.com/webhooks The webhook endpoint. This is the URL triggered for the event
format json Format of encoding for the rule, in this case JSON
name User-Agent Optional header or headers, including custom headers that might be required. In this case a user agent header is specified (this needs to be set for some providers)
value user-agent-name The value of the header
enveloped true Wrap packet in metadata

The corresponding request is:

curl --location --request POST 'https://control.ably.net/v1/apps/${APP_ID}/rules' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ${ACCESS_TOKEN}' \
--data-raw '{
    "ruleType": "http",
    "requestMode": "single",
    "source": {
        "channelFilter": "^my-channel.*",
        "type": "channel.message"
    },
    "target": {
        "url": "https://example.com/webhooks",
        "format": "json",
        "headers": [
            {
                "name": "User-Agent",
                "value": "user-agent-string"
            },
            {
                "name": "headerName",
                "value": "headerValue"
            }
        ],
        "enveloped": true
    }
}'

Sample response:

{
    "id": "3DySkw",
    "appId": "28GY6a",
    "ruleType": "http",
    "requestMode": "single",
    "status": "enabled",
    "source": {
        "channelFilter": "^my-channel.*",
        "type": "channel.message"
    },
    "target": {
        "url": "https://example.com/webhooks",
        "signingKeyId": null,
        "enveloped": true,
        "format": "json",
        "headers": [
            {
                "name": "User-Agent",
                "value": "user-agent-string"
            },
            {
                "name": "headerName",
                "value": "headerValue"
            }
        ]
    },
    "version": "1.0",
    "created": 1630588265781,
    "modified": 1630588265781,
    "_links": {
        "self": "https://control.ably.net/v1/apps/28GY6a/rules/3DySkw"
    }
}

This shows the created webhook rule.

Update a rule

If you need to change a rule you can update it. For example, if you wanted to change the webhook endpoint URL you could carry out the following request:

curl --location --request PATCH 'https://control.ably.net/v1/apps/${APP_ID}/rules/${RULE_ID}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ${ACCESS_TOKEN}' \
--data-raw '{
    "ruleType": "http",
    "target": {
        "url": "https://example.com/webhooks/webhook1"
    }
}'

The response is the same as for rule creation, but reflects the updated information.

Delete a rule

If you need to delete a rule you can:

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

In this case there is only a status code returned (204), or an error code.

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.