Compose API

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

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "_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/accounts/:id/users

List users who are members of the provided account.

 

Header Auth

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

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "_embedded": {
    "users": [{
      "id": "58b4a6dda4b5493eb82df6f8",
      "name": "Marian Aufderhar"
    }, {
      "id": "58b4a6dea4b5493eb82df6fb",
      "name": "Garnett Ritchie"
    }]
  }
}

Path Params

id
string
required

ID of the account for which the users should be listed.

 
Suggest Edits

/2016-07/accounts/:account_id/users/

Create a new user associated with the account id

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.compose.io/2016-07/accounts/account_id/users
curl -X POST 'https://api.compose.io/2016-07/accounts/58c96de5eac0b97b3a000017/users' \
-H "Authorization: Bearer [[app:Authorization]]" \
-H "Content-Type: application/json; charset=utf-8" \
-d ' {
  "name": "Lawrence Waterhouse",
  "email": "lawrence@waterhouse.com",
  "phone": "613-555-0101"
}'
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "id":"38d52319cbf6db000f29aab1",
  "name":"Lawrence Waterhouse"
}

Path Params

account_id
string
required

The ID of the account you wish to add the user to.

Body Params

name
string
required

The user's name.

email
string
required

The user's email address.

phone
string

The user's phone number.

 

Creates a new user that is associated with the account specified. You can refer to the following links to learn more about Users and Accounts.

Suggest Edits

/2016-07/accounts/:account_id/users/:user_id

Deletes a user associated with the account id

 

Header Auth

 Authentication is required for this endpoint.
deletehttps://api.compose.io/2016-07/accounts/account_id/users/user_id
curl -X DELETE 'https://api.compose.io/2016-07/accounts/58c96de5eac0b97b3a000017/users/38d52319cbf6db000f29aab1'  \
-H "Authorization: Bearer [[app:Authorization]]" \
-H "Content-Type: application/json"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "id":"38d52319cbf6db000f29aab1",
  "name":"Lawrence Waterhouse"
}

Path Params

account_id
string
required

The ID of the account you wish to delete the user from.

user_id
string
required

The ID of the user you wish to delete.

 

Note: There is no undo for deleting a user.

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

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "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

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{"id":"57acab4c0b2fa983373f498c","name":"Garnett Ritchie"}
 
Suggest Edits

/2016-07/teams

List the teams on the account.

 

Header Auth

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

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{"_embedded": {
        "teams": [{
            "id"   : "587fa15eacef4ad9fb0002a2"
            "name" : "Dev Team",
            "users": [{
                "id"   : "587fa15eacef4ad9fb0002a4",
                "name" : "bob coolguy"
            },
            ...
            ]
        }]
      }}
 

Lists all the teams, with id and name, on the account. Each team's users will be listed with their id and name.

Suggest Edits

/2016-07/teams

Creates a new team.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.compose.io/2016-07/teams
curl -X POST 'https://api.compose.io/2016-07/teams' \
-H "Authorization: Bearer [[app:Authorization]]" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{    
  "team": {
      "name" : "Ops-Team"
    }
  }'
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{"id": "587fa15eacef4ad9fb0002a2",
 "name": "Ops-Team",
 "users":[]
}

Body Params

team
object
 
team.name
string

Name of 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.

Suggest Edits

/2016-07/teams/:team_id/users

Update the membership of a team.

 

Header Auth

 Authentication is required for this endpoint.
puthttps://api.compose.io/2016-07/teams/team_id/users
curl -X PUT 'https://api.compose.io/2016-07/teams/587fa15eacef4ad9fb0002a2/users' \
-H "Authorization: Bearer [[app:Authorization]]" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{    
  "user_ids": [
    "587fa15eacef4ad9fb0002a1"
    ]}'
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{"id":"587fa15eacef4ad9fb0002a2",
 "name":"Ops-Team",
 "users":[{
   "id":"587fa15eacef4ad9fb0002a1",
   "name":"Paul Smith"}]
}

Path Params

team_id
string
required

Specify the team being updated

Body Params

user_ids
array of strings

Specify the users who will be members of the 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.

Suggest Edits

/2016-07/teams/:team_id

Fetch information about a specific team.

 

Header Auth

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

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{"id"   : "587fa15eacef4ad9fb0002a2",
 "name" : "Ops-Team",
 "users": [{
   "id": "587fa15eacef4ad9fb0002a1",
   "name":  "Paul Smith"
 }]
}

