Docs Menu
Docs Home
MongoDB Cloud Manager

Public API Principles

On this page

  • HTTP Methods
  • JSON
  • Linking
  • Lists
  • Envelopes
  • Pretty Printing
  • Response Codes
  • Errors
  • Authentication
  • Automation
  • Rate Limiting
  • Additional Information

The Cloud Manager Public API follows the REST architecture principles to expose internal resources that provide programmatic access to Cloud Manager's features.

As with changes made through the web interface, changes made through the API are subject to Cloud Manager pricing. If you add servers and incur charges, you must have a valid credit card on file with Cloud Manager or risk having your account locked.

The API has the following features:

JSON entities
All entities are expressed in JSON.
Key-based access
Each Cloud Manager user or application needing to connect to Cloud Manager must generate an API key before accessing the Cloud Manager API.
Digest authentication
To ensure that your public API key is never sent over the network, API requests are authenticated using HTTP Digest Authentication.
Browsable interface
Using a consistent linking mechanism, you can browse the entire API by starting at the root resource and following links to related resources.
User Access Control

Each Cloud Manager user's API capabilities match the permissions that their Cloud Manager Roles grant.


API Network Access List

The Cloud Manager API can secure access to the Cloud Manager Administration API through an API Access List. This list restricts access to the API to specific IP or CIDR addresses. Each API key has its own Cloud Manager Administration API access list. When you create a new organization using the Cloud Manager UI, the MongoDB Atlas enables the API access list requirement by default.

To learn more, see (Optional) Require an API Access List for Your Organization.

You can access the API only via HTTPS, which ensures all data sent over the network is fully encrypted using TLS.

All resources support a subset of these common HTTP Methods:

Retrieve the JSON representation of a resource.
Create a new resource using the provided JSON representation.
Replace a resource with the provided JSON representation.
Update the specified fields in a resource using the provided JSON representation.
Remove a resource.
Retrieve the response header without the JSON representation of the resource.

All entities are represented in JSON. The following rules for requests and conventions of responses apply:

Apply the Correct Content Type Header
When sending JSON to the server via POST or PUT, make sure to specify the correct content type request header: Content-Type: application/json
Set Dates as ISO 8601 Strings

When sending dates to the server (as query parameters or fields in POST or PATCH request entities), use dates formatted according to the ISO 8601 standard. If you don't specify a time zone, Cloud Manager assumes UTC. Include a time zone designator to avoid any ambiguity.


  • September 27, 2018 is expressed as 2018-09-27.

  • September 27, 2018 at 4:00 PM EDT is expressed (with time zone) as 2018-09-27T16:00-04:00.

In some cases, a timestamp is returned as a JSON representation of a BSON timestamp, most notably in the backup resources. This representation of a BSON timestamp provides a JSON document as an object with two fields:

Seconds since the UNIX Epoch
An incrementing 32-bit integer ordinal for operations within a given second.


The third operation at September 27, 2018 at 4:00 PM EDT is expressed (with time zone) as

{ date: 2018-09-27T16:00-04:00, increment: 3 }
Rejects Invalid Fields

Invalid fields are rejected rather than ignored.


You attempt to create a new entity and misspell one of the fields, or if you attempt to update an existing entity and include a field that cannot be modified, the Cloud Manager responds with an HTTP 400 status code and an error message stating which field was invalid.

Returns Dates as ISO 8601 Strings
All dates are returned as ISO 8601-formatted strings designated in UTC.
Labels Field to Disambiguate Units

Fields that contain numeric values in a particular unit are named so as to disambiguate the unit being used.


A host's uptime is returned in millseconds, so the name of the host entity field is uptimeMsec.

Returns Default Values for Fields without Other Values

Fields that do not have a current value are returned with an appropriate default value.


Cloud Manager does not have any statistics for a newly discovered host, so any statistics-related fields have a value of zero.

Fields that do not have a sensible default value are omitted from the entity.


A host that is not using authentication omits the username field from the returned entity.

Returns Fields in Alphabetical Order
The fields in the JSON documents that the Cloud Manager returns are in alphabetical order. The order could change. Do not depend on the order of the fields.

