Create One Ephemeral Atlas Cluster | Atlas Admin API v2 documentation (preview)

Create One Ephemeral Atlas Cluster Beta PREVIEW

POST /api/atlas/v2/unauth/ephemeralClusters:create

This API is in preview. Breaking changes might be introduced before it is released. Don't use preview APIs in production.

Creates an Atlas Ephemeral cluster and returns its connection and claim details.

An Ephemeral cluster is a temporary Free cluster that you can create and connect to without an Atlas account. Atlas pauses the cluster 2 days after creation and deletes it 7 days after creation unless you claim it to an Atlas account.

Claiming an Ephemeral cluster converts it into a standard Free cluster with no expiration date and moves it into a new or existing Atlas organization. Until you claim the cluster, you can read and write its data but can't perform administrative operations, such as scaling the cluster, adding database users, or changing network access.

Atlas deploys all Ephemeral clusters to AWS us-east-1 and allows connections from any IP address (0.0.0.0/0). To learn more about Ephemeral clusters, see Create an Atlas Ephemeral Cluster in the MongoDB Atlas documentation.

application/vnd.atlas.preview+json

Body

Ephemeral cluster to create. An empty body creates a cluster with the default name.

clusterName string | null

Human-readable label that identifies the Ephemeral cluster. Defaults to Cluster0.

Format should match the following pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]*$.

Responses

201 application/vnd.atlas.preview+json

Created
Hide headers attributes Show headers attributes
- RateLimit-Limit
  
  The maximum number of requests that a user can make within a specific time window.
- RateLimit-Remaining
  
  The number of requests remaining in the current rate limit window before the limit is reached.
Hide response attributes Show response attributes object
- claimUrl string(uri)
  
  Unique URL for claiming this Ephemeral cluster. Redirects to the Atlas sign-in or registration page, where a user signs in or creates an account to claim the cluster. Valid for 7 days after the cluster is created.
- clusterId string
  
  Unique identifier of the Ephemeral cluster. Use this ID to retrieve the cluster's status and details in a GET request.
- connectionString string
  
  Connection string that uses the mongodb+srv:// protocol to connect to the Ephemeral cluster. This string includes the unredacted SCRAM credentials (username and password) for an automatically generated database user that Atlas grants the built-in readWriteAnyDatabase role.
- expiresAt string(date-time)
  
  Date and time when the cluster will be paused and no longer accessible until it is claimed. This parameter expresses its value in the ISO 8601 timestamp format in UTC.
- status string
  
  Status of the Ephemeral cluster.
  
  Values are ACTIVE or PROVISIONING.
- termsOfService string
  
  Notice that by using this API, you agree to MongoDB's Cloud Terms of Service at https://www.mongodb.com/legal/terms-and-conditions/cloud and Privacy Policy at https://www.mongodb.com/legal/privacy/privacy-policy.
400 application/json

Bad Request.
Hide response attributes Show response attributes object
- badRequestDetail object
  
  Bad request detail.
  
  Hide badRequestDetail attribute Show badRequestDetail attribute object
  
  fields array[object]
  
  Describes all violations in a client request.
  
  Hide fields attributes Show fields attributes object
  
  description string Required
  
  A description of why the request element is bad.
  
  field string Required
  
  A path that leads to a field in the request body.
- detail string | null
  
  Describes the specific conditions or reasons that cause each type of error.
- error integer(int32) Required
  
  HTTP status code returned with this error.
  
  External documentation
- errorCode string Required
  
  Application error code returned with this error.
- parameters array[object]
  
  Parameters used to give more information about the error.
- reason string | null
  
  Application error message returned with this error.
429 application/json

Too Many Requests.
Hide headers attributes Show headers attributes
- RateLimit-Limit
  
  The maximum number of requests that a user can make within a specific time window.
- RateLimit-Remaining
  
  The number of requests remaining in the current rate limit window before the limit is reached.
- Retry-After
  
  The minimum time you should wait, in seconds, before retrying the API request. This header might be returned for 429 or 503 error responses.
Hide response attributes Show response attributes object
- badRequestDetail object
  
  Bad request detail.
  
  Hide badRequestDetail attribute Show badRequestDetail attribute object
  
  fields array[object]
  
  Describes all violations in a client request.
  
  Hide fields attributes Show fields attributes object
  
  description string Required
  
  A description of why the request element is bad.
  
  field string Required
  
  A path that leads to a field in the request body.
- detail string | null
  
  Describes the specific conditions or reasons that cause each type of error.
- error integer(int32) Required
  
  HTTP status code returned with this error.
  
  External documentation
- errorCode string Required
  
  Application error code returned with this error.
- parameters array[object]
  
  Parameters used to give more information about the error.
- reason string | null
  
  Application error message returned with this error.
500 application/json

Internal Server Error.
Hide response attributes Show response attributes object
- badRequestDetail object
  
  Bad request detail.
  
  Hide badRequestDetail attribute Show badRequestDetail attribute object
  
  fields array[object]
  
  Describes all violations in a client request.
  
  Hide fields attributes Show fields attributes object
  
  description string Required
  
  A description of why the request element is bad.
  
  field string Required
  
  A path that leads to a field in the request body.
- detail string | null
  
  Describes the specific conditions or reasons that cause each type of error.
- error integer(int32) Required
  
  HTTP status code returned with this error.
  
  External documentation
- errorCode string Required
  
  Application error code returned with this error.
- parameters array[object]
  
  Parameters used to give more information about the error.
- reason string | null
  
  Application error message returned with this error.

POST /api/atlas/v2/unauth/ephemeralClusters:create

atlas api ephemeralClusters createEphemeralCluster --help

curl --include \
  --header "Accept: application/vnd.atlas.preview+json" \
  --header "Content-Type: application/json" \
  -X POST "https://cloud.mongodb.com/api/atlas/v2/unauth/ephemeralClusters:create" \
  -d '{ <Payload> }'

Request examples

{
  "clusterName": "string"
}

Response examples (201)

# Headers

# Payload
{
  "claimUrl": "https://example.com",
  "clusterId": "string",
  "connectionString": "string",
  "expiresAt": "2026-05-04T09:42:00Z",
  "status": "ACTIVE",
  "termsOfService": "string"
}

Response examples (400)

{
  "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"
}

Response examples (429)

{
  "detail": "(This is just an example, the exception may not be related to this endpoint)",
  "error": 429,
  "errorCode": "RATE_LIMITED",
  "reason": "Too Many Requests"
}

Response examples (500)

{
  "detail": "(This is just an example, the exception may not be related to this endpoint)",
  "error": 500,
  "errorCode": "UNEXPECTED_ERROR",
  "reason": "Internal Server Error"
}