Atlas Administration API Reference

HTTP Methods

All resources support a subset of these common HTTP Methods:

JSON

All entities are represented in JSON. The following rules and conventions apply:

• Content Type Request 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

• Invalid Fields

  Invalid fields are rejected rather than ignored. For example, if you attempt to create a new entity and misspell one of the fields, or attempt to update an existing entity and include a field that can't be modified, the server responds with a 400 status code and an error message stating which field is invalid.

• ISO-8601-Formatted Dates

  All dates are returned as ISO-8601-formatted strings designated in UTC. When sending dates to the server (i.e., as query parameters or fields in POST or PATCH request entities), use ISO-8601-formatted dates. If you do not specify a time zone, UTC is assumed. However, it is highly recommended that you include a time zone designator to avoid any ambiguity.

• BSON Timestamps

  In some cases, a timestamp is returned as a BSON timestamp, most notably in the backup resources. These are represented in JSON documents as an object with two fields: date, which is an ISO-8601-formatted date string in UTC with granularity to the second, and increment a 32-bit integer.

• Field Names for Fields with Numbers

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

• Empty Fields

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

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

• Field Order

  The fields in the JSON documents returned by the server are in no particular order, and the order may change. Do not depend on the order of the fields.

Linking

Each resource includes one or more links to sub-resources and/or related resources. Links are placed in the links field of an entity, which is an array of link relation objects. Each link relation has two fields:

All entities include at least one link relation called self, which is simply its own URL. When an entity is part of a list, then it only includes the self link relation.

For more information, refer to the Web Linking Specification. Note that although the specification describes a format for including links in the HTTP response headers, doing so is not a requirement. To make the Atlas Administration API easily browsable, it includes the links in the response body rather than in the response headers.

Lists

Some resources return a list of entities. When a list of entities is expected in a response, the results are returned in batches bounded by the following query parameters:

The response entity contains three fields:

If you make a request for a list of entities and there are no results, then the Atlas Administration API responds with a 200 status code and the results array is empty. 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. However, if you request a list of entities in a context that does not exist (e.g., the list of hosts for a non-existent project), then this does result in a 404 response status.

Envelopes

Some clients might 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 and contains any relevant details that would normally be in the response headers. By default, the Atlas Administration 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:

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

Pretty Printing

By default, extraneous whitespace is stripped from the JSON returned by the server. 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 "https://cloud.mongodb.com/api/atlas/v1.0?pretty=true"

Response Codes

Responses use the standard HTTP response codes, including:

Errors

When a request returns an error, the response body contains a JSON document. This document includes details about why the Atlas Administration API request failed. The document contains five parameters:

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

Project ID

Your Project ID is a string value that uniquely identifies a Atlas project.

Atlas projects were previously identified as "groups". Some Atlas endpoints reference group or {GROUP-ID} as part of the request path, query, or body parameters. For any endpoint that requires your {GROUP-ID}, specify your Project ID instead.

To retrieve your project ID:

Authentication

The Atlas Administration API uses HTTP Digest Authentication to authenticate requests. Digest authentication requires a username and a password, where the API public key serves as the username and its corresponding API private key serves as the password. To learn more, see Atlas Administration API Authentication.

Configuring digest authentication for the Atlas Administration API differs depending on the method you use to make API requests. If you use cURL, include the --digest flag in the request body. For usage details, see Make an API Request.

Rate Limiting

Certain resources limit how many requests they can process per minute.

For these resources, Atlas allows up to 100 requests per minute per project. Atlas Administration API keys belong to an organization, but can be granted access multiple projects.

If you exceed the rate limit, the Atlas Administration API returns a 429 (Too Many Requests) HTTP status code.

Next Steps

To get started, see Get Started with the Atlas Administration API.

To manage programmatic access to the Atlas Administration API, see any of the following procedures:

• Manage Programmatic Access to an Organization.

• Manage Programmatic Access to Multiple Organizations.

• Manage Programmatic Access to a Project.