Each resource includes one or more links to sub-resources and/or related resources.


A host has a link to the project it belongs to, the replica set it belongs to, and so on.

Links are placed in the links field of an entity, which is an array of link relation objects. Each link relation has two fields:

Name (or type) of the relation. Many of these are considered Extension Relation Types and are prefixed by
Target URL.

All entities include at least one link relation called self, which is simply its own URL. When an entity is part of a list (i.e., when requesting all hosts in a project), then it only includes the self link relation.


This is a portion of a host resource with a few links:

2 "id": "xxx",
3 "projectId": "yyy",
4 "hostname": "",
5 "port": 27017,
6 "links": [
7 {
8 "rel": "self",
9 "href": ""
10 },
11 {
12 "rel": "",
13 "href": ""
14 }
15 ]

To learn more, see the Web Linking Specification.


Although the Web Linking Specification describes a format for including links in the HTTP response headers, it is not required. To make the API easily browsable, it includes the links in the response body rather than in the response headers.

Some resources return a list of entities.


You can request a list of all hosts in a project.

When a list of entities is expected in a response, the results are returned in batches bounded by two query parameters:

Page number (1-based). Defaults to 1 if not specified.
Number of items to return per page, up to a maximum of 500. Defaults to 100 if not specified.

The response entity contains three fields:


Total number of items in the entire result set.


If a project has a total of 57 hosts, and you make a request with pageNum=6 and itemsPerPage=10, then totalCount is 57.

Result set, which is an array of entity documents.

Contains one to three link relations:

  • previous for the previous page of results (omitted for the first page);

  • next for the next page of results (omitted for the last page);

  • self for the current page (always present).

If you make a request for a list of entities and there are no results, then the API responds with an HTTP 200 status code and an empty results array. It does not respond with a 404 in this case, since the list of entities may not be empty at some point in the future.

If you had requested a list of entities in a context that does not exist (i.e., the list of hosts for a non-existent project), then this results in a an HTTP 404 response status.


This is an HTTP response for the second page of 10 hosts in a project with a total of 57 hosts:

3 "totalCount": 57,
4 "results": [
5 {
6 "id": "yyy",
7 "projectId": "xxx",
8 // additional host properties...
9 },
10 // additional host documents...
11 ],
12 "links": [
13 {
14 "rel" : "self",
15 "href" : ""
16 },
17 {
18 "rel": "previous",
19 "href": ""
20 },
21 {
22 "rel": "next",
23 "href": ""
24 }
25 ]

Some clients may not be able to access the HTTP response headers and/or status code. In that case, you can request that the response include an envelope, which is simply an extra layer of information in the JSON document that contains any relevant details that would normally be in the response headers.

By default, the API does not include the response in an envelope. To request one, simply add the query parameter envelope=true.

For responses that contain a single entity, the envelope contains two fields:

HTTP status code.
Requested entity.

For responses that contain a list of entities, there is already an envelope that wraps the results, so specifying envelope=true as a query parameter in this case only adds the status field to the existing envelope.

By default, extraneous whitespace is stripped from the JSON that Cloud Manager returns. To ask for pretty-printed JSON, simply append the pretty=true query parameter to any request:

curl --user '{USERNAME}:{APIKEY}' --digest \
--header 'Accept: application/json' \
--include \
--request GET ""


All the examples in this document show pretty-printed JSON for clarity, although some example URLs may not contain this additional query parameter.

Responses utilize the standard HTTP response codes, including:

The request was successful. This is the typical response to a successful GET request.
A new resource was created. This is the typical response to a successful POST request.
A request for an asynchronous operation was accepted.
Bad Request
Something was wrong with the client request.
Authentication is required but was not present in the request. Typically this means that the digest authentication information was omitted from the request, the provided credentials are incorrect, or the user associated with the given API key is not allowed to access the requested resource.
Access to the specified resource is not permitted.
Not Found
The requested resource does not exist.
Method Not Allowed

The HTTP method is not supported for the specified resource. Keep in mind that each resource may only support a subset of HTTP methods.


