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.

EndpointDescription
GET /accounts/:account/deploymentsList all MongoDB deployments on an account
GET /deployments/:account/:deploymentGet the details for a deployment
PATCH /deployments/:account/:deploymentRename a deployment for easier reference
GET /deployments/:account/:deployment/backupsList the backups for a deployment
GET /deployments/:account/:deployment/versionGet MongoDB version info for a deployment
PUT /deployments/:account/:deployment/versionUpgrade to a new version of MongoDB on a deployment
POST /deployments/:account/:deployment/databasesCreate a new database
POST /accounts/:account/deployments/elasticCreate a new Elastic Deployment
POST /accounts/:account/deployments/dedicatedCreate a new dedicated deployment

Common Parameters

ParamDescription
:accountslug or id for an account
:deploymentname 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

NameTypeDescription
namestringName of the deployment
database_namestringName of the default database
locationstringRegion in which to provision the deployment. List available locations using GET /locations.
usernamestringUsername for the default database user
passwordstringPassword for the default database user
typestringDeployment 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

NameTypeDescription
namestringName of the deployment
database_namestringName of the default database
locationstringRegion in which to provision the deployment. List available locations using GET /locations.
typestringDeployment type. Currently must be mongodb.
flavorstringInstance type, for example: m1.medium
nodesintNumber 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!

Updated about a year ago

Deployments


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.