Control API

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 Beta.

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:

1. Make sure you have Postman installed.

2. Start Postman and select “File > Import” from the main menu. The import dialog is displayed:


Postman import dialog

3. 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”:


Link to OpenAPI document

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


Postman import default

5. The imported document now appears in your Postman collections:


Postman imported collection

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.

1. Expand the collection to the Lists account apps request. The following screenshot shows the parameters for the request:


App list request

2. The Lists account apps request is an account-level operation and therefore requires your account ID in the account_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.

3. 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:


Bearer token

Note: If you don’t supply this token, your request will fail to authenticate.

4. Now that this request is configured, you can send the request by clicking the “Send” button:


Send request

5. The server returns a response, listing your Ably apps:


Response

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.

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.