Path Params

team_id
string
required

Specify the team

 

Returns team name and id. The users that are on the team will be listed with their id and name.

Suggest Edits

/2016-07/teams/:team_id

Update team with the provided id.

 

Header Auth

 Authentication is required for this endpoint.
patchhttps://api.compose.io/2016-07/teams/team_id
curl -X PATCH 'https://api.compose.io/2016-07/teams/587fa15eacef4ad9fb0002a2' \
-H "Authorization: Bearer [[app:Authorization]] " \
-H "Content-Type: application/json; charset=utf-8" \
-d '{    
  "team" : {
    "name": "Jazz-Team"
    }
  }'
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{"id"   : "587fa15eacef4ad9fb0002a2"
    "name" : "Jazz-Team",
    "users": [{
      "id": 587fa15eacef4ad9fb0002a1
    }]}

Path Params

team_id
string
required

Specify a team to update.

Body Params

team
object
 
team.name
string

Specify a new team name.

 

Renames a team with the specified team_id. Team users and permissions stay the same.

Suggest Edits

/2016-07/teams/:team_id

Delete a team.

 

Header Auth

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

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{"id":"587fa15eacef4ad9fb0002a2",
 "name":"Jazz-Team",
 "users":[
   {"id":"587fa15eacef4ad9fb0002a1","name":"Paul Smith"}
 ]
}

Path Params

team_id
string
required

Specify a team to be deleted.

 

Removes a team from the account. This only removes the team; the users will remain on the account.

Suggest Edits

/2016-07/audit_events

Retrieve all audit events to which your user has access.

 

Header Auth

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

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}

{
    "_embedded": {
        "audit_events": [
            {
                "_links": {
                    "self": {
                        "href": "/audit_events/5942f38d7af8b48386e5bde4{?embed}",
                        "templated": true
                    }
                },
                "account_id": "592883fa7af8b41cb85e86c7",
                "cluster_id": null,
                "created_at": "2017-06-15T20:52:29.883Z",
                "data": {},
                "deployment_id": null,
                "email": "elena.ferrante@compose.io",
                "event": "user.login",
                "id": "5942f38d7af8b48386e5bde4",
                "ip": "127.0.0.1",
                "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.86 Safari/537.36",
                "user_id": "592883ff7af8b41cb85e8984"
            }
        ]
    }
}

Query Params

older_than
date

Include only audit events older than the given date or date-time. The value should be specified in ISO-8601 format.

newer_than
date

Include only audit events newer than the given date or datetime. The value should be specified in ISO-8601 format.

cursor
string

Return results after audit event ID given for this value. This value is used instead of a page number for pagination. Your client should keep track of the ID of the last audit event seen in a given page, and then supply that ID for this value when requesting the next page. The next page of results will begin with the record immediately after the record specified by the cursor.

limit
int32

Include at most the given number of records. The default is 25 and maximum is 100.

 

Returned JSON

Key
Description

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.

email

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.

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

self

A URI for this audit event.

Suggest Edits

/2016-07/audit_events/:id

Fetch information about a specific audit event accessible to your user.

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.compose.io/2016-07/audit_events/:audit_event_id
curl --request GET \
  --url https://api.compose.io/2016-07/audit_events/:audit_event_id
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.compose.io/2016-07/audit_events/:audit_event_id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.compose.io/2016-07/audit_events/:audit_event_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.compose.io/2016-07/audit_events/:audit_event_id");

xhr.send(data);
import requests

url = "https://api.compose.io/2016-07/audit_events/:audit_event_id"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "_links": {
        "self": {
            "href": "https://api.compose.io/2016-07/audit_events/592885947af8b461d539ab11{?embed}",
            "templated": true
        }
    },
    "account_id": "592883fa7af8b41cb85e86c7",
    "cluster_id": null,
    "created_at": "2017-05-26T19:44:20.065Z",
    "data": {},
    "deployment_id": null,
    "email": "elena.ferrante@compose.io",
    "event": "user.login",
    "id": "592885947af8b461d539ab11",
    "ip": "127.0.0.1",
    "user_agent": "Mozilla/5.0 (X11; CrOS aarch64 9460.50.0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.71 Safari/537.36",
    "user_id": "592883ff7af8b41cb85e8984"
}

Path Params

id
string
required

The ID of the deployment you wish to fetch

 

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.

Returned JSON

Key
Description

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.

