MongoDB Atlas Administration API
API docs by Redocly

MongoDB Atlas Administration API (1.0)

Download OpenAPI specification:Download

License: CC BY-NC-SA 3.0 US Terms of Service

The MongoDB Atlas Administration API allows developers to manage all components in MongoDB Atlas.

The Atlas Administration API uses HTTP Digest Authentication to authenticate requests. Provide a programmatic API public key and corresponding private key as the username and password when constructing the HTTP request. For example, to return database access history with cURL, run the following command in the terminal:

curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" \
  --digest \
  --header "Accept: application/json" \
  -X GET "https://cloud.mongodb.com/api/atlas/v1.0/groups/{groupId}/dbAccessHistory/clusters/{clusterName}?pretty=true"

To learn more, see Get Started with the Atlas Administration API. For support, see MongoDB Support.

Access Tracking

Returns access logs for authentication attempts made to Atlas database deployments. To view database access history, you must have either the Project Owner or Organization Owner role.

Return Database Access History for One Cluster using Its Cluster Name

Returns the access logs of one cluster identified by the cluster's name. Access logs contain a list of authentication requests made against your cluster. You can't use this feature on tenant-tier clusters (M0, M2, M5). To use this resource, the requesting API Key must have the Project Monitoring Admin role.

Database Access History
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

authResult
boolean

Flag that indicates whether the response returns the successful authentication attempts only.

end
integer <int64>

Date and time when to stop retrieving database history. If you specify end, you must also specify start. This parameter uses UNIX epoch time in milliseconds.

ipAddress
string^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)(\.(?!$)|$))...

One Internet Protocol address that attempted to authenticate with the database.

nLogs
integer <int32> [ 0 .. 20000 ]
Default: 20000

Maximum number of lines from the log to return.

start
integer <int64>

Date and time when MongoDB Cloud begins retrieving database history. If you specify start, you must also specify end. This parameter uses UNIX epoch time in milliseconds.

Responses

Response samples

Content type
application/json
{
  • "accessLogs": [
    ]
}

Return Database Access History for One Cluster using Its Hostname

Returns the access logs of one cluster identified by the cluster's hostname. Access logs contain a list of authentication requests made against your clusters. You can't use this feature on tenant-tier clusters (M0, M2, M5). To use this resource, the requesting API Key must have the Project Monitoring Admin role.

Database Access History
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

hostname
required
string

Fully qualified domain name or IP address of the MongoDB host that stores the log files that you want to download.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

authResult
boolean

Flag that indicates whether the response returns the successful authentication attempts only.

end
integer <int64>

Date and time when to stop retrieving database history. If you specify end, you must also specify start. This parameter uses UNIX epoch time in milliseconds.

ipAddress
string^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)(\.(?!$)|$))...

One Internet Protocol address that attempted to authenticate with the database.

nLogs
integer <int32> [ 0 .. 20000 ]
Default: 20000

Maximum number of lines from the log to return.

start
integer <int64>

Date and time when MongoDB Cloud begins retrieving database history. If you specify start, you must also specify end. This parameter uses UNIX epoch time in milliseconds.

Responses

Response samples

Content type
application/json
{
  • "accessLogs": [
    ]
}

Alert Configurations

Returns and edits the conditions that trigger alerts and how MongoDB Cloud notifies users. This collection remains under revision and may change.

Get All Alert Configuration Matchers Field Names

Get all field names that the matchers.fieldName parameter accepts when you create or update an Alert Configuration. You can successfully call this endpoint with any assigned role.

Authorizations:
DigestAuthServiceAccounts
query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
[
  • "APPLICATION_ID"
]

Return All Alert Configurations for One Project

Returns all alert configurations for one project. These alert configurations apply to any component in the project. Alert configurations define the triggers and notification methods for alerts. To use this resource, the requesting API Key must have the Project Read Only role.

This resource remains under revision and may change.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Create One Alert Configuration in One Project

Creates one alert configuration for the specified project. Alert configurations define the triggers and notification methods for alerts. To use this resource, the requesting API Key must have the Organization Owner or Project Owner role.

This resource remains under revision and may change.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Creates one alert configuration for the specified project.

One of
enabled
boolean
Default: false

Flag that indicates whether someone enabled this alert configuration for the specified project.

required
Billing Event Types (object) or Cps Backup Event Types (object) or FTS Index Audit Types (object) or Group Event Types (object) or NDS Audit Types (object) or NDS Maintenance Window Audit Types (object) or Online Archive Event Types (object) or User Event Types (object) or Resource Event Types (object) or Stream Processor Event Types (object) or NDS Auto Scaling Audit Types (object)

Incident that triggered this alert.

Array of objects (Matchers)

Matching conditions for target resources.

required
Array of Datadog Notification (object) or Email Notification (object) or Group Notification (object) or HipChat Notification (object) or Microsoft Teams Notification (object) or OpsGenie Notification (object) or Org Notification (object) or PagerDuty Notification (object) or Slack Notification (object) or SMS Notification (object) or Team Notification (object) or User Notification (object) or VictorOps Notification (object) or Webhook Notification (object) (AlertsNotificationRootForGroup)

List that contains the targets that MongoDB Cloud sends notifications.

Responses

Request samples

Content type
application/json
Example
{
  • "enabled": false,
  • "eventTypeName": "CREDIT_CARD_ABOUT_TO_EXPIRE",
  • "matchers": [
    ],
  • "notifications": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "created": "2019-08-24T14:15:22Z",
  • "enabled": false,
  • "eventTypeName": "CREDIT_CARD_ABOUT_TO_EXPIRE",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "links": [],
  • "matchers": [
    ],
  • "notifications": [
    ],
  • "updated": "2019-08-24T14:15:22Z"
}

Remove One Alert Configuration from One Project

Removes one alert configuration from the specified project. To use this resource, the requesting API Key must have the Organization Owner or Project Owner role.

This resource remains under revision and may change.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

alertConfigId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies the alert configuration. Use the /alertConfigs endpoint to retrieve all alert configurations to which the authenticated user has access.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "detail": "(This is just an example, the exception may not be related to this endpoint)",
  • "error": 401,
  • "errorCode": "NOT_ORG_GROUP_CREATOR",
  • "reason": "Unauthorized"
}

Return One Alert Configuration from One Project

Returns the specified alert configuration from the specified project. To use this resource, the requesting API Key must have the Project Read Only role.

This resource remains under revision and may change.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

alertConfigId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies the alert configuration. Use the /alertConfigs endpoint to retrieve all alert configurations to which the authenticated user has access.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
Example
{
  • "created": "2019-08-24T14:15:22Z",
  • "enabled": false,
  • "eventTypeName": "CREDIT_CARD_ABOUT_TO_EXPIRE",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "links": [],
  • "matchers": [
    ],
  • "notifications": [
    ],
  • "updated": "2019-08-24T14:15:22Z"
}

Toggle One State of One Alert Configuration in One Project

Enables or disables the specified alert configuration in the specified project. The resource enables the specified alert configuration if currently enabled. The resource disables the specified alert configuration if currently disabled. To use this resource, the requesting API Key must have the Organization Owner or Project Owner role.

NOTE: This endpoint updates only the enabled/disabled state for the alert configuration. To update more than just this configuration, see Update One Alert Configuration.

This resource remains under revision and may change.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

alertConfigId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies the alert configuration that triggered this alert. Use the /alertConfigs endpoint to retrieve all alert configurations to which the authenticated user has access.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Enables or disables the specified alert configuration in the specified project.

enabled
boolean

Flag that indicates whether to enable or disable the specified alert configuration in the specified project.

Responses

Request samples

Content type
application/json
{
  • "enabled": true
}

Response samples

Content type
application/json
Example
{
  • "created": "2019-08-24T14:15:22Z",
  • "enabled": false,
  • "eventTypeName": "CREDIT_CARD_ABOUT_TO_EXPIRE",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "links": [],
  • "matchers": [
    ],
  • "notifications": [
    ],
  • "updated": "2019-08-24T14:15:22Z"
}

Update One Alert Configuration for One Project

Updates one alert configuration in the specified project. Alert configurations define the triggers and notification methods for alerts. To use this resource, the requesting API Key must have the Organization Owner or Project Owner role.

NOTE: To enable or disable the alert configuration, see Toggle One State of One Alert Configuration in One Project.

This resource remains under revision and may change.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

alertConfigId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies the alert configuration. Use the /alertConfigs endpoint to retrieve all alert configurations to which the authenticated user has access.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Updates one alert configuration in the specified project.

One of
enabled
boolean
Default: false

Flag that indicates whether someone enabled this alert configuration for the specified project.

required
Billing Event Types (object) or Cps Backup Event Types (object) or FTS Index Audit Types (object) or Group Event Types (object) or NDS Audit Types (object) or NDS Maintenance Window Audit Types (object) or Online Archive Event Types (object) or User Event Types (object) or Resource Event Types (object) or Stream Processor Event Types (object) or NDS Auto Scaling Audit Types (object)

Incident that triggered this alert.

Array of objects (Matchers)

Matching conditions for target resources.

required
Array of Datadog Notification (object) or Email Notification (object) or Group Notification (object) or HipChat Notification (object) or Microsoft Teams Notification (object) or OpsGenie Notification (object) or Org Notification (object) or PagerDuty Notification (object) or Slack Notification (object) or SMS Notification (object) or Team Notification (object) or User Notification (object) or VictorOps Notification (object) or Webhook Notification (object) (AlertsNotificationRootForGroup)

List that contains the targets that MongoDB Cloud sends notifications.

Responses

Request samples

Content type
application/json
Example
{
  • "enabled": false,
  • "eventTypeName": "CREDIT_CARD_ABOUT_TO_EXPIRE",
  • "matchers": [
    ],
  • "notifications": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "created": "2019-08-24T14:15:22Z",
  • "enabled": false,
  • "eventTypeName": "CREDIT_CARD_ABOUT_TO_EXPIRE",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "links": [],
  • "matchers": [
    ],
  • "notifications": [
    ],
  • "updated": "2019-08-24T14:15:22Z"
}

Return All Alert Configurations Set for One Alert

Returns all alert configurations set for the specified alert. To use this resource, the requesting API Key must have the Project Read Only role.

This resource remains under revision and may change.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

alertId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the alert. Use the /alerts endpoint to retrieve all alerts to which the authenticated user has access.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

Responses

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Alerts

Returns and acknowledges alerts that MongoDB Cloud triggers based on the alert conditions that you define. This collection remains under revision and may change.

Return All Open Alerts for Alert Configuration

Returns all open alerts that the specified alert configuration triggers. These alert configurations apply to the specified project only. Alert configurations define the triggers and notification methods for alerts. Open alerts have been triggered but remain unacknowledged. To use this resource, the requesting API Key must have the Project Read Only role.

This resource remains under revision and may change.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

alertConfigId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies the alert configuration. Use the /alertConfigs endpoint to retrieve all alert configurations to which the authenticated user has access.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Return All Alerts from One Project

Returns all alerts. These alerts apply to all components in one project. You receive an alert when a monitored component meets or exceeds a value you set. To use this resource, the requesting API Key must have the Project Read Only role.

This resource remains under revision and may change.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

status
string
Enum: "OPEN" "TRACKING" "CLOSED"

Status of the alerts to return. Omit to return all alerts in all statuses.

Responses

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Return One Alert from One Project

Returns one alert. This alert applies to any component in one project. You receive an alert when a monitored component meets or exceeds a value you set. To use this resource, the requesting API Key must have the Project Read Only role.

This resource remains under revision and may change.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

alertId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the alert. Use the /alerts endpoint to retrieve all alerts to which the authenticated user has access.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
Example
{
  • "acknowledgedUntil": "2019-08-24T14:15:22Z",
  • "acknowledgementComment": "Expiration on 3/19. Silencing for 7days.",
  • "acknowledgingUsername": "user@example.com",
  • "alertConfigId": "32b6e34b3d91647abb20e7b8",
  • "created": "2019-08-24T14:15:22Z",
  • "eventTypeName": "DEPLOYMENT_FAILURE",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "lastNotified": "2019-08-24T14:15:22Z",
  • "links": [],
  • "orgId": "32b6e34b3d91647abb20e7b8",
  • "resolved": "2019-08-24T14:15:22Z",
  • "status": "OPEN",
  • "updated": "2019-08-24T14:15:22Z"
}

Acknowledge One Alert from One Project

Confirms receipt of one existing alert. This alert applies to any component in one project. Acknowledging an alert prevents successive notifications. You receive an alert when a monitored component meets or exceeds a value you set until you acknowledge the alert. To use this resource, the requesting API Key must have the Organization Owner or Project Owner role.

This resource remains under revision and may change.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

alertId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the alert. Use the /alerts endpoint to retrieve all alerts to which the authenticated user has access.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Acknowledges or unacknowledges one alert.

acknowledgedUntil
string <date-time>

Date and time until which this alert has been acknowledged. This parameter expresses its value in the ISO 8601 timestamp format in UTC. The resource returns this parameter if a MongoDB User previously acknowledged this alert.

  • To acknowledge this alert forever, set the parameter value to 100 years in the future.

  • To unacknowledge a previously acknowledged alert, do not set this parameter value.

acknowledgementComment
string <= 200 characters

Comment that a MongoDB Cloud user submitted when acknowledging the alert.

Responses

Request samples

Content type
application/json
{
  • "acknowledgedUntil": "2019-08-24T14:15:22Z",
  • "acknowledgementComment": "Expiration on 3/19. Silencing for 7days."
}

Response samples

Content type
application/json
Example
{
  • "acknowledgedUntil": "2019-08-24T14:15:22Z",
  • "acknowledgementComment": "Expiration on 3/19. Silencing for 7days.",
  • "acknowledgingUsername": "user@example.com",
  • "alertConfigId": "32b6e34b3d91647abb20e7b8",
  • "created": "2019-08-24T14:15:22Z",
  • "eventTypeName": "DEPLOYMENT_FAILURE",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "lastNotified": "2019-08-24T14:15:22Z",
  • "links": [],
  • "orgId": "32b6e34b3d91647abb20e7b8",
  • "resolved": "2019-08-24T14:15:22Z",
  • "status": "OPEN",
  • "updated": "2019-08-24T14:15:22Z"
}

Return All User-Defined Analyzers for One Cluster

Returns all Atlas Search custom analyzers that the specified cluster uses in the specified project. Custom analyzers define the operations to perform to index a field. To use this resource, the requesting API Key must have the Project Data Access Read Write role.

Custom Analyzers
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Name of the cluster that contains the collection with one or more Atlas Search indexes.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update All User-Defined Analyzers for One Cluster

Updates one or more Atlas Search custom analyzers on the specified cluster. Custom analyzers define the operations to perform to index a field. To use this resource, the requesting API Key must have the Project Data Access Admin role.

Custom Analyzers
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Name of the cluster that contains the collection with one or more Atlas Search indexes.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Updates one or more Atlas Search custom analyzers on the specified cluster.

Array
Array of htmlStrip (object) or icuNormalize (object) or mapping (object) or persian (object)

Filters that examine text one character at a time and perform filtering operations.

name
required
string

Human-readable name that identifies the custom analyzer. Names must be unique within an index, and must not start with any of the following strings:

  • lucene.
  • builtin.
  • mongodb.
Array of asciiFolding (object) or daitchMokotoffSoundex (object) or edgeGram (object) or englishPossessive (object) or flattenGraph (object) or icuFolding (object) or icuNormalizer (object) or kStemming (object) or length (object) or lowercase (object) or nGram (object) or porterStemming (object) or regex (object) or reverse (object) or shingle (object) or snowballStemming (object) or spanishPluralStemming (object) or stempel (object) or stopword (object) or trim (object) or wordDelimiterGraph (object)

Filter that performs operations such as:

  • Stemming, which reduces related words, such as "talking", "talked", and "talks" to their root word "talk".

  • Redaction, the removal of sensitive information from public documents.

required
object

Tokenizer that you want to use to create tokens. Tokens determine how Atlas Search splits up text into discrete chunks for indexing.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Create One Atlas Search Index

Creates one Atlas Search index on the specified collection. Atlas Search indexes define the fields on which to create the index and the analyzers to use when creating the index. Only clusters running MongoDB v4.2 or later can use Atlas Search. To use this resource, the requesting API Key must have the Project Data Access Admin role.

Atlas Search Indexes
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Name of the cluster that contains the collection on which to create an Atlas Search index.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Creates one Atlas Search index on the specified collection.

collectionName
required
string

Human-readable label that identifies the collection that contains one or more Atlas Search indexes.

database
required
string

Human-readable label that identifies the database that contains the collection with one or more Atlas Search indexes.

name
required
string

Human-readable label that identifies this index. Within each namespace, names of all indexes in the namespace must be unique.

type
string

Type of the index. Default type is search.

analyzer
string
Default: "lucene.standard"
Enum: "lucene.standard" "lucene.simple" "lucene.whitespace" "lucene.keyword" "lucene.arabic" "lucene.armenian" "lucene.basque" "lucene.bengali" "lucene.brazilian" "lucene.bulgarian" "lucene.catalan" "lucene.chinese" "lucene.cjk" "lucene.czech" "lucene.danish" "lucene.dutch" "lucene.english" "lucene.finnish" "lucene.french" "lucene.galician" "lucene.german" "lucene.greek" "lucene.hindi" "lucene.hungarian" "lucene.indonesian" "lucene.irish" "lucene.italian" "lucene.japanese" "lucene.korean" "lucene.kuromoji" "lucene.latvian" "lucene.lithuanian" "lucene.morfologik" "lucene.nori" "lucene.norwegian" "lucene.persian" "lucene.portuguese" "lucene.romanian" "lucene.russian" "lucene.smartcn" "lucene.sorani" "lucene.spanish" "lucene.swedish" "lucene.thai" "lucene.turkish" "lucene.ukrainian"

Specific pre-defined method chosen to convert database field text into searchable words. This conversion reduces the text of fields into the smallest units of text. These units are called a term or token. This process, known as tokenization, involves a variety of changes made to the text in fields:

  • extracting words
  • removing punctuation
  • removing accents
  • changing to lowercase
  • removing common words
  • reducing words to their root form (stemming)
  • changing words to their base form (lemmatization) MongoDB Cloud uses the selected process to build the Atlas Search index.
Atlas Search Analyzers
Array of objects (analyzers)

List of user-defined methods to convert database field text into searchable words.

Custom Atlas Search Analyzers
object (mappings)

Index specifications for the collection's fields.

searchAnalyzer
string
Default: "lucene.standard"
Enum: "lucene.standard" "lucene.simple" "lucene.whitespace" "lucene.keyword" "lucene.arabic" "lucene.armenian" "lucene.basque" "lucene.bengali" "lucene.brazilian" "lucene.bulgarian" "lucene.catalan" "lucene.chinese" "lucene.cjk" "lucene.czech" "lucene.danish" "lucene.dutch" "lucene.english" "lucene.finnish" "lucene.french" "lucene.galician" "lucene.german" "lucene.greek" "lucene.hindi" "lucene.hungarian" "lucene.indonesian" "lucene.irish" "lucene.italian" "lucene.japanese" "lucene.korean" "lucene.kuromoji" "lucene.latvian" "lucene.lithuanian" "lucene.morfologik" "lucene.nori" "lucene.norwegian" "lucene.persian" "lucene.portuguese" "lucene.romanian" "lucene.russian" "lucene.smartcn" "lucene.sorani" "lucene.spanish" "lucene.swedish" "lucene.thai" "lucene.turkish" "lucene.ukrainian"

Method applied to identify words when searching this index.

storedSource
object

Flag that indicates whether to store all fields (true) on Atlas Search. By default, Atlas doesn't store (false) the fields on Atlas Search. Alternatively, you can specify an object that only contains the list of fields to store (include) or not store (exclude) on Atlas Search. To learn more, see documentation.

Stored Source Fields
Array of objects (Synonym Mapping Definition)

Rule sets that map words to their synonyms in this index.

Synonym Mapping

Responses

Request samples

Content type
application/json
Example
{
  • "collectionName": "string",
  • "database": "string",
  • "name": "string",
  • "type": "search",
  • "analyzer": "lucene.standard",
  • "analyzers": [
    ],
  • "mappings": {
    },
  • "searchAnalyzer": "lucene.standard",
  • "storedSource": {
    },
  • "synonyms": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "collectionName": "string",
  • "database": "string",
  • "indexID": "32b6e34b3d91647abb20e7b8",
  • "name": "string",
  • "status": "IN_PROGRESS",
  • "type": "search",
  • "analyzer": "lucene.standard",
  • "analyzers": [
    ],
  • "mappings": {
    },
  • "searchAnalyzer": "lucene.standard",
  • "storedSource": {
    },
  • "synonyms": [
    ]
}

Return All Atlas Search Indexes for One Collection

Returns all Atlas Search indexes on the specified collection. Atlas Search indexes contain the indexed fields and the analyzers used to create the indexes. To use this resource, the requesting API Key must have the Project Data Access Read Write role.

Atlas Search Indexes
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Name of the cluster that contains the collection with one or more Atlas Search indexes.

collectionName
required
string

Name of the collection that contains one or more Atlas Search indexes.

databaseName
required
string

Human-readable label that identifies the database that contains the collection with one or more Atlas Search indexes.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Remove One Atlas Search Index

Removes one Atlas Search index that you identified with its unique ID. To use this resource, the requesting API Key must have the Project Data Access Admin role.

Atlas Search Indexes
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Name of the cluster that contains the database and collection with one or more Application Search indexes.

indexId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the Atlas Search index. Use the Get All Atlas Search Indexes for a Collection API endpoint to find the IDs of all Atlas Search indexes.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{ }

Return One Atlas Search Index

Returns one Atlas Search index in the specified project. You identify this index using its unique ID. Atlas Search index contains the indexed fields and the analyzers used to create the index. To use this resource, the requesting API Key must have the Project Data Access Read Write role.

Atlas Search Indexes
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Name of the cluster that contains the collection with one or more Atlas Search indexes.

indexId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the Application Search index. Use the Get All Application Search Indexes for a Collection API endpoint to find the IDs of all Application Search indexes.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
Example
{
  • "collectionName": "string",
  • "database": "string",
  • "indexID": "32b6e34b3d91647abb20e7b8",
  • "name": "string",
  • "status": "IN_PROGRESS",
  • "type": "search",
  • "analyzer": "lucene.standard",
  • "analyzers": [
    ],
  • "mappings": {
    },
  • "searchAnalyzer": "lucene.standard",
  • "storedSource": {
    },
  • "synonyms": [
    ]
}

Update One Atlas Search Index

Updates one Atlas Search index that you identified with its unique ID. Atlas Search indexes define the fields on which to create the index and the analyzers to use when creating the index. To use this resource, the requesting API Key must have the Project Data Access Admin role.

Atlas Search Indexes
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Name of the cluster that contains the collection whose Atlas Search index to update.

indexId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the Atlas Search index. Use the Get All Atlas Search Indexes for a Collection API endpoint to find the IDs of all Atlas Search indexes.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Details to update on the Atlas Search index.

collectionName
required
string

Human-readable label that identifies the collection that contains one or more Atlas Search indexes.

database
required
string

Human-readable label that identifies the database that contains the collection with one or more Atlas Search indexes.

name
required
string

Human-readable label that identifies this index. Within each namespace, names of all indexes in the namespace must be unique.

type
string

Type of the index. Default type is search.

analyzer
string
Default: "lucene.standard"
Enum: "lucene.standard" "lucene.simple" "lucene.whitespace" "lucene.keyword" "lucene.arabic" "lucene.armenian" "lucene.basque" "lucene.bengali" "lucene.brazilian" "lucene.bulgarian" "lucene.catalan" "lucene.chinese" "lucene.cjk" "lucene.czech" "lucene.danish" "lucene.dutch" "lucene.english" "lucene.finnish" "lucene.french" "lucene.galician" "lucene.german" "lucene.greek" "lucene.hindi" "lucene.hungarian" "lucene.indonesian" "lucene.irish" "lucene.italian" "lucene.japanese" "lucene.korean" "lucene.kuromoji" "lucene.latvian" "lucene.lithuanian" "lucene.morfologik" "lucene.nori" "lucene.norwegian" "lucene.persian" "lucene.portuguese" "lucene.romanian" "lucene.russian" "lucene.smartcn" "lucene.sorani" "lucene.spanish" "lucene.swedish" "lucene.thai" "lucene.turkish" "lucene.ukrainian"

Specific pre-defined method chosen to convert database field text into searchable words. This conversion reduces the text of fields into the smallest units of text. These units are called a term or token. This process, known as tokenization, involves a variety of changes made to the text in fields:

  • extracting words
  • removing punctuation
  • removing accents
  • changing to lowercase
  • removing common words
  • reducing words to their root form (stemming)
  • changing words to their base form (lemmatization) MongoDB Cloud uses the selected process to build the Atlas Search index.
Atlas Search Analyzers
Array of objects (analyzers)

List of user-defined methods to convert database field text into searchable words.

Custom Atlas Search Analyzers
object (mappings)

Index specifications for the collection's fields.

searchAnalyzer
string
Default: "lucene.standard"
Enum: "lucene.standard" "lucene.simple" "lucene.whitespace" "lucene.keyword" "lucene.arabic" "lucene.armenian" "lucene.basque" "lucene.bengali" "lucene.brazilian" "lucene.bulgarian" "lucene.catalan" "lucene.chinese" "lucene.cjk" "lucene.czech" "lucene.danish" "lucene.dutch" "lucene.english" "lucene.finnish" "lucene.french" "lucene.galician" "lucene.german" "lucene.greek" "lucene.hindi" "lucene.hungarian" "lucene.indonesian" "lucene.irish" "lucene.italian" "lucene.japanese" "lucene.korean" "lucene.kuromoji" "lucene.latvian" "lucene.lithuanian" "lucene.morfologik" "lucene.nori" "lucene.norwegian" "lucene.persian" "lucene.portuguese" "lucene.romanian" "lucene.russian" "lucene.smartcn" "lucene.sorani" "lucene.spanish" "lucene.swedish" "lucene.thai" "lucene.turkish" "lucene.ukrainian"

Method applied to identify words when searching this index.

storedSource
object

Flag that indicates whether to store all fields (true) on Atlas Search. By default, Atlas doesn't store (false) the fields on Atlas Search. Alternatively, you can specify an object that only contains the list of fields to store (include) or not store (exclude) on Atlas Search. To learn more, see documentation.

Stored Source Fields
Array of objects (Synonym Mapping Definition)

Rule sets that map words to their synonyms in this index.

Synonym Mapping

Responses

Request samples

Content type
application/json
Example
{
  • "collectionName": "string",
  • "database": "string",
  • "name": "string",
  • "type": "search",
  • "analyzer": "lucene.standard",
  • "analyzers": [
    ],
  • "mappings": {
    },
  • "searchAnalyzer": "lucene.standard",
  • "storedSource": {
    },
  • "synonyms": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "collectionName": "string",
  • "database": "string",
  • "indexID": "32b6e34b3d91647abb20e7b8",
  • "name": "string",
  • "status": "IN_PROGRESS",
  • "type": "search",
  • "analyzer": "lucene.standard",
  • "analyzers": [
    ],
  • "mappings": {
    },
  • "searchAnalyzer": "lucene.standard",
  • "storedSource": {
    },
  • "synonyms": [
    ]
}

Auditing

Returns and edits database auditing settings for MongoDB Cloud projects.

Return the Auditing Configuration for One Project

Returns the auditing configuration for the specified project. The auditing configuration defines the events that MongoDB Cloud records in the audit log. To use this resource, the requesting API Key must have the Project Owner role. This feature isn't available for M0, M2, M5, or serverless clusters.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "auditAuthorizationSuccess": false,
  • "auditFilter": "string",
  • "configurationType": "NONE",
  • "enabled": false
}

Update Auditing Configuration for One Project

Updates the auditing configuration for the specified project. The auditing configuration defines the events that MongoDB Cloud records in the audit log. To use this resource, the requesting API Key must have the Project Owner role. This feature isn't available for M0, M2, M5, or serverless clusters.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Updated auditing configuration for the specified project.

auditAuthorizationSuccess
boolean
Default: false

Flag that indicates whether someone set auditing to track successful authentications. This only applies to the "atype" : "authCheck" audit filter. Setting this parameter to true degrades cluster performance.

System Auditing Messages
auditFilter
string

JSON document that specifies which events to record. Escape any characters that may prevent parsing, such as single or double quotes, using a backslash (\).

Custom Auditing Filter
enabled
boolean
Default: false

Flag that indicates whether someone enabled database auditing for the specified project.

Responses

Request samples

Content type
application/json
{
  • "auditAuthorizationSuccess": false,
  • "auditFilter": "string",
  • "enabled": false
}

Response samples

Content type
application/json
{
  • "auditAuthorizationSuccess": false,
  • "auditFilter": "string",
  • "configurationType": "NONE",
  • "enabled": false
}

AWS Clusters DNS

Returns and edits custom DNS configurations for MongoDB Cloud database deployments on AWS. The resource requires your Project ID. If you use the VPC peering on AWS and you use your own DNS servers instead of Amazon Route 53, enable custom DNS. Before 31 March 2020, applications deployed within AWS using custom DNS services and VPC-peered with MongoDB Cloud couldn't connect over private IP addresses. Custom DNS resolved to public IP addresses. AWS internal DNS resolved to private IP addresses. Applications deployed with custom DNS services in AWS should use Private IP for Peering connection strings.

Return One Custom DNS Configuration for Atlas Clusters on AWS

Returns the custom DNS configuration for AWS clusters in the specified project. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "enabled": true
}

Toggle State of One Custom DNS Configuration for Atlas Clusters on AWS

Enables or disables the custom DNS configuration for AWS clusters in the specified project. Enable custom DNS if you use AWS VPC peering and use your own DNS servers. To use this resource, the requesting API Key must have the Project Atlas Admin role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Enables or disables the custom DNS configuration for AWS clusters in the specified project.

enabled
required
boolean

Flag that indicates whether the project's clusters deployed to Amazon Web Services (AWS) use a custom Domain Name System (DNS). When "enabled": true, connect to your cluster using Private IP for Peering connection strings.

To learn more, see FAQ: Connection String Options in the MongoDB Atlas documentation.

Responses

Request samples

Content type
application/json
{
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "enabled": true
}

Cloud Backups

Manages Cloud Backup snapshots, snapshot export buckets, restore jobs, and schedules. This resource applies only to clusters that use Cloud Backups.

Return All Snapshot Export Buckets

Returns all Export Buckets associated with the specified project. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{}

Create One Snapshot Export Bucket

Creates an Export Bucket for a given AWS S3 Bucket. Once created, snapshots can be exported to the Export Bucket and its referenced AWS S3 Bucket. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Specifies the AWS S3 Bucket and IAM role that the Export Bucket should reference.

bucketName
required
string [ 3 .. 63 ] characters

Human-readable label that identifies the AWS S3 Bucket or Azure Storage Container that the role is authorized to export to.

cloudProvider
required
string
Enum: "AWS" "AZURE"

Human-readable label that identifies the cloud provider that Snapshots are exported to.

iamRoleId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal character string that identifies the Unified AWS Access role ID that MongoDB Cloud uses to access the AWS S3 bucket.

Responses

Request samples

Content type
application/json
{
  • "bucketName": "export-bucket",
  • "cloudProvider": "AWS",
  • "iamRoleId": "32b6e34b3d91647abb20e7b8"
}

Response samples

Content type
application/json
{
  • "_id": "32b6e34b3d91647abb20e7b8",
  • "bucketName": "export-bucket",
  • "cloudProvider": "AWS",
  • "iamRoleId": "32b6e34b3d91647abb20e7b8",
  • "links": []
}

Delete One Snapshot Export Bucket

Deletes an Export Bucket. Auto export must be disabled on all clusters in this Project exporting to this Export Bucket before revoking access. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

exportBucketId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal character string that identifies the Export Bucket.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Responses

Response samples

Content type
application/json
{ }

Return One Snapshot Export Bucket

Returns one Export Bucket associated with the specified Project. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

exportBucketId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal character string that identifies the Export Bucket.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Responses

Response samples

Content type
application/json
{
  • "_id": "32b6e34b3d91647abb20e7b8",
  • "bucketName": "export-bucket",
  • "cloudProvider": "AWS",
  • "iamRoleId": "32b6e34b3d91647abb20e7b8",
  • "links": []
}

Return the Backup Compliance Policy settings

Returns the Backup Compliance Policy settings with the specified project. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "authorizedEmail": "user@example.com",
  • "authorizedUserFirstName": "string",
  • "authorizedUserLastName": "string",
  • "copyProtectionEnabled": false,
  • "encryptionAtRestEnabled": false,
  • "onDemandPolicyItem": {
    },
  • "pitEnabled": false,
  • "projectId": "32b6e34b3d91647abb20e7b8",
  • "restoreWindowDays": 0,
  • "scheduledPolicyItems": [
    ],
  • "state": "ACTIVE",
  • "updatedDate": "2019-08-24T14:15:22Z",
  • "updatedUser": "user@example.com"
}

Update or enable the Backup Compliance Policy settings

Updates the Backup Compliance Policy settings for the specified project. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

overwriteBackupPolicies
boolean
Default: true

Flag that indicates whether to overwrite non complying backup policies with the new data protection settings or not.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

The new Backup Compliance Policy settings.

authorizedEmail
required
string <email>

Email address of the user who authorized to update the Backup Compliance Policy settings.

authorizedUserFirstName
string

First name of the user who authorized to update the Backup Compliance Policy settings.

authorizedUserLastName
string

Last name of the user who authorized to update the Backup Compliance Policy settings.

copyProtectionEnabled
boolean
Default: false

Flag that indicates whether to prevent cluster users from deleting backups copied to other regions, even if those additional snapshot regions are removed. If unspecified, this value defaults to false.

encryptionAtRestEnabled
boolean
Default: false

Flag that indicates whether Encryption at Rest using Customer Key Management is required for all clusters with a Backup Compliance Policy. If unspecified, this value defaults to false.

Encryption at Rest using Customer Key Management
object (BackupComplianceOnDemandPolicyItem)

Specifications for on-demand policy.

pitEnabled
boolean
Default: false

Flag that indicates whether the cluster uses Continuous Cloud Backups with a Backup Compliance Policy. If unspecified, this value defaults to false.

Continuous Cloud Backups
projectId
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the project for the Backup Compliance Policy.

restoreWindowDays
integer <int32>

Number of previous days that you can restore back to with Continuous Cloud Backup with a Backup Compliance Policy. You must specify a positive, non-zero integer, and the maximum retention window can't exceed the hourly retention time. This parameter applies only to Continuous Cloud Backups with a Backup Compliance Policy.

Array of objects (BackupComplianceScheduledPolicyItem)

List that contains the specifications for one scheduled policy.

Responses

Request samples

Content type
application/json
{
  • "authorizedEmail": "user@example.com",
  • "authorizedUserFirstName": "string",
  • "authorizedUserLastName": "string",
  • "copyProtectionEnabled": false,
  • "encryptionAtRestEnabled": false,
  • "onDemandPolicyItem": {
    },
  • "pitEnabled": false,
  • "projectId": "32b6e34b3d91647abb20e7b8",
  • "restoreWindowDays": 0,
  • "scheduledPolicyItems": [
    ]
}

Response samples

Content type
application/json
{
  • "authorizedEmail": "user@example.com",
  • "authorizedUserFirstName": "string",
  • "authorizedUserLastName": "string",
  • "copyProtectionEnabled": false,
  • "encryptionAtRestEnabled": false,
  • "onDemandPolicyItem": {
    },
  • "pitEnabled": false,
  • "projectId": "32b6e34b3d91647abb20e7b8",
  • "restoreWindowDays": 0,
  • "scheduledPolicyItems": [
    ],
  • "state": "ACTIVE",
  • "updatedDate": "2019-08-24T14:15:22Z",
  • "updatedUser": "user@example.com"
}

Return All Snapshot Export Jobs

Returns all Cloud Backup Snapshot Export Jobs associated with the specified Atlas cluster. To use this resource, the requesting API Key must have the Project Atlas Admin role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

Responses

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Create One Snapshot Export Job

Exports one backup Snapshot for dedicated Atlas cluster using Cloud Backups to an Export Bucket. To use this resource, the requesting API Key must have the Project Atlas Admin role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Request Body schema: application/json

Information about the Cloud Backup Snapshot Export Job to create.

Array of objects (BackupLabel)

Collection of key-value pairs that represent custom data to add to the metadata file that MongoDB Cloud uploads to the bucket when the export job finishes.

exportBucketId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal character string that identifies the Export Bucket.

snapshotId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal character string that identifies the Cloud Backup Snapshot to export.

Responses

Request samples

Content type
application/json
{
  • "customData": [
    ],
  • "exportBucketId": "32b6e34b3d91647abb20e7b8",
  • "snapshotId": "32b6e34b3d91647abb20e7b8"
}

Response samples

Content type
application/json
{
  • "components": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "customData": [
    ],
  • "exportBucketId": "32b6e34b3d91647abb20e7b8",
  • "exportStatus": {
    },
  • "finishedAt": "2019-08-24T14:15:22Z",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "links": [],
  • "prefix": "string",
  • "snapshotId": "32b6e34b3d91647abb20e7b8",
  • "state": "Cancelled"
}

Return One Snapshot Export Job

Returns one Cloud Backup Snapshot Export Job associated with the specified Atlas cluster. To use this resource, the requesting API Key must have the Project Atlas Admin role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster.

exportId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal character string that identifies the Export Job.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Responses

Response samples

Content type
application/json
{
  • "components": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "customData": [
    ],
  • "exportBucketId": "32b6e34b3d91647abb20e7b8",
  • "exportStatus": {
    },
  • "finishedAt": "2019-08-24T14:15:22Z",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "links": [],
  • "prefix": "string",
  • "snapshotId": "32b6e34b3d91647abb20e7b8",
  • "state": "Cancelled"
}

Return All Restore Jobs for One Cluster

Returns all cloud backup restore jobs for one cluster from the specified project. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster with the restore jobs you want to return.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Restore One Snapshot of One Cluster

Restores one snapshot of one cluster from the specified project. Atlas takes on-demand snapshots immediately and scheduled snapshots at regular intervals. If an on-demand snapshot with a status of queued or inProgress exists, before taking another snapshot, wait until Atlas completes completes processing the previously taken on-demand snapshot.

To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Restores one snapshot of one cluster from the specified project.

deliveryType
required
string
Enum: "automated" "download" "pointInTime"

Human-readable label that categorizes the restore job to create.

oplogInc
integer <int32> >= 1

Oplog operation number from which you want to restore this snapshot. This number represents the second part of an Oplog timestamp. The resource returns this parameter when "deliveryType" : "pointInTime" and oplogTs exceeds 0.

oplogTs
integer <int32> >= 1199145600

Date and time from which you want to restore this snapshot. This parameter expresses this timestamp in the number of seconds that have elapsed since the UNIX epoch. This number represents the first part of an Oplog timestamp. The resource returns this parameter when "deliveryType" : "pointInTime" and oplogTs exceeds 0.

pointInTimeUTCSeconds
integer <int32> >= 1199145600

Date and time from which MongoDB Cloud restored this snapshot. This parameter expresses this timestamp in the number of seconds that have elapsed since the UNIX epoch. The resource returns this parameter when "deliveryType" : "pointInTime" and pointInTimeUTCSeconds exceeds 0.

snapshotId
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal character string that identifies the snapshot.

targetClusterName
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the target cluster to which the restore job restores the snapshot. The resource returns this parameter when "deliveryType": "automated". Required for automated and pointInTime restore types.

targetGroupId
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the target project for the specified targetClusterName. Required for automated and pointInTime restore types.

Responses

Request samples

Content type
application/json
{
  • "deliveryType": "automated",
  • "oplogInc": 1,
  • "oplogTs": 1199145600,
  • "pointInTimeUTCSeconds": 1199145600,
  • "snapshotId": "32b6e34b3d91647abb20e7b8",
  • "targetClusterName": "string",
  • "targetGroupId": "32b6e34b3d91647abb20e7b8"
}

Response samples

Content type
application/json
{
  • "cancelled": true,
  • "components": [
    ],
  • "deliveryType": "automated",
  • "deliveryUrl": [
    ],
  • "desiredTimestamp": {
    },
  • "expired": true,
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "failed": true,
  • "finishedAt": "2019-08-24T14:15:22Z",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "links": [],
  • "oplogInc": 1,
  • "oplogTs": 1199145600,
  • "pointInTimeUTCSeconds": 1199145600,
  • "privateDownloadDeliveryUrls": [
    ],
  • "snapshotId": "32b6e34b3d91647abb20e7b8",
  • "targetClusterName": "string",
  • "targetGroupId": "32b6e34b3d91647abb20e7b8",
  • "timestamp": "2019-08-24T14:15:22Z"
}

Cancel One Restore Job of One Cluster

Cancels one cloud backup restore job of one cluster from the specified project. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster.

restoreJobId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the restore job to remove.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{ }

Return One Restore Job of One Cluster

Returns one cloud backup restore job for one cluster from the specified project. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster with the restore jobs you want to return.

restoreJobId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the restore job to return.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "cancelled": true,
  • "components": [
    ],
  • "deliveryType": "automated",
  • "deliveryUrl": [
    ],
  • "desiredTimestamp": {
    },
  • "expired": true,
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "failed": true,
  • "finishedAt": "2019-08-24T14:15:22Z",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "links": [],
  • "oplogInc": 1,
  • "oplogTs": 1199145600,
  • "pointInTimeUTCSeconds": 1199145600,
  • "privateDownloadDeliveryUrls": [
    ],
  • "snapshotId": "32b6e34b3d91647abb20e7b8",
  • "targetClusterName": "string",
  • "targetGroupId": "32b6e34b3d91647abb20e7b8",
  • "timestamp": "2019-08-24T14:15:22Z"
}

Remove All Cloud Backup Schedules

Removes all cloud backup schedules for the specified cluster. This schedule defines when MongoDB Cloud takes scheduled snapshots and how long it stores those snapshots. To use this resource, the requesting API Key must have the Project Atlas Admin role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Responses

Response samples

Content type
application/json
{
  • "autoExportEnabled": true,
  • "clusterId": "32b6e34b3d91647abb20e7b8",
  • "clusterName": "string",
  • "copySettings": [
    ],
  • "export": {
    },
  • "extraRetentionSettings": [
    ],
  • "links": [],
  • "nextSnapshot": "2019-08-24T14:15:22Z",
  • "policies": [
    ],
  • "referenceHourOfDay": 0,
  • "referenceMinuteOfHour": 0,
  • "restoreWindowDays": 0,
  • "useOrgAndGroupNamesInExportPrefix": true
}

Return One Cloud Backup Schedule

Returns the cloud backup schedule for the specified cluster within the specified project. This schedule defines when MongoDB Cloud takes scheduled snapshots and how long it stores those snapshots. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "autoExportEnabled": true,
  • "clusterId": "32b6e34b3d91647abb20e7b8",
  • "clusterName": "string",
  • "copySettings": [
    ],
  • "export": {
    },
  • "extraRetentionSettings": [
    ],
  • "links": [],
  • "nextSnapshot": "2019-08-24T14:15:22Z",
  • "policies": [
    ],
  • "referenceHourOfDay": 0,
  • "referenceMinuteOfHour": 0,
  • "restoreWindowDays": 0,
  • "useOrgAndGroupNamesInExportPrefix": true
}

Update Cloud Backup Schedule for One Cluster

Updates the cloud backup schedule for one cluster within the specified project. This schedule defines when MongoDB Cloud takes scheduled snapshots and how long it stores those snapshots. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Updates the cloud backup schedule for one cluster within the specified project.

Note: In the request body, provide only the fields that you want to update.

autoExportEnabled
boolean

Flag that indicates whether MongoDB Cloud automatically exports Cloud Backup Snapshots to the Export Bucket.

Array of objects (DiskBackupCopySetting)

List that contains a document for each copy setting item in the desired backup policy.

Array of objects (DeleteCopiedBackups)

List that contains a document for each deleted copy setting whose backup copies you want to delete.

object (export)

Policy for automatically exporting Cloud Backup Snapshots.

Array of objects (ExtraRetentionSetting)

List that contains a document for each extra retention setting item in the desired backup policy.

Array of objects (AdvancedDiskBackupSnapshotSchedulePolicy) <= 1 items

Rules set for this backup schedule.

referenceHourOfDay
integer <int32>

Hour of day in Coordinated Universal Time (UTC) that represents when MongoDB Cloud takes the Snapshot.

referenceMinuteOfHour
integer <int32>

Minute of the referenceHourOfDay that represents when MongoDB Cloud takes the Snapshot.

restoreWindowDays
integer <int32>

Number of previous days that you can restore back to with Continuous Cloud Backup accuracy. You must specify a positive, non-zero integer. This parameter applies to continuous Cloud Backups only.

updateSnapshots
boolean

Flag that indicates whether to apply the retention changes in the updated backup policy to Snapshots that MongoDB Cloud took previously.

useOrgAndGroupNamesInExportPrefix
boolean

Flag that indicates whether to use organization and project names instead of organization and project UUIDs in the path to the metadata files that MongoDB Cloud uploads to your Export Bucket.

Responses

Request samples

Content type
application/json
{
  • "autoExportEnabled": true,
  • "copySettings": [
    ],
  • "deleteCopiedBackups": [
    ],
  • "export": {
    },
  • "extraRetentionSettings": [
    ],
  • "policies": [
    ],
  • "referenceHourOfDay": 0,
  • "referenceMinuteOfHour": 0,
  • "restoreWindowDays": 0,
  • "updateSnapshots": true,
  • "useOrgAndGroupNamesInExportPrefix": true
}

Response samples

Content type
application/json
{
  • "autoExportEnabled": true,
  • "clusterId": "32b6e34b3d91647abb20e7b8",
  • "clusterName": "string",
  • "copySettings": [
    ],
  • "export": {
    },
  • "extraRetentionSettings": [
    ],
  • "links": [],
  • "nextSnapshot": "2019-08-24T14:15:22Z",
  • "policies": [
    ],
  • "referenceHourOfDay": 0,
  • "referenceMinuteOfHour": 0,
  • "restoreWindowDays": 0,
  • "useOrgAndGroupNamesInExportPrefix": true
}

Return All Replica Set Cloud Backups

Returns all snapshots of one cluster from the specified project. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Take One On-Demand Snapshot

Takes one on-demand snapshot for the specified cluster. Atlas takes on-demand snapshots immediately and scheduled snapshots at regular intervals. If an on-demand snapshot with a status of queued or inProgress exists, before taking another snapshot, wait until Atlas completes completes processing the previously taken on-demand snapshot.

To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Takes one on-demand snapshot.

description
string

Human-readable phrase or sentence that explains the purpose of the snapshot. The resource returns this parameter when "status" : "onDemand".

retentionInDays
integer <int32> >= 1

Number of days that MongoDB Cloud should retain the on-demand snapshot. Must be at least 1.

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "retentionInDays": 1
}

Response samples

Content type
application/json
Example
{
  • "cloudProvider": "AWS",
  • "copyRegions": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "frequencyType": "hourly",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "links": [],
  • "masterKeyUUID": "72659f08-8b3c-4913-bb4e-a8a68e036502",
  • "mongodVersion": "string",
  • "policyItems": [
    ],
  • "replicaSetName": "string",
  • "snapshotType": "onDemand",
  • "status": "queued",
  • "storageSizeBytes": 0,
  • "type": "replicaSet"
}

Remove One Sharded Cluster Cloud Backup

Removes one snapshot of one sharded cluster from the specified project. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster.

snapshotId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the desired snapshot.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{ }

Return One Sharded Cluster Cloud Backup

Returns one snapshot of one sharded cluster from the specified project. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster.

snapshotId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the desired snapshot.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "configServerType": "EMBEDDED",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "frequencyType": "hourly",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "links": [],
  • "masterKeyUUID": "72659f08-8b3c-4913-bb4e-a8a68e036502",
  • "members": [
    ],
  • "mongodVersion": "string",
  • "policyItems": [
    ],
  • "snapshotIds": [
    ],
  • "snapshotType": "onDemand",
  • "status": "queued",
  • "storageSizeBytes": 0,
  • "type": "replicaSet"
}

Return All Sharded Cluster Cloud Backups

Returns all snapshots of one sharded cluster from the specified project. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Remove One Replica Set Cloud Backup

Removes the specified snapshot. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster.

snapshotId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the desired snapshot.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{ }

Return One Replica Set Cloud Backup

Returns one snapshot from the specified cluster. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster.

snapshotId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the desired snapshot.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "cloudProvider": "AWS",
  • "copyRegions": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "frequencyType": "hourly",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "links": [],
  • "masterKeyUUID": "72659f08-8b3c-4913-bb4e-a8a68e036502",
  • "mongodVersion": "string",
  • "policyItems": [
    ],
  • "replicaSetName": "string",
  • "snapshotType": "onDemand",
  • "status": "queued",
  • "storageSizeBytes": 0,
  • "type": "replicaSet"
}

Change Expiration Date for One Cloud Backup

Changes the expiration date for one cloud backup snapshot for one cluster in the specified project.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster.

snapshotId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the desired snapshot.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Changes the expiration date for one cloud backup snapshot for one cluster in the specified project.

retentionUnit
required
string
Enum: "DAYS" "WEEKS" "MONTHS" "YEARS"

Quantity of time in which MongoDB Cloud measures snapshot retention.

retentionValue
required
integer <int32>

Number that indicates the amount of days, weeks, months, or years that MongoDB Cloud retains the snapshot. For less frequent policy items, MongoDB Cloud requires that you specify a value greater than or equal to the value specified for more frequent policy items. If the hourly policy item specifies a retention of two days, specify two days or greater for the retention of the weekly policy item.

Responses

Request samples

Content type
application/json
{
  • "retentionUnit": "DAYS",
  • "retentionValue": 5
}

Response samples

Content type
application/json
{
  • "cloudProvider": "AWS",
  • "copyRegions": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "frequencyType": "hourly",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "links": [],
  • "masterKeyUUID": "72659f08-8b3c-4913-bb4e-a8a68e036502",
  • "mongodVersion": "string",
  • "policyItems": [
    ],
  • "replicaSetName": "string",
  • "snapshotType": "onDemand",
  • "status": "queued",
  • "storageSizeBytes": 0,
  • "type": "replicaSet"
}

Return All Restore Jobs for One Serverless Instance

Returns all restore jobs for one serverless instance from the specified project. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the serverless instance.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Restore One Snapshot of One Serverless Instance

Restores one snapshot of one serverless instance from the specified project. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the serverless instance whose snapshot you want to restore.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Restores one snapshot of one serverless instance from the specified project.

deliveryType
required
string
Enum: "automated" "download" "pointInTime"

Human-readable label that categorizes the restore job to create.

oplogInc
integer <int32> >= 1

Oplog operation number from which you want to restore this snapshot. This number represents the second part of an Oplog timestamp. The resource returns this parameter when "deliveryType" : "pointInTime" and oplogTs exceeds 0.

oplogTs
integer <int32> >= 1199145600

Date and time from which you want to restore this snapshot. This parameter expresses this timestamp in the number of seconds that have elapsed since the UNIX epoch. This number represents the first part of an Oplog timestamp. The resource returns this parameter when "deliveryType" : "pointInTime" and oplogTs exceeds 0.

pointInTimeUTCSeconds
integer <int32> >= 1199145600

Date and time from which MongoDB Cloud restored this snapshot. This parameter expresses this timestamp in the number of seconds that have elapsed since the UNIX epoch. The resource returns this parameter when "deliveryType" : "pointInTime" and pointInTimeUTCSeconds exceeds 0.

snapshotId
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal character string that identifies the snapshot.

targetClusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the target cluster to which the restore job restores the snapshot. The resource returns this parameter when "deliveryType": "automated".

targetGroupId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the target project for the specified targetClusterName.

Responses

Request samples

Content type
application/json
{
  • "deliveryType": "automated",
  • "oplogInc": 1,
  • "oplogTs": 1199145600,
  • "pointInTimeUTCSeconds": 1199145600,
  • "snapshotId": "32b6e34b3d91647abb20e7b8",
  • "targetClusterName": "string",
  • "targetGroupId": "32b6e34b3d91647abb20e7b8"
}

Response samples

Content type
application/json
{
  • "cancelled": true,
  • "deliveryType": "automated",
  • "deliveryUrl": [
    ],
  • "desiredTimestamp": {
    },
  • "expired": true,
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "failed": true,
  • "finishedAt": "2019-08-24T14:15:22Z",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "links": [],
  • "oplogInc": 1,
  • "oplogTs": 1199145600,
  • "pointInTimeUTCSeconds": 1199145600,
  • "snapshotId": "32b6e34b3d91647abb20e7b8",
  • "targetClusterName": "string",
  • "targetGroupId": "32b6e34b3d91647abb20e7b8",
  • "timestamp": "2019-08-24T14:15:22Z"
}

Return One Restore Job for One Serverless Instance

Returns one restore job for one serverless instance from the specified project. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the serverless instance.

restoreJobId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the restore job to return.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "cancelled": true,
  • "deliveryType": "automated",
  • "deliveryUrl": [
    ],
  • "desiredTimestamp": {
    },
  • "expired": true,
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "failed": true,
  • "finishedAt": "2019-08-24T14:15:22Z",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "links": [],
  • "oplogInc": 1,
  • "oplogTs": 1199145600,
  • "pointInTimeUTCSeconds": 1199145600,
  • "snapshotId": "32b6e34b3d91647abb20e7b8",
  • "targetClusterName": "string",
  • "targetGroupId": "32b6e34b3d91647abb20e7b8",
  • "timestamp": "2019-08-24T14:15:22Z"
}

Return All Snapshots of One Serverless Instance

Returns all snapshots of one serverless instance from the specified project. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the serverless instance.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

Responses

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Return One Snapshot of One Serverless Instance

Returns one snapshot of one serverless instance from the specified project. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the serverless instance.

snapshotId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies the desired snapshot.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Responses

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "frequencyType": "hourly",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "links": [],
  • "mongodVersion": "string",
  • "serverlessInstanceName": "string",
  • "snapshotType": "onDemand",
  • "status": "queued",
  • "storageSizeBytes": 0
}

Cloud Migration Service

Manages the Cloud Migration Service. Source organizations, projects, and MongoDB clusters reside on Cloud Manager or Ops Manager. Destination organizations, projects, and MongoDB clusters reside on MongoDB Cloud. Source databases can't use any authentication except SCRAM-SHA.

Migrate One Local Managed Cluster to MongoDB Atlas

Migrate one cluster that Cloud or Ops Manager manages to MongoDB Atlas.

Please make sure to validate your migration before initiating it.

You can use this API endpoint for push live migrations only. Your API Key must have the Organization Owner role to successfully call this resource.

NOTE: Migrating time-series collections is not yet supported on MongoDB 6.0 or higher. Migrations on MongoDB 6.0 or higher will skip any time-series collections on the source cluster.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

One migration to be created.

required
object (Destination)

Document that describes the destination of the migration.

dropEnabled
required
boolean

Flag that indicates whether the migration process drops all collections from the destination cluster before the migration starts.

migrationHosts
Array of strings = 1 items

List of migration hosts used for this migration.

object (ShardingRequest)

Document that configures sharding on the destination cluster when migrating from a replica set source to a sharded cluster destination on MongoDB 6.0 or higher. If you don't wish to shard any collections on the destination cluster, leave this empty.

required
object (Source)

Document that describes the source of the migration.

Responses

Request samples

Content type
application/json
{
  • "destination": {
    },
  • "dropEnabled": true,
  • "migrationHosts": [
    ],
  • "sharding": {
    },
  • "source": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "32b6e34b3d91647abb20e7b8",
  • "lagTimeSeconds": 0,
  • "migrationHosts": [
    ],
  • "readyForCutover": true,
  • "status": "NEW"
}

Validate One Migration Request

Verifies whether the provided credentials, available disk space, MongoDB versions, and so on meet the requirements of the migration request. If the check passes, the migration can proceed. Your API Key must have the Organization Owner role to successfully call this resource.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

One migration to be validated.

required
object (Destination)

Document that describes the destination of the migration.

dropEnabled
required
boolean

Flag that indicates whether the migration process drops all collections from the destination cluster before the migration starts.

migrationHosts
Array of strings = 1 items

List of migration hosts used for this migration.

object (ShardingRequest)

Document that configures sharding on the destination cluster when migrating from a replica set source to a sharded cluster destination on MongoDB 6.0 or higher. If you don't wish to shard any collections on the destination cluster, leave this empty.

required
object (Source)

Document that describes the source of the migration.

Responses

Request samples

Content type
application/json
{
  • "destination": {
    },
  • "dropEnabled": true,
  • "migrationHosts": [
    ],
  • "sharding": {
    },
  • "source": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "32b6e34b3d91647abb20e7b8",
  • "errorMessage": "string",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "sourceGroupId": "32b6e34b3d91647abb20e7b8",
  • "status": "PENDING"
}

Return One Migration Validation Job

Return the status of one migration validation job. Your API Key must have the Organization Owner role to successfully call this resource.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

validationId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 507f1f77bcf86cd799439011

Unique 24-hexadecimal digit string that identifies the validation job.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Responses

Response samples

Content type
application/json
{
  • "_id": "32b6e34b3d91647abb20e7b8",
  • "errorMessage": "string",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "sourceGroupId": "32b6e34b3d91647abb20e7b8",
  • "status": "PENDING"
}

Return One Migration Job

Return details of one cluster migration job. Each push live migration job uses one migration host. Your API Key must have the Organization Member role to successfully call this resource.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

liveMigrationId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 6296fb4c7c7aa997cf94e9a8

Unique 24-hexadecimal digit string that identifies the migration.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "_id": "32b6e34b3d91647abb20e7b8",
  • "lagTimeSeconds": 0,
  • "migrationHosts": [
    ],
  • "readyForCutover": true,
  • "status": "NEW"
}

Cut Over the Migrated Cluster

Cut over the migrated cluster to MongoDB Atlas. Confirm when the cut over completes. When the cut over completes, MongoDB Atlas completes the live migration process and stops synchronizing with the source cluster. Your API Key must have the Organization Owner role to successfully call this resource.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

liveMigrationId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 6296fb4c7c7aa997cf94e9a8

Unique 24-hexadecimal digit string that identifies the migration.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "detail": "(This is just an example, the exception may not be related to this endpoint) No provider AWS exists.",
  • "error": 400,
  • "errorCode": "VALIDATION_ERROR",
  • "reason": "Bad Request"
}

Return All Projects Available for Migration

Return all projects that you can migrate to the specified organization.

Authorizations:
DigestAuthServiceAccounts
path Parameters
orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Remove One Link-Token

Remove one organization link and its associated public API key. MongoDB Atlas uses the link-token for push live migrations only. Live migrations (push) let you securely push data from Cloud Manager or Ops Manager into MongoDB Atlas. Your API Key must have the Organization Owner role to successfully call this resource.

Authorizations:
DigestAuthServiceAccounts
path Parameters
orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Responses

Response samples

Content type
application/json
{ }

Create One Link-Token

Create one link-token that contains all the information required to complete the link. MongoDB Atlas uses the link-token for push live migrations only. Live migration (push) allows you to securely push data from Cloud Manager or Ops Manager into MongoDB Atlas. Your API Key must have the Organization Owner role to successfully call this resource.

Authorizations:
DigestAuthServiceAccounts
path Parameters
orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

IP address access list entries associated with the migration.

accessListIps
Array of strings

IP address access list entries associated with the API key.

Responses

Request samples

Content type
application/json
{
  • "accessListIps": [
    ]
}

Response samples

Content type
application/json
{
  • "linkToken": "string"
}

Cloud Provider Access

Returns, adds, authorizes, and removes AWS IAM roles in Atlas.

Return All Cloud Provider Access Roles

Returns all cloud provider access roles with access to the specified project. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "awsIamRoles": [
    ],
  • "azureServicePrincipals": [
    ]
}

Create One Cloud Provider Access Role

Creates one access role for the specified cloud provider. Some MongoDB Cloud features use these cloud provider access roles for authentication. To use this resource, the requesting API Key must have the Project Owner role.

Set Up Access to Cloud Providers
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Creates one role for the specified cloud provider.

providerName
required
string

Human-readable label that identifies the cloud provider of the role.

Responses

Request samples

Content type
application/json
Example
{
  • "providerName": "AWS"
}

Response samples

Content type
application/json
Example
{
  • "providerName": "AWS",
  • "atlasAWSAccountArn": "arn:aws:iam::772401394250:role/my-test-aws-role",
  • "atlasAssumedRoleExternalId": "24be57ae-3c7b-4f00-b2d8-8ad523d5bd8d",
  • "authorizedDate": "2019-08-24T14:15:22Z",
  • "createdDate": "2019-08-24T14:15:22Z",
  • "featureUsages": [
    ],
  • "iamAssumedRoleArn": "arn:aws:iam::123456789012:root",
  • "roleId": "32b6e34b3d91647abb20e7b8"
}

Deauthorize One Cloud Provider Access Role

Revokes access to the specified project for the specified access role. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

cloudProvider
required
string
Enum: "AWS" "AZURE" "GCP"

Human-readable label that identifies the cloud provider of the role to deauthorize.

roleId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the role.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "detail": "(This is just an example, the exception may not be related to this endpoint) No provider AWS exists.",
  • "error": 400,
  • "errorCode": "VALIDATION_ERROR",
  • "reason": "Bad Request"
}

Return specified Cloud Provider Access Role

Returns the access role with the specified id and with access to the specified project. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

roleId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the role.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
Example
{
  • "providerName": "AWS",
  • "atlasAWSAccountArn": "arn:aws:iam::772401394250:role/my-test-aws-role",
  • "atlasAssumedRoleExternalId": "24be57ae-3c7b-4f00-b2d8-8ad523d5bd8d",
  • "authorizedDate": "2019-08-24T14:15:22Z",
  • "createdDate": "2019-08-24T14:15:22Z",
  • "featureUsages": [
    ],
  • "iamAssumedRoleArn": "arn:aws:iam::123456789012:root",
  • "roleId": "32b6e34b3d91647abb20e7b8"
}

Authorize One Cloud Provider Access Role

Grants access to the specified project for the specified access role. To use this resource, the requesting API Key must have the Project Owner role. This API endpoint is one step in a procedure to create unified access for MongoDB Cloud services. This is not required for GCP service account access.

Set Up Access to Cloud Providers
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

roleId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the role.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Grants access to the specified project for the specified access role.

providerName
required
string

Human-readable label that identifies the cloud provider of the role.

iamAssumedRoleArn
string [ 20 .. 2048 ] characters

Amazon Resource Name (ARN) that identifies the Amazon Web Services (AWS) Identity and Access Management (IAM) role that MongoDB Cloud assumes when it accesses resources in your AWS account.

Responses

Request samples

Content type
application/json
Example
{
  • "providerName": "AWS",
  • "iamAssumedRoleArn": "arn:aws:iam::123456789012:root"
}

Response samples

Content type
application/json
Example
{
  • "providerName": "AWS",
  • "atlasAWSAccountArn": "arn:aws:iam::772401394250:role/my-test-aws-role",
  • "atlasAssumedRoleExternalId": "24be57ae-3c7b-4f00-b2d8-8ad523d5bd8d",
  • "authorizedDate": "2019-08-24T14:15:22Z",
  • "createdDate": "2019-08-24T14:15:22Z",
  • "featureUsages": [
    ],
  • "iamAssumedRoleArn": "arn:aws:iam::123456789012:root",
  • "roleId": "32b6e34b3d91647abb20e7b8"
}

Cluster Outage Simulation

Returns, starts, or ends a cluster outage simulation.

End an Outage Simulation

Ends a cluster outage simulation.

Cluster Outage Simulation
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster that is undergoing outage simulation.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "clusterName": "string",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "outageFilters": [
    ],
  • "startRequestDate": "2022-01-01T00:00:00Z",
  • "state": "START_REQUESTED"
}

Return One Outage Simulation

Returns one outage simulation for one cluster.

Cluster Outage Simulation
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster that is undergoing outage simulation.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "clusterName": "string",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "outageFilters": [
    ],
  • "startRequestDate": "2022-01-01T00:00:00Z",
  • "state": "START_REQUESTED"
}

Start an Outage Simulation

Starts a cluster outage simulation.

Cluster Outage Simulation
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster to undergo an outage simulation.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Describes the outage simulation.

Array of objects (AtlasClusterOutageSimulationOutageFilter) non-empty

List of settings that specify the type of cluster outage simulation.

Responses

Request samples

Content type
application/json
{
  • "outageFilters": [
    ]
}

Response samples

Content type
application/json
{
  • "clusterName": "string",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "outageFilters": [
    ],
  • "startRequestDate": "2022-01-01T00:00:00Z",
  • "state": "START_REQUESTED"
}

Clusters

Returns, adds, edits, and removes database deployments. Changes to cluster configurations can affect costs. This resource requires your Project ID.

Return All Authorized Clusters in All Projects

Returns the details for all clusters in all projects to which you have access. Clusters contain a group of hosts that maintain the same data set. The response does not include multi-cloud clusters. To use this resource, the requesting API Key can have any cluster-level role.

Authorizations:
DigestAuthServiceAccounts
query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Return All Clusters in One Project

Returns the details for all clusters in the specific project to which you have access. Clusters contain a group of hosts that maintain the same data set. The response does not include multi-cloud clusters. To return multi-cloud clusters, use Get All Advanced Clusters. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

includeDeletedWithRetainedBackups
boolean
Default: false

Flag that indicates whether to return Clusters with retain backups.

Responses

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Create One Cluster

Creates one cluster in the specific project. Clusters contain a group of hosts that maintain the same data set. This resource does not create multi-cloud clusters. To create a multi-cloud cluster, use Create One Advanced Cluster. To use this resource, the requesting API Key must have the Project Owner role.

When you deploy an M10+ dedicated cluster, Atlas creates a VPC for the selected provider and region or regions if no existing VPC or VPC peering connection exists for that provider and region. Atlas assigns the VPC a Classless Inter-Domain Routing (CIDR) block.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Details to create for one cluster in the specified project.

acceptDataRisksAndForceReplicaSetReconfig
string <date-time>

If reconfiguration is necessary to regain a primary due to a regional outage, submit this field alongside your topology reconfiguration to request a new regional outage resistant topology. Forced reconfigurations during an outage of the majority of electable nodes carry a risk of data loss if replicated writes (even majority committed writes) have not been replicated to the new primary node. MongoDB Atlas docs contain more information. To proceed with an operation which carries that risk, set acceptDataRisksAndForceReplicaSetReconfig to the current date.

Reconfiguring a Replica Set during a regional outage
object (Automatic Cluster Scaling Settings)

Range of instance sizes to which your cluster can scale.

Cluster Auto-Scaling
backupEnabled
boolean

Flag that indicates whether the cluster can perform backups. If set to true, the cluster can perform backups. You must set this value to true for NVMe clusters. Backup uses Cloud Backups for dedicated clusters and Shared Cluster Backups for tenant clusters. If set to false, the cluster doesn't use MongoDB Cloud backups.

object (MongoDB Connector for Business Intelligence Settings)

Settings needed to configure the MongoDB Connector for Business Intelligence for this cluster.

MongoDB Connector for Business Intelligence
clusterType
string
Enum: "REPLICASET" "SHARDED" "GEOSHARDED"

Configuration of nodes that comprise the cluster.

configServerManagementMode
string
Default: "ATLAS_MANAGED"
Enum: "ATLAS_MANAGED" "FIXED_TO_DEDICATED"

Config Server Management Mode for creating or updating a sharded cluster.

When configured as ATLAS_MANAGED, atlas may automatically switch the cluster's config server type for optimal performance and savings.

When configured as FIXED_TO_DEDICATED, the cluster will always use a dedicated config server.

MongoDB Sharded Cluster Config Servers
diskSizeGB
number <double> [ 10 .. 4096 ]

Storage capacity of instance data volumes expressed in gigabytes. Increase this number to add capacity.

This value is not configurable on M0/M2/M5 clusters.

MongoDB Cloud requires this parameter if you set replicationSpecs.

If you specify a disk size below the minimum (10 GB), this parameter defaults to the minimum disk size value.

Storage charge calculations depend on whether you choose the default value or a custom value.

The maximum value for disk storage cannot exceed 50 times the maximum RAM for the selected cluster. If you require more storage space, consider upgrading your cluster to a higher tier.

diskWarmingMode
string
Default: "FULLY_WARMED"
Enum: "FULLY_WARMED" "VISIBLE_EARLIER"

Disk warming mode selection.

Reduce Secondary Disk Warming Impact
encryptionAtRestProvider
string
Enum: "NONE" "AWS" "AZURE" "GCP"

Cloud service provider that manages your customer keys to provide an additional layer of Encryption at Rest for the cluster.

Encryption at Rest using Customer Key Management
globalClusterSelfManagedSharding
boolean

Set this field to configure the Sharding Management Mode when creating a new Global Cluster.

When set to false, the management mode is set to Atlas-Managed Sharding. This mode fully manages the sharding of your Global Cluster and is built to provide a seamless deployment experience.

When set to true, the management mode is set to Self-Managed Sharding. This mode leaves the management of shards in your hands and is built to provide an advanced and flexible deployment experience.

This setting cannot be changed once the cluster is deployed.

Creating a Global Cluster
Array of objects (Component Label)
Deprecated

Collection of key-value pairs between 1 to 255 characters in length that tag and categorize the cluster. The MongoDB Cloud console doesn't display your labels.

Cluster labels are deprecated and will be removed in a future release. We strongly recommend that you use resource tags instead.

mongoDBMajorVersion
string

MongoDB major version of the cluster.

On creation: Choose from the available versions of MongoDB, or leave unspecified for the current recommended default in the MongoDB Cloud platform. The recommended version is a recent Long Term Support version. The default is not guaranteed to be the most recently released version throughout the entire release cycle. For versions available in a specific project, see the linked documentation or use the API endpoint for project LTS versions endpoint.

On update: Increase version only by 1 major version at a time. If the cluster is pinned to a MongoDB feature compatibility version exactly one major version below the current MongoDB version, the MongoDB version can be downgraded to the previous major version.

Available MongoDB Versions in Atlas
mongoDBVersion
string([\d]+\.[\d]+\.[\d]+)

Version of MongoDB that the cluster runs.

name
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster.

numShards
integer <int32> [ 1 .. 50 ]
Default: 1

Number of shards up to 50 to deploy for a sharded cluster. The resource returns 1 to indicate a replica set and values of 2 and higher to indicate a sharded cluster. The returned value equals the number of shards in the cluster.

Sharding
paused
boolean

Flag that indicates whether the cluster is paused.

pitEnabled
boolean

Flag that indicates whether the cluster uses continuous cloud backups.

Continuous Cloud Backups
providerBackupEnabled
boolean

Flag that indicates whether the M10 or higher cluster can perform Cloud Backups. If set to true, the cluster can perform backups. If this and backupEnabled are set to false, the cluster doesn't use MongoDB Cloud backups.

object (Cloud Service Provider Settings for a Cluster)

Group of cloud provider settings that configure the provisioned MongoDB hosts.

replicaSetScalingStrategy
string
Default: "WORKLOAD_TYPE"
Enum: "SEQUENTIAL" "WORKLOAD_TYPE" "NODE_TYPE"

Set this field to configure the replica set scaling mode for your cluster.

By default, Atlas scales under WORKLOAD_TYPE. This mode allows Atlas to scale your analytics nodes in parallel to your operational nodes.

When configured as SEQUENTIAL, Atlas scales all nodes sequentially. This mode is intended for steady-state workloads and applications performing latency-sensitive secondary reads.

When configured as NODE_TYPE, Atlas scales your electable nodes in parallel with your read-only and analytics nodes. This mode is intended for large, dynamic workloads requiring frequent and timely cluster tier scaling. This is the fastest scaling strategy, but it might impact latency of workloads when performing extensive secondary reads.

Modify the Replica Set Scaling Mode
replicationFactor
integer <int32>
Deprecated
Default: 3
Enum: 3 5 7

Number of members that belong to the replica set. Each member retains a copy of your databases, providing high availability and data redundancy. Use replicationSpecs instead.

object (Region Configuration)

Physical location where MongoDB Cloud provisions cluster nodes.

Array of objects (LegacyReplicationSpec)

List of settings that configure your cluster regions.

  • For Global Clusters, each object in the array represents one zone where MongoDB Cloud deploys your clusters nodes.
  • For non-Global sharded clusters and replica sets, the single object represents where MongoDB Cloud deploys your clusters nodes.
rootCertType
string
Default: "ISRGROOTX1"
Value: "ISRGROOTX1"

Root Certificate Authority that MongoDB Atlas clusters uses. MongoDB Cloud supports Internet Security Research Group.

Array of objects (Resource Tag)

List that contains key-value pairs between 1 to 255 characters in length for tagging and categorizing the cluster.

Resource Tags
terminationProtectionEnabled
boolean
Default: false

Flag that indicates whether termination protection is enabled on the cluster. If set to true, MongoDB Cloud won't delete the cluster. If set to false, MongoDB Cloud will delete the cluster.

versionReleaseSystem
string
Default: "LTS"
Enum: "LTS" "CONTINUOUS"

Method by which the cluster maintains the MongoDB versions. If value is CONTINUOUS, you must not specify mongoDBMajorVersion.

Responses

Request samples

Content type
application/json
{
  • "acceptDataRisksAndForceReplicaSetReconfig": "2019-08-24T14:15:22Z",
  • "autoScaling": {
    },
  • "backupEnabled": true,
  • "biConnector": {
    },
  • "clusterType": "REPLICASET",
  • "configServerManagementMode": "ATLAS_MANAGED",
  • "diskSizeGB": 10,
  • "diskWarmingMode": "FULLY_WARMED",
  • "encryptionAtRestProvider": "NONE",
  • "globalClusterSelfManagedSharding": true,
  • "labels": [
    ],
  • "mongoDBMajorVersion": "5.0",
  • "mongoDBVersion": "5.0.25",
  • "name": "string",
  • "numShards": 1,
  • "paused": true,
  • "pitEnabled": true,
  • "providerBackupEnabled": true,
  • "providerSettings": {
    },
  • "replicaSetScalingStrategy": "SEQUENTIAL",
  • "replicationFactor": 3,
  • "replicationSpec": {
    },
  • "replicationSpecs": [
    ],
  • "rootCertType": "ISRGROOTX1",
  • "tags": [
    ],
  • "terminationProtectionEnabled": false,
  • "versionReleaseSystem": "LTS"
}

Response samples

Content type
application/json
{
  • "acceptDataRisksAndForceReplicaSetReconfig": "2019-08-24T14:15:22Z",
  • "autoScaling": {
    },
  • "backupEnabled": true,
  • "biConnector": {
    },
  • "clusterType": "REPLICASET",
  • "configServerManagementMode": "ATLAS_MANAGED",
  • "configServerType": "DEDICATED",
  • "connectionStrings": {
    },
  • "createDate": "2019-08-24T14:15:22Z",
  • "diskSizeGB": 10,
  • "diskWarmingMode": "FULLY_WARMED",
  • "encryptionAtRestProvider": "NONE",
  • "featureCompatibilityVersion": "string",
  • "featureCompatibilityVersionExpirationDate": "2019-08-24T14:15:22Z",
  • "globalClusterSelfManagedSharding": true,
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "labels": [
    ],
  • "links": [],
  • "mongoDBEmployeeAccessGrant": {},
  • "mongoDBMajorVersion": "5.0",
  • "mongoDBVersion": "5.0.25",
  • "mongoURI": "string",
  • "mongoURIUpdated": "2019-08-24T14:15:22Z",
  • "mongoURIWithOptions": "string",
  • "name": "string",
  • "numShards": 1,
  • "paused": true,
  • "pitEnabled": true,
  • "providerBackupEnabled": true,
  • "providerSettings": {
    },
  • "replicaSetScalingStrategy": "SEQUENTIAL",
  • "replicationFactor": 3,
  • "replicationSpec": {
    },
  • "replicationSpecs": [
    ],
  • "rootCertType": "ISRGROOTX1",
  • "srvAddress": "string",
  • "stateName": "IDLE",
  • "tags": [
    ],
  • "terminationProtectionEnabled": false,
  • "versionReleaseSystem": "LTS"
}

Return All Cloud Provider Regions

Returns the list of regions available for the specified cloud provider at the specified tier. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

providers
Array of strings

Cloud providers whose regions to retrieve. When you specify multiple providers, the response can return only tiers and regions that support multi-cloud clusters.

tier
string

Cluster tier for which to retrieve the regions.

Responses

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Upgrade One Shared-tier Cluster

Upgrades a shared-tier cluster in the specified project. To use this resource, the requesting API key must have the Project Cluster Manager role. Each project supports up to 25 clusters.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Details of the shared-tier cluster upgrade in the specified project.

acceptDataRisksAndForceReplicaSetReconfig
string <date-time>

If reconfiguration is necessary to regain a primary due to a regional outage, submit this field alongside your topology reconfiguration to request a new regional outage resistant topology. Forced reconfigurations during an outage of the majority of electable nodes carry a risk of data loss if replicated writes (even majority committed writes) have not been replicated to the new primary node. MongoDB Atlas docs contain more information. To proceed with an operation which carries that risk, set acceptDataRisksAndForceReplicaSetReconfig to the current date.

Reconfiguring a Replica Set during a regional outage
object (Automatic Cluster Scaling Settings)

Range of instance sizes to which your cluster can scale.

Cluster Auto-Scaling
backupEnabled
boolean

Flag that indicates whether the cluster can perform backups. If set to true, the cluster can perform backups. You must set this value to true for NVMe clusters. Backup uses Cloud Backups for dedicated clusters and Shared Cluster Backups for tenant clusters. If set to false, the cluster doesn't use MongoDB Cloud backups.

object (MongoDB Connector for Business Intelligence Settings)

Settings needed to configure the MongoDB Connector for Business Intelligence for this cluster.

MongoDB Connector for Business Intelligence
clusterType
string
Enum: "REPLICASET" "SHARDED" "GEOSHARDED"

Configuration of nodes that comprise the cluster.

configServerManagementMode
string
Default: "ATLAS_MANAGED"
Enum: "ATLAS_MANAGED" "FIXED_TO_DEDICATED"

Config Server Management Mode for creating or updating a sharded cluster.

When configured as ATLAS_MANAGED, atlas may automatically switch the cluster's config server type for optimal performance and savings.

When configured as FIXED_TO_DEDICATED, the cluster will always use a dedicated config server.

MongoDB Sharded Cluster Config Servers
diskSizeGB
number <double> [ 10 .. 4096 ]

Storage capacity of instance data volumes expressed in gigabytes. Increase this number to add capacity.

This value is not configurable on M0/M2/M5 clusters.

MongoDB Cloud requires this parameter if you set replicationSpecs.

If you specify a disk size below the minimum (10 GB), this parameter defaults to the minimum disk size value.

Storage charge calculations depend on whether you choose the default value or a custom value.

The maximum value for disk storage cannot exceed 50 times the maximum RAM for the selected cluster. If you require more storage space, consider upgrading your cluster to a higher tier.

diskWarmingMode
string
Default: "FULLY_WARMED"
Enum: "FULLY_WARMED" "VISIBLE_EARLIER"

Disk warming mode selection.

Reduce Secondary Disk Warming Impact
encryptionAtRestProvider
string
Enum: "NONE" "AWS" "AZURE" "GCP"

Cloud service provider that manages your customer keys to provide an additional layer of Encryption at Rest for the cluster.

Encryption at Rest using Customer Key Management
globalClusterSelfManagedSharding
boolean

Set this field to configure the Sharding Management Mode when creating a new Global Cluster.

When set to false, the management mode is set to Atlas-Managed Sharding. This mode fully manages the sharding of your Global Cluster and is built to provide a seamless deployment experience.

When set to true, the management mode is set to Self-Managed Sharding. This mode leaves the management of shards in your hands and is built to provide an advanced and flexible deployment experience.

This setting cannot be changed once the cluster is deployed.

Creating a Global Cluster
Array of objects (Component Label)
Deprecated

Collection of key-value pairs between 1 to 255 characters in length that tag and categorize the cluster. The MongoDB Cloud console doesn't display your labels.

Cluster labels are deprecated and will be removed in a future release. We strongly recommend that you use resource tags instead.

mongoDBMajorVersion
string

MongoDB major version of the cluster.

On creation: Choose from the available versions of MongoDB, or leave unspecified for the current recommended default in the MongoDB Cloud platform. The recommended version is a recent Long Term Support version. The default is not guaranteed to be the most recently released version throughout the entire release cycle. For versions available in a specific project, see the linked documentation or use the API endpoint for project LTS versions endpoint.

On update: Increase version only by 1 major version at a time. If the cluster is pinned to a MongoDB feature compatibility version exactly one major version below the current MongoDB version, the MongoDB version can be downgraded to the previous major version.

Available MongoDB Versions in Atlas
mongoDBVersion
string([\d]+\.[\d]+\.[\d]+)

Version of MongoDB that the cluster runs.

name
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster.

numShards
integer <int32> [ 1 .. 50 ]
Default: 1

Number of shards up to 50 to deploy for a sharded cluster. The resource returns 1 to indicate a replica set and values of 2 and higher to indicate a sharded cluster. The returned value equals the number of shards in the cluster.

Sharding
paused
boolean

Flag that indicates whether the cluster is paused.

pitEnabled
boolean

Flag that indicates whether the cluster uses continuous cloud backups.

Continuous Cloud Backups
providerBackupEnabled
boolean

Flag that indicates whether the M10 or higher cluster can perform Cloud Backups. If set to true, the cluster can perform backups. If this and backupEnabled are set to false, the cluster doesn't use MongoDB Cloud backups.

object (Cloud Service Provider Settings for a Cluster)

Group of cloud provider settings that configure the provisioned MongoDB hosts.

replicaSetScalingStrategy
string
Default: "WORKLOAD_TYPE"
Enum: "SEQUENTIAL" "WORKLOAD_TYPE" "NODE_TYPE"

Set this field to configure the replica set scaling mode for your cluster.

By default, Atlas scales under WORKLOAD_TYPE. This mode allows Atlas to scale your analytics nodes in parallel to your operational nodes.

When configured as SEQUENTIAL, Atlas scales all nodes sequentially. This mode is intended for steady-state workloads and applications performing latency-sensitive secondary reads.

When configured as NODE_TYPE, Atlas scales your electable nodes in parallel with your read-only and analytics nodes. This mode is intended for large, dynamic workloads requiring frequent and timely cluster tier scaling. This is the fastest scaling strategy, but it might impact latency of workloads when performing extensive secondary reads.

Modify the Replica Set Scaling Mode
replicationFactor
integer <int32>
Deprecated
Default: 3
Enum: 3 5 7

Number of members that belong to the replica set. Each member retains a copy of your databases, providing high availability and data redundancy. Use replicationSpecs instead.

object (Region Configuration)

Physical location where MongoDB Cloud provisions cluster nodes.

Array of objects (LegacyReplicationSpec)

List of settings that configure your cluster regions.

  • For Global Clusters, each object in the array represents one zone where MongoDB Cloud deploys your clusters nodes.
  • For non-Global sharded clusters and replica sets, the single object represents where MongoDB Cloud deploys your clusters nodes.
rootCertType
string
Default: "ISRGROOTX1"
Value: "ISRGROOTX1"

Root Certificate Authority that MongoDB Atlas clusters uses. MongoDB Cloud supports Internet Security Research Group.

Array of objects (Resource Tag)

List that contains key-value pairs between 1 to 255 characters in length for tagging and categorizing the cluster.

Resource Tags
terminationProtectionEnabled
boolean
Default: false

Flag that indicates whether termination protection is enabled on the cluster. If set to true, MongoDB Cloud won't delete the cluster. If set to false, MongoDB Cloud will delete the cluster.

versionReleaseSystem
string
Default: "LTS"
Enum: "LTS" "CONTINUOUS"

Method by which the cluster maintains the MongoDB versions. If value is CONTINUOUS, you must not specify mongoDBMajorVersion.

Responses

Request samples

Content type
application/json
{
  • "acceptDataRisksAndForceReplicaSetReconfig": "2019-08-24T14:15:22Z",
  • "autoScaling": {
    },
  • "backupEnabled": true,
  • "biConnector": {
    },
  • "clusterType": "REPLICASET",
  • "configServerManagementMode": "ATLAS_MANAGED",
  • "diskSizeGB": 10,
  • "diskWarmingMode": "FULLY_WARMED",
  • "encryptionAtRestProvider": "NONE",
  • "globalClusterSelfManagedSharding": true,
  • "labels": [
    ],
  • "mongoDBMajorVersion": "5.0",
  • "mongoDBVersion": "5.0.25",
  • "name": "string",
  • "numShards": 1,
  • "paused": true,
  • "pitEnabled": true,
  • "providerBackupEnabled": true,
  • "providerSettings": {
    },
  • "replicaSetScalingStrategy": "SEQUENTIAL",
  • "replicationFactor": 3,
  • "replicationSpec": {
    },
  • "replicationSpecs": [
    ],
  • "rootCertType": "ISRGROOTX1",
  • "tags": [
    ],
  • "terminationProtectionEnabled": false,
  • "versionReleaseSystem": "LTS"
}

Response samples

Content type
application/json
{
  • "acceptDataRisksAndForceReplicaSetReconfig": "2019-08-24T14:15:22Z",
  • "autoScaling": {
    },
  • "backupEnabled": true,
  • "biConnector": {
    },
  • "clusterType": "REPLICASET",
  • "configServerManagementMode": "ATLAS_MANAGED",
  • "configServerType": "DEDICATED",
  • "connectionStrings": {
    },
  • "createDate": "2019-08-24T14:15:22Z",
  • "diskSizeGB": 10,
  • "diskWarmingMode": "FULLY_WARMED",
  • "encryptionAtRestProvider": "NONE",
  • "featureCompatibilityVersion": "string",
  • "featureCompatibilityVersionExpirationDate": "2019-08-24T14:15:22Z",
  • "globalClusterSelfManagedSharding": true,
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "labels": [
    ],
  • "links": [],
  • "mongoDBEmployeeAccessGrant": {},
  • "mongoDBMajorVersion": "5.0",
  • "mongoDBVersion": "5.0.25",
  • "mongoURI": "string",
  • "mongoURIUpdated": "2019-08-24T14:15:22Z",
  • "mongoURIWithOptions": "string",
  • "name": "string",
  • "numShards": 1,
  • "paused": true,
  • "pitEnabled": true,
  • "providerBackupEnabled": true,
  • "providerSettings": {
    },
  • "replicaSetScalingStrategy": "SEQUENTIAL",
  • "replicationFactor": 3,
  • "replicationSpec": {
    },
  • "replicationSpecs": [
    ],
  • "rootCertType": "ISRGROOTX1",
  • "srvAddress": "string",
  • "stateName": "IDLE",
  • "tags": [
    ],
  • "terminationProtectionEnabled": false,
  • "versionReleaseSystem": "LTS"
}

Upgrades One Shared-Tier Cluster to the Serverless Instance

Upgrades a shared-tier cluster to a serverless instance in the specified project. To use this resource, the requesting API key must have the Project Cluster Manager role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Details of the shared-tier cluster upgrade in the specified project.

name
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the serverless instance.

required
object (Cloud Service Provider Settings for a Serverless Instance)

Group of cloud provider settings that configure the provisioned MongoDB serverless instance.

object (Serverless Backup Options)

Group of settings that configure serverless backup.

Array of objects (Resource Tag)

List that contains key-value pairs between 1 to 255 characters in length for tagging and categorizing the serverless instance.

terminationProtectionEnabled
boolean
Default: false

Flag that indicates whether termination protection is enabled on the serverless instance. If set to true, MongoDB Cloud won't delete the serverless instance. If set to false, MongoDB Cloud will delete the serverless instance.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "providerSettings": {
    },
  • "serverlessBackupOptions": {
    },
  • "tags": [
    ],
  • "terminationProtectionEnabled": false
}

Response samples

Content type
application/json
{
  • "connectionStrings": {
    },
  • "createDate": "2019-08-24T14:15:22Z",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "links": [],
  • "mongoDBVersion": "string",
  • "name": "string",
  • "providerSettings": {
    },
  • "serverlessBackupOptions": {
    },
  • "stateName": "IDLE",
  • "tags": [
    ],
  • "terminationProtectionEnabled": false
}

Remove One Cluster

Removes one cluster in the specific project. Clusters contain a group of hosts that maintain the same data set. The cluster must have termination protection disabled in order to be deleted. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

retainBackups
boolean

Flag that indicates whether to retain backup snapshots for the deleted dedicated cluster.

Responses

Response samples

Content type
application/json
{
  • "detail": "(This is just an example, the exception may not be related to this endpoint) No provider AWS exists.",
  • "error": 400,
  • "errorCode": "VALIDATION_ERROR",
  • "reason": "Bad Request"
}

Return One Cluster in One Project

Returns the details for one cluster in the specified project. Clusters contain a group of hosts that maintain the same data set. The response does not include multi-cloud clusters. To return a multi-cloud cluster, use Get One Advanced Cluster. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "acceptDataRisksAndForceReplicaSetReconfig": "2019-08-24T14:15:22Z",
  • "autoScaling": {
    },
  • "backupEnabled": true,
  • "biConnector": {
    },
  • "clusterType": "REPLICASET",
  • "configServerManagementMode": "ATLAS_MANAGED",
  • "configServerType": "DEDICATED",
  • "connectionStrings": {
    },
  • "createDate": "2019-08-24T14:15:22Z",
  • "diskSizeGB": 10,
  • "diskWarmingMode": "FULLY_WARMED",
  • "encryptionAtRestProvider": "NONE",
  • "featureCompatibilityVersion": "string",
  • "featureCompatibilityVersionExpirationDate": "2019-08-24T14:15:22Z",
  • "globalClusterSelfManagedSharding": true,
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "labels": [
    ],
  • "links": [],
  • "mongoDBEmployeeAccessGrant": {},
  • "mongoDBMajorVersion": "5.0",
  • "mongoDBVersion": "5.0.25",
  • "mongoURI": "string",
  • "mongoURIUpdated": "2019-08-24T14:15:22Z",
  • "mongoURIWithOptions": "string",
  • "name": "string",
  • "numShards": 1,
  • "paused": true,
  • "pitEnabled": true,
  • "providerBackupEnabled": true,
  • "providerSettings": {
    },
  • "replicaSetScalingStrategy": "SEQUENTIAL",
  • "replicationFactor": 3,
  • "replicationSpec": {
    },
  • "replicationSpecs": [
    ],
  • "rootCertType": "ISRGROOTX1",
  • "srvAddress": "string",
  • "stateName": "IDLE",
  • "tags": [
    ],
  • "terminationProtectionEnabled": false,
  • "versionReleaseSystem": "LTS"
}

Update Configuration of One Cluster

Update the details for one cluster in the specified project. Clusters contain a group of hosts that maintain the same data set. This resource does not update multi-cloud clusters. To update a multi-cloud cluster, use Update One Advanced Cluster. You can upgrade your cluster only one major version at a time. You can't skip any major versions. Each major version contains some features that might not be backward-compatible with previous versions. Check the Release Notes for changes that might affect your applications. After you upgrade the MongoDB major version, you will not be able to downgrade to previous versions.

As of MongoDB version 4.2, Legacy Backups are deprecated in favor of Cloud Backups. When you upgrade to version 4.2 or later, your backup system upgrades to Cloud Backups if it is currently set to Legacy Backup. After this upgrade, all your existing legacy backup snapshots remain available. They expire over time in accordance with your retention policy. Your backup policy resets to the default schedule. If you had a custom backup policy in place with legacy backups, you must re-create it with the procedure outlined in the Cloud Backup documentation.

To use this resource, the requesting API Key must have the Project Cluster Manager role. This feature isn't available for M0 free clusters, M2 and M5 shared-tier clusters.

The total number of nodes in clusters spanning across regions has a specific constraint on a per-project basis. MongoDB Cloud limits the total number of nodes in other regions in one project to a total of 40. This total excludes Google Cloud regions communicating with each other, free clusters, or shared clusters. The total number of nodes between any two regions must meet this constraint. For example, if a project has nodes in clusters spread across three regions: 30 nodes in Region A, 10 nodes in Region B, and 5 nodes in Region C, you can add only 5 more nodes to Region C because if you exclude Region C, Region A + Region B = 40. If you exclude Region B, Region A + Region C = 35, <= 40. If you exclude Region A, Region B + Region C = 15, <= 40. Each combination of regions with the added 5 nodes still meets the per-project constraint: Region A + B = 40, Region A + C = 40, and Region B + C = 20. You can't create a multi-region cluster in a project if it has one or more clusters spanning 40 or more nodes in other regions.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Details to update for one cluster in the specified project.

acceptDataRisksAndForceReplicaSetReconfig
string <date-time>

If reconfiguration is necessary to regain a primary due to a regional outage, submit this field alongside your topology reconfiguration to request a new regional outage resistant topology. Forced reconfigurations during an outage of the majority of electable nodes carry a risk of data loss if replicated writes (even majority committed writes) have not been replicated to the new primary node. MongoDB Atlas docs contain more information. To proceed with an operation which carries that risk, set acceptDataRisksAndForceReplicaSetReconfig to the current date.

Reconfiguring a Replica Set during a regional outage
object (Automatic Cluster Scaling Settings)

Range of instance sizes to which your cluster can scale.

Cluster Auto-Scaling
backupEnabled
boolean

Flag that indicates whether the cluster can perform backups. If set to true, the cluster can perform backups. You must set this value to true for NVMe clusters. Backup uses Cloud Backups for dedicated clusters and Shared Cluster Backups for tenant clusters. If set to false, the cluster doesn't use MongoDB Cloud backups.

object (MongoDB Connector for Business Intelligence Settings)

Settings needed to configure the MongoDB Connector for Business Intelligence for this cluster.

MongoDB Connector for Business Intelligence
clusterType
string
Enum: "REPLICASET" "SHARDED" "GEOSHARDED"

Configuration of nodes that comprise the cluster.

configServerManagementMode
string
Default: "ATLAS_MANAGED"
Enum: "ATLAS_MANAGED" "FIXED_TO_DEDICATED"

Config Server Management Mode for creating or updating a sharded cluster.

When configured as ATLAS_MANAGED, atlas may automatically switch the cluster's config server type for optimal performance and savings.

When configured as FIXED_TO_DEDICATED, the cluster will always use a dedicated config server.

MongoDB Sharded Cluster Config Servers
diskSizeGB
number <double> [ 10 .. 4096 ]

Storage capacity of instance data volumes expressed in gigabytes. Increase this number to add capacity.

This value is not configurable on M0/M2/M5 clusters.

MongoDB Cloud requires this parameter if you set replicationSpecs.

If you specify a disk size below the minimum (10 GB), this parameter defaults to the minimum disk size value.

Storage charge calculations depend on whether you choose the default value or a custom value.

The maximum value for disk storage cannot exceed 50 times the maximum RAM for the selected cluster. If you require more storage space, consider upgrading your cluster to a higher tier.

diskWarmingMode
string
Default: "FULLY_WARMED"
Enum: "FULLY_WARMED" "VISIBLE_EARLIER"

Disk warming mode selection.

Reduce Secondary Disk Warming Impact
encryptionAtRestProvider
string
Enum: "NONE" "AWS" "AZURE" "GCP"

Cloud service provider that manages your customer keys to provide an additional layer of Encryption at Rest for the cluster.

Encryption at Rest using Customer Key Management
globalClusterSelfManagedSharding
boolean

Set this field to configure the Sharding Management Mode when creating a new Global Cluster.

When set to false, the management mode is set to Atlas-Managed Sharding. This mode fully manages the sharding of your Global Cluster and is built to provide a seamless deployment experience.

When set to true, the management mode is set to Self-Managed Sharding. This mode leaves the management of shards in your hands and is built to provide an advanced and flexible deployment experience.

This setting cannot be changed once the cluster is deployed.

Creating a Global Cluster
Array of objects (Component Label)
Deprecated

Collection of key-value pairs between 1 to 255 characters in length that tag and categorize the cluster. The MongoDB Cloud console doesn't display your labels.

Cluster labels are deprecated and will be removed in a future release. We strongly recommend that you use resource tags instead.

mongoDBMajorVersion
string

MongoDB major version of the cluster.

On creation: Choose from the available versions of MongoDB, or leave unspecified for the current recommended default in the MongoDB Cloud platform. The recommended version is a recent Long Term Support version. The default is not guaranteed to be the most recently released version throughout the entire release cycle. For versions available in a specific project, see the linked documentation or use the API endpoint for project LTS versions endpoint.

On update: Increase version only by 1 major version at a time. If the cluster is pinned to a MongoDB feature compatibility version exactly one major version below the current MongoDB version, the MongoDB version can be downgraded to the previous major version.

Available MongoDB Versions in Atlas
mongoDBVersion
string([\d]+\.[\d]+\.[\d]+)

Version of MongoDB that the cluster runs.

name
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster.

numShards
integer <int32> [ 1 .. 50 ]
Default: 1

Number of shards up to 50 to deploy for a sharded cluster. The resource returns 1 to indicate a replica set and values of 2 and higher to indicate a sharded cluster. The returned value equals the number of shards in the cluster.

Sharding
paused
boolean

Flag that indicates whether the cluster is paused.

pitEnabled
boolean

Flag that indicates whether the cluster uses continuous cloud backups.

Continuous Cloud Backups
providerBackupEnabled
boolean

Flag that indicates whether the M10 or higher cluster can perform Cloud Backups. If set to true, the cluster can perform backups. If this and backupEnabled are set to false, the cluster doesn't use MongoDB Cloud backups.

object (Cloud Service Provider Settings for a Cluster)

Group of cloud provider settings that configure the provisioned MongoDB hosts.

replicaSetScalingStrategy
string
Default: "WORKLOAD_TYPE"
Enum: "SEQUENTIAL" "WORKLOAD_TYPE" "NODE_TYPE"

Set this field to configure the replica set scaling mode for your cluster.

By default, Atlas scales under WORKLOAD_TYPE. This mode allows Atlas to scale your analytics nodes in parallel to your operational nodes.

When configured as SEQUENTIAL, Atlas scales all nodes sequentially. This mode is intended for steady-state workloads and applications performing latency-sensitive secondary reads.

When configured as NODE_TYPE, Atlas scales your electable nodes in parallel with your read-only and analytics nodes. This mode is intended for large, dynamic workloads requiring frequent and timely cluster tier scaling. This is the fastest scaling strategy, but it might impact latency of workloads when performing extensive secondary reads.

Modify the Replica Set Scaling Mode
replicationFactor
integer <int32>
Deprecated
Default: 3
Enum: 3 5 7

Number of members that belong to the replica set. Each member retains a copy of your databases, providing high availability and data redundancy. Use replicationSpecs instead.

object (Region Configuration)

Physical location where MongoDB Cloud provisions cluster nodes.

Array of objects (LegacyReplicationSpec)

List of settings that configure your cluster regions.

  • For Global Clusters, each object in the array represents one zone where MongoDB Cloud deploys your clusters nodes.
  • For non-Global sharded clusters and replica sets, the single object represents where MongoDB Cloud deploys your clusters nodes.
rootCertType
string
Default: "ISRGROOTX1"
Value: "ISRGROOTX1"

Root Certificate Authority that MongoDB Atlas clusters uses. MongoDB Cloud supports Internet Security Research Group.

Array of objects (Resource Tag)

List that contains key-value pairs between 1 to 255 characters in length for tagging and categorizing the cluster.

Resource Tags
terminationProtectionEnabled
boolean
Default: false

Flag that indicates whether termination protection is enabled on the cluster. If set to true, MongoDB Cloud won't delete the cluster. If set to false, MongoDB Cloud will delete the cluster.

versionReleaseSystem
string
Default: "LTS"
Enum: "LTS" "CONTINUOUS"

Method by which the cluster maintains the MongoDB versions. If value is CONTINUOUS, you must not specify mongoDBMajorVersion.

Responses

Request samples

Content type
application/json
{
  • "acceptDataRisksAndForceReplicaSetReconfig": "2019-08-24T14:15:22Z",
  • "autoScaling": {
    },
  • "backupEnabled": true,
  • "biConnector": {
    },
  • "clusterType": "REPLICASET",
  • "configServerManagementMode": "ATLAS_MANAGED",
  • "diskSizeGB": 10,
  • "diskWarmingMode": "FULLY_WARMED",
  • "encryptionAtRestProvider": "NONE",
  • "globalClusterSelfManagedSharding": true,
  • "labels": [
    ],
  • "mongoDBMajorVersion": "5.0",
  • "mongoDBVersion": "5.0.25",
  • "name": "string",
  • "numShards": 1,
  • "paused": true,
  • "pitEnabled": true,
  • "providerBackupEnabled": true,
  • "providerSettings": {
    },
  • "replicaSetScalingStrategy": "SEQUENTIAL",
  • "replicationFactor": 3,
  • "replicationSpec": {
    },
  • "replicationSpecs": [
    ],
  • "rootCertType": "ISRGROOTX1",
  • "tags": [
    ],
  • "terminationProtectionEnabled": false,
  • "versionReleaseSystem": "LTS"
}

Response samples

Content type
application/json
{
  • "acceptDataRisksAndForceReplicaSetReconfig": "2019-08-24T14:15:22Z",
  • "autoScaling": {
    },
  • "backupEnabled": true,
  • "biConnector": {
    },
  • "clusterType": "REPLICASET",
  • "configServerManagementMode": "ATLAS_MANAGED",
  • "configServerType": "DEDICATED",
  • "connectionStrings": {
    },
  • "createDate": "2019-08-24T14:15:22Z",
  • "diskSizeGB": 10,
  • "diskWarmingMode": "FULLY_WARMED",
  • "encryptionAtRestProvider": "NONE",
  • "featureCompatibilityVersion": "string",
  • "featureCompatibilityVersionExpirationDate": "2019-08-24T14:15:22Z",
  • "globalClusterSelfManagedSharding": true,
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "labels": [
    ],
  • "links": [],
  • "mongoDBEmployeeAccessGrant": {},
  • "mongoDBMajorVersion": "5.0",
  • "mongoDBVersion": "5.0.25",
  • "mongoURI": "string",
  • "mongoURIUpdated": "2019-08-24T14:15:22Z",
  • "mongoURIWithOptions": "string",
  • "name": "string",
  • "numShards": 1,
  • "paused": true,
  • "pitEnabled": true,
  • "providerBackupEnabled": true,
  • "providerSettings": {
    },
  • "replicaSetScalingStrategy": "SEQUENTIAL",
  • "replicationFactor": 3,
  • "replicationSpec": {
    },
  • "replicationSpecs": [
    ],
  • "rootCertType": "ISRGROOTX1",
  • "srvAddress": "string",
  • "stateName": "IDLE",
  • "tags": [
    ],
  • "terminationProtectionEnabled": false,
  • "versionReleaseSystem": "LTS"
}

Return One Advanced Configuration Options for One Cluster

Returns the advanced configuration details for one cluster in the specified project. Clusters contain a group of hosts that maintain the same data set. Advanced configuration details include the read/write concern, index and oplog limits, and other database settings. This feature isn't available for M0 free clusters, M2 and M5 shared-tier clusters, or serverless clusters. To use this resource, the requesting API Key must have the Project Read Only role.

Global Clusters
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "changeStreamOptionsPreAndPostImagesExpireAfterSeconds": -1,
  • "chunkMigrationConcurrency": 0,
  • "defaultMaxTimeMS": 0,
  • "defaultReadConcern": "local",
  • "defaultWriteConcern": "string",
  • "failIndexKeyTooLong": true,
  • "javascriptEnabled": true,
  • "minimumEnabledTlsProtocol": "TLS1_0",
  • "noTableScan": true,
  • "oplogMinRetentionHours": 0,
  • "oplogSizeMB": 0,
  • "queryStatsLogVerbosity": 0,
  • "sampleRefreshIntervalBIConnector": 0,
  • "sampleSizeBIConnector": 0,
  • "transactionLifetimeLimitSeconds": 1
}

Update Advanced Configuration Options for One Cluster

Updates the advanced configuration details for one cluster in the specified project. Clusters contain a group of hosts that maintain the same data set. Advanced configuration details include the read/write concern, index and oplog limits, and other database settings. To use this resource, the requesting API Key must have the Project Cluster Manager role. This feature isn't available for M0 free clusters, M2 and M5 shared-tier clusters, or serverless clusters.

Global Clusters
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Advanced configuration details to add for one cluster in the specified project.

changeStreamOptionsPreAndPostImagesExpireAfterSeconds
integer <int32>
Default: -1

The minimum pre- and post-image retention time in seconds.

This option corresponds to the ``changeStreamOptions.preAndPostImages.expireAfterSeconds`` cluster parameter. This setting controls the retention policy of change stream pre- and post-images. Pre- and post-images are the versions of a document before and after document modification, respectively. ``expireAfterSeconds`` controls how long MongoDB retains pre- and post-images. When set to -1 (off), MongoDB uses the default retention policy: pre- and post-images are retained until the corresponding change stream events are removed from the oplog. To set the minimum pre- and post-image retention time, specify an integer value greater than zero. Setting this too low could increase the risk of interrupting Realm sync or triggers processing. The default value is -1 (off).
chunkMigrationConcurrency
integer <int32>

Number of threads on the source shard and the receiving shard for chunk migration. The number of threads should not exceed the half the total number of CPU cores in the sharded cluster.

This option corresponds to the `chunkMigrationConcurrency` `mongod` configuration file option.
defaultMaxTimeMS
integer <int32>

Default time limit in milliseconds for individual read operations to complete.

This option corresponds to the defaultMaxTimeMS cluster parameter.
defaultReadConcern
string
Default: "available"
Enum: "local" "available"

Default level of acknowledgment requested from MongoDB for read operations set for this cluster.

MongoDB 4.4 clusters default to available. MongoDB 5.0 and later clusters default to local.

This option corresponds to the global default read concern.
defaultWriteConcern
string

Default level of acknowledgment requested from MongoDB for write operations when none is specified by the driver.

This option corresponds to the the implicit default write concern.
failIndexKeyTooLong
boolean
Deprecated
Default: true

Flag that indicates whether you can insert or update documents where all indexed entries don't exceed 1024 bytes. If you set this to false, mongod writes documents that exceed this limit but doesn't index them. This parameter has been removed as of MongoDB 4.4.

This option corresponds to the `failIndexKeyTooLong` `mongod` configuration file option.
javascriptEnabled
boolean

Flag that indicates whether the cluster allows execution of operations that perform server-side executions of JavaScript. When using 8.0+, we recommend disabling server-side JavaScript and using operators of aggregation pipeline as more performant alternative.

This option corresponds to modifying the `security.javascriptEnabled` configuration file option for each `mongod` and `mongos` in the cluster.
minimumEnabledTlsProtocol
string
Enum: "TLS1_0" "TLS1_1" "TLS1_2"

Minimum Transport Layer Security (TLS) version that the cluster accepts for incoming connections. Clusters using TLS 1.0 or 1.1 should consider setting TLS 1.2 as the minimum TLS protocol version.

This option corresponds to the `net.ssl.disabledProtocols` `mongod` configuration file option.
noTableScan
boolean

Flag that indicates whether the cluster disables executing any query that requires a collection scan to return results.

This option corresponds to the `notablescan` `mongod` configuration file option.
oplogMinRetentionHours
number or null <double>

Minimum retention window for cluster's oplog expressed in hours. A value of null indicates that the cluster uses the default minimum oplog window that MongoDB Cloud calculates.

This option corresponds to the `storage.oplogMinRetentionHours` `mongod` configuration file option.
oplogSizeMB
integer or null <int32>

Storage limit of cluster's oplog expressed in megabytes. A value of null indicates that the cluster uses the default oplog size that MongoDB Cloud calculates.

This option corresponds to the `replication.oplogSizeMB` `mongod` configuration file option.
queryStatsLogVerbosity
integer <int32>

May be set to 1 (disabled) or 3 (enabled). When set to 3, Atlas will include redacted and anonymized $queryStats output in MongoDB logs. $queryStats output does not contain literals or field values. Enabling this setting might impact the performance of your cluster.

This option corresponds to the queryStats component for the logComponentVerbosity server parameter.
sampleRefreshIntervalBIConnector
integer <int32> >= 0
Default: 0

Interval in seconds at which the mongosqld process re-samples data to create its relational schema.

This option corresponds to the `sampleRefreshIntervalSecs` `mongosqld` option.
sampleSizeBIConnector
integer <int32> >= 0

Number of documents per database to sample when gathering schema information.

This option corresponds to the `sampleSize` `mongosqld` option.
transactionLifetimeLimitSeconds
integer <int64> >= 1

Lifetime, in seconds, of multi-document transactions. Atlas considers the transactions that exceed this limit as expired and so aborts them through a periodic cleanup process.

This option corresponds to the `transactionLifetimeLimitSeconds` `mongod` configuration file option.

Responses

Request samples

Content type
application/json
{
  • "changeStreamOptionsPreAndPostImagesExpireAfterSeconds": -1,
  • "chunkMigrationConcurrency": 0,
  • "defaultMaxTimeMS": 0,
  • "defaultReadConcern": "local",
  • "defaultWriteConcern": "string",
  • "failIndexKeyTooLong": true,
  • "javascriptEnabled": true,
  • "minimumEnabledTlsProtocol": "TLS1_0",
  • "noTableScan": true,
  • "oplogMinRetentionHours": 0,
  • "oplogSizeMB": 0,
  • "queryStatsLogVerbosity": 0,
  • "sampleRefreshIntervalBIConnector": 0,
  • "sampleSizeBIConnector": 0,
  • "transactionLifetimeLimitSeconds": 1
}

Response samples

Content type
application/json
{
  • "changeStreamOptionsPreAndPostImagesExpireAfterSeconds": -1,
  • "chunkMigrationConcurrency": 0,
  • "defaultMaxTimeMS": 0,
  • "defaultReadConcern": "local",
  • "defaultWriteConcern": "string",
  • "failIndexKeyTooLong": true,
  • "javascriptEnabled": true,
  • "minimumEnabledTlsProtocol": "TLS1_0",
  • "noTableScan": true,
  • "oplogMinRetentionHours": 0,
  • "oplogSizeMB": 0,
  • "queryStatsLogVerbosity": 0,
  • "sampleRefreshIntervalBIConnector": 0,
  • "sampleSizeBIConnector": 0,
  • "transactionLifetimeLimitSeconds": 1
}

Test Failover for One Cluster

Starts a failover test for the specified cluster in the specified project. Clusters contain a group of hosts that maintain the same data set. A failover test checks how MongoDB Cloud handles the failure of the cluster's primary node. During the test, MongoDB Cloud shuts down the primary node and elects a new primary. To use this resource, the requesting API Key must have the Project Cluster Manager role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "detail": "(This is just an example, the exception may not be related to this endpoint)",
  • "error": 401,
  • "errorCode": "NOT_ORG_GROUP_CREATOR",
  • "reason": "Unauthorized"
}

Return Status of All Cluster Operations

Returns the status of all changes that you made to the specified cluster in the specified project. Use this resource to check the progress MongoDB Cloud has made in processing your changes. The response does not include the deployment of new dedicated clusters. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{}

Load Sample Dataset Request into Cluster

Requests loading the MongoDB sample dataset into the specified cluster. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

name
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster into which you load the sample dataset.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Responses

Response samples

Content type
application/json
{
  • "_id": "32b6e34b3d91647abb20e7b8",
  • "clusterName": "string",
  • "completeDate": "2019-08-24T14:15:22Z",
  • "createDate": "2019-08-24T14:15:22Z",
  • "errorMessage": "string",
  • "state": "WORKING"
}

Check Status of Cluster Sample Dataset Request

Checks the progress of loading the sample dataset into one cluster. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

sampleDatasetId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the loaded sample dataset.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Responses

Response samples

Content type
application/json
{
  • "_id": "32b6e34b3d91647abb20e7b8",
  • "clusterName": "string",
  • "completeDate": "2019-08-24T14:15:22Z",
  • "createDate": "2019-08-24T14:15:22Z",
  • "errorMessage": "string",
  • "state": "WORKING"
}

Custom Database Roles

Returns, adds, edits, and removes custom database user privilege roles. Use custom roles to specify custom sets of actions that the MongoDB Cloud built-in roles can't describe. You define custom roles at the project level, for all clusters in the project. This resource supports a subset of MongoDB privilege actions. You can create a subset of custom role actions. To create a wider list of custom role actions, use the MongoDB Cloud user interface. Custom roles must include actions that all project's clusters support, and that are compatible with each MongoDB version that your project's clusters use. For example, if your project has MongoDB 4.2 clusters, you can't create custom roles that use actions introduced in MongoDB 4.4.

Return All Custom Roles in One Project

Returns all custom roles for the specified project. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create One Custom Role

Creates one custom role in the specified project. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Creates one custom role in the specified project.

Array of objects (Database Privilege Action)

List of the individual privilege actions that the role grants.

Array of objects (Inherited Role) unique

List of the built-in roles that this custom role inherits.

roleName
required
string

Human-readable label that identifies the role for the request. This name must be unique for this custom role in this project.

Responses

Request samples

Content type
application/json
{
  • "actions": [
    ],
  • "inheritedRoles": [
    ],
  • "roleName": "string"
}

Response samples

Content type
application/json
{
  • "actions": [
    ],
  • "inheritedRoles": [
    ],
  • "roleName": "string"
}

Remove One Custom Role from One Project

Removes one custom role from the specified project. You can't remove a custom role that would leave one or more child roles with no parent roles or actions. You also can't remove a custom role that would leave one or more database users without roles. To use this resource, the requesting API Key must have the Project Atlas Admin role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

roleName
required
string

Human-readable label that identifies the role for the request. This name must be unique for this custom role in this project.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "detail": "(This is just an example, the exception may not be related to this endpoint) No provider AWS exists.",
  • "error": 400,
  • "errorCode": "VALIDATION_ERROR",
  • "reason": "Bad Request"
}

Return One Custom Role in One Project

Returns one custom role for the specified project. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

roleName
required
string

Human-readable label that identifies the role for the request. This name must be unique for this custom role in this project.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "actions": [
    ],
  • "inheritedRoles": [
    ],
  • "roleName": "string"
}

Update One Custom Role in One Project

Updates one custom role in the specified project. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

roleName
required
string

Human-readable label that identifies the role for the request. This name must beunique for this custom role in this project.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Updates one custom role in the specified project.

Array of objects (Database Privilege Action)

List of the individual privilege actions that the role grants.

Array of objects (Inherited Role) unique

List of the built-in roles that this custom role inherits.

Responses

Request samples

Content type
application/json
{
  • "actions": [
    ],
  • "inheritedRoles": [
    ]
}

Response samples

Content type
application/json
{
  • "actions": [
    ],
  • "inheritedRoles": [
    ],
  • "roleName": "string"
}

Data Federation

Returns, adds, edits, and removes Federated Database Instances. This resource requires your project ID. Changes to federated database instance configurations can affect costs.

Return All Federated Database Instances in One Project

Returns the details of all federated database instances in the specified project. To use this resource, the requesting API Key must have the Project Read Only or higher role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

type
string
Default: "USER"
Enum: "USER" "ONLINE_ARCHIVE"

Type of Federated Database Instances to return.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create One Federated Database Instance in One Project

Creates one federated database instance in the specified project. To use this resource, the requesting API Key must have the Project Owner or Project Charts Admin roles.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

skipRoleValidation
boolean
Default: false

Flag that indicates whether this request should check if the requesting IAM role can read from the S3 bucket. AWS checks if the role can list the objects in the bucket before writing to it. Some IAM roles only need write permissions. This flag allows you to skip that check.

Request Body schema: application/json

Details to create one federated database instance in the specified project.

object (Data Federation Cloud Provider)

Cloud provider where this Federated Database Instance is hosted.

object (DataLakeDataProcessRegion)

Information about the cloud provider region to which the Federated Database Instance routes client connections.

name
string

Human-readable label that identifies the Federated Database Instance.

object (DataLakeStorage)

Configuration information for each data store and its mapping to MongoDB Cloud databases.

Responses

Request samples

Content type
application/json
{
  • "cloudProviderConfig": {
    },
  • "dataProcessRegion": {
    },
  • "name": "string",
  • "storage": {
    }
}

Response samples

Content type
application/json
{
  • "cloudProviderConfig": {
    },
  • "dataProcessRegion": {
    },
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "hostnames": [
    ],
  • "name": "string",
  • "privateEndpointHostnames": [
    ],
  • "state": "UNVERIFIED",
  • "storage": {
    }
}

Remove One Federated Database Instance from One Project

Removes one federated database instance from the specified project. To use this resource, the requesting API Key must have the Project Owner or Project Charts Admin roles.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

tenantName
required
string

Human-readable label that identifies the federated database instance to remove.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{ }

Return One Federated Database Instance in One Project

Returns the details of one federated database instance within the specified project. To use this resource, the requesting API Key must have the Project Read Only or Project Charts Admin roles.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

tenantName
required
string

Human-readable label that identifies the Federated Database to return.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Responses

Response samples

Content type
application/json
{
  • "cloudProviderConfig": {
    },
  • "dataProcessRegion": {
    },
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "hostnames": [
    ],
  • "name": "string",
  • "privateEndpointHostnames": [
    ],
  • "state": "UNVERIFIED",
  • "storage": {
    }
}

Update One Federated Database Instance in One Project

Updates the details of one federated database instance in the specified project. To use this resource, the requesting API Key must have the Project Owner or higher role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

tenantName
required
string

Human-readable label that identifies the federated database instance to update.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

skipRoleValidation
required
boolean

Flag that indicates whether this request should check if the requesting IAM role can read from the S3 bucket. AWS checks if the role can list the objects in the bucket before writing to it. Some IAM roles only need write permissions. This flag allows you to skip that check.

Request Body schema: application/json

Details of one Federated Database to update in the specified project.

object (Data Federation Cloud Provider)

Cloud provider where this Federated Database Instance is hosted.

object (DataLakeDataProcessRegion)

Information about the cloud provider region to which the Federated Database Instance routes client connections.

name
string

Human-readable label that identifies the Federated Database Instance.

object (DataLakeStorage)

Configuration information for each data store and its mapping to MongoDB Cloud databases.

Responses

Request samples

Content type
application/json
{
  • "cloudProviderConfig": {
    },
  • "dataProcessRegion": {
    },
  • "name": "string",
  • "storage": {
    }
}

Response samples

Content type
application/json
{
  • "cloudProviderConfig": {
    },
  • "dataProcessRegion": {
    },
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "hostnames": [
    ],
  • "name": "string",
  • "privateEndpointHostnames": [
    ],
  • "state": "UNVERIFIED",
  • "storage": {
    }
}

Return All Query Limits for One Federated Database Instance

Returns query limits for a federated databases instance in the specified project. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

tenantName
required
string

Human-readable label that identifies the federated database instance for which you want to retrieve query limits.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete One Query Limit For One Federated Database Instance

Deletes one query limit for one federated database instance. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

tenantName
required
string

Human-readable label that identifies the federated database instance to which the query limit applies.

limitName
required
string
Enum: "bytesProcessed.query" "bytesProcessed.daily" "bytesProcessed.weekly" "bytesProcessed.monthly"

Human-readable label that identifies this data federation instance limit.

Limit Name Description Default
bytesProcessed.query Limit on the number of bytes processed during a single data federation query N/A
bytesProcessed.daily Limit on the number of bytes processed for the data federation instance for the current day N/A
bytesProcessed.weekly Limit on the number of bytes processed for the data federation instance for the current week N/A
bytesProcessed.monthly Limit on the number of bytes processed for the data federation instance for the current month N/A
query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Responses

Response samples

Content type
application/json
{ }

Return One Federated Database Instance Query Limit for One Project

Returns the details of one query limit for the specified federated database instance in the specified project. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

tenantName
required
string

Human-readable label that identifies the federated database instance to which the query limit applies.

limitName
required
string
Enum: "bytesProcessed.query" "bytesProcessed.daily" "bytesProcessed.weekly" "bytesProcessed.monthly"

Human-readable label that identifies this data federation instance limit.

Limit Name Description Default
bytesProcessed.query Limit on the number of bytes processed during a single data federation query N/A
bytesProcessed.daily Limit on the number of bytes processed for the data federation instance for the current day N/A
bytesProcessed.weekly Limit on the number of bytes processed for the data federation instance for the current week N/A
bytesProcessed.monthly Limit on the number of bytes processed for the data federation instance for the current month N/A
query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "currentUsage": 0,
  • "defaultLimit": 0,
  • "lastModifiedDate": "2019-08-24T14:15:22Z",
  • "maximumLimit": 0,
  • "name": "string",
  • "overrunPolicy": "BLOCK",
  • "tenantName": "string",
  • "value": 0
}

Configure One Query Limit for One Federated Database Instance

Creates or updates one query limit for one federated database instance. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

tenantName
required
string

Human-readable label that identifies the federated database instance to which the query limit applies.

limitName
required
string
Enum: "bytesProcessed.query" "bytesProcessed.daily" "bytesProcessed.weekly" "bytesProcessed.monthly"

Human-readable label that identifies this data federation instance limit.

Limit Name Description Default
bytesProcessed.query Limit on the number of bytes processed during a single data federation query N/A
bytesProcessed.daily Limit on the number of bytes processed for the data federation instance for the current day N/A
bytesProcessed.weekly Limit on the number of bytes processed for the data federation instance for the current week N/A
bytesProcessed.monthly Limit on the number of bytes processed for the data federation instance for the current month N/A
query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Request Body schema: application/json

Creates or updates one query limit for one federated database instance.

overrunPolicy
string
Enum: "BLOCK" "BLOCK_AND_KILL"

Only used for Data Federation limits. Action to take when the usage limit is exceeded. If limit span is set to QUERY, this is ignored because MongoDB Cloud stops the query when it exceeds the usage limit.

value
required
integer <int64>

Amount to set the limit to.

Responses

Request samples

Content type
application/json
{
  • "overrunPolicy": "BLOCK",
  • "value": 0
}

Response samples

Content type
application/json
{
  • "currentUsage": 0,
  • "defaultLimit": 0,
  • "lastModifiedDate": "2019-08-24T14:15:22Z",
  • "maximumLimit": 0,
  • "name": "string",
  • "overrunPolicy": "BLOCK",
  • "tenantName": "string",
  • "value": 0
}

Download Query Logs for One Federated Database Instance

Downloads the query logs for the specified federated database instance. To use this resource, the requesting API Key must have the Project Owner or Project Data Access Read Write roles. The API does not support direct calls with the json response schema. You must request a gzip response schema using an accept header of the format: "Accept: application/gzip".

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

tenantName
required
string

Human-readable label that identifies the federated database instance for which you want to download query logs.

query Parameters
endDate
integer <int64> 1199145600
Example: endDate=1636481348

Timestamp that specifies the end point for the range of log messages to download. MongoDB Cloud expresses this timestamp in the number of seconds that have elapsed since the UNIX epoch.

startDate
integer <int64> 1199145600
Example: startDate=1636466948

Timestamp that specifies the starting point for the range of log messages to download. MongoDB Cloud expresses this timestamp in the number of seconds that have elapsed since the UNIX epoch.

Responses

Response samples

Content type
application/json
{
  • "detail": "(This is just an example, the exception may not be related to this endpoint) No provider AWS exists.",
  • "error": 400,
  • "errorCode": "VALIDATION_ERROR",
  • "reason": "Bad Request"
}

Return All Federated Database Instance and Online Archive Private Endpoints in One Project

Returns all private endpoints for Federated Database Instances and Online Archives in the specified project. To use this resource, the requesting API Key must have the Project Read Only or Project Charts Admin roles.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Create One Federated Database Instance and Online Archive Private Endpoint for One Project

Adds one private endpoint for Federated Database Instances and Online Archives to the specified projects. If the endpoint ID already exists and the associated comment is unchanged, Atlas Data Federation makes no change to the endpoint ID list. If the endpoint ID already exists and the associated comment is changed, Atlas Data Federation updates the comment value only in the endpoint ID list. If the endpoint ID doesn't exist, Atlas Data Federation appends the new endpoint to the list of endpoints in the endpoint ID list. Each region has an associated service name for the various endpoints in each region.

us-east-1 is com.amazonaws.vpce.us-east-1.vpce-svc-00e311695874992b4.

us-west-1 is com.amazonaws.vpce.us-west-2.vpce-svc-09d86b19e59d1b4bb.

eu-west-1 is com.amazonaws.vpce.eu-west-1.vpce-svc-0824460b72e1a420e.

eu-west-2 is com.amazonaws.vpce.eu-west-2.vpce-svc-052f1840aa0c4f1f9.

eu-central-1 is com.amazonaws.vpce.eu-central-1.vpce-svc-0ac8ce91871138c0d.

sa-east-1 is com.amazonaws.vpce.sa-east-1.vpce-svc-0b56e75e8cdf50044.

ap-southeast-2 is com.amazonaws.vpce.ap-southeast-2.vpce-svc-036f1de74d761706e.

ap-south-1 is com.amazonaws.vpce.ap-south-1.vpce-svc-03eb8a541f96d356d.

To use this resource, the requesting API Key must have the Project Owner or Project Charts Admin roles.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Private endpoint for Federated Database Instances and Online Archives to add to the specified project.

azureConnectionName
string

Connection name that identifies the Azure private endpoint connection.

azureLinkId
string

Link ID that identifies the Azure private endpoint connection.

comment
string

Human-readable string to associate with this private endpoint.

customerEndpointDNSName
string

Human-readable label to identify customer's VPC endpoint DNS name. If defined, you must also specify a value for region.

customerEndpointIPAddress
string^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)(\.(?!$)|$))...

IP address used to connect to the Azure private endpoint.

endpointId
required
string = 22 characters ^vpce-[0-9a-f]{17}$

Unique 22-character alphanumeric string that identifies the private endpoint.

Atlas Data Lake supports Amazon Web Services private endpoints using the AWS PrivateLink feature.
errorMessage
string

Error message describing a failure approving the private endpoint request.

provider
string
Default: "AWS"
Value: "AWS"

Human-readable label that identifies the cloud service provider. Atlas Data Lake supports Amazon Web Services only.

region
string

Human-readable label to identify the region of customer's VPC endpoint. If defined, you must also specify a value for customerEndpointDNSName.

status
string
Enum: "PENDING" "OK" "FAILED" "DELETING"

Status of the private endpoint connection request.

type
string
Default: "DATA_LAKE"
Value: "DATA_LAKE"

Human-readable label that identifies the resource type associated with this private endpoint.

Responses

Request samples

Content type
application/json
{
  • "azureConnectionName": "string",
  • "azureLinkId": "string",
  • "comment": "string",
  • "customerEndpointDNSName": "string",
  • "customerEndpointIPAddress": "string",
  • "endpointId": "vpce-3bf78b0ddee411ba1",
  • "errorMessage": "string",
  • "provider": "AWS",
  • "region": "US_EAST_1",
  • "status": "PENDING",
  • "type": "DATA_LAKE"
}

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Remove One Federated Database Instance and Online Archive Private Endpoint from One Project

Removes one private endpoint for Federated Database Instances and Online Archives in the specified project. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

endpointId
required
string = 22 characters ^vpce-[0-9a-f]{17}$

Unique 22-character alphanumeric string that identifies the private endpoint to remove. Atlas Data Federation supports AWS private endpoints using the AWS PrivateLink feature.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{ }

Return One Federated Database Instance and Online Archive Private Endpoint in One Project

Returns the specified private endpoint for Federated Database Instances or Online Archives in the specified project. To use this resource, the requesting API Key must have the Project Read Only or Project Charts Admin roles.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

endpointId
required
string = 22 characters ^vpce-[0-9a-f]{17}$

Unique 22-character alphanumeric string that identifies the private endpoint to return. Atlas Data Federation supports AWS private endpoints using the AWS PrivateLink feature.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "azureConnectionName": "string",
  • "azureLinkId": "string",
  • "comment": "string",
  • "customerEndpointDNSName": "string",
  • "customerEndpointIPAddress": "string",
  • "endpointId": "vpce-3bf78b0ddee411ba1",
  • "errorMessage": "string",
  • "provider": "AWS",
  • "region": "US_EAST_1",
  • "status": "PENDING",
  • "type": "DATA_LAKE"
}

Data Lake Pipelines

Returns, edits, and removes Atlas Data Lake Pipelines and associated runs.

Data Lake Pipelines are deprecated. Please see Data Lake Deprecation Guide.

Return All Data Lake Pipelines from One Project Deprecated

Returns a list of Data Lake Pipelines. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create One Data Lake Pipeline Deprecated

Creates one Data Lake Pipeline.

Data Lake Pipelines are deprecated. Please see Data Lake Deprecation Guide.
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Request Body schema: application/json

Creates one Data Lake Pipeline.

object (Dataset Retention Policy)

Dataset Retention Policy for a Scheduled Data Lake Pipeline.

name
string

Name of this Data Lake Pipeline.

object (Ingestion Destination)

Ingestion destination of a Data Lake Pipeline.

object (Ingestion Source)

Ingestion Source of a Data Lake Pipeline.

Array of objects (Field Transformation)

Fields to be excluded for this Data Lake Pipeline.

Responses

Request samples

Content type
application/json
{
  • "datasetRetentionPolicy": {
    },
  • "name": "string",
  • "sink": { },
  • "source": {
    },
  • "transformations": [
    ]
}

Response samples

Content type
application/json
{
  • "_id": "32b6e34b3d91647abb20e7b8",
  • "createdDate": "2019-08-24T14:15:22Z",
  • "datasetRetentionPolicy": {
    },
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "lastUpdatedDate": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "sink": {
    },
  • "source": {
    },
  • "state": "ACTIVE",
  • "transformations": [
    ]
}

Remove One Data Lake Pipeline Deprecated

Removes one Data Lake Pipeline.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

pipelineName
required
string [ 1 .. 64 ] characters ^[^/\\ "$]{1,64}$

Human-readable label that identifies the Data Lake Pipeline.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Responses

Response samples

Content type
application/json
{ }

Return One Data Lake Pipeline Deprecated

Returns the details of one Data Lake Pipeline within the specified project. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

pipelineName
required
string [ 1 .. 64 ] characters ^[^/\\ "$]{1,64}$

Human-readable label that identifies the Data Lake Pipeline.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "_id": "32b6e34b3d91647abb20e7b8",
  • "createdDate": "2019-08-24T14:15:22Z",
  • "datasetRetentionPolicy": {
    },
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "lastUpdatedDate": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "sink": {
    },
  • "source": {
    },
  • "state": "ACTIVE",
  • "transformations": [
    ]
}

Update One Data Lake Pipeline Deprecated

Updates one Data Lake Pipeline.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

pipelineName
required
string [ 1 .. 64 ] characters ^[^/\\ "$]{1,64}$

Human-readable label that identifies the Data Lake Pipeline.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Request Body schema: application/json

Updates one Data Lake Pipeline.

object (Dataset Retention Policy)

Dataset Retention Policy for a Scheduled Data Lake Pipeline.

name
string

Name of this Data Lake Pipeline.

object (Ingestion Destination)

Ingestion destination of a Data Lake Pipeline.

object (Ingestion Source)

Ingestion Source of a Data Lake Pipeline.

Array of objects (Field Transformation)

Fields to be excluded for this Data Lake Pipeline.

Responses

Request samples

Content type
application/json
{
  • "datasetRetentionPolicy": {
    },
  • "name": "string",
  • "sink": { },
  • "source": {
    },
  • "transformations": [
    ]
}

Response samples

Content type
application/json
{
  • "_id": "32b6e34b3d91647abb20e7b8",
  • "createdDate": "2019-08-24T14:15:22Z",
  • "datasetRetentionPolicy": {
    },
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "lastUpdatedDate": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "sink": {
    },
  • "source": {
    },
  • "state": "ACTIVE",
  • "transformations": [
    ]
}

Return Available Ingestion Schedules for One Data Lake Pipeline Deprecated

Returns a list of backup schedule policy items that you can use as a Data Lake Pipeline source. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

pipelineName
required
string [ 1 .. 64 ] characters ^[^/\\ "$]{1,64}$

Human-readable label that identifies the Data Lake Pipeline.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Return Available Backup Snapshots for One Data Lake Pipeline Deprecated

Returns a list of backup snapshots that you can use to trigger an on demand pipeline run. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

pipelineName
required
string [ 1 .. 64 ] characters ^[^/\\ "$]{1,64}$

Human-readable label that identifies the Data Lake Pipeline.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

completedAfter
string <date-time>
Example: completedAfter=2022-01-01T00:00:00Z

Date and time after which MongoDB Cloud created the snapshot. If specified, MongoDB Cloud returns available backup snapshots created after this time and date only. This parameter expresses its value in the ISO 8601 timestamp format in UTC.

Responses

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Pause One Data Lake Pipeline Deprecated

Pauses ingestion for a Data Lake Pipeline within the specified project. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

pipelineName
required
string [ 1 .. 64 ] characters ^[^/\\ "$]{1,64}$

Human-readable label that identifies the Data Lake Pipeline.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "_id": "32b6e34b3d91647abb20e7b8",
  • "createdDate": "2019-08-24T14:15:22Z",
  • "datasetRetentionPolicy": {
    },
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "lastUpdatedDate": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "sink": {
    },
  • "source": {
    },
  • "state": "ACTIVE",
  • "transformations": [
    ]
}

Resume One Data Lake Pipeline Deprecated

Resumes ingestion for a Data Lake Pipeline within the specified project. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

pipelineName
required
string [ 1 .. 64 ] characters ^[^/\\ "$]{1,64}$

Human-readable label that identifies the Data Lake Pipeline.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "_id": "32b6e34b3d91647abb20e7b8",
  • "createdDate": "2019-08-24T14:15:22Z",
  • "datasetRetentionPolicy": {
    },
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "lastUpdatedDate": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "sink": {
    },
  • "source": {
    },
  • "state": "ACTIVE",
  • "transformations": [
    ]
}

Return All Data Lake Pipeline Runs from One Project Deprecated

Returns a list of past Data Lake Pipeline runs. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

pipelineName
required
string [ 1 .. 64 ] characters ^[^/\\ "$]{1,64}$

Human-readable label that identifies the Data Lake Pipeline.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

createdBefore
string <date-time>
Example: createdBefore=2022-01-01T00:00:00Z

If specified, Atlas returns only Data Lake Pipeline runs initiated before this time and date.

Responses

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Delete Pipeline Run Dataset Deprecated

Deletes dataset that Atlas generated during the specified pipeline run.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

pipelineName
required
string [ 1 .. 64 ] characters ^[^/\\ "$]{1,64}$

Human-readable label that identifies the Data Lake Pipeline.

pipelineRunId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal character string that identifies a Data Lake Pipeline run.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{ }

Return One Data Lake Pipeline Run Deprecated

Returns the details of one Data Lake Pipeline run within the specified project. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

pipelineName
required
string [ 1 .. 64 ] characters ^[^/\\ "$]{1,64}$

Human-readable label that identifies the Data Lake Pipeline.

pipelineRunId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal character string that identifies a Data Lake Pipeline run.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "_id": "32b6e34b3d91647abb20e7b8",
  • "backupFrequencyType": "HOURLY",
  • "createdDate": "2019-08-24T14:15:22Z",
  • "datasetName": "v1$atlas$snapshot$Cluster0$myDatabase$myCollection$19700101T000000Z",
  • "datasetRetentionPolicy": {
    },
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "lastUpdatedDate": "2019-08-24T14:15:22Z",
  • "phase": "SNAPSHOT",
  • "pipelineId": "32b6e34b3d91647abb20e7b8",
  • "scheduledDeletionDate": "2019-08-24T14:15:22Z",
  • "snapshotId": "32b6e34b3d91647abb20e7b8",
  • "state": "PENDING",
  • "stats": {
    }
}

Trigger on demand snapshot ingestion Deprecated

Triggers a Data Lake Pipeline ingestion of a specified snapshot.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

pipelineName
required
string [ 1 .. 64 ] characters ^[^/\\ "$]{1,64}$

Human-readable label that identifies the Data Lake Pipeline.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Triggers a single ingestion run of a snapshot.

object (Dataset Retention Policy)

Dataset Retention Policy for a Scheduled Data Lake Pipeline.

snapshotId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal character string that identifies the snapshot.

Responses

Request samples

Content type
application/json
{
  • "datasetRetentionPolicy": {
    },
  • "snapshotId": "32b6e34b3d91647abb20e7b8"
}

Response samples

Content type
application/json
{
  • "_id": "32b6e34b3d91647abb20e7b8",
  • "backupFrequencyType": "HOURLY",
  • "createdDate": "2019-08-24T14:15:22Z",
  • "datasetName": "v1$atlas$snapshot$Cluster0$myDatabase$myCollection$19700101T000000Z",
  • "datasetRetentionPolicy": {
    },
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "lastUpdatedDate": "2019-08-24T14:15:22Z",
  • "phase": "SNAPSHOT",
  • "pipelineId": "32b6e34b3d91647abb20e7b8",
  • "scheduledDeletionDate": "2019-08-24T14:15:22Z",
  • "snapshotId": "32b6e34b3d91647abb20e7b8",
  • "state": "PENDING",
  • "stats": {
    }
}

Database Users

Returns, adds, edits, and removes database users.

Return All Database Users from One Project

Returns all database users that belong to the specified project. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Create One Database User in One Project

Creates one database user in the specified project. This MongoDB Cloud supports a maximum of 100 database users per project. If you require more than 100 database users on a project, contact Support. To use this resource, the requesting API Key must have the Project Owner or Project Charts Admin roles.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Creates one database user in the specified project.

awsIAMType
string
Default: "NONE"
Enum: "NONE" "USER" "ROLE"

Human-readable label that indicates whether the new database user authenticates with the Amazon Web Services (AWS) Identity and Access Management (IAM) credentials associated with the user or the user's role.

databaseName
required
string
Default: "admin"
Enum: "admin" "$external"

The database against which the database user authenticates. Database users must provide both a username and authentication database to log into MongoDB. If the user authenticates with AWS IAM, x.509, LDAP, or OIDC Workload this value should be $external. If the user authenticates with SCRAM-SHA or OIDC Workforce, this value should be admin.

deleteAfterDate
string <date-time>

Date and time when MongoDB Cloud deletes the user. This parameter expresses its value in the ISO 8601 timestamp format in UTC and can include the time zone designation. You must specify a future date that falls within one week of making the Application Programming Interface (API) request.

description
string <= 100 characters

Description of this database user.

groupId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the project.

Array of objects (Component Label)

List that contains the key-value pairs for tagging and categorizing the MongoDB database user. The labels that you define do not appear in the console.

ldapAuthType
string
Default: "NONE"
Enum: "NONE" "GROUP" "USER"

Part of the Lightweight Directory Access Protocol (LDAP) record that the database uses to authenticate this database user on the LDAP host.

oidcAuthType
string
Default: "NONE"
Enum: "NONE" "IDP_GROUP" "USER"

Human-readable label that indicates whether the new database user or group authenticates with OIDC federated authentication. To create a federated authentication user, specify the value of USER in this field. To create a federated authentication group, specify the value of IDP_GROUP in this field.

password
string >= 8 characters

Alphanumeric string that authenticates this database user against the database specified in databaseName. To authenticate with SCRAM-SHA, you must specify this parameter. This parameter doesn't appear in this response.

SCRAM-SHA
Array of objects (Database User Role)

List that provides the pairings of one role with one applicable database.

Array of objects (Database User Scope)

List that contains clusters, MongoDB Atlas Data Lakes, and MongoDB Atlas Streams Instances that this database user can access. If omitted, MongoDB Cloud grants the database user access to all the clusters, MongoDB Atlas Data Lakes, and MongoDB Atlas Streams Instances in the project.

username
required
string <= 1024 characters

Human-readable label that represents the user that authenticates to MongoDB. The format of this label depends on the method of authentication:

Authentication Method Parameter Needed Parameter Value username Format
AWS IAM awsIAMType ROLE ARN
AWS IAM awsIAMType USER ARN
x.509 x509Type CUSTOMER RFC 2253 Distinguished Name
x.509 x509Type MANAGED RFC 2253 Distinguished Name
LDAP ldapAuthType USER RFC 2253 Distinguished Name
LDAP ldapAuthType GROUP RFC 2253 Distinguished Name
OIDC Workforce oidcAuthType IDP_GROUP Atlas OIDC IdP ID (found in federation settings), followed by a '/', followed by the IdP group name
OIDC Workload oidcAuthType USER Atlas OIDC IdP ID (found in federation settings), followed by a '/', followed by the IdP user name
SCRAM-SHA awsIAMType, x509Type, ldapAuthType, oidcAuthType NONE Alphanumeric string
x509Type
string
Default: "NONE"
Enum: "NONE" "CUSTOMER" "MANAGED"

X.509 method that MongoDB Cloud uses to authenticate the database user.

  • For application-managed X.509, specify MANAGED.
  • For self-managed X.509, specify CUSTOMER.

Users created with the CUSTOMER method require a Common Name (CN) in the username parameter. You must create externally authenticated users on the $external database.

Responses

Request samples

Content type
application/json
Example

AWS IAM Authentication

{
  • "awsIAMType": "USER",
  • "databaseName": "$external",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "roles": [
    ],
  • "scopes": [
    ],
  • "username": "arn:aws:iam::358363220050:user/mongodb-aws-iam-auth-test-user"
}

Response samples

Content type
application/json
{
  • "awsIAMType": "NONE",
  • "databaseName": "admin",
  • "deleteAfterDate": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "labels": [
    ],
  • "ldapAuthType": "NONE",
  • "links": [],
  • "oidcAuthType": "NONE",
  • "roles": [
    ],
  • "scopes": [
    ],
  • "username": "string",
  • "x509Type": "NONE"
}

Remove One Database User from One Project

Removes one database user from the specified project. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

databaseName
required
string

The database against which the database user authenticates. Database users must provide both a username and authentication database to log into MongoDB. If the user authenticates with AWS IAM, x.509, LDAP, or OIDC Workload this value should be $external. If the user authenticates with SCRAM-SHA or OIDC Workforce, this value should be admin.

username
required
string
Example: SCRAM-SHA: dylan or AWS IAM: arn:aws:iam::123456789012:user/sales/enterprise/DylanBloggs or x.509/LDAP: CN=Dylan Bloggs,OU=Enterprise,OU=Sales,DC=Example,DC=COM or OIDC: IdPIdentifier/IdPGroupName

Human-readable label that represents the user that authenticates to MongoDB. The format of this label depends on the method of authentication:

Authentication Method Parameter Needed Parameter Value username Format
AWS IAM awsIAMType ROLE ARN
AWS IAM awsIAMType USER ARN
x.509 x509Type CUSTOMER RFC 2253 Distinguished Name
x.509 x509Type MANAGED RFC 2253 Distinguished Name
LDAP ldapAuthType USER RFC 2253 Distinguished Name
LDAP ldapAuthType GROUP RFC 2253 Distinguished Name
OIDC Workforce oidcAuthType IDP_GROUP Atlas OIDC IdP ID (found in federation settings), followed by a '/', followed by the IdP group name
OIDC Workload oidcAuthType USER Atlas OIDC IdP ID (found in federation settings), followed by a '/', followed by the IdP user name
SCRAM-SHA awsIAMType, x509Type, ldapAuthType, oidcAuthType NONE Alphanumeric string
query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{ }

Return One Database User from One Project

Returns one database user that belong to the specified project. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

databaseName
required
string

The database against which the database user authenticates. Database users must provide both a username and authentication database to log into MongoDB. If the user authenticates with AWS IAM, x.509, LDAP, or OIDC Workload this value should be $external. If the user authenticates with SCRAM-SHA or OIDC Workforce, this value should be admin.

username
required
string
Example: SCRAM-SHA: dylan or AWS IAM: arn:aws:iam::123456789012:user/sales/enterprise/DylanBloggs or x.509/LDAP: CN=Dylan Bloggs,OU=Enterprise,OU=Sales,DC=Example,DC=COM or OIDC: IdPIdentifier/IdPGroupName

Human-readable label that represents the user that authenticates to MongoDB. The format of this label depends on the method of authentication:

Authentication Method Parameter Needed Parameter Value username Format
AWS IAM awsIAMType ROLE ARN
AWS IAM awsIAMType USER ARN
x.509 x509Type CUSTOMER RFC 2253 Distinguished Name
x.509 x509Type MANAGED RFC 2253 Distinguished Name
LDAP ldapAuthType USER RFC 2253 Distinguished Name
LDAP ldapAuthType GROUP RFC 2253 Distinguished Name
OIDC Workforce oidcAuthType IDP_GROUP Atlas OIDC IdP ID (found in federation settings), followed by a '/', followed by the IdP group name
OIDC Workload oidcAuthType USER Atlas OIDC IdP ID (found in federation settings), followed by a '/', followed by the IdP user name
SCRAM-SHA awsIAMType, x509Type, ldapAuthType, oidcAuthType NONE Alphanumeric string
query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "awsIAMType": "NONE",
  • "databaseName": "admin",
  • "deleteAfterDate": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "labels": [
    ],
  • "ldapAuthType": "NONE",
  • "links": [],
  • "oidcAuthType": "NONE",
  • "roles": [
    ],
  • "scopes": [
    ],
  • "username": "string",
  • "x509Type": "NONE"
}

Update One Database User in One Project

Updates one database user that belongs to the specified project. To use this resource, the requesting API Key must have the Project Owner or Project Charts Admin roles.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

databaseName
required
string

The database against which the database user authenticates. Database users must provide both a username and authentication database to log into MongoDB. If the user authenticates with AWS IAM, x.509, LDAP, or OIDC Workload this value should be $external. If the user authenticates with SCRAM-SHA or OIDC Workforce, this value should be admin.

username
required
string
Example: SCRAM-SHA: dylan or AWS IAM: arn:aws:iam::123456789012:user/sales/enterprise/DylanBloggs or x.509/LDAP: CN=Dylan Bloggs,OU=Enterprise,OU=Sales,DC=Example,DC=COM or OIDC: IdPIdentifier/IdPGroupName

Human-readable label that represents the user that authenticates to MongoDB. The format of this label depends on the method of authentication:

Authentication Method Parameter Needed Parameter Value username Format
AWS IAM awsIAMType ROLE ARN
AWS IAM awsIAMType USER ARN
x.509 x509Type CUSTOMER RFC 2253 Distinguished Name
x.509 x509Type MANAGED RFC 2253 Distinguished Name
LDAP ldapAuthType USER RFC 2253 Distinguished Name
LDAP ldapAuthType GROUP RFC 2253 Distinguished Name
OIDC Workforce oidcAuthType IDP_GROUP Atlas OIDC IdP ID (found in federation settings), followed by a '/', followed by the IdP group name
OIDC Workload oidcAuthType USER Atlas OIDC IdP ID (found in federation settings), followed by a '/', followed by the IdP user name
SCRAM-SHA awsIAMType, x509Type, ldapAuthType, oidcAuthType NONE Alphanumeric string
query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Updates one database user that belongs to the specified project.

awsIAMType
string
Default: "NONE"
Enum: "NONE" "USER" "ROLE"

Human-readable label that indicates whether the new database user authenticates with the Amazon Web Services (AWS) Identity and Access Management (IAM) credentials associated with the user or the user's role.

databaseName
required
string
Default: "admin"
Enum: "admin" "$external"

The database against which the database user authenticates. Database users must provide both a username and authentication database to log into MongoDB. If the user authenticates with AWS IAM, x.509, LDAP, or OIDC Workload this value should be $external. If the user authenticates with SCRAM-SHA or OIDC Workforce, this value should be admin.

deleteAfterDate
string <date-time>

Date and time when MongoDB Cloud deletes the user. This parameter expresses its value in the ISO 8601 timestamp format in UTC and can include the time zone designation. You must specify a future date that falls within one week of making the Application Programming Interface (API) request.

description
string <= 100 characters

Description of this database user.

groupId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the project.

Array of objects (Component Label)

List that contains the key-value pairs for tagging and categorizing the MongoDB database user. The labels that you define do not appear in the console.

ldapAuthType
string
Default: "NONE"
Enum: "NONE" "GROUP" "USER"

Part of the Lightweight Directory Access Protocol (LDAP) record that the database uses to authenticate this database user on the LDAP host.

oidcAuthType
string
Default: "NONE"
Enum: "NONE" "IDP_GROUP" "USER"

Human-readable label that indicates whether the new database user or group authenticates with OIDC federated authentication. To create a federated authentication user, specify the value of USER in this field. To create a federated authentication group, specify the value of IDP_GROUP in this field.

password
string >= 8 characters

Alphanumeric string that authenticates this database user against the database specified in databaseName. To authenticate with SCRAM-SHA, you must specify this parameter. This parameter doesn't appear in this response.

SCRAM-SHA
Array of objects (Database User Role)

List that provides the pairings of one role with one applicable database.

Array of objects (Database User Scope)

List that contains clusters, MongoDB Atlas Data Lakes, and MongoDB Atlas Streams Instances that this database user can access. If omitted, MongoDB Cloud grants the database user access to all the clusters, MongoDB Atlas Data Lakes, and MongoDB Atlas Streams Instances in the project.

username
required
string <= 1024 characters

Human-readable label that represents the user that authenticates to MongoDB. The format of this label depends on the method of authentication:

Authentication Method Parameter Needed Parameter Value username Format
AWS IAM awsIAMType ROLE ARN
AWS IAM awsIAMType USER ARN
x.509 x509Type CUSTOMER RFC 2253 Distinguished Name
x.509 x509Type MANAGED RFC 2253 Distinguished Name
LDAP ldapAuthType USER RFC 2253 Distinguished Name
LDAP ldapAuthType GROUP RFC 2253 Distinguished Name
OIDC Workforce oidcAuthType IDP_GROUP Atlas OIDC IdP ID (found in federation settings), followed by a '/', followed by the IdP group name
OIDC Workload oidcAuthType USER Atlas OIDC IdP ID (found in federation settings), followed by a '/', followed by the IdP user name
SCRAM-SHA awsIAMType, x509Type, ldapAuthType, oidcAuthType NONE Alphanumeric string
x509Type
string
Default: "NONE"
Enum: "NONE" "CUSTOMER" "MANAGED"

X.509 method that MongoDB Cloud uses to authenticate the database user.

  • For application-managed X.509, specify MANAGED.
  • For self-managed X.509, specify CUSTOMER.

Users created with the CUSTOMER method require a Common Name (CN) in the username parameter. You must create externally authenticated users on the $external database.

Responses

Request samples

Content type
application/json
{
  • "awsIAMType": "NONE",
  • "databaseName": "admin",
  • "deleteAfterDate": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "labels": [
    ],
  • "ldapAuthType": "NONE",
  • "oidcAuthType": "NONE",
  • "password": "stringst",
  • "roles": [
    ],
  • "scopes": [
    ],
  • "username": "string",
  • "x509Type": "NONE"
}

Response samples

Content type
application/json
{
  • "awsIAMType": "NONE",
  • "databaseName": "admin",
  • "deleteAfterDate": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "labels": [
    ],
  • "ldapAuthType": "NONE",
  • "links": [],
  • "oidcAuthType": "NONE",
  • "roles": [
    ],
  • "scopes": [
    ],
  • "username": "string",
  • "x509Type": "NONE"
}

Encryption at Rest using Customer Key Management

Returns and edits the Encryption at Rest using Customer Key Management configuration. MongoDB Cloud encrypts all storage whether or not you use your own key management.

Return One Configuration for Encryption at Rest using Customer-Managed Keys for One Project

Returns the configuration for encryption at rest using the keys you manage through your cloud provider. MongoDB Cloud encrypts all storage even if you don't use your own key management. This resource requires the requesting API Key to have the Project Owner role.

LIMITED TO M10 OR GREATER: MongoDB Cloud limits this feature to dedicated cluster tiers of M10 and greater.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "awsKms": {
    },
  • "azureKeyVault": {},
  • "googleCloudKms": {
    }
}

Update Configuration for Encryption at Rest using Customer-Managed Keys for One Project

Updates the configuration for encryption at rest using the keys you manage through your cloud provider. MongoDB Cloud encrypts all storage even if you don't use your own key management. This resource requires the requesting API Key to have the Project Owner role. This feature isn't available for M0 free clusters, M2, M5, or serverless clusters.

After you configure at least one Encryption at Rest using a Customer Key Management provider for the MongoDB Cloud project, Project Owners can enable Encryption at Rest using Customer Key Management for each MongoDB Cloud cluster for which they require encryption. The Encryption at Rest using Customer Key Management provider doesn't have to match the cluster cloud service provider. MongoDB Cloud doesn't automatically rotate user-managed encryption keys. Defer to your preferred Encryption at Rest using Customer Key Management provider's documentation and guidance for best practices on key rotation. MongoDB Cloud automatically creates a 90-day key rotation alert when you configure Encryption at Rest using Customer Key Management using your Key Management in an MongoDB Cloud project. MongoDB Cloud encrypts all storage whether or not you use your own key management.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Required parameters depend on whether someone has enabled Encryption at Rest using Customer Key Management:

If you have enabled Encryption at Rest using Customer Key Management (CMK), Atlas requires all of the parameters for the desired encryption provider.

  • To use AWS Key Management Service (KMS), MongoDB Cloud requires all the fields in the awsKms object.
  • To use Azure Key Vault, MongoDB Cloud requires all the fields in the azureKeyVault object.
  • To use Google Cloud Key Management Service (KMS), MongoDB Cloud requires all the fields in the googleCloudKms object.

If you enabled Encryption at Rest using Customer Key Management, administrators can pass only the changed fields for the awsKms, azureKeyVault, or googleCloudKms object to update the configuration to this endpoint.

object (AWSKMSConfiguration)

Amazon Web Services (AWS) KMS configuration details and encryption at rest configuration set for the specified project.

Amazon Web Services Key Management Service
object (AzureKeyVault)

Details that define the configuration of Encryption at Rest using Azure Key Vault (AKV).

Azure Key Vault
object (GoogleCloudKMS)

Details that define the configuration of Encryption at Rest using Google Cloud Key Management Service (KMS).

Google Cloud Key Management Service

Responses

Request samples

Content type
application/json
{
  • "awsKms": {
    },
  • "azureKeyVault": {},
  • "googleCloudKms": {
    }
}

Response samples

Content type
application/json
{
  • "awsKms": {
    },
  • "azureKeyVault": {},
  • "googleCloudKms": {
    }
}

Events

Returns events. This collection remains under revision and may change.

Return All Events from One Project

Returns one event for the specified project. Events identify significant database, billing, or security activities or status changes. To use this resource, the requesting API Key must have the Project Read Only role.

This resource remains under revision and may change.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

clusterNames
Array of strings[ items [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$ ]

Human-readable label that identifies the cluster.

Array of Alert Audit Types (object) or Alert Audit Types (object) or API User Event Types (object) or Service Account Event Types (object) or App Services Event Types (object) or Auto Indexing Event Types (object) or Automation Config Event Types (object) or AWS Peer Vpc Audit Types (object) or Azure Peer Network Audit Types (object) or Billing Event Types (object) or Cluster Connection Audit Types (object) or Cluster Event Types (object) or Cps Backup Event Types (object) or Data Explorer Accessed Event Types (object) or CPS Backup Compliance Policy Event Types (object) or Disk Backup Event Types (object) or Encryption Event Types (object) or Export Bucket Audit Types (object) or FTS Index Audit Types (object) or GCP Peer Vpc Audit Types (object) or Group Audit Types (object) or Group Event Types (object) or Group Integration Event Types (object) or Host Event Types (object) or Host Metric Event Types (object) or Index Build Audit Types (object) or NDS Audit Types (object) or NDS DB Check Audit Types (object) or NDS Data Validation Audit Types (object) or NDS Auto Scaling Audit Types (object) or NDS Maintenance Window Audit Types (object) or NDS Serverless Auto Scaling Audit Types (object) or NDS Serverless Instance Audit Types (object) or NDS Auto Scaling Audit Types (object) or NDS Tenant Endpoint Service Deployment Audit Types (object) or NDS x509 User Auth Event Types (object) or Online Archive Event Types (object) or Private Link Audit Types (object) or Proactive Operation Event Types (object) or ReplicaSet Event Types (object) or Search Deployment Audit Types (object) or Serverless Deployment Audit Types (object) or Serverless Event Types (object) or Setup Serverless Audit Types (object) or Streams Event Types (object) or Stream Processor Event Types (object) or Support Case Event Types (object) or Support Event Types (object) or Team Event Types (object) or Tenant Backup Event Types (object) or User Event Types (object) or Version Audit Types (object) or Resource Event Types (object) (EventTypeForNdsGroup)

Category of incident recorded at this moment in time.

IMPORTANT: The complete list of event type values changes frequently.

Array of Alert Audit Types (object) or Alert Audit Types (object) or API User Event Types (object) or Service Account Event Types (object) or App Services Event Types (object) or Auto Indexing Event Types (object) or Automation Config Event Types (object) or AWS Peer Vpc Audit Types (object) or Azure Peer Network Audit Types (object) or Billing Event Types (object) or Cluster Connection Audit Types (object) or Cluster Event Types (object) or Cps Backup Event Types (object) or Data Explorer Accessed Event Types (object) or CPS Backup Compliance Policy Event Types (object) or Disk Backup Event Types (object) or Encryption Event Types (object) or Export Bucket Audit Types (object) or FTS Index Audit Types (object) or GCP Peer Vpc Audit Types (object) or Group Audit Types (object) or Group Event Types (object) or Group Integration Event Types (object) or Host Event Types (object) or Host Metric Event Types (object) or Index Build Audit Types (object) or NDS Audit Types (object) or NDS DB Check Audit Types (object) or NDS Data Validation Audit Types (object) or NDS Auto Scaling Audit Types (object) or NDS Maintenance Window Audit Types (object) or NDS Serverless Auto Scaling Audit Types (object) or NDS Serverless Instance Audit Types (object) or NDS Auto Scaling Audit Types (object) or NDS Tenant Endpoint Service Deployment Audit Types (object) or NDS x509 User Auth Event Types (object) or Online Archive Event Types (object) or Private Link Audit Types (object) or Proactive Operation Event Types (object) or ReplicaSet Event Types (object) or Search Deployment Audit Types (object) or Serverless Deployment Audit Types (object) or Serverless Event Types (object) or Setup Serverless Audit Types (object) or Streams Event Types (object) or Stream Processor Event Types (object) or Support Case Event Types (object) or Support Event Types (object) or Team Event Types (object) or Tenant Backup Event Types (object) or User Event Types (object) or Version Audit Types (object) or Resource Event Types (object) (EventTypeForNdsGroup)

Category of event that you would like to exclude from query results, such as CLUSTER_CREATED

IMPORTANT: Event type names change frequently. Verify that you specify the event type correctly by checking the complete list of event types.

includeRaw
boolean
Default: false

Flag that indicates whether to include the raw document in the output. The raw document contains additional meta information about the event.

maxDate
string <date-time>

Date and time from when MongoDB Cloud stops returning events. This parameter uses the ISO 8601 timestamp format in UTC.

minDate
string <date-time>

Date and time from when MongoDB Cloud starts returning events. This parameter uses the ISO 8601 timestamp format in UTC.

Responses

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Return One Event from One Project

Returns one event for the specified project. Events identify significant database, billing, or security activities or status changes. To use this resource, the requesting API Key must have the Project Read Only role.

This resource remains under revision and may change.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

eventId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the event that you want to return. Use the /events endpoint to retrieve all events to which the authenticated user has access.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

includeRaw
boolean
Default: false

Flag that indicates whether to include the raw document in the output. The raw document contains additional meta information about the event.

Responses

Response samples

Content type
application/json
Example
{
  • "apiKeyId": "32b6e34b3d91647abb20e7b8",
  • "created": "2019-08-24T14:15:22Z",
  • "eventTypeName": "AUTO_INDEXING_ENABLED",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "isGlobalAdmin": false,
  • "links": [],
  • "orgId": "32b6e34b3d91647abb20e7b8",
  • "publicKey": "test.user@mongodb.com",
  • "raw": {
    },
  • "remoteAddress": "216.172.40.186",
  • "userId": "32b6e34b3d91647abb20e7b8",
  • "username": "test.user@mongodb.com"
}

Return All Events from One Organization

Returns all events for the specified organization. Events identify significant database, billing, or security activities or status changes. To use this resource, the requesting API Key must have the Organization Member role.

This resource remains under revision and may change.

Authorizations:
DigestAuthServiceAccounts
path Parameters
orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Array of Alert Audit Types (object) or Alert Audit Types (object) or API User Event Types (object) or Service Account Event Types (object) or Billing Event Types (object) or Federation Settings Event Types (object) or Group Audit Types (object) or Mlab Migration Audit Types (object) or NDS Audit Types (object) or Org Event Types (object) or Partner Event Types (object) or Support Event Types (object) or Team Event Types (object) or User Event Types (object) or Resource Event Types (object) or Atlas Resource Policy Audit Types (object) (EventTypeForOrg)

Category of incident recorded at this moment in time.

IMPORTANT: The complete list of event type values changes frequently.

includeRaw
boolean
Default: false

Flag that indicates whether to include the raw document in the output. The raw document contains additional meta information about the event.

maxDate
string <date-time>

Date and time from when MongoDB Cloud stops returning events. This parameter uses the ISO 8601 timestamp format in UTC.

minDate
string <date-time>
Example: minDate=2021-11-17T23:15:00.06Z

Date and time from when MongoDB Cloud starts returning events. This parameter uses the ISO 8601 timestamp format in UTC.

Responses

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Return One Event from One Organization

Returns one event for the specified organization. Events identify significant database, billing, or security activities or status changes. To use this resource, the requesting API Key must have the Organization Member role.

This resource remains under revision and may change.

Authorizations:
DigestAuthServiceAccounts
path Parameters
orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

eventId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the event that you want to return. Use the /events endpoint to retrieve all events to which the authenticated user has access.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

includeRaw
boolean
Default: false

Flag that indicates whether to include the raw document in the output. The raw document contains additional meta information about the event.

Responses

Response samples

Content type
application/json
Example
{
  • "apiKeyId": "32b6e34b3d91647abb20e7b8",
  • "created": "2019-08-24T14:15:22Z",
  • "eventTypeName": "FEDERATION_SETTINGS_CREATED",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "isGlobalAdmin": false,
  • "links": [],
  • "orgId": "32b6e34b3d91647abb20e7b8",
  • "publicKey": "test.user@mongodb.com",
  • "raw": {
    },
  • "remoteAddress": "216.172.40.186",
  • "userId": "32b6e34b3d91647abb20e7b8",
  • "username": "test.user@mongodb.com"
}

Federated Authentication

Returns, adds, edits, and removes federation-related features such as role mappings and connected organization configurations.

Delete One Federation Settings Instance

Deletes the federation settings instance and all associated data, including identity providers and domains. To use this resource, the requesting API Key must have the Organization Owner role in the last remaining connected organization. Note: requests to this resource will fail if there is more than one connected organization in the federation.

Authorizations:
DigestAuthServiceAccounts
path Parameters
federationSettingsId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 55fa922fb343282757d9554e

Unique 24-hexadecimal digit string that identifies your federation.

Responses

Response samples

Content type
application/json
{
  • "detail": "(This is just an example, the exception may not be related to this endpoint) No provider AWS exists.",
  • "error": 400,
  • "errorCode": "VALIDATION_ERROR",
  • "reason": "Bad Request"
}

Return All Connected Org Configs from One Federation

Returns all connected org configs in the specified federation. To use this resource, the requesting API Key must have the Organization Owner role in one of the connected orgs.

Authorizations:
DigestAuthServiceAccounts
path Parameters
federationSettingsId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 55fa922fb343282757d9554e

Unique 24-hexadecimal digit string that identifies your federation.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

Responses

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Remove One Org Config Connected to One Federation

Removes one connected organization configuration from the specified federation. To use this resource, the requesting API Key must have the Organization Owner role. Note: This request fails if only one connected organization exists in the federation.

Authorizations:
DigestAuthServiceAccounts
path Parameters
federationSettingsId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 55fa922fb343282757d9554e

Unique 24-hexadecimal digit string that identifies your federation.

orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies the connected organization configuration to remove.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Responses

Response samples

Content type
application/json
{ }

Return One Org Config Connected to One Federation

Returns the specified connected org config from the specified federation. To use this resource, the requesting API Key must have the Organization Owner role in the connected org.

Authorizations:
DigestAuthServiceAccounts
path Parameters
federationSettingsId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 55fa922fb343282757d9554e

Unique 24-hexadecimal digit string that identifies your federation.

orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies the connected organization configuration to return.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Responses

Response samples

Content type
application/json
{
  • "dataAccessIdentityProviderIds": [
    ],
  • "domainAllowList": [
    ],
  • "domainRestrictionEnabled": true,
  • "identityProviderId": "stringstringstringst",
  • "orgId": "32b6e34b3d91647abb20e7b8",
  • "postAuthRoleGrants": [
    ],
  • "roleMappings": [
    ],
  • "userConflicts": [
    ]
}

Update One Org Config Connected to One Federation

Updates one connected organization configuration from the specified federation. To use this resource, the requesting API Key must have the Organization Owner role.

Note If the organization configuration has no associated identity provider, you can't use this resource to update role mappings or post authorization role grants.

Note: The domainRestrictionEnabled field defaults to false if not provided in the request.

Note: If the identityProviderId field is not provided, you will disconnect the organization and the identity provider.

Note: Currently connected data access identity providers missing from the dataAccessIdentityProviderIds field will be disconnected.

Authorizations:
DigestAuthServiceAccounts
path Parameters
federationSettingsId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 55fa922fb343282757d9554e

Unique 24-hexadecimal digit string that identifies your federation.

orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies the connected organization configuration to update.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Request Body schema: application/json

The connected organization configuration that you want to update.

dataAccessIdentityProviderIds
Array of strings unique [ items = 24 characters ^([a-f0-9]{24})$ ]

The collection of unique ids representing the identity providers that can be used for data access in this organization.

domainAllowList
Array of strings unique

Approved domains that restrict users who can join the organization based on their email address.

domainRestrictionEnabled
required
boolean

Value that indicates whether domain restriction is enabled for this connected org.

identityProviderId
string = 20 characters ^([a-f0-9]{20})$

Legacy 20-hexadecimal digit string that identifies the UI access identity provider that this connected org config is associated with. This id can be found within the Federation Management Console > Identity Providers tab by clicking the info icon in the IdP ID row of a configured identity provider.

postAuthRoleGrants
Array of strings unique
Items Enum: "ORG_OWNER" "ORG_MEMBER" "ORG_GROUP_CREATOR" "ORG_BILLING_ADMIN" "ORG_BILLING_READ_ONLY" "ORG_READ_ONLY"

Atlas roles that are granted to a user in this organization after authenticating. Roles are a human-readable label that identifies the collection of privileges that MongoDB Cloud grants a specific MongoDB Cloud user. These roles can only be organization specific roles.

Array of objects (Federated Authentication Role Mapping) unique

Role mappings that are configured in this organization.

Array of objects (Federated User)

List that contains the users who have an email address that doesn't match any domain on the allowed list.

Responses

Request samples

Content type
application/json
{
  • "dataAccessIdentityProviderIds": [
    ],
  • "domainAllowList": [
    ],
  • "domainRestrictionEnabled": true,
  • "identityProviderId": "stringstringstringst",
  • "postAuthRoleGrants": [
    ],
  • "roleMappings": [
    ],
  • "userConflicts": [
    ]
}

Response samples

Content type
application/json
{
  • "dataAccessIdentityProviderIds": [
    ],
  • "domainAllowList": [
    ],
  • "domainRestrictionEnabled": true,
  • "identityProviderId": "stringstringstringst",
  • "orgId": "32b6e34b3d91647abb20e7b8",
  • "postAuthRoleGrants": [
    ],
  • "roleMappings": [
    ],
  • "userConflicts": [
    ]
}

Return All Role Mappings from One Organization

Returns all role mappings from the specified organization in the specified federation. To use this resource, the requesting API Key must have the Organization Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
federationSettingsId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 55fa922fb343282757d9554e

Unique 24-hexadecimal digit string that identifies your federation.

orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Responses

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Add One Role Mapping to One Organization

Adds one role mapping to the specified organization in the specified federation. To use this resource, the requesting API Key must have the Organization Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
federationSettingsId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 55fa922fb343282757d9554e

Unique 24-hexadecimal digit string that identifies your federation.

orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Request Body schema: application/json

The role mapping that you want to create.

externalGroupName
required
string [ 1 .. 200 ] characters

Unique human-readable label that identifies the identity provider group to which this role mapping applies.

Array of objects (RoleAssignment) unique

Atlas roles and the unique identifiers of the groups and organizations associated with each role. The array must include at least one element with an Organization role and its respective orgId. Each element in the array can have a value for orgId or groupId, but not both.

Responses

Request samples

Content type
application/json
{
  • "externalGroupName": "string",
  • "roleAssignments": [
    ]
}

Response samples

Content type
application/json
{
  • "externalGroupName": "string",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "roleAssignments": [
    ]
}

Remove One Role Mapping from One Organization

Removes one role mapping in the specified organization from the specified federation. To use this resource, the requesting API Key must have the Organization Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
federationSettingsId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 55fa922fb343282757d9554e

Unique 24-hexadecimal digit string that identifies your federation.

id
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies the role mapping that you want to remove.

orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Responses

Response samples

Content type
application/json
{
  • "detail": "(This is just an example, the exception may not be related to this endpoint) No provider AWS exists.",
  • "error": 400,
  • "errorCode": "VALIDATION_ERROR",
  • "reason": "Bad Request"
}

Return One Role Mapping from One Organization

Returns one role mapping from the specified organization in the specified federation. To use this resource, the requesting API Key must have the Organization Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
federationSettingsId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 55fa922fb343282757d9554e

Unique 24-hexadecimal digit string that identifies your federation.

id
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies the role mapping that you want to return.

orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Responses

Response samples

Content type
application/json
{
  • "externalGroupName": "string",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "roleAssignments": [
    ]
}

Update One Role Mapping in One Organization

Updates one role mapping in the specified organization in the specified federation. To use this resource, the requesting API Key must have the Organization Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
federationSettingsId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 55fa922fb343282757d9554e

Unique 24-hexadecimal digit string that identifies your federation.

id
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies the role mapping that you want to update.

orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Request Body schema: application/json

The role mapping that you want to update.

externalGroupName
required
string [ 1 .. 200 ] characters

Unique human-readable label that identifies the identity provider group to which this role mapping applies.

Array of objects (RoleAssignment) unique

Atlas roles and the unique identifiers of the groups and organizations associated with each role. The array must include at least one element with an Organization role and its respective orgId. Each element in the array can have a value for orgId or groupId, but not both.

Responses

Request samples

Content type
application/json
{
  • "externalGroupName": "string",
  • "roleAssignments": [
    ]
}

Response samples

Content type
application/json
{
  • "externalGroupName": "string",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "roleAssignments": [
    ]
}

Return All Identity Providers in One Federation

Returns all identity providers with the provided protocol and type in the specified federation. If no protocol is specified, only SAML identity providers will be returned. If no idpType is specified, only WORKFORCE identity providers will be returned. To use this resource, the requesting API Key must have the Organization Owner role in one of the connected organizations.

Authorizations:
DigestAuthServiceAccounts
path Parameters
federationSettingsId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 55fa922fb343282757d9554e

Unique 24-hexadecimal digit string that identifies your federation.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

protocol
Array of strings
Items Enum: "SAML" "OIDC"

The protocols of the target identity providers.

idpType
Array of strings
Items Enum: "WORKFORCE" "WORKLOAD"

The types of the target identity providers.

Responses

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Return One SAML Identity Provider

Returns one SAML identity provider from the specified federation. To use this resource, the requesting API Key must have the Organization Owner role in one of the connected organizations.

Authorizations:
DigestAuthServiceAccounts
path Parameters
federationSettingsId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 55fa922fb343282757d9554e

Unique 24-hexadecimal digit string that identifies your federation.

identityProviderId
required
string = 20 characters ^([a-f0-9]{20})$
Example: c2777a9eca931f29fc2f

Legacy 20-hexadecimal digit string that identifies the identity provider. This id can be found within the Federation Management Console > Identity Providers tab by clicking the info icon in the IdP ID row of a configured identity provider.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Responses

Response samples

Content type
application/json
{
  • "acsUrl": "string",
  • "associatedDomains": [
    ],
  • "associatedOrgs": [
    ],
  • "audienceUri": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "displayName": "string",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "idpType": "WORKFORCE",
  • "issuerUri": "string",
  • "oktaIdpId": "stringstringstringst",
  • "pemFileInfo": {
    },
  • "protocol": "SAML",
  • "requestBinding": "HTTP-POST",
  • "responseSignatureAlgorithm": "SHA-1",
  • "slug": "string",
  • "ssoDebugEnabled": true,
  • "ssoUrl": "string",
  • "status": "ACTIVE",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Return the Metadata of One Identity Provider

Returns the metadata of one identity provider in the specified federation. To use this resource, the requesting API Key must have the Organization Owner role in one of the connected organizations.

Authorizations:
DigestAuthServiceAccounts
path Parameters
federationSettingsId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 55fa922fb343282757d9554e

Unique 24-hexadecimal digit string that identifies your federation.

identityProviderId
required
string = 20 characters ^([a-f0-9]{20})$
Example: c2777a9eca931f29fc2f

Legacy 20-hexadecimal digit string that identifies the identity provider. This id can be found within the Federation Management Console > Identity Providers tab by clicking the info icon in the IdP ID row of a configured identity provider.

Responses

Response samples

Content type
application/json
"string"

Return Federation Settings for One Organization

Returns information about the federation settings for the specified organization. To use this resource, the requesting API Key must have the Organization Owner role in the connected org.

Authorizations:
DigestAuthServiceAccounts
path Parameters
orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "federatedDomains": [
    ],
  • "hasRoleMappings": true,
  • "id": "32b6e34b3d91647abb20e7b8",
  • "identityProviderId": "c2777a9eca931f29fc2f",
  • "identityProviderStatus": "ACTIVE"
}

Global Clusters

Returns, adds, and removes Global Cluster managed namespaces and custom zone mappings. Each collection in a Global Cluster is associated with a managed namespace. When you create a managed namespace for a Global Cluster, MongoDB Cloud creates an empty collection for that namespace. Creating a managed namespace doesn't populate a collection with data. Similarly, deleting a managed namespace doesn't delete the associated collection. MongoDB Cloud shards the empty collection using the required location field and a custom shard key. For example, if your custom shard key is city, the compound shard key is location, city. Each Global Cluster is also associated with one or more Global Writes Zones. When a user creates a Global Cluster, MongoDB Cloud automatically maps each location code to the closest geographical zone. Custom zone mappings allow administrators to override these automatic mappings. For example, a use case might require mapping a location code to a geographically distant zone. Administrators can manage custom zone mappings with the APIs below and the Global Cluster Configuration pane when you create or modify your Global Cluster.

Return All Global Clusters Data

Returns all managed namespaces and custom zone mappings for the specified global cluster. Managed namespaces identify collections using the database name, the dot separator, and the collection name. Custom zone mappings matches ISO 3166-2 location codes to zones in your global cluster. To use this resource, the requesting API Key must have the Project Read Only role.

Global Clusters
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies this global cluster.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "customZoneMapping": {
    },
  • "managedNamespaces": [
    ],
  • "selfManagedSharding": true
}

Remove All Custom Zone Mappings from One Global Cluster

Removes all custom zone mappings for the specified global cluster. A custom zone mapping matches one ISO 3166-2 location code to a zone in your global cluster. Removing the custom zone mappings restores the default mapping. By default, MongoDB Cloud maps each location code to the closest geographical zone. To use this resource, the requesting API Key must have the Project Owner role.

Global Clusters
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies this global cluster.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "customZoneMapping": {
    },
  • "managedNamespaces": [
    ],
  • "selfManagedSharding": true
}

Add Custom Zone Mappings to One Global Cluster

Add one or more custom zone mappings to the specified global cluster. A custom zone mapping matches one ISO 3166-2 location code to a zone in your global cluster. By default, MongoDB Cloud maps each location code to the closest geographical zone. To use this resource, the requesting API Key must have the Project Owner role.

Global Clusters
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies this global cluster.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Custom zone mapping to add to the specified global cluster.

Array of objects (Global Cluster Zone)

List that contains comma-separated key value pairs to map zones to geographic regions. These pairs map an ISO 3166-1a2 location code, with an ISO 3166-2 subdivision code when possible, to the human-readable label for the desired custom zone. MongoDB Cloud maps the ISO 3166-1a2 code to the nearest geographical zone by default. Include this parameter to override the default mappings.

This parameter returns an empty object if no custom zones exist.

Responses

Request samples

Content type
application/json
{
  • "customZoneMappings": [
    ]
}

Response samples

Content type
application/json
{
  • "customZoneMapping": {
    },
  • "managedNamespaces": [
    ],
  • "selfManagedSharding": true
}

Remove One Managed Namespace from One Global Cluster

Removes one managed namespace within the specified global cluster. A managed namespace identifies a collection using the database name, the dot separator, and the collection name. Deleting a managed namespace does not remove the associated collection or data. To use this resource, the requesting API Key must have the Project Data Access Admin role.

Global Clusters
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies this global cluster.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

db
string

Human-readable label that identifies the database that contains the collection.

collection
string

Human-readable label that identifies the collection associated with the managed namespace.

Responses

Response samples

Content type
application/json
{
  • "customZoneMapping": {
    },
  • "managedNamespaces": [
    ],
  • "selfManagedSharding": true
}

Create One Managed Namespace in One Global Cluster

Creates one managed namespace within the specified global cluster. A managed namespace identifies a collection using the database name, the dot separator, and the collection name. To use this resource, the requesting API Key must have the Project Data Access Admin role.

Global Clusters
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies this global cluster.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Managed namespace to create within the specified global cluster.

collection
required
string

Human-readable label of the collection to manage for this Global Cluster.

db
required
string

Human-readable label of the database to manage for this Global Cluster.

isCustomShardKeyHashed
boolean
Default: false

Flag that indicates whether someone hashed the custom shard key for the specified collection. If you set this value to false, MongoDB Cloud uses ranged sharding.

Hashed Shard Keys
isShardKeyUnique
boolean
Default: false

Flag that indicates whether someone hashed the custom shard key. If this parameter returns false, this cluster uses ranged sharding.

numInitialChunks
integer <int64> <= 8192

Minimum number of chunks to create initially when sharding an empty collection with a hashed shard key.

Global Cluster Sharding
presplitHashedZones
boolean
Default: false

Flag that indicates whether MongoDB Cloud should create and distribute initial chunks for an empty or non-existing collection. MongoDB Cloud distributes data based on the defined zones and zone ranges for the collection.

Hashed Shard Key

Responses

Request samples

Content type
application/json
{
  • "collection": "string",
  • "db": "string",
  • "isCustomShardKeyHashed": false,
  • "isShardKeyUnique": false,
  • "numInitialChunks": 8192,
  • "presplitHashedZones": false
}

Response samples

Content type
application/json
{
  • "customZoneMapping": {
    },
  • "managedNamespaces": [
    ],
  • "selfManagedSharding": true
}

Remove All Custom Zone Mappings from One Global Cluster

Removes all custom zone mappings for the specified global cluster. A custom zone mapping matches one ISO 3166-2 location code to a zone in your global cluster. Removing the custom zone mappings restores the default mapping. By default, MongoDB Cloud maps each location code to the closest geographical zone. To use this resource, the requesting API Key must have the Project Owner role.

Global Clusters
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies this cluster.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "customZoneMapping": {
    },
  • "managedNamespaces": [
    ],
  • "selfManagedSharding": true
}

Remove One Managed Namespace from One Global Cluster

Removes one managed namespace within the specified global cluster. A managed namespace identifies a collection using the database name, the dot separator, and the collection name. Deleting a managed namespace does not remove the associated collection or data. To use this resource, the requesting API Key must have the Project Data Access Admin role.

Global Clusters
Authorizations:
DigestAuthServiceAccounts
path Parameters
clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies this cluster.

groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

db
string

Human-readable label that identifies the database that contains the collection.

collection
string

Human-readable label that identifies the collection associated with the managed namespace.

Responses

Response samples

Content type
application/json
{
  • "customZoneMapping": {
    },
  • "managedNamespaces": [
    ],
  • "selfManagedSharding": true
}

Invoices

Returns invoices.

Return All Invoices for One Organization

Returns all invoices that MongoDB issued to the specified organization. This list includes all invoices regardless of invoice status. To use this resource, the requesting API Key must have the Organization Billing Viewer, Organization Billing Admin, or Organization Owner role. If you have a cross-organization setup, you can view linked invoices if you have the Organization Billing Admin or Organization Owner role. To compute the total owed amount of the invoices - sum up total owed of each invoice. It could be computed as a sum of owed amount of each payment included into the invoice. To compute payment's owed amount - use formula totalBilledCents * unitPrice + salesTax - startingBalanceCents.

Authorizations:
DigestAuthServiceAccounts
path Parameters
orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

viewLinkedInvoices
boolean
Default: true
Example: viewLinkedInvoices=true

Flag that indicates whether to return linked invoices in the linkedInvoices field.

statusNames
Array of strings unique
Items Enum: "PENDING" "CLOSED" "FORGIVEN" "FAILED" "PAID" "FREE" "PREPAID" "INVOICED"

Statuses of the invoice to be retrieved. Omit to return invoices of all statuses.

fromDate
string <date>
Example: fromDate=2023-01-01

Retrieve the invoices the startDates of which are greater than or equal to the fromDate. If omit, the invoices return will go back to earliest startDate.

toDate
string <date>
Example: toDate=2023-01-01

Retrieve the invoices the endDates of which are smaller than or equal to the toDate. If omit, the invoices return will go further to latest endDate.

sortBy
string
Default: "END_DATE"
Enum: "START_DATE" "END_DATE"

Field used to sort the returned invoices by. Use in combination with orderBy parameter to control the order of the result.

orderBy
string
Default: "desc"
Enum: "desc" "asc"
Example: orderBy=desc

Field used to order the returned invoices by. Use in combination of sortBy parameter to control the order of the result.

Responses

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Return All Pending Invoices for One Organization

Returns all invoices accruing charges for the current billing cycle for the specified organization. To use this resource, the requesting API Key must have the Organization Billing Viewer, Organization Billing Admin, or Organization Owner role. If you have a cross-organization setup, you can view linked invoices if you have the Organization Billing Admin or Organization Owner Role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Return One Organization Invoice

Returns one invoice that MongoDB issued to the specified organization. A unique 24-hexadecimal digit string identifies the invoice. You can choose to receive this invoice in JSON or CSV format. To use this resource, the requesting API Key must have the Organization Billing Viewer, Organization Billing Admin, or Organization Owner role. If you have a cross-organization setup, you can query for a linked invoice if you have the Organization Billing Admin or Organization Owner role. To compute the total owed amount of the invoice - sum up total owed amount of each payment included into the invoice. To compute payment's owed amount - use formula totalBilledCents * unitPrice + salesTax - startingBalanceCents.

Authorizations:
DigestAuthServiceAccounts
path Parameters
orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

invoiceId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the invoice submitted to the specified organization. Charges typically post the next day.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
{
  • "amountBilledCents": 0,
  • "amountPaidCents": 0,
  • "created": "2019-08-24T14:15:22Z",
  • "creditsCents": 0,
  • "endDate": "2019-08-24T14:15:22Z",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "lineItems": [
    ],
  • "linkedInvoices": [
    ],
  • "links": [],
  • "orgId": "32b6e34b3d91647abb20e7b8",
  • "payments": [
    ],
  • "refunds": [
    ],
  • "salesTaxCents": 0,
  • "startDate": "2019-08-24T14:15:22Z",
  • "startingBalanceCents": 0,
  • "statusName": "PENDING",
  • "subtotalCents": 0,
  • "updated": "2019-08-24T14:15:22Z"
}

Return One Organization Invoice as CSV

Returns one invoice that MongoDB issued to the specified organization in CSV format. A unique 24-hexadecimal digit string identifies the invoice. To use this resource, the requesting API Key have at least the Organization Billing Viewer, Organization Billing Admin, or Organization Owner role. If you have a cross-organization setup, you can query for a linked invoice if you have the Organization Billing Admin or Organization Owner Role. To compute the total owed amount of the invoice - sum up total owed amount of each payment included into the invoice. To compute payment's owed amount - use formula totalBilledCents * unitPrice + salesTax - startingBalanceCents.

Authorizations:
DigestAuthServiceAccounts
path Parameters
orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

invoiceId
required
string[0-9a-f]+

Unique 24-hexadecimal digit string that identifies the invoice submitted to the specified organization. Charges typically post the next day.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
text/csv
Invoice Number,666acb8787ba43606905dcae,
Billing Period,"June 1, 2024 - July 1, 2024",
Organization Name,Test 2,
Organization ID,666acb8787ba43606905dcac,

Date,Usage Date,Description,Note,Organization Name,Organization ID,Project,Project ID,SKU,Region,Cluster,Replica Set,Config Server,Application,Unit,Unit Price,Quantity,Discount Percent,Amount

LDAP Configuration

Returns, edits, verifies, and removes LDAP configurations. An LDAP configuration defines settings for MongoDB Cloud to connect to your LDAP server over TLS for user authentication and authorization. Your LDAP server must be visible to the internet or connected to your MongoDB Cloud cluster with VPC Peering. Also, your LDAP server must use TLS. You must have the MongoDB Cloud admin user privilege to use these endpoints. Also, to configure user authentication and authorization with LDAPS, your cluster must run MongoDB 3.6 or higher. Groups for which you have configured LDAPS can't create a cluster using a version of MongoDB 3.6 or lower.

Return the Current LDAP or X.509 Configuration

Returns the current LDAP configuration for the specified project. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "customerX509": {},
  • "ldap": {
    },
  • "links": []
}

Edit the LDAP or X.509 Configuration

Edits the LDAP configuration for the specified project. To use this resource, the requesting API Key must have the Project Owner role.

Updating this configuration triggers a rolling restart of the database.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Updates the LDAP configuration for the specified project.

object (Database User TLS Certificate Settings)

Settings to configure TLS Certificates for database users.

object (LDAP Security Settings)

Lightweight Directory Access Protocol (LDAP) over Transport Layer Security (TLS) configuration details that apply to the specified project.

Responses

Request samples

Content type
application/json
{
  • "customerX509": {
    },
  • "ldap": {
    }
}

Response samples

Content type
application/json
{
  • "customerX509": {},
  • "ldap": {
    },
  • "links": []
}

Remove the Current LDAP User to DN Mapping

Removes the current LDAP Distinguished Name mapping captured in the userToDNMapping document from the LDAP configuration for the specified project. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "customerX509": {},
  • "ldap": {
    },
  • "links": []
}

Verify the LDAP Configuration in One Project

Verifies the LDAP configuration for the specified project. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

The LDAP configuration for the specified project that you want to verify.

authzQueryTemplate
string
Default: "{USER}?memberOf?base"

Lightweight Directory Access Protocol (LDAP) query template that MongoDB Cloud applies to create an LDAP query to return the LDAP groups associated with the authenticated MongoDB user. MongoDB Cloud uses this parameter only for user authorization.

Use the {USER} placeholder in the Uniform Resource Locator (URL) to substitute the authenticated username. The query relates to the host specified with the hostname. Format this query per RFC 4515 and RFC 4516.

bindPassword
required
string

Password that MongoDB Cloud uses to authenticate the bindUsername.

bindUsername
required
string^(?:(?<cn>CN=(?<name>[^,]*)),)?(?:(?<path>(?:...

Full Distinguished Name (DN) of the Lightweight Directory Access Protocol (LDAP) user that MongoDB Cloud uses to connect to the LDAP host. LDAP distinguished names must be formatted according to RFC 2253.

RFC 2253
caCertificate
string

Certificate Authority (CA) certificate that MongoDB Cloud uses to verify the identity of the Lightweight Directory Access Protocol (LDAP) host. MongoDB Cloud allows self-signed certificates. To delete an assigned value, pass an empty string: "caCertificate": "".

hostname
required
string^([0-9]{1,3}\.){3}[0-9]{1,3}|([0-9a-f]{1,4}:)...

Human-readable label that identifies the hostname or Internet Protocol (IP) address of the Lightweight Directory Access Protocol (LDAP) host. This host must have access to the internet or have a Virtual Private Cloud (VPC) peering connection to your cluster.

port
required
integer <int32>
Default: 636

IANA port to which the Lightweight Directory Access Protocol (LDAP) host listens for client connections.

Responses

Request samples

Content type
application/json
{
  • "authzQueryTemplate": "{USER}?memberOf?base",
  • "bindPassword": "string",
  • "bindUsername": "CN=BindUser,CN=Users,DC=myldapserver,DC=mycompany,DC=com",
  • "caCertificate": "string",
  • "hostname": "string",
  • "port": 636
}

Response samples

Content type
application/json
{
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "links": [],
  • "request": {
    },
  • "requestId": "32b6e34b3d91647abb20e7b8",
  • "status": "FAIL",
  • "validations": [
    ]
}

Return the Status of One Verify LDAP Configuration Request

Returns the status of one request to verify one LDAP configuration for the specified project. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

requestId
required
string = 24 characters ^([a-f0-9]{24})$

Unique string that identifies the request to verify an LDAP configuration.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "links": [],
  • "request": {
    },
  • "requestId": "32b6e34b3d91647abb20e7b8",
  • "status": "FAIL",
  • "validations": [
    ]
}

Legacy Backup

Manages Legacy Backup snapshots, restore jobs, schedules and checkpoints.

Return All Legacy Backup Checkpoints Deprecated

Returns all legacy backup checkpoints for one cluster in the specified project. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster that contains the checkpoints that you want to return.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Return One Legacy Backup Checkpoint Deprecated

Returns one legacy backup checkpoint for one cluster in the specified project. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

checkpointId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the checkpoint.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster that contains the checkpoints that you want to return.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "clusterId": "32b6e34b3d91647abb20e7b8",
  • "completed": "2019-08-24T14:15:22Z",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "links": [],
  • "parts": [
    ],
  • "restorable": true,
  • "started": "2019-08-24T14:15:22Z",
  • "timestamp": "2019-08-24T14:15:22Z"
}

Return All Legacy Backup Restore Jobs Deprecated

Returns all legacy backup restore jobs for one cluster in the specified project. To use this resource, the requesting API Key must have the Project Read Only role.

Effective 23 March 2020, all new clusters can use only Cloud Backups. When you upgrade to 4.2, your backup system upgrades to cloud backup if it is currently set to legacy backup. After this upgrade, all your existing legacy backup snapshots remain available. They expire over time in accordance with your retention policy. Your backup policy resets to the default schedule. If you had a custom backup policy in place with legacy backups, you must re-create it with the procedure outlined in the Cloud Backup documentation. If you use the BATCH-ID query parameter, you can retrieve all restore jobs in the specified batch. When creating a restore job for a sharded cluster, MongoDB Cloud creates a separate job for each shard, plus another for the config server. Each of those jobs are part of a batch. However, a batch can't include a restore job for a replica set.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster with the snapshot you want to return.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

batchId
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the batch of restore jobs to return. Timestamp in ISO 8601 date and time format in UTC when creating a restore job for a sharded cluster, Application creates a separate job for each shard, plus another for the config host. Each of these jobs comprise one batch. A restore job for a replica set can't be part of a batch.

Responses

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Create One Legacy Backup Restore Job Deprecated

Restores one legacy backup for one cluster in the specified project. To use this resource, the requesting API Key must have the Project Owner role. Effective 23 March 2020, all new clusters can use only Cloud Backups. When you upgrade to 4.2, your backup system upgrades to cloud backup if it is currently set to legacy backup. After this upgrade, all your existing legacy backup snapshots remain available. They expire over time in accordance with your retention policy. Your backup policy resets to the default schedule. If you had a custom backup policy in place with legacy backups, you must re-create it with the procedure outlined in the Cloud Backup documentation. This endpoint doesn't support creating checkpoint restore jobs for sharded clusters, or creating restore jobs for queryable backup snapshots. If you create an automated restore job by specifying delivery.methodName of AUTOMATED_RESTORE in your request body, MongoDB Cloud removes all existing data on the target cluster prior to the restore.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster with the snapshot you want to return.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Legacy backup to restore to one cluster in the specified project.

checkpointId
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the sharded cluster checkpoint. The checkpoint represents the point in time back to which you want to restore you data. This parameter applies when "delivery.methodName" : "AUTOMATED_RESTORE". Use this parameter with sharded clusters only.

  • If you set checkpointId, you can't set oplogInc, oplogTs, snapshotId, or pointInTimeUTCMillis.
  • If you provide this parameter, this endpoint restores all data up to this checkpoint to the database you specify in the delivery object.
required
object (Restore Snapshot Delivery Metadata)

Method and details that indicate how to deliver the restored snapshot data.

oplogInc
integer <int32> >= 1

Thirty-two-bit incrementing ordinal that represents operations within a given second. When paired with oplogTs, this represents the point in time to which MongoDB Cloud restores your data. This parameter applies when "delivery.methodName" : "AUTOMATED_RESTORE".

  • If you set oplogInc, you must set oplogTs, and can't set checkpointId, snapshotId, or pointInTimeUTCMillis.
  • If you provide this parameter, this endpoint restores all data up to and including this Oplog timestamp to the database you specified in the delivery object.
oplogTs
string^(?:[1-9]\\d{3}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9...

Date and time from which you want to restore this snapshot. This parameter expresses its value in ISO 8601 format in UTC. This represents the first part of an Oplog timestamp. When paired with oplogInc, they represent the last database operation to which you want to restore your data. This parameter applies when "delivery.methodName" : "AUTOMATED_RESTORE". Run a query against local.oplog.rs on your replica set to find the desired timestamp.

  • If you set oplogTs, you must set oplogInc, and you can't set checkpointId, snapshotId, or pointInTimeUTCMillis.
  • If you provide this parameter, this endpoint restores all data up to and including this Oplog timestamp to the database you specified in the delivery object.
pointInTimeUTCMillis
integer <int64> >= 1199145600000

Timestamp from which you want to restore this snapshot. This parameter expresses its value in the number of milliseconds elapsed since the UNIX epoch. This timestamp must fall within the last 24 hours of the current time. This parameter applies when "delivery.methodName" : "AUTOMATED_RESTORE".

  • If you provide this parameter, this endpoint restores all data up to this point in time to the database you specified in the delivery object.
  • If you set pointInTimeUTCMillis, you can't set oplogInc, oplogTs, snapshotId, or checkpointId.
snapshotId
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the snapshot to restore. If you set snapshotId, you can't set oplogInc, oplogTs, pointInTimeUTCMillis, or checkpointId.

Responses

Request samples

Content type
application/json
{
  • "checkpointId": "32b6e34b3d91647abb20e7b8",
  • "delivery": {
    },
  • "oplogInc": 1,
  • "oplogTs": "string",
  • "pointInTimeUTCMillis": 1199145600000,
  • "snapshotId": "32b6e34b3d91647abb20e7b8"
}

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Return One Legacy Backup Restore Job Deprecated

Returns one legacy backup restore job for one cluster in the specified project. To use this resource, the requesting API Key must have the Project Read Only role.

Effective 23 March 2020, all new clusters can use only Cloud Backups. When you upgrade to 4.2, your backup system upgrades to cloud backup if it is currently set to legacy backup. After this upgrade, all your existing legacy backup snapshots remain available. They expire over time in accordance with your retention policy. Your backup policy resets to the default schedule. If you had a custom backup policy in place with legacy backups, you must re-create it with the procedure outlined in the Cloud Backup documentation.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster with the snapshot you want to return.

jobId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the restore job.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "batchId": "32b6e34b3d91647abb20e7b8",
  • "clusterId": "32b6e34b3d91647abb20e7b8",
  • "clusterName": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "delivery": {
    },
  • "encryptionEnabled": true,
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "hashes": [],
  • "id": "32b6e34b3d91647abb20e7b8",
  • "links": [],
  • "masterKeyUUID": "72659f08-8b3c-4913-bb4e-a8a68e036502",
  • "snapshotId": "32b6e34b3d91647abb20e7b8",
  • "statusName": "IN_PROGRESS",
  • "timestamp": {
    }
}

Return One Snapshot Schedule Deprecated

Returns the snapshot schedule for one cluster in the specified project. To use this resource, the requesting API Key must have the Project Read Only role.

Effective 23 March 2020, all new clusters can use only Cloud Backups. When you upgrade to 4.2, your backup system upgrades to cloud backup if it is currently set to legacy backup. After this upgrade, all your existing legacy backup snapshots remain available. They expire over time in accordance with your retention policy. Your backup policy resets to the default schedule. If you had a custom backup policy in place with legacy backups, you must re-create it with the procedure outlined in the Cloud Backup documentation.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster with the snapshot you want to return.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "clusterCheckpointIntervalMin": 15,
  • "clusterId": "32b6e34b3d91647abb20e7b8",
  • "dailySnapshotRetentionDays": 0,
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "links": [],
  • "monthlySnapshotRetentionMonths": 0,
  • "pointInTimeWindowHours": 0,
  • "snapshotIntervalHours": 6,
  • "snapshotRetentionDays": 2,
  • "weeklySnapshotRetentionWeeks": 0
}

Update Snapshot Schedule for One Cluster Deprecated

Updates the snapshot schedule for one cluster in the specified project. To use this resource, the requesting API Key must have the Project Owner role.

Effective 23 March 2020, all new clusters can use only Cloud Backups. When you upgrade to 4.2, your backup system upgrades to cloud backup if it is currently set to legacy backup. After this upgrade, all your existing legacy backup snapshots remain available. They expire over time in accordance with your retention policy. Your backup policy resets to the default schedule. If you had a custom backup policy in place with legacy backups, you must re-create it with the procedure outlined in the Cloud Backup documentation.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster with the snapshot you want to return.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Update the snapshot schedule for one cluster in the specified project.

clusterCheckpointIntervalMin
required
integer <int32>
Enum: 15 30 60

Quantity of time expressed in minutes between successive cluster checkpoints. This parameter applies only to sharded clusters. This number determines the granularity of continuous cloud backups for sharded clusters.

clusterId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the cluster with the snapshot you want to return.

dailySnapshotRetentionDays
required
integer <int32>
Enum: 0 3 4 5 6 7 15 30 60 90 120 180 360

Quantity of time to keep daily snapshots. MongoDB Cloud expresses this value in days. Set this value to 0 to disable daily snapshot retention.

monthlySnapshotRetentionMonths
required
integer <int32>
Enum: 0 1 2 3 4 5 6 7 8 9 10 11 12 13 18 24 36

Number of months that MongoDB Cloud must keep monthly snapshots. Set this value to 0 to disable monthly snapshot retention.

pointInTimeWindowHours
required
integer <int32>

Number of hours before the current time from which MongoDB Cloud can create a Continuous Cloud Backup snapshot.

snapshotIntervalHours
required
integer <int32>
Enum: 6 8 12 24

Number of hours that must elapse before taking another snapshot.

snapshotRetentionDays
required
integer <int32>
Enum: 2 3 4 5

Number of days that MongoDB Cloud must keep recent snapshots.

weeklySnapshotRetentionWeeks
required
integer <int32>
Enum: 0 1 2 3 4 5 6 7 8 12 16 20 24 52

Number of weeks that MongoDB Cloud must keep weekly snapshots. Set this value to 0 to disable weekly snapshot retention.

Responses

Request samples

Content type
application/json
{
  • "clusterCheckpointIntervalMin": 15,
  • "clusterId": "32b6e34b3d91647abb20e7b8",
  • "dailySnapshotRetentionDays": 0,
  • "monthlySnapshotRetentionMonths": 0,
  • "pointInTimeWindowHours": 0,
  • "snapshotIntervalHours": 6,
  • "snapshotRetentionDays": 2,
  • "weeklySnapshotRetentionWeeks": 0
}

Response samples

Content type
application/json
{
  • "clusterCheckpointIntervalMin": 15,
  • "clusterId": "32b6e34b3d91647abb20e7b8",
  • "dailySnapshotRetentionDays": 0,
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "links": [],
  • "monthlySnapshotRetentionMonths": 0,
  • "pointInTimeWindowHours": 0,
  • "snapshotIntervalHours": 6,
  • "snapshotRetentionDays": 2,
  • "weeklySnapshotRetentionWeeks": 0
}

Return All Legacy Backup Snapshots Deprecated

Returns all legacy backup snapshots for one cluster in the specified project. To use this resource, the requesting API Key must have the Project Read Only role. Effective 23 March 2020, all new clusters can use only Cloud Backups. When you upgrade to 4.2, your backup system upgrades to cloud backup if it is currently set to legacy backup. After this upgrade, all your existing legacy backup snapshots remain available. They expire over time in accordance with your retention policy. Your backup policy resets to the default schedule. If you had a custom backup policy in place with legacy backups, you must re-create it with the procedure outlined in the Cloud Backup documentation.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

completed
string
Default: "true"
Enum: "all" "true" "false"

Human-readable label that specifies whether to return only completed, incomplete, or all snapshots. By default, MongoDB Cloud only returns completed snapshots.

Responses

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Remove One Legacy Backup Snapshot Deprecated

Removes one legacy backup snapshot for one cluster in the specified project. To use this resource, the requesting API Key must have the Project Owner role. Effective 23 March 2020, all new clusters can use only Cloud Backups. When you upgrade to 4.2, your backup system upgrades to cloud backup if it is currently set to legacy backup. After this upgrade, all your existing legacy backup snapshots remain available. They expire over time in accordance with your retention policy. Your backup policy resets to the default schedule. If you had a custom backup policy in place with legacy backups, you must re-create it with the procedure outlined in the Cloud Backup documentation.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster.

snapshotId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the desired snapshot.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{ }

Return One Legacy Backup Snapshot Deprecated

Returns one legacy backup snapshot for one cluster in the specified project. To use this resource, the requesting API Key must have the Project Read Only role. Effective 23 March 2020, all new clusters can use only Cloud Backups. When you upgrade to 4.2, your backup system upgrades to cloud backup if it is currently set to legacy backup. After this upgrade, all your existing legacy backup snapshots remain available. They expire over time in accordance with your retention policy. Your backup policy resets to the default schedule. If you had a custom backup policy in place with legacy backups, you must re-create it with the procedure outlined in the Cloud Backup documentation.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster.

snapshotId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the desired snapshot.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "clusterId": "32b6e34b3d91647abb20e7b8",
  • "clusterName": "string",
  • "complete": true,
  • "created": {
    },
  • "doNotDelete": true,
  • "expires": "2019-08-24T14:15:22Z",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "incremental": true,
  • "lastOplogAppliedTimestamp": {
    },
  • "links": [],
  • "parts": [
    ]
}

Change One Legacy Backup Snapshot Expiration Deprecated

Changes the expiration date for one legacy backup snapshot for one cluster in the specified project. To use this resource, the requesting API Key must have the Project Owner role. Effective 23 March 2020, all new clusters can use only Cloud Backups. When you upgrade to 4.2, your backup system upgrades to cloud backup if it is currently set to legacy backup. After this upgrade, all your existing legacy backup snapshots remain available. They expire over time in accordance with your retention policy. Your backup policy resets to the default schedule. If you had a custom backup policy in place with legacy backups, you must re-create it with the procedure outlined in the Cloud Backup documentation.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster.

snapshotId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the desired snapshot.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Changes One Legacy Backup Snapshot Expiration.

doNotDelete
boolean

Flag that indicates whether someone can delete this snapshot. You can't set "doNotDelete" : true and set a timestamp for expires in the same request.

expires
string <date-time>

Date and time when MongoDB Cloud deletes the snapshot. If "doNotDelete" : true, MongoDB Cloud removes any value set for this parameter.

Responses

Request samples

Content type
application/json
{
  • "doNotDelete": true,
  • "expires": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "clusterId": "32b6e34b3d91647abb20e7b8",
  • "clusterName": "string",
  • "complete": true,
  • "created": {
    },
  • "doNotDelete": true,
  • "expires": "2019-08-24T14:15:22Z",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "incremental": true,
  • "lastOplogAppliedTimestamp": {
    },
  • "links": [],
  • "parts": [
    ]
}

Maintenance Windows

Returns, edits, and removes maintenance windows. The maintenance procedure that MongoDB Cloud performs requires at least one replica set election during the maintenance window per replica set. You can defer a scheduled maintenance event for a project up to two times. Deferred maintenance events occur during your preferred maintenance window exactly one week after the previously scheduled date and time.

Reset One Maintenance Window for One Project

Resets the maintenance window for the specified project. To use this resource, the requesting API Key must have the Project Owner role. Urgent maintenance activities such as security patches can't wait for your chosen window. MongoDB Cloud starts those maintenance activities when needed. After you schedule maintenance for your cluster, you can't change your maintenance window until the current maintenance efforts complete. The maintenance procedure that MongoDB Cloud performs requires at least one replica set election during the maintenance window per replica set. Maintenance always begins as close to the scheduled hour as possible, but in-progress cluster updates or unexpected system issues could delay the start time. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Responses

Response samples

Content type
application/json
{
  • "detail": "(This is just an example, the exception may not be related to this endpoint) No provider AWS exists.",
  • "error": 400,
  • "errorCode": "VALIDATION_ERROR",
  • "reason": "Bad Request"
}

Return One Maintenance Window for One Project

Returns the maintenance window for the specified project. MongoDB Cloud starts those maintenance activities when needed. You can't change your maintenance window until the current maintenance efforts complete. The maintenance procedure that MongoDB Cloud performs requires at least one replica set election during the maintenance window per replica set. Maintenance always begins as close to the scheduled hour as possible, but in-progress cluster updates or unexpected system issues could delay the start time. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "autoDeferOnceEnabled": true,
  • "dayOfWeek": 1,
  • "hourOfDay": 23,
  • "numberOfDeferrals": 0,
  • "startASAP": true
}

Update Maintenance Window for One Project

Updates the maintenance window for the specified project. Urgent maintenance activities such as security patches can't wait for your chosen window. MongoDB Cloud starts those maintenance activities when needed. After you schedule maintenance for your cluster, you can't change your maintenance window until the current maintenance efforts complete. The maintenance procedure that MongoDB Cloud performs requires at least one replica set election during the maintenance window per replica set. Maintenance always begins as close to the scheduled hour as possible, but in-progress cluster updates or unexpected system issues could delay the start time. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Request Body schema: application/json

Updates the maintenance window for the specified project.

autoDeferOnceEnabled
boolean

Flag that indicates whether MongoDB Cloud should defer all maintenance windows for one week after you enable them.

dayOfWeek
required
integer <int32> [ 1 .. 7 ]

One-based integer that represents the day of the week that the maintenance window starts.

Value Day of Week
1 Sunday
2 Monday
3 Tuesday
4 Wednesday
5 Thursday
6 Friday
7 Saturday
hourOfDay
integer <int32> [ 0 .. 23 ]

Zero-based integer that represents the hour of the of the day that the maintenance window starts according to a 24-hour clock. Use 0 for midnight and 12 for noon.

startASAP
boolean

Flag that indicates whether MongoDB Cloud starts the maintenance window immediately upon receiving this request. To start the maintenance window immediately for your project, MongoDB Cloud must have maintenance scheduled and you must set a maintenance window. This flag resets to false after MongoDB Cloud completes maintenance.

Responses

Request samples

Content type
application/json
{
  • "autoDeferOnceEnabled": true,
  • "dayOfWeek": 1,
  • "hourOfDay": 23,
  • "startASAP": true
}

Response samples

Content type
application/json
{
  • "detail": "(This is just an example, the exception may not be related to this endpoint) No provider AWS exists.",
  • "error": 400,
  • "errorCode": "VALIDATION_ERROR",
  • "reason": "Bad Request"
}

Toggle Automatic Deferral of Maintenance for One Project

Toggles automatic deferral of the maintenance window for the specified project. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Responses

Response samples

Content type
application/json
{
  • "detail": "(This is just an example, the exception may not be related to this endpoint) No provider AWS exists.",
  • "error": 400,
  • "errorCode": "VALIDATION_ERROR",
  • "reason": "Bad Request"
}

Defer One Maintenance Window for One Project

Defers the maintenance window for the specified project. Urgent maintenance activities such as security patches can't wait for your chosen window. MongoDB Cloud starts those maintenance activities when needed. After you schedule maintenance for your cluster, you can't change your maintenance window until the current maintenance efforts complete. The maintenance procedure that MongoDB Cloud performs requires at least one replica set election during the maintenance window per replica set. Maintenance always begins as close to the scheduled hour as possible, but in-progress cluster updates or unexpected system issues could delay the start time. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Responses

Response samples

Content type
application/json
{
  • "detail": "(This is just an example, the exception may not be related to this endpoint) No provider AWS exists.",
  • "error": 400,
  • "errorCode": "VALIDATION_ERROR",
  • "reason": "Bad Request"
}

MongoDB Cloud Users

Returns, adds, and edits MongoDB Cloud users.

Create One MongoDB Cloud User

Creates one MongoDB Cloud user account. A MongoDB Cloud user account grants access to only the MongoDB Cloud application. To grant database access, create a database user. MongoDB Cloud sends an email to the users you specify, inviting them to join the project. Invited users don't have access to the project until they accept the invitation. Invitations expire after 30 days.

MongoDB Cloud limits MongoDB Cloud user membership to a maximum of 250 MongoDB Cloud users per team. MongoDB Cloud limits MongoDB Cloud user membership to 500 MongoDB Cloud users per project and 500 MongoDB Cloud users per organization, which includes the combined membership of all projects in the organization. MongoDB Cloud raises an error if an operation exceeds these limits. For example, if you have an organization with five projects, and each project has 100 MongoDB Cloud users, and each MongoDB Cloud user belongs to only one project, you can't add any MongoDB Cloud users to this organization without first removing existing MongoDB Cloud users from the organization.

To use this resource, the requesting API Key can have any role.

Authorizations:
DigestAuthServiceAccounts
query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

MongoDB Cloud user account to create.

country
required
string^([A-Z]{2})$

Two alphabet characters that identifies MongoDB Cloud user's geographic location. This parameter uses the ISO 3166-1a2 code format.

firstName
required
string

First or given name that belongs to the MongoDB Cloud user.

lastName
required
string

Last name, family name, or surname that belongs to the MongoDB Cloud user.

mobileNumber
required
string(?:(?:\\+?1\\s*(?:[.-]\\s*)?)?(?:(\\s*([2-9]1...

Mobile phone number that belongs to the MongoDB Cloud user.

password
required
string >= 8 characters

Password applied with the username to log in to MongoDB Cloud. MongoDB Cloud does not return this parameter except in response to creating a new MongoDB Cloud user. Only the MongoDB Cloud user can update their password after it has been set from the MongoDB Cloud console.

Array of objects (Role Assignment)

List of objects that display the MongoDB Cloud user's roles and the corresponding organization or project to which that role applies. A role can apply to one organization or one project but not both.

username
required
string <email>

Email address that represents the username of the MongoDB Cloud user.

Responses

Request samples

Content type
application/json
{
  • "country": "string",
  • "firstName": "string",
  • "lastName": "string",
  • "mobileNumber": "string",
  • "password": "stringst",
  • "roles": [
    ],
  • "username": "user@example.com"
}

Response samples

Content type
application/json
{
  • "country": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "emailAddress": "user@example.com",
  • "firstName": "string",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "lastAuth": "2019-08-24T14:15:22Z",
  • "lastName": "string",
  • "links": [],
  • "mobileNumber": "string",
  • "password": "stringst",
  • "roles": [
    ],
  • "teamIds": [
    ],
  • "username": "user@example.com"
}

Return One MongoDB Cloud User using Their Username

Returns the details for one MongoDB Cloud user account with the specified username. You can't use this endpoint to return information about an API Key. To return information about an API Key, use the Return One Organization API Key endpoint. To use this resource, the requesting API Key can have any role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
userName
required
string^[a-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-z0-9!#$%...

Email address that belongs to the MongoDB Cloud user account. You cannot modify this address after creating the user.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "country": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "emailAddress": "user@example.com",
  • "firstName": "string",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "lastAuth": "2019-08-24T14:15:22Z",
  • "lastName": "string",
  • "links": [],
  • "mobileNumber": "string",
  • "password": "stringst",
  • "roles": [
    ],
  • "teamIds": [
    ],
  • "username": "user@example.com"
}

Return One MongoDB Cloud User using Its ID

Returns the details for one MongoDB Cloud user account with the specified unique identifier for the user. You can't use this endpoint to return information on an API Key. To return information about an API Key, use the Return One Organization API Key endpoint. You can always retrieve your own user account. If you are the owner of a MongoDB Cloud organization or project, you can also retrieve the user profile for any user with membership in that organization or project. To use this resource, the requesting API Key can have any role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
userId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies this user.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "country": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "emailAddress": "user@example.com",
  • "firstName": "string",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "lastAuth": "2019-08-24T14:15:22Z",
  • "lastName": "string",
  • "links": [],
  • "mobileNumber": "string",
  • "password": "stringst",
  • "roles": [
    ],
  • "teamIds": [
    ],
  • "username": "user@example.com"
}

Monitoring and Logs

Returns database deployment monitoring and logging data.

Download Logs for One Cluster Host in One Project

Returns a compressed (.gz) log file that contains a range of log messages for the specified host for the specified project. MongoDB updates process and audit logs from the cluster backend infrastructure every five minutes. Logs are stored in chunks approximately five minutes in length, but this duration may vary. If you poll the API for log files, we recommend polling every five minutes even though consecutive polls could contain some overlapping logs. This feature isn't available for M0 free clusters, M2, M5, or serverless clusters. To use this resource, the requesting API Key must have the Project Data Access Read Only or higher role. The API does not support direct calls with the json response schema. You must request a gzip response schema using an accept header of the format: "Accept: application/vnd.atlas.YYYY-MM-DD+gzip".

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

hostName
required
string^([0-9]{1,3}\.){3}[0-9]{1,3}|([0-9a-f]{1,4}:)...

Human-readable label that identifies the host that stores the log files that you want to download.

logName
required
string
Enum: "mongodb" "mongos" "mongodb-audit-log" "mongos-audit-log"

Human-readable label that identifies the log file that you want to return. To return audit logs, enable Database Auditing for the specified project.

Set up Database Auditing
query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

endDate
integer <int64> >= 1199145600

Specifies the date and time for the ending point of the range of log messages to retrieve, in the number of seconds that have elapsed since the UNIX epoch. This value will default to 24 hours after the start date. If the start date is also unspecified, the value will default to the time of the request.

startDate
integer <int64> >= 1199145600

Specifies the date and time for the starting point of the range of log messages to retrieve, in the number of seconds that have elapsed since the UNIX epoch. This value will default to 24 hours prior to the end date. If the end date is also unspecified, the value will default to 24 hours prior to the time of the request.

Responses

Response samples

Content type
application/json
{
  • "detail": "(This is just an example, the exception may not be related to this endpoint) No provider AWS exists.",
  • "error": 400,
  • "errorCode": "VALIDATION_ERROR",
  • "reason": "Bad Request"
}

Return All Atlas Search Metric Types for One Process

Returns all Atlas Search metric types available for one process in the specified project. You must have the Project Read Only or higher role to view the Atlas Search metric types.

Authorizations:
DigestAuthServiceAccounts
path Parameters
processId
required
string^([0-9]{1,3}\.){3}[0-9]{1,3}|([0-9a-f]{1,4}\:...
Example: my.host.name.com:27017

Combination of hostname and IANA port that serves the MongoDB process. The host must be the hostname, fully qualified domain name (FQDN), or Internet Protocol address (IPv4 or IPv6) of the host that runs the MongoDB process (mongod or mongos). The port must be the IANA port on which the MongoDB process listens for requests.

groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Responses

Response samples

Content type
application/json
{
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "hardwareMetrics": [
    ],
  • "indexMetrics": [
    ],
  • "links": [],
  • "processId": "mongodb.example.com:27017",
  • "statusMetrics": [
    ]
}

Return All Atlas Search Index Metrics for One Namespace

Returns the Atlas Search index metrics within the specified time range for one namespace in the specified process.

Authorizations:
DigestAuthServiceAccounts
path Parameters
processId
required
string^([0-9]{1,3}\.){3}[0-9]{1,3}|([0-9a-f]{1,4}\:...
Example: my.host.name.com:27017

Combination of hostname and IANA port that serves the MongoDB process. The host must be the hostname, fully qualified domain name (FQDN), or Internet Protocol address (IPv4 or IPv6) of the host that runs the MongoDB process (mongod or mongos). The port must be the IANA port on which the MongoDB process listens for requests.

databaseName
required
string
Example: mydb

Human-readable label that identifies the database.

collectionName
required
string
Example: mycoll

Human-readable label that identifies the collection.

groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
granularity
required
string
Example: granularity=PT1M

Duration that specifies the interval at which Atlas reports the metrics. This parameter expresses its value in the ISO 8601 duration format in UTC.

period
string
Example: period=PT10H

Duration over which Atlas reports the metrics. This parameter expresses its value in the ISO 8601 duration format in UTC. Include this parameter when you do not set start and end.

start
string <date-time>

Date and time when MongoDB Cloud begins reporting the metrics. This parameter expresses its value in the ISO 8601 timestamp format in UTC. Include this parameter when you do not set period.

end
string <date-time>

Date and time when MongoDB Cloud stops reporting the metrics. This parameter expresses its value in the ISO 8601 timestamp format in UTC. Include this parameter when you do not set period.

envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

metrics
required
Array of strings <= 10 items unique
Items Enum: "INDEX_SIZE_ON_DISK" "NUMBER_OF_DELETES" "NUMBER_OF_ERROR_QUERIES" "NUMBER_OF_GETMORE_COMMANDS" "NUMBER_OF_INDEX_FIELDS" "NUMBER_OF_INSERTS" "NUMBER_OF_SUCCESS_QUERIES" "NUMBER_OF_UPDATES" "REPLICATION_LAG" "TOTAL_NUMBER_OF_QUERIES"

List that contains the measurements that MongoDB Atlas reports for the associated data series.

Responses

Response samples

Content type
application/json
{
  • "collectionName": "string",
  • "databaseName": "string",
  • "end": "2019-08-24T14:15:22Z",
  • "granularity": "PT1M",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "indexIds": [
    ],
  • "indexStatsMeasurements": [
    ],
  • "links": [],
  • "processId": "mongodb.example.com:27017",
  • "start": "2019-08-24T14:15:22Z"
}

Return Atlas Search Metrics for One Index in One Specified Namespace

Returns the Atlas Search metrics data series within the provided time range for one namespace and index name on the specified process. You must have the Project Read Only or higher role to view the Atlas Search metric types.

Authorizations:
DigestAuthServiceAccounts
path Parameters
processId
required
string^([0-9]{1,3}\.){3}[0-9]{1,3}|([0-9a-f]{1,4}\:...
Example: my.host.name.com:27017

Combination of hostname and IANA port that serves the MongoDB process. The host must be the hostname, fully qualified domain name (FQDN), or Internet Protocol address (IPv4 or IPv6) of the host that runs the MongoDB process (mongod or mongos). The port must be the IANA port on which the MongoDB process listens for requests.

indexName
required
string
Example: myindex

Human-readable label that identifies the index.

databaseName
required
string
Example: mydb

Human-readable label that identifies the database.

collectionName
required
string
Example: mycoll

Human-readable label that identifies the collection.

groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
granularity
required
string
Example: granularity=PT1M

Duration that specifies the interval at which Atlas reports the metrics. This parameter expresses its value in the ISO 8601 duration format in UTC.

period
string
Example: period=PT10H

Duration over which Atlas reports the metrics. This parameter expresses its value in the ISO 8601 duration format in UTC. Include this parameter when you do not set start and end.

start
string <date-time>

Date and time when MongoDB Cloud begins reporting the metrics. This parameter expresses its value in the ISO 8601 timestamp format in UTC. Include this parameter when you do not set period.

end
string <date-time>

Date and time when MongoDB Cloud stops reporting the metrics. This parameter expresses its value in the ISO 8601 timestamp format in UTC. Include this parameter when you do not set period.

envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

metrics
required
Array of strings <= 10 items unique
Items Enum: "INDEX_SIZE_ON_DISK" "NUMBER_OF_DELETES" "NUMBER_OF_ERROR_QUERIES" "NUMBER_OF_GETMORE_COMMANDS" "NUMBER_OF_INDEX_FIELDS" "NUMBER_OF_INSERTS" "NUMBER_OF_SUCCESS_QUERIES" "NUMBER_OF_UPDATES" "REPLICATION_LAG" "TOTAL_NUMBER_OF_QUERIES"

List that contains the measurements that MongoDB Atlas reports for the associated data series.

Responses

Response samples

Content type
application/json
{
  • "collectionName": "string",
  • "databaseName": "string",
  • "end": "2019-08-24T14:15:22Z",
  • "granularity": "PT1M",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "indexIds": [
    ],
  • "indexStatsMeasurements": [
    ],
  • "links": [],
  • "processId": "mongodb.example.com:27017",
  • "start": "2019-08-24T14:15:22Z"
}

Return Atlas Search Hardware and Status Metrics

Returns the Atlas Search hardware and status data series within the provided time range for one process in the specified project. You must have the Project Read Only or higher role to view the Atlas Search metric types.

Authorizations:
DigestAuthServiceAccounts
path Parameters
processId
required
string^([0-9]{1,3}\.){3}[0-9]{1,3}|([0-9a-f]{1,4}\:...
Example: my.host.name.com:27017

Combination of hostname and IANA port that serves the MongoDB process. The host must be the hostname, fully qualified domain name (FQDN), or Internet Protocol address (IPv4 or IPv6) of the host that runs the MongoDB process (mongod or mongos). The port must be the IANA port on which the MongoDB process listens for requests.

groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
granularity
required
string
Example: granularity=PT1M

Duration that specifies the interval at which Atlas reports the metrics. This parameter expresses its value in the ISO 8601 duration format in UTC.

period
string
Example: period=PT10H

Duration over which Atlas reports the metrics. This parameter expresses its value in the ISO 8601 duration format in UTC. Include this parameter when you do not set start and end.

start
string <date-time>

Date and time when MongoDB Cloud begins reporting the metrics. This parameter expresses its value in the ISO 8601 timestamp format in UTC. Include this parameter when you do not set period.

end
string <date-time>

Date and time when MongoDB Cloud stops reporting the metrics. This parameter expresses its value in the ISO 8601 timestamp format in UTC. Include this parameter when you do not set period.

envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

metrics
required
Array of strings <= 10 items unique
Items Enum: "FTS_DISK_USAGE" "FTS_PROCESS_CPU_KERNEL" "FTS_PROCESS_CPU_USER" "FTS_PROCESS_NORMALIZED_CPU_KERNEL" "FTS_PROCESS_NORMALIZED_CPU_USER" "FTS_PROCESS_RESIDENT_MEMORY" "FTS_PROCESS_SHARED_MEMORY" "FTS_PROCESS_VIRTUAL_MEMORY" "JVM_CURRENT_MEMORY" "JVM_MAX_MEMORY" "PAGE_FAULTS"

List that contains the metrics that you want MongoDB Atlas to report for the associated data series. If you don't set this parameter, this resource returns all hardware and status metrics for the associated data series.

Responses

Response samples

Content type
application/json
{
  • "end": "2019-08-24T14:15:22Z",
  • "granularity": "PT1M",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "hardwareMeasurements": [
    ],
  • "links": [],
  • "processId": "mongodb.example.com:27017",
  • "start": "2019-08-24T14:15:22Z",
  • "statusMeasurements": [
    ]
}

Return All MongoDB Processes in One Project

Returns details of all processes for the specified project. A MongoDB process can be either a mongod or mongos. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Return One MongoDB Process by ID

Returns the processes for the specified host for the specified project. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

processId
required
string^([0-9]{1,3}\.){3}[0-9]{1,3}|([0-9a-f]{1,4}\:...
Example: mongodb.example.com:27017

Combination of hostname and Internet Assigned Numbers Authority (IANA) port that serves the MongoDB process. The host must be the hostname, fully qualified domain name (FQDN), or Internet Protocol address (IPv4 or IPv6) of the host that runs the MongoDB process (mongod or mongos). The port must be the IANA port on which the MongoDB process listens for requests.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "created": "2019-08-24T14:15:22Z",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "hostname": "string",
  • "id": "string",
  • "lastPing": "2019-08-24T14:15:22Z",
  • "links": [],
  • "port": 0,
  • "replicaSetName": "string",
  • "shardName": "string",
  • "typeName": "REPLICA_PRIMARY",
  • "userAlias": "string",
  • "version": "string"
}

Return Available Databases for One MongoDB Process

Returns the list of databases running on the specified host for the specified project. M0 free clusters, M2, M5, and serverless clusters have some operational limits. The MongoDB Cloud process must be a mongod. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

processId
required
string^([0-9]{1,3}\.){3}[0-9]{1,3}|([0-9a-f]{1,4}\:...
Example: mongodb.example.com:27017

Combination of hostname and Internet Assigned Numbers Authority (IANA) port that serves the MongoDB process. The host must be the hostname, fully qualified domain name (FQDN), or Internet Protocol address (IPv4 or IPv6) of the host that runs the MongoDB process (mongod). The port must be the IANA port on which the MongoDB process listens for requests.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{}

Return One Database for a MongoDB Process

Returns one database running on the specified host for the specified project. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

databaseName
required
string

Human-readable label that identifies the database that the specified MongoDB process serves.

processId
required
string^([0-9]{1,3}\.){3}[0-9]{1,3}|([0-9a-f]{1,4}\:...
Example: mongodb.example.com:27017

Combination of hostname and Internet Assigned Numbers Authority (IANA) port that serves the MongoDB process. The host must be the hostname, fully qualified domain name (FQDN), or Internet Protocol address (IPv4 or IPv6) of the host that runs the MongoDB process (mongod or mongos). The port must be the IANA port on which the MongoDB process listens for requests.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{}

Return Measurements of One Database for One MongoDB Process

Returns the measurements of one database for the specified host for the specified project. Returns the database's on-disk storage space based on the MongoDB dbStats command output. To calculate some metric series, Atlas takes the rate between every two adjacent points. For these metric series, the first data point has a null value because Atlas can't calculate a rate for the first data point given the query time range. Atlas retrieves database metrics every 20 minutes but reduces frequency when necessary to optimize database performance. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

databaseName
required
string

Human-readable label that identifies the database that the specified MongoDB process serves.

processId
required
string^([0-9]{1,3}\.){3}[0-9]{1,3}|([0-9a-f]{1,4}\:...
Example: mongodb.example.com:27017

Combination of hostname and Internet Assigned Numbers Authority (IANA) port that serves the MongoDB process. The host must be the hostname, fully qualified domain name (FQDN), or Internet Protocol address (IPv4 or IPv6) of the host that runs the MongoDB process (mongod or mongos). The port must be the IANA port on which the MongoDB process listens for requests.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

m
Array of strings [ 1 .. 10 ] items unique
Items Enum: "DATABASE_AVERAGE_OBJECT_SIZE" "DATABASE_COLLECTION_COUNT" "DATABASE_DATA_SIZE" "DATABASE_STORAGE_SIZE" "DATABASE_INDEX_SIZE" "DATABASE_INDEX_COUNT" "DATABASE_EXTENT_COUNT" "DATABASE_OBJECT_COUNT" "DATABASE_VIEW_COUNT"

One or more types of measurement to request for this MongoDB process. If omitted, the resource returns all measurements. To specify multiple values for m, repeat the m parameter for each value. Specify measurements that apply to the specified host. MongoDB Cloud returns an error if you specified any invalid measurements.

granularity
required
string
Example: granularity=PT1M

Duration that specifies the interval at which Atlas reports the metrics. This parameter expresses its value in the ISO 8601 duration format in UTC.

period
string
Example: period=PT10H

Duration over which Atlas reports the metrics. This parameter expresses its value in the ISO 8601 duration format in UTC. Include this parameter when you do not set start and end.

start
string <date-time>

Date and time when MongoDB Cloud begins reporting the metrics. This parameter expresses its value in the ISO 8601 timestamp format in UTC. Include this parameter when you do not set period.

end
string <date-time>

Date and time when MongoDB Cloud stops reporting the metrics. This parameter expresses its value in the ISO 8601 timestamp format in UTC. Include this parameter when you do not set period.

Responses

Response samples

Content type
application/json
{
  • "databaseName": "string",
  • "end": "2019-08-24T14:15:22Z",
  • "granularity": "PT1M",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "hostId": "mongodb.example.com:27017",
  • "links": [],
  • "measurements": [
    ],
  • "partitionName": "string",
  • "processId": "mongodb.example.com:27017",
  • "start": "2019-08-24T14:15:22Z"
}

Return Available Disks for One MongoDB Process

Returns the list of disks or partitions for the specified host for the specified project. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

processId
required
string^([0-9]{1,3}\.){3}[0-9]{1,3}|([0-9a-f]{1,4}\:...
Example: mongodb.example.com:27017

Combination of hostname and Internet Assigned Numbers Authority (IANA) port that serves the MongoDB process. The host must be the hostname, fully qualified domain name (FQDN), or Internet Protocol address (IPv4 or IPv6) of the host that runs the MongoDB process (mongod or mongos). The port must be the IANA port on which the MongoDB process listens for requests.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{}

Return Measurements of One Disk

Returns measurement details for one disk or partition for the specified host for the specified project. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
partitionName
required
string

Human-readable label of the disk or partition to which the measurements apply.

groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

processId
required
string^([0-9]{1,3}\.){3}[0-9]{1,3}|([0-9a-f]{1,4}\:...
Example: mongodb.example.com:27017

Combination of hostname and Internet Assigned Numbers Authority (IANA) port that serves the MongoDB process. The host must be the hostname, fully qualified domain name (FQDN), or Internet Protocol address (IPv4 or IPv6) of the host that runs the MongoDB process (mongod or mongos). The port must be the IANA port on which the MongoDB process listens for requests.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Responses

Response samples

Content type
application/json
{}

Return Measurements of One Disk for One MongoDB Process

Returns the measurements of one disk or partition for the specified host for the specified project. Returned value can be one of the following:

  • Throughput of I/O operations for the disk partition used for the MongoDB process
  • Percentage of time during which requests the partition issued and serviced
  • Latency per operation type of the disk partition used for the MongoDB process
  • Amount of free and used disk space on the disk partition used for the MongoDB process

To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

partitionName
required
string

Human-readable label of the disk or partition to which the measurements apply.

processId
required
string^([0-9]{1,3}\.){3}[0-9]{1,3}|([0-9a-f]{1,4}\:...
Example: mongodb.example.com:27017

Combination of hostname and Internet Assigned Numbers Authority (IANA) port that serves the MongoDB process. The host must be the hostname, fully qualified domain name (FQDN), or Internet Protocol address (IPv4 or IPv6) of the host that runs the MongoDB process (mongod or mongos). The port must be the IANA port on which the MongoDB process listens for requests.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

m
Array of strings [ 1 .. 10 ] items unique
Items Enum: "DISK_PARTITION_IOPS_READ" "MAX_DISK_PARTITION_IOPS_READ" "DISK_PARTITION_IOPS_WRITE" "MAX_DISK_PARTITION_IOPS_WRITE" "DISK_PARTITION_IOPS_TOTAL" "MAX_DISK_PARTITION_IOPS_TOTAL" "DISK_PARTITION_LATENCY_READ" "MAX_DISK_PARTITION_LATENCY_READ" "DISK_PARTITION_LATENCY_WRITE" "MAX_DISK_PARTITION_LATENCY_WRITE" "DISK_PARTITION_SPACE_FREE" "MAX_DISK_PARTITION_SPACE_FREE" "DISK_PARTITION_SPACE_USED" "MAX_DISK_PARTITION_SPACE_USED" "DISK_PARTITION_SPACE_PERCENT_FREE" "MAX_DISK_PARTITION_SPACE_PERCENT_FREE" "DISK_PARTITION_SPACE_PERCENT_USED" "MAX_DISK_PARTITION_SPACE_PERCENT_USED" "DISK_PARTITION_THROUGHPUT_READ" "DISK_PARTITION_THROUGHPUT_WRITE" "DISK_QUEUE_DEPTH"

One or more types of measurement to request for this MongoDB process. If omitted, the resource returns all measurements. To specify multiple values for m, repeat the m parameter for each value. Specify measurements that apply to the specified host. MongoDB Cloud returns an error if you specified any invalid measurements.

period
string
Example: period=PT10H

Duration over which Atlas reports the metrics. This parameter expresses its value in the ISO 8601 duration format in UTC. Include this parameter when you do not set start and end.

granularity
required
string
Example: granularity=PT1M

Duration that specifies the interval at which Atlas reports the metrics. This parameter expresses its value in the ISO 8601 duration format in UTC.

start
string <date-time>

Date and time when MongoDB Cloud begins reporting the metrics. This parameter expresses its value in the ISO 8601 timestamp format in UTC. Include this parameter when you do not set period.

end
string <date-time>

Date and time when MongoDB Cloud stops reporting the metrics. This parameter expresses its value in the ISO 8601 timestamp format in UTC. Include this parameter when you do not set period.

Responses

Response samples

Content type
application/json
{
  • "databaseName": "string",
  • "end": "2019-08-24T14:15:22Z",
  • "granularity": "PT1M",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "hostId": "mongodb.example.com:27017",
  • "links": [],
  • "measurements": [
    ],
  • "partitionName": "string",
  • "processId": "mongodb.example.com:27017",
  • "start": "2019-08-24T14:15:22Z"
}

Return Measurements for One MongoDB Process

Returns disk, partition, or host measurements per process for the specified host for the specified project. Returned value can be one of the following:

  • Throughput of I/O operations for the disk partition used for the MongoDB process
  • Percentage of time during which requests the partition issued and serviced
  • Latency per operation type of the disk partition used for the MongoDB process
  • Amount of free and used disk space on the disk partition used for the MongoDB process
  • Measurements for the host, such as CPU usage or number of I/O operations

To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

processId
required
string^([0-9]{1,3}\.){3}[0-9]{1,3}|([0-9a-f]{1,4}\:...
Example: mongodb.example.com:27017

Combination of hostname and Internet Assigned Numbers Authority (IANA) port that serves the MongoDB process. The host must be the hostname, fully qualified domain name (FQDN), or Internet Protocol address (IPv4 or IPv6) of the host that runs the MongoDB process (mongod or mongos). The port must be the IANA port on which the MongoDB process listens for requests.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

m
Array of strings [ 1 .. 10 ] items unique
Items Enum: "ASSERT_MSG" "ASSERT_REGULAR" "ASSERT_USER" "ASSERT_WARNING" "BACKGROUND_FLUSH_AVG" "CACHE_BYTES_READ_INTO" "CACHE_BYTES_WRITTEN_FROM" "CACHE_DIRTY_BYTES" "CACHE_USED_BYTES" "CACHE_FILL_RATIO" "DIRTY_FILL_RATIO" "COMPUTED_MEMORY" "CONNECTIONS" "CURSORS_TOTAL_OPEN" "CURSORS_TOTAL_TIMED_OUT" "DB_DATA_SIZE_TOTAL" "DB_STORAGE_TOTAL" "DOCUMENT_METRICS_DELETED" "DOCUMENT_METRICS_INSERTED" "DOCUMENT_METRICS_RETURNED" "DOCUMENT_METRICS_UPDATED" "EXTRA_INFO_PAGE_FAULTS" "FTS_DISK_UTILIZATION" "FTS_MEMORY_MAPPED" "FTS_MEMORY_RESIDENT" "FTS_MEMORY_VIRTUAL" "FTS_PROCESS_CPU_KERNEL" "FTS_PROCESS_CPU_USER" "FTS_PROCESS_NORMALIZED_CPU_KERNEL" "FTS_PROCESS_NORMALIZED_CPU_USER" "GLOBAL_ACCESSES_NOT_IN_MEMORY" "GLOBAL_LOCK_CURRENT_QUEUE_READERS" "GLOBAL_LOCK_CURRENT_QUEUE_TOTAL" "GLOBAL_LOCK_CURRENT_QUEUE_WRITERS" "GLOBAL_PAGE_FAULT_EXCEPTIONS_THROWN" "INDEX_COUNTERS_BTREE_ACCESSES" "INDEX_COUNTERS_BTREE_HITS" "INDEX_COUNTERS_BTREE_MISS_RATIO" "INDEX_COUNTERS_BTREE_MISSES" "JOURNALING_COMMITS_IN_WRITE_LOCK" "JOURNALING_MB" "JOURNALING_WRITE_DATA_FILES_MB" "MAX_PROCESS_CPU_CHILDREN_KERNEL" "MAX_PROCESS_CPU_CHILDREN_USER" "MAX_PROCESS_CPU_KERNEL" "MAX_PROCESS_CPU_USER" "MAX_PROCESS_NORMALIZED_CPU_CHILDREN_KERNEL" "MAX_PROCESS_NORMALIZED_CPU_CHILDREN_USER" "MAX_PROCESS_NORMALIZED_CPU_KERNEL" "MAX_PROCESS_NORMALIZED_CPU_USER" "MAX_SWAP_USAGE_FREE" "MAX_SWAP_USAGE_USED " "MAX_SYSTEM_CPU_GUEST" "MAX_SYSTEM_CPU_IOWAIT" "MAX_SYSTEM_CPU_IRQ" "MAX_SYSTEM_CPU_KERNEL" "MAX_SYSTEM_CPU_SOFTIRQ" "MAX_SYSTEM_CPU_STEAL" "MAX_SYSTEM_CPU_USER" "MAX_SYSTEM_MEMORY_AVAILABLE" "MAX_SYSTEM_MEMORY_FREE" "MAX_SYSTEM_MEMORY_USED" "MAX_SYSTEM_NETWORK_IN" "MAX_SYSTEM_NETWORK_OUT" "MAX_SYSTEM_NORMALIZED_CPU_GUEST" "MAX_SYSTEM_NORMALIZED_CPU_IOWAIT" "MAX_SYSTEM_NORMALIZED_CPU_IRQ" "MAX_SYSTEM_NORMALIZED_CPU_KERNEL" "MAX_SYSTEM_NORMALIZED_CPU_NICE" "MAX_SYSTEM_NORMALIZED_CPU_SOFTIRQ" "MAX_SYSTEM_NORMALIZED_CPU_STEAL" "MAX_SYSTEM_NORMALIZED_CPU_USER" "MEMORY_MAPPED" "MEMORY_RESIDENT" "MEMORY_VIRTUAL" "NETWORK_BYTES_IN" "NETWORK_BYTES_OUT" "NETWORK_NUM_REQUESTS" "OP_EXECUTION_TIME_COMMANDS" "OP_EXECUTION_TIME_READS" "OP_EXECUTION_TIME_WRITES" "OPCOUNTER_CMD" "OPCOUNTER_DELETE" "OPCOUNTER_TTL_DELETED" "OPCOUNTER_GETMORE" "OPCOUNTER_INSERT" "OPCOUNTER_QUERY" "OPCOUNTER_REPL_CMD" "OPCOUNTER_REPL_DELETE" "OPCOUNTER_REPL_INSERT" "OPCOUNTER_REPL_UPDATE" "OPCOUNTER_UPDATE" "OPERATIONS_SCAN_AND_ORDER" "OPERATIONS_QUERIES_KILLED" "OPLOG_MASTER_LAG_TIME_DIFF" "OPLOG_MASTER_TIME" "OPLOG_RATE_GB_PER_HOUR" "OPLOG_SLAVE_LAG_MASTER_TIME" "OPLOG_REPLICATION_LAG" "PROCESS_CPU_CHILDREN_KERNEL" "PROCESS_CPU_CHILDREN_USER" "PROCESS_CPU_KERNEL" "PROCESS_CPU_USER" "PROCESS_NORMALIZED_CPU_CHILDREN_KERNEL" "PROCESS_NORMALIZED_CPU_CHILDREN_USER" "PROCESS_NORMALIZED_CPU_KERNEL" "PROCESS_NORMALIZED_CPU_USER" "QUERY_EXECUTOR_SCANNED" "QUERY_EXECUTOR_SCANNED_OBJECTS" "QUERY_TARGETING_SCANNED_OBJECTS_PER_RETURNED" "QUERY_TARGETING_SCANNED_PER_RETURNED" "RESTARTS_IN_LAST_HOUR" "SWAP_USAGE_FREE" "SWAP_USAGE_USED" "SYSTEM_CPU_GUEST" "SYSTEM_CPU_IOWAIT" "SYSTEM_CPU_IRQ" "SYSTEM_CPU_KERNEL" "SYSTEM_CPU_NICE" "SYSTEM_CPU_SOFTIRQ" "SYSTEM_CPU_STEAL" "SYSTEM_CPU_USER" "SYSTEM_MEMORY_AVAILABLE" "SYSTEM_MEMORY_FREE" "SYSTEM_MEMORY_USED" "SYSTEM_NETWORK_IN" "SYSTEM_NETWORK_OUT" "SYSTEM_NORMALIZED_CPU_GUEST" "SYSTEM_NORMALIZED_CPU_IOWAIT" "SYSTEM_NORMALIZED_CPU_IRQ" "SYSTEM_NORMALIZED_CPU_KERNEL" "SYSTEM_NORMALIZED_CPU_NICE" "SYSTEM_NORMALIZED_CPU_SOFTIRQ" "SYSTEM_NORMALIZED_CPU_STEAL" "SYSTEM_NORMALIZED_CPU_USER" "TICKETS_AVAILABLE_READS" "TICKETS_AVAILABLE_WRITE" "OPERATION_THROTTLING_REJECTED_OPERATIONS"

One or more types of measurement to request for this MongoDB process. If omitted, the resource returns all measurements. To specify multiple values for m, repeat the m parameter for each value. Specify measurements that apply to the specified host. MongoDB Cloud returns an error if you specified any invalid measurements.

period
string
Example: period=PT10H

Duration over which Atlas reports the metrics. This parameter expresses its value in the ISO 8601 duration format in UTC. Include this parameter when you do not set start and end.

granularity
required
string
Example: granularity=PT1M

Duration that specifies the interval at which Atlas reports the metrics. This parameter expresses its value in the ISO 8601 duration format in UTC.

start
string <date-time>

Date and time when MongoDB Cloud begins reporting the metrics. This parameter expresses its value in the ISO 8601 timestamp format in UTC. Include this parameter when you do not set period.

end
string <date-time>

Date and time when MongoDB Cloud stops reporting the metrics. This parameter expresses its value in the ISO 8601 timestamp format in UTC. Include this parameter when you do not set period.

Responses

Response samples

Content type
application/json
{
  • "databaseName": "string",
  • "end": "2019-08-24T14:15:22Z",
  • "granularity": "PT1M",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "hostId": "mongodb.example.com:27017",
  • "links": [],
  • "measurements": [
    ],
  • "partitionName": "string",
  • "processId": "mongodb.example.com:27017",
  • "start": "2019-08-24T14:15:22Z"
}

Download Logs for One Cluster Host in One Project

Returns a compressed (.gz) log file that contains a range of log messages for the specified host for the specified project. MongoDB updates process and audit logs from the cluster backend infrastructure every five minutes. Logs are stored in chunks approximately five minutes in length, but this duration may vary. If you poll the API for log files, we recommend polling every five minutes even though consecutive polls could contain some overlapping logs. This feature isn't available for M0 free clusters, M2, M5, or serverless clusters. To use this resource, the requesting API Key must have the Project Data Access Read Only or higher role. The API does not support direct calls with the json response schema. You must request a gzip response schema using an accept header of the format: "Accept: application/vnd.atlas.YYYY-MM-DD+gzip".

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

hostName
required
string^([0-9]{1,3}\.){3}[0-9]{1,3}|([0-9a-f]{1,4}:)...

Human-readable label that identifies the host that stores the log files that you want to download.

logName
required
string
Enum: "mongodb" "mongos" "mongodb-audit-log" "mongos-audit-log"

Human-readable label that identifies the log file that you want to return. To return audit logs, enable Database Auditing for the specified project.

Set up Database Auditing
query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

endDate
integer <int64> >= 1199145600

Specifies the date and time for the ending point of the range of log messages to retrieve, in the number of seconds that have elapsed since the UNIX epoch. This value will default to 24 hours after the start date. If the start date is also unspecified, the value will default to the time of the request.

startDate
integer <int64> >= 1199145600

Specifies the date and time for the starting point of the range of log messages to retrieve, in the number of seconds that have elapsed since the UNIX epoch. This value will default to 24 hours prior to the end date. If the end date is also unspecified, the value will default to 24 hours prior to the time of the request.

Responses

Response samples

Content type
application/json
{
  • "detail": "(This is just an example, the exception may not be related to this endpoint) No provider AWS exists.",
  • "error": 400,
  • "errorCode": "VALIDATION_ERROR",
  • "reason": "Bad Request"
}

Multi-Cloud Clusters

Returns, adds, edits, or removes multi-cloud clusters. Changes to cluster configurations can affect costs.

The total number of nodes in clusters spanning across regions has a specific constraint on a per-project basis. MongoDB Cloud limits the total number of nodes in other regions in one project to a total of 40. This total excludes Google Cloud regions communicating with each other, shared-tier clusters, or serverless clusters. The total number of nodes between any two regions must meet this constraint. For example, if a project has nodes in clusters spread across three regions: 30 nodes in Region A, 10 nodes in Region B, and 5 nodes in Region C, you can add only 5 more nodes to Region C because if you exclude Region C, Region A + Region B = 40. If you exclude Region B, Region A + Region C = 35, <= 40. If you exclude Region A, Region B + Region C = 15, <= 40. Each combination of regions with the added 5 nodes still meets the per-project constraint. Region A + B = 40. Region A + C = 40. Region B + C = 20. You can't create a multi-region cluster in a project if it has one or more clusters spanning 40 or more nodes in other regions. Each project supports up to 25 database deployments.

If your MongoDB Cloud project contains a custom role that uses actions introduced in a specific MongoDB version, you must delete that role before you create clusters with an earlier MongoDB version. MongoDB Cloud clusters created after July 2020 use TLS version 1.2 by default. When you create a cluster, MongoDB Cloud creates a network container in the project for the cloud provider to which you deploy the cluster if one doesn't already exist.

Return All Clusters in One Project

Returns the details for all clusters in the specific project to which you have access. Clusters contain a group of hosts that maintain the same data set. The response includes multi-cloud clusters. To use this resource, the requesting API Key must have the Project Read Only role. This feature is not available for serverless clusters.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

includeDeletedWithRetainedBackups
boolean
Default: false

Flag that indicates whether to return Clusters with retain backups.

Responses

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Create One Cluster from One Project

Creates one cluster in the specified project. Clusters contain a group of hosts that maintain the same data set. This resource can create multi-cloud clusters. Each project supports up to 25 database deployments. To use this resource, the requesting API Key must have the Project Owner role. This feature is not available for serverless clusters.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Cluster to create in the specific project.

acceptDataRisksAndForceReplicaSetReconfig
string <date-time>

If reconfiguration is necessary to regain a primary due to a regional outage, submit this field alongside your topology reconfiguration to request a new regional outage resistant topology. Forced reconfigurations during an outage of the majority of electable nodes carry a risk of data loss if replicated writes (even majority committed writes) have not been replicated to the new primary node. MongoDB Atlas docs contain more information. To proceed with an operation which carries that risk, set acceptDataRisksAndForceReplicaSetReconfig to the current date.

Reconfiguring a Replica Set during a regional outage
backupEnabled
boolean
Default: false

Flag that indicates whether the cluster can perform backups. If set to true, the cluster can perform backups. You must set this value to true for NVMe clusters. Backup uses Cloud Backups for dedicated clusters and Shared Cluster Backups for tenant clusters. If set to false, the cluster doesn't use backups.

object (MongoDB Connector for Business Intelligence Settings)

Settings needed to configure the MongoDB Connector for Business Intelligence for this cluster.

MongoDB Connector for Business Intelligence
clusterType
string
Enum: "REPLICASET" "SHARDED" "GEOSHARDED"

Configuration of nodes that comprise the cluster.

configServerManagementMode
string
Default: "ATLAS_MANAGED"
Enum: "ATLAS_MANAGED" "FIXED_TO_DEDICATED"

Config Server Management Mode for creating or updating a sharded cluster.

When configured as ATLAS_MANAGED, atlas may automatically switch the cluster's config server type for optimal performance and savings.

When configured as FIXED_TO_DEDICATED, the cluster will always use a dedicated config server.

MongoDB Sharded Cluster Config Servers
diskSizeGB
number <double> [ 10 .. 4096 ]

Storage capacity of instance data volumes expressed in gigabytes. Increase this number to add capacity.

This value is not configurable on M0/M2/M5 clusters.

MongoDB Cloud requires this parameter if you set replicationSpecs.

If you specify a disk size below the minimum (10 GB), this parameter defaults to the minimum disk size value.

Storage charge calculations depend on whether you choose the default value or a custom value.

The maximum value for disk storage cannot exceed 50 times the maximum RAM for the selected cluster. If you require more storage space, consider upgrading your cluster to a higher tier.

diskWarmingMode
string
Default: "FULLY_WARMED"
Enum: "FULLY_WARMED" "VISIBLE_EARLIER"

Disk warming mode selection.

Reduce Secondary Disk Warming Impact
encryptionAtRestProvider
string
Enum: "NONE" "AWS" "AZURE" "GCP"

Cloud service provider that manages your customer keys to provide an additional layer of encryption at rest for the cluster. To enable customer key management for encryption at rest, the cluster replicationSpecs[n].regionConfigs[m].{type}Specs.instanceSize setting must be M10 or higher and "backupEnabled" : false or omitted entirely.

Encryption at Rest using Customer Key Management
globalClusterSelfManagedSharding
boolean

Set this field to configure the Sharding Management Mode when creating a new Global Cluster.

When set to false, the management mode is set to Atlas-Managed Sharding. This mode fully manages the sharding of your Global Cluster and is built to provide a seamless deployment experience.

When set to true, the management mode is set to Self-Managed Sharding. This mode leaves the management of shards in your hands and is built to provide an advanced and flexible deployment experience.

This setting cannot be changed once the cluster is deployed.

Creating a Global Cluster
Array of objects (Component Label)
Deprecated

Collection of key-value pairs between 1 to 255 characters in length that tag and categorize the cluster. The MongoDB Cloud console doesn't display your labels.

Cluster labels are deprecated and will be removed in a future release. We strongly recommend that you use resource tags instead.

mongoDBMajorVersion
string

MongoDB major version of the cluster.

On creation: Choose from the available versions of MongoDB, or leave unspecified for the current recommended default in the MongoDB Cloud platform. The recommended version is a recent Long Term Support version. The default is not guaranteed to be the most recently released version throughout the entire release cycle. For versions available in a specific project, see the linked documentation or use the API endpoint for project LTS versions endpoint.

On update: Increase version only by 1 major version at a time. If the cluster is pinned to a MongoDB feature compatibility version exactly one major version below the current MongoDB version, the MongoDB version can be downgraded to the previous major version.

Available MongoDB Versions in Atlas
name
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the advanced cluster.

paused
boolean

Flag that indicates whether the cluster is paused.

pitEnabled
boolean

Flag that indicates whether the cluster uses continuous cloud backups.

Continuous Cloud Backups
replicaSetScalingStrategy
string
Default: "WORKLOAD_TYPE"
Enum: "SEQUENTIAL" "WORKLOAD_TYPE" "NODE_TYPE"

Set this field to configure the replica set scaling mode for your cluster.

By default, Atlas scales under WORKLOAD_TYPE. This mode allows Atlas to scale your analytics nodes in parallel to your operational nodes.

When configured as SEQUENTIAL, Atlas scales all nodes sequentially. This mode is intended for steady-state workloads and applications performing latency-sensitive secondary reads.

When configured as NODE_TYPE, Atlas scales your electable nodes in parallel with your read-only and analytics nodes. This mode is intended for large, dynamic workloads requiring frequent and timely cluster tier scaling. This is the fastest scaling strategy, but it might impact latency of workloads when performing extensive secondary reads.

Modify the Replica Set Scaling Mode
Array of objects (Replication Specifications)

List of settings that configure your cluster regions. For Global Clusters, each object in the array represents a zone where your clusters nodes deploy. For non-Global sharded clusters and replica sets, this array has one object representing where your clusters nodes deploy.

rootCertType
string
Default: "ISRGROOTX1"
Value: "ISRGROOTX1"

Root Certificate Authority that MongoDB Cloud cluster uses. MongoDB Cloud supports Internet Security Research Group.

Array of objects (Resource Tag)

List that contains key-value pairs between 1 to 255 characters in length for tagging and categorizing the cluster.

Resource Tags
terminationProtectionEnabled
boolean
Default: false

Flag that indicates whether termination protection is enabled on the cluster. If set to true, MongoDB Cloud won't delete the cluster. If set to false, MongoDB Cloud will delete the cluster.

versionReleaseSystem
string
Default: "LTS"
Enum: "LTS" "CONTINUOUS"

Method by which the cluster maintains the MongoDB versions. If value is CONTINUOUS, you must not specify mongoDBMajorVersion.

Responses

Request samples

Content type
application/json

Multi Cloud Cluster

{
  • "clusterType": "REPLICASET",
  • "links": [ ],
  • "name": "multiCloud",
  • "replicationSpecs": [
    ]
}

Response samples

Content type
application/json
{
  • "acceptDataRisksAndForceReplicaSetReconfig": "2019-08-24T14:15:22Z",
  • "backupEnabled": false,
  • "biConnector": {
    },
  • "clusterType": "REPLICASET",
  • "configServerManagementMode": "ATLAS_MANAGED",
  • "configServerType": "DEDICATED",
  • "connectionStrings": {
    },
  • "createDate": "2019-08-24T14:15:22Z",
  • "diskSizeGB": 10,
  • "diskWarmingMode": "FULLY_WARMED",
  • "encryptionAtRestProvider": "NONE",
  • "featureCompatibilityVersion": "string",
  • "featureCompatibilityVersionExpirationDate": "2019-08-24T14:15:22Z",
  • "globalClusterSelfManagedSharding": true,
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "labels": [
    ],
  • "links": [],
  • "mongoDBEmployeeAccessGrant": {},
  • "mongoDBMajorVersion": "string",
  • "mongoDBVersion": "string",
  • "name": "string",
  • "paused": true,
  • "pitEnabled": true,
  • "replicaSetScalingStrategy": "SEQUENTIAL",
  • "replicationSpecs": [
    ],
  • "rootCertType": "ISRGROOTX1",
  • "stateName": "IDLE",
  • "tags": [
    ],
  • "terminationProtectionEnabled": false,
  • "versionReleaseSystem": "LTS"
}

Remove One Cluster from One Project

Removes one cluster from the specified project. The cluster must have termination protection disabled in order to be deleted. To use this resource, the requesting API Key must have the Project Owner role. This feature is not available for serverless clusters.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

retainBackups
boolean

Flag that indicates whether to retain backup snapshots for the deleted dedicated cluster.

Responses

Response samples

Content type
application/json
{
  • "detail": "(This is just an example, the exception may not be related to this endpoint) No provider AWS exists.",
  • "error": 400,
  • "errorCode": "VALIDATION_ERROR",
  • "reason": "Bad Request"
}

Return One Cluster from One Project

Returns the details for one cluster in the specified project. Clusters contain a group of hosts that maintain the same data set. The response includes multi-cloud clusters. To use this resource, the requesting API Key must have the Project Read Only role. This feature is not available for serverless clusters.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies this cluster.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "acceptDataRisksAndForceReplicaSetReconfig": "2019-08-24T14:15:22Z",
  • "backupEnabled": false,
  • "biConnector": {
    },
  • "clusterType": "REPLICASET",
  • "configServerManagementMode": "ATLAS_MANAGED",
  • "configServerType": "DEDICATED",
  • "connectionStrings": {
    },
  • "createDate": "2019-08-24T14:15:22Z",
  • "diskSizeGB": 10,
  • "diskWarmingMode": "FULLY_WARMED",
  • "encryptionAtRestProvider": "NONE",
  • "featureCompatibilityVersion": "string",
  • "featureCompatibilityVersionExpirationDate": "2019-08-24T14:15:22Z",
  • "globalClusterSelfManagedSharding": true,
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "labels": [
    ],
  • "links": [],
  • "mongoDBEmployeeAccessGrant": {},
  • "mongoDBMajorVersion": "string",
  • "mongoDBVersion": "string",
  • "name": "string",
  • "paused": true,
  • "pitEnabled": true,
  • "replicaSetScalingStrategy": "SEQUENTIAL",
  • "replicationSpecs": [
    ],
  • "rootCertType": "ISRGROOTX1",
  • "stateName": "IDLE",
  • "tags": [
    ],
  • "terminationProtectionEnabled": false,
  • "versionReleaseSystem": "LTS"
}

Modify One Cluster from One Project

Updates the details for one cluster in the specified project. Clusters contain a group of hosts that maintain the same data set. This resource can update multi-cloud clusters. To update a cluster's termination protection, the requesting API Key must have the Project Owner role. For all other updates, the requesting API Key must have the Project Cluster Manager role. You can't modify a paused cluster (paused : true). You must call this endpoint to set paused : false. After this endpoint responds with paused : false, you can call it again with the changes you want to make to the cluster. This feature is not available for serverless clusters.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Cluster to update in the specified project.

acceptDataRisksAndForceReplicaSetReconfig
string <date-time>

If reconfiguration is necessary to regain a primary due to a regional outage, submit this field alongside your topology reconfiguration to request a new regional outage resistant topology. Forced reconfigurations during an outage of the majority of electable nodes carry a risk of data loss if replicated writes (even majority committed writes) have not been replicated to the new primary node. MongoDB Atlas docs contain more information. To proceed with an operation which carries that risk, set acceptDataRisksAndForceReplicaSetReconfig to the current date.

Reconfiguring a Replica Set during a regional outage
backupEnabled
boolean
Default: false

Flag that indicates whether the cluster can perform backups. If set to true, the cluster can perform backups. You must set this value to true for NVMe clusters. Backup uses Cloud Backups for dedicated clusters and Shared Cluster Backups for tenant clusters. If set to false, the cluster doesn't use backups.

object (MongoDB Connector for Business Intelligence Settings)

Settings needed to configure the MongoDB Connector for Business Intelligence for this cluster.

MongoDB Connector for Business Intelligence
clusterType
string
Enum: "REPLICASET" "SHARDED" "GEOSHARDED"

Configuration of nodes that comprise the cluster.

configServerManagementMode
string
Default: "ATLAS_MANAGED"
Enum: "ATLAS_MANAGED" "FIXED_TO_DEDICATED"

Config Server Management Mode for creating or updating a sharded cluster.

When configured as ATLAS_MANAGED, atlas may automatically switch the cluster's config server type for optimal performance and savings.

When configured as FIXED_TO_DEDICATED, the cluster will always use a dedicated config server.

MongoDB Sharded Cluster Config Servers
diskSizeGB
number <double> [ 10 .. 4096 ]

Storage capacity of instance data volumes expressed in gigabytes. Increase this number to add capacity.

This value is not configurable on M0/M2/M5 clusters.

MongoDB Cloud requires this parameter if you set replicationSpecs.

If you specify a disk size below the minimum (10 GB), this parameter defaults to the minimum disk size value.

Storage charge calculations depend on whether you choose the default value or a custom value.

The maximum value for disk storage cannot exceed 50 times the maximum RAM for the selected cluster. If you require more storage space, consider upgrading your cluster to a higher tier.

diskWarmingMode
string
Default: "FULLY_WARMED"
Enum: "FULLY_WARMED" "VISIBLE_EARLIER"

Disk warming mode selection.

Reduce Secondary Disk Warming Impact
encryptionAtRestProvider
string
Enum: "NONE" "AWS" "AZURE" "GCP"

Cloud service provider that manages your customer keys to provide an additional layer of encryption at rest for the cluster. To enable customer key management for encryption at rest, the cluster replicationSpecs[n].regionConfigs[m].{type}Specs.instanceSize setting must be M10 or higher and "backupEnabled" : false or omitted entirely.

Encryption at Rest using Customer Key Management
globalClusterSelfManagedSharding
boolean

Set this field to configure the Sharding Management Mode when creating a new Global Cluster.

When set to false, the management mode is set to Atlas-Managed Sharding. This mode fully manages the sharding of your Global Cluster and is built to provide a seamless deployment experience.

When set to true, the management mode is set to Self-Managed Sharding. This mode leaves the management of shards in your hands and is built to provide an advanced and flexible deployment experience.

This setting cannot be changed once the cluster is deployed.

Creating a Global Cluster
Array of objects (Component Label)
Deprecated

Collection of key-value pairs between 1 to 255 characters in length that tag and categorize the cluster. The MongoDB Cloud console doesn't display your labels.

Cluster labels are deprecated and will be removed in a future release. We strongly recommend that you use resource tags instead.

mongoDBMajorVersion
string

MongoDB major version of the cluster.

On creation: Choose from the available versions of MongoDB, or leave unspecified for the current recommended default in the MongoDB Cloud platform. The recommended version is a recent Long Term Support version. The default is not guaranteed to be the most recently released version throughout the entire release cycle. For versions available in a specific project, see the linked documentation or use the API endpoint for project LTS versions endpoint.

On update: Increase version only by 1 major version at a time. If the cluster is pinned to a MongoDB feature compatibility version exactly one major version below the current MongoDB version, the MongoDB version can be downgraded to the previous major version.

Available MongoDB Versions in Atlas
name
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the advanced cluster.

paused
boolean

Flag that indicates whether the cluster is paused.

pitEnabled
boolean

Flag that indicates whether the cluster uses continuous cloud backups.

Continuous Cloud Backups
replicaSetScalingStrategy
string
Default: "WORKLOAD_TYPE"
Enum: "SEQUENTIAL" "WORKLOAD_TYPE" "NODE_TYPE"

Set this field to configure the replica set scaling mode for your cluster.

By default, Atlas scales under WORKLOAD_TYPE. This mode allows Atlas to scale your analytics nodes in parallel to your operational nodes.

When configured as SEQUENTIAL, Atlas scales all nodes sequentially. This mode is intended for steady-state workloads and applications performing latency-sensitive secondary reads.

When configured as NODE_TYPE, Atlas scales your electable nodes in parallel with your read-only and analytics nodes. This mode is intended for large, dynamic workloads requiring frequent and timely cluster tier scaling. This is the fastest scaling strategy, but it might impact latency of workloads when performing extensive secondary reads.

Modify the Replica Set Scaling Mode
Array of objects (Replication Specifications)

List of settings that configure your cluster regions. For Global Clusters, each object in the array represents a zone where your clusters nodes deploy. For non-Global sharded clusters and replica sets, this array has one object representing where your clusters nodes deploy.

rootCertType
string
Default: "ISRGROOTX1"
Value: "ISRGROOTX1"

Root Certificate Authority that MongoDB Cloud cluster uses. MongoDB Cloud supports Internet Security Research Group.

Array of objects (Resource Tag)

List that contains key-value pairs between 1 to 255 characters in length for tagging and categorizing the cluster.

Resource Tags
terminationProtectionEnabled
boolean
Default: false

Flag that indicates whether termination protection is enabled on the cluster. If set to true, MongoDB Cloud won't delete the cluster. If set to false, MongoDB Cloud will delete the cluster.

versionReleaseSystem
string
Default: "LTS"
Enum: "LTS" "CONTINUOUS"

Method by which the cluster maintains the MongoDB versions. If value is CONTINUOUS, you must not specify mongoDBMajorVersion.

Responses

Request samples

Content type
application/json
{
  • "acceptDataRisksAndForceReplicaSetReconfig": "2019-08-24T14:15:22Z",
  • "backupEnabled": false,
  • "biConnector": {
    },
  • "clusterType": "REPLICASET",
  • "configServerManagementMode": "ATLAS_MANAGED",
  • "diskSizeGB": 10,
  • "diskWarmingMode": "FULLY_WARMED",
  • "encryptionAtRestProvider": "NONE",
  • "globalClusterSelfManagedSharding": true,
  • "labels": [
    ],
  • "mongoDBMajorVersion": "string",
  • "name": "string",
  • "paused": true,
  • "pitEnabled": true,
  • "replicaSetScalingStrategy": "SEQUENTIAL",
  • "replicationSpecs": [
    ],
  • "rootCertType": "ISRGROOTX1",
  • "tags": [
    ],
  • "terminationProtectionEnabled": false,
  • "versionReleaseSystem": "LTS"
}

Response samples

Content type
application/json
{
  • "acceptDataRisksAndForceReplicaSetReconfig": "2019-08-24T14:15:22Z",
  • "backupEnabled": false,
  • "biConnector": {
    },
  • "clusterType": "REPLICASET",
  • "configServerManagementMode": "ATLAS_MANAGED",
  • "configServerType": "DEDICATED",
  • "connectionStrings": {
    },
  • "createDate": "2019-08-24T14:15:22Z",
  • "diskSizeGB": 10,
  • "diskWarmingMode": "FULLY_WARMED",
  • "encryptionAtRestProvider": "NONE",
  • "featureCompatibilityVersion": "string",
  • "featureCompatibilityVersionExpirationDate": "2019-08-24T14:15:22Z",
  • "globalClusterSelfManagedSharding": true,
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "labels": [
    ],
  • "links": [],
  • "mongoDBEmployeeAccessGrant": {},
  • "mongoDBMajorVersion": "string",
  • "mongoDBVersion": "string",
  • "name": "string",
  • "paused": true,
  • "pitEnabled": true,
  • "replicaSetScalingStrategy": "SEQUENTIAL",
  • "replicationSpecs": [
    ],
  • "rootCertType": "ISRGROOTX1",
  • "stateName": "IDLE",
  • "tags": [
    ],
  • "terminationProtectionEnabled": false,
  • "versionReleaseSystem": "LTS"
}

Test Failover for One Cluster

Starts a failover test for the specified cluster in the specified project. Clusters contain a group of hosts that maintain the same data set. A failover test checks how MongoDB Cloud handles the failure of the cluster's primary node. During the test, MongoDB Cloud shuts down the primary node and elects a new primary. To use this resource, the requesting API Key must have the Project Cluster Manager role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "detail": "(This is just an example, the exception may not be related to this endpoint)",
  • "error": 401,
  • "errorCode": "NOT_ORG_GROUP_CREATOR",
  • "reason": "Unauthorized"
}

Network Peering

Returns, adds, edits, and removes network peering containers and peering connections. When you deploy an M10+ dedicated cluster, Atlas creates a VPC for the selected provider and region or regions if no existing VPC or VPC peering connection exists for that provider and region. Atlas assigns the VPC a Classless Inter-Domain Routing (CIDR) block.

Return All Network Peering Containers in One Project for One Cloud Provider

Returns details about all network peering containers in the specified project for the specified cloud provider. If you do not specify the cloud provider, MongoDB Cloud returns details about all network peering containers in the project for Amazon Web Services (AWS). To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

providerName
required
string
Default: "AWS"
Enum: "AWS" "AZURE" "GCP"

Cloud service provider that serves the desired network peering containers.

Responses

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Create One New Network Peering Container

Creates one new network peering container in the specified project. MongoDB Cloud can deploy Network Peering connections in a network peering container. GCP can have one container per project. AWS and Azure can have one container per cloud provider region. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Creates one new network peering container in the specified project.

providerName
string

Cloud service provider that serves the requested network peering containers.

atlasCidrBlock
string^((([0-9]{1,3}\.){3}[0-9]{1,3})|(:{0,2}([0-9a...

IP addresses expressed in Classless Inter-Domain Routing (CIDR) notation that MongoDB Cloud uses for the network peering containers in your project. MongoDB Cloud assigns all of the project's clusters deployed to this cloud provider an IP address from this range. MongoDB Cloud locks this value if an M10 or greater cluster or a network peering connection exists in this project.

These CIDR blocks must fall within the ranges reserved per RFC 1918. AWS and Azure further limit the block to between the /24 and /21 ranges.

To modify the CIDR block, the target project cannot have:

  • Any M10 or greater clusters
  • Any other VPC peering connections

You can also create a new project and create a network peering connection to set the desired MongoDB Cloud network peering container CIDR block for that project. MongoDB Cloud limits the number of MongoDB nodes per network peering connection based on the CIDR block and the region selected for the project.

Example: A project in an Amazon Web Services (AWS) region supporting three availability zones and an MongoDB CIDR network peering container block of limit of /24 equals 27 three-node replica sets.

regionName
required
string
Enum: "US_EAST_1" "US_EAST_2" "US_WEST_1" "US_WEST_2" "CA_CENTRAL_1" "EU_NORTH_1" "EU_WEST_1" "EU_WEST_2" "EU_WEST_3" "EU_CENTRAL_1" "EU_CENTRAL_2" "SA_EAST_1" "AP_EAST_1" "AP_SOUTHEAST_2" "AP_SOUTHEAST_3" "AP_SOUTHEAST_4" "AP_NORTHEAST_1" "AP_NORTHEAST_2" "AP_NORTHEAST_3" "AP_SOUTHEAST_1" "AP_SOUTH_1" "AP_SOUTH_2" "CN_NORTH_1" "CN_NORTHWEST_1" "ME_CENTRAL_1" "ME_SOUTH_1" "AF_SOUTH_1" "EU_SOUTH_1" "EU_SOUTH_2" "IL_CENTRAL_1" "CA_WEST_1" "GLOBAL" "US_GOV_WEST_1" "US_GOV_EAST_1"

Geographic area that Amazon Web Services (AWS) defines to which MongoDB Cloud deployed this network peering container.

Responses

Request samples

Content type
application/json
Example
{
  • "providerName": "AWS",
  • "atlasCidrBlock": "string",
  • "region": "US_CENTRAL",
  • "regionName": "US_EAST_1"
}

Response samples

Content type
application/json
Example
{
  • "id": "32b6e34b3d91647abb20e7b8",
  • "providerName": "AWS",
  • "provisioned": true,
  • "atlasCidrBlock": "string",
  • "azureSubscriptionId": "32b6e34b3d91647abb20e7b8",
  • "region": "US_CENTRAL",
  • "vnetName": "stringstringstringstringstringstringst",
  • "regionName": "US_EAST_1",
  • "vpcId": "vpc-b555d3b0d9cb783b0"
}

Return All Network Peering Containers in One Project

Returns details about all network peering containers in the specified project. Network peering containers contain network peering connections. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Remove One Network Peering Container

Removes one network peering container in the specified project. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

containerId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies the MongoDB Cloud network container that you want to remove.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{ }

Return One Network Peering Container

Returns details about one network peering container in one specified project. Network peering containers contain network peering connections. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

containerId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies the MongoDB Cloud network container.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
Example
{
  • "id": "32b6e34b3d91647abb20e7b8",
  • "providerName": "AWS",
  • "provisioned": true,
  • "atlasCidrBlock": "string",
  • "azureSubscriptionId": "32b6e34b3d91647abb20e7b8",
  • "region": "US_CENTRAL",
  • "vnetName": "stringstringstringstringstringstringst",
  • "regionName": "US_EAST_1",
  • "vpcId": "vpc-b555d3b0d9cb783b0"
}

Update One Network Peering Container

Updates the network details and labels of one specified network peering container in the specified project. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

containerId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies the MongoDB Cloud network container that you want to remove.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Updates the network details and labels of one specified network peering container in the specified project.

providerName
string

Cloud service provider that serves the requested network peering containers.

atlasCidrBlock
string^((([0-9]{1,3}\.){3}[0-9]{1,3})|(:{0,2}([0-9a...

IP addresses expressed in Classless Inter-Domain Routing (CIDR) notation that MongoDB Cloud uses for the network peering containers in your project. MongoDB Cloud assigns all of the project's clusters deployed to this cloud provider an IP address from this range. MongoDB Cloud locks this value if an M10 or greater cluster or a network peering connection exists in this project.

These CIDR blocks must fall within the ranges reserved per RFC 1918. AWS and Azure further limit the block to between the /24 and /21 ranges.

To modify the CIDR block, the target project cannot have:

  • Any M10 or greater clusters
  • Any other VPC peering connections

You can also create a new project and create a network peering connection to set the desired MongoDB Cloud network peering container CIDR block for that project. MongoDB Cloud limits the number of MongoDB nodes per network peering connection based on the CIDR block and the region selected for the project.

Example: A project in an Amazon Web Services (AWS) region supporting three availability zones and an MongoDB CIDR network peering container block of limit of /24 equals 27 three-node replica sets.

regionName
required
string
Enum: "US_EAST_1" "US_EAST_2" "US_WEST_1" "US_WEST_2" "CA_CENTRAL_1" "EU_NORTH_1" "EU_WEST_1" "EU_WEST_2" "EU_WEST_3" "EU_CENTRAL_1" "EU_CENTRAL_2" "SA_EAST_1" "AP_EAST_1" "AP_SOUTHEAST_2" "AP_SOUTHEAST_3" "AP_SOUTHEAST_4" "AP_NORTHEAST_1" "AP_NORTHEAST_2" "AP_NORTHEAST_3" "AP_SOUTHEAST_1" "AP_SOUTH_1" "AP_SOUTH_2" "CN_NORTH_1" "CN_NORTHWEST_1" "ME_CENTRAL_1" "ME_SOUTH_1" "AF_SOUTH_1" "EU_SOUTH_1" "EU_SOUTH_2" "IL_CENTRAL_1" "CA_WEST_1" "GLOBAL" "US_GOV_WEST_1" "US_GOV_EAST_1"

Geographic area that Amazon Web Services (AWS) defines to which MongoDB Cloud deployed this network peering container.

Responses

Request samples

Content type
application/json
Example
{
  • "providerName": "AWS",
  • "atlasCidrBlock": "string",
  • "region": "US_CENTRAL",
  • "regionName": "US_EAST_1"
}

Response samples

Content type
application/json
Example
{
  • "id": "32b6e34b3d91647abb20e7b8",
  • "providerName": "AWS",
  • "provisioned": true,
  • "atlasCidrBlock": "string",
  • "azureSubscriptionId": "32b6e34b3d91647abb20e7b8",
  • "region": "US_CENTRAL",
  • "vnetName": "stringstringstringstringstringstringst",
  • "regionName": "US_EAST_1",
  • "vpcId": "vpc-b555d3b0d9cb783b0"
}

Return All Network Peering Connections in One Project

Returns details about all network peering connections in the specified project. Network peering allows multiple cloud-hosted applications to securely connect to the same project. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

providerName
string
Default: "AWS"
Enum: "AWS" "AZURE" "GCP"

Cloud service provider to use for this VPC peering connection.

Responses

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Create One New Network Peering Connection

Creates one new network peering connection in the specified project. Network peering allows multiple cloud-hosted applications to securely connect to the same project. To use this resource, the requesting API Key must have the Project Owner role. To learn more about considerations and prerequisites, see the Network Peering Documentation.

Azure Network Peering Prerequisites
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Create one network peering connection.

accepterRegionName
required
string

Amazon Web Services (AWS) region where the Virtual Peering Connection (VPC) that you peered with the MongoDB Cloud VPC resides. The resource returns null if your VPC and the MongoDB Cloud VPC reside in the same region.

awsAccountId
required
string = 12 characters ^[0-9]{12}$

Unique twelve-digit string that identifies the Amazon Web Services (AWS) account that owns the VPC that you peered with the MongoDB Cloud VPC.

containerId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the MongoDB Cloud network container that contains the specified network peering connection.

providerName
string

Cloud service provider that serves the requested network peering connection.

routeTableCidrBlock
required
string^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)(\.(?!$)|$))...

Internet Protocol (IP) addresses expressed in Classless Inter-Domain Routing (CIDR) notation of the VPC's subnet that you want to peer with the MongoDB Cloud VPC.

vpcId
required
string >= 5 characters ^vpc-[0-9a-f]{17}$

Unique string that identifies the VPC on Amazon Web Services (AWS) that you want to peer with the MongoDB Cloud VPC.

Responses

Request samples

Content type
application/json
Example
{
  • "accepterRegionName": "string",
  • "awsAccountId": "stringstring",
  • "containerId": "32b6e34b3d91647abb20e7b8",
  • "providerName": "AWS",
  • "routeTableCidrBlock": "string",
  • "vpcId": "string"
}

Response samples

Content type
application/json
Example
{
  • "accepterRegionName": "string",
  • "awsAccountId": "stringstring",
  • "connectionId": "string",
  • "containerId": "32b6e34b3d91647abb20e7b8",
  • "errorStateName": "REJECTED",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "providerName": "AWS",
  • "routeTableCidrBlock": "string",
  • "statusName": "INITIATING",
  • "vpcId": "string"
}

Remove One Existing Network Peering Connection

Removes one network peering connection in the specified project. If you Removes the last network peering connection associated with a project, MongoDB Cloud also removes any AWS security groups from the project IP access list. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

peerId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the network peering connection that you want to delete.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{ }

Return One Network Peering Connection in One Project

Returns details about one specified network peering connection in the specified project. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

peerId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the network peering connection that you want to retrieve.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
Example
{
  • "accepterRegionName": "string",
  • "awsAccountId": "stringstring",
  • "connectionId": "string",
  • "containerId": "32b6e34b3d91647abb20e7b8",
  • "errorStateName": "REJECTED",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "providerName": "AWS",
  • "routeTableCidrBlock": "string",
  • "statusName": "INITIATING",
  • "vpcId": "string"
}

Update One New Network Peering Connection

Updates one specified network peering connection in the specified project. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

peerId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the network peering connection that you want to update.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Modify one network peering connection.

accepterRegionName
required
string

Amazon Web Services (AWS) region where the Virtual Peering Connection (VPC) that you peered with the MongoDB Cloud VPC resides. The resource returns null if your VPC and the MongoDB Cloud VPC reside in the same region.

awsAccountId
required
string = 12 characters ^[0-9]{12}$

Unique twelve-digit string that identifies the Amazon Web Services (AWS) account that owns the VPC that you peered with the MongoDB Cloud VPC.

containerId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the MongoDB Cloud network container that contains the specified network peering connection.

providerName
string

Cloud service provider that serves the requested network peering connection.

routeTableCidrBlock
required
string^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)(\.(?!$)|$))...

Internet Protocol (IP) addresses expressed in Classless Inter-Domain Routing (CIDR) notation of the VPC's subnet that you want to peer with the MongoDB Cloud VPC.

vpcId
required
string >= 5 characters ^vpc-[0-9a-f]{17}$

Unique string that identifies the VPC on Amazon Web Services (AWS) that you want to peer with the MongoDB Cloud VPC.

Responses

Request samples

Content type
application/json
Example
{
  • "accepterRegionName": "string",
  • "awsAccountId": "stringstring",
  • "containerId": "32b6e34b3d91647abb20e7b8",
  • "providerName": "AWS",
  • "routeTableCidrBlock": "string",
  • "vpcId": "string"
}

Response samples

Content type
application/json
Example
{
  • "accepterRegionName": "string",
  • "awsAccountId": "stringstring",
  • "connectionId": "string",
  • "containerId": "32b6e34b3d91647abb20e7b8",
  • "errorStateName": "REJECTED",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "providerName": "AWS",
  • "routeTableCidrBlock": "string",
  • "statusName": "INITIATING",
  • "vpcId": "string"
}

Verify Connect via Peering Only Mode for One Project Deprecated

Verifies if someone set the specified project to Connect via Peering Only mode. To use this resource, the requesting API Key must have the Project Read Only role.

Changes to Connection Strings
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "enabled": true
}

Disable Connect via Peering Only Mode for One Project Deprecated

Disables Connect via Peering Only mode for the specified project. To use this resource, the requesting API Key must have the Project Owner role.

Changes to Connection Strings
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Disables Connect via Peering Only mode for the specified project.

enabled
required
boolean

Flag that indicates whether someone enabled Connect via Peering Only mode for the specified project.

Responses

Request samples

Content type
application/json
{
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "enabled": true
}

Online Archive

Returns, adds, edits, or removes an online archive.

Return All Online Archives for One Cluster

Returns details of all online archives. This archive stores data from one cluster within one project. To use this resource, the requesting API Key must have the Project Read Only role.

Online Archive
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster that contains the collection for which you want to return the online archives.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Create One Online Archive

Creates one online archive. This archive stores data from one cluster within one project. To use this resource, the requesting API Key must have the Project Data Access Admin role.

Online Archive
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster that contains the collection for which you want to create one online archive.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Creates one online archive.

collName
required
string

Human-readable label that identifies the collection for which you created the online archive.

collectionType
string
Default: "STANDARD"
Enum: "TIMESERIES" "STANDARD"

Classification of MongoDB database collection that you want to return.

If you set this parameter to TIMESERIES, set "criteria.type" : "date" and "criteria.dateFormat" : "ISODATE".

required
object (CriteriaView)

Rules by which MongoDB Cloud archives data.

Use the criteria.type field to choose how MongoDB Cloud selects data to archive. Choose data using the age of the data or a MongoDB query. "criteria.type": "DATE" selects documents to archive based on a date. "criteria.type": "CUSTOM" selects documents to archive based on a custom JSON query. MongoDB Cloud doesn't support "criteria.type": "CUSTOM" when "collectionType": "TIMESERIES".

object (DataExpirationRuleView)

Rule for specifying when data should be deleted from the archive.

object (CreateDataProcessRegionView)

Settings to configure the region where you wish to store your archived data.

dbName
required
string

Human-readable label of the database that contains the collection that contains the online archive.

Array of objects (Online Archive Partition) non-empty

List that contains document parameters to use to logically divide data within a collection. Partitions provide a coarse level of filtering of the underlying collection data. To divide your data, specify parameters that you frequently query. If you "specified :criteria.type": "DATE" in the CREATE ONE ONLINE ARCHIVE endpoint, then you can specify up to three parameters by which to query. One of these parameters must be the DATE value, which is required in this case. If you "specified :criteria.type": "CUSTOM" in the CREATE ONE ONLINE ARCHIVE endpoint, then you can specify up to two parameters by which to query. Queries that don't use ":criteria.type": "DATE" or ":criteria.type": "CUSTOM" parameters cause MongoDB to scan a full collection of all archived documents. This takes more time and increases your costs.

paused
boolean

Flag that indicates whether this online archive exists in the paused state. A request to resume fails if the collection has another active online archive. To pause an active online archive or resume a paused online archive, you must include this parameter. To pause an active archive, set this to true. To resume a paused archive, set this to false.

object (Online Archive Schedule)

Regular frequency and duration when archiving process occurs.

Responses

Request samples

Content type
application/json
{
  • "collName": "string",
  • "collectionType": "TIMESERIES",
  • "criteria": {
    },
  • "dataExpirationRule": {
    },
  • "dataProcessRegion": {
    },
  • "dbName": "string",
  • "partitionFields": [
    ],
  • "paused": true,
  • "schedule": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "32b6e34b3d91647abb20e7b8",
  • "clusterName": "string",
  • "collName": "string",
  • "collectionType": "TIMESERIES",
  • "criteria": {
    },
  • "dataExpirationRule": {
    },
  • "dataProcessRegion": {
    },
  • "dataSetName": "string",
  • "dbName": "string",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "partitionFields": [
    ],
  • "paused": true,
  • "schedule": {
    },
  • "state": "PENDING"
}

Download Online Archive Query Logs

Downloads query logs for the specified online archive. To use this resource, the requesting API Key must have the Project Data Access Read Only or higher role. The API does not support direct calls with the json response schema. You must request a gzip response schema using an accept header of the format: "Accept: application/gzip".

Online Archive
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster that contains the collection for which you want to return the query logs from one online archive.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

startDate
integer <int64> >= 1199145600
Example: startDate=1636481348

Date and time that specifies the starting point for the range of log messages to return. This resource expresses this value in the number of seconds that have elapsed since the UNIX epoch.

endDate
integer <int64> >= 1199145600
Example: endDate=1636481348

Date and time that specifies the end point for the range of log messages to return. This resource expresses this value in the number of seconds that have elapsed since the UNIX epoch.

archiveOnly
boolean
Default: false

Flag that indicates whether to download logs for queries against your online archive only or both your online archive and cluster.

Responses

Response samples

Content type
application/json
{
  • "detail": "(This is just an example, the exception may not be related to this endpoint) No provider AWS exists.",
  • "error": 400,
  • "errorCode": "VALIDATION_ERROR",
  • "reason": "Bad Request"
}

Remove One Online Archive

Removes one online archive. This archive stores data from one cluster within one project. To use this resource, the requesting API Key must have the Project Data Access Admin role.

Online Archive
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

archiveId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the online archive to delete.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster that contains the collection from which you want to remove an online archive.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{ }

Return One Online Archive

Returns one online archive for one cluster. This archive stores data from one cluster within one project. To use this resource, the requesting API Key must have the Project Read Only role.

Online Archive
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

archiveId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the online archive to return.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster that contains the specified collection from which Application created the online archive.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "_id": "32b6e34b3d91647abb20e7b8",
  • "clusterName": "string",
  • "collName": "string",
  • "collectionType": "TIMESERIES",
  • "criteria": {
    },
  • "dataExpirationRule": {
    },
  • "dataProcessRegion": {
    },
  • "dataSetName": "string",
  • "dbName": "string",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "partitionFields": [
    ],
  • "paused": true,
  • "schedule": {
    },
  • "state": "PENDING"
}

Update One Online Archive

Updates, pauses, or resumes one online archive. This archive stores data from one cluster within one project. To use this resource, the requesting API Key must have the Project Data Access Admin role.

Online Archive
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

archiveId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the online archive to update.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster that contains the specified collection from which Application created the online archive.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Updates, pauses, or resumes one online archive.

object (CriteriaView)

Rules by which MongoDB Cloud archives data.

Use the criteria.type field to choose how MongoDB Cloud selects data to archive. Choose data using the age of the data or a MongoDB query. "criteria.type": "DATE" selects documents to archive based on a date. "criteria.type": "CUSTOM" selects documents to archive based on a custom JSON query. MongoDB Cloud doesn't support "criteria.type": "CUSTOM" when "collectionType": "TIMESERIES".

object (DataExpirationRuleView)

Rule for specifying when data should be deleted from the archive.

paused
boolean

Flag that indicates whether this online archive exists in the paused state. A request to resume fails if the collection has another active online archive. To pause an active online archive or resume a paused online archive, you must include this parameter. To pause an active archive, set this to true. To resume a paused archive, set this to false.

object (Online Archive Schedule)

Regular frequency and duration when archiving process occurs.

Responses

Request samples

Content type
application/json
{
  • "criteria": {
    },
  • "dataExpirationRule": {
    },
  • "paused": true,
  • "schedule": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "32b6e34b3d91647abb20e7b8",
  • "clusterName": "string",
  • "collName": "string",
  • "collectionType": "TIMESERIES",
  • "criteria": {
    },
  • "dataExpirationRule": {
    },
  • "dataProcessRegion": {
    },
  • "dataSetName": "string",
  • "dbName": "string",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "partitionFields": [
    ],
  • "paused": true,
  • "schedule": {
    },
  • "state": "PENDING"
}

Organizations

Returns, adds, and edits organizational units in MongoDB Cloud.

Return All Organizations

Returns all organizations to which the requesting API Key has access. To use this resource, the requesting API Key must have the Organization Member role.

Authorizations:
DigestAuthServiceAccounts
query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

name
string

Human-readable label of the organization to use to filter the returned list. Performs a case-insensitive search for an organization that starts with the specified name.

Responses

Response samples

Content type
application/json
{}

Create One Organization

Creates one organization in MongoDB Cloud and links it to the requesting API Key's organization. To use this resource, the requesting API Key must have the Organization Owner role. The requesting API Key's organization must be a paying organization. To learn more, see Configure a Paying Organization in the MongoDB Atlas documentation.

Authorizations:
DigestAuthServiceAccounts
query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Organization that you want to create.

object (CreateAtlasOrganizationApiKey)

Details of the programmatic API key to be created.

federationSettingsId
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the federation to link the newly created organization to. If specified, the proposed Organization Owner of the new organization must have the Organization Owner role in an organization associated with the federation.

name
required
string [ 1 .. 64 ] characters ^[\p{L}\p{N}\-_.(),:&@+']{1,64}$

Human-readable label that identifies the organization.

orgOwnerId
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the MongoDB Cloud user that you want to assign the Organization Owner role. This user must be a member of the same organization as the calling API key. If you provide federationSettingsId, this user must instead have the Organization Owner role on an organization in the specified federation. This parameter is required only when you authenticate with Programmatic API Keys.

Responses

Request samples

Content type
application/json
{
  • "apiKey": {
    },
  • "federationSettingsId": "32b6e34b3d91647abb20e7b8",
  • "name": "string",
  • "orgOwnerId": "32b6e34b3d91647abb20e7b8"
}

Response samples

Content type
application/json
{
  • "apiKey": {
    },
  • "federationSettingsId": "32b6e34b3d91647abb20e7b8",
  • "orgOwnerId": "32b6e34b3d91647abb20e7b8",
  • "organization": {}
}

Remove One Organization

Removes one specified organization. MongoDB Cloud imposes the following limits on this resource:

  • Organizations with active projects cannot be removed.
  • All projects in the organization must be removed before you can remove the organization. To use this resource, the requesting API Key must have the Organization Owner role.
Authorizations:
DigestAuthServiceAccounts
path Parameters
orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Responses

Response samples

Content type
application/json
{ }

Return One Organization

Returns one organization to which the requesting API key has access. To use this resource, the requesting API Key must have the Organization Member role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{}

Rename One Organization

Renames one organization. To use this resource, the requesting API Key must have the Organization Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Details to update on the specified organization.

name
required
string [ 1 .. 64 ] characters ^[\p{L}\p{N}\-_.(),:&@+']{1,64}$

Human-readable label that identifies the organization.

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{}

Return One or More Projects in One Organization

Returns multiple projects in the specified organization. Each organization can have multiple projects. Use projects to:

  • Isolate different environments, such as development, test, or production environments, from each other.
  • Associate different MongoDB Cloud users or teams with different environments, or give different permission to MongoDB Cloud users in different environments.
  • Maintain separate cluster security configurations.
  • Create different alert settings.

To use this resource, the requesting API Key must have the Organization Member role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

name
string

Human-readable label of the project to use to filter the returned list. Performs a case-insensitive search for a project within the organization which is prefixed by the specified name.

Responses

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Return All Organization Invitations

Returns all pending invitations to the specified organization. To use this resource, the requesting API Key must have the Organization Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

username
string <email>

Email address of the user account invited to this organization. If you exclude this parameter, this resource returns all pending invitations.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update One Organization Invitation

Updates the details of one pending invitation to the specified organization. To specify which invitation, provide the username of the invited user. To use this resource, the requesting API Key must have the Organization Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Updates the details of one pending invitation to the specified organization.

Array of objects (OrganizationInvitationGroupRoleAssignmentsRequest)

List of projects that the user will be added to when they accept their invitation to the organization.

roles
Array of strings unique
Items Enum: "ORG_OWNER" "ORG_MEMBER" "ORG_GROUP_CREATOR" "ORG_BILLING_ADMIN" "ORG_READ_ONLY"

One or more organization level roles to assign to the MongoDB Cloud user.

teamIds
Array of strings unique [ items = 24 characters ^([a-f0-9]{24})$ ]

List of teams to which you want to invite the desired MongoDB Cloud user.

username
string <email>

Email address that belongs to the desired MongoDB Cloud user.

Responses

Request samples

Content type
application/json
{
  • "groupRoleAssignments": [
    ],
  • "roles": [
    ],
  • "teamIds": [
    ],
  • "username": "user@example.com"
}

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "groupRoleAssignments": [
    ],
  • "id": "32b6e34b3d91647abb20e7b8",
  • "inviterUsername": "user@example.com",
  • "links": [],
  • "orgId": "32b6e34b3d91647abb20e7b8",
  • "orgName": "string",
  • "roles": [
    ],
  • "teamIds": [
    ],
  • "username": "user@example.com"
}

Invite One MongoDB Cloud User to Join One Atlas Organization

Invites one MongoDB Cloud user to join the specified organization. The user must accept the invitation to access information within the specified organization. To use this resource, the requesting API Key must have the Organization Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Invites one MongoDB Cloud user to join the specified organization.

Array of objects (OrganizationInvitationGroupRoleAssignmentsRequest)

List of projects that the user will be added to when they accept their invitation to the organization.

roles
Array of strings unique
Items Enum: "ORG_OWNER" "ORG_MEMBER" "ORG_GROUP_CREATOR" "ORG_BILLING_ADMIN" "ORG_READ_ONLY"

One or more organization level roles to assign to the MongoDB Cloud user.

teamIds
Array of strings unique [ items = 24 characters ^([a-f0-9]{24})$ ]

List of teams to which you want to invite the desired MongoDB Cloud user.

username
string <email>

Email address that belongs to the desired MongoDB Cloud user.

Responses

Request samples

Content type
application/json
{
  • "groupRoleAssignments": [
    ],
  • "roles": [
    ],
  • "teamIds": [
    ],
  • "username": "user@example.com"
}

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "groupRoleAssignments": [
    ],
  • "id": "32b6e34b3d91647abb20e7b8",
  • "inviterUsername": "user@example.com",
  • "links": [],
  • "orgId": "32b6e34b3d91647abb20e7b8",
  • "orgName": "string",
  • "roles": [
    ],
  • "teamIds": [
    ],
  • "username": "user@example.com"
}

Cancel One Organization Invitation

Cancels one pending invitation sent to the specified MongoDB Cloud user to join an organization. You can't cancel an invitation that the user accepted. To use this resource, the requesting API Key must have the Organization Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

invitationId
required
string

Unique 24-hexadecimal digit string that identifies the invitation.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{ }

Return One Organization Invitation

Returns the details of one pending invitation to the specified organization. To use this resource, the requesting API Key must have the Organization Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

invitationId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the invitation.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Responses

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "groupRoleAssignments": [
    ],
  • "id": "32b6e34b3d91647abb20e7b8",
  • "inviterUsername": "user@example.com",
  • "links": [],
  • "orgId": "32b6e34b3d91647abb20e7b8",
  • "orgName": "string",
  • "roles": [
    ],
  • "teamIds": [
    ],
  • "username": "user@example.com"
}

Update One Organization Invitation by Invitation ID

Updates the details of one pending invitation to the specified organization. To specify which invitation, provide the unique identification string for that invitation. Use the Return All Organization Invitations endpoint to retrieve IDs for all pending organization invitations. To use this resource, the requesting API Key must have the Organization Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

invitationId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the invitation.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Updates the details of one pending invitation to the specified organization.

Array of objects (OrganizationInvitationGroupRoleAssignmentsRequest)

List of projects that the user will be added to when they accept their invitation to the organization.

roles
Array of strings unique
Items Enum: "ORG_OWNER" "ORG_MEMBER" "ORG_GROUP_CREATOR" "ORG_BILLING_ADMIN" "ORG_READ_ONLY"

One or more organization level roles to assign to the MongoDB Cloud user.

teamIds
Array of strings unique [ items = 24 characters ^([a-f0-9]{24})$ ]

List of teams to which you want to invite the desired MongoDB Cloud user.

Responses

Request samples

Content type
application/json
{
  • "groupRoleAssignments": [
    ],
  • "roles": [
    ],
  • "teamIds": [
    ]
}

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "groupRoleAssignments": [
    ],
  • "id": "32b6e34b3d91647abb20e7b8",
  • "inviterUsername": "user@example.com",
  • "links": [],
  • "orgId": "32b6e34b3d91647abb20e7b8",
  • "orgName": "string",
  • "roles": [
    ],
  • "teamIds": [
    ],
  • "username": "user@example.com"
}

Return Settings for One Organization

Returns details about the specified organization's settings. To use this resource, the requesting API Key must have the Organization Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "apiAccessListRequired": true,
  • "genAIFeaturesEnabled": true,
  • "maxServiceAccountSecretValidityInHours": 0,
  • "multiFactorAuthRequired": true,
  • "restrictEmployeeAccess": true,
  • "securityContact": "string"
}

Update Settings for One Organization

Updates the organization's settings. To use this resource, the requesting API Key must have the Organization Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Details to update on the specified organization's settings.

apiAccessListRequired
boolean

Flag that indicates whether to require API operations to originate from an IP Address added to the API access list for the specified organization.

genAIFeaturesEnabled
boolean
Default: true

Flag that indicates whether this organization has access to generative AI features. This setting only applies to Atlas Commercial and is enabled by default. Once this setting is turned on, Project Owners may be able to enable or disable individual AI features at the project level.

Generative AI FAQs
maxServiceAccountSecretValidityInHours
integer <int32>

Number that represents the maximum period before expiry in hours for new Atlas Admin API Service Account secrets within the specified organization.

multiFactorAuthRequired
boolean

Flag that indicates whether to require users to set up Multi-Factor Authentication (MFA) before accessing the specified organization. To learn more, see: https://www.mongodb.com/docs/atlas/security-multi-factor-authentication/.

restrictEmployeeAccess
boolean

Flag that indicates whether to block MongoDB Support from accessing Atlas infrastructure and cluster logs for any deployment in the specified organization without explicit permission. Once this setting is turned on, you can grant MongoDB Support a 24-hour bypass access to the Atlas deployment to resolve support issues. To learn more, see: https://www.mongodb.com/docs/atlas/security-restrict-support-access/.

securityContact
string

String that specifies a single email address for the specified organization to receive security-related notifications. Specifying a security contact does not grant them authorization or access to Atlas for security decisions or approvals. An empty string is valid and clears the existing security contact (if any).

Responses

Request samples

Content type
application/json
{
  • "apiAccessListRequired": true,
  • "genAIFeaturesEnabled": true,
  • "maxServiceAccountSecretValidityInHours": 0,
  • "multiFactorAuthRequired": true,
  • "restrictEmployeeAccess": true,
  • "securityContact": "string"
}

Response samples

Content type
application/json
{
  • "apiAccessListRequired": true,
  • "genAIFeaturesEnabled": true,
  • "maxServiceAccountSecretValidityInHours": 0,
  • "multiFactorAuthRequired": true,
  • "restrictEmployeeAccess": true,
  • "securityContact": "string"
}

Return All MongoDB Cloud Users in One Organization

Returns details about the MongoDB Cloud users associated with the specified organization. Each MongoDB Cloud user returned must belong to the specified organization or to a project within the specified organization. To use this resource, the requesting API Key must have the Organization Member role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

Responses

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Remove One MongoDB Cloud User From One Organization

Removes one MongoDB Cloud user from the specified organization. To use this resource, the requesting API Key must have the Organization User Admin role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

userId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the user to be deleted.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{ }

Performance Advisor

Returns suggested indexes and slow query data for a database deployment. Also enables or disables MongoDB Cloud-managed slow operation thresholds. To view field values in a sample query, you must have the Project Data Access Read Only role or higher. Otherwise, MongoDB Cloud returns redacted data rather than the field values.

Disable Managed Slow Operation Threshold

Disables the slow operation threshold that MongoDB Cloud calculated for the specified project. The threshold determines which operations the Performance Advisor and Query Profiler considers slow. When enabled, MongoDB Cloud uses the average execution time for operations on your cluster to determine slow-running queries. As a result, the threshold is more pertinent to your cluster workload. The slow operation threshold is enabled by default for dedicated clusters (M10+). When disabled, MongoDB Cloud considers any operation that takes longer than 100 milliseconds to be slow. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "detail": "(This is just an example, the exception may not be related to this endpoint)",
  • "error": 401,
  • "errorCode": "NOT_ORG_GROUP_CREATOR",
  • "reason": "Unauthorized"
}

Enable Managed Slow Operation Threshold

Enables MongoDB Cloud to use its slow operation threshold for the specified project. The threshold determines which operations the Performance Advisor and Query Profiler considers slow. When enabled, MongoDB Cloud uses the average execution time for operations on your cluster to determine slow-running queries. As a result, the threshold is more pertinent to your cluster workload. The slow operation threshold is enabled by default for dedicated clusters (M10+). When disabled, MongoDB Cloud considers any operation that takes longer than 100 milliseconds to be slow. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "detail": "(This is just an example, the exception may not be related to this endpoint)",
  • "error": 401,
  • "errorCode": "NOT_ORG_GROUP_CREATOR",
  • "reason": "Unauthorized"
}

Return All Namespaces for One Host

Returns up to 20 namespaces for collections experiencing slow queries on the specified host. If you specify a secondary member of a replica set that hasn't received any database read operations, the endpoint doesn't return any namespaces. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

processId
required
string^([0-9]{1,3}\.){3}[0-9]{1,3}|([0-9a-f]{1,4}\:...

Combination of host and port that serves the MongoDB process. The host must be the hostname, FQDN, IPv4 address, or IPv6 address of the host that runs the MongoDB process (mongod or mongos). The port must be the IANA port on which the MongoDB process listens for requests.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

duration
integer <int64>

Length of time expressed during which the query finds suggested indexes among the managed namespaces in the cluster. This parameter expresses its value in milliseconds.

  • If you don't specify the since parameter, the endpoint returns data covering the duration before the current time.
  • If you specify neither the duration nor since parameters, the endpoint returns data from the previous 24 hours.
since
integer <int64> >= 1199145600000

Date and time from which the query retrieves the suggested indexes. This parameter expresses its value in the number of milliseconds that have elapsed since the UNIX epoch.

  • If you don't specify the duration parameter, the endpoint returns data covering from the since value and the current time.
  • If you specify neither the duration nor the since parameters, the endpoint returns data from the previous 24 hours.

Responses

Response samples

Content type
application/json
{
  • "namespaces": [
    ]
}

Return Slow Queries

Returns log lines for slow queries that the Performance Advisor and Query Profiler identified. The Performance Advisor monitors queries that MongoDB considers slow and suggests new indexes to improve query performance. MongoDB Cloud bases the threshold for slow queries on the average time of operations on your cluster. This enables workload-relevant recommendations. To use this resource, the requesting API Key must have the Project Data Access Read Write role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

processId
required
string^([0-9]{1,3}\.){3}[0-9]{1,3}|([0-9a-f]{1,4}\:...

Combination of host and port that serves the MongoDB process. The host must be the hostname, FQDN, IPv4 address, or IPv6 address of the host that runs the MongoDB process (mongod or mongos). The port must be the IANA port on which the MongoDB process listens for requests.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

duration
integer <int64>

Length of time expressed during which the query finds slow queries among the managed namespaces in the cluster. This parameter expresses its value in milliseconds.

  • If you don't specify the since parameter, the endpoint returns data covering the duration before the current time.
  • If you specify neither the duration nor since parameters, the endpoint returns data from the previous 24 hours.
namespaces
Array of strings

Namespaces from which to retrieve slow queries. A namespace consists of one database and one collection resource written as .: <database>.<collection>. To include multiple namespaces, pass the parameter multiple times delimited with an ampersand (&) between each namespace. Omit this parameter to return results for all namespaces.

nLogs
integer <int64> [ 0 .. 20000 ]
Default: 20000

Maximum number of lines from the log to return.

since
integer <int64> >= 1199145600000

Date and time from which the query retrieves the slow queries. This parameter expresses its value in the number of milliseconds that have elapsed since the UNIX epoch.

  • If you don't specify the duration parameter, the endpoint returns data covering from the since value and the current time.
  • If you specify neither the duration nor the since parameters, the endpoint returns data from the previous 24 hours.

Responses

Response samples

Content type
application/json
{
  • "slowQueries": [
    ]
}

Return Suggested Indexes

Returns the indexes that the Performance Advisor suggests. The Performance Advisor monitors queries that MongoDB considers slow and suggests new indexes to improve query performance. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

processId
required
string^([0-9]{1,3}\.){3}[0-9]{1,3}|([0-9a-f]{1,4}\:...

Combination of host and port that serves the MongoDB process. The host must be the hostname, FQDN, IPv4 address, or IPv6 address of the host that runs the MongoDB process (mongod or mongos). The port must be the IANA port on which the MongoDB process listens for requests.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

duration
integer <int64>

Length of time expressed during which the query finds suggested indexes among the managed namespaces in the cluster. This parameter expresses its value in milliseconds.

  • If you don't specify the since parameter, the endpoint returns data covering the duration before the current time.
  • If you specify neither the duration nor since parameters, the endpoint returns data from the previous 24 hours.
namespaces
Array of strings

Namespaces from which to retrieve suggested indexes. A namespace consists of one database and one collection resource written as .: <database>.<collection>. To include multiple namespaces, pass the parameter multiple times delimited with an ampersand (&) between each namespace. Omit this parameter to return results for all namespaces.

nExamples
integer <int64>
Default: 5

Maximum number of example queries that benefit from the suggested index.

nIndexes
integer <int64>

Number that indicates the maximum indexes to suggest.

since
integer <int64> >= 1199145600000

Date and time from which the query retrieves the suggested indexes. This parameter expresses its value in the number of milliseconds that have elapsed since the UNIX epoch.

  • If you don't specify the duration parameter, the endpoint returns data covering from the since value and the current time.
  • If you specify neither the duration nor the since parameters, the endpoint returns data from the previous 24 hours.

Responses

Response samples

Content type
application/json
{
  • "shapes": [
    ],
  • "suggestedIndexes": [
    ]
}

Private Endpoint Services

Returns, adds, edits, and removes private endpoint services.

Create One Private Endpoint Service for One Provider

Creates one private endpoint service for the specified cloud service provider. This cloud service provider manages the private endpoint service for the project. When you create a private endpoint service, MongoDB Cloud creates a network container in the project for the cloud provider for which you create the private endpoint service if one doesn't already exist. To learn more about private endpoint terminology in MongoDB Cloud, see Private Endpoint Concepts. To use this resource, the requesting API Key must have the Project Owner role.

Private Endpoint Concepts
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Creates one private endpoint for the specified cloud service provider.

providerName
required
string
Enum: "AWS" "AZURE" "GCP"

Human-readable label that identifies the cloud service provider for which you want to create the private endpoint service.

region
required
string

Cloud provider region in which you want to create the private endpoint service. Regions accepted as values differ for Amazon Web Services, Google Cloud Platform, and Microsoft Azure.

Responses

Request samples

Content type
application/json
{
  • "providerName": "AWS",
  • "region": "string"
}

Response samples

Content type
application/json
Example
{
  • "cloudProvider": "AWS",
  • "endpointServiceName": "string",
  • "errorMessage": "string",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "interfaceEndpoints": [
    ],
  • "regionName": "string",
  • "status": "INITIATING"
}

Return Regionalized Private Endpoint Status

Checks whether each region in the specified cloud service provider can create multiple private endpoints per region. The cloud service provider manages the private endpoint for the project. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "enabled": true
}

Toggle Regionalized Private Endpoint Status

Enables or disables the ability to create multiple private endpoints per region in all cloud service providers in one project. The cloud service provider manages the private endpoints for the project. Connection strings to existing multi-region and global sharded clusters change when you enable this setting. You must update your applications to use the new connection strings. This might cause downtime. To use this resource, the requesting API Key must have the Project Owner role and all clusters in the deployment must be sharded clusters. Once enabled, you cannot create replica sets.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Enables or disables the ability to create multiple private endpoints per region in all cloud service providers in one project.

enabled
required
boolean

Flag that indicates whether someone enabled the regionalized private endpoint setting for the specified project.

  • Set this value to true to enable regionalized private endpoints. This allows you to create more than one private endpoint in a cloud provider region. You need to enable this setting to connect to multi-region and global MongoDB Cloud sharded clusters. Enabling regionalized private endpoints introduces the following limitations:

    • Your applications must use the new connection strings for existing multi-region and global sharded clusters. This might cause downtime.

    • Your MongoDB Cloud project can't contain replica sets nor can you create new replica sets in this project.

    • You can't disable this setting if you have:

      • more than one private endpoint in more than one region
      • more than one private endpoint in one region and one private endpoint in one or more regions.

  • Set this value to false to disable regionalized private endpoints.

Responses

Request samples

Content type
application/json
{
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "enabled": true
}

Return All Private Endpoint Services for One Provider

Returns the name, interfaces, and state of all private endpoint services for the specified cloud service provider. This cloud service provider manages the private endpoint service for the project. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

cloudProvider
required
string
Default: "AWS"
Enum: "AWS" "AZURE" "GCP"

Cloud service provider that manages this private endpoint service.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Remove One Private Endpoint Service for One Provider

Removes one private endpoint service from the specified project. This cloud service provider manages the private endpoint service that belongs to the project. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

cloudProvider
required
string
Default: "AWS"
Enum: "AWS" "AZURE" "GCP"

Cloud service provider that manages this private endpoint service.

endpointServiceId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the private endpoint service that you want to delete.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{ }

Return One Private Endpoint Service for One Provider

Returns the name, interfaces, and state of the specified private endpoint service from one project. The cloud service provider hosted this private endpoint service that belongs to the project. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

cloudProvider
required
string
Default: "AWS"
Enum: "AWS" "AZURE" "GCP"

Cloud service provider that manages this private endpoint service.

endpointServiceId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the private endpoint service that you want to return.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
Example
{
  • "cloudProvider": "AWS",
  • "endpointServiceName": "string",
  • "errorMessage": "string",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "interfaceEndpoints": [
    ],
  • "regionName": "string",
  • "status": "INITIATING"
}

Create One Private Endpoint for One Provider

Creates one private endpoint for the specified cloud service provider. This cloud service provider manages the private endpoint service, which in turn manages the private endpoints for the project. To use this resource, the requesting API Key must have the Project Owner role. To learn more about considerations, limitations, and prerequisites, see the MongoDB documentation for setting up a private endpoint.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

cloudProvider
required
string
Default: "AWS"
Enum: "AWS" "AZURE" "GCP"

Cloud service provider that manages this private endpoint.

endpointServiceId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the private endpoint service for which you want to create a private endpoint.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Creates one private endpoint for the specified cloud service provider.

One of
object AWS Recursive

Responses

Request samples

Content type
application/json
Example
{
  • "id": "vpce-3bf78b0ddee411ba1"
}

Response samples

Content type
application/json
Example
{
  • "cloudProvider": "AWS",
  • "connectionStatus": "PENDING_ACCEPTANCE",
  • "deleteRequested": true,
  • "errorMessage": "string",
  • "interfaceEndpointId": "32b6e34b3d91647abb20e7b8"
}

Remove One Private Endpoint for One Provider

Removes one private endpoint from the specified project and private endpoint service, as managed by the specified cloud service provider. When the last private endpoint is removed from a given private endpoint service, that private endpoint service is also removed. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

cloudProvider
required
string
Default: "AWS"
Enum: "AWS" "AZURE" "GCP"

Cloud service provider that manages this private endpoint.

endpointId
required
string^vpce-[0-9a-f]{17}|^%2[fF]subscriptions%2[fF]...

Unique string that identifies the private endpoint you want to delete. The format of the endpointId parameter differs for AWS and Azure. You must URL encode the endpointId for Azure private endpoints.

endpointServiceId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the private endpoint service from which you want to delete a private endpoint.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{ }

Return One Private Endpoint for One Provider

Returns the connection state of the specified private endpoint. The private endpoint service manages this private endpoint which belongs to one project hosted from one cloud service provider. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

cloudProvider
required
string
Default: "AWS"
Enum: "AWS" "AZURE" "GCP"

Cloud service provider that manages this private endpoint.

endpointId
required
string^vpce-[0-9a-f]{17}|^%2[fF]subscriptions%2[fF]...

Unique string that identifies the private endpoint you want to return. The format of the endpointId parameter differs for AWS and Azure. You must URL encode the endpointId for Azure private endpoints.

endpointServiceId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the private endpoint service for which you want to return a private endpoint.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
Example
{
  • "cloudProvider": "AWS",
  • "connectionStatus": "PENDING_ACCEPTANCE",
  • "deleteRequested": true,
  • "errorMessage": "string",
  • "interfaceEndpointId": "32b6e34b3d91647abb20e7b8"
}

Programmatic API Keys

Returns, adds, edits, and removes access tokens to use the MongoDB Cloud API. MongoDB Cloud applies these keys to organizations. These resources can return, assign, or revoke use of these keys within a specified project.

Return All Organization API Keys Assigned to One Project

Returns all organization API keys that you assigned to the specified project. Users with the Project Owner role in the project associated with the API key can use the organization API key to access the resources. To use this resource, the requesting API Key must have the Project Owner role.

Programmatic API Keys
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Create and Assign One Organization API Key to One Project

Creates and assigns the specified organization API key to the specified project. Users with the Project Owner role in the project associated with the API key can use the organization API key to access the resources. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Organization API key to be created and assigned to the specified project.

desc
required
string [ 1 .. 250 ] characters

Purpose or explanation provided when someone created this project API key.

roles
required
Array of strings non-empty
Items Enum: "ORG_OWNER" "ORG_MEMBER" "ORG_GROUP_CREATOR" "ORG_BILLING_ADMIN" "ORG_READ_ONLY" "ORG_TEAM_MEMBERS_ADMIN" "GROUP_ATLAS_ADMIN" "GROUP_AUTOMATION_ADMIN" "GROUP_BACKUP_ADMIN" "GROUP_MONITORING_ADMIN" "GROUP_OWNER" "GROUP_READ_ONLY" "GROUP_USER_ADMIN" "GROUP_BILLING_ADMIN" "GROUP_DATA_ACCESS_ADMIN" "GROUP_DATA_ACCESS_READ_ONLY" "GROUP_DATA_ACCESS_READ_WRITE" "GROUP_CHARTS_ADMIN" "GROUP_CLUSTER_MANAGER" "GROUP_SEARCH_INDEX_EDITOR" "GROUP_STREAM_PROCESSING_OWNER"

List of roles to grant this API key. If you provide this list, provide a minimum of one role and ensure each role applies to this project.

Responses

Request samples

Content type
application/json
{
  • "desc": "string",
  • "roles": [
    ]
}

Response samples

Content type
application/json
{
  • "desc": "string",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "links": [],
  • "privateKey": "55c3bbb6-b4bb-0be1-e66d20841f3e",
  • "publicKey": "zmmrboas",
  • "roles": [
    ]
}

Unassign One Organization API Key from One Project

Removes one organization API key from the specified project. To use this resource, the requesting API Key must have the Project Owner role.

Programmatic API Keys
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

apiUserId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies this organization API key that you want to unassign from one project.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{ }

Update Roles of One Organization API Key to One Project

Updates the roles of the organization API key that you specify for the project that you specify. You must specify at least one valid role for the project. The application removes any roles that you do not include in this request if they were previously set in the organization API key that you specify for the project.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

apiUserId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies this organization API key that you want to unassign from one project.

query Parameters
pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Request Body schema: application/json

Organization API Key to be updated. This request requires a minimum of one of the two body parameters.

desc
string [ 1 .. 250 ] characters

Purpose or explanation provided when someone creates this project API key.

roles
Array of strings
Items Enum: "ORG_OWNER" "ORG_MEMBER" "ORG_GROUP_CREATOR" "ORG_BILLING_ADMIN" "ORG_READ_ONLY" "ORG_TEAM_MEMBERS_ADMIN" "GROUP_ATLAS_ADMIN" "GROUP_AUTOMATION_ADMIN" "GROUP_BACKUP_ADMIN" "GROUP_MONITORING_ADMIN" "GROUP_OWNER" "GROUP_READ_ONLY" "GROUP_USER_ADMIN" "GROUP_BILLING_ADMIN" "GROUP_DATA_ACCESS_ADMIN" "GROUP_DATA_ACCESS_READ_ONLY" "GROUP_DATA_ACCESS_READ_WRITE" "GROUP_CHARTS_ADMIN" "GROUP_CLUSTER_MANAGER" "GROUP_SEARCH_INDEX_EDITOR" "GROUP_STREAM_PROCESSING_OWNER"

List of roles to grant this API key. If you provide this list, provide a minimum of one role and ensure each role applies to this project.

Responses

Request samples

Content type
application/json
{
  • "desc": "string",
  • "roles": [
    ]
}

Response samples

Content type
application/json
{
  • "desc": "string",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "links": [],
  • "privateKey": "55c3bbb6-b4bb-0be1-e66d20841f3e",
  • "publicKey": "zmmrboas",
  • "roles": [
    ]
}

Assign One Organization API Key to One Project

Assigns the specified organization API key to the specified project. Users with the Project Owner role in the project associated with the API key can then use the organization API key to access the resources. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

apiUserId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies this organization API key that you want to assign to one project.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Organization API key to be assigned to the specified project.

Array
roles
Array of strings
Items Enum: "GROUP_CLUSTER_MANAGER" "GROUP_DATA_ACCESS_ADMIN" "GROUP_DATA_ACCESS_READ_ONLY" "GROUP_DATA_ACCESS_READ_WRITE" "GROUP_SEARCH_INDEX_EDITOR" "GROUP_STREAM_PROCESSING_OWNER" "GROUP_OWNER" "GROUP_READ_ONLY"

List of roles to grant this API key. If you provide this list, provide a minimum of one role and ensure each role applies to this project.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{ }

Return All Organization API Keys

Returns all organization API keys for the specified organization. The organization API keys grant programmatic access to an organization. You can't use the API key to log into MongoDB Cloud through the console. To use this resource, the requesting API Key must have the Organization Member role.

Programmatic API Keys
Authorizations:
DigestAuthServiceAccounts
path Parameters
orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Create One Organization API Key

Creates one API key for the specified organization. An organization API key grants programmatic access to an organization. You can't use the API key to log into the console. To use this resource, the requesting API Key must have the Organization Owner role.

Programmatic API Keys
Authorizations:
DigestAuthServiceAccounts
path Parameters
orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Organization API Key to be created.

desc
required
string [ 1 .. 250 ] characters

Purpose or explanation provided when someone created this organization API key.

roles
required
Array of strings non-empty
Items Enum: "ORG_OWNER" "ORG_MEMBER" "ORG_GROUP_CREATOR" "ORG_BILLING_ADMIN" "ORG_READ_ONLY" "ORG_TEAM_MEMBERS_ADMIN"

List of roles to grant this API key. If you provide this list, provide a minimum of one role and ensure each role applies to this organization.

Responses

Request samples

Content type
application/json
{
  • "desc": "string",
  • "roles": [
    ]
}

Response samples

Content type
application/json
{
  • "desc": "string",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "links": [],
  • "privateKey": "55c3bbb6-b4bb-0be1-e66d20841f3e",
  • "publicKey": "zmmrboas",
  • "roles": [
    ]
}

Remove One Organization API Key

Removes one organization API key from the specified organization. When you remove an API key from an organization, MongoDB Cloud also removes that key from any projects that use that key. To use this resource, the requesting API Key must have the Organization Owner role.

Configure Atlas API Access
Authorizations:
DigestAuthServiceAccounts
path Parameters
orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

apiUserId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies this organization API key.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{ }

Return One Organization API Key

Returns one organization API key. The organization API keys grant programmatic access to an organization. You can't use the API key to log into MongoDB Cloud through the user interface. To use this resource, the requesting API Key must have the Organization Member role.

Programmatic API Keys
Authorizations:
DigestAuthServiceAccounts
path Parameters
orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

apiUserId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies this organization API key that you want to update.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "desc": "string",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "links": [],
  • "privateKey": "55c3bbb6-b4bb-0be1-e66d20841f3e",
  • "publicKey": "zmmrboas",
  • "roles": [
    ]
}

Update One Organization API Key

Updates one organization API key in the specified organization. The organization API keys grant programmatic access to an organization. To use this resource, the requesting API Key must have the Organization Owner role.

Programmatic API Keys
Authorizations:
DigestAuthServiceAccounts
path Parameters
orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

apiUserId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies this organization API key you want to update.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Organization API key to be updated. This request requires a minimum of one of the two body parameters.

desc
string [ 1 .. 250 ] characters

Purpose or explanation provided when someone creates this organization API key.

roles
Array of strings
Items Enum: "ORG_OWNER" "ORG_MEMBER" "ORG_GROUP_CREATOR" "ORG_BILLING_ADMIN" "ORG_READ_ONLY" "ORG_TEAM_MEMBERS_ADMIN"

List of roles to grant this API key. If you provide this list, provide a minimum of one role and ensure each role applies to this organization.

Responses

Request samples

Content type
application/json
{
  • "desc": "string",
  • "roles": [
    ]
}

Response samples

Content type
application/json
{
  • "desc": "string",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "links": [],
  • "privateKey": "55c3bbb6-b4bb-0be1-e66d20841f3e",
  • "publicKey": "zmmrboas",
  • "roles": [
    ]
}

Return All Access List Entries for One Organization API Key

Returns all access list entries that you configured for the specified organization API key. To use this resource, the requesting API Key must have the Organization Member role.

Programmatic API Keys
Authorizations:
DigestAuthServiceAccounts
path Parameters
orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

apiUserId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies this organization API key for which you want to return access list entries.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{}

Create Access List Entries for One Organization API Key

Creates the access list entries for the specified organization API key. Resources require all API requests originate from IP addresses on the API access list. To use this resource, the requesting API Key must have the Read Write role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

apiUserId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies this organization API key for which you want to create a new access list entry.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Access list entries to be created for the specified organization API key.

Array
cidrBlock
string^((([0-9]{1,3}\.){3}[0-9]{1,3})|(:{0,2}([0-9a...

Range of network addresses that you want to add to the access list for the API key. This parameter requires the range to be expressed in classless inter-domain routing (CIDR) notation of Internet Protocol version 4 or version 6 addresses. You can set a value for this parameter or ipAddress but not both in the same request.

ipAddress
string^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)(\.(?!$)|$))...

Network address that you want to add to the access list for the API key. This parameter requires the address to be expressed as one Internet Protocol version 4 or version 6 address. You can set a value for this parameter or cidrBlock but not both in the same request.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{}

Remove One Access List Entry for One Organization API Key

Removes the specified access list entry from the specified organization API key. Resources require all API requests originate from the IP addresses on the API access list. To use this resource, the requesting API Key must have the Read Write role. In addition, you cannot remove the requesting IP address from the requesting organization API key.

Configure Atlas API Access
Authorizations:
DigestAuthServiceAccounts
path Parameters
orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

apiUserId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies this organization API key for which you want to remove access list entries.

ipAddress
required
string^([0-9]{1,3}\.){3}[0-9]{1,3}(%2[fF][0-9]{1,3}...
Example: 192.0.2.0%2F24

One IP address or multiple IP addresses represented as one CIDR block to limit requests to API resources in the specified organization. When adding a CIDR block with a subnet mask, such as 192.0.2.0/24, use the URL-encoded value %2F for the forward slash /.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{ }

Return One Access List Entry for One Organization API Key

Returns one access list entry for the specified organization API key. Resources require all API requests originate from IP addresses on the API access list. To use this resource, the requesting API Key must have the Organization Member role.

Configure Atlas API Access
Authorizations:
DigestAuthServiceAccounts
path Parameters
orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

ipAddress
required
string^([0-9]{1,3}\.){3}[0-9]{1,3}(%2[fF][0-9]{1,3}...
Example: 192.0.2.0%2F24

One IP address or multiple IP addresses represented as one CIDR block to limit requests to API resources in the specified organization. When adding a CIDR block with a subnet mask, such as 192.0.2.0/24, use the URL-encoded value %2F for the forward slash /.

apiUserId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies this organization API key for which you want to return access list entries.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "cidrBlock": "203.0.113.0/24",
  • "count": 1,
  • "created": "2019-08-24T14:15:22Z",
  • "ipAddress": "203.0.113.10",
  • "lastUsed": "2019-08-24T14:15:22Z",
  • "lastUsedAddress": "203.0.113.10",
  • "links": []
}

Project IP Access List

Returns, adds, edits, and removes network access limits to database deployments in Atlas. This resource replaces the whitelist resource. Atlas removed whitelists in July 2021. Update your applications to use this new resource. This resource manages a project's IP Access List and supports creating temporary Access List entries that automatically expire within a user-configurable 7-day period.

Return Project IP Access List

Returns all access list entries from the specified project's IP access list. Each entry in the project's IP access list contains either one IP address or one CIDR-notated block of IP addresses. MongoDB Cloud only allows client connections to the cluster from entries in the project's IP access list. To use this resource, the requesting API Key must have the Project Read Only or Project Charts Admin roles. This resource replaces the whitelist resource. MongoDB Cloud removed whitelists in July 2021. Update your applications to use this new resource. The /groups/{GROUP-ID}/accessList endpoint manages the database IP access list. This endpoint is distinct from the orgs/{ORG-ID}/apiKeys/{API-KEY-ID}/accesslist endpoint, which manages the access list for MongoDB Cloud organizations.

IP access list
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{}

Add Entries to Project IP Access List

Adds one or more access list entries to the specified project. MongoDB Cloud only allows client connections to the cluster from entries in the project's IP access list. Write each entry as either one IP address or one CIDR-notated block of IP addresses. To use this resource, the requesting API Key must have the Project Owner or Project Charts Admin roles. This resource replaces the whitelist resource. MongoDB Cloud removed whitelists in July 2021. Update your applications to use this new resource. The /groups/{GROUP-ID}/accessList endpoint manages the database IP access list. This endpoint is distinct from the orgs/{ORG-ID}/apiKeys/{API-KEY-ID}/accesslist endpoint, which manages the access list for MongoDB Cloud organizations. This endpoint doesn't support concurrent POST requests. You must submit multiple POST requests synchronously.

IP access list
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

One or more access list entries to add to the specified project.

Array
awsSecurityGroup
string^([0-9]*/)?sg-([0-9]*)

Unique string of the Amazon Web Services (AWS) security group that you want to add to the project's IP access list. Your IP access list entry can be one awsSecurityGroup, one cidrBlock, or one ipAddress. You must configure Virtual Private Connection (VPC) peering for your project before you can add an AWS security group to an IP access list. You cannot set AWS security groups as temporary access list entries. Don't set this parameter if you set cidrBlock or ipAddress.

cidrBlock
string^([0-9]{1,3}\.){3}[0-9]{1,3}(%2[fF][0-9]{1,3}...

Range of IP addresses in Classless Inter-Domain Routing (CIDR) notation that you want to add to the project's IP access list. Your IP access list entry can be one awsSecurityGroup, one cidrBlock, or one ipAddress. Don't set this parameter if you set awsSecurityGroup or ipAddress.

comment
string <= 80 characters

Remark that explains the purpose or scope of this IP access list entry.

deleteAfterDate
string <date-time>

Date and time after which MongoDB Cloud deletes the temporary access list entry. This parameter expresses its value in the ISO 8601 timestamp format in UTC and can include the time zone designation. The date must be later than the current date but no later than one week after you submit this request. The resource returns this parameter if you specified an expiration date when creating this IP access list entry.

ipAddress
string^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)(\.(?!$)|$))...

IP address that you want to add to the project's IP access list. Your IP access list entry can be one awsSecurityGroup, one cidrBlock, or one ipAddress. Don't set this parameter if you set awsSecurityGroup or cidrBlock.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{}

Remove One Entry from One Project IP Access List

Removes one access list entry from the specified project's IP access list. Each entry in the project's IP access list contains one IP address, one CIDR-notated block of IP addresses, or one AWS Security Group ID. MongoDB Cloud only allows client connections to the cluster from entries in the project's IP access list. To use this resource, the requesting API Key must have the Project Owner role. This resource replaces the whitelist resource. MongoDB Cloud removed whitelists in July 2021. Update your applications to use this new resource. The /groups/{GROUP-ID}/accessList endpoint manages the database IP access list. This endpoint is distinct from the orgs/{ORG-ID}/apiKeys/{API-KEY-ID}/accesslist endpoint, which manages the access list for MongoDB Cloud organizations.

IP access list
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

entryValue
required
string^([0-9]{1,3}\.){3}[0-9]{1,3}(%2[fF][0-9]{1,3}...
Example: IPv4: 192.0.2.0%2F24 or IPv6: 2001:db8:85a3:8d3:1319:8a2e:370:7348 or IPv4 CIDR: 198.51.100.0%2f24 or IPv6 CIDR: 2001:db8::%2f58 or AWS SG: sg-903004f8

Access list entry that you want to remove from the project's IP access list. This value can use one of the following: one AWS security group ID, one IP address, or one CIDR block of addresses. For CIDR blocks that use a subnet mask, replace the forward slash (/) with its URL-encoded value (%2F). When you remove an entry from the IP access list, existing connections from the removed address or addresses may remain open for a variable amount of time. The amount of time it takes MongoDB Cloud to close the connection depends upon several factors, including:

  • how your application established the connection,
  • how MongoDB Cloud or the driver using the address behaves, and
  • which protocol (like TCP or UDP) the connection uses.
query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{ }

Return One Project IP Access List Entry

Returns one access list entry from the specified project's IP access list. Each entry in the project's IP access list contains either one IP address or one CIDR-notated block of IP addresses. MongoDB Cloud only allows client connections to the cluster from entries in the project's IP access list. To use this resource, the requesting API Key must have the Project Read Only or Project Charts Admin roles. This resource replaces the whitelist resource. MongoDB Cloud removed whitelists in July 2021. Update your applications to use this new resource. This endpoint (/groups/{GROUP-ID}/accessList) manages the Project IP Access List. It doesn't manage the access list for MongoDB Cloud organizations. TheProgrammatic API Keys endpoint (/orgs/{ORG-ID}/apiKeys/{API-KEY-ID}/accesslist) manages those access lists.

IP access list
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

entryValue
required
string^([0-9]{1,3}\.){3}[0-9]{1,3}(%2[fF][0-9]{1,3}...
Example: IPv4: 192.0.2.0%2F24 or IPv6: 2001:db8:85a3:8d3:1319:8a2e:370:7348 or IPv4 CIDR: 198.51.100.0%2f24 or IPv6 CIDR: 2001:db8::%2f58 or AWS SG: sg-903004f8

Access list entry that you want to return from the project's IP access list. This value can use one of the following: one AWS security group ID, one IP address, or one CIDR block of addresses. For CIDR blocks that use a subnet mask, replace the forward slash (/) with its URL-encoded value (%2F).

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "awsSecurityGroup": "string",
  • "cidrBlock": "string",
  • "comment": "string",
  • "deleteAfterDate": "2019-08-24T14:15:22Z",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "ipAddress": "string",
  • "links": []
}

Return Status of One Project IP Access List Entry

Returns the status of one project IP access list entry. This resource checks if the provided project IP access list entry applies to all cloud providers serving clusters from the specified project.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

entryValue
required
string^([0-9]{1,3}\.){3}[0-9]{1,3}(%2[fF][0-9]{1,3}...
Example: IPv4: 192.0.2.0%2F24 or IPv6: 2001:db8:85a3:8d3:1319:8a2e:370:7348 or IPv4 CIDR: 198.51.100.0%2f24 or IPv6 CIDR: 2001:db8::%2f58 or AWS SG: sg-903004f8

Network address or cloud provider security construct that identifies which project access list entry to be verified.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "STATUS": "PENDING"
}

Projects

Returns, adds, and edits collections of clusters and users in MongoDB Cloud.

Return All Projects

Returns details about all projects. Projects group clusters into logical collections that support an application environment, workload, or both. Each project can have its own users, teams, security, tags, and alert settings. To use this resource, the requesting API Key must have the Organization Read Only role or higher.

Authorizations:
DigestAuthServiceAccounts
query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Create One Project

Creates one project. Projects group clusters into logical collections that support an application environment, workload, or both. Each project can have its own users, teams, security, tags, and alert settings. To use this resource, the requesting API Key must have the Read Write role.

Authorizations:
DigestAuthServiceAccounts
query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

projectOwnerId
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the MongoDB Cloud user to whom to grant the Project Owner role on the specified project. If you set this parameter, it overrides the default value of the oldest Organization Owner.

Request Body schema: application/json

Creates one project.

name
required
string [ 1 .. 64 ] characters ^[\p{L}\p{N}\-_.(),:&@+']{1,64}$

Human-readable label that identifies the project included in the MongoDB Cloud organization.

orgId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the MongoDB Cloud organization to which the project belongs.

regionUsageRestrictions
string
Default: "COMMERCIAL_FEDRAMP_REGIONS_ONLY"
Enum: "COMMERCIAL_FEDRAMP_REGIONS_ONLY" "GOV_REGIONS_ONLY"

Applies to Atlas for Government only.

In Commercial Atlas, this field will be rejected in requests and missing in responses.

This field sets restrictions on available regions in the project.

Value Available Regions
COMMERCIAL_FEDRAMP_REGIONS_ONLY Only allows deployments in FedRAMP Moderate regions.
GOV_REGIONS_ONLY Only allows deployments in GovCloud regions.
https://www.mongodb.com/docs/atlas/government/overview/supported-regions/#supported-cloud-providers-and-regions
Array of objects (Resource Tag)

List that contains key-value pairs between 1 to 255 characters in length for tagging and categorizing the project.

Resource Tags
withDefaultAlertsSettings
boolean
Default: true

Flag that indicates whether to create the project with default alert settings.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "orgId": "32b6e34b3d91647abb20e7b8",
  • "regionUsageRestrictions": "COMMERCIAL_FEDRAMP_REGIONS_ONLY",
  • "tags": [
    ],
  • "withDefaultAlertsSettings": true
}

Response samples

Content type
application/json
{
  • "clusterCount": 0,
  • "created": "2019-08-24T14:15:22Z",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "links": [],
  • "name": "string",
  • "orgId": "32b6e34b3d91647abb20e7b8",
  • "regionUsageRestrictions": "COMMERCIAL_FEDRAMP_REGIONS_ONLY",
  • "tags": [
    ]
}

Return One Project using Its Name

Returns details about the specified project. Projects group clusters into logical collections that support an application environment, workload, or both. Each project can have its own users, teams, security, tags, and alert settings. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupName
required
string [ 1 .. 64 ] characters

Human-readable label that identifies this project.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "clusterCount": 0,
  • "created": "2019-08-24T14:15:22Z",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "links": [],
  • "name": "string",
  • "orgId": "32b6e34b3d91647abb20e7b8",
  • "regionUsageRestrictions": "COMMERCIAL_FEDRAMP_REGIONS_ONLY",
  • "tags": [
    ]
}

Remove One Project

Removes the specified project. Projects group clusters into logical collections that support an application environment, workload, or both. Each project can have its own users, teams, security, tags, and alert settings. You can delete a project only if there are no Online Archives for the clusters in the project. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{ }

Return One Project

Returns details about the specified project. Projects group clusters into logical collections that support an application environment, workload, or both. Each project can have its own users, teams, security, tags, and alert settings. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "clusterCount": 0,
  • "created": "2019-08-24T14:15:22Z",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "links": [],
  • "name": "string",
  • "orgId": "32b6e34b3d91647abb20e7b8",
  • "regionUsageRestrictions": "COMMERCIAL_FEDRAMP_REGIONS_ONLY",
  • "tags": [
    ]
}

Update One Project

Updates the human-readable label that identifies the specified project, or the tags associated with the project. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Project to update.

name
string

Human-readable label that identifies the project included in the MongoDB Cloud organization.

Array of objects (Resource Tag)

List that contains key-value pairs between 1 to 255 characters in length for tagging and categorizing the project.

Resource Tags

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "clusterCount": 0,
  • "created": "2019-08-24T14:15:22Z",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "links": [],
  • "name": "string",
  • "orgId": "32b6e34b3d91647abb20e7b8",
  • "regionUsageRestrictions": "COMMERCIAL_FEDRAMP_REGIONS_ONLY",
  • "tags": [
    ]
}

Return All Project Invitations

Returns all pending invitations to the specified project. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

username
string <email>

Email address of the user account invited to this project.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update One Project Invitation

Updates the details of one pending invitation to the specified project. To specify which invitation to update, provide the username of the invited user. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Updates the details of one pending invitation to the specified project.

roles
Array of strings unique
Items Enum: "GROUP_CLUSTER_MANAGER" "GROUP_DATA_ACCESS_ADMIN" "GROUP_DATA_ACCESS_READ_ONLY" "GROUP_DATA_ACCESS_READ_WRITE" "GROUP_OWNER" "GROUP_READ_ONLY"

One or more project level roles to assign to the MongoDB Cloud user.

username
string <email>

Email address of the MongoDB Cloud user invited to the specified project.

Responses

Request samples

Content type
application/json
{
  • "roles": [
    ],
  • "username": "user@example.com"
}

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "groupName": "string",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "inviterUsername": "user@example.com",
  • "links": [],
  • "roles": [
    ],
  • "username": "user@example.com"
}

Invite One MongoDB Cloud User to Join One Project

Invites one MongoDB Cloud user to join the specified project. The MongoDB Cloud user must accept the invitation to access information within the specified project. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Request Body schema: application/json

Invites one MongoDB Cloud user to join the specified project.

roles
Array of strings unique
Items Enum: "GROUP_CLUSTER_MANAGER" "GROUP_DATA_ACCESS_ADMIN" "GROUP_DATA_ACCESS_READ_ONLY" "GROUP_DATA_ACCESS_READ_WRITE" "GROUP_OWNER" "GROUP_READ_ONLY"

One or more project level roles to assign to the MongoDB Cloud user.

username
string <email>

Email address of the MongoDB Cloud user invited to the specified project.

Responses

Request samples

Content type
application/json
{
  • "roles": [
    ],
  • "username": "user@example.com"
}

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "groupName": "string",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "inviterUsername": "user@example.com",
  • "links": [],
  • "roles": [
    ],
  • "username": "user@example.com"
}

Cancel One Project Invitation

Cancels one pending invitation sent to the specified MongoDB Cloud user to join a project. You can't cancel an invitation that the user accepted. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

invitationId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the invitation.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Responses

Response samples

Content type
application/json
{ }

Return One Project Invitation

Returns the details of one pending invitation to the specified project. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

invitationId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the invitation.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "groupName": "string",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "inviterUsername": "user@example.com",
  • "links": [],
  • "roles": [
    ],
  • "username": "user@example.com"
}

Update One Project Invitation by Invitation ID

Updates the details of one pending invitation to the specified project. To specify which invitation to update, provide the unique identification string for that invitation. Use the Return All Project Invitations endpoint to retrieve IDs for all pending project invitations. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

invitationId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the invitation.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Request Body schema: application/json

Updates the details of one pending invitation to the specified project.

roles
Array of strings unique
Items Enum: "GROUP_CLUSTER_MANAGER" "GROUP_DATA_ACCESS_ADMIN" "GROUP_DATA_ACCESS_READ_ONLY" "GROUP_DATA_ACCESS_READ_WRITE" "GROUP_OWNER" "GROUP_READ_ONLY"

One or more organization or project level roles to assign to the MongoDB Cloud user.

Responses

Request samples

Content type
application/json
{
  • "roles": [
    ]
}

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "groupName": "string",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "inviterUsername": "user@example.com",
  • "links": [],
  • "roles": [
    ],
  • "username": "user@example.com"
}

Return All Limits for One Project

Returns all the limits for the specified project. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Remove One Project Limit

Removes the specified project limit. Depending on the limit, Atlas either resets the limit to its default value or removes the limit entirely. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
limitName
required
string
Enum: "atlas.project.security.databaseAccess.users" "atlas.project.deployment.clusters" "atlas.project.deployment.serverlessMTMs" "atlas.project.security.databaseAccess.customRoles" "atlas.project.security.networkAccess.entries" "atlas.project.security.networkAccess.crossRegionEntries" "atlas.project.deployment.nodesPerPrivateLinkRegion" "dataFederation.bytesProcessed.query" "dataFederation.bytesProcessed.daily" "dataFederation.bytesProcessed.weekly" "dataFederation.bytesProcessed.monthly" "atlas.project.deployment.privateServiceConnectionsPerRegionGroup" "atlas.project.deployment.privateServiceConnectionsSubnetMask" "atlas.project.deployment.salesSoldM0s"

Human-readable label that identifies this project limit.

Limit Name Description Default API Override Limit
atlas.project.deployment.clusters Limit on the number of clusters in this project if the org is not sales-sold (If org is sales-sold, the limit is 100) 25 90
atlas.project.deployment.nodesPerPrivateLinkRegion Limit on the number of nodes per Private Link region in this project 50 90
atlas.project.security.databaseAccess.customRoles Limit on the number of custom roles in this project 100 1400
atlas.project.security.databaseAccess.users Limit on the number of database users in this project 100 900
atlas.project.security.networkAccess.crossRegionEntries Limit on the number of cross-region network access entries in this project 40 220
atlas.project.security.networkAccess.entries Limit on the number of network access entries in this project 200 20
dataFederation.bytesProcessed.query Limit on the number of bytes processed during a single Data Federation query N/A N/A
dataFederation.bytesProcessed.daily Limit on the number of bytes processed across all Data Federation tenants for the current day N/A N/A
dataFederation.bytesProcessed.weekly Limit on the number of bytes processed across all Data Federation tenants for the current week N/A N/A
dataFederation.bytesProcessed.monthly Limit on the number of bytes processed across all Data Federation tenants for the current month N/A N/A
atlas.project.deployment.privateServiceConnectionsPerRegionGroup Number of Private Service Connections per Region Group 50 100
atlas.project.deployment.privateServiceConnectionsSubnetMask Subnet mask for GCP PSC Networks. Has lower limit of 20. 27 27
atlas.project.deployment.salesSoldM0s Limit on the number of M0 clusters in this project if the org is sales-sold 100 100
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{ }

Return One Limit for One Project

Returns the specified limit for the specified project. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
limitName
required
string
Enum: "atlas.project.security.databaseAccess.users" "atlas.project.deployment.clusters" "atlas.project.deployment.serverlessMTMs" "atlas.project.security.databaseAccess.customRoles" "atlas.project.security.networkAccess.entries" "atlas.project.security.networkAccess.crossRegionEntries" "atlas.project.deployment.nodesPerPrivateLinkRegion" "dataFederation.bytesProcessed.query" "dataFederation.bytesProcessed.daily" "dataFederation.bytesProcessed.weekly" "dataFederation.bytesProcessed.monthly" "atlas.project.deployment.privateServiceConnectionsPerRegionGroup" "atlas.project.deployment.privateServiceConnectionsSubnetMask" "atlas.project.deployment.salesSoldM0s"

Human-readable label that identifies this project limit.

Limit Name Description Default API Override Limit
atlas.project.deployment.clusters Limit on the number of clusters in this project if the org is not sales-sold (If org is sales-sold, the limit is 100) 25 90
atlas.project.deployment.nodesPerPrivateLinkRegion Limit on the number of nodes per Private Link region in this project 50 90
atlas.project.security.databaseAccess.customRoles Limit on the number of custom roles in this project 100 1400
atlas.project.security.databaseAccess.users Limit on the number of database users in this project 100 900
atlas.project.security.networkAccess.crossRegionEntries Limit on the number of cross-region network access entries in this project 40 220
atlas.project.security.networkAccess.entries Limit on the number of network access entries in this project 200 20
dataFederation.bytesProcessed.query Limit on the number of bytes processed during a single Data Federation query N/A N/A
dataFederation.bytesProcessed.daily Limit on the number of bytes processed across all Data Federation tenants for the current day N/A N/A
dataFederation.bytesProcessed.weekly Limit on the number of bytes processed across all Data Federation tenants for the current week N/A N/A
dataFederation.bytesProcessed.monthly Limit on the number of bytes processed across all Data Federation tenants for the current month N/A N/A
atlas.project.deployment.privateServiceConnectionsPerRegionGroup Number of Private Service Connections per Region Group 50 100
atlas.project.deployment.privateServiceConnectionsSubnetMask Subnet mask for GCP PSC Networks. Has lower limit of 20. 27 27
atlas.project.deployment.salesSoldM0s Limit on the number of M0 clusters in this project if the org is sales-sold 100 100
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
Example
{
  • "currentUsage": 0,
  • "defaultLimit": 0,
  • "maximumLimit": 0,
  • "name": "atlas.project.deployment.clusters",
  • "value": 0
}

Set One Project Limit

Sets the specified project limit. To use this resource, the requesting API Key must have the Project Owner role.

NOTE: Increasing the following configuration limits might lead to slower response times in the MongoDB Cloud UI or increased user management overhead leading to authentication or authorization re-architecture. If possible, we recommend that you create additional projects to gain access to more of these resources for a more sustainable growth pattern.

Authorizations:
DigestAuthServiceAccounts
path Parameters
limitName
required
string
Enum: "atlas.project.security.databaseAccess.users" "atlas.project.deployment.clusters" "atlas.project.deployment.serverlessMTMs" "atlas.project.security.databaseAccess.customRoles" "atlas.project.security.networkAccess.entries" "atlas.project.security.networkAccess.crossRegionEntries" "atlas.project.deployment.nodesPerPrivateLinkRegion" "dataFederation.bytesProcessed.query" "dataFederation.bytesProcessed.daily" "dataFederation.bytesProcessed.weekly" "dataFederation.bytesProcessed.monthly" "atlas.project.deployment.privateServiceConnectionsPerRegionGroup" "atlas.project.deployment.privateServiceConnectionsSubnetMask" "atlas.project.deployment.salesSoldM0s"

Human-readable label that identifies this project limit.

Limit Name Description Default API Override Limit
atlas.project.deployment.clusters Limit on the number of clusters in this project if the org is not sales-sold (If org is sales-sold, the limit is 100) 25 90
atlas.project.deployment.nodesPerPrivateLinkRegion Limit on the number of nodes per Private Link region in this project 50 90
atlas.project.security.databaseAccess.customRoles Limit on the number of custom roles in this project 100 1400
atlas.project.security.databaseAccess.users Limit on the number of database users in this project 100 900
atlas.project.security.networkAccess.crossRegionEntries Limit on the number of cross-region network access entries in this project 40 220
atlas.project.security.networkAccess.entries Limit on the number of network access entries in this project 200 20
dataFederation.bytesProcessed.query Limit on the number of bytes processed during a single Data Federation query N/A N/A
dataFederation.bytesProcessed.daily Limit on the number of bytes processed across all Data Federation tenants for the current day N/A N/A
dataFederation.bytesProcessed.weekly Limit on the number of bytes processed across all Data Federation tenants for the current week N/A N/A
dataFederation.bytesProcessed.monthly Limit on the number of bytes processed across all Data Federation tenants for the current month N/A N/A
atlas.project.deployment.privateServiceConnectionsPerRegionGroup Number of Private Service Connections per Region Group 50 100
atlas.project.deployment.privateServiceConnectionsSubnetMask Subnet mask for GCP PSC Networks. Has lower limit of 20. 27 27
atlas.project.deployment.salesSoldM0s Limit on the number of M0 clusters in this project if the org is sales-sold 100 100
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Limit to update.

value
required
integer <int64>

Amount to set the limit to.

Responses

Request samples

Content type
application/json
Example
{
  • "value": 0,
  • "name": "atlas.project.deployment.clusters"
}

Response samples

Content type
application/json
Example
{
  • "currentUsage": 0,
  • "defaultLimit": 0,
  • "maximumLimit": 0,
  • "name": "atlas.project.deployment.clusters",
  • "value": 0
}

Return One Project Settings

Returns details about the specified project's settings. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "isCollectDatabaseSpecificsStatisticsEnabled": true,
  • "isDataExplorerEnabled": true,
  • "isExtendedStorageSizesEnabled": true,
  • "isPerformanceAdvisorEnabled": true,
  • "isRealtimePerformancePanelEnabled": true,
  • "isSchemaAdvisorEnabled": true
}

Update One Project Settings

Updates the settings of the specified project. You can update any of the options available. MongoDB cloud only updates the options provided in the request. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Settings to update.

isCollectDatabaseSpecificsStatisticsEnabled
boolean

Flag that indicates whether to collect database-specific metrics for the specified project.

isDataExplorerEnabled
boolean

Flag that indicates whether to enable the Data Explorer for the specified project.

isExtendedStorageSizesEnabled
boolean

Flag that indicates whether to enable extended storage sizes for the specified project.

isPerformanceAdvisorEnabled
boolean

Flag that indicates whether to enable the Performance Advisor and Profiler for the specified project.

isRealtimePerformancePanelEnabled
boolean

Flag that indicates whether to enable the Real Time Performance Panel for the specified project.

isSchemaAdvisorEnabled
boolean

Flag that indicates whether to enable the Schema Advisor for the specified project.

Responses

Request samples

Content type
application/json
{
  • "isCollectDatabaseSpecificsStatisticsEnabled": true,
  • "isDataExplorerEnabled": true,
  • "isExtendedStorageSizesEnabled": true,
  • "isPerformanceAdvisorEnabled": true,
  • "isRealtimePerformancePanelEnabled": true,
  • "isSchemaAdvisorEnabled": true
}

Response samples

Content type
application/json
{
  • "isCollectDatabaseSpecificsStatisticsEnabled": true,
  • "isDataExplorerEnabled": true,
  • "isExtendedStorageSizesEnabled": true,
  • "isPerformanceAdvisorEnabled": true,
  • "isRealtimePerformancePanelEnabled": true,
  • "isSchemaAdvisorEnabled": true
}

Return All Users in One Project

Returns details about all users in the specified project. Users belong to an organization. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

flattenTeams
boolean
Default: false

Flag that indicates whether the returned list should include users who belong to a team with a role in this project. You might not have assigned the individual users a role in this project. If "flattenTeams" : false, this resource returns only users with a role in the project. If "flattenTeams" : true, this resource returns both users with roles in the project and users who belong to teams with roles in the project.

includeOrgUsers
boolean
Default: false

Flag that indicates whether the returned list should include users with implicit access to the project, the Organization Owner or Organization Read Only role. You might not have assigned the individual users a role in this project. If "includeOrgUsers": false, this resource returns only users with a role in the project. If "includeOrgUsers": true, this resource returns both users with roles in the project and users who have implicit access to the project through their organization role.

Responses

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Remove One User from One Project

Removes the specified user from the specified project. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

userId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal string that identifies MongoDB Cloud user you want to remove from the specified project. To return a application user's ID using their application username, use the Get All application users in One Project endpoint.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "detail": "(This is just an example, the exception may not be related to this endpoint) No provider AWS exists.",
  • "error": 400,
  • "errorCode": "VALIDATION_ERROR",
  • "reason": "Bad Request"
}

Rolling Index

Creates one index to a database deployment in a rolling manner. You can't create a rolling index on an M0 free cluster or M2/M5 shared cluster.

Create One Rolling Index

Creates an index on the cluster identified by its name in a rolling manner. Creating the index in this way allows index builds on one replica set member as a standalone at a time, starting with the secondary members. Creating indexes in this way requires at least one replica set election. To use this resource, the requesting API Key must have the Project Data Access Admin role.

Rolling Index Builds on Replica Sets
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster on which MongoDB Cloud creates an index.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Rolling index to create on the specified cluster.

object (Collation)

One or more settings that specify language-specific rules to compare strings within this index.

Collation Options
collection
required
string

Human-readable label of the collection for which MongoDB Cloud creates an index.

db
required
string

Human-readable label of the database that holds the collection on which MongoDB Cloud creates an index.

Array of objects[ items = 1 properties ]

List that contains one or more objects that describe the parameters that you want to index.

object (IndexOptions)

One or more settings that determine how the MongoDB Cloud creates this MongoDB index.

Index Options

Responses

Request samples

Content type
application/json
Example

2dspere Index

{
  • "collation": {
    },
  • "collection": "accounts",
  • "db": "sample_airbnb",
  • "keys": [
    ],
  • "options": {
    }
}

Response samples

Content type
application/json
{
  • "detail": "(This is just an example, the exception may not be related to this endpoint) No provider AWS exists.",
  • "error": 400,
  • "errorCode": "VALIDATION_ERROR",
  • "reason": "Bad Request"
}

Root

Returns details that describe the MongoDB Cloud build and the access token that requests this resource. This starts the MongoDB Cloud API.

Return the status of this MongoDB application

This resource returns information about the MongoDB application along with API key meta data.

Authorizations:
DigestAuthServiceAccounts
query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "apiKey": {
    },
  • "appName": "MongoDB Atlas",
  • "build": "83be55e140f493c88e7f578aae96548dd881587b",
  • "links": [],
  • "throttling": true
}

Serverless Instances

Returns, adds, edits, and removes serverless instances.

Return All Serverless Instances from One Project

Returns details for all serverless instances in the specified project. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Create One Serverless Instance in One Project

Creates one serverless instance in the specified project. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Create One Serverless Instance in One Project.

name
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the serverless instance.

required
object (Cloud Service Provider Settings for a Serverless Instance)

Group of cloud provider settings that configure the provisioned MongoDB serverless instance.

object (Serverless Backup Options)

Group of settings that configure serverless backup.

Array of objects (Resource Tag)

List that contains key-value pairs between 1 to 255 characters in length for tagging and categorizing the serverless instance.

terminationProtectionEnabled
boolean
Default: false

Flag that indicates whether termination protection is enabled on the serverless instance. If set to true, MongoDB Cloud won't delete the serverless instance. If set to false, MongoDB Cloud will delete the serverless instance.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "providerSettings": {
    },
  • "serverlessBackupOptions": {
    },
  • "tags": [
    ],
  • "terminationProtectionEnabled": false
}

Response samples

Content type
application/json
{
  • "connectionStrings": {
    },
  • "createDate": "2019-08-24T14:15:22Z",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "links": [],
  • "mongoDBVersion": "string",
  • "name": "string",
  • "providerSettings": {
    },
  • "serverlessBackupOptions": {
    },
  • "stateName": "IDLE",
  • "tags": [
    ],
  • "terminationProtectionEnabled": false
}

Remove One Serverless Instance from One Project

Removes one serverless instance from the specified project. The serverless instance must have termination protection disabled in order to be deleted. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

name
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the serverless instance.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{ }

Return One Serverless Instance from One Project

Returns details for one serverless instance in the specified project. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

name
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the serverless instance.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "connectionStrings": {
    },
  • "createDate": "2019-08-24T14:15:22Z",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "links": [],
  • "mongoDBVersion": "string",
  • "name": "string",
  • "providerSettings": {
    },
  • "serverlessBackupOptions": {
    },
  • "stateName": "IDLE",
  • "tags": [
    ],
  • "terminationProtectionEnabled": false
}

Update One Serverless Instance in One Project

Updates one serverless instance in the specified project. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

name
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the serverless instance.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Update One Serverless Instance in One Project.

object (Serverless Backup Options)

Group of settings that configure serverless backup.

Array of objects (Resource Tag)

List that contains key-value pairs between 1 to 255 characters in length for tagging and categorizing the serverless instance.

terminationProtectionEnabled
boolean
Default: false

Flag that indicates whether termination protection is enabled on the serverless instance. If set to true, MongoDB Cloud won't delete the serverless instance. If set to false, MongoDB Cloud will delete the serverless instance.

Responses

Request samples

Content type
application/json
{
  • "serverlessBackupOptions": {
    },
  • "tags": [
    ],
  • "terminationProtectionEnabled": false
}

Response samples

Content type
application/json
{
  • "connectionStrings": {
    },
  • "createDate": "2019-08-24T14:15:22Z",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "links": [],
  • "mongoDBVersion": "string",
  • "name": "string",
  • "providerSettings": {
    },
  • "serverlessBackupOptions": {
    },
  • "stateName": "IDLE",
  • "tags": [
    ],
  • "terminationProtectionEnabled": false
}

Serverless Private Endpoints

Returns, adds, edits, and removes private endpoints for serverless instances. To learn more, see the Atlas Administration API tab on the following tutorial.

Set Up a Private Endpoint for a Serverless Instance Tutorial

Return All Private Endpoints for One Serverless Instance

Returns all private endpoints for one serverless instance. You must have at least the Project Read Only role for the project to successfully call this resource.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

instanceName
required
string <= 64 characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the serverless instance associated with the tenant endpoint.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create One Private Endpoint for One Serverless Instance

Creates one private endpoint for one serverless instance. To use this resource, the requesting API Key must have the Project Owner role.

A new endpoint won't be immediately available after creation. Read the steps in the linked tutorial for detailed guidance.

Set Up a Private Endpoint for a Serverless Instance Tutorial
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

instanceName
required
string <= 64 characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the serverless instance for which the tenant endpoint will be created.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Request Body schema: application/json

Information about the Private Endpoint to create for the Serverless Instance.

comment
string <= 80 characters

Human-readable comment associated with the private endpoint.

Responses

Request samples

Content type
application/json
{
  • "comment": "string"
}

Response samples

Content type
application/json
Example
{
  • "_id": "32b6e34b3d91647abb20e7b8",
  • "cloudProviderEndpointId": "string",
  • "comment": "string",
  • "endpointServiceName": "string",
  • "errorMessage": "string",
  • "providerName": "AWS",
  • "status": "RESERVATION_REQUESTED"
}

Remove One Private Endpoint for One Serverless Instance

Remove one private endpoint from one serverless instance. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

instanceName
required
string <= 64 characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the serverless instance from which the tenant endpoint will be removed.

endpointId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the tenant endpoint which will be removed.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Responses

Response samples

Content type
application/json
{ }

Return One Private Endpoint for One Serverless Instance

Return one private endpoint for one serverless instance. Identify this endpoint using its unique ID. You must have at least the Project Read Only role for the project to successfully call this resource.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

instanceName
required
string <= 64 characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the serverless instance associated with the tenant endpoint.

endpointId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the tenant endpoint.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Responses

Response samples

Content type
application/json
Example
{
  • "_id": "32b6e34b3d91647abb20e7b8",
  • "cloudProviderEndpointId": "string",
  • "comment": "string",
  • "endpointServiceName": "string",
  • "errorMessage": "string",
  • "providerName": "AWS",
  • "status": "RESERVATION_REQUESTED"
}

Update One Private Endpoint for One Serverless Instance

Updates one private endpoint for one serverless instance. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

instanceName
required
string <= 64 characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the serverless instance associated with the tenant endpoint that will be updated.

endpointId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the tenant endpoint which will be updated.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Request Body schema: application/json

Object used for update.

comment
string <= 80 characters

Human-readable comment associated with the private endpoint.

providerName
required
string

Human-readable label that identifies the cloud provider of the tenant endpoint.

cloudProviderEndpointId
string^vpce-[0-9a-f]{17}$

Unique string that identifies the private endpoint's network interface.

Responses

Request samples

Content type
application/json
Example
{
  • "comment": "string",
  • "providerName": "AWS",
  • "cloudProviderEndpointId": "string"
}

Response samples

Content type
application/json
Example
{
  • "_id": "32b6e34b3d91647abb20e7b8",
  • "cloudProviderEndpointId": "string",
  • "comment": "string",
  • "endpointServiceName": "string",
  • "errorMessage": "string",
  • "providerName": "AWS",
  • "status": "RESERVATION_REQUESTED"
}

Shared-Tier Restore Jobs

Returns and adds restore jobs for shared-tier database deployments.

Create One Restore Job from One M2 or M5 Cluster

Restores the specified cluster. MongoDB Cloud limits which clusters can be the target clusters of a restore. The target cluster can't use encryption at rest, run a major release MongoDB version different than the snapshot, or receive client requests during restores. MongoDB Cloud deletes all existing data on the target cluster prior to the restore operation. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster.

groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

The restore job details.

snapshotId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the snapshot to restore.

targetDeploymentItemName
required
string [ 1 .. 64 ] characters ^[\p{L}\p{N}\-_.(),:&@+']{1,64}$

Human-readable label that identifies the cluster on the target project to which you want to restore the snapshot. You can restore the snapshot to a cluster tier M2 or greater.

targetProjectId
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the project that contains the cluster to which you want to restore the snapshot.

Responses

Request samples

Content type
application/json
{
  • "snapshotId": "32b6e34b3d91647abb20e7b8",
  • "targetDeploymentItemName": "string",
  • "targetProjectId": "32b6e34b3d91647abb20e7b8"
}

Response samples

Content type
application/json
{
  • "clusterName": "string",
  • "deliveryType": "RESTORE",
  • "expirationDate": "2019-08-24T14:15:22Z",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "links": [],
  • "projectId": "32b6e34b3d91647abb20e7b8",
  • "restoreFinishedDate": "2019-08-24T14:15:22Z",
  • "restoreScheduledDate": "2019-08-24T14:15:22Z",
  • "snapshotFinishedDate": "2019-08-24T14:15:22Z",
  • "snapshotId": "32b6e34b3d91647abb20e7b8",
  • "snapshotUrl": "string",
  • "status": "PENDING",
  • "targetDeploymentItemName": "string",
  • "targetProjectId": "32b6e34b3d91647abb20e7b8"
}

Return All Restore Jobs for One M2 or M5 Cluster

Returns all restore jobs for the specified M2 or M5 cluster. Restore jobs restore a cluster using a snapshot. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster.

groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Return One Restore Job for One M2 or M5 Cluster

Returns the specified restore job. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster.

groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

restoreId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the restore job to return.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "clusterName": "string",
  • "deliveryType": "RESTORE",
  • "expirationDate": "2019-08-24T14:15:22Z",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "links": [],
  • "projectId": "32b6e34b3d91647abb20e7b8",
  • "restoreFinishedDate": "2019-08-24T14:15:22Z",
  • "restoreScheduledDate": "2019-08-24T14:15:22Z",
  • "snapshotFinishedDate": "2019-08-24T14:15:22Z",
  • "snapshotId": "32b6e34b3d91647abb20e7b8",
  • "snapshotUrl": "string",
  • "status": "PENDING",
  • "targetDeploymentItemName": "string",
  • "targetProjectId": "32b6e34b3d91647abb20e7b8"
}

Shared-Tier Snapshots

Returns and requests to download shared-tier database deployment snapshots.

Download One M2 or M5 Cluster Snapshot

Requests one snapshot for the specified shared cluster. This resource returns a snapshotURL that you can use to download the snapshot. This snapshotURL remains active for four hours after you make the request. To use this resource, the requesting API Key must have the Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster.

groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Snapshot to be downloaded.

snapshotId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the snapshot to restore.

targetDeploymentItemName
required
string [ 1 .. 64 ] characters ^[\p{L}\p{N}\-_.(),:&@+']{1,64}$

Human-readable label that identifies the cluster on the target project to which you want to restore the snapshot. You can restore the snapshot to a cluster tier M2 or greater.

targetProjectId
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the project that contains the cluster to which you want to restore the snapshot.

Responses

Request samples

Content type
application/json
{
  • "snapshotId": "32b6e34b3d91647abb20e7b8",
  • "targetDeploymentItemName": "string",
  • "targetProjectId": "32b6e34b3d91647abb20e7b8"
}

Response samples

Content type
application/json
{
  • "clusterName": "string",
  • "deliveryType": "RESTORE",
  • "expirationDate": "2019-08-24T14:15:22Z",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "links": [],
  • "projectId": "32b6e34b3d91647abb20e7b8",
  • "restoreFinishedDate": "2019-08-24T14:15:22Z",
  • "restoreScheduledDate": "2019-08-24T14:15:22Z",
  • "snapshotFinishedDate": "2019-08-24T14:15:22Z",
  • "snapshotId": "32b6e34b3d91647abb20e7b8",
  • "snapshotUrl": "string",
  • "status": "PENDING",
  • "targetDeploymentItemName": "string",
  • "targetProjectId": "32b6e34b3d91647abb20e7b8"
}

Return All Snapshots for One M2 or M5 Cluster

Returns details for all snapshots for the specified shared cluster. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Return One Snapshot for One M2 or M5 Cluster

Returns details for one snapshot for the specified shared cluster. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

clusterName
required
string [ 1 .. 64 ] characters ^([a-zA-Z0-9][a-zA-Z0-9-]*)?[a-zA-Z0-9]+$

Human-readable label that identifies the cluster.

snapshotId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the desired snapshot.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "expiration": "2019-08-24T14:15:22Z",
  • "finishTime": "2019-08-24T14:15:22Z",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "links": [],
  • "mongoDBVersion": "string",
  • "scheduledTime": "2019-08-24T14:15:22Z",
  • "startTime": "2019-08-24T14:15:22Z",
  • "status": "PENDING"
}

Teams

Returns, adds, edits, or removes teams.

Return All Teams in One Project

Returns all teams to which the authenticated user has access in the project specified using its unique 24-hexadecimal digit identifier. All members of the team share the same project access. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

Responses

Response samples

Content type
application/json
{}

Add One or More Teams to One Project

Adds one team to the specified project. All members of the team share the same project access. MongoDB Cloud limits the number of users to a maximum of 100 teams per project and a maximum of 250 teams per organization. To use this resource, the requesting API Key must have the Project Owner role.

Manage Organization Teams
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Team to add to the specified project.

Array
roleNames
Array of strings unique
Items Enum: "GROUP_CLUSTER_MANAGER" "GROUP_DATA_ACCESS_ADMIN" "GROUP_DATA_ACCESS_READ_ONLY" "GROUP_DATA_ACCESS_READ_WRITE" "GROUP_OWNER" "GROUP_READ_ONLY"

One or more organization- or project-level roles to assign to the MongoDB Cloud user.

teamId
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal character string that identifies the team.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{}

Remove One Team from One Project

Removes one team specified using its unique 24-hexadecimal digit identifier from the project specified using its unique 24-hexadecimal digit identifier. To use this resource, the requesting API Key must have the Project Owner role.

Manage Organization Teams
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

teamId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the team that you want to remove from the specified project.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Responses

Response samples

Content type
application/json
{
  • "detail": "(This is just an example, the exception may not be related to this endpoint) No provider AWS exists.",
  • "error": 400,
  • "errorCode": "VALIDATION_ERROR",
  • "reason": "Bad Request"
}

Update Team Roles in One Project

Updates the project roles assigned to the specified team. You can grant team roles for specific projects and grant project access roles to users in the team. All members of the team share the same project access. To use this resource, the requesting API Key must have the Project Owner role.

Manage Organization Teams
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

teamId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the team for which you want to update roles.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

The project roles assigned to the specified team.

roleNames
Array of strings unique
Items Enum: "GROUP_CLUSTER_MANAGER" "GROUP_DATA_ACCESS_ADMIN" "GROUP_DATA_ACCESS_READ_ONLY" "GROUP_DATA_ACCESS_READ_WRITE" "GROUP_OWNER" "GROUP_READ_ONLY"

One or more organization- or project-level roles to assign to the MongoDB Cloud user.

teamId
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal character string that identifies the team.

Responses

Request samples

Content type
application/json
{
  • "roleNames": [
    ],
  • "teamId": "32b6e34b3d91647abb20e7b8"
}

Response samples

Content type
application/json
{}

Return All Teams in One Organization

Returns all teams that belong to the specified organization. Teams enable you to grant project access roles to MongoDB Cloud users. MongoDB Cloud only returns teams for which you have access. To use this resource, the requesting API Key must have the Organization Member role.

Manage Organization Teams
Authorizations:
DigestAuthServiceAccounts
path Parameters
orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{}

Create One Team in One Organization

Creates one team in the specified organization. Teams enable you to grant project access roles to MongoDB Cloud users. MongoDB Cloud limits the number of teams to a maximum of 250 teams per organization. To use this resource, the requesting API Key must have the Organization Owner role.

Manage Organization Teams
Authorizations:
DigestAuthServiceAccounts
path Parameters
orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Team that you want to create in the specified organization.

name
required
string

Human-readable label that identifies the team.

usernames
Array of strings <email> unique

List that contains the MongoDB Cloud users in this team.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "usernames": [
    ]
}

Response samples

Content type
application/json
{}

Return One Team using its Name

Returns one team that you identified using its human-readable name. This team belongs to one organization. Teams enable you to grant project access roles to MongoDB Cloud users. To use this resource, the requesting API Key must have the Organization Member role.

Manage Organization Teams
Authorizations:
DigestAuthServiceAccounts
path Parameters
orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

teamName
required
string

Name of the team whose information you want to return.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{}

Remove One Team from One Organization

Removes one team specified using its unique 24-hexadecimal digit identifier from the organization specified using its unique 24-hexadecimal digit identifier. To use this resource, the requesting API Key must have the Organization Owner role.

Manage Organization Teams
Authorizations:
DigestAuthServiceAccounts
path Parameters
orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

teamId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the team that you want to delete.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{ }

Return One Team using its ID

Returns one team that you identified using its unique 24-hexadecimal digit ID. This team belongs to one organization. Teams enable you to grant project access roles to MongoDB Cloud users. To use this resource, the requesting API Key must have the Organization Member role.

Manage Organization Teams
Authorizations:
DigestAuthServiceAccounts
path Parameters
orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

teamId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the team whose information you want to return.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{}

Rename One Team

Renames one team in the specified organization. Teams enable you to grant project access roles to MongoDB Cloud users. To use this resource, the requesting API Key must have the Organization Owner role.

Manage Organization Teams
Authorizations:
DigestAuthServiceAccounts
path Parameters
orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

teamId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the team that you want to rename.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Details to update on the specified team.

name
required
string

Human-readable label that identifies the team.

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{}

Return All MongoDB Cloud Users Assigned to One Team

Returns all MongoDB Cloud users assigned to the team specified using its unique 24-hexadecimal digit identifier. This team belongs to one organization. Teams enable you to grant project access roles to MongoDB Cloud users. To use this resource, the requesting API Key must have the Organization Member role.

Manage Organization Teams
Authorizations:
DigestAuthServiceAccounts
path Parameters
orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

teamId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the team whose application users you want to return.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Assign MongoDB Cloud Users from One Organization to One Team

Adds one or more MongoDB Cloud users from the specified organization to the specified team. Teams enable you to grant project access roles to MongoDB Cloud users. You can assign up to 250 MongoDB Cloud users from one organization to one team. To use this resource, the requesting API Key must have the Organization Owner role.

Manage Organization Teams
Authorizations:
DigestAuthServiceAccounts
path Parameters
orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

teamId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal character string that identifies the team to which you want to add MongoDB Cloud users.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

One or more MongoDB Cloud users that you want to add to the specified team.

Array
id
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the MongoDB Cloud user.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Remove One MongoDB Cloud User from One Team

Removes one MongoDB Cloud user from the specified team. This team belongs to one organization. Teams enable you to grant project access roles to MongoDB Cloud users. To use this resource, the requesting API Key must have the Organization Owner role.

Manage Organization Teams
Authorizations:
DigestAuthServiceAccounts
path Parameters
orgId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 4888442a3354817a7320eb61

Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

teamId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies the team from which you want to remove one database application user.

userId
required
string = 24 characters ^([a-f0-9]{24})$

Unique 24-hexadecimal digit string that identifies MongoDB Cloud user that you want to remove from the specified team.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "detail": "(This is just an example, the exception may not be related to this endpoint) No provider AWS exists.",
  • "error": 400,
  • "errorCode": "VALIDATION_ERROR",
  • "reason": "Bad Request"
}

Third-Party Integrations

Returns, adds, edits, and removes third-party service integration configurations. MongoDB Cloud sends alerts to each third-party service that you configure.

IMPORTANT: Each project can only have one configuration per integrationType.

Return All Active Third-Party Service Integrations

Returns the settings that permit integrations with all configured third-party services. These settings apply to all databases managed in one MongoDB Cloud project. To use this resource, the requesting API Key must have the Organization Owner or Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{}

Remove One Third-Party Service Integration

Removes the settings that permit configuring one third-party service integration. These settings apply to all databases managed in one MongoDB Cloud project. If you delete an integration from a project, you remove that integration configuration only for that project. This action doesn't affect any other project or organization's configured {INTEGRATION-TYPE} integrations. To use this resource, the requesting API Key must have the Organization Owner or Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
integrationType
required
string (Integration Type)
Enum: "PAGER_DUTY" "SLACK" "DATADOG" "NEW_RELIC" "OPS_GENIE" "VICTOR_OPS" "WEBHOOK" "HIP_CHAT" "PROMETHEUS" "MICROSOFT_TEAMS"

Human-readable label that identifies the service which you want to integrate with MongoDB Cloud.

groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{ }

Return One Third-Party Service Integration

Returns the settings for configuring integration with one third-party service. These settings apply to all databases managed in one MongoDB Cloud project. To use this resource, the requesting API Key must have the Organization Owner or Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

integrationType
required
string (Integration Type)
Enum: "PAGER_DUTY" "SLACK" "DATADOG" "NEW_RELIC" "OPS_GENIE" "VICTOR_OPS" "WEBHOOK" "HIP_CHAT" "PROMETHEUS" "MICROSOFT_TEAMS"

Human-readable label that identifies the service which you want to integrate with MongoDB Cloud.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
Example
{
  • "apiKey": "****************************a23c",
  • "id": "string",
  • "region": "US",
  • "type": "DATADOG"
}

Configure One Third-Party Service Integration

Adds the settings for configuring one third-party service integration. These settings apply to all databases managed in the specified MongoDB Cloud project. Each project can have only one configuration per {INTEGRATION-TYPE}. To use this resource, the requesting API Key must have the Organization Owner or Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
integrationType
required
string (Integration Type)
Enum: "PAGER_DUTY" "SLACK" "DATADOG" "NEW_RELIC" "OPS_GENIE" "VICTOR_OPS" "WEBHOOK" "HIP_CHAT" "PROMETHEUS" "MICROSOFT_TEAMS"

Human-readable label that identifies the service which you want to integrate with MongoDB Cloud.

groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Third-party integration that you want to configure for your project.

apiKey
required
string

Key that allows MongoDB Cloud to access your Datadog account.

NOTE: After you create a notification which requires an API or integration key, the key appears partially redacted when you:

  • View or edit the alert through the Atlas UI.

  • Query the alert for the notification through the Atlas Administration API.

id
string or null

Integration id.

region
string
Enum: "US" "EU" "US3" "US5" "AP1" "US1_FED"

Two-letter code that indicates which regional URL MongoDB uses to access the Datadog API.

To learn more about Datadog's regions, see Datadog Sites.

type
string

Human-readable label that identifies the service to which you want to integrate with MongoDB Cloud. The value must match the third-party service integration type.

Responses

Request samples

Content type
application/json
Example
{
  • "apiKey": "****************************a23c",
  • "id": "string",
  • "region": "US",
  • "type": "DATADOG"
}

Response samples

Content type
application/json
{}

Update One Third-Party Service Integration

Updates the settings for configuring integration with one third-party service. These settings apply to all databases managed in one MongoDB Cloud project. To use this resource, the requesting API Key must have the Organization Owner or Project Owner role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
integrationType
required
string (Integration Type)
Enum: "PAGER_DUTY" "SLACK" "DATADOG" "NEW_RELIC" "OPS_GENIE" "VICTOR_OPS" "WEBHOOK" "HIP_CHAT" "PROMETHEUS" "MICROSOFT_TEAMS"

Human-readable label that identifies the service which you want to integrate with MongoDB Cloud.

groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Third-party integration that you want to configure for your project.

apiKey
required
string

Key that allows MongoDB Cloud to access your Datadog account.

NOTE: After you create a notification which requires an API or integration key, the key appears partially redacted when you:

  • View or edit the alert through the Atlas UI.

  • Query the alert for the notification through the Atlas Administration API.

id
string or null

Integration id.

region
string
Enum: "US" "EU" "US3" "US5" "AP1" "US1_FED"

Two-letter code that indicates which regional URL MongoDB uses to access the Datadog API.

To learn more about Datadog's regions, see Datadog Sites.

type
string

Human-readable label that identifies the service to which you want to integrate with MongoDB Cloud. The value must match the third-party service integration type.

Responses

Request samples

Content type
application/json
Example
{
  • "apiKey": "****************************a23c",
  • "id": "string",
  • "region": "US",
  • "type": "DATADOG"
}

Response samples

Content type
application/json
{}

X.509 Authentication

Returns, edits, and removes user-managed X.509 configurations. Also returns and generates MongoDB Cloud-managed X.509 certificates for database users. The following resources help manage database users who authenticate using X.509 certificates. You can manage these X.509 certificates or let MongoDB Cloud do it for you. If MongoDB Cloud manages your certificates, it also manages your Certificate Authority and can generate certificates for your database users. No additional X.509 configuration is required. If you manage your certificates, you must provide a Certificate Authority and generate certificates for your database users.

Self-Managed X.509 Certificates

Return All X.509 Certificates Assigned to One MongoDB User

Returns all unexpired X.509 certificates for the specified MongoDB user. This MongoDB user belongs to one project. Atlas manages these certificates and the MongoDB user. To use this resource, the requesting API Key must have the Project Read Only role.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

username
required
string

Human-readable label that represents the MongoDB database user account whose certificates you want to return.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

includeCount
boolean
Default: true
Example: includeCount=true

Flag that indicates whether the response returns the total number of items (totalCount) in the response.

itemsPerPage
integer [ 1 .. 500 ]
Default: 100
Example: itemsPerPage=100

Number of items that the response returns per page.

pageNum
integer >= 1
Default: 1
Example: pageNum=1

Number of the page that displays the current set of the total objects that the response returns.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Responses

Response samples

Content type
application/json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Create One X.509 Certificate for One MongoDB User

Generates one X.509 certificate for the specified MongoDB user. Atlas manages the certificate and MongoDB user that belong to one project. To use this resource, the requesting API Key must have the Project Owner role.

To get MongoDB Cloud to generate a managed certificate for a database user, set "x509Type" : "MANAGED" on the desired MongoDB Database User.

If you are managing your own Certificate Authority (CA) in Self-Managed X.509 mode, you must generate certificates for database users using your own CA.

Self-Managed X.509
Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

username
required
string

Human-readable label that represents the MongoDB database user account for whom to create a certificate.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

pretty
boolean
Default: false
Example: pretty=false

Flag that indicates whether the response body should be in the prettyprint format.

Request Body schema: application/json

Generates one X.509 certificate for the specified MongoDB user.

monthsUntilExpiration
integer <int32> <= 24
Default: 3

Number of months that the certificate remains valid until it expires.

Responses

Request samples

Content type
application/json
{
  • "monthsUntilExpiration": 3
}

Response samples

Content type
application/json
"string"

Disable Customer-Managed X.509

Clears the customer-managed X.509 settings on a project, including the uploaded Certificate Authority, which disables self-managed X.509.

Updating this configuration triggers a rolling restart of the database. You must have the Project Owner role to use this endpoint.

Authorizations:
DigestAuthServiceAccounts
path Parameters
groupId
required
string = 24 characters ^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

NOTE: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups.

query Parameters
envelope
boolean
Default: false
Example: envelope=false

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Responses

Response samples

Content type
application/json
{
  • "customerX509": {},
  • "ldap": {
    },
  • "links": []
}