Create One Legacy Backup Restore Job | (Deprecated) Atlas Admin API v1 documentation

Create One Legacy Backup Restore Job Deprecated

POST /api/atlas/v1.0/groups/{groupId}/clusters/{clusterName}/restoreJobs

Restores one legacy backup for one cluster in the specified project. To use this resource, the requesting Service Account or API Key must have the Project Owner role. Effective 23 March 2020, all new clusters can use only Cloud Backups. When you upgrade to 4.2, your backup system upgrades to cloud backup if it is currently set to legacy backup. After this upgrade, all your existing legacy backup snapshots remain available. They expire over time in accordance with your retention policy. Your backup policy resets to the default schedule. If you had a custom backup policy in place with legacy backups, you must re-create it with the procedure outlined in the Cloud Backup documentation. This endpoint doesn't support creating checkpoint restore jobs for sharded clusters, or creating restore jobs for queryable backup snapshots. If you create an automated restore job by specifying delivery.methodName of AUTOMATED_RESTORE in your request body, MongoDB Cloud removes all existing data on the target cluster prior to the restore.

Cloud Backup Documentation

Path parameters

groupId string Required

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

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

Format should match the following pattern: ^([a-f0-9]{24})$.
clusterName string Required

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

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

Query parameters

envelope boolean

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

Default value is false.
pretty boolean

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

Default value is false.

Prettyprint

application/json

Body Required

Legacy backup to restore to one cluster in the specified project.

checkpointId string
Unique 24-hexadecimal digit string that identifies the sharded cluster checkpoint. The checkpoint represents the point in time back to which you want to restore you data. This parameter applies when "delivery.methodName" : "AUTOMATED_RESTORE". Use this parameter with sharded clusters only.
- If you set checkpointId, you can't set oplogInc, oplogTs, snapshotId, or pointInTimeUTCMillis.
- If you provide this parameter, this endpoint restores all data up to this checkpoint to the database you specify in the delivery object.
Format should match the following pattern: ^([a-f0-9]{24})$.
delivery object Required

Method and details that indicate how to deliver the restored snapshot data.
Hide delivery attributes Show delivery attributes object
- expirationHours integer(int32)
  
  Number of hours after the restore job completes that indicates when the Uniform Resource Locator (URL) for the snapshot download file expires. The resource returns this parameter when "delivery.methodName" : "HTTP".
  
  Minimum value is 1.
- maxDownloads integer(int32)
  
  Positive integer that indicates how many times you can use the Uniform Resource Locator (URL) for the snapshot download file. The resource returns this parameter when "delivery.methodName" : "HTTP".
  
  Minimum value is 1.
- methodName string Required
  
  Human-readable label that identifies the means for delivering the data. If you set "delivery.methodName" : "AUTOMATED_RESTORE", you must also set: delivery.targetGroupId and delivery.targetClusterName or delivery.targetClusterId. The response returns "delivery.methodName" : "HTTP" as an automated restore uses HyperText Transport Protocol (HTTP) to deliver the restore job to the target host.
  
  Values are CLIENT_PIT_HTTP, QUERY, AUTOMATED_RESTORE, HTTP, THIRD_PARTY_COPY, CLIENT_PIT_SCP, or SCP.
- targetClusterId string
  Unique 24-hexadecimal digit string that identifies the target cluster. Use the clusterId returned in the response body of the Get All Snapshots and Get a Snapshot endpoints. This parameter applies when "delivery.methodName" : "AUTOMATED_RESTORE".
  
  If the target cluster doesn't have backup enabled, two resources return parameters with empty values:
  
  Get All Snapshots endpoint returns an empty results array without clusterId elements
  
  Get a Snapshot endpoint doesn't return a clusterId parameter.
  
  To return a response with the clusterId parameter, either use the delivery.targetClusterName parameter or enable backup on the target cluster.
  Format should match the following pattern: ^([a-f0-9]{24})$.