email

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.

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

self

A URI for this audit event.

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

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "_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/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

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "_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/recipes/:id

Get the details of a specific recipe.

 

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

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "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",
    "operations_complete": 14,
    "operations_total": 14,
    "deployment_id": "5821fd28a4b549d06e398869",
    "parent_id": "59a02a95fd58e80011000000",
    "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.

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

Recipe Operations

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.

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

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "_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

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "id": "59a6b3a5f32fb6001001ae6c",
  "account_id": "52a50cb96230650018000000",
  "name": "fizz-production",
  "type": "postgresql",
  "created_at": "2017-08-30T12:46:29Z",
  "notes": "",
  "customer_billing_code": "",
  "cluster_id": "57ade1d70b2fa9ce1c7e6162",
  "ca_certificate_base64": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURaekNDQWsrZ0F3SUJBZ0lFV2FhenFqQU5CZ2txaGtpRzl3MEJBUTBGQURBMU1UTXdNUVlEVlFRRERDcGoKYjIxd2IzTjFjbVV0TlRNNFl6ZzVZelV6WkdFMU9UVXdOamxrTmpJM016Rm1OamN4TmpNMk1EVXdIaGNOTVRjdwpPRE13TVRJME5qTTBXaGNOTXpjd09ETXdNVEl3TURBd1dqQTFNVE13TVFZRFZRUUREQ3BqYjIxd2IzTjFjbVV0Ck5UTTRZemc1WXpVelpHRTFPVFV3Tmpsa05qSTNNekZtTmpjeE5qTTJNRFV3Z2dFaU1BMEdDU3FHU0liM0RRRUIKQVFVQUE0SUJEd0F3Z2dFS0FvSUJBUUN2YUxVZVVKVkI1VXZpeS9FUFlZKzVZUHI5TjVUT3VoVTZKdXYyaGlVNQpKc3BVeG10Z1BVdXloWU9LY29vMzFZZXRjQ3RRaWVCNE5HUnp0eE5vUmdmVlpkbHFaSmdqRHBiSFNXYW9YM1NKCkhDV2lFbExleUg2cnk0cG5McEd0QnpaWTBNMlBYOXpBbnhFbkI4em1RT1hhSjB4MUR0SmxhS2lMOVBrRW5WengKcjQ5OHRRSFpIVms1OStCcGxXNFQrK2FrblA3bzNOUFVTMTRYaEZVRFFFdzdvVVJmdFpwcFB1YklFZVNJd1pXTQpzSC9jTVRJQzRkWGRsZTFvOEhNeEpqemtKOXJDNCtaK1dQUi9mWnVxL0EwSFVwUUl5S1o5WFFmcElhVjRzVk9pCnZjaDJNUHVRWDRhTDhHY3FvdlVmbnRFU0tkdW9XQmFVcmRGQ1dXZUhROFRQQWdNQkFBR2pmekI5TUIwR0ExVWQKRGdRV0JCVEdsdjdHaE9SbGtnQzJVTlRUcFBQeTZ2NGR0VEFPQmdOVkhROEJBZjhFQkFNQ0FnUXdIUVlEVlIwbApCQll3RkFZSUt3WUJCUVVIQXdFR0NDc0dBUVVGQndNQ01Bd0dBMVVkRXdRRk1BTUJBZjh3SHdZRFZSMGpCQmd3CkZvQVV4cGIreG9Ua1paSUF0bERVMDZUejh1citIYlV3RFFZSktvWklodmNOQVFFTkJRQURnZ0VCQUptMlRXdmIKTVZPdFZONTRjdnhFTnJTVW41RHQ0OHo2V25RQWxveGlsSUtiaG0wUU56NDlhWHVmVXh6ZTloWEJ0VkhPQllYTwpKWGlla1hSOUxEajE1eDZ6NjJDZ0RFWlkwSU5yY0RKUjYxVTAyY3l1bjc3QXQ5c0ZycVFvL1hmeWt2T3Z0d29pCi9TcDgrTU5hQVZ4THRaWFQ1N1hhWUo3ZDdyQWw1a2pEaWxRaDhQb2xJd2JoZjNwM042YXVOV0lTdlY0SGF4NDQKS1dHd2FoMTREQzhRSENzNWoydlJkUkpobERYS1IyRTQ5VDI2RWdyZStLbzdTMGp1ek0rcjZ0MEFLZFFoMytFVgpLK0Q0SHlsZmNZbXNWeTRINE9BaEJLbjU3M0VXZnNOY0VPYXoySFN2SXRaOXJzY0ZqdFYyWWpaVXlGa3MyNmUwCnlKaEdqa0lySWhNTnF4RT0KLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo=",
  "connection_strings": {
    "direct": [
      "postgres://admin:XXXXX@aws-eu-west-1-portal.8.dblayer.com:17000/compose",
      "postgres://admin:XXXXX@aws-eu-west-1-portal.9.dblayer.com:17000/compose"
    ],
    "cli": [
      "psql \"sslmode=require host=aws-eu-west-1-portal.8.dblayer.com port=17000 dbname=compose user=admin\"",
      "psql \"sslmode=require host=aws-eu-west-1-portal.9.dblayer.com port=17000 dbname=compose user=admin\""
    ],
    "maps": [],
    "misc": {},
    "ssh": [],
    "health": [],
    "admin": []
  },
  "version": "9.6.3",
  "provision_recipe_id": "59a6b3a5f32fb6001001ae6b",
  "_links": {
    "compose_web_ui": {
      "href": "https://app.compose.io/compose-3/deployments/fizz-production{?embed}",
      "templated": true
    },
    "scalings": {
      "href": "https://api.compose.io/2016-07/deployments/59a6b3a5f32fb6001001ae6c/scalings{?embed}",
      "templated": true
    },
    "backups": {
      "href": "https://api.compose.io/2016-07/deployments/59a6b3a5f32fb6001001ae6c/backups{?embed}",
      "templated": true
    },
    "alerts": {
      "href": "https://api.compose.io/2016-07/deployments/59a6b3a5f32fb6001001ae6c/alerts{?embed}",
      "templated": true
    },
    "cluster": {
      "href": "https://api.compose.io/2016-07/clusters/57ade1d70b2fa9ce1c7e6162{?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.cache_mode
boolean

Whether to optimize the deployment to be used as a cache (Redis only)

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)

deployment.provisioning_tags
array of strings

Cluster tags to target when provisioning. (optional, leave blank if providing cluster_id or datacenter)

 

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.

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.

cluster_id

The id of the cluster that this deployment is deployed on.

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/: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

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "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",
  "cluster_id": "59a6a6238a681830479c80f8",
  "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": [],
    "ssh": [],
    "health": [],
    "admin": []
  },
  "_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.

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.

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

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

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "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/: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

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "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/deployments/: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

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
 "_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",
       "operations_complete": 14,
       "operations_total": 14,
       "deployment_id": "52a50cb96230650018000000",
       "parent_id": "59a02a95fd58e80011000000",
       "_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/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

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "_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/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

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "allocated_units": 2,
  "used_units": 1,
  "starting_units": 1,
  "minimum_units": 1,
  "unit_size_in_mb": 1024,
  "unit_type": "memory"
}

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.

