Compose Database-as-a-Service Help and Documentation

Everything you need to know about Compose, Hosted or Enterprise, is here in our help system. Whether you run one database for your businesses' sole application or six different databases to support an entire corporation, we've got the information you need.

Deployments

This is the older REST API and is now deprecated.

Go to the dedicated apidocs.compose.com for details of the current API which works with all Compose databases with the exception of the MongoDB Classic deployments.

Endpoint Description
GET /accounts/:account/deployments List all MongoDB deployments on an account
GET /deployments/:account/:deployment Get the details for a deployment
PATCH /deployments/:account/:deployment Rename a deployment for easier reference
GET /deployments/:account/:deployment/backups List the backups for a deployment
GET /deployments/:account/:deployment/version Get MongoDB version info for a deployment
PUT /deployments/:account/:deployment/version Upgrade to a new version of MongoDB on a deployment
POST /deployments/:account/:deployment/databases Create a new database
POST /accounts/:account/deployments/elastic Create a new Elastic Deployment
POST /accounts/:account/deployments/dedicated Create a new dedicated deployment

Common Parameters

Param Description
:account slug or id for an account
:deployment name or id for a deployment

GET /accounts/:account/deployments

List all MongoDB deployments on an account.

Request

curl -i -X GET 'https://api.compose.io/accounts/your-account/deployments' \
-H 'Content-Type: application/json' \
-H 'Accept-Version: 2014-06' \
-H 'Authorization: Bearer [OAUTH_TOKEN]'

Response

[
  {
    "id": "123456",
    "name": null,
    "location": "aws:us-east-1",
    "type": "mongodb",
    "plan": "mongohq:elastic",
    "version": "2.4.10",
    "current_primary": "awesomeness.compose.io:10000",
    "members": [
      "awesomeness.compose.io:10000",
      "awesomeness.compose.io:10001"
    ],
    "ignored_members": [],
    "allow_multiple_databases": true,
    "status": "running",
    "databases": [
      {
        "id": "123456",
        "name": "database-1",
        "deprovision_date": null,
        "status": "running",
        "deployment_id": "123456",
        "plan": "mongohq:elastic"
      }
    ]
  }
]

GET /deployments/:account/:deployment

Get the details for a deployment by its name or id.

Request

curl -i -X GET 'https://api.compose.io/deployments/your-account/deployment-1' \
-H 'Content-Type: application/json' \
-H 'Accept-Version: 2014-06' \
-H 'Authorization: Bearer [OAUTH_TOKEN]'

Response

{
  "id": "123456",
  "name": null,
  "location": "aws:us-east-1",
  "type": "mongodb",
  "plan": "mongohq:elastic",
  "version": "2.4.10",
  "current_primary": "awesomeness.compose.io:10000",
  "members": [
    "awesomeness.compose.io:10000",
    "awesomeness.compose.io:10001"
  ],
  "ignored_members": [],
  "allow_multiple_databases": true,
  "status": "running",
  "databases": [
    {
      "id": "123456",
      "name": "database-1",
      "deprovision_date": null,
      "status": "running",
      "deployment_id": "123456",
      "plan": "mongohq:elastic"
    }
  ]
}

PATCH /deployments/:account/:deployment

Rename a deployment for easier reference.

Request

curl -i -X PATCH 'https://api.compose.io/deployments/your-account/deployment-1' \
-H 'Content-Type: application/json' \
-H 'Accept-Version: 2014-06' \
-H 'Authorization: Bearer [OAUTH_TOKEN]' \
-d '{"name":"new-name"}'

Response

{
  "name": "new-name"
}

GET /deployments/:account/:deployment/backups

List the backups available for a given deployment.

Request

curl -i -X GET 'https://api.compose.io/deployments/your-account/deployment-1/backups' \
-H 'Content-Type: application/json' \
-H 'Accept-Version: 2014-06' \
-H 'Authorization: Bearer [OAUTH_TOKEN]'

Response

[
  {
    "created_at": "2014-05-04T21:42:41+00:00",
    "database_names": [
      "my-database"
    ],
    "deployment_id": "deployment-1",
    "filename": "2014-05-04_21-42-41_UTC_my-database.tar.gz",
    "id": "backup-1",
    "links": [
      {
        "href": "https://api.compose.io/backups/backup-1/download",
        "rel": "download"
      },
      {
        "href": "https://api.compose.io/backups/backup-1/restore",
        "rel": "restore"
      }
    ],
    "size": 33947,
    "status": "complete",
    "type": "weekly"
  }
]

GET /deployments/:account/:deployment/version

Get MongoDB version info for a given deployment.

Includes info about available upgrades that can be performed on your deployment.

Request