- targetClusterName string
  Human-readable label that identifies the target cluster. Use the clusterName returned in the response body of the Get All Snapshots and Get a Snapshot endpoints. This parameter applies when "delivery.methodName" : "AUTOMATED_RESTORE".
  
  If the target cluster doesn't have backup enabled, two resources return parameters with empty values:
  
  Get All Snapshots endpoint returns an empty results array without clusterId elements
  
  Get a Snapshot endpoint doesn't return a clusterId parameter.
  
  To return a response with the clusterId parameter, either use the delivery.targetClusterName parameter or enable backup on the target cluster.
  Format should match the following pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]*$.
- targetGroupId string
  
  Unique 24-hexadecimal digit string that identifies the project that contains the destination cluster for the restore job. The resource returns this parameter when "delivery.methodName" : "AUTOMATED_RESTORE".
  
  Format should match the following pattern: ^([a-f0-9]{24})$.
oplogInc integer(int32)
Thirty-two-bit incrementing ordinal that represents operations within a given second. When paired with oplogTs, this represents the point in time to which MongoDB Cloud restores your data. This parameter applies when "delivery.methodName" : "AUTOMATED_RESTORE".
- If you set oplogInc, you must set oplogTs, and can't set checkpointId, snapshotId, or pointInTimeUTCMillis.
- If you provide this parameter, this endpoint restores all data up to and including this Oplog timestamp to the database you specified in the delivery object.
Minimum value is 1.
oplogTs string
Date and time from which you want to restore this snapshot. This parameter expresses its value in ISO 8601 format in UTC. This represents the first part of an Oplog timestamp. When paired with oplogInc, they represent the last database operation to which you want to restore your data. This parameter applies when "delivery.methodName" : "AUTOMATED_RESTORE". Run a query against local.oplog.rs on your replica set to find the desired timestamp.
- If you set oplogTs, you must set oplogInc, and you can't set checkpointId, snapshotId, or pointInTimeUTCMillis.
- If you provide this parameter, this endpoint restores all data up to and including this Oplog timestamp to the database you specified in the delivery object.
Format should match the following pattern: ^(?:[1-9]\\d{3}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1\\d|2[0-8])|(?:0[13-9]|1[0-2])-(?:29|30)|(?:0[13578]|1[02])-31)|(?:[1-9]\\d(?:0[48]|[2468][048]|[13579][26])|(?:[2468][048]|[13579][26])00)-02-29)T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d{1,9})?(?:Z|[+-][01]\\d:[0-5]\\d)$.
pointInTimeUTCMillis integer(int64)
Timestamp from which you want to restore this snapshot. This parameter expresses its value in the number of milliseconds elapsed since the UNIX epoch. This timestamp must fall within the last 24 hours of the current time. This parameter applies when "delivery.methodName" : "AUTOMATED_RESTORE".
- If you provide this parameter, this endpoint restores all data up to this point in time to the database you specified in the delivery object.
- If you set pointInTimeUTCMillis, you can't set oplogInc, oplogTs, snapshotId, or checkpointId.
Minimum value is 1199145600000.

UNIX Epoch
snapshotId string

Unique 24-hexadecimal digit string that identifies the snapshot to restore. If you set snapshotId, you can't set oplogInc, oplogTs, pointInTimeUTCMillis, or checkpointId.

Format should match the following pattern: ^([a-f0-9]{24})$.

Responses

200 application/json

OK
Hide response attributes Show response attributes object
- links array[object]
  
  List of one or more Uniform Resource Locators (URLs) that point to API sub-resources, related API resources, or both. RFC 5988 outlines these relationships.
  
  Web Linking Specification (RFC 5988)
  
  Hide links attributes Show links attributes object
  
  href string
  
  Uniform Resource Locator (URL) that points another API resource to which this response has some relationship. This URL often begins with https://cloud.mongodb.com/api/atlas.
  
  rel string
  
  Uniform Resource Locator (URL) that defines the semantic relationship between this resource and another API resource. This URL often begins with https://cloud.mongodb.com/api/atlas.