unit_type

The type of unit. Either memory (RAM) or data (disk storage).

Note: The unit_type field is a hint 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. This field is only of interest to developers implementing consoles that replicate Compose functionality.

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

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "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

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "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/: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

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "_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/: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

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "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/: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

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "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/: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

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "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/:id.

Note: for the body parameters, either cluster_id or datacenter is required.

Suggest Edits

/2016-07/deployments/:id/alerts

Returns current alerts for a specific deployment.

 

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

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "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/addons

List addons available for a given deployment

 

Header Auth

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

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "_embedded": {
    "addons": [{
      "name": "syslog"
    }]
  }
}

Path Params

id
string
required

ID of the deployment

 

This endpoint returns a list of addons available for a deployment. The key/values are detailed below:

Returned JSON

Key
Value

addons

List of available addons. If no addons are available, this will return an empty list.

name

Name of addon.

Suggest Edits

/2016-07/deployments/: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

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{  
   "_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/: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

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{  
   "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/: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

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
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/: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

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "_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 currently assigned to this role

Suggest Edits

/2016-07/deployments/: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

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{  
   "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/: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

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
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

/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

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "_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",
      "tags": ["staging", "encrypted"],
      "_links": {
 	      "tags": {
          "href": "http://example.org/2016-07/clusters/5706b9d1a4b5493d4e00016c/tags{?embed}",
          "templated": true
        }
      }
    }]
  }
}
 

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

tags

User-defined tags on the cluster as a string array.

Suggest Edits

/2016-07/clusters/:id

