Compose API Documentation

Compose's API gives developers and users programmatic control over the database deployment capabilities of the database-as-a-service platform. Here you'll find the information you need to take the controls.

Documentation
Suggest Edits

The Compose API

 

Access to this API is authorized through a token obtained from the Compose console Account view.

How the Compose API is documented

The Compose API uses JSON-HAL conventions for expressing hyperlinks.

Suggest Edits

/2016-07/accounts

Fetch information about all accounts to which your user is a member.

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.compose.io/2016-07/accounts
curl -X GET -H "Authorization: Bearer [[app:Authorization]]" -H "Content-Type: application/json" 'https://api.compose.io/2016-07/accounts'
A binary file was returned

You couldn't be authenticated

{
  "_embedded":{
    "accounts":[
      {
        "id": "52a50cb96230650018000000",
        "name": "Northwind",
        "slug": "northwind"
      }
    ]
  }
}
 

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.

`accounts` object key
Description

id

The account id associated with the token

name

The account name

slug

The account slug (short name)

Suggest Edits

/2016-07/databases

Get a list of available databases and their versions.

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.compose.io/2016-07/databases
curl -X GET -H "Content-Type: application/json" 'https://api.compose.io/2016-07/databases'
A binary file was returned

You couldn't be authenticated

{
  "_embedded": {
    "applications": [{
      "type": "elastic_search",
      "status": "stable",
      "display_name": "Elasticsearch",
      "_embedded": {
	"versions": [{
	  "application": "elastic_search",
	  "status": "deprecated",
	  "preferred": false,
	  "version": "2.1.1"
	}, {
	  "application": "elastic_search",
	  "status": "stable",
	  "preferred": true,
	  "version": "2.4.0"
	}, {
	  "application": "elastic_search",
	  "status": "internal",
	  "preferred": false,
	  "version": "3.0.4"
	}, {
	  "application": "elastic_search",
	  "status": "internal",
	  "preferred": false,
	  "version": "3.2.0"
	}]
      }
    }, {
      "type": "etcd",
      "status": "beta",
      "display_name": "etcd",
      "_embedded": {
	"versions": [{
	  "application": "etcd",
	  "status": "deprecated",
	  "preferred": false,
	  "version": "2.2.2"
	}, {
	  "application": "etcd",
	  "status": "deprecated",
	  "preferred": false,
	  "version": "2.2.5"
	}, {
	  "application": "etcd",
	  "status": "beta",
	  "preferred": true,
	  "version": "2.3.7"
	}]
      }
    }, {
      "type": "mongodb",
      "status": "stable",
      "display_name": "MongoDB",
      "_embedded": {
	"versions": [{
	  "application": "mongodb",
	  "status": "deprecated",
	  "preferred": false,
	  "version": "3.2.0"
	}, {
	  "application": "mongodb",
	  "status": "deprecated",
	  "preferred": false,
	  "version": "3.2.1"
	}, {
	  "application": "mongodb",
	  "status": "deprecated",
	  "preferred": false,
	  "version": "3.2.6"
	}, {
	  "application": "mongodb",
	  "status": "deprecated",
	  "preferred": false,
	  "version": "3.2.7"
	}, {
	  "application": "mongodb",
	  "status": "deprecated",
	  "preferred": false,
	  "version": "3.2.8"
	}, {
	  "application": "mongodb",
	  "status": "stable",
	  "preferred": true,
	  "version": "3.2.10"
	}]
      }
    }, {
      "type": "mysql",
      "status": "stable",
      "display_name": "MySQL",
      "_embedded": {
	"versions": [{
	  "application": "mysql",
	  "status": "stable",
	  "preferred": true,
	  "version": "5.7.15"
	}]
      }
    }, {
      "type": "postgresql",
      "status": "stable",
      "display_name": "PostgreSQL",
      "_embedded": {
	"versions": [{
	  "application": "postgresql",
	  "status": "deprecated",
	  "preferred": false,
	  "version": "9.4.8"
	}, {
	  "application": "postgresql",
	  "status": "stable",
	  "preferred": true,
	  "version": "9.4.9"
	}, {
	  "application": "postgresql",
	  "status": "deprecated",
	  "preferred": false,
	  "version": "9.5.2"
	}, {
	  "application": "postgresql",
	  "status": "deprecated",
	  "preferred": false,
	  "version": "9.5.3"
	}, {
	  "application": "postgresql",
	  "status": "stable",
	  "preferred": true,
	  "version": "9.5.4"
	}, {
	  "application": "postgresql",
	  "status": "internal",
	  "preferred": false,
	  "version": "9.5.5"
	}]
      }
    }, {
      "type": "rabbitmq",
      "status": "stable",
      "display_name": "RabbitMQ",
      "_embedded": {
	"versions": [{
	  "application": "rabbitmq",
	  "status": "deprecated",
	  "preferred": false,
	  "version": "3.5.6"
	}, {
	  "application": "rabbitmq",
	  "status": "stable",
	  "preferred": true,
	  "version": "3.6.5"
	}]
      }
    }, {
      "type": "redis",
      "status": "stable",
      "display_name": "Redis",
      "_embedded": {
	"versions": [{
	  "application": "redis",
	  "status": "deprecated",
	  "preferred": false,
	  "version": "2.8.21"
	}, {
	  "application": "redis",
	  "status": "stable",
	  "preferred": true,
	  "version": "3.0.7"
	}, {
	  "application": "redis",
	  "status": "deprecated",
	  "preferred": false,
	  "version": "3.2.1"
	}, {
	  "application": "redis",
	  "status": "deprecated",
	  "preferred": false,
	  "version": "3.2.3"
	}, {
	  "application": "redis",
	  "status": "deprecated",
	  "preferred": false,
	  "version": "3.2.4"
	}, {
	  "application": "redis",
	  "status": "stable",
	  "preferred": true,
	  "version": "3.2.6"
	}]
      }
    }, {
      "type": "rethink",
      "status": "stable",
      "display_name": "RethinkDB",
      "_embedded": {
	"versions": [{
	  "application": "rethink",
	  "status": "deprecated",
	  "preferred": false,
	  "version": "2.3.4"
	}, {
	  "application": "rethink",
	  "status": "stable",
	  "preferred": true,
	  "version": "2.3.5"
	}]
      }
    }, {
      "type": "scylla",
      "status": "beta",
      "display_name": "ScyllaDB",
      "_embedded": {
	"versions": [{
	  "application": "scylla",
	  "status": "beta",
	  "preferred": true,
	  "version": "1.4.2"
	}]
      }
    }]
  }
}
 

Databases are categorized by their stability status ("stable", "beta", "alpha", "deprecated"). The currently preferred versions are marked with preferred "true".

Returned JSON

`applications` object key
Description

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.

Suggest Edits

/2016-07/recipes/:id

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.compose.io/2016-07/recipes/id
curl -X GET 'https://api.compose.io/2016-07/recipes/5821fd28a4b549d06e39886d'
-H "Authorization: Bearer [[app:Authorization]]"
-H "Content-Type: application/json; charset=utf-8"
A binary file was returned

You couldn't be authenticated

{
    "id": "5821fd28a4b549d06e39886d",
    "template": "Recipes::Deployment::Run",
    "status": "complete",
    "status_detail": "All operations have completed successfully!",
    "account_id": "5821fd28a4b549d06e398867",
    "created_at": "2016-12-27T20:35:32.733Z",
    "updated_at": "2016-12-27T20:40:44.087Z",
    "deployment_id": "5821fd28a4b549d06e398869",
    "name": "Provision",
    "_embedded": {
        "recipes": []
    }
}

Path Params

id
string
required

The Recipe ID to examine

 

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.

Returned JSON