You are not allowed to DELETE the root resource.


This is typically the response to a request to create or modify a property of an entity that is unique when an existing entity already exists with the same value for that property.


If you attempt to create a project with the same name as an existing project, the request fails.

Various server errors
Something unexpected went wrong. Try again later and consider notifying Cloud Manager Support.

When a request results in an error, the response body contains a JSON document with additional details about what went wrong. The document contains five fields:

Data Type
Human-readable description of the API request error.
Named constant representing the API request error as shown in Cloud Manager Administration API Error Codes.
array of strings
List of parameters passed in the API request.


Cloud Manager returns this response body for an incorrectly formatted request:

2 "detail" : "Cannot find resource /api/public/v1.0/softwareComponents/version.",
3 "error" : 404,
4 "errorCode" : "RESOURCE_NOT_FOUND",
5 "parameters" : [ "/api/public/v1.0/softwareComponents/version" ],
6 "reason" : "Not Found"

To review the list of codes, see Cloud Manager Administration API Error Codes.

As previously mentioned, the Cloud Manager API uses HTTP Digest Authentication. The details of digest authentication are beyond the scope of this document, but it essentially requires a username and a password which are hashed using a unique server-generated value called a nonce. The username is the username of a registered Cloud Manager account, and the password is a public API key associated with that account.

Keep the following points in mind:

  • The server-generated nonce is used by the client to hash the username and password before sending them back to the server to authenticate a request. The nonce is only valid for a short amount of time as per the digest authentication specification. This is to prevent replay attacks, so you cannot cache a nonce and use it forever.

  • Using digest authentication in combination with HTTPS provides an extra layer of security by ensuring that a password is never transmitted back to the server.

  • Some resource methods require even more security and are additionally protected by access lists that allow access to the resource only from the IP addresses listed. Each user configures their own access list of IP addresses that allow access to the resource.

  • The Cloud Manager has a concept of roles, which allow more fine-grained control of the operations a user is allowed to perform. The API resources also enforce the same authorization rules, so the resources and methods that can be accessed by an API key are governed by the roles granted to the associated user.


    To DELETE a host, the user that owns the API key used to make the request must be a Project Monitoring Admin or Project Owner in the project to which the host belongs.

  • Many resources are tied to a project (former known as a group), as evidenced by URLs of the following form:


    For these resources, the user tied to the API key must be a member of the project. Otherwise Cloud Manager responds with an HTTP 401 error.

The Automation Configuration Resource and Get Automation Status of Latest Plan resources provide endpoints that let you modify a project's deployment and retrieve deployment status. You can modify a deployment by sending a new automation configuration to Cloud Manager. The automation configuration is where you describe and configure the MongoDB processes to be deployed. Cloud Manager refers to this as the deployment's "goal state." When you submit a new automation configuration through the API, the Automations adjust the current state of the system to match the goal state.


There is no protection in the API to prevent concurrent modifications. If two administrators both start with a configuration based on the current version, make their own modifications, and then submit their modifications, the later modification wins.

Certain resources are subject to rate limiting.

For resources that are rate limited, Cloud Manager allows up to 100 requests per minute per project. Keep in mind that a Public API Key is assigned to a Cloud Manager user, but that user may access multiple projects.


Consider two users: A and B.

User A belongs to project X, and user B belongs to projects X and Y.

  1. At 1:00:00pm, User A makes 50 requests to a rate limited resource in project X, all of which complete by 1:00:20pm.

  2. At 1:00:30pm, User B attempts to make 60 requests to a rate limited resource in project X.

    Since User A has already used up 50 requests within the 1:00pm minute for project X, the last 10 requests User B attempts to make are rejected. However, User B can make requests to a rate limited resource in project Y, since each project maintains a separate request counter.

  3. At 1:01pm, requests to project X may proceed, because the request counter used for rate limiting reset each minute.

If you exceed the rate limit, the API returns an HTTP 429 Too Many Requests response code.

See Cloud Manager Administration API Resources for a complete reference of all resources available in the Cloud Manager Public API.




Cloud Manager Administration API Resources