MongoDB Atlas Administration API 2.0
  • 2025-03-12 (latest)
  • 2025-02-19
  • 2024-11-13
  • 2024-10-23
  • 2024-08-05
  • 2024-05-30
  • 2023-11-15
  • 2023-10-01
  • 2023-02-01
  • 2023-01-01
API docs by Redocly

MongoDB Atlas Administration API (2.0)

Resource Version 2025-03-12

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/vnd.atlas.2025-03-12+json" \
  -X GET "https://cloud.mongodb.com/api/atlas/v2/groups/{groupId}/dbAccessHistory/clusters/{clusterName}?pretty=true"

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

You can also explore the various endpoints available through the Atlas Administration API in MongoDB's Postman workspace.

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 or the Project Database Access Admin role.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[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/vnd.atlas.2023-01-01+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 or the Project Database Access Admin role.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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/vnd.atlas.2023-01-01+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/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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/vnd.atlas.2023-01-01+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 Data Protection 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/vnd.atlas.2023-01-01+json
Example
{
  • "enabled": false,
  • "eventTypeName": "CREDIT_CARD_ABOUT_TO_EXPIRE",
  • "matchers": [
    ],
  • "notifications": [
    ]
}

Response samples

Content type
application/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^([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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^([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/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^([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/vnd.atlas.2023-01-01+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/vnd.atlas.2023-01-01+json
{
  • "enabled": true
}

Response samples

Content type
application/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^([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/vnd.atlas.2023-01-01+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 Data Protection 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/vnd.atlas.2023-01-01+json
Example
{
  • "enabled": false,
  • "eventTypeName": "CREDIT_CARD_ABOUT_TO_EXPIRE",
  • "matchers": [
    ],
  • "notifications": [
    ]
}

Response samples

Content type
application/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^([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/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^([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/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^([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/vnd.atlas.2023-01-01+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. Deprecated versions: v2-{2023-01-01}

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^([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/vnd.atlas.2024-05-30+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.

ISO 8601
acknowledgementComment
string <= 200 characters

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

unacknowledgeAlert
boolean

Flag that indicates to unacknowledge a previously acknowledged alert. By default this value is set to false. If set to true, it will override the acknowledgedUntil parameter.

Responses

Request samples

Content type
application/vnd.atlas.2024-05-30+json
{
  • "acknowledgedUntil": "2019-08-24T14:15:22Z",
  • "acknowledgementComment": "Expiration on 3/19. Silencing for 7days.",
  • "unacknowledgeAlert": true
}

Response samples

Content type
application/vnd.atlas.2024-05-30+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"
}

Create One Atlas Search Index Deprecated

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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[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/vnd.atlas.2023-01-01+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.

numPartitions
integer <int32>
Default: 1

Number of index partitions. Note: This feature is currently in preview.

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/vnd.atlas.2023-01-01+json
Example
{
  • "collectionName": "string",
  • "database": "string",
  • "name": "string",
  • "numPartitions": 1,
  • "type": "search",
  • "analyzer": "lucene.standard",
  • "analyzers": [
    ],
  • "mappings": {
    },
  • "searchAnalyzer": "lucene.standard",
  • "storedSource": {
    },
  • "synonyms": [
    ]
}

Response samples

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

Return All Atlas Search Indexes for One Collection Deprecated

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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[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/vnd.atlas.2023-01-01+json
[
  • {
    }
]

Remove One Atlas Search Index Deprecated

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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[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^([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/vnd.atlas.2023-01-01+json
{ }

Return One Atlas Search Index Deprecated

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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[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^([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/vnd.atlas.2023-01-01+json
Example
{
  • "collectionName": "string",
  • "database": "string",
  • "indexID": "32b6e34b3d91647abb20e7b8",
  • "name": "string",
  • "numPartitions": 1,
  • "status": "IN_PROGRESS",
  • "type": "search",
  • "analyzer": "lucene.standard",
  • "analyzers": [
    ],
  • "mappings": {
    },
  • "searchAnalyzer": "lucene.standard",
  • "storedSource": {
    },
  • "synonyms": [
    ]
}

Update One Atlas Search Index Deprecated

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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[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^([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/vnd.atlas.2023-01-01+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.

numPartitions
integer <int32>
Default: 1

Number of index partitions. Note: This feature is currently in preview.

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/vnd.atlas.2023-01-01+json
Example
{
  • "collectionName": "string",
  • "database": "string",
  • "name": "string",
  • "numPartitions": 1,
  • "type": "search",
  • "analyzer": "lucene.standard",
  • "analyzers": [
    ],
  • "mappings": {
    },
  • "searchAnalyzer": "lucene.standard",
  • "storedSource": {
    },
  • "synonyms": [
    ]
}

Response samples

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

Delete Search Nodes

Deletes the Search Nodes for the specified cluster.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[a-zA-Z0-9][a-zA-Z0-9-]*$

Label that identifies the cluster 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/vnd.atlas.2024-05-30+json
{ }

Return Search Nodes

Returns the Search Nodes for the specified cluster. Deprecated versions: v2-{2024-05-30}, v2-{2023-01-01}

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[a-zA-Z0-9][a-zA-Z0-9-]*$

Label that identifies the cluster to return the Search Nodes for.

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

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the 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/vnd.atlas.2025-03-12+json
{
  • "encryptionAtRestProvider": "NONE",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "specs": [
    ],
  • "stateName": "IDLE"
}

Update Search Nodes

Updates the Search Nodes for the specified cluster. Deprecated versions: v2-{2023-01-01}

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[a-zA-Z0-9][a-zA-Z0-9-]*$

Label that identifies the cluster to update the Search Nodes for.

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

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the 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/vnd.atlas.2024-05-30+json

Updates the Search Nodes for the specified cluster.

required
Array of objects (ApiSearchDeploymentSpecView) = 1 items

List of settings that configure the Search Nodes for your cluster.

NOTE: We accept a single configuration for all nodes currently.

Responses

Request samples

Content type
application/vnd.atlas.2024-05-30+json
{
  • "specs": [
    ]
}

Response samples

Content type
application/vnd.atlas.2024-05-30+json
{
  • "encryptionAtRestProvider": "NONE",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "specs": [
    ],
  • "stateName": "IDLE"
}

Create Search Nodes

Creates Search Nodes for the specified cluster.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[a-zA-Z0-9][a-zA-Z0-9-]*$

Label that identifies the cluster to create Search Nodes for.

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

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the 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/vnd.atlas.2024-05-30+json

Creates Search Nodes for the specified cluster.

required
Array of objects (ApiSearchDeploymentSpecView) = 1 items

List of settings that configure the Search Nodes for your cluster.

NOTE: We accept a single configuration for all nodes currently.

Responses

Request samples

Content type
application/vnd.atlas.2024-05-30+json
{
  • "specs": [
    ]
}

Response samples

Content type
application/vnd.atlas.2024-05-30+json
{
  • "encryptionAtRestProvider": "NONE",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "specs": [
    ],
  • "stateName": "IDLE"
}

Return All Atlas Search Indexes for One Cluster

Returns all Atlas Search indexes on the specified cluster. 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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[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/vnd.atlas.2024-05-30+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[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/vnd.atlas.2024-05-30+json

Creates one Atlas Search index on the specified collection.

collectionName
required
string

Label that identifies the collection to create an Atlas Search index in.

database
required
string

Label that identifies the database that contains the collection to create an Atlas Search index in.

name
required
string

Label that identifies this index. Within each namespace, names of all indexes in the namespace must be unique.

type
string

Type of the index. The default type is search.

required
object (Text Search Index Definition)

The text search index definition set by the user.

Responses

Request samples

Content type
application/vnd.atlas.2024-05-30+json
Example
{
  • "collectionName": "string",
  • "database": "string",
  • "name": "string",
  • "type": "search",
  • "definition": {
    }
}

Response samples

Content type
application/vnd.atlas.2024-05-30+json
Example
{
  • "collectionName": "string",
  • "database": "string",
  • "indexID": "32b6e34b3d91647abb20e7b8",
  • "latestDefinition": {
    },
  • "latestDefinitionVersion": {
    },
  • "name": "string",
  • "queryable": true,
  • "status": "DELETING",
  • "statusDetail": [
    ],
  • "type": "search",
  • "synonymMappingStatus": "FAILED",
  • "synonymMappingStatusDetail": [
    ]
}

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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[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

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/vnd.atlas.2024-05-30+json
[
  • {
    }
]

Remove One Atlas Search Index by Name

Removes one Atlas Search index that you identified with its database, collection, and name. To use this resource, the requesting API key must have the Project Data Access Admin role. This deletion is eventually consistent.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[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.

collectionName
required
string

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

databaseName
required
string

Label that identifies the database that contains the collection with one or more Atlas Search indexes.

indexName
required
string

Name of the Atlas Search index 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/vnd.atlas.2024-05-30+json
{ }

Return One Atlas Search Index by Name

Returns one Atlas Search index in the specified project. You identify this index using its database, collection and name. 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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[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

Label that identifies the database that contains the collection with one or more Atlas Search indexes.

indexName
required
string

Name of the Atlas Search index 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/vnd.atlas.2024-05-30+json
Example
{
  • "collectionName": "string",
  • "database": "string",
  • "indexID": "32b6e34b3d91647abb20e7b8",
  • "latestDefinition": {
    },
  • "latestDefinitionVersion": {
    },
  • "name": "string",
  • "queryable": true,
  • "status": "DELETING",
  • "statusDetail": [
    ],
  • "type": "search",
  • "synonymMappingStatus": "FAILED",
  • "synonymMappingStatusDetail": [
    ]
}

Update One Atlas Search Index By Name

Updates one Atlas Search index that you identified with its database, collection name, and index name. 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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[a-zA-Z0-9][a-zA-Z0-9-]*$

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

collectionName
required
string

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

databaseName
required
string

Label that identifies the database that contains the collection with one or more Atlas Search indexes.

indexName
required
string

Name of the Atlas Search index 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/vnd.atlas.2024-05-30+json

Details to update the Atlas Search index with.

required
Text Search Index Definition (object) or Vector Search Index Definition (object)

The index definition to update the search index to.

Responses

Request samples

Content type
application/vnd.atlas.2024-05-30+json
{
  • "definition": {
    }
}

Response samples

Content type
application/vnd.atlas.2024-05-30+json
Example
{
  • "collectionName": "string",
  • "database": "string",
  • "indexID": "32b6e34b3d91647abb20e7b8",
  • "latestDefinition": {
    },
  • "latestDefinitionVersion": {
    },
  • "name": "string",
  • "queryable": true,
  • "status": "DELETING",
  • "statusDetail": [
    ],
  • "type": "search",
  • "synonymMappingStatus": "FAILED",
  • "synonymMappingStatusDetail": [
    ]
}

Remove One Atlas Search Index by Id

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. This deletion is eventually consistent.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[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^([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/vnd.atlas.2024-05-30+json
{ }

Return One Atlas Search Index by ID

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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[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^([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/vnd.atlas.2024-05-30+json
Example
{
  • "collectionName": "string",
  • "database": "string",
  • "indexID": "32b6e34b3d91647abb20e7b8",
  • "latestDefinition": {
    },
  • "latestDefinitionVersion": {
    },
  • "name": "string",
  • "queryable": true,
  • "status": "DELETING",
  • "statusDetail": [
    ],
  • "type": "search",
  • "synonymMappingStatus": "FAILED",
  • "synonymMappingStatusDetail": [
    ]
}

Update One Atlas Search Index By ID

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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[a-zA-Z0-9][a-zA-Z0-9-]*$

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

indexId
required
string^([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/vnd.atlas.2024-05-30+json

Details to update on the Atlas Search index.

required
Text Search Index Definition (object) or Vector Search Index Definition (object)

The index definition to update the search index to.

Responses

Request samples

Content type
application/vnd.atlas.2024-05-30+json
{
  • "definition": {
    }
}

Response samples

Content type
application/vnd.atlas.2024-05-30+json
Example
{
  • "collectionName": "string",
  • "database": "string",
  • "indexID": "32b6e34b3d91647abb20e7b8",
  • "latestDefinition": {
    },
  • "latestDefinitionVersion": {
    },
  • "name": "string",
  • "queryable": true,
  • "status": "DELETING",
  • "statusDetail": [
    ],
  • "type": "search",
  • "synonymMappingStatus": "FAILED",
  • "synonymMappingStatusDetail": [
    ]
}

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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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/vnd.atlas.2023-01-01+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/vnd.atlas.2023-01-01+json
{
  • "auditAuthorizationSuccess": false,
  • "auditFilter": "string",
  • "enabled": false
}

Response samples

Content type
application/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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/vnd.atlas.2023-01-01+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/vnd.atlas.2023-01-01+json
{
  • "enabled": true
}

Response samples

Content type
application/vnd.atlas.2023-01-01+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. Deprecated versions: v2-{2023-01-01}

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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/vnd.atlas.2024-05-30+json
{}

Create One Snapshot Export Bucket

Creates a Snapshot Export Bucket for an AWS S3 Bucket or Azure Blob Storage Container. Once created, an snapshots can be exported to the Export Bucket and its referenced AWS S3 Bucket or Azure Blob Storage Container. To use this resource, the requesting API Key must have the Project Owner role. Deprecated versions: v2-{2023-01-01}

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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/vnd.atlas.2024-05-30+json

Specifies the role and AWS S3 Bucket or Azure Blob Storage Container 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

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

iamRoleId
required
string^([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/vnd.atlas.2024-05-30+json
Example

AWS

{
  • "bucketName": "export-bucket",
  • "cloudProvider": "AWS",
  • "iamRoleId": "668c5f0ed436263134491592"
}

Response samples

Content type
application/vnd.atlas.2024-05-30+json
Example

AWS

{
  • "_id": "32b6e34b3d91647abb20e7b8",
  • "bucketName": "export-bucket",
  • "cloudProvider": "AWS",
  • "iamRoleId": "668c5f0ed436263134491592",
  • "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 Backup Manager role.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^([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/vnd.atlas.2023-01-01+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. Deprecated versions: v2-{2023-01-01}

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^([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/vnd.atlas.2024-05-30+json
Example

AWS

{
  • "_id": "32b6e34b3d91647abb20e7b8",
  • "bucketName": "export-bucket",
  • "cloudProvider": "AWS",
  • "iamRoleId": "668c5f0ed436263134491592",
  • "links": []
}

Disable the Backup Compliance Policy settings

Disables the Backup Compliance Policy settings with the specified project. As a prerequisite, a support ticket needs to be file first, instructions in https://www.mongodb.com/docs/atlas/backup/cloud-backup/backup-compliance-policy/. To use this resource, the requesting API Key must have the Project Owner role.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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/vnd.atlas.2024-11-13+json
{ }

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. Deprecated versions: v2-{2023-01-01}

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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/vnd.atlas.2023-10-01+json
{
  • "authorizedEmail": "user@example.com",
  • "authorizedUserFirstName": "string",
  • "authorizedUserLastName": "string",
  • "copyProtectionEnabled": false,
  • "deletable": 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. Deprecated versions: v2-{2023-01-01}

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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/vnd.atlas.2023-10-01+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
required
string

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

authorizedUserLastName
required
string

Last name of the user who authorized to updated 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^([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/vnd.atlas.2023-10-01+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/vnd.atlas.2023-10-01+json
{
  • "authorizedEmail": "user@example.com",
  • "authorizedUserFirstName": "string",
  • "authorizedUserLastName": "string",
  • "copyProtectionEnabled": false,
  • "deletable": 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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[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/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[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/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$

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

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

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

Responses

Request samples

Content type
application/vnd.atlas.2023-01-01+json
{
  • "customData": [
    ],
  • "exportBucketId": "32b6e34b3d91647abb20e7b8",
  • "snapshotId": "32b6e34b3d91647abb20e7b8"
}

Response samples

Content type
application/vnd.atlas.2023-01-01+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",
  • "stateReason": {
    }
}

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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[a-zA-Z0-9][a-zA-Z0-9-]*$

Human-readable label that identifies the cluster.

exportId
required
string^([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/vnd.atlas.2023-01-01+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",
  • "stateReason": {
    }
}

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 Backup Manager role.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[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/vnd.atlas.2023-01-01+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 Backup Manager role.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[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/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$

Unique 24-hexadecimal character string that identifies the snapshot.

targetClusterName
string^[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^([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/vnd.atlas.2023-01-01+json
{
  • "deliveryType": "automated",
  • "oplogInc": 1,
  • "oplogTs": 1199145600,
  • "pointInTimeUTCSeconds": 1199145600,
  • "snapshotId": "32b6e34b3d91647abb20e7b8",
  • "targetClusterName": "string",
  • "targetGroupId": "32b6e34b3d91647abb20e7b8"
}

Response samples

Content type
application/vnd.atlas.2023-01-01+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 Backup Manager role.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[a-zA-Z0-9][a-zA-Z0-9-]*$

Human-readable label that identifies the cluster.

restoreJobId
required
string^([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/vnd.atlas.2023-01-01+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 Backup Manager role.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[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^([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/vnd.atlas.2023-01-01+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. Deprecated versions: v2-{2023-01-01}

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[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/vnd.atlas.2024-08-05+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. Deprecated versions: v2-{2023-01-01}

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[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/vnd.atlas.2024-08-05+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. Deprecated versions: v2-{2023-01-01}

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[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/vnd.atlas.2024-08-05+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 (DiskBackupCopySetting20240805)

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

Array of objects (DeleteCopiedBackups20240805)

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/vnd.atlas.2024-08-05+json
{
  • "autoExportEnabled": true,
  • "copySettings": [
    ],
  • "deleteCopiedBackups": [
    ],
  • "export": {
    },
  • "extraRetentionSettings": [
    ],
  • "policies": [
    ],
  • "referenceHourOfDay": 0,
  • "referenceMinuteOfHour": 0,
  • "restoreWindowDays": 0,
  • "updateSnapshots": true,
  • "useOrgAndGroupNamesInExportPrefix": true
}

Response samples

Content type
application/vnd.atlas.2024-08-05+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 or Project Backup Manager role.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[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/vnd.atlas.2023-01-01+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 Backup Manager role.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[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/vnd.atlas.2023-01-01+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/vnd.atlas.2023-01-01+json
{
  • "description": "string",
  • "retentionInDays": 1
}

Response samples

Content type
application/vnd.atlas.2023-01-01+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 Backup Manager role.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[a-zA-Z0-9][a-zA-Z0-9-]*$

Human-readable label that identifies the cluster.

snapshotId
required
string^([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/vnd.atlas.2023-01-01+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 or Project Backup Manager role.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[a-zA-Z0-9][a-zA-Z0-9-]*$

Human-readable label that identifies the cluster.

snapshotId
required
string^([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/vnd.atlas.2023-01-01+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 or Project Backup Manager role.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[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/vnd.atlas.2023-01-01+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 Backup Manager role.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[a-zA-Z0-9][a-zA-Z0-9-]*$

Human-readable label that identifies the cluster.

snapshotId
required
string^([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/vnd.atlas.2023-01-01+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 or Project Backup Manager role.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[a-zA-Z0-9][a-zA-Z0-9-]*$

Human-readable label that identifies the cluster.

snapshotId
required
string^([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/vnd.atlas.2023-01-01+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, the requesting API Key must have the Project Backup Manager role.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[a-zA-Z0-9][a-zA-Z0-9-]*$

Human-readable label that identifies the cluster.

snapshotId
required
string^([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/vnd.atlas.2023-01-01+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/vnd.atlas.2023-01-01+json
{
  • "retentionUnit": "DAYS",
  • "retentionValue": 5
}

Response samples

Content type
application/vnd.atlas.2023-01-01+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.

This API can also be used on Flex clusters that were created with the createServerlessInstance endpoint or Flex clusters that were migrated from Serverless instances. This endpoint will be sunset in January 2026. Please use the listFlexBackupRestoreJobs endpoint instead.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[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/vnd.atlas.2023-01-01+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.

This API can also be used on Flex clusters that were created with the createServerlessInstance endpoint or Flex clusters that were migrated from Serverless instances. This endpoint will be sunset in January 2026. Please use the createFlexBackupRestoreJob endpoint instead.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[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/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$

Unique 24-hexadecimal character string that identifies the snapshot.

targetClusterName
required
string^[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^([a-f0-9]{24})$

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

Responses

Request samples

Content type
application/vnd.atlas.2023-01-01+json
{
  • "deliveryType": "automated",
  • "oplogInc": 1,
  • "oplogTs": 1199145600,
  • "pointInTimeUTCSeconds": 1199145600,
  • "snapshotId": "32b6e34b3d91647abb20e7b8",
  • "targetClusterName": "string",
  • "targetGroupId": "32b6e34b3d91647abb20e7b8"
}

Response samples

Content type
application/vnd.atlas.2023-01-01+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.

This API can also be used on Flex clusters that were created with the createServerlessInstance endpoint or Flex clusters that were migrated from Serverless instances. This endpoint will be sunset in January 2026. Please use the getFlexBackupRestoreJob endpoint instead.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[a-zA-Z0-9][a-zA-Z0-9-]*$

Human-readable label that identifies the serverless instance.

restoreJobId
required
string^([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/vnd.atlas.2023-01-01+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.

This API can also be used on Flex clusters that were created with the createServerlessInstance endpoint or Flex clusters that were migrated from Serverless instances. This endpoint will be sunset in January 2026. Please use the listFlexBackups endpoint instead.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[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/vnd.atlas.2023-01-01+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.

This endpoint can also be used on Flex clusters that were created with the createServerlessInstance API or Flex clusters that were migrated from Serverless instances. This endpoint will be sunset in January 2026. Please use the getFlexBackup endpoint instead.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[a-zA-Z0-9][a-zA-Z0-9-]*$

Human-readable label that identifies the serverless instance.

snapshotId
required
string^([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/vnd.atlas.2023-01-01+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. Deprecated versions: v2-{2023-01-01}

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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/vnd.atlas.2024-05-30+json

One migration to be created.

required
object (Destination)

Document that describes the destination of the migration.

dropDestinationData
boolean
Default: false

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/vnd.atlas.2024-05-30+json
{
  • "destination": {
    },
  • "dropDestinationData": false,
  • "migrationHosts": [
    ],
  • "sharding": {
    },
  • "source": {
    }
}

Response samples

Content type
application/vnd.atlas.2024-05-30+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. Deprecated versions: v2-{2023-01-01}

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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/vnd.atlas.2024-05-30+json

One migration to be validated.

required
object (Destination)

Document that describes the destination of the migration.

dropDestinationData
boolean
Default: false

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/vnd.atlas.2024-05-30+json
{
  • "destination": {
    },
  • "dropDestinationData": false,
  • "migrationHosts": [
    ],
  • "sharding": {
    },
  • "source": {
    }
}

Response samples

Content type
application/vnd.atlas.2024-05-30+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^([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/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^([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/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^([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^([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/vnd.atlas.2023-01-01+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^([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/vnd.atlas.2023-01-01+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^([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/vnd.atlas.2023-01-01+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/vnd.atlas.2023-01-01+json
{
  • "accessListIps": [
    ]
}

Response samples

Content type
application/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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/vnd.atlas.2023-01-01+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/vnd.atlas.2023-01-01+json
Example
{
  • "providerName": "AWS"
}

Response samples

Content type
application/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^([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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^([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/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^([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/vnd.atlas.2023-01-01+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/vnd.atlas.2023-01-01+json
Example
{
  • "providerName": "AWS",
  • "iamAssumedRoleArn": "arn:aws:iam::123456789012:root"
}

Response samples

Content type
application/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[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/vnd.atlas.2023-01-01+json
{
  • "clusterName": "string",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "outageFilters": [
    ],
  • "startRequestDate": "2019-08-24T14:15:22Z",
  • "state": "START_REQUESTED"
}

Return One Outage Simulation

Returns one outage simulation for one cluster.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[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/vnd.atlas.2023-01-01+json
{
  • "clusterName": "string",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "outageFilters": [
    ],
  • "startRequestDate": "2019-08-24T14:15:22Z",
  • "state": "START_REQUESTED"
}

Start an Outage Simulation

Starts a cluster outage simulation.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[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/vnd.atlas.2023-01-01+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/vnd.atlas.2023-01-01+json
{
  • "outageFilters": [
    ]
}

Response samples

Content type
application/vnd.atlas.2023-01-01+json
{
  • "clusterName": "string",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "id": "32b6e34b3d91647abb20e7b8",
  • "outageFilters": [
    ],
  • "startRequestDate": "2019-08-24T14:15:22Z",
  • "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/vnd.atlas.2023-01-01+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 includes clusters with asymmetrically-sized shards. To use this resource, the requesting API Key must have the Project Read Only role. This feature is not available for serverless clusters.

This endpoint can also be used on Flex clusters that were created using the createCluster endpoint or former M2/M5 clusters that have been migrated to Flex clusters until January 2026. Please use the listFlexClusters endpoint for Flex clusters instead. Deprecated versions: v2-{2023-02-01}, v2-{2023-01-01}

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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/vnd.atlas.2024-08-05+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 clusters with asymmetrically-sized shards. 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.

Please note that using an instanceSize of M2 or M5 will create a Flex cluster instead. Support for the instanceSize of M2 or M5 will be discontinued in January 2026. We recommend using the createFlexCluster API for such configurations moving forward. Deprecated versions: v2-{2024-08-05}, v2-{2023-02-01}, v2-{2023-01-01}

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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/vnd.atlas.2024-10-23+json

Cluster to create in this 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 (ApiAtlasClusterAdvancedConfigurationView)

Group of settings that configures a subset of the advanced configuration details.

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
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.

object (EmployeeAccessGrantView)

MongoDB employee granted access level and expiration for a cluster.

mongoDBMajorVersion
string

MongoDB major version of the cluster. Set to the binary major version.

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^[a-zA-Z0-9][a-zA-Z0-9-]*$

Human-readable label that identifies the 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
redactClientLogData
boolean

Enable or disable log redaction.

This setting configures the mongod or mongos to redact any document field contents from a message accompanying a given log event before logging. This prevents the program from writing potentially sensitive data stored on the database to the diagnostic log. Metadata such as error or operation codes, line numbers, and source file names are still visible in the logs.

Use redactClientLogData in conjunction with Encryption at Rest and TLS/SSL (Transport Encryption) to assist compliance with regulatory requirements.

Note: changing this setting on a cluster will trigger a rolling restart as soon as the cluster is updated.

Log Redaction
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. This array has one object per shard representing node configurations in each shard. For replica sets there is only one object representing node configurations.

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/vnd.atlas.2024-10-23+json

Cluster

{
  • "clusterType": "SHARDED",
  • "name": "myCluster",
  • "replicationSpecs": [
    ]
}

Response samples

Content type
application/vnd.atlas.2024-10-23+json
{
  • "acceptDataRisksAndForceReplicaSetReconfig": "2019-08-24T14:15:22Z",
  • "advancedConfiguration": {
    },
  • "backupEnabled": false,
  • "biConnector": {
    },
  • "clusterType": "REPLICASET",
  • "configServerManagementMode": "ATLAS_MANAGED",
  • "configServerType": "DEDICATED",
  • "connectionStrings": {
    },
  • "createDate": "2019-08-24T14:15:22Z",
  • "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,
  • "redactClientLogData": true,
  • "replicaSetScalingStrategy": "SEQUENTIAL",
  • "replicationSpecs": [
    ],
  • "rootCertType": "ISRGROOTX1",
  • "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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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/vnd.atlas.2023-01-01+json
{
  • "links": [],
  • "results": [
    ],
  • "totalCount": 0
}

Upgrade One Shared-tier Cluster

Upgrades a shared-tier cluster to a Flex or Dedicated (M10+) 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.

This endpoint can also be used to upgrade Flex clusters that were created using the createCluster API or former M2/M5 clusters that have been migrated to Flex clusters, using instanceSizeName to “M2” or “M5” until January 2026. This functionality will be available until January 2026, after which it will only be available for M0 clusters. Please use the upgradeFlexCluster endpoint instead.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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/vnd.atlas.2023-01-01+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 (ApiAtlasClusterAdvancedConfigurationView)

Group of settings that configures a subset of the advanced configuration details.

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.

object (EmployeeAccessGrantView)

MongoDB employee granted access level and expiration for a cluster.

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^[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/vnd.atlas.2023-01-01+json
{
  • "acceptDataRisksAndForceReplicaSetReconfig": "2019-08-24T14:15:22Z",
  • "advancedConfiguration": {
    },
  • "autoScaling": {
    },
  • "backupEnabled": true,
  • "biConnector": {
    },
  • "clusterType": "REPLICASET",
  • "configServerManagementMode": "ATLAS_MANAGED",
  • "diskSizeGB": 10,
  • "diskWarmingMode": "FULLY_WARMED",
  • "encryptionAtRestProvider": "NONE",
  • "globalClusterSelfManagedSharding": true,
  • "labels": [
    ],
  • "mongoDBEmployeeAccessGrant": {
    },
  • "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/vnd.atlas.2023-01-01+json
{
  • "acceptDataRisksAndForceReplicaSetReconfig": "2019-08-24T14:15:22Z",
  • "advancedConfiguration": {
    },
  • "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 Deprecated

This endpoint has been deprecated as of February 2025 as we no longer support the creation of new serverless instances. Please use the upgradeFlexCluster endpoint to upgrade Flex clusters.

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.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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/vnd.atlas.2023-01-01+json

Details of the shared-tier cluster upgrade in the specified project.

name
string^[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/vnd.atlas.2023-01-01+json
{
  • "name": "string",
  • "providerSettings": {
    },
  • "serverlessBackupOptions": {
    },
  • "tags": [
    ],
  • "terminationProtectionEnabled": false
}

Response samples

Content type
application/vnd.atlas.2023-01-01+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 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.

This endpoint can also be used on Flex clusters that were created using the createCluster endpoint or former M2/M5 clusters that have been migrated to Flex clusters until January 2026. Please use the deleteFlexCluster endpoint for Flex clusters instead. Deprecated versions: v2-{2023-01-01}

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[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 clusters with asymmetrically-sized shards. To use this resource, the requesting API Key must have the Project Read Only role. This feature is not available for serverless clusters.

This endpoint can also be used on Flex clusters that were created using the createCluster endpoint or former M2/M5 clusters that have been migrated to Flex clusters until January 2026. Please use the getFlexCluster endpoint for Flex clusters instead. Deprecated versions: v2-{2023-02-01}, v2-{2023-01-01}

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[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/vnd.atlas.2024-08-05+json
{
  • "acceptDataRisksAndForceReplicaSetReconfig": "2019-08-24T14:15:22Z",
  • "advancedConfiguration": {
    },
  • "backupEnabled": false,
  • "biConnector": {
    },
  • "clusterType": "REPLICASET",
  • "configServerManagementMode": "ATLAS_MANAGED",
  • "configServerType": "DEDICATED",
  • "connectionStrings": {
    },
  • "createDate": "2019-08-24T14:15:22Z",
  • "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,
  • "redactClientLogData": 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 clusters with asymmetrically-sized shards. 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. Deprecated versions: v2-{2024-08-05}, v2-{2023-02-01}, v2-{2023-01-01}

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[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/vnd.atlas.2024-10-23+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
object (ApiAtlasClusterAdvancedConfigurationView)

Group of settings that configures a subset of the advanced configuration details.

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
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.

object (EmployeeAccessGrantView)

MongoDB employee granted access level and expiration for a cluster.

mongoDBMajorVersion
string

MongoDB major version of the cluster. Set to the binary major version.

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^[a-zA-Z0-9][a-zA-Z0-9-]*$

Human-readable label that identifies the 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
redactClientLogData
boolean

Enable or disable log redaction.

This setting configures the mongod or mongos to redact any document field contents from a message accompanying a given log event before logging. This prevents the program from writing potentially sensitive data stored on the database to the diagnostic log. Metadata such as error or operation codes, line numbers, and source file names are still visible in the logs.

Use redactClientLogData in conjunction with Encryption at Rest and TLS/SSL (Transport Encryption) to assist compliance with regulatory requirements.

Note: changing this setting on a cluster will trigger a rolling restart as soon as the cluster is updated.

Log Redaction
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. This array has one object per shard representing node configurations in each shard. For replica sets there is only one object representing node configurations.

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/vnd.atlas.2024-10-23+json
{
  • "acceptDataRisksAndForceReplicaSetReconfig": "2019-08-24T14:15:22Z",
  • "advancedConfiguration": {
    },
  • "backupEnabled": false,
  • "biConnector": {
    },
  • "clusterType": "REPLICASET",
  • "configServerManagementMode": "ATLAS_MANAGED",
  • "diskWarmingMode": "FULLY_WARMED",
  • "encryptionAtRestProvider": "NONE",
  • "globalClusterSelfManagedSharding": true,
  • "labels": [
    ],
  • "mongoDBEmployeeAccessGrant": {
    },
  • "mongoDBMajorVersion": "string",
  • "name": "string",
  • "paused": true,
  • "pitEnabled": true,
  • "redactClientLogData": true,
  • "replicaSetScalingStrategy": "SEQUENTIAL",
  • "replicationSpecs": [
    ],
  • "rootCertType": "ISRGROOTX1",
  • "tags": [
    ],
  • "terminationProtectionEnabled": false,
  • "versionReleaseSystem": "LTS"
}

Response samples

Content type
application/vnd.atlas.2024-10-23+json
{
  • "acceptDataRisksAndForceReplicaSetReconfig": "2019-08-24T14:15:22Z",
  • "advancedConfiguration": {
    },
  • "backupEnabled": false,
  • "biConnector": {
    },
  • "clusterType": "REPLICASET",
  • "configServerManagementMode": "ATLAS_MANAGED",
  • "configServerType": "DEDICATED",
  • "connectionStrings": {
    },
  • "createDate": "2019-08-24T14:15:22Z",
  • "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,
  • "redactClientLogData": true,
  • "replicaSetScalingStrategy": "SEQUENTIAL",
  • "replicationSpecs": [
    ],
  • "rootCertType": "ISRGROOTX1",
  • "stateName": "IDLE",
  • "tags": [
    ],
  • "terminationProtectionEnabled": false,
  • "versionReleaseSystem": "LTS"
}

Get cluster internal configuration of sharded cluster AutoScaling operations Deprecated

Returns the internal configuration of AutoScaling for sharded clusters. This endpoint can be used for diagnostic purposes to ensure that sharded clusters updated from older APIs have gained support for AutoScaling each shard independently.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[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/vnd.atlas.2024-08-05+json
{
  • "autoScalingMode": "INDEPENDENT_SHARD_SCALING"
}

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, flex clusters, or serverless clusters. To use this resource, the requesting API Key must have the Project Read Only role. Deprecated versions: v2-{2023-01-01}

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[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/vnd.atlas.2024-08-05+json
{
  • "changeStreamOptionsPreAndPostImagesExpireAfterSeconds": -1,
  • "chunkMigrationConcurrency": 0,
  • "customOpensslCipherConfigTls12": [
    ],
  • "defaultMaxTimeMS": 0,
  • "defaultWriteConcern": "string",
  • "javascriptEnabled": true,
  • "minimumEnabledTlsProtocol": "TLS1_0",
  • "noTableScan": true,
  • "oplogMinRetentionHours": 0,
  • "oplogSizeMB": 0,
  • "queryStatsLogVerbosity": 0,
  • "sampleRefreshIntervalBIConnector": 0,
  • "sampleSizeBIConnector": 0,
  • "tlsCipherConfigMode": "CUSTOM",
  • "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, flex clusters, or serverless clusters. Deprecated versions: v2-{2023-01-01}

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[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/vnd.atlas.2024-08-05+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.
customOpensslCipherConfigTls12
Array of strings
Items Enum: "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384" "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256"

The custom OpenSSL cipher suite list for TLS 1.2. This field is only valid when tlsCipherConfigMode is set to CUSTOM.

This option corresponds to the `opensslCipherConfig` `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.
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.
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.
tlsCipherConfigMode
string
Enum: "CUSTOM" "DEFAULT"

The TLS cipher suite configuration mode. The default mode uses the default cipher suites. The custom mode allows you to specify custom cipher suites for both TLS 1.2 and TLS 1.3.

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/vnd.atlas.2024-08-05+json
{
  • "changeStreamOptionsPreAndPostImagesExpireAfterSeconds": -1,
  • "chunkMigrationConcurrency": 0,
  • "customOpensslCipherConfigTls12": [
    ],
  • "defaultMaxTimeMS": 0,
  • "defaultWriteConcern": "string",
  • "javascriptEnabled": true,
  • "minimumEnabledTlsProtocol": "TLS1_0",
  • "noTableScan": true,
  • "oplogMinRetentionHours": 0,
  • "oplogSizeMB": 0,
  • "queryStatsLogVerbosity": 0,
  • "sampleRefreshIntervalBIConnector": 0,
  • "sampleSizeBIConnector": 0,
  • "tlsCipherConfigMode": "CUSTOM",
  • "transactionLifetimeLimitSeconds": 1
}

Response samples

Content type
application/vnd.atlas.2024-08-05+json
{
  • "changeStreamOptionsPreAndPostImagesExpireAfterSeconds": -1,
  • "chunkMigrationConcurrency": 0,
  • "customOpensslCipherConfigTls12": [
    ],
  • "defaultMaxTimeMS": 0,
  • "defaultWriteConcern": "string",
  • "javascriptEnabled": true,
  • "minimumEnabledTlsProtocol": "TLS1_0",
  • "noTableScan": true,
  • "oplogMinRetentionHours": 0,
  • "oplogSizeMB": 0,
  • "queryStatsLogVerbosity": 0,
  • "sampleRefreshIntervalBIConnector": 0,
  • "sampleSizeBIConnector": 0,
  • "tlsCipherConfigMode": "CUSTOM",
  • "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. Deprecated versions: v2-{2023-01-01}

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[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/vnd.atlas.2023-01-01+json
{}

Grant MongoDB employee cluster access for one cluster.

Grants MongoDB employee cluster access for the given duration and at the specified level for one cluster.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[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.

Request Body schema: application/vnd.atlas.2024-08-05+json

Grant access level and expiration.

expirationTime
required
string <date-time>

Expiration date for the employee access grant.

grantType
required
string
Enum: "CLUSTER_DATABASE_LOGS" "CLUSTER_INFRASTRUCTURE" "CLUSTER_INFRASTRUCTURE_AND_APP_SERVICES_SYNC_DATA"

Level of access to grant to MongoDB Employees.

Responses

Request samples

Content type
application/vnd.atlas.2024-08-05+json
{
  • "expirationTime": "2019-08-24T14:15:22Z",
  • "grantType": "CLUSTER_DATABASE_LOGS"
}

Response samples

Content type
application/vnd.atlas.2024-08-05+json
{ }

Pin FCV for One Cluster from One Project

Pins the Feature Compatibility Version (FCV) to the current MongoDB version and sets the pin expiration date. If an FCV pin already exists for the cluster, calling this method will only update the expiration date of the existing pin and will not repin the FCV.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[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.

Request Body schema: application/vnd.atlas.2024-05-30+json

Optional request params for tuning FCV pinning configuration.

expirationDate
string <date-time>

Expiration date of the fixed FCV. If not specified, the expiration date will default to 4 weeks from the date FCV was originally pinned. Note that this field cannot exceed 4 weeks from the pinned date.

Responses

Request samples

Content type
application/vnd.atlas.2024-05-30+json
{
  • "expirationDate": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/vnd.atlas.2024-05-30+json
{ }

Revoke granted MongoDB employee cluster access for one cluster.

Revokes a previously granted MongoDB employee cluster access.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[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/vnd.atlas.2024-08-05+json
{ }

Unpins FCV for One Cluster from One Project

Unpins the current fixed Feature Compatibility Version (FCV). This feature is not available for clusters on rapid release.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[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/vnd.atlas.2024-05-30+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[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/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^([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/vnd.atlas.2023-01-01+json
{
  • "_id": "32b6e34b3d91647abb20e7b8",
  • "clusterName": "string",
  • "completeDate": "2019-08-24T14:15:22Z",
  • "createDate": "2019-08-24T14:15:22Z",
  • "errorMessage": "string",
  • "state": "WORKING"
}

Collection Level Metrics

Returns, adds, and edits pinned namespaces for the specified cluster or process. Also returns collection level latency metric data.

Return Pinned Namespaces

Returns a list of given cluster's pinned namespaces, a set of namespaces manually selected by users to collect query latency metrics on.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[a-zA-Z0-9][a-zA-Z0-9-]*$

Human-readable label that identifies the cluster to retrieve pinned namespaces for.

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

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the 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/vnd.atlas.2023-11-15+json
{
  • "clusterId": "32b6e34b3d91647abb20e7b8",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "pinnedNamespaces": [
    ]
}

Add Pinned Namespaces

Add provided list of namespaces to existing pinned namespaces list for collection-level latency metrics collection for the given Group and Cluster

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[a-zA-Z0-9][a-zA-Z0-9-]*$

Human-readable label that identifies the cluster to pin namespaces to.

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

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the 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/vnd.atlas.2023-11-15+json

List of namespace strings (combination of database and collection name) to pin for query latency metric collection.

namespaces
Array of strings unique

List of namespace strings (combination of database and collection) on the specified host or cluster.

Responses

Request samples

Content type
application/vnd.atlas.2023-11-15+json
{
  • "namespaces": [
    ]
}

Response samples

Content type
application/vnd.atlas.2023-11-15+json
{
  • "clusterId": "32b6e34b3d91647abb20e7b8",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "pinnedNamespaces": [
    ]
}

Pin Namespaces

Pin provided list of namespaces for collection-level latency metrics collection for the given Group and Cluster. This initializes a pinned namespaces list or replaces any existing pinned namespaces list for the Group and Cluster.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[a-zA-Z0-9][a-zA-Z0-9-]*$

Human-readable label that identifies the cluster to pin namespaces to.

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

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the 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/vnd.atlas.2023-11-15+json

List of namespace strings (combination of database and collection name) to pin for query latency metric collection.

namespaces
Array of strings unique

List of namespace strings (combination of database and collection) on the specified host or cluster.

Responses

Request samples

Content type
application/vnd.atlas.2023-11-15+json
{
  • "namespaces": [
    ]
}

Response samples

Content type
application/vnd.atlas.2023-11-15+json
{
  • "clusterId": "32b6e34b3d91647abb20e7b8",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "pinnedNamespaces": [
    ]
}

Unpin namespaces

Unpin provided list of namespaces for collection-level latency metrics collection for the given Group and Cluster

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[a-zA-Z0-9][a-zA-Z0-9-]*$

Human-readable label that identifies the cluster to unpin namespaces from.

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

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the 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/vnd.atlas.2023-11-15+json

List of namespace strings (combination of database and collection name) to pin for query latency metric collection.

namespaces
Array of strings unique

List of namespace strings (combination of database and collection) on the specified host or cluster.

Responses

Request samples

Content type
application/vnd.atlas.2023-11-15+json
{
  • "namespaces": [
    ]
}

Response samples

Content type
application/vnd.atlas.2023-11-15+json
{
  • "clusterId": "32b6e34b3d91647abb20e7b8",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "pinnedNamespaces": [
    ]
}

Return Ranked Namespaces from a Cluster

Return the subset of namespaces from the given cluster sorted by highest total execution time (descending) within the given time window.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[a-zA-Z0-9][a-zA-Z0-9-]*$

Human-readable label that identifies the cluster to pin namespaces to.

clusterView
required
string
Enum: "PRIMARY" "SECONDARY" "INDIVIDUAL_PROCESS"

Human-readable label that identifies the cluster topology to retrieve metrics for.

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

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

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.

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.

Responses

Response samples

Content type
application/vnd.atlas.2023-11-15+json
{
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "identifierId": "string",
  • "rankedNamespaces": [
    ]
}

Return Cluster-Level Query Latency

Get a list of the Coll Stats Latency cluster-level measurements for the given namespace.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^[a-zA-Z0-9][a-zA-Z0-9-]*$

Human-readable label that identifies the cluster to retrieve metrics for.

clusterView
required
string
Enum: "PRIMARY" "SECONDARY" "INDIVIDUAL_PROCESS"

Human-readable label that identifies the cluster topology to retrieve metrics for.

databaseName
required
string
Example: mydb

Human-readable label that identifies the database.

collectionName
required
string
Example: mycoll

Human-readable label that identifies the collection.

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

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the 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
Array of strings unique
Items Enum: "READS_OPS" "READS_LATENCY" "AVERAGE_READS_LATENCY" "READS_P50_VALUE" "READS_P95_VALUE" "READS_P99_VALUE" "WRITES_OPS" "WRITES_LATENCY" "AVERAGE_WRITES_LATENCY" "WRITES_P50_VALUE" "WRITES_P95_VALUE" "WRITES_P99_VALUE" "COMMANDS_OPS" "COMMANDS_LATENCY" "AVERAGE_COMMANDS_LATENCY" "COMMANDS_P50_VALUE" "COMMANDS_P95_VALUE" "COMMANDS_P99_VALUE" "TOTAL_OPS" "TOTAL_LATENCY" "AVERAGE_TOTAL_OPS_LATENCY" "TOTAL_OPS_P50_VALUE" "TOTAL_OPS_P95_VALUE" "TOTAL_OPS_P99_VALUE"

List that contains the metrics that you want to retrieve for the associated data series. If you don't set this parameter, this resource returns data series for all Coll Stats Latency metrics.

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.

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.

Responses

Response samples

Content type
application/vnd.atlas.2023-11-15+json
{
  • "clusterId": "string",
  • "clusterView": "string",
  • "collectionName": "string",
  • "databaseName": "string",
  • "end": "2019-08-24T14:15:22Z",
  • "granularity": "PT1M",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "links": [],
  • "measurements": [
    ],
  • "processId": "mongodb.example.com:27017",
  • "start": "2019-08-24T14:15:22Z"
}

Return all metric names

Returns all available Coll Stats Latency metric names and their respective units for the specified project at the time of request.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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/vnd.atlas.2023-11-15+json
{ }

Return Ranked Namespaces from a Host

Return the subset of namespaces from the given process ranked by highest total execution time (descending) within the given time window.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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: 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.

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

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

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.

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.

Responses

Response samples

Content type
application/vnd.atlas.2023-11-15+json
{
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "identifierId": "string",
  • "rankedNamespaces": [
    ]
}

Return Host-Level Query Latency

Get a list of the Coll Stats Latency process-level measurements for the given namespace

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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: 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.

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

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the 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
Array of strings unique
Items Enum: "READS_OPS" "READS_LATENCY" "AVERAGE_READS_LATENCY" "READS_P50_VALUE" "READS_P95_VALUE" "READS_P99_VALUE" "WRITES_OPS" "WRITES_LATENCY" "AVERAGE_WRITES_LATENCY" "WRITES_P50_VALUE" "WRITES_P95_VALUE" "WRITES_P99_VALUE" "COMMANDS_OPS" "COMMANDS_LATENCY" "AVERAGE_COMMANDS_LATENCY" "COMMANDS_P50_VALUE" "COMMANDS_P95_VALUE" "COMMANDS_P99_VALUE" "TOTAL_OPS" "TOTAL_LATENCY" "AVERAGE_TOTAL_OPS_LATENCY" "TOTAL_OPS_P50_VALUE" "TOTAL_OPS_P95_VALUE" "TOTAL_OPS_P99_VALUE"

List that contains the metrics that you want to retrieve for the associated data series. If you don't set this parameter, this resource returns data series for all Coll Stats Latency metrics.

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.

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.

Responses

Response samples

Content type
application/vnd.atlas.2023-11-15+json
{
  • "collectionName": "string",
  • "databaseName": "string",
  • "end": "2019-08-24T14:15:22Z",
  • "granularity": "PT1M",
  • "groupId": "32b6e34b3d91647abb20e7b8",
  • "links": [],
  • "measurements": [
    ],
  • "processId": "mongodb.example.com:27017",
  • "start": "2019-08-24T14:15:22Z"
}

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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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/vnd.atlas.2023-01-01+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, Project Stream Processing Owner role, or the Project Database Access Admin role.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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/vnd.atlas.2023-01-01+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/vnd.atlas.2023-01-01+json
{
  • "actions": [
    ],
  • "inheritedRoles": [
    ],
  • "roleName": "string"
}

Response samples

Content type
application/vnd.atlas.2023-01-01+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 Owner role, Project Stream Processing Owner role, or the Project Database Access Admin role.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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/vnd.atlas.2023-01-01+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, the Project Stream Processing Owner role, or the Project Database Access Admin role.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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/vnd.atlas.2023-01-01+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/vnd.atlas.2023-01-01+json
{
  • "actions": [
    ],
  • "inheritedRoles": [
    ]
}

Response samples

Content type
application/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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/vnd.atlas.2023-01-01+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/vnd.atlas.2023-01-01+json
{
  • "cloudProviderConfig": {
    },
  • "dataProcessRegion": {
    },
  • "name": "string",
  • "storage": {
    }
}

Response samples

Content type
application/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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/vnd.atlas.2023-01-01+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/vnd.atlas.2023-01-01+json
{
  • "cloudProviderConfig": {
    },
  • "dataProcessRegion": {
    },
  • "name": "string",
  • "storage": {
    }
}

Response samples

Content type
application/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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/vnd.atlas.2023-01-01+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/vnd.atlas.2023-01-01+json
{
  • "overrunPolicy": "BLOCK",
  • "value": 0
}

Response samples

Content type
application/vnd.atlas.2023-01-01+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/vnd.atlas.YYYY-MM-DD+gzip".

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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/vnd.atlas.2023-01-01+json

Private endpoint for Federated Database Instances and Online Archives to add to the specified project.

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^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/vnd.atlas.2023-01-01+json
{
  • "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/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^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/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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^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/vnd.atlas.2023-01-01+json
{
  • "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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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/vnd.atlas.2023-01-01+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/vnd.atlas.2023-01-01+json
{
  • "datasetRetentionPolicy": {
    },
  • "name": "string",
  • "sink": { },
  • "source": {
    },
  • "transformations": [
    ]
}

Response samples

Content type
application/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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}$

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/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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}$

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/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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}$

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/vnd.atlas.2023-01-01+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/vnd.atlas.2023-01-01+json
{
  • "datasetRetentionPolicy": {
    },
  • "name": "string",
  • "sink": { },
  • "source": {
    },
  • "transformations": [
    ]
}

Response samples

Content type
application/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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}$

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/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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}$

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>

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/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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}$

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/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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}$

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/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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}$

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>

If specified, Atlas returns only Data Lake Pipeline runs initiated before this time and date.

Responses

Response samples

Content type
application/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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}$

Human-readable label that identifies the Data Lake Pipeline.

pipelineRunId
required
string^([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/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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}$

Human-readable label that identifies the Data Lake Pipeline.

pipelineRunId
required
string^([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/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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}$

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/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$

Unique 24-hexadecimal character string that identifies the snapshot.

Responses

Request samples

Content type
application/vnd.atlas.2023-01-01+json
{
  • "datasetRetentionPolicy": {
    },
  • "snapshotId": "32b6e34b3d91647abb20e7b8"
}

Response samples

Content type
application/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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/vnd.atlas.2023-01-01+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 role, the Project Charts Admin role, Project Stream Processing Owner role, or the Project Database Access Admin role.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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/vnd.atlas.2023-01-01+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

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/vnd.atlas.2023-01-01+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/vnd.atlas.2023-01-01+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, the Project Stream Processing Owner role, or the Project Database Access Admin role.

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

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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/vnd.atlas.2023-01-01+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^([a-f0-9]{24})$
Example: 32b6e34b3d91647abb20e7b8

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

NOTE: Groups and projects are synonymous terms. Your group id is the 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.