The Compose API
Access to this API is authorized through a token obtained from the Compose console Account view.
The Compose API uses JSON-HAL conventions for expressing hyperlinks.
/2016-07/accounts
Fetch information about all accounts to which your user is a member.
This endpoint returns _embedded key containing a key accounts whose value is an array enumerating accounts objects. These represent accounts connected to the authorization token in use. Currently, this array will only be populated with one entry.
id
The account id associated with the token
name
The account name
slug
The account slug (short name)
/2016-07/databases
Get a list of available databases and their versions.
Databases are categorized by their stability status ("stable", "beta", "alpha", "deprecated"). The currently preferred versions are marked with preferred "true".
type
The type of the database being described. One of mongodb, redis, postgresql, elastic_search, rethink, rabbitmq, etcd, scylla, mysql, or disque.
status
The highest available stability level of the database ("stable", "beta", "alpha", "deprecated").
versions
A list of known versions in the Compose ecosystem.
versions.application
The type of the database version described.
versions.status
The stability level of this particular version of the database ("stable", "beta", "alpha", "deprecated").
versions.preferred
Whether this version is one of the currently preferred versions for the database. (It is highly recommended to only deploy the currently preferred versions.)
versions.version
The version number of the database that is being described.
/2016-07/recipes/:id
A recipe is a process, or processes, which performs a task; in this case, that task is deprovisioning. When the API returns a recipe, it gives the id and status information about that process and its current status. The recipe runs asynchronously and this endpoint allows applications to poll for the current status of any recipe.
id
The recipe id - it should be the same as the id in the request parameter.
template
A reference name for the recipe being performed. This is configured by Compose engineering.
status
The status of this recipe. It can be running, waiting, complete or failed.
status_details
A descriptive string which provides further details of the current status, designed to be shown to the user.
account_id
The id of the account associated with the running of this recipe.
deployment_id
The id of the deployment that this recipe is working on. Recipes work on a single deployment.
name
A short descriptive name of the recipe's purpose.
recipes[]
An array of recipe objects, like this one, if the recipe has sub-recipes.
created_at
Date & time when the recipe was created (ISO8601 format)
updated_at
Date & time when the recipe was last updated (ISO8601 format)
/2016-07/deployments
Fetch information about all the deployments accessible to your user.
This endpoint returns all deployments associated with the accounts returned by the /2016-07/accounts endpoint. It returns an _embedded object with a deployments key who's value is an array of deployment objects. The key/values of deployment objects are detailed below.
id
The deployment id, used when addressing a specific deployment in the API.
name
The name that was given to the deployment.
type
The type of database that this deployment contains.
created_at
The time and date of when the deployment was created. Encoded as an ISO 8601 format timestamp.
notes
The notes associated with the deployment.
customer_billing_code
The editable billing code associated with the deployment.
_links.compose_web_ui.href
A URL which serves as a link to the Compose console where this deployment can be administered from a browser.
_links.compose_web_ui.templated
Is the above link in a templated format. Currently true. {?embed} is the template marker to add further parameters.
/2016-07/deployments
Create a new deployment.
Many different databases can handle many different kinds of connections. To keep things consistent, we return all the possible types of connection keys in connection_strings but with only keys relevant to the deployment type populated. Also, some databases and drivers are "cluster-aware", meaning the can accept one connection string to connect to all nodes at once. Other databases or drivers, however, are not "cluster-aware" and require a separate connection string for each node. So, to keep the data structure consistent, connection strings are always returned as arrays.
id
The new deployment's id.
name
The deployment's given name.
connection_strings.health
The connection string querying the health of the deployment.
connection_strings.ssh
Connection string for SSH tunnels.
connection_strings.admin
The connection string (usually as URL) for connecting to the deployment's web based administration front-end.
connection_strings.ssh_admin
The connection string for SSH enabled admin (unused).
connection_strings.cli
An array of connection strings. The array elements are command line/shell commands for connecting from the console to the database.
connection_string.direct
An array of connection strings. The array elements are URLs to be used by applications to connect to the database.
provision_recipe_id
A recipe track for the status of database provisioning.
ca_certificate_base64
A base64 CA Certificate to be used by clients connecting to the database when it is deployed to verify SSL connections.
type
Type of database being deployed.
created_at
Timestamp for start of deployment process.
notes
The notes associated with the deployment.
customer_billing_code
The editable billing code associated with the deployment.
version
The version number of the deployment.
One or more of the following links will be present in the JSON _links object. All links are in templated format, meaning that an {?embed} string within the link is the template's marker to add further parameters:
compose_web_ui
A URL which serves as a link to the Compose console where this deployment can be administered from a browser.
scalings
A URI for an endpoint which offers scaling information about this deployment.
backups
A URI for an endpoint which offers backups and information about backups for this deployment.
alerts
A URI for an endpoint which offers information on the health of this deployment.
cluster
A URI which returns information on the cluster where this deployment resides.
/2016-07/deployments/:deployment_id/recipes
Retrieves the recipes, past and present, associated with the deployment.
This endpoint returns all the recipes that have been applied to a deployment in its lifetime.
Data is returned encapsulated in an _embedded object which contains an array with the key of recipes. Each element of the array is a JSON object which contains a recipe as documented in the /2016-07/recipes/:id endpoint.
/2016-07/deployments/:id
Deprovision a deployment.
Will respond with information about the deprovisioning recipe that is being run.
A Recipe is a process, or processes, which performs a task; in this case, that task is deprovisioning. When the API returns a recipe, it gives the id and status information about that process and its current status. The recipe runs asynchronously.
By querying the recipe endpoint - /2016-07/recipes/:id with the returned id, you can get updates on the status of the task being performed. Completetion is denoted by the status field being returned as completed.
/2016-07/clusters
Gets all the clusters accessible to your user.
Enterprise clusters associated with an account can be enumerated with this endpoint. If enterprise clusters exist, it returns an array of objects with information about each. Most importantly, this includes the cluster id which can be used with other endpoints to specify a deployment destination.
The endpoint returns an array of clusters which contain the following fields.
account_id
The account id associated with the cluster.
account_slug
The account slug associated with the cluster.
created_at
The date that the cluster was created.
id
The cluster id.
multitenant
Whether or not this cluster is a multitenant (as opposed to an enterprise cluster).
name
The name of the cluster.
provider
The cloud provider of the cluster (aws, softlayer, gcp, etc).
region
The region the cluster is in. Please refer to the associated cloud provider documentation for a list of possible regions.
subdomain
The subdomain used by the hosts in this cluster.
type
The type of the cluster (enterprise, multitenant, etc).
/2016-07/clusters/:id
This endpoint returns a single cluster associated with the cluster id used in the path parameters. It returns the same information as the /2016-07/clusters endpoint, but for a single cluster. The key/values of cluster objects are detailed below.
account_id
The account id associated with the cluster.
account_slug
The account slug associated with the cluster.
created_at
The date that the cluster was created.
id
The cluster id. Same id as the one used in the path parameters.
multitenant
Whether or not this cluster is a multitenant (as opposed to an enterprise cluster).
name
The name of the cluster.
provider
The cloud provider of the cluster (aws, softlayer, gcp, etc).
region
The region the cluster is in. Please refer to the associated cloud provider documentation for a list of possible regions.
subdomain
The subdomain used by the hosts in this cluster.
type
The type of the cluster (enterprise, multitenant, etc).
/2016-07/accounts/:id
Update the account information for the account with the provided ID.
/2016-07/user
Get information about the user authenticated by the provided access token.
/2016-07/deployments/:id/versions
Returns the possible version transitions for the provided deployment.
In this example, the MongoDB deployment is version 3.2.8, which is upgradable to 3.2.10. If multiple versions transitions were available for 3.2.8, they would also be listed.
application
The type of database described by the transition.
method
The manner in which the transition is to be performed ("in_place", "restore").
from_version
The current version of the specified deployment.
to_version
The possible upgrade target version for the specified deployment.
/2016-07/datacenters
Returns the currently available datacenters in the Compose platform.
/2016-07/deployments/:id
Fetch information about a specific deployment accessible to your user.
This endpoint returns a single deployment associated with the deployment id used in the path parameters. It returns the same information as the /2016-07/deployments endpoint along with the deployment's connection strings. The key/values of deployment objects are detailed below.
id
The deployment id. Same id as the one used in the path parameters.
account_id
The account id associated with the deployment.
name
The name that was given to the deployment.
created_at
The date that the deployment was created.
notes
The notes associated with the deployment.
customer_billing_code
The editable billing code associated with the deployment.
version
The current version number of the database within the deployment.
ca_certificate_base64
A base64 CA Certificate to be used by clients connecting to the database when it is deployed to verify SSL connections.
connection_strings.direct
An array of connection strings. The array elements are URLs to be used by applications to connect to the database.
connection_strings.cli
An array of connection strings. The array elements are command line/shell commands for connecting from the console to the database.
connection_strings.maps
Address translation map for Scylla deployments.
connection_strings.ssh
Connection string for SSH tunnels.
connection_strings.health
The connection string querying the health of the deployment.
connection_strings.admin
The connection string (usually as URL) for connecting to the deployment's web based administration front-end.
One or more of the following links will be present in the JSON _links object. All links are in templated format, meaning that an {?embed} string within the link is the template's marker to add further parameters
compose_web_ui
A URL which serves as a link to the Compose console where this deployment can be administered from a browser.
scalings
A URI for an endpoint which offers scaling information about this deployment.
backups
A URI for an endpoint which offers backups and information about backups for this deployment.
alerts
A URI for an endpoint which offers information on the health of this deployment.
cluster
A URI which returns information on the cluster where this deployment resides.
/2016-07/deployments/:id/scalings
Get scaling information about your deployment
Will respond with the deployment's Scaling information.
allocated_units
The number of units the deployment has available
used_units
The number of units the deployment is actually using
starting_units
The minimum required units for the deployment type
minimum_units
The minimum number of units you can scale to. Equals the greater of used_units or starting_units.
unit_size_in_mb
The size in megabytes of a single unit. When multiplied by a number of units will equal the total number of megabytes.
/2016-07/deployments/:id/scalings
Scale your deployment
Will respond with information about the Scaling recipe that is being run.
A Recipe is a process, or processes, which performs a task; in this case, that task is scaling. When the API returns a recipe, it gives the id and status information about that process and its current status. The recipe runs asynchronously.
By querying the recipe endpoint - /2016-07/recipes/:id with the returned id, you can get updates on the status of the task being performed. Completion is denoted by the status field being returned as completed.
/2016-07/deployments/:id/versions
Upgrades a deployment's software to a newer version.
id
ID of the recipe for the deployment upgrade job.
account_id
ID of the account that owns the deployment.
template
Template of the recipe that is being run.
status
Current status of the recipe.
status_detail
Further details about the recipe status.
created_at
Date and time when the recipe job started (ISO8601 format).
updated_at
Date and time when the recipe job was last updated (ISO8601 format).
deployment_id
ID of the deployment that is being upgraded.
name
Name of the recipe that is being run.
Will respond with information about the upgrade recipe that is being run.
A Recipe is a process, or processes, which performs a task; in this case, that task is upgrading. When the API returns a recipe, it gives the id and status information about that process and its current status. The recipe runs asynchronously.
By querying the recipe endpoint - /2016-07/recipes/:id with the returned id, you can get updates on the status of the task being performed. Completetion is denoted by the status field being returned as completed.
/2016-07/deployments/:deployment_id/backups
Fetch information about all the backups available for a deployment.
This endpoint returns all backups associated with the deployment given in the parameters. It returns an _embedded object with a backups key whose value is an array of backup objects. The key/values of backup objects are detailed below.
id
The backup id, used when addressing a specific backup in the API.
deployment_id
The ID of the deployment that is associated with the backup.
name
Name of the backup - the time that the backup was created.
type
The type of backup: daily, weekly, monthly, and on demand.
status
The status of the backup (whether or not the backup has finished being created).
is_downloadable
Whether or not this backup can be downloaded. Can be true or false.
/2016-07/deployments/:deployment_id/backups
Create an on-demand backup for a deployment.
Will respond with information about the Recipe being run. For more details about the returned key/value pairs refer to the /2016-07/recipes/:id.
Please note: the returned id is a recipe id, not a backup id, as the backup record is not created until part way through the backup process.
/2016-07/deployments/:deployment_id/backups/:backup_id
Fetch information for a specific backup.
This endpoint returns a single backup associated with the backup id and deployment id used in the path parameters. It returns the same information as the /2016-07/deployments/:deployment_id/backup endpoint along with the backup's download link. The key/values are detailed below:
id
ID of the backup requested.
deployment_id
The ID of the deployment that is associated with the backup.
name
Name of the backup - the time that the backup was created.
type
The type of backup: daily, weekly, monthly, and on demand.
status
The status of the backup (whether or not the backup has finished being created).
is_downloadable
Whether or not this backup can be downloaded. Can be true or false.
download_link
Download link for the backup.
/2016-07/deployments/:deployment_id/backups/:backup_id/restore
Restores a deployment's backup to a new deployment.
Creates a new deployment using the backup specified. Will return details on the new deployment created. For more information on the returned JSON refer to /2016-07/deployments.
Note: for the body parameters, either cluster_id or datacenter is required.
/2016-07/deployments/:id/alerts
This endpoint returns any active alerts associated with the deployment id used in the path parameters, along with a summary of the deployment's health.
capsule_id
The ID of the capsule associated with this alert. May be null for alerts that apply to the deployment as a whole.
deployment_id
The ID of the deployment associated with this alert. This will be the same as the ID used in the path parameter.
message
A human-readable message describing the nature of the alert.
name
The name of the alert
status
The status of the alert:
healthy: everything is normal
warning: an issue has been detected, but it is not a serious issue
critical: the issue is serious, and is likely to impact usage of this deployment
unknown: something unexpected has happened that may not affect the deployment. e.g. a failure within the monitoring system
waiting: an alert has been triggered by an in-progress operation, and it is expected to clear shortly.
/2016-07/deployments/:id
Update the deployment information for the deployment with the provided ID.
/2016-07/deployments/:deployment_id/team_roles
List Team Roles for Deployment
This endpoint returns _embedded key containing a key team_roles whose value is an array enumerating the different team roles for a deployment. The team roles are currently "developer", "manager", or "admin".
The endpoint returns a list of team roles for a deployment with the following fields.
name
The name associated with the role
teams
List of teams currently assigned to this role
/2016-07/deployments/:deployment_id/team_roles
Assign Team Roles for Deployment
Given a team_id and a role name, this endpoint will assign a team to the role specified for a deployment. The current roles and their permissions are in the following table.
developer
Developers have access to the data within the deployment, including connection strings, backups, and log files.
manager
Managers can configure the deployment itself, including scaling it, adding and removing portals, and configuring database-specific settings.
admin
Admins can do everything Developers and Managers can, and in addition, they can configure roles and deprovision the deployment.
The endpoint returns the assigned team role with the following fields.
name
The name associated with the role
teams
List of teams currently assigned to this role
/2016-07/deployments/:deployment_id/team_roles
Remove Team Roles for Deployment
This endpoint will remove a team from the specified role.
/2016-07/deployments/:deployment_id/roles
Assign User Roles for Deployment
Given a user_id and a role name, this endpoint will assign a user to the role specified for a deployment. The current roles and their permissions are described below
developer
Developers have access to the data within the deployment, including connection strings, backups, and log files.
manager
Managers can configure the deployment itself, including scaling it, adding and removing portals, and configuring database-specific settings.
admin
Admins can do everything Developers and Managers can, and in addition, they can configure roles and deprovision the deployment.
The endpoint returns the assigned role with the following fields.
name
The name associated with the role
users
List of users currently assigned to this role
/2016-07/deployments/:deployment_id/roles
List User Roles for Deployment
This endpoint returns _embedded key containing a key roles whose value is an array enumerating the different role types for a deployment. The roles for a deployment are currently. "developer", "manager", and "admin".
The endpoint returns the assigned role with the following fields.
name
The name associated with the role
users
List of users currentlyx assigned to this role
/2016-07/deployments/:deployment_id/roles
Remove User Roles for Deployment
This endpoint will remove a user from the specified role.
Introducing the API Vendor Extensions
The functionality described in these endpoints is specifically for third-party vendors of Compose services. Access to them is controlled by a vendor ID key provided by Compose on request.
/2016-07/refresh_tokens
Exchange a personal API token for an application-specific refresh token.
NOTE: You must provide a personal API token Authorization header for the user whose account will be accessed by the OAuth application. The refresh token will be created for this user.
This route is an "advanced" route for 3rd party vendors that are integrating with our API. Vendor client IDs are currently provided by request.
The returned token is an application-specific bearer token valid for one hour. You may safely ignore it if all you require is the refresh token, which is used to generate more bearer tokens in the future.
Applications are encouraged to discard the personal token upon storage of the refresh token as the personal token is significantly more sensitive.
For security reasons, issues with credentials provided to this endpoint will always return a 404.
/2016-07/billables
Get all the billable items associated with your user.
The billables endpoint returns information about billable items related to an account. This includes all deployments and capsules that make up a deployment.
Data is returned encapsulated in an _embedded object which contains an array with the key of billables. Each element of the array is a JSON object which contains the following key/value pairs.
id
The id of this billable record.
account_id
The account_id to which this billable belongs.
amount
The amount of this billable.
start_at
The date and time at which this billable started being billable.
end_at
The date and time at which this billable ended being billable. If still current, this value will be in the far future.
description
A human readable description of what this billable is reflecting.
identifier
A unique identifier for the resources that the billable is reflecting.
resource_identifier
A unique identifier for the system that is providing the resources that the billable consumes.
sku
A stock code unit value which identifies the class of the resource being billed for.
units
The number of data or memory units.
replaces_id
The id of the resource replaced by this billable where the resource was scaled up/down.