Key
Description

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)

Suggest Edits

/2016-07/deployments

Fetch information about all the deployments accessible to your user.

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.compose.io/2016-07/deployments
curl -X GET -H "Authorization: Bearer [[app:Authorization]]" -H "Content-Type: application/hal+json" 'https://api.compose.io/2016-07/deployments'
A binary file was returned

You couldn't be authenticated

{
  "_embedded": {
    "deployments": [{
      "id": "56f17b4fa4b549d899000001",
      "name": "test-deployment-1",
      "type": "elastic_search",
      "created_at": "2016-07-22T19:23:07.767Z",
      "notes": "the first test deployment",
      "customer_billing_code": "bill-to-test-team",
      "_links": {
        "compose_web_ui": {
          "href": "https://app.compose.io/northwind/deployments/test-deployment-1{?embed}",
          "templated": true
        }
      }
    }]
  }
}
 

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.

Returned JSON

`deployments` object key
Description

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.

Suggest Edits

/2016-07/deployments

Create a new deployment.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.compose.io/2016-07/deployments
curl -X POST 'https://api.compose.io/2016-07/deployments' \
-H "Authorization: Bearer [[app:Authorization]]" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{
  "deployment": {
    "name": "fizz-production",
    "account_id": "52a50cb96230650018000000",
    "cluster_id": "57ade1d70b2fa9ce1c7e6162",
    "type": "postgresql"
  }
}'
A binary file was returned

You couldn't be authenticated

{
  "id": "52a50cb96230650018000000",
  "name": "fizz-production",
  "connection_strings": {
    "health": null,
    "ssh": null,
    "admin": null,
    "ssh_admin": null,
    "cli": ["psql \"sslmode=require host=cpu.blazzleblazzle.compose.direct port=10000 dbname=compose user=compose\""],
    "direct": ["postgres://compose:XXXXXX@customer-cluster.1.compose.direct:10020/compose"]
  },
  "provision_recipe_id": "52a50cb96230650018000000",
  "ca_certificate_base64": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURmekNDQW1lZ0F3SUJBZ0lFVjhZR2h6QU5CZ2txaGtpRzl3MEJBUTBGQURCQk1UOHdQUVlEVlFRREREWkUKWVc0Z1EyOXVibTl5SUVOdmJuTjFiSFJwYm1jdFpXTTBZams0TjJNd1lURmhNak5tWVRNek9ESXhZbUV3TkRkbApOVGt6TmpZd0hoY05NVFl3T0RNd01qSXhPVFV4V2hjTk16WXdPRE13TWpJd01EQXdXakJCTVQ4d1BRWURWUVFECkREWkVZVzRnUTI5dWJtOXlJRU52Ym5OMWJIUnBibWN0WldNMFlqazROMk13WVRGaE1qTm1ZVE16T0RJeFltRXcKTkRkbE5Ua3pOall3Z2dFaU1BMEdDU3FHU0liM0RRRUJBUVVBQTRJQkR3QXdnZ0VLQW9JQkFRRHV6dmdrNUtFUApyclRHbnFjcnpCK0R6RGhLbE1pV3VxZjllcmlJelpURmNhRFFqTkh3T1JFQ2V1S29YeUNDa3lXV2R3THZ1bmlFCmZEanV2RytGV3ZtUms1SkxPWG5zM0lQbFhFUUM1SWhjdDVzVkxVN3kzR2FzcUF6T0syR0wwNWVIYm1WOXhLRjcKdjRycUdXTHAxZTV1UEd0SHM5NGJoLzd1NkpualpEbGEycmhFV2xmWm03T1VUWWJxc1p1ZVM5MmRSYlJMK05teQpHbVl6aEp3b2lNb2NuQ1RtT0xkSUdrdmtRMm5LekIxRkhFN080NUx5YUdLMFE4YjVqdW1zUDhtcGZXTlRJZ3lyCmVTVmRKRHJwcVN5Rld6enB4enlvMDRSeWlJTjZyNlY5aUhGWEJIaU81RE9aLzlvVkR1R04vM0N2NVZ4M1E0L3YKNGgvNkxzRXBxK2QxQWdNQkFBR2pmekI5TUIwR0ExVWREZ1FXQkJSTzRmanVaaXNQRnRYRFFHYkNTWDFpbnFpdAphakFPQmdOVkhROEJBZjhFQkFNQ0FnUXdIUVlEVlIwbEJCWXdGQVlJS3dZQkJRVUhBd0VHQ0NzR0FRVUZCd01DCk1Bd0dBMVVkRXdRRk1BTUJBZjh3SHdZRFZSMGpCQmd3Rm9BVVR1SDQ3bVlyRHhiVncwQm13a2w5WXA2b3JXb3cKRFFZSktvWklodmNOQVFFTkJRQURnZ0VCQUtIbW85eVFDYU8zNzU0UmtRS3NnT0RjbUt5SXM4bTNLVWx1dldSVwpESUFPVVlRN3BTUk4xcXQ1MDR1U0tWUGFBZDhGRWZvYkpVaVVyU2ZWQ1prVUorV0ExeVFOOGcwSDV0aWN1a1FNCnlNMmZjRFdpclBhMjdUN2ExQ0l1NkdLNnBvcUhWNyswdjFPVlBXUW1Cb2NtTXlTZmVQekhCR0huYk5sRURpeU0KWXdtMkJJNzREakpWK3ZaL2VWQm1yT2pnajhkS0l3RDNncVR0c0QzbnVMcUQ2TlRVeGg0ckVMQ1dQekN2RzYwNwpYZE1NbGlkZkE2MTBaekdOQ0l1SWhoc2hsSFlVdEFGTDRITllFM25IK3lPSVhUR3VGY2hmc2FtdkJDekIvVEFqCjJaUkdDZSthMEFtVmJPTHpOYVlBL2RYR1UrdVJXMWgzK29JSEF2OUkvclBSQ1hZPQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg==",
  "type": "postgresql",
  "version": "9.6.3",
  "created_at": "2016-04-05T17:48:07Z",
  "_links": {
    "compose_web_ui": {
      "href": "https://app.compose.io/northwind/deployments/fizz-production{?embed}",
      "templated": true
    }
  }
}

Body Params

deployment
object
 
deployment.name
string

Name of new deployment (must be unique per account)

deployment.account_id
string

Specify the account in which the deployment will be placed.

deployment.cluster_id
string

Enterprise cluster on the account to provision to (optional, leave blank for Compose Hosted)

deployment.datacenter
string

Datacenter to use for Compose Hosted (this parameter is ignored if cluster_id is specified): aws:us-east-1, aws:eu-west-1, softlayer:london-02, softlayer:dallas-09

deployment.type
string

Type of deployment (mongodb, redis, postgresql, elastic_search, rethink, rabbitmq, etcd, scylla, mysql, disque)

deployment.version
string

Version of the software to deploy (optional)

deployment.units
int32

Number of resource units to allocate to the deployment (defaults to 1)

deployment.ssl
boolean

Whether SSL should be enabled (if applicable to the deployment)

deployment.wired_tiger
boolean

Whether to use Wired Tiger as the storage engine (MongoDB only)

deployment.notes
string

Any notes you would like to associate with the deployment (optional)

deployment.customer_billing_code
string

An editable billing code you can use to keep track of this deployment in your records (optional)

 

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.

Returned JSON

Key
Description

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.

Returned Links

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:

Link
Description

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.

Suggest Edits

/2016-07/deployments/:deployment_id/recipes

Retrieves the recipes, past and present, associated with the deployment.

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.compose.io/2016-07/deployments/deployment_id/recipes
curl -X GET -H "Authorization: Bearer [[app:Authorization]" -H "Content-Type: application/json" 'https://api.compose.io/2016-07/deployments/52a50cb96230650018000000/recipes'
A binary file was returned

