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/accounts/:id
Close an account
When successful, this endpoint returns the account associated with the account id used in the path parameters. It returns the same information as the /2016-07/accounts
endpoint id successful. While accounts are marked as closed immediately, it will take some time for the system to purge the account completely. As such, other endpoints may continue to return data for a couple of days. The key/values of the account object are detailed below.
id
The account id associated with specified account
name
The account name
slug
The account slug (short name)
If a user has not removed all deployments and sandbox databases associated with the account, then a 402 status code will be returned indicating that that needs to be done to finalize the billing for the account before the account can be deleted.
/2016-07/accounts/:id/users
Create a new user associated with the account id
/2016-07/accounts/:id/users/:user_id
Deletes a user associated with the account id
Note: There is no undo for deleting a user.
/2016-07/audit_events
Retrieve all audit events to which your user has access.
This endpoint returns an _embedded
key which contains an audit_events
key. That key's value is an array of audit events selected on the basis of the query parameters. Each element of the array contains an audit event object. The key/values of audit event objects are detailed below.
id
The ID of the audit event. This is the same ID as the one used in the path parameters.
account_id
The account ID associated with the audit event.
deployment_id
The deployment ID associated with the audit event.
cluster_id
The cluster ID associated with the audit event.
user_id
The user ID associated with the audit event.
created_at
The date that the audit event was created.
data
Any pertinent data recorded with the audit event.
The email address of the user who initiated the action described by the audit event.
event
The type of the audit event.
ip
The IP address of the user who initiated the action described by the event.
user_agent
The user agent of the user who initiated the action described by the event.
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.
self
A URI for this audit event.
/2016-07/audit_events/:id
Fetch information about a specific audit event accessible to your user.
This endpoint returns a single audit event associated with the audit event ID used in the path parameters. It returns the same information as the /2016-07/audit_events
endpoint. The key/values of audit event objects are detailed below.
id
The ID of the audit event. This is the same ID as the one used in the path parameters.
account_id
The account ID associated with the audit event.
deployment_id
The deployment ID associated with the audit event.
cluster_id
The cluster ID associated with the audit event.
user_id
The user ID associated with the audit event.
created_at
The date that the audit event was created.
data
Any pertinent data recorded with the audit event.
The email address of the user who initiated the action described by the audit event.
event
The type of the audit event.
ip
The IP address of the user who initiated the action described by the event.
user_agent
The user agent of the user who initiated the action described by the event.
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.
self
A URI for this audit event.
/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).
tags
User-defined tags on the cluster as a string array.
/2016-07/clusters/:id
Gets the details of a specific cluster.
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).
tags
User-defined tags on the cluster as a string array.
/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/datacenters
Returns the currently available datacenters in the Compose platform.
/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 they 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.
API-consuming accounts with exclusively owned clusters can leverage the provisioning_tags
field to select from one of their own clusters. Tags can be added and managed on owned clusters through the /2016-07/clusters/:id and PATCH, POST and DELETE methods on 2016/clusters/:id/tags on the endpoint.
When a deployment is being provisioned, it will be provisioned to a cluster where all the provisioning_tags
exist in the clusters tags. If more than one cluster matches the tags,
then a cluster will be selected on a best-fit basis - least utilization, most available resources - from amongst the matched clusters.
Note that specifying a cluster id will automatically override the use of provisioning tags.
For multi-tenant deployments, the provisioning_tags
are ignored.
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. (will be null for deployments that have Let's Encrypt enabled)
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.
cluster_id
The id of the cluster that this deployment is deployed on.
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/: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.
cluster_id
The id of the cluster that this deployment is deployed on.
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.
connection_strings.misc
Miscellaneous, database-specific connections strings for particular tools or configurations.
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
Update the deployment information for the deployment with the provided ID.
/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/deployments/:id/addons
List addons available for a given deployment
This endpoint returns a list of addons available for a deployment. The key/values are detailed below:
addons
List of available addons. If no addons are available, this will return an empty list.
name
Name of addon.
is_active
Whether or not this addon is active for the deployment. Can be true or false.
/2016-07/deployments/:id/alerts
Returns current alerts for a specific deployment.
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/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 - includes the time that the backup was initiated.
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.
is_restorable
Whether or not this backup can be used to restore directly into a new deployment. Can be true or false.
created_at
The time the backup was completed.
/2016-07/deployments/: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/: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/: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/:id.
Note: for the body parameters, either cluster_id
or datacenter
is required.
/2016-07/deployments/:id/password
Update your deployment's master password
Will respond with information about the password change recipe that is being run.
A Recipe is a process, or processes, which performs a task; in this case, that task is changing the deployment's master password. 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/portals
Gets a list of portals associated with a deployment.
The endpoint returns all portals associated with the deployment given in the parameters. It returns an _embedded
object with a portals
key whose value is an array of portals. The key/values of the object are detailed below.
id
The portal id.
name
The name associated with the portal.
type
The type of portal—typically haproxy
or ssl
.
internal_ip
The ip address associated with the portal.
zone
The zone where the portal is located.
hostname
The portal's hostname.
ssl_enabled
Whether or not the portal is SSL enabled. Only applies to Redis haproxies as they can have both SSL enabled and non-SSL enabled portals.
Deployments with specialized portals
MongoDB and RethinkDB TCP portals are specialized configurations for those database types that have knowledge of your configurations, member shards, and nodes. These portals will return mongodb
and rethink
as their type.
/2016-07/deployments/:id/portals
Adds a portal to a deployment.
Will respond with information about the portal recipe that is being run to add the portal.
A Recipe is a process, or processes, which performs a task; in this case, that task is adding a portal. 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/portals/:portal_id
Removes a portal from a deployment.
Will respond with information about the portals recipe that is being run to delete the selected portal.
A Recipe is a process, or processes, which performs a task; in this case, that task is deleteing a portal. 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/portal_users
List Portal Users for Deployment
This endpoint returns a list of portal users associated with a deployment. The results are contained within an _embedded
key contains a portal_users
key. This key's value is an array enumerating the different portal users for a deployment. The portal user types for a deployment are currently "ssh", "haproxy".
The endpoint returns an array of portal users with the following fields.
name
The name associated with the portal user
type
The type of portal (e.g. ssh) this user is defined for.
/2016-07/deployments/:id/portal_users
Create a portal user associated with a deployment
Will respond with information about the portal user recipe that is being run.
A Recipe is a process, or processes, which performs a task; in this case, that task is adding a portal user. 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/portal_users/:portal_user_id
Destroy a portal user associated with a deployment
Will respond with information about the portal user recipe that is being run to remove a portal user
A Recipe is a process, or processes, which performs a task; in this case, that task is removing a portal user. 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/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/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 currently assigned to this role
/2016-07/deployments/: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/:id/roles
Remove User Roles for Deployment
This endpoint will remove a user from the specified role.
/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.
memory_per_unit_in_mb
The amount of memory in megabytes of a single unit. When multiplied by a number of units will equal a total amount of memory (RAM).
storage_per_unit_in_mb
The amount of storage in megabytes of a single unit. When multiplied by a number of units will equal a total amount of storage (disk).
unit_size_in_mb
The size in megabytes of a single unit. Equivalent to memory_per_unit_in_mb
when unit_type
is memory
, or storage_per_unit_in_mb
when unit_type
is data
. Mainly useful for implementing scaling UIs; see note below.
unit_type
The type of unit. Either memory
(RAM) or data
(disk storage). Mainly useful for implementing scaling UIs; see note below.
Note: The unit_size_in_mb
and unit_type
fields are hints for applications presenting Scaling UIs on how to present higher and lower scalings in a slider or some other interactive element. This hint is reflected in the Compose UI, for example, where data
type slider values rise more rapidly, and to higher values, than memory
type slider values. These fields are only of interest to developers implementing consoles that replicate Compose functionality.
For all other uses, use memory_per_unit_in_mb
and storage_per_unit_in_mb
to determine your deployment's memory and storage allocation, usage, starting value, and minimum.
/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/settings/max_connections
Increases allowed connections to a PostgreSQL deployment
- This endpoint is only allowed for PostgreSQL deployments.
- PostgreSQL connections use memory resources, so deployments may require additional scaling to increase connection count. Scaling your deployment will affect the cost of your deployment.
- As the database is scaled up, we add 100 connections to the maximum number of connections for every two units of scale. For example, three units of scale is equivalent to 3GB of disk storage, 306MB of RAM, and you could have up to 200 connections.
/2016-07/deployments/: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/: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/:id/team_roles
Remove Team Roles for Deployment
This endpoint will remove a team from the specified role.
/2016-07/deployments/:id/whitelist
Gets a list of whitelisted IP addresses on a deployment.
This endpoint returns all whitelist entries associated with the deployment given in the parameters. It returns an _embedded
object with a whitelist
key whose value is an array of whitelist entries. The key/values of the objects are detailed below.
id
The whitelist entry id.
description
The description associated with the whitelist entry.
ip
The ip address that is being whitelisted. Returned ip addresses are netmasked by default.
/2016-07/deployments/:id/whitelist
Adds a whitelisted IP to the deployment.
Will respond with information about the whitelist recipe that is being run.
A Recipe is a process, or processes, which performs a task; in this case, that task is creating a whitelist entry. 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
.
IP addresses and masks
An IP address for the whitelist comprises of a single complete IPv4 address or IPv6 address with or without a netmask that is to be whitelisted. Although the IP entry allows for IPv6, no Compose deployments are currently available to IPv6 networking and so these addresses cannot be filtered on.
/2016-07/deployments/:id/whitelist/:whitelist_id
Removes a whitelisted IP from a deployment.
Will respond with information about the whitelist recipe that is being run.
A Recipe is a process, or processes, which performs a task; in this case, that task is destroying a whitelist entry. 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
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/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/recipes/:id
Get the details of a specific recipe.
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.
parent_id
The id of this recipe's parent, if this recipe is a sub-recipe.
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)
operations_complete
The number of recipe operations that have been completed (see below).
operations_total
The total number of operations that this recipe will run (see below).
Operations are the discrete steps that take place in the process of completing a recipe. Each operation will increment the operations_complete
field and may update the status_detail field as it is run. The total number of expected operations to be run for completion of the recipe is available in operations_total
.
These values, operations_complete
and operations_total
can be used as an approximate indicator of progress but note that completion of a recipe is only realized when the status
field shows completed
.
This is because sub-recipes may be included in the recipe. A recipes' sub-recipes will each have their own operations_complete
and operations_total
. Only when all sub-recipes are also complete - and the parent recipe has run all its operations - will the parent recipe be labelled as complete.
/2016-07/teams
List the teams on the account.
Lists all the teams, with id and name, on the account. Each team's users will be listed with their id and name.
/2016-07/teams
Creates a new team.
Creates a new team on the account and returns the id, name, and users list. The users list should be empty at time of team creation.
/2016-07/teams/:id
Fetch information about a specific team.
Returns team name and id. The users that are on the team will be listed with their id and name.
/2016-07/teams/:id
Update team with the provided id.
Renames a team with the specified team_id. Team users and permissions stay the same.
/2016-07/teams/:id
Delete a team.
Removes a team from the account. This only removes the team; the users will remain on the account.
/2016-07/teams/:id/users
Update the membership of a team.
This call will fully replace a team's membership with the provided list of User IDs. Users must be a member of the same account as the team specified.
/2016-07/user
Get information about the user authenticated by the provided access token.
/2016-07/deployments/:id/logfiles
Fetch information about the logfiles available for a deployment.
This endpoint returns all logfiles associated with the deployment given in the parameters. It returns an _embedded
object with a logfile
key whose value is an array of logfile objects. The key/values of logfile objects are detailed below.
id
The logfile id, used when addressing a specific logfile in the API.
deployment_id
The ID of the deployment that is associated with the logfile.
capsule_id
The ID of the capsule that is associated with the logfile.
name
Name of the logfile (which includes the time that the logfile was created).
region
The region of logfiles. (which will always match the region of deployment capsule).
status
The status of the logfile (whether or not the logfile has finished being written).
file_size
The file size of the logfile
date
The date when the logfile was captured.
/2016-07/deployments/:id/logfiles/:logfile_id
Fetch information for a specific logfile.
This endpoint returns information for a single logfile associated with the logfile id and deployment id used in the path parameters. It returns the same information as the /2016-07/deployments/:deployment_id/logfiles endpoint and adds the with the logfile's download link. The key/values are detailed below:
id
The logfile id, used when addressing a specific logfile in the API.
deployment_id
The ID of the deployment that is associated with the logfile.
capsule_id
The ID of the capsule that is associated with the logfile.
name
Name of the logfile (including the time that the logfile was created).
region
The region of logfiles (which will always match region of deployment capsule).
status
The status of the logfile (whether or not the logfile has finished being written).
file_size
The file size of the logfile
date
The date when the logfile was captured.
download_link
Download link for the logfile.
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.