- results array[object]
  
  List of returned documents that MongoDB Cloud provides when completing this request.
  
  Hide results attributes Show results attributes object
  
  batchId string
  
  Unique 24-hexadecimal digit string that identifies the batch to which this restore job belongs. This parameter exists only for a sharded cluster restore.
  
  Format should match the following pattern: ^([a-f0-9]{24})$.
  
  clusterId string
  
  Unique 24-hexadecimal digit string that identifies the cluster with the snapshot you want to return. This parameter returns for restore clusters.
  
  Format should match the following pattern: ^([a-f0-9]{24})$.
  
  clusterName string
  
  Human-readable label that identifies the cluster containing the snapshots you want to retrieve.
  
  Format should match the following pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]*$.
  
  created string(date-time)
  
  Date and time when someone requested this restore job. This parameter expresses its value in the ISO 8601 timestamp format in UTC.
  
  delivery object Required
  
  Method and details that indicate how to deliver the restored snapshot data.
  
  Hide delivery attributes Show delivery attributes object
  
  authHeader string
  
  Header name to use when downloading the restore, used with "delivery.methodName" : "HTTP".
  
  authValue string
  
  Header value to use when downloading the restore, used with "delivery.methodName" : "HTTP".
  
  expirationHours integer(int32)
  
  Number of hours after the restore job completes that indicates when the Uniform Resource Locator (URL) for the snapshot download file expires. The resource returns this parameter when "delivery.methodName" : "HTTP".
  
  Minimum value is 1.
  
  expires string(date-time)
  
  Date and time when the Uniform Resource Locator (URL) for the snapshot download file expires. This parameter expresses its value in the ISO 8601 timestamp format in UTC. The resource returns this parameter when "delivery.methodName" : "HTTP".
  
  maxDownloads integer(int32)
  
  Positive integer that indicates how many times you can use the Uniform Resource Locator (URL) for the snapshot download file. The resource returns this parameter when "delivery.methodName" : "HTTP".
  
  Minimum value is 1.
  
  methodName string Required
  
  Human-readable label that identifies the means for delivering the data. If you set "delivery.methodName" : "AUTOMATED_RESTORE", you must also set: delivery.targetGroupId and delivery.targetClusterName or delivery.targetClusterId. The response returns "delivery.methodName" : "HTTP" as an automated restore uses HyperText Transport Protocol (HTTP) to deliver the restore job to the target host.
  
  Values are CLIENT_PIT_HTTP, QUERY, AUTOMATED_RESTORE, HTTP, THIRD_PARTY_COPY, CLIENT_PIT_SCP, or SCP.
  
  statusName string
  
  State of the downloadable snapshot file when MongoDB Cloud received this request.
  
  Values are NOT_STARTED, IN_PROGRESS, READY, FAILED, INTERRUPTED, EXPIRED, MAX_DOWNLOADS_EXCEEDED, or PENDING.
  
  targetClusterId string
  
  Unique 24-hexadecimal digit string that identifies the target cluster. Use the clusterId returned in the response body of the Get All Snapshots and Get a Snapshot endpoints. This parameter applies when "delivery.methodName" : "AUTOMATED_RESTORE".
  
  If the target cluster doesn't have backup enabled, two resources return parameters with empty values:
  
  Get All Snapshots endpoint returns an empty results array without clusterId elements
  
  Get a Snapshot endpoint doesn't return a clusterId parameter.
  
  To return a response with the clusterId parameter, either use the delivery.targetClusterName parameter or enable backup on the target cluster.
  
  Format should match the following pattern: ^([a-f0-9]{24})$.
  
  targetClusterName string
  
  Human-readable label that identifies the target cluster. Use the clusterName returned in the response body of the Get All Snapshots and Get a Snapshot endpoints. This parameter applies when "delivery.methodName" : "AUTOMATED_RESTORE".
  
  If the target cluster doesn't have backup enabled, two resources return parameters with empty values:
  
  Get All Snapshots endpoint returns an empty results array without clusterId elements
  
  Get a Snapshot endpoint doesn't return a clusterId parameter.
  
  To return a response with the clusterId parameter, either use the delivery.targetClusterName parameter or enable backup on the target cluster.
  
  Format should match the following pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]*$.
  
  targetGroupId string
  
  Unique 24-hexadecimal digit string that identifies the project that contains the destination cluster for the restore job. The resource returns this parameter when "delivery.methodName" : "AUTOMATED_RESTORE".
  
  Format should match the following pattern: ^([a-f0-9]{24})$.
  
  url string Deprecated
  
  Uniform Resource Locator (URL) from which you can download the restored snapshot data. Url includes the verification key. The resource returns this parameter when "delivery.methodName" : "HTTP".
  
  urlV2 string
  
  Uniform Resource Locator (URL) from which you can download the restored snapshot data. This should be preferred over url. The verification key must be sent as an HTTP header. The resource returns this parameter when "delivery.methodName" : "HTTP".
  
  encryptionEnabled boolean
  
  Flag that indicates whether someone encrypted the data in the restored snapshot.
  
  groupId string
  
  Unique 24-hexadecimal digit string that identifies the project that owns the snapshots.
  
  Format should match the following pattern: ^([a-f0-9]{24})$.
  
  hashes array[object]
  
  List that contains documents mapping each restore file to a hashed checksum. This parameter applies after you download the corresponding delivery.url. If "methodName" : "HTTP", this list contains one object that represents the hash of the .tar.gz file.
  
  Key and value pair that map one restore file to one hashed checksum. This parameter applies after you download the corresponding delivery.url.
  
  Hide hashes attributes Show hashes attributes object
  
  fileName string
  
  Human-readable label that identifies the hashed file.
  
  hash string
  
  Hashed checksum that maps to the restore file.
  
  links array[object]
  
  List of one or more Uniform Resource Locators (URLs) that point to API sub-resources, related API resources, or both. RFC 5988 outlines these relationships.
  
  Web Linking Specification (RFC 5988)
  
  Hide links attributes Show links attributes object
  
  href string
  
  Uniform Resource Locator (URL) that points another API resource to which this response has some relationship. This URL often begins with https://cloud.mongodb.com/api/atlas.
  
  rel string
  
  Uniform Resource Locator (URL) that defines the semantic relationship between this resource and another API resource. This URL often begins with https://cloud.mongodb.com/api/atlas.
  
  typeName string
  
  Human-readable label that identifies the hashing algorithm used to compute the hash value.
  
  Value is SHA1.
  
  id string
  
  Unique 24-hexadecimal digit string that identifies the restore job.
  
  Format should match the following pattern: ^([a-f0-9]{24})$.
  
  links array[object]
  
  List of one or more Uniform Resource Locators (URLs) that point to API sub-resources, related API resources, or both. RFC 5988 outlines these relationships.
  
  Web Linking Specification (RFC 5988)
  
  Hide links attributes Show links attributes object
  
  href string
  
  Uniform Resource Locator (URL) that points another API resource to which this response has some relationship. This URL often begins with https://cloud.mongodb.com/api/atlas.
  
  rel string
  
  Uniform Resource Locator (URL) that defines the semantic relationship between this resource and another API resource. This URL often begins with https://cloud.mongodb.com/api/atlas.
  
  masterKeyUUID string(uuid)
  
  Universally Unique Identifier (UUID) that identifies the Key Management Interoperability (KMIP) master key used to encrypt the snapshot data. This parameter applies only when "encryptionEnabled" : "true".
  
  snapshotId string
  
  Unique 24-hexadecimal digit string that identifies the snapshot to restore. If you set snapshotId, you can't set oplogInc, oplogTs, pointInTimeUTCMillis, or checkpointId.
  
  Format should match the following pattern: ^([a-f0-9]{24})$.
  
  statusName string
  
  Human-readable label that identifies the status of the downloadable file at the time of the request.
  
  Values are IN_PROGRESS, BROKEN, KILLED, or FINISHED.
  
  timestamp object
  
  BSON timestamp that indicates when the checkpoint token entry in the oplog occurred.
  
  Hide timestamp attributes Show timestamp attributes object
  
  increment integer(int32)
  
  Order of the database operation that the oplog recorded at specific date and time.
  
  Minimum value is 1199145600.
  
  date string(date-time)
  
  Date and time when the oplog recorded this database operation. This parameter expresses its value in the ISO 8601 timestamp format in UTC.