You couldn't be authenticated

{
 "_embedded": {
   "recipes": [
     {
       "id": "570c016707b2f9001400107b",
       "name": "Provision",
       "template": "Recipes::Deployment::Run",
       "status": "complete",
       "status_detail": "All operations have completed successfully!",
       "account_id": "52a50cb96230650018000000",
       "created_at": "2016-12-27T20:35:32.733Z",
       "updated_at": "2016-12-27T20:40:44.087Z",
       "deployment_id": "52a50cb96230650018000000",
       "_embedded": {
         "recipes": []
       }
     }
   ]
 }
}

Path Params

deployment_id
string
required

ID of the deployment whose recipes you want returned.

 

This endpoint returns all the recipes that have been applied to a deployment in its lifetime.

Returned JSON

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.

Suggest Edits

/2016-07/deployments/:id

Deprovision a deployment.

 

Header Auth

 Authentication is required for this endpoint.
deletehttps://api.compose.io/2016-07/deployments/id
curl -X DELETE -H "Authorization: Bearer [[app:Authorization]]" -H "Content-Type: application/json" 'https://api.compose.io/2016-07/deployments/570bcb3fee4cde000e000002'
A binary file was returned

You couldn't be authenticated

{
  "id": "570bf60a70ea13000d000000",
  "name": "Deprovision",
  "template": "Recipes::Deployment::Deprovision",
  "status": "waiting",
  "status_detail": "Running destroy_capsule on cpu.deccd8317431c28552f493a6d4aecf5d.",
  "account_id": "52a50cb96230650018000000",
  "created_at": "2016-12-27T20:35:32.733Z",
  "updated_at": "2016-12-27T20:40:44.087Z",
  "deployment_id": "570bcb3fee4cde000e000002",
  "_embedded": {
    "recipes": []
  }
}

Path Params

id
string
required

The ID of the deployment to deprovision

 

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.

Suggest Edits

/2016-07/clusters

Gets all the clusters accessible to your user.

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.compose.io/2016-07/clusters
curl -X GET -H "Authorization: Bearer [[app:Authorization]]" -H "Content-Type: application/json" 'https://api.compose.io/2016-07/clusters'
A binary file was returned

You couldn't be authenticated

{
  "_embedded": {
    "clusters": [{
      "id": "5706b9d1a4b5493d4e00016c",
      "account_id": "5703fa57a4b54901d6000000",
      "name": "test-cluster-4",
      "type": null,
      "provider": "aws",
      "region": "us-east-1",
      "multitenant": true,
      "account_slug": "compose-test-85dfec005b29b98dd2755d3c59bdaa4b",
      "created_at": "2016-04-07T15:49:37.796-04:00",
      "subdomain": "test-cluster-4-compose-test-85dfec005b29b98dd2755d3c59bdaa4b"
    }]
  }
}
 

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.

Returned JSON

The endpoint returns an array of clusters which contain the following fields.

Key
Description

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

Suggest Edits

/2016-07/clusters/:id

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.compose.io/2016-07/clusters/id
curl -X GET -H "Authorization: Bearer [[app:Authorization]]" -H "Content-Type: application/json" "https://api.compose.io/2016-07/clusters/570bcb3fee4cde000e000002"
A binary file was returned

You couldn't be authenticated

{
    "account_id": "570d0e81bc2c484e8d000000",
    "account_slug": "mongohq",
    "created_at": "2016-11-22T13:34:31.377Z",
    "id": "570bcb3fee4cde000e000002",
    "multitenant": false,
    "name": "test-enterprise-cluster",
    "provider": "aws",
    "region": "us-east-1",
    "subdomain": "test-enterprise-cluster-mongohq",
    "type": "enterprise"
}

Path Params

id
string
required

The ID of the cluster you wish to fetch

 

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.

Returned JSON

Key
Description

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

Suggest Edits

/2016-07/accounts/:id

Update the account information for the account with the provided ID.

 

Header Auth

 Authentication is required for this endpoint.
patchhttps://api.compose.io/2016-07/accounts/id
curl -X PATCH 'https://api.compose.io/2016-07/accounts/52a50cb96230650018000000'
-H "Authorization: Bearer [[app:Authorization]]"
-H "Content-Type: application/json; charset=utf-8" \
-d '{
  "account": {
    "stripe_customer_id": "cus_8zKpKRAJTpj9bj"
  }
}'
A binary file was returned

You couldn't be authenticated

{
  "id": "52a50cb96230650018000000",
  "name": "Northwind",
  "slug": "northwind"
}

Path Params

id
string
required

ID of the account to update.

Body Params

stripe_customer_id
string

Stripe customer ID to bill for billable services.

 
Suggest Edits

/2016-07/user

Get information about the user authenticated by the provided access token.

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.compose.io/2016-07/user
curl -X GET -H "Authorization: Bearer [[app:Authorization]]" -H "Content-Type: application/json" 'https://api.compose.io/2016-07/user'
A binary file was returned

You couldn't be authenticated

{"id":"57acab4c0b2fa983373f498c","name":"Garnett Ritchie"}
 
Suggest Edits

/2016-07/deployments/:id/versions

Returns the possible version transitions for the provided deployment.

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.compose.io/2016-07/deployments/id/versions
curl -X GET 'https://api.compose.io/2016-07/deployments/5821fd28a4b549d06e39886f/versions'
-H "Authorization: Bearer [[app:Authorization]]"
-H "Content-Type: application/json; charset=utf-8"
A binary file was returned

You couldn't be authenticated

{
  "_embedded": {
    "transitions": [
      {
        "application": "mongodb",
        "method": "in_place",
        "from_version": "3.2.8",
        "to_version": "3.2.10"
      }
    ]
  }
}

Path Params

id
string
required

The ID of the deployment for which the versions should be listed.

 

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.

Returned JSON

`transitions` object key
Description

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.

Suggest Edits

/2016-07/datacenters

Returns the currently available datacenters in the Compose platform.

 
gethttps://api.compose.io/2016-07/datacenters
curl -X GET -H "Content-Type: application/json" 'https://api.compose.io/2016-07/datacenters'
A binary file was returned

You couldn't be authenticated

{
  "_embedded": {
    "datacenters": [
      {
        "region": "dallas-9",
        "provider": "softlayer",
        "slug": "softlayer:dallas-9"
      },
      {
        "region": "sydney-1",
        "provider": "softlayer",
        "slug": "softlayer:sydney-1"
      },
      {
        "region": "ap-southeast-1",
        "provider": "aws",
        "slug": "aws:ap-southeast-1"
      },
      {
        "region": "europe-west1",
        "provider": "gce",
        "slug": "gce:europe-west1"
      },
      {
        "region": "eu-central-1",
        "provider": "aws",
        "slug": "aws:eu-central-1"
      },
      {
        "region": "london-02",
        "provider": "softlayer",
        "slug": "softlayer:london-02"
      },
      {
        "region": "us-east1",
        "provider": "gce",
        "slug": "gce:us-east1"
      },
      {
        "region": "us-west-2",
        "provider": "aws",
        "slug": "aws:us-west-2"
      },
      {
        "region": "us-east-1",
        "provider": "aws",
        "slug": "aws:us-east-1"
      },
      {
        "region": "eu-west-1",
        "provider": "aws",
        "slug": "aws:eu-west-1"
      }
    ]
  }
}
 

Returned JSON

`datacenters` object key
Description

region

Where in the world is this datacenter?

provider

What company is managing this datacenter?

slug

The identifier for the datacenter that is accepted by the deployment creation endpoint.

Suggest Edits

