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