curl -i -X GET 'https://api.compose.io/deployments/your-account/deployment-1/version' \
-H 'Content-Type: application/json' \
-H 'Accept-Version: 2014-06' \
-H 'Authorization: Bearer [OAUTH_TOKEN]'

Response

{
  "type": "MongoDB",
  "version": "2.2.3",
  "messages": [
    "This deployment is currently 2 minor versions behind the latest production release of MongoDB. Please clone your database to a staging database to test any upgrades. This will prevent any unexpected breaking changes."
  ],
  "eligible_upgrade_version": {
    "version": "2.2.9",
    "upgrade_type": "patch",
    "messages": []
  },
  "upgrade_path": [
    {
      "version": "2.4.10",
      "upgrade_type": "minor",
      "messages": [
        "Message for 2.4",
        "Message for 2.4.10"
      ]
    },
    {
      "version": "2.6.0",
      "upgrade_type": "minor",
      "messages": [
        "Message for 2.6"
      ]
    }
  ]
}

PUT /deployments/:account/:deployment/version

Upgrade to a new version of MongoDB on a deployment. A PUT to this URL will perform an upgrade to the version specified in the eligible_upgrade_version field shown above.

Request

curl -i -X PUT 'https://api.compose.io/deployments/your-account/deployment-1/version' \
-H 'Content-Type: application/json' \
-H 'Accept-Version: 2014-06' \
-H 'Authorization: Bearer [OAUTH_TOKEN]'

Response

{
  "id": "deployment-1",
  "name": "my-deployment",
  "location": "aws:us-east-1",
  "type": "mongodb",
  "version": "2.2.9",
  "current_primary": "awesomeness.compose.io:10000",
  "members": [
    "awesomeness.compose.io:10000"
  ],
  "ignored_members": [],
  "allow_multiple_databases": false,
  "status": "running",
  "alert_setting": {
    // TODO
  }
}

POST /deployments/:account/:deployment/databases

Create a new database within the specified deployment.

Parameters

Field
Description

name

Name of the new database

username

Username for the default user on the new database

password

Password for the default user on the new database

Request

curl -i -X POST 'https://api.compose.io/deployments/your-account/deployment-1/databases' \
-H 'Content-Type: application/json' \
-H 'Accept-Version: 2014-06' \
-H 'Authorization: Bearer [OAUTH_TOKEN]' \
-d '{"name":"my-database-2", "username": "my-user", "password": "my-password"}'

Response

{
  "name": "my-database-2",
  "status": "running",
  "deployment_id": "123456"
}

POST /accounts/:account/deployments/elastic

Create an Elastic Deployment. The initial status of the deployment will be "new". You should poll for updates to the deployment status every 5 seconds using GET /deployments/:account/:deployment.

Parameters

Name Type Description
name string Name of the deployment
database_name string Name of the default database
location string Region in which to provision the deployment. List available locations using GET /locations.
username string Username for the default database user
password string Password for the default database user
type string Deployment type. Currently must be mongodb.

Request

curl -i -X POST 'https://api.compose.io/accounts/your-account/deployments/elastic' \
-H 'Content-Type: application/json' \
-H 'Accept-Version: 2014-06' \
-H 'Authorization: Bearer [OAUTH_TOKEN]' \
-d '{"database_name":"db-name","location":"aws:us-east-1"}'

Response

{
  id: "deployment-1",
  name: null,
  location: "aws:us-east-1",
  type: "mongodb",
  version: "2.6.1",
  current_primary: "awesomeness.compose.io:10000",
  members: ["awesomeness.compose.io:10000"],
  ignored_members: [],
  allow_multiple_databases: false,
  status: "running",
  alert_setting: {
    // TODO
  }
}

POST /accounts/:account/deployments/dedicated

Create a new dedicated deployment.

Parameters

Name Type Description
name string Name of the deployment
database_name string Name of the default database
location string Region in which to provision the deployment. List available locations using GET /locations.
type string Deployment type. Currently must be mongodb.
flavor string Instance type, for example: m1.medium
nodes int Number of data nodes

Request

curl -i -X POST 'https://api.compose.io/accounts/your-account/deployments/dedicated' \
-H 'Content-Type: application/json' \
-H 'Accept-Version: 2014-06' \
-H 'Authorization: Bearer [OAUTH_TOKEN]' \
-d '{"database_name":"db-name","location":"aws:us-east-1","nodes":2,"flavor":"m1.medium"}'

Response

{
  id: "deployment-1",
  name: null,
  location: "aws:us-east-1", // find available locations using GET /locations
  type: "mongodb",
  version: "2.6.1",
  current_primary: "awesomeness.compose.io:10000",
  members: ["awesomeness.compose.io:10000"],
  ignored_members: [],
  allow_multiple_databases: false,
  status: "running",
  alert_setting: {
    // TODO
  }
}

Still Need Help?

If this article didn't solve things, summon a human and get some help!

Deployments