MongoDB Atlas organizes everything by project (a.k.a. group). Almost every operation requires a groupId (24‑hex string). Within a project the most commonly referenced resources are clusters (identified by their human‑readable clusterName), database users (username + databaseName), backups/snapshots (24‑hex snapshotId), alert configurations/alerts (alertConfigId / alertId), network containers and private endpoints (containerId / endpointId), and various federation or AI resources that use their own IDs. Learn where each ID lives before trying to change things: you will normally call list endpoints to discover IDs, then call create/update/delete endpoints using those values.

How the domain is organized (what to fetch first)

Projects (groups) are the root scope. Most calls require groupId. Within a project:

• Clusters are referenced by clusterName (label visible in the Atlas UI). Use cluster operations to view status, metrics, snapshots and to create/update/delete clusters. Call listGroups to discover projects and listGroupClusters to discover clusters and their clusterName values.
• Backups and snapshots are tied to a cluster; snapshot and restore operations expect a clusterName and snapshot/restore job IDs. Some endpoints differ by cluster type (shared M2/M5 vs dedicated), so choose the matching snapshots/restore endpoint.
• Database users are addressed by username and databaseName together. Some authentication methods change the required databaseName and username format—see the DB user section.
• Network objects (containers, private endpoints) require containerId or endpointId; those are obtained from list endpoints for containers or private endpoints.
• Federation and identity-provider resources live under a federationSettingsId and sometimes also an orgId. Identity provider IDs can be legacy 20‑hex or current 24‑hex depending on API version.

Always call the relevant list operation first to get the exact identifier you need (for example listGroups, listGroupClusters, listGroupAlerts, listGroupClusterSearchIndexes, listGroupAiModelApiKeys).

Common entry points (what to call first)

Use these to discover IDs and names before taking action:

• Get the project id(s): listGroups → project id (24 hex). Most workflows start here.
• Get clusters in a project: listGroupClusters → use clusterName for cluster‑scoped calls.
• Find alerts/alert configs: listGroupAlerts and listGroupAlertConfigs → alertId / alertConfigId.
• Find snapshots/restore jobs: listGroupClusterSnapshots (or listGroupClusterBackupSnapshots/listGroupClusterBackupTenantSnapshots) → snapshotId; listGroupClusterBackupRestoreJobs → restoreJobId.
• Find database users and certificates: getGroupDatabaseUser (for a specific user) or listGroupDatabaseUserCerts (certs), or call listGroupDatabaseUsers (if available) to enumerate users.
• Find search indexes: listGroupClusterSearchIndex or listGroupClusterFtsIndex → index indexId or indexName.
• Federation / IdP: listFederationSettingIdentityProviders and listFederationSettingConnectedOrgConfigs to discover federationSettingsId, identityProviderId, and connected orgs.

Typical user requests and the operation sequences

Below are the most common tasks users ask an assistant to perform and the minimal, reproducible operation sequences to accomplish them.

Project / cluster lifecycle

• Create a project: call createGroup with body: Group.
• Create a cluster: call createGroupCluster with groupId and a LegacyAtlasCluster body (cluster label becomes clusterName). After create, call getGroupCluster to verify.
• Update a cluster: call updateGroupCluster with groupId, clusterName and the updated cluster body. Consider the Use-Effective-Instance-Fields flag: when true the response includes the original requested hardware fields and separate effective fields; when false you see the current operational values. Note: with autoscaling enabled, that header can affect whether replicationSpec changes are applied.
• Delete a cluster: call deleteGroupCluster with groupId and clusterName. Use the retainBackups flag if you must preserve cloud backups.

Database users and authentication