/2016-07/deployments/:id

Fetch information about a specific deployment accessible to your user.

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.compose.io/2016-07/deployments/id
curl -X GET -H "Authorization: Bearer [[app:Authorization]]" -H "Content-Type: application/json" "https://api.compose.io/2016-07/deployments/570bcb3fee4cde000e000002"
A binary file was returned

You couldn't be authenticated

{
  "id":"5854017e89d50f424e000192",
  "account_id":"5854017d89d50f424e000002",
  "name":"fizz-production",
  "type":"postgresql",
  "created_at":"2016-12-16T15:00:14.922Z",
  "notes":"the production fizz db",
  "customer_billing_code":"bill-to-fizz",
  "version":"9.6.3",
  "connection_strings": {
    "direct": ["postgres://compose:XXXX@customer-cluster.1.compose.direct:10020/compose"],
    "cli": ["psql \"sslmode=require host=cpu.blazzleblazzle.compose.direct port=10000 dbname=compose user=compose\""],
    "maps": null,
    "ssh": null,
    "health": null,
    "admin": null
  },
  "_links": {
    "compose_web_ui": {
      "href":"https://app.compose.io/northwind/deployments/fizz-production{?embed}",
      "templated":true
    }
  }
}

Path Params

id
string
required

The ID of the deployment you wish to fetch

 

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.

Returned JSON

Key
Description

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.

Returned Links

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

Link
Description

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.

Suggest Edits

/2016-07/deployments/:id/scalings

Get scaling information about your deployment

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.compose.io/2016-07/deployments/id/scalings
curl -X GET -H "Authorization: Bearer [[app:Authorization]]" -H "Content-Type: application/json" 'https://api.compose.io/2016-07/deployments/570bcb3fee4cde000e000002/scalings'
A binary file was returned

You couldn't be authenticated

{
  "allocated_units": 2,
  "used_units": 1,
  "starting_units": 1,
  "minimum_units": 1,
  "unit_size_in_mb": 1024
}

Path Params

id
string
required

The ID of the deployment for which the scalings should be listed.

 

Will respond with the deployment's Scaling information.

Key
Description

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.

Suggest Edits

/2016-07/deployments/:id/scalings

Scale your deployment

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.compose.io/2016-07/deployments/id/scalings
curl -X POST 'https://api.compose.io/2016-07/deployments/52a50cb96230650018000000/scalings'
-H "Authorization: Bearer [[app:Authorization]]"
-H "Content-Type: application/json; charset=utf-8" \
-d '{
  "deployment": {
    "units": 5
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "570bcb3fee4cde000e000002",
 	"account_id": "586eab527c65836dde5533e8",
 	"template": "Recipes::Deployment::Run",
  "status": "complete",
  "status_detail": "All operations have completed successfully!",
 	"created_at": "2017-01-05T15:23:46.853-05:00",
 	"updated_at": "2017-01-05T15:23:46.853-05:00",
 	"deployment_id": "586eab527c65836dde5533ea",
 	"name": "Scale deployment to 5 units",
 	"_embedded": {
  	"recipes": []
	}
}

Path Params

id
string
required

The ID of the deployment to scale

Body Params

deployment
object
 
deployment.units
int32

The number of units to scale your deployment to

 

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.

Suggest Edits

/2016-07/deployments/:id/versions

Upgrades a deployment's software to a newer version.

 

Header Auth

 Authentication is required for this endpoint.
patchhttps://api.compose.io/2016-07/deployments/id/versions
curl -X PATCH 'https://api.compose.io/2016-07/deployments/586f8851a4b54946c901f2b5/versions'
-H "Authorization: Bearer [[app:Authorization]]"
-H "Content-Type: application/json; charset=utf-8" \
-d '{
  "deployment": {
    "version": "3.2.6"
  }
}'
A binary file was returned

You couldn't be authenticated

{
  "id": "586f8851a4b54946c901f2b7",
  "account_id": "586f8851a4b54946c901f2b2",
  "template": "Recipes::Deployment::Run",
  "status": "running",
  "status_detail": "Running post_reparent_capsule on redis1115.sl-us-dal-9-utility.4.",
  "created_at": "2017-01-06T12:13:47Z",
  "updated_at": "2017-01-06T12:13:49Z",
  "deployment_id": "586f8851a4b54946c901f2b5",
  "name": "Redis::Version::Change",
  "_embedded": {
    "recipes": []
  }
}

Path Params

id
string
required

The ID of the deployment to be upgraded.

Body Params

deployment
object
 
deployment.version
string

The target version to which the deployment should transition. Use the GET variation of this endpoint for a list of possible target versions for the deployment.

 
Key
Description

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.

Suggest Edits

/2016-07/deployments/:deployment_id/backups

Fetch information about all the backups available for a deployment.

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.compose.io/2016-07/deployments/deployment_id/backups
curl -X GET -H "Authorization: Bearer [[app:Authorization]]" -H "Content-Type: application/json" "https://api.compose.io/2016-07/deployments/5854017d89d50f424e00002c/backups"
A binary file was returned

You couldn't be authenticated

{
  "_embedded": {
    "backups": [{
      "id":"5854018289d50f424e00030b",
      "deployment_id":"5854017d89d50f424e00002c",
      "name":"test-deployment-2_2017-01-10_19-41-12_utc_daily",
      "type":"daily",
      "status":"complete",
      "is_downloadable": true
    },
    {
      "id":"5854018289d50f424e00030c",
      "deployment_id":"5854017d89d50f424e00002c",
      "name":"test-deployment-2_2017-01-11_19-41-12_utc_daily",
      "type":"daily",
      "status":"complete",
      "is_downloadable": true
    },
    {
      "id":"5854018289d50f424e00030d",
      "deployment_id":"5854017d89d50f424e00002c",
      "name":"test-deployment-2_2017-01-12_19-41-37_utc_daily",
      "type":"daily",
      "status":"complete",
      "is_downloadable": true
    }]
  }
}

Path Params

deployment_id
string
required

The ID of the deployment whose backups you want to fetch.

 

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.

Returned JSON

`backups` object key
Description

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.

Suggest Edits

/2016-07/deployments/:deployment_id/backups

Create an on-demand backup for a deployment.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.compose.io/2016-07/deployments/deployment_id/backups
curl -X POST -H "Authorization: Bearer [[app:Authorization]]" -H "Content-Type: application/json" "https://api.compose.io/2016-07/deployments/5854017d89d50f424e00002c/backups"
A binary file was returned

You couldn't be authenticated

{
  "id":"578e8a825475c70010230008",
  "account_id":"52a50cb96230650018000000",
  "template":"Recipes::Deployment::Run",
  "status":"running",
  "status_detail":"Running backup_on_demand on aws-us-east-1-data.11.",
  "created_at":"2017-01-17T21:24:18Z",
  "updated_at":"2017-01-17T21:24:18Z",
  "deployment_id":"5854017d89d50f424e00002c",
  "name":"Backup",
  "_embedded":{
    "recipes":[]
  }
}

Path Params

deployment_id
string
required

The ID of the deployment you wish to backup

 

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.

Suggest Edits

/2016-07/deployments/:deployment_id/backups/:backup_id

Fetch information for a specific backup.

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.compose.io/2016-07/deployments/deployment_id/backups/backup_id
curl -X GET -H "Authorization: Bearer [[app:Authorization]]" -H "Content-Type: application/json" "https://api.compose.io/2016-07/deployments/5854017d89d50f424e00002c/backups/5854018289d50f424e00030b"
A binary file was returned

You couldn't be authenticated