- totalCount integer(int32)
  
  Total number of documents available. MongoDB Cloud omits this value if includeCount is set to false. The total number is an estimate and may not be exact.
  
  Minimum value is 0.
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
  
  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
  
  Application error message returned with this error.
401 application/json

Unauthorized.
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
  
  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
  
  Application error message returned with this error.
403 application/json

Forbidden.
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
  
  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
  
  Application error message returned with this error.
404 application/json

Not Found.
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
  
  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
  
  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
  
  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
  
  Application error message returned with this error.

POST /api/atlas/v1.0/groups/{groupId}/clusters/{clusterName}/restoreJobs

curl \ --request POST 'https://cloud.mongodb.com/api/atlas/v1.0/groups/32b6e34b3d91647abb20e7b8/clusters/{clusterName}/restoreJobs' \ --header "Authorization: Bearer $ACCESS_TOKEN" \ --header "Content-Type: application/json" \ --data '{"checkpointId":"32b6e34b3d91647abb20e7b8","delivery":{"expirationHours":42,"maxDownloads":42,"methodName":"CLIENT_PIT_HTTP","targetClusterId":"32b6e34b3d91647abb20e7b8","targetClusterName":"string","targetGroupId":"32b6e34b3d91647abb20e7b8"},"oplogInc":42,"oplogTs":"string","pointInTimeUTCMillis":42,"snapshotId":"32b6e34b3d91647abb20e7b8"}'

