A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The MongoDB Atlas API is how an app or AI agent manages an Atlas deployment: launching and resizing clusters, creating database users, opening network access to a database, and taking or restoring backups. Access is granted through a service account or an API key, and each one is assigned an organization or project role that sets which operations it can perform. Atlas versions the API per resource by date, so a request names the exact resource version it wants.
How an app or AI agent connects to Atlas determines what it can reach. There is a route for making calls, a token route for service accounts, and a hosted server that exposes Atlas tools to agents, and each is governed by the key or token behind it and the organization or project role it carries.
The Atlas Administration API is a JSON REST API at https://cloud.mongodb.com/api/atlas/v2. A call authenticates with a service account Bearer token or a Digest API key, and names the resource version it wants in the Accept header, for example application/vnd.atlas.2025-03-12+json. Most paths are scoped under a project (group) ID.
MongoDB publishes an official Model Context Protocol server (mongodb-js/mongodb-mcp-server) that exposes Atlas administration as tools an AI agent can call, like atlas-list-clusters, atlas-create-cluster, atlas-create-db-user, atlas-create-access-list, and atlas-list-alerts. It runs locally and authenticates to the Administration API with a service account or an API key, so the tools inherit that credential's roles.
A service account uses the OAuth 2.0 client credentials flow, exchanging a client ID and secret for a Bearer access token at the token endpoint. The token is valid for one hour and is then refreshed. This is the recommended method for machine-to-machine access. The service account is assigned organization and project roles that govern what its token can do.
An API key is the legacy method. It has a public key and a private key, sent with HTTP Digest authentication, where Atlas hashes the keys with a short-lived nonce to guard against replay. A key belongs to one organization and is assigned organization and project roles. An IP access list can restrict which addresses may use it.
The Atlas Administration API is split into areas an agent can act on, like clusters, projects, database users, network access, backups, organizations, and alerts. Each area has its own methods, and a write can launch infrastructure, change who can reach a database, or open it to new network addresses.
Methods for launching, resizing, and removing database clusters in a project.
Methods for working with projects, called groups in the API.
Methods for the accounts that authenticate to the databases in a project.
Methods for the IP and CIDR ranges allowed to reach a project's databases.
Methods for cloud backup snapshots and restore jobs on a cluster.
Methods for organizations, which hold projects, billing, and API keys.
Methods for open alerts and the alert configurations that raise them.
Methods for the organization API keys that authenticate to this very API.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
ClustersMethods for launching, resizing, and removing database clusters in a project.5 | ||||||
| GET | /api/atlas/v2/groups/{groupId}/clusters | List all clusters in a project. | read | GROUP_READ_ONLY | Current | |
Read-only; any project role that can view the project can list clusters. Acts oncluster Permission (capability) GROUP_READ_ONLYVersionAvailable since the API’s base version Webhook eventNone Rate limitClusters set: capacity 10,000, refill 5,000 / 60s (per project) SourceOfficial documentation ↗ | ||||||
| GET | /api/atlas/v2/groups/{groupId}/clusters/{clusterName} | Get the details and state of one cluster. | read | GROUP_READ_ONLY | Current | |
Read-only. Acts oncluster Permission (capability) GROUP_READ_ONLYVersionAvailable since the API’s base version Webhook eventNone Rate limitClusters set: capacity 10,000, refill 5,000 / 60s (per project) SourceOfficial documentation ↗ | ||||||
| POST | /api/atlas/v2/groups/{groupId}/clusters | Create a new cluster in a project, choosing the tier, region, and configuration. | write | GROUP_CLUSTER_MANAGER | Current | |
Provisions real, billable infrastructure; needs a project role that can manage clusters. Acts oncluster Permission (capability) GROUP_CLUSTER_MANAGERVersionAvailable since the API’s base version Webhook eventNone Rate limitClusters set: capacity 10,000, refill 5,000 / 60s (per project) SourceOfficial documentation ↗ | ||||||
| PATCH | /api/atlas/v2/groups/{groupId}/clusters/{clusterName} | Update a cluster, such as resizing the tier or changing its configuration. | write | GROUP_CLUSTER_MANAGER | Current | |
Can change cost and capacity of a running cluster. Acts oncluster Permission (capability) GROUP_CLUSTER_MANAGERVersionAvailable since the API’s base version Webhook eventNone Rate limitClusters set: capacity 10,000, refill 5,000 / 60s (per project) SourceOfficial documentation ↗ | ||||||
| DELETE | /api/atlas/v2/groups/{groupId}/clusters/{clusterName} | Delete a cluster from a project. | write | GROUP_CLUSTER_MANAGER | Current | |
Irreversible; tears down the cluster and its data. Acts oncluster Permission (capability) GROUP_CLUSTER_MANAGERVersionAvailable since the API’s base version Webhook eventNone Rate limitClusters set: capacity 10,000, refill 5,000 / 60s (per project) SourceOfficial documentation ↗ | ||||||
Projects (Groups)Methods for working with projects, called groups in the API.4 | ||||||
| GET | /api/atlas/v2/groups | List all projects the credential can access. | read | ORG_READ_ONLY | Current | |
Returns only projects the credential's roles can see. Acts onproject Permission (capability) ORG_READ_ONLYVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/atlas/v2/groups/{groupId} | Get one project by its group ID. | read | GROUP_READ_ONLY | Current | |
Read-only. Acts onproject Permission (capability) GROUP_READ_ONLYVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/atlas/v2/groups | Create a new project (group) in an organization. | write | ORG_GROUP_CREATOR | Current | |
Needs an organization role that can create projects. Acts onproject Permission (capability) ORG_GROUP_CREATORVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/atlas/v2/groups/{groupId} | Delete a project and the resources scoped under it. | write | GROUP_OWNER | Current | |
Irreversible; the project must have no active clusters. Acts onproject Permission (capability) GROUP_OWNERVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Database UsersMethods for the accounts that authenticate to the databases in a project.3 | ||||||
| GET | /api/atlas/v2/groups/{groupId}/databaseUsers | List the database users in a project. | read | GROUP_READ_ONLY | Current | |
Read-only. Acts ondatabaseUser Permission (capability) GROUP_READ_ONLYVersionAvailable since the API’s base version Webhook eventNone Rate limitDatabase Users set: capacity 10,000, refill 5,000 / 60s (per project) SourceOfficial documentation ↗ | ||||||
| POST | /api/atlas/v2/groups/{groupId}/databaseUsers | Create a database user that can authenticate to the project's clusters. | write | GROUP_DATABASE_ACCESS_ADMIN | Current | |
Grants a new login to the databases, with the privileges set on the user. Acts ondatabaseUser Permission (capability) GROUP_DATABASE_ACCESS_ADMINVersionAvailable since the API’s base version Webhook eventNone Rate limitDatabase Users set: capacity 10,000, refill 5,000 / 60s (per project) SourceOfficial documentation ↗ | ||||||
| DELETE | /api/atlas/v2/groups/{groupId}/databaseUsers/{username} | Delete a database user from a project. | write | GROUP_DATABASE_ACCESS_ADMIN | Current | |
Removes that login's access to the databases. Acts ondatabaseUser Permission (capability) GROUP_DATABASE_ACCESS_ADMINVersionAvailable since the API’s base version Webhook eventNone Rate limitDatabase Users set: capacity 10,000, refill 5,000 / 60s (per project) SourceOfficial documentation ↗ | ||||||
Network access (IP access list)Methods for the IP and CIDR ranges allowed to reach a project's databases.3 | ||||||
| GET | /api/atlas/v2/groups/{groupId}/accessList | List the IP and CIDR entries on a project's access list. | read | GROUP_READ_ONLY | Current | |
Read-only. Acts onprojectIpAccessList Permission (capability) GROUP_READ_ONLYVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/atlas/v2/groups/{groupId}/accessList | Add one or more IP or CIDR entries to a project's access list. | write | GROUP_NETWORK_ACCESS_MANAGER | Current | |
Opens new network addresses to the project's databases. Acts onprojectIpAccessList Permission (capability) GROUP_NETWORK_ACCESS_MANAGERVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/atlas/v2/groups/{groupId}/accessList/{entryValue} | Remove an IP or CIDR entry from a project's access list. | write | GROUP_NETWORK_ACCESS_MANAGER | Current | |
Closes a network address's reach to the databases. Acts onprojectIpAccessList Permission (capability) GROUP_NETWORK_ACCESS_MANAGERVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Backups & snapshotsMethods for cloud backup snapshots and restore jobs on a cluster.3 | ||||||
| GET | /api/atlas/v2/groups/{groupId}/clusters/{clusterName}/backup/snapshots | List the cloud backup snapshots taken for a cluster. | read | GROUP_READ_ONLY | Current | |
Read-only. Acts ondiskBackupSnapshot Permission (capability) GROUP_READ_ONLYVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/atlas/v2/groups/{groupId}/clusters/{clusterName}/backup/snapshots | Take an on-demand cloud backup snapshot of a cluster. | write | GROUP_BACKUP_MANAGER | Current | |
Creates a new snapshot of the cluster's data. Acts ondiskBackupSnapshot Permission (capability) GROUP_BACKUP_MANAGERVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/atlas/v2/groups/{groupId}/clusters/{clusterName}/backup/restoreJobs | Start a restore job that recovers a cluster from a snapshot. | write | GROUP_BACKUP_MANAGER | Current | |
A restore can overwrite live data on the target cluster. Acts ondiskBackupRestoreJob Permission (capability) GROUP_BACKUP_MANAGERVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
OrganizationsMethods for organizations, which hold projects, billing, and API keys.2 | ||||||
| GET | /api/atlas/v2/orgs | List the organizations the credential can access. | read | ORG_READ_ONLY | Current | |
Read-only. Acts onorganization Permission (capability) ORG_READ_ONLYVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/atlas/v2/orgs/{orgId} | Get one organization by its ID. | read | ORG_READ_ONLY | Current | |
Read-only. Acts onorganization Permission (capability) ORG_READ_ONLYVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
AlertsMethods for open alerts and the alert configurations that raise them.2 | ||||||
| GET | /api/atlas/v2/groups/{groupId}/alerts | List the open alerts in a project. | read | GROUP_READ_ONLY | Current | |
Read-only. Acts onalert Permission (capability) GROUP_READ_ONLYVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/atlas/v2/groups/{groupId}/alertConfigs | Create an alert configuration that defines a condition and where to notify. | write | GROUP_ALERTS_MANAGER | Current | |
Sets which conditions raise an alert and the integration it notifies, like email, Slack, or a webhook target. Acts onalertConfig Permission (capability) GROUP_ALERTS_MANAGERVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Programmatic API keysMethods for the organization API keys that authenticate to this very API.3 | ||||||
| GET | /api/atlas/v2/orgs/{orgId}/apiKeys | List the programmatic API keys in an organization. | read | ORG_READ_ONLY | Current | |
Read-only; the private key is never returned after creation. Acts onapiKey Permission (capability) ORG_READ_ONLYVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/atlas/v2/orgs/{orgId}/apiKeys | Create a new programmatic API key in an organization. | write | ORG_OWNER | Current | |
Mints a credential that can call this API; the private key is shown only once. Acts onapiKey Permission (capability) ORG_OWNERVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/atlas/v2/orgs/{orgId}/apiKeys/{apiKeyId} | Delete a programmatic API key from an organization. | write | ORG_OWNER | Current | |
Revokes that credential's access to the Administration API. Acts onapiKey Permission (capability) ORG_OWNERVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
The Atlas Administration API does not push events to a webhook of its own. Atlas alerts are delivered instead through configured integrations, like email, Slack, PagerDuty, or a generic webhook set on an alert configuration.
| Event | What it signals | Triggered by |
|---|
Atlas limits how fast an app can call the Administration API using a token-bucket model that sets a separate capacity and refill rate per endpoint set and scope, rather than one uniform per-minute ceiling.
Atlas does not apply one uniform request limit across the Administration API. It uses a token-bucket model where each endpoint set has its own capacity (a burst of requests) and refill rate (how fast that burst is replenished), scoped to an organization, a project, a user, or an IP address. Cluster and database-user endpoints in a project allow a capacity of 10,000 with a refill of 5,000 per 60 seconds, while organization-scoped sets like the activity feed allow far less. Going over returns HTTP 429 with the error code RATE_LIMITED_TOKEN_BUCKET and, when present, RateLimit-Limit, RateLimit-Remaining, and Retry-After headers.
List endpoints page with a page number (pageNum, starting at 1) and an items-per-page count (itemsPerPage). A response wraps the results in a results array alongside totalCount and a links section, and an envelope query parameter can include the HTTP status in the body. Headers are not guaranteed, so an integration handles their absence.
The items-per-page count (itemsPerPage) controls how many objects a single page returns. A Bearer access token from a service account is valid for one hour before it must be refreshed.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Validation error (e.g. ATLAS_INVALID_CIDR_BLOCK) | The request was malformed or a value was invalid, for example a bad CIDR block on a network access entry or a missing required field. The body names a specific errorCode and detail. | Read the errorCode and detail, fix the request, and resend. The request is not retryable as-is. |
| 401 | Unauthorized | Authentication failed. The Bearer token is missing or expired, or the Digest credentials are wrong. | Refresh the service account token (it lasts one hour) or check the API key, then retry. |
| 403 | Forbidden | The credential authenticated but its organization or project role does not allow this operation, or its IP is not on the access list. | Grant the service account or API key the needed role (for example GROUP_CLUSTER_MANAGER for cluster changes), or add the calling IP to the access list. |
| 404 | Not found | The requested resource does not exist or is not visible to this credential, for example a cluster name or project ID that is wrong. | Verify the group ID and resource name, and confirm the credential has access to that project. |
| 406 | Not Acceptable | The Accept header omitted the resource version or named a version that does not exist for that resource. | Set the Accept header to a valid dated version, like application/vnd.atlas.2025-03-12+json. |
| 409 | Conflict | The operation cannot run in the resource's current state, for example changing a cluster that is mid-deployment or creating something that already exists. | Wait for the resource to reach a stable state, or reconcile the conflict, then retry. |
| 429 | RATE_LIMITED_TOKEN_BUCKET | The token-bucket capacity for this endpoint set and scope was exhausted. The detail names the path, the wait time, the capacity, and the refill rate. | Back off using the Retry-After header when present, then retry with exponential backoff. |
| 500 | ATLAS_GENERAL_ERROR | An unexpected error on the Atlas side. It is rare. | Retry with backoff, and contact MongoDB support if it persists. |
Atlas versions the Administration API per resource by date. A request names the resource version it wants in the Accept header, and Atlas keeps an older version working for at least twelve months after it is deprecated.
The latest dated resource version of the Administration API, named in the Accept header as application/vnd.atlas.2025-03-12+json. Atlas versions each resource independently by date: breaking changes mint a new dated version, while non-breaking changes are folded into the current one.
Dated resource versions released through 2024 carried breaking changes for individual resources ahead of the 2025 cut. Each became the stable version for its resource until a newer date superseded it.
A dated resource version in the first year of the reintroduced versioned API, carrying breaking changes for the resources it covered.
Part of the first release of the reintroduced versioned Atlas Administration API, supported for an extended period after its later deprecation.
The initial dated resource version of the reintroduced versioned Administration API, equivalent to the older unversioned v1.0 endpoints. Supported for an extended period after deprecation.
Pin a resource version in the Accept header and move up before a deprecated version is removed.
Atlas Administration API changelog ↗Bollard AI sits between a team's AI agents and MongoDB Atlas. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.