{
  "id":"5854018289d50f424e00030b",
  "deployment_id":"5854017d89d50f424e00002c",
  "name":"test-deployment-2_2017-01-16_17-49-32_utc_daily",
  "type":"daily",
  "status":"complete",
  "is_downloadable": true,
  "download_link":"https://dblayer-backups-postgresql.s3.amazonaws.com/Northwind/5854017d89d50f424e00002c/test-deployment-1_2017-01-16_17-49-32_utc_daily.tar.gz?X-Amz-Algorithm=AWS4-HMAC-SHA256\u0026X-Amz-Credential=AKIAIWSH7U3PEG5COCFA%2F20170117%2Fus-east-1%2Fs3%2Faws4_request\u0026X-Amz-Date=20170117T195036Z\u0026X-Amz-Expires=86400\u0026X-Amz-SignedHeaders=host\u0026X-Amz-Signature=aeea198b9a00422ef5c08de779890509ad260a4455ef23fc6a9a53cdc3681b905"
}

Path Params

deployment_id
string
required

The ID of the deployment which the backup belongs to.

backup_id
string
required

The ID of the backup you want to fetch.

 

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:

Returned JSON

Key
Value

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.

Suggest Edits

/2016-07/deployments/:deployment_id/backups/:backup_id/restore

Restores a deployment's backup to a new deployment.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.compose.io/2016-07/deployments/deployment_id/backups/backup_id/restore
curl -X POST 'https://api.compose.io/2016-07/deployments/586ff2c977419d001c000003/backups/587e73bb237d54266b000752/restore' \
-H "Authorization: Bearer [[app:Authorization]]" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{
  "deployment": {
    "name": "test-deployment-2-restored",
    "datacenter": "aws:us-east-1"
  }
}'
A binary file was returned

You couldn't be authenticated

{
  "id":"5821fd28a4b549d06e0473e",
  "account_id":"52a50cb96230650018000000",
  "name":"test-deployment-2-restored",
  "type":"postgresql",
  "created_at":"2017-01-18T18:32:24Z",
  "connection_strings":{
    "direct":["postgres://compose:XXXXXX@aws-us-east-1-portal.11.dblayer.com:12345/compose"],
    "cli":["psql \"sslmode=require host=aws-us-east-1-portal.11.dblayer.com port=10000 dbname=compose user=compose\""],
    "maps":null,
    "ssh":null,
    "health":null,
    "admin":null
  },
  "provision_recipe_id":"578af4b85fa6c70040000038",
 "ca_certificate_base64":"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURZVENDQWttZ0F3SUJBZ0lFV0grMHV6QU5CZ2txaGtpRzl3MEJBUTBGQURBeU1UQXdMZ1lEVlFRRERDZGsKWVhScWQzVXRZalZrWVRRek1HWmhNREE0TnpOall6a3dZbVZoTWpjMU0yWTVaR0prTWprd0hoY05NVGN3TVRFNApNVGd6TWpJM1doY05NemN3TVRFNE1UZ3dNREF3V2pBeU1UQXdMZ1lEVlFRRERDZGtZWFJxZDNVdFlqVmtZVFF6Ck1HWmhNREE0TnpOall6a3dZbVZoTWpjMU0yWTVaR0prTWprd2dnRWlNQTBHQ1NxR1NJYjNEUUVCQVFVQUE0SUIKRHdBd2dnRUtBb0lCQVFEa3g3bTBPUG93eXk1bktWaUdvRWlDb1E5a3daalBGb0QxVGQzMmNXSnU2L0l3V3dLKwpQN0dhSis4UVBDY25nNWQ4Q1hLVDdQWHdXT0VYMkJyVXhCbXhaQXpHemlRSWFsWm0zWndNdDcvUmg0L1RBVGQrCnM2QXgxSC9icENzd2hyV1U5Q2ptZ2tLcWgrUHdtYkRnUTRsclR2em5hRlZBMjhIak9VSVhxMllmcERUd0l6SisKeDVKMW9JVDZmaUhteDBFSkJkVG1UMEZqWUZ4Yk94dk12S0JKck5vNGZFNlhpSklvSmRGQ0g2K3hvTWZjbktWYwowV2x1MFBBVFBRRHgva2hoejFReUdBMloyeFJ5MGNSTHYza0VzSXAvSDdyWFhPY3lvNFo1dk1yeWpNSEVURGVXCnRWZjJ6UTFQTzF3bkM1M0tBTmdicGprK29GUXFSNFErU291WkFnTUJBQUdqZnpCOU1CMEdBMVVkRGdRV0JCU1MKS1RFZ3I5UE1SYlZsWHEzM1ZkZDFGamtqdXpBT0JnTlZIUThCQWY4RUJBTUNBZ1F3SFFZRFZSMGxCQll3RkFZSQpLd1lCQlFVSEF3RUdDQ3NHQVFVRkJ3TUNNQXdHQTFVZEV3UUZNQU1CQWY4d0h3WURWUjBqQkJnd0ZvQVVraWt4CklLL1R6RVcxWlY2dDkxWFhkUlk1STezd2QQWUpLb1pJaHZjTkFRRU5CUUFEZ2dFQkFCY0doMlFvNGpmbEs2Y3YKZGZ6allqL1hudU1nMjJuc05WaVFmbERsc1RqSEVTOGJ1L1c0TW4rWUoxekw0NUUzOGRTOFQ3ajhsQ08vY2JuYgoyZitIZGcvU3VxUU9oT3BLaXRBUzNRZWxsVlF3NHJQaklKcTlEMjFCandhOXpzMkZrUjI2N3kzVWVYaDRyRHBQCk51TjBNMyt4QWVzb3EzcXlINTlSZ1Fpb1loeEErajVUZy9naXBSSGxxbG1LbFE1WFZkWXc5K0RpU2lHc2ZyWWEKcFhjdXpXV1IzYmpoK3Y3Z1FoSGFIejNSTnB1WStVTU1aZmhLZENsSlMycDNZZ1RiOVE2QmlvMHcwS2F6VXU3UQpJSjN3dVRQQ25FS2JiQUVVN21PVWV6V2plM0tubVhDRHJHWVpVRjJybWJ3eHdPNjZsUUZpVnJrYU5LR0x4emxtCkV4SFRKNWM9Ci0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K",
  "_links":{
    "compose_web_ui":{
      "href":"https://app.compose.io/Northwind/deployments/test-deployment-2-restored{?embed}",
      "templated":true
    }
  }
}

Path Params

deployment_id
string
required

The ID of the deployment that the backup belongs to

backup_id
string
required

The ID of the backup you wish to restore

Body Params

deployment
object
 
deployment.name
string
required

The name of the new deployment (must be unique per account)

deployment.cluster_id
string

Enterprise cluster on the account to provision to (optional, leave blank for Compose Hosted)

deployment.datacenter
string

Datacenter to use for Compose Hosted (this parameter is ignored if cluster_id is specified): aws:us-east-1, aws:eu-west-1, softlayer:london-02, softlayer:dallas-09

deployment.version
string

Version of the software to deploy (optional)

deployment.ssl
string