Request examples

{ "checkpointId": "32b6e34b3d91647abb20e7b8", "delivery": { "expirationHours": 42, "maxDownloads": 42, "methodName": "CLIENT_PIT_HTTP", "targetClusterId": "32b6e34b3d91647abb20e7b8", "targetClusterName": "string", "targetGroupId": "32b6e34b3d91647abb20e7b8" }, "oplogInc": 42, "oplogTs": "string", "pointInTimeUTCMillis": 42, "snapshotId": "32b6e34b3d91647abb20e7b8" }

Response examples (200)

{ "links": [ { "href": "https://cloud.mongodb.com/api/atlas", "rel": "self" } ], "results": [ { "batchId": "32b6e34b3d91647abb20e7b8", "clusterId": "32b6e34b3d91647abb20e7b8", "clusterName": "string", "created": "2025-05-04T09:42:00Z", "delivery": { "authHeader": "string", "authValue": "string", "expirationHours": 42, "expires": "2025-05-04T09:42:00Z", "maxDownloads": 42, "methodName": "CLIENT_PIT_HTTP", "statusName": "NOT_STARTED", "targetClusterId": "32b6e34b3d91647abb20e7b8", "targetClusterName": "string", "targetGroupId": "32b6e34b3d91647abb20e7b8", "url": "string", "urlV2": "string" }, "encryptionEnabled": true, "groupId": "32b6e34b3d91647abb20e7b8", "hashes": [ { "fileName": "string", "hash": "string", "links": [ { "href": "https://cloud.mongodb.com/api/atlas", "rel": "self" } ], "typeName": "SHA1" } ], "id": "32b6e34b3d91647abb20e7b8", "links": [ { "href": "https://cloud.mongodb.com/api/atlas", "rel": "self" } ], "masterKeyUUID": "string", "snapshotId": "32b6e34b3d91647abb20e7b8", "statusName": "IN_PROGRESS", "timestamp": { "increment": 1199145600, "date": "2025-05-04T09:42:00Z" } } ], "totalCount": 42 }

Response examples (400)

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

Response examples (401)

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

Response examples (403)

{ "error": 403, "detail": "(This is just an example, the exception may not be related to this endpoint)", "reason": "Forbidden", "errorCode": "CANNOT_CHANGE_GROUP_NAME" }

Response examples (404)

{ "error": 404, "detail": "(This is just an example, the exception may not be related to this endpoint) Cannot find resource AWS", "reason": "Not Found", "errorCode": "RESOURCE_NOT_FOUND" }

Response examples (500)

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