Introduction
The Composable API is a RESTful API that allows you to create, manage, and execute interactions.
The API is located at https://api.becomposable.com/api/v1. In this API reference guide we will use short paths, relative to this URL when we are referring to endpoints locations.
For example /interactions
refers to https://api.becomposable.com/api/v1/interactions
.
When you sign in for the first time to Composable Studio, a default organization named <User Name>'s Personal Account will be created for you.
You can create new accounts and switch between them from the Studio Application.
In this guide we will use account and organziation interchangeably they both refer to the same thing.
Authentication
To authenticate with the API, you need to provide a valid API key as a bearer token in the Authorization
header of your request.
Example:
Authorization: Bearer <api_key>
The API key is bound to an organzization (i.e. account). If you have more organization you need to create API keys for each organization.
Accept Header
When performing requests to the API, you must use an application/json
accept header.
Accept: application/json
Even in case of errors the response will be in JSON
format.
Errors
The API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success and codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a token was invalid, etc.), and codes in the 5xx range indicate an error with Composable's servers. When an error occurs, the API will return a JSON object with the following structure:
{
"error": "Error name",
"status": {http_error_code},
"message": "Error message"
}
Example:
{
"error": "Not Found",
"status": 404,
"message": "Interaction not found: 6554cf617eae1c28ef5f3d41"
}
When using the StudioClient
provided by the JavaScript SDK you don't need to explicitely set the request headers. The SDK will automatically set the Authorization
, X-Project-Id
and Accept
headers for you.
And the response errors will be automatically converted to JavaScript errors.