Whether SSL should be enabled (if applicable to the 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.

Suggest Edits

/2016-07/deployments/:id/alerts

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.compose.io/2016-07/deployments/id/alerts
curl -X GET -H "Authorization: Bearer [[app:Authorization]]" -H "Content-Type: application/json" "https://api.compose.io/2016-07/deployments/5883e82d6983e7001900001e/alerts"
A binary file was returned

You couldn't be authenticated

{
    "summary": "critical",
    "_embedded": {
        "alerts": [
            {
                "capsule_id": "5883e82ed968860010004083",
                "deployment_id": "5883e82d6983e7001900001e",
                "message": "2 of 3 sentinels are subscribed",
                "name": "redis112-redis_sentinel_subscription_check",
                "status": "critical"
            },
            {
                "capsule_id": "5883e82ed968860010004085",
                "deployment_id": "5883e82d6983e7001900001e",
                "message": "Slaves master_link_status is DOWN.",
                "name": "redis72-redis_master_link_check",
                "status": "critical"
            },
            {
                "capsule_id": "5883e82ed968860010004085",
                "deployment_id": "5883e82d6983e7001900001e",
                "message": "1 of 3 sentinels are subscribed",
                "name": "redis72-redis_sentinel_subscription_check",
                "status": "critical"
            }
        ]
    }
}

Path Params

id
string
required

The ID of the deployment you wish to check the alerts of

 

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.

Returned JSON

Key
Description

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.

Suggest Edits

/2016-07/deployments/:id

Update the deployment information for the deployment with the provided ID.

 

Header Auth

 Authentication is required for this endpoint.
patchhttps://api.compose.io/2016-07/deployments/id
curl -X PATCH 'https://api.compose.io/2016-07/deployments/52a50cb96230650018000000'
-H "Authorization: Bearer [[app:Authorization]]"
-H "Content-Type: application/json; charset=utf-8" \
-d '{
  "deployment": {
    "notes": "My updated notes",
    "customer_billing_code": "My customer billing code"
  }
}'
A binary file was returned

You couldn't be authenticated

{
  "id": "52a50cb96230650018000000", 
  "account_id": "593ebaf6e138230f9b202a7c", 
  "name": "carlie-schaefer", 
  "type": "postgresql", 
  "created_at": "2017-06-12T16:02:00.523Z", 
  "notes": "My updated notes", 
  "customer_billing_code": "My customer billing code", 
  "_links": {
    "compose_web_ui": {
      "href"=>"https://app.compose.io/shanel-larson/deployments/carlie-schaefer{?embed}",
      "templated": true
    },
    "scalings": {
      "href": "https://app.compose.io/2016-07/deployments/593ebaf8e138230f9b202a7e/scalings{?embed}", 
      "templated": true
    },
    "backups": {
      "href": "https://app.compose.io/2016-07/deployments/593ebaf8e138230f9b202a7e/backups{?embed}",
      "templated": true
    },
    "alerts": {
      "href"=>"https://app.compose.io/2016-07/deployments/593ebaf8e138230f9b202a7e/alerts{?embed}",
      "templated": true
    },
    "cluster": {
      "href"=>"https://app.compose.io/2016-07/clusters/593ebaf8e138230f9b202a87{?embed}",
      "templated": true
    }
  }
}

Path Params

id
string
required

ID of the deployment to update.

Body Params

notes
string

Notes field for the deployment

customer_billing_code
string

Customer billing code for the deployment

 
Suggest Edits

/2016-07/deployments/:deployment_id/team_roles

List Team Roles for Deployment

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.compose.io/2016-07/deployments/deployment_id/team_roles
curl -X GET 'https://api.compose.io/2016-07/deployments/{deployment_id}/team_roles' \
-H "Authorization: Bearer [[app:Authorization]" \
-H "Content-Type: application/json"
A binary file was returned

You couldn't be authenticated

{  
   "_embedded":{  
      "team_roles":[  
         {  
            "name":"developer",
            "teams":[  
               {  
                  "id":"581220995e145a0eba00000a",
                  "name":"cool developers"
               }
            ]
         }
      ]
   }
}

Path Params

deployment_id
string
required

ID of the deployment whose team roles you want returned.

 

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

Returned JSON

The endpoint returns a list of team roles for a deployment with the following fields.

Key
Description

name

The name associated with the role

teams

List of teams currently assigned to this role

Suggest Edits

/2016-07/deployments/:deployment_id/team_roles

Assign Team Roles for Deployment

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.compose.io/2016-07/deployments/deployment_id/team_roles
curl -X POST 'https://api.compose.io/2016-07/deployments/{deployment_id}/team_roles' \
-H "Authorization: Bearer [[app:Authorization]]" \
-H "Content-Type: application/json" \
-d '
{
  "team_role": {
    "name"   : "developer",
    "team_id" :"581220995e145a0eba00000a"
  }
}
'
A binary file was returned

You couldn't be authenticated

{  
   "name":"developer",
   "teams":[  
      {  
         "id":"581220995e145a0eba00000a",
         "name":"cool developers"
      }
   ]
}

Path Params

deployment_id
string
required

ID of the deployment to add a team role to

Body Params

team_role
object
 
team_role.name
string

The name of the role. The available roles are "developer", "manager", and "admin"

team_role.team_id
string

the ID of the team to be assigned to the specified role

 

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.

Roles

Role
Description

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.

Returned JSON

The endpoint returns the assigned team role with the following fields.

Key
Description

name

The name associated with the role

teams

List of teams currently assigned to this role

Suggest Edits

/2016-07/deployments/:deployment_id/team_roles

Remove Team Roles for Deployment

 

Header Auth

 Authentication is required for this endpoint.
deletehttps://api.compose.io/2016-07/deployments/deployment_id/team_roles
curl -X DELETE 'https://api.compose.io/2016-07/deployments/{deployment_id}/team_roles' \
-H "Authorization: Bearer [[app:Authorization]]" \
-H "Content-Type: application/json" \
-d '
{
  "team_role": {
    "name"   : "developer",
    "team_id" :"581220995e145a0eba00000a"
  }
}
'
A binary file was returned

You couldn't be authenticated

Try the API to see results

Path Params

deployment_id
string
required

ID of the deployment whose team role you want to delete.

Body Params

team_role
object
 
team_role.name
string

The name of the role. The available roles are "developer", "manager", and "admin"

team_role.team_id
string

The ID of the team to be unassigned to the specified role

 

This endpoint will remove a team from the specified role.

Suggest Edits

/2016-07/deployments/:deployment_id/roles

Assign User Roles for Deployment

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.compose.io/2016-07/deployments/deployment_id/team_roles
curl -X POST 'https://api.compose.io/2016-07/deployments/{deployment_id}/roles' \
-H "Authorization: Bearer [[app:Authorization]]" \
-H "Content-Type: application/json; charset=utf-8" \
-d ' 
{
  "role": {
    "name"   : "developer",
    "user_id" :"58b9c5c41d36944452000013"
  }
}
'
A binary file was returned

You couldn't be authenticated

{  
   "name":"developer",
   "users":[  
      {  
         "id":"58b9c5c41d36944452000013",
         "name":"cool developer"
      }
   ]
}

Path Params

deployment_id
string
required

ID of the deployment to add a team role to

Body Params

role
object
 
role.name
string

The name of the role. The available roles are "developer", "manager", and "admin"

role.user_id
string

the ID of the user to be assigned to the specified role

 

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

Roles

Role
Description

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.

Returned JSON

The endpoint returns the assigned role with the following fields.

Key
Description

name

The name associated with the role

users

List of users currently assigned to this role

Suggest Edits

/2016-07/deployments/:deployment_id/roles

List User Roles for Deployment

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.compose.io/2016-07/deployments/deployment_id/roles
curl -X GET 'https://api.compose.io/2016-07/deployments/{deployment_id}/roles' \
-H "Authorization: Bearer [[app:Authorization]" \
-H "Content-Type: application/json"
A binary file was returned

You couldn't be authenticated

{
  "_embedded": {
    "roles": [
      {
        "name": "admin",
        "users": [
          {
            "id": "5967a2598aeea9eb87d39d45",
            "name": "Database Lover"
          }
        ]
      }
    ]
  }
}

Path Params

deployment_id
string
required

ID of the deployment whose team roles you want returned.

 

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

Returned JSON

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

Suggest Edits

/2016-07/deployments/:deployment_id/roles

Remove User Roles for Deployment

 