Gets the details of a specific cluster.

 

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

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "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",
    "tags": ["staging", "encrypted"],
    "_links": {
      "tags": {
        "href": "http://example.org/2016-07/clusters/570d0e81bc2c484e8d000000/tags{?embed}",
        "templated": true
      }
    }
  }
}

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

tags

User-defined tags on the cluster as a string array.

Suggest Edits

/2016-07/clusters/:id/tags

Replace the tags for a cluster

 

Header Auth

 Authentication is required for this endpoint.
patchhttps://api.compose.io/2016-07/clusters/:id/tags
curl -X PATCH 'https://api.compose.io/2016-07/clusters/5989e548a4b549a615f72a62/tags'
-H "Authorization: Bearer [[app:Authorization]]"
-H "Content-Type: application/json; charset=utf-8" \
-d '{
  "cluster": {
    "tags": ["staging", "east", "encrypted_disk"]
  }
}'
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "name": "krystel",
  "type": "multitenant",
  "provider": "softlayer",
  "region": "us-east-2",
  "multitenant": false,
  "created_at": "2017-08-08T16:22:32.210Z",
  "subdomain": "krystel-ms-johnpaul-prosacco",
  "tags": ["staging", "east", "encrypted_disk"],
  "id": "5989e548a4b549a615f72a62",
  "account_id": "5989e548a4b549a615f72a61",
  "account_slug": "ms-johnpaul-prosacco",
  "_links": {
    "tags": {
      "href": "http://example.org/2016-07/clusters/5989e548a4b549a615f72a62/tags{?embed}",
      "templated": true
    }
  }
}

Body Params

cluster
object
 
cluster.tags
array of strings

New tags that will replace the existing tags

 
Suggest Edits

/2016-07/clusters/:id/tags

Add tags to a cluster

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.compose.io/2016-07/clusters/:id/tags
curl -X POST 'https://api.compose.io/2016-07/clusters/5989e548a4b549a615f72a62/tags'
-H "Authorization: Bearer [[app:Authorization]]"
-H "Content-Type: application/json; charset=utf-8" \
-d '{
  "cluster": {
    "tags": ["staging", "east", "encrypted_disk"]
  }
}'
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "name": "krystel",
  "type": "multitenant",
  "provider": "softlayer",
  "region": "us-east-2",
  "multitenant": false,
  "created_at": "2017-08-08T16:22:32.210Z",
  "subdomain": "krystel-ms-johnpaul-prosacco",
  "tags": ["marketing", "staging", "east", "encrypted_disk"],
  "id": "5989e548a4b549a615f72a62",
  "account_id": "5989e548a4b549a615f72a61",
  "account_slug": "ms-johnpaul-prosacco",
  "_links": {
    "tags": {
      "href": "http://example.org/2016-07/clusters/5989e548a4b549a615f72a62/tags{?embed}",
      "templated": true
    }
  }
}

Body Params

cluster
object
 
cluster.tags
array of strings

Tags to add to the existing tags on a cluster

 
Suggest Edits

/2016-07/clusters/:id/tags

Remove tags from a cluster

 

Header Auth

 Authentication is required for this endpoint.
deletehttps://api.compose.io/2016-07/clusters/:id/tags
curl -X DELETE 'https://api.compose.io/2016-07/clusters/5989e548a4b549a615f72a62/tags'
-H "Authorization: Bearer [[app:Authorization]]"
-H "Content-Type: application/json; charset=utf-8" \
-d '{
  "cluster": {
    "tags": ["marketing"]
  }
}'
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "name": "krystel",
  "type": "multitenant",
  "provider": "softlayer",
  "region": "us-east-2",
  "multitenant": false,
  "created_at": "2017-08-08T16:22:32.210Z",
  "subdomain": "krystel-ms-johnpaul-prosacco",
  "tags": ["staging", "east", "encrypted_disk"],
  "id": "5989e548a4b549a615f72a62",
  "account_id": "5989e548a4b549a615f72a61",
  "account_slug": "ms-johnpaul-prosacco",
  "_links": {
    "tags": {
      "href": "http://example.org/2016-07/clusters/5989e548a4b549a615f72a62/tags{?embed}",
      "templated": true
    }
  }
}

Body Params

cluster
object
 
cluster.tags
array of strings

Tags to remove from the existing cluster tags

 
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

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "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

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "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

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "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

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{}{
  "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

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "_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.