• Create a DB user: call createGroupDatabaseUser with groupId and the user body. The request must include databaseName (authentication database) and username.
• Delete a DB user: call deleteGroupDatabaseUser with groupId, databaseName, and username.
• Username and databaseName rules (non-obvious):
  • SCRAM/OIDC Workforce users authenticate against admin and use an alphanumeric username.
  • External methods (AWS IAM, x.509, LDAP, OIDC Workload) often use $external as databaseName and require special username formats:
    • AWS IAM: username is the ARN for ROLE or USER types.
    • x.509: username is an RFC‑2253 DN.
    • LDAP: username is an RFC‑2253 DN for USER/GROUP.
    • OIDC Workforce/Workload: format is <Atlas OIDC IdP ID>/<IdP group or user name> for the IdP Group/User types.

Always pick the correct databaseName and username format for the authentication method—these determine which delete/get/update endpoints to call and whether the operation will succeed.

Network & IP access

• Inspect current project IP access list: listGroupAccessListEntries (use groupId).
• Remove an access entry: deleteGroupAccessListEntry with groupId and entryValue (the API accepts an IP, CIDR, or cloud security construct). Use the list endpoint first to confirm the exact entryValue string returned by Atlas.
• Create containers/private endpoints: use createGroupContainer for network containers and createGroupBackupPrivateEndpoint / createGroupEncryptionAtRestPrivateEndpoint for private endpoints; find their IDs via listGroupContainers or listGroupBackupPrivateEndpoints.

Backups & snapshots

• Take an on‑demand snapshot: call takeGroupClusterBackupSnapshots with groupId, clusterName, and the snapshot request body; snapshot responses will include snapshotId.
• List snapshots: call listGroupClusterSnapshots (or the appropriate tenant/specific snapshot list) with groupId and clusterName to find snapshotId values.
• Create a restore job: createGroupClusterBackupRestoreJob (for cloud backup) or createGroupClusterBackupTenantRestore (for M2/M5) — pick the endpoint matching the cluster type.
• Cancel a restore job: cancelGroupClusterBackupRestoreJob with groupId, clusterName, and restoreJobId.
• Export or update snapshot export buckets and jobs: use createGroupClusterBackupExport, createGroupBackupExportBucket, updateGroupBackupExportBucket, and getGroupClusterBackupExport to manage export jobs and buckets.

Note: Atlas exposes legacy and newer backup endpoints; choose the set that matches your cluster type and the snapshot/restore objects returned by the list/get endpoints.

Alerts & incident handling

• Create alert rules: createGroupAlertConfig with groupId and a GroupAlertsConfig body.
• Toggle an alert config on/off: toggleGroupAlertConfig with groupId and alertConfigId (body: AlertsToggle).
• Acknowledge an alert: acknowledgeGroupAlert with groupId and alertId (body: AlertView).
• List open alerts: listGroupAlerts with groupId and optional status filter. Use getGroupAlert to retrieve a single alert.

Atlas Search indexes

• List indexes for a collection: listGroupClusterSearchIndex (or FTS variant) with groupId, clusterName, databaseName, collectionName → returns indexId and indexName.
• Create an index: createGroupClusterSearchIndex with groupId, clusterName, and SearchIndexCreateRequest body.
• Update by id: updateGroupClusterSearchIndex with groupId, clusterName, indexId, and SearchIndexUpdateRequest body.
• Delete by id or by name: use deleteGroupClusterSearchIndex (by indexId) or deleteGroupClusterSearchIndexByName (by indexName plus db/collection); list first to obtain the correct identifier.

Federation and identity providers

• Discover federations and their identity providers: listFederationSettingIdentityProviders (needs federationSettingsId) and listFederationSettingConnectedOrgConfigs.
• Identity provider IDs: older API versions use 20‑hex ids while newer versions use 24‑hex ids—check the identityProviderId returned by the list call before using it in update/delete operations.
• Manage role mappings and connected orgs using createFederationSettingConnectedOrgConfigRoleMapping, listFederationSettingConnectedOrgConfigRoleMappings, and the matching update/delete operations. Many federation operations also accept or require an orgId.

AI model API keys and rate limits