Header Auth

 Authentication is required for this endpoint.
deletehttps://api.compose.io/2016-07/deployments/deployment_id/roles
curl -X DELETE 'https://api.compose.io/2016-07/deployments/{deployment_id}/roles' \
-H "Authorization: Bearer [[app:Authorization]]" \
-H "Content-Type: application/json" \
-d '
{
  "role": {
    "name"   : "developer",
    "user_id" :"581220995e145a0eba00000a"
  }
}
'
A binary file was returned

You couldn't be authenticated

Try the API to see results

Path Params

deployment_id
string
required

ID of the deployment whose team role you want to delete.

Body Params

role
object
 
role.name
string

The name of the role. The available roles are "developer", "manager", and "admin"

role.user_id
string

the ID of the user to be unassigned to the specified role

 

This endpoint will remove a user from the specified role.

Suggest Edits

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.

Suggest Edits

/2016-07/users

Registration. Create a brand new user (and account).

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.compose.io/2016-07/users
curl -X POST https://api.compose.io/2016-07/users
-H "Content-Type: application/json; charset=utf-8" \
-d '{
  "user": {
    "name": "George Costanza",
    "email": "george@seinfeldt.org",
    "password": "bosco4ever",
    "account_name": "Festivus Observers"
  }
}'
A binary file was returned

You couldn't be authenticated

{
  "id": "57a36dc2a4b5495dd4458312",
  "name": "George Costanza",
  "_embedded": {
    "accounts": [{
      "id": "57a36dc2a4b5495dd4458313",
      "slug": "festivus-observers",
      "name": "Festivus Observers"
    }],
    "oauth_access_token": {
      "token": "7c4b5060c4bb6876e7af14b82aaedb9da5002d288285c4a732e3bd81ac924960"
    }
  }
}

Body Params

name
string

Full name of the user.

email
string

Email of the user.

password
string

Password for the user.

account_name
string

Company/account name.

Headers

X-OAuth-Client-ID
string

(optional) If you are a vendor of Compose services, you can provide your client ID & secret during registration to "claim" the account that is created. Vendors can perform certain extra operations on accounts under their control. If this doesn't look familiar to you, you probably have no use for these features and can ignore this header. Client IDs are currently provided by request only.

X-OAuth-Client-Secret
string

(optional) Provide along with X-OAuth-Client-ID (both are required for Vendor behavior)

 
Suggest Edits

/2016-07/refresh_tokens

Exchange a personal API token for an application-specific refresh token.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.compose.io/2016-07/refresh_tokens
curl -X POST 'https://api.compose.io/2016-07/refresh_tokens'
-H "Authorization: Bearer [[app:Authorization]]"
-H "Content-Type: application/json; charset=utf-8" \
-d '{
  "refresh_token": {
    "client_id": "251a23925f78fa35f35e49f34ad09ee7d9425857006060f515720eb83c58cc26",
    "client_secret": "c9eb665c72c1c2c8147d743efce0d52338c2bcf2e5b7095baa572ee70b7de8bd"
  }
}'
A binary file was returned

You couldn't be authenticated

{
  "token": "0ffeab878eba25d7f57605eb5bc401548b830c295bb7b14ef49c21337bb1a864",
  "refresh_token": "ae5662076e386cbcb0468e9231b0701fc254807929f3507ddaa059a000763ef0"
}

Body Params

client_id
string

The ID of the OAuth application that will be acting on behalf of the user.

client_secret
string

The secret key for the OAuth application that will be acting on behalf of the user.

 

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.

Suggest Edits

/2016-07/deployments/:id/disablements

Disables access to the deployment

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.compose.io/2016-07/deployments/:id/disablements
curl -X POST 'https://api.compose.io/2016-07/deployments/57f80f58a4b5498cce6712fb/disablements'
-H "Authorization: Bearer [[app:Authorization]]"
-H "Content-Type: application/json; charset=utf-8"
A binary file was returned

You couldn't be authenticated

{
  "id": "57f80f62a4b5498cce6712fd",
  "template": "Recipes::Deployment::Run",
  "status": "running",
  "status_detail": null,
  "account_id": "57f81008a4b5498cce6712ff",
  "created_at": "2016-12-27T20:35:32.733Z",
  "updated_at": "2016-12-27T20:40:44.087Z",
  "deployment_id": "57f80f58a4b5498cce6712fb",
  "name": "Disable",
  "_embedded": {
    "recipes": []
  }
}

Headers

X-OAuth-Client-ID
string

(optional) If you have a client OAuth ID, you can authenticate as a vendor to manage access to deployments owned by accounts registered under your vendor. You may omit the Authorization header if you provide a client header pair.

X-OAuth-Client-Secret
string

(optional) You must provide this if you are providing X-OAuth-Client-ID

 
Suggest Edits

/2016-07/deployments/:id/disablements

(Re-)enables access to the deployment

 

Header Auth

 Authentication is required for this endpoint.
deletehttps://api.compose.io/2016-07/deployments/:id/disablements
curl -X DELETE 'https://api.compose.io/2016-07/deployments/57f80f58a4b5498cce6712fb/disablements'
-H "Authorization: Bearer [[app:Authorization]]"
-H "Content-Type: application/json; charset=utf-8"
A binary file was returned

You couldn't be authenticated

{}{
  "id": "57f8100ea4b5498cce671300",
  "template": "Recipes::Deployment::Run",
  "status": "running",
  "status_detail": null,
  "account_id": "57f81008a4b5498cce6712ff",
  "created_at": "2016-12-27T20:35:32.733Z",
  "updated_at": "2016-12-27T20:40:44.087Z",
  "deployment_id": "57f80f58a4b5498cce6712fb",
  "name": "Enable",
  "_embedded": {
    "recipes": []
  }
}

Headers

X-OAuth-Client-ID
string

(optional) If you have a client OAuth ID, you can authenticate as a vendor to manage access to deployments owned by accounts registered under your vendor. You may omit the Authorization header if you provide a client header pair.

X-OAuth-Client-Secret
string

(optional) You must provide this if you are providing X-OAuth-Client-ID

 
Suggest Edits

/2016-07/billables

Get all the billable items associated with your user.

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.compose.io/2016-07/billables
curl -X GET -H "Authorization: Bearer [[app:Authorization]]" -H "Content-Type: application/json" 'https://api.compose.io/2016-07/billables'
A binary file was returned

You couldn't be authenticated

