Development status

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

Copied!

Control API is currently in Preview.

Apps

Copied!

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

Copied!

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"


Copied!

Sample response:


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


Copied!

Create an app

Copied!

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
}'


Copied!

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
}


Copied!

Queues

Copied!

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

Copied!

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}'


Copied!

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"
    },
    ...
]


Copied!

Create a queue

Copied!

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"
}'


Copied!

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"
}


Copied!

Keys

Copied!

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

Copied!

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}'


Copied!

Sample response:


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


Copied!

Create a key

Copied!

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"
        ]
    }
}'


Copied!

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
}


Copied!

Update a key

Copied!

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"
        ]
    }
}'


Copied!

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
}


Copied!

Revoke a key

Copied!

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}'


Copied!

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

Rules

Copied!

You can use the Control API to manage Ably integration 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

Copied!

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}'


Copied!

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"
        }
    },
    ...
]


Copied!

List a rule by rule ID

Copied!


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


Copied!

The rule details are returned for the specified rule.

Create a rule

Copied!

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
    }
}'


Copied!

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"
    }
}


Copied!

This shows the created webhook rule.

Update a rule

Copied!

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"
    }
}'


Copied!

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

Delete a rule

Copied!

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}'


Copied!

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

See also

Copied!