• List, create, update, delete AI model API keys with listGroupAiModelApiKeys, createGroupAiModelApiKey, updateGroupAiModelApiKey, and deleteGroupAiModelApiKey (operate using the apiKeyId).
• Rate limits: use listGroupAiModelRateLimits, getGroupAiModelRateLimit (by modelGroupName), and updateGroupAiModelRateLimit to inspect and change model rate limits. resetGroupAiModelRateLimits clears limits for a group.

Logs, metrics, and query shapes

• Download logs: downloadGroupClusterLog returns either plain text or base64 (response body may be $text, $base64, or a string). Use the cluster host hostName, logName and optional start/end timestamps.
• Metrics and coll stats: use the cluster metrics endpoints (for example listGroupClusterCollStatMeasurements) with clusterName, databaseName, collectionName, and either a start/end window or an ISO‑8601 period to retrieve time series.
• Query shapes: obtain SHA256 query shape hashes from MongoDB logs or $queryStats/$explain, then use listGroupClusterQueryShapes, getGroupClusterQueryShape, updateGroupClusterQueryShape and insight endpoints to manage and inspect rejected or recorded query shapes.

Responses and multiple schemas

Many operations return different schemas depending on API version or cluster type (for example getGroupCluster can return legacy or advanced cluster descriptions). After each call inspect the returned object to determine the appropriate next step—IDs, names, and nested fields differ across responses. When a list call returns items, prefer using the exact identifier delivered in that list (do not try to guess a different id format).

Non‑obvious gotchas and quirks

• groupId vs orgId: group and project are synonymous in Atlas. groupId is required for almost every project‑scoped call. orgId is used for organization‑level resources (API keys assignment, federation connected orgs). Do not mix them.
• cluster identity: Atlas uses human‑readable clusterName for most cluster endpoints rather than a separate numeric or hex cluster id. Use listGroupClusters to confirm exact label and casing before calling cluster operations.
• Snapshot/restore endpoints vary by cluster family: shared (M2/M5) vs dedicated clusters have different endpoints and response shapes—use list/get to determine which object model your cluster uses and call matching endpoints (e.g., tenant vs disk backup endpoints).
• Identity provider IDs change by API version: some federation APIs expect a 20‑hex legacy id; newer endpoints expect 24‑hex. Discover the id via the list operation you call and pass it through unchanged.
• Use-Effective-Instance-Fields header behavior: setting it to true changes how hardware fields are represented in responses (client requested vs effective). When autoscaling is enabled, Atlas may ignore replicationSpec changes if this header is used—be explicit about your intent when updating replication specs.
• Database user deletion requires both databaseName and username: the right databaseName depends on auth method (admin for SCRAM/Workforce, $external for external methods). Using the wrong databaseName will not target the intended DB user.
• Deleting access list entries: the entryValue returned in list responses is the canonical string to use for deletion. Remove using that exact string to avoid mismatches.
• Envelope and pretty flags: many endpoints accept envelope and pretty. envelope=true wraps the response and adds a status field—use it only when the caller expects this wrapper format.
• Log/download payloads: downloadGroupClusterLog and similar download endpoints may return plain text or base64 branches in the response. Inspect which field is present to obtain the text payload.

Quick checklist before calling destructive operations

• Confirm groupId from listGroups and verify project membership.
• Confirm exact clusterName via listGroupClusters before operations that require it.
• For snapshot/restore operations, list snapshots first to get snapshotId and confirm cluster type (tenant vs disk backup).
• For DB user operations, confirm databaseName and username formats appropriate to the authentication method.
• For index or alert work, list the resources first to obtain indexId / alertConfigId / alertId before delete/acknowledge/update.

Final notes

Workflows in Atlas are discovery → operate → verify. Use the list/get endpoints to discover canonical IDs and names, call the create/update/delete operation that matches the resource type and cluster family, then verify the result with a get/list call. Pay attention to the few header and parameter nuances described above (effective instance fields, auth database for users, identity provider id formats, and backup family differences) — they are the common causes of failed or unexpected operations.