{
  "_embedded": {
    "billables": [
      {
        "id": "5719191eb248c197d5000001",
        "account_id": "5719181d4939cb0001000002",
        "amount": 12,
        "start_at": "2016-04-21T18:16:59+00:00",
        "end_at": "3012-02-28T00:00:00+00:00",
        "description": "postgresql member postgresql0: capsule 2 data unit(s)",
        "identifier": "capsule:5719191b0501490012000003",
        "resource_identifier": "host:5719190ea4b5492e270000ed",
        "sku": "capsule:data",
        "units": 2,
        "replaces_id": null
      },
      {
        "id": "5719191fb248c197d5000004",
        "account_id": "5719181d4939cb0001000002",
        "amount": 12,
        "start_at": "2016-04-21T18:17:02+00:00",
        "end_at": "3012-02-28T00:00:00+00:00",
        "description": "postgresql member postgresql0: capsule 2 data unit(s)",
        "identifier": "capsule:5719191e0501490012000004",
        "resource_identifier": "host:5719190ea4b5492e270000f3",
        "sku": "capsule:data",
        "units": 2,
        "replaces_id": null
      },
      {
        "id": "57191920b248c197d5000005",
        "account_id": "5719181d4939cb0001000002",
        "amount": 1,
        "start_at": "2016-04-21T18:17:03+00:00",
        "end_at": "3012-02-28T00:00:00+00:00",
        "description": "etcd arbiter etcd0: capsule 1 lightweight unit(s)",
        "identifier": "capsule:5719191f0501490012000005",
        "resource_identifier": "host:5719190ea4b5492e2700010b",
        "sku": "capsule:lightweight",
        "units": 1,
        "replaces_id": null
      },
      {
        "id": "57191921b248c197d5000006",
        "account_id": "5719181d4939cb0001000002",
        "amount": 4.5,
        "start_at": "2016-04-21T18:17:04+00:00",
        "end_at": "3012-02-28T00:00:00+00:00",
        "description": "haproxy proxy haproxy0: capsule 1 cpu unit(s)",
        "identifier": "capsule:571919200501490012000007",
        "resource_identifier": "host:5719190ea4b5492e27000150",
        "sku": "capsule:cpu",
        "units": 1,
        "replaces_id": null
      },
      {
        "id": "571919fcb248c197d5000007",
        "account_id": "5719181d4939cb0001000002",
        "amount": 12,
        "start_at": "2016-04-21T18:20:43+00:00",
        "end_at": "3012-02-28T00:00:00+00:00",
        "description": "postgresql member postgresql0: capsule 2 data unit(s)",
        "identifier": "capsule:571919fb050149000f000004",
        "resource_identifier": "host:5719190ea4b5492e270000bb",
        "sku": "capsule:data",
        "units": 2,
        "replaces_id": null
      },
      {
        "id": "571919fdb248c197d5000009",
        "account_id": "5719181d4939cb0001000002",
        "amount": 12,
        "start_at": "2016-04-21T18:20:44+00:00",
        "end_at": "3012-02-28T00:00:00+00:00",
        "description": "postgresql member postgresql0: capsule 2 data unit(s)",
        "identifier": "capsule:571919fc050149000f000005",
        "resource_identifier": "host:5719190ea4b5492e270000c1",
        "sku": "capsule:data",
        "units": 2,
        "replaces_id": null
      },
      {
        "id": "57191a00b248c197d500000a",
        "account_id": "5719181d4939cb0001000002",
        "amount": 1,
        "start_at": "2016-04-21T18:20:46+00:00",
        "end_at": "3012-02-28T00:00:00+00:00",
        "description": "etcd arbiter etcd0: capsule 1 lightweight unit(s)",
        "identifier": "capsule:571919fe050149000f000006",
        "resource_identifier": "host:5719190ea4b5492e27000064",
        "sku": "capsule:lightweight",
        "units": 1,
        "replaces_id": null
      },
      {
        "id": "57191a02b248c197d500000b",
        "account_id": "5719181d4939cb0001000002",
        "amount": 4.5,
        "start_at": "2016-04-21T18:20:49+00:00",
        "end_at": "3012-02-28T00:00:00+00:00",
        "description": "haproxy proxy haproxy0: capsule 1 cpu unit(s)",
        "identifier": "capsule:57191a01050149000f000008",
        "resource_identifier": "host:5719190ea4b5492e270000ff",
        "sku": "capsule:cpu",
        "units": 1,
        "replaces_id": null
      },
      {
        "id": "57191fa6b248c197d500000c",
        "account_id": "5719181d4939cb0001000002",
        "amount": 12,
        "start_at": "2016-04-21T18:44:53+00:00",
        "end_at": "3012-02-28T00:00:00+00:00",
        "description": "postgresql member postgresql0: capsule 2 data unit(s)",
        "identifier": "capsule:57191fa5050149000f000019",
        "resource_identifier": "host:5719190ea4b5492e27000084",
        "sku": "capsule:data",
        "units": 2,
        "replaces_id": null
      },
      {
        "id": "57191fa7b248c197d500000e",
        "account_id": "5719181d4939cb0001000002",
        "amount": 12,
        "start_at": "2016-04-21T18:44:54+00:00",
        "end_at": "3012-02-28T00:00:00+00:00",
        "description": "postgresql member postgresql0: capsule 2 data unit(s)",
        "identifier": "capsule:57191fa6050149000f00001a",
        "resource_identifier": "host:5719190ea4b5492e2700008a",
        "sku": "capsule:data",
        "units": 2,
        "replaces_id": null
      },
      {
        "id": "57191fa9b248c197d500000f",
        "account_id": "5719181d4939cb0001000002",
        "amount": 1,
        "start_at": "2016-04-21T18:44:56+00:00",
        "end_at": "3012-02-28T00:00:00+00:00",
        "description": "etcd arbiter etcd0: capsule 1 lightweight unit(s)",
        "identifier": "capsule:57191fa8050149000f00001b",
        "resource_identifier": "host:5719190ea4b5492e27000026",
        "sku": "capsule:lightweight",
        "units": 1,
        "replaces_id": null
      },
      {
        "id": "57191faab248c197d5000010",
        "account_id": "5719181d4939cb0001000002",
        "amount": 4.5,
        "start_at": "2016-04-21T18:44:57+00:00",
        "end_at": "3012-02-28T00:00:00+00:00",
        "description": "haproxy proxy haproxy0: capsule 1 cpu unit(s)",
        "identifier": "capsule:57191fa9050149000f00001d",
        "resource_identifier": "host:5719190ea4b5492e270000cd",
        "sku": "capsule:cpu",
        "units": 1,
        "replaces_id": null
      },
      {
        "id": "5719203bb248c197d5000011",
        "account_id": "5719181d4939cb0001000002",
        "amount": 12,
        "start_at": "2016-04-21T18:47:22+00:00",
        "end_at": "3012-02-28T00:00:00+00:00",
        "description": "postgresql member postgresql0: capsule 2 data unit(s)",
        "identifier": "capsule:5719203a0501490012000018",
        "resource_identifier": "host:5719190da4b5492e27000002",
        "sku": "capsule:data",
        "units": 2,
        "replaces_id": null
      },
      {
        "id": "5719203cb248c197d5000013",
        "account_id": "5719181d4939cb0001000002",
        "amount": 12,
        "start_at": "2016-04-21T18:47:23+00:00",
        "end_at": "3012-02-28T00:00:00+00:00",
        "description": "postgresql member postgresql0: capsule 2 data unit(s)",
        "identifier": "capsule:5719203b0501490012000019",
        "resource_identifier": "host:5719190da4b5492e27000008",
        "sku": "capsule:data",
        "units": 2,
        "replaces_id": null
      },
      {
        "id": "5719203db248c197d5000014",
        "account_id": "5719181d4939cb0001000002",
        "amount": 1,
        "start_at": "2016-04-21T18:47:24+00:00",
        "end_at": "3012-02-28T00:00:00+00:00",
        "description": "etcd arbiter etcd0: capsule 1 lightweight unit(s)",
        "identifier": "capsule:5719203c050149001200001a",
        "resource_identifier": "host:5719190ea4b5492e27000111",
        "sku": "capsule:lightweight",
        "units": 1,
        "replaces_id": null
      },
      {
        "id": "5719203fb248c197d5000015",
        "account_id": "5719181d4939cb0001000002",
        "amount": 4.5,
        "start_at": "2016-04-21T18:47:26+00:00",
        "end_at": "3012-02-28T00:00:00+00:00",
        "description": "haproxy proxy haproxy0: capsule 1 cpu unit(s)",
        "identifier": "capsule:5719203e050149001200001c",
        "resource_identifier": "host:5719190ea4b5492e27000096",
        "sku": "capsule:cpu",
        "units": 1,
        "replaces_id": null
      }
    ]
  }
}
 

The billables endpoint returns information about billable items related to an account. This includes all deployments and capsules that make up a deployment.

Returned JSON

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.

Key
Description

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.