Testing with Postman
The Control API is designed for programmatic access to your account. However, you can try out individual requests using either a command line tool such as Curl or HTTPie, or a graphical tool such as Postman or Paw. This topic shows you how to make requests using Postman.
Development status
Control API is currently in Preview.
Importing the OpenAPI document into Postman
A convenient way to try out the Control API is by importing the OpenAPI document into Postman, and then sending requests and checking the responses. To do this, perform the following steps:
- Make sure you have Postman installed.
- Start Postman and select “File > Import” from the main menu. The import dialog is displayed:

- Click the “Link” tab, and paste in the following URL:
https://raw.githubusercontent.com/ably/open-specs/main/definitions/control-v1.yaml
, then click “Continue”:

- In the Import dialog, use the default settings and click “Import”:

- The imported document now appears in your Postman collections:

You have now imported the OpenAPI document into Postman.
Sending a request
First, you need to obtain a Control API token to authenticate any requests you send to the Control API.
For many Control API requests you also need to specify your account ID or app ID. You can see the account ID and app ID section for details on how to obtain these.
Now that you have obtained the token and IDs, you can learn how to send a request in Postman.
- Expand the collection to the
Lists account apps
request. The following screenshot shows the parameters for the request:

- The
Lists account apps
request is an account-level operation and therefore requires your account ID in theaccount_id
path variable. This path variable is highlighted with the green box in the previous screenshot. Paste your Ably account ID into the “VALUE“ field.
- You also need to enter your Control API token as a
Bearer Token
in the “Authorization” tab. Paste your Ably Control API token into the token field marked with the placeholder text<Bearer Token>
, as shown in the following screenshot:

Note: If you don’t supply this token, your request will fail to authenticate.
- Now that this request is configured, you can send the request by clicking the “Send” button:

- The server returns a response, listing your Ably apps:

You can now try out other requests. You need to set the necessary parameters and authentication token as required by that specific request. Consult the API Reference for further information.
You can also use the command-line tool Curl to work with the Control API. See the Curl examples section of the Ably documentation.