Modify Cloud Backup Backup Policy¶

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.

The Atlas API authenticates using HTTP Digest Authentication. Provide a programmatic API public key and corresponding private key as the username and password when constructing the HTTP request.

To learn how to configure API access for an Atlas project, see Configure Atlas API Access.

All requests to this endpoint must originate from an IP address in the organization's API access list.

Tip

Resource¶

PATCH /groups/{GROUP-ID}/clusters/{CLUSTER-NAME}/backup/schedule

Request Parameters¶

Request Path Parameters¶

Parameter	Type	Description
`GROUP-ID`	string	Unique identifier of the project for the Atlas cluster.
`CLUSTER-NAME`	string	Name of the Atlas cluster that contains the snapshot you want to retrieve.

Request Query Parameters¶

This endpoint might use any of the HTTP request query parameters available to all Atlas API resources. All of these are optional.

Name Type Necessity Description Default

pretty boolean Optional Flag indicating whether the response body should be in a prettyprint format. false

envelope

boolean

Optional

Flag indicating if Atlas should wrap the response in a JSON envelope.

This option may be needed for some API clients. These clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query.

For endpoints that return one result, the response body includes:

status	HTTP response code
envelope	Expected response body

false

Request Body Parameters¶

Name	Type	Necessity	Description
`policies[]`	array	Required	Array containing a document for each backup policy item in the desired updated backup policy.
`policies[i]` `.id`	string	Required	Unique identifier of the backup policy that you want to update.
`policies[i]` `.policyItems[]`	array	Required	Array of backup policy items.
`policies[i]` `.policyItems[n]` `.frequencyInterval`	number	Required	Desired frequency of the new backup policy item specified by `frequencyType`. A value of `1` specifies the first instance of the corresponding `frequencyType`. Example In a monthly policy item, `1` indicates that the monthly snapshot occurs on the first day of the month. In a weekly policy item, `1` indicates that the weekly snapshot occurs on Monday. The following frequency values are valid: Hourly: `1`, `2,`, `4`, `6`, `8`, and `12`. Note The only accepted value you can set for frequency interval with NVMe clusters is `12`. Daily: `1` Weekly: `1` through `7`, where `1` is Monday and `7` is Sunday. Monthly: `1` through `28` and `40`, where `1` is the first day of the month and `40` is the last day of the month.
`policies[i]` `.policyItems[n]` `.frequencyType`	string	Required	Frequency associated with the backup policy item. One of the following values: `hourly`, `daily`, `weekly` or `monthly`. Note You cannot specify multiple `hourly` and `daily` backup policy items.
`policies[i]` `.policyItems[n]` `.id`	string	Required	Unique identifier of the backup policy item.
`policies[i]` `.policyItems[n]` `.retentionUnit`	string	Required	Scope of the backup policy item: `days`, `weeks`, or `months`.
`policies[i]` `.policyItems[n]` `.retentionValue`	string	Required	Value to associate with `retentionUnit`. Note Atlas requires that the value specified for `retentionValue` for less frequent policy items be equal to or larger than the value specified for more frequent policy items. For example, if the hourly policy item specifies a retention of two days, the retention for the weekly policy item must be two days or greater.
`referenceHourOfDay`	number	Optional	UTC Hour of day between `0` and `23`, inclusive, representing which hour of the day that Atlas takes snapshots for backup policy items.
`referenceMinuteOfHour`	number	Optional	UTC Minutes after `referenceHourOfDay` that Atlas takes snapshots for backup policy items. Must be between `0` and `59`, inclusive.
`restoreWindowDays`	number	Optional	Number of days back in time you can restore to with Continuous Cloud Backup accuracy. Must be a positive, non-zero integer. Applies to continuous cloud backups only.
`updateSnapshots`	boolean	Optional	Specify `true` to apply the retention changes in the updated backup policy to snapshots that Atlas took previously.

Response¶

Name	Type	Description
`clusterId`	string	Unique identifier of the Atlas cluster.
`clusterName`	string	Name of the Atlas cluster.
`links`	array	One or more links to sub-resources and/or related resources. The relations between URL s are explained in the Web Linking Specification
`nextSnapshot`	string	Timestamp in the number of seconds that have elapsed since the UNIX epoch when Atlas takes the next snapshot.
`policies[]`	array	Unique identifier for the snapshot and an array of backup policy items.
`policies[i]` `.id`	string	Unique identifier of the backup policy.
`policies[i]` `.policyItems[]`	array	Array of backup policy items.
`policies[i]` `.policyItems[n]` `.frequencyInterval`	number	Desired frequency of the new backup policy item specified by `frequencyType`.
`policies[i]` `.policyItems[n]` `.frequencyType`	string	Frequency associated with the backup policy item. One of the following values: `hourly`, `daily`, `weekly` or `monthly`.
`policies[i]` `.policyItems[n]` `.id`	string	Unique identifier of the backup policy item.
`policies[i]` `.policyItems[n]` `.retentionUnit`	string	Metric of duration of the backup policy item: `days`, `weeks`, or `months`.
`policies[i]` `.policyItems[n]` `.retentionValue`	number	Duration for which the backup is kept. Associated with `retentionUnit`.
`referenceHourOfDay`	number	UTC Hour of day between `0` and `23` representing which hour of the day that Atlas takes a snapshot.
`referenceMinuteOfHour`	number	UTC Minute of day between `0` and `59` representing which minute of the `referenceHourOfDay` that Atlas takes the snapshot.
`restoreWindowDays`	number	Number of days back in time you can restore to with Continuous Cloud Backup accuracy. Must be a positive, non-zero integer. Applies to continuous cloud backups only.
`updateSnapshots`	boolean	Flag indicating if updates to retention in the backup policy were applied to snapshots that Atlas took earlier. If set to `true`, the retention changes were applied to earlier snapshots.

Example Request¶

1 curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest --include \
2   --header "Accept: application/json" \
3   --header "Content-Type: application/json" \
4   --request PATCH "https://cloud.mongodb.com/api/atlas/v1.0/groups/5b6212af90dc76637950a2c6/clusters/MyCluster/backup/schedule" \
5   --data '
6     {
7       "referenceHourOfDay": 12,
8       "referenceMinuteOfHour": 30,
9       "policies": [
10       {
11          "id": "5c95242c87d9d636e70c28ef",
12          "policyItems": [
13            {
14              "id": "5c95242c87d9d636e70c28f0",
15              "frequencyType": "hourly",
16              "frequencyInterval": 6,
17              "retentionValue": 2,
18              "retentionUnit": "days"
19            },
20            {
21              "id": "5c95242c87d9d636e70c28f2",
22              "frequencyType": "weekly",
23              "frequencyInterval": 1,
24              "retentionValue": 3,
25              "retentionUnit": "weeks"
26            }
27          ]
28        }
29      ],
30      "updateSnapshots": true
31     }'

Example Response¶

1 {
2   "clusterId" : "5c94f6ea80eef5617167224d",
3   "clusterName" : "Cluster0",
4   "links" : [ {
5     "href" : "https://cloud.mongodb.com/api/atlas/v1.0/groups/5b6212af90dc76637950a2c6/clusters/Cluster0/backup/schedule",
6     "rel" : "self"
7   }, {
8     "href" : "https://cloud.mongodb.com/api/atlas/v1.0/groups/5b6212af90dc76637950a2c6",
9     "rel" : "http://mms.mongodb.com/group"
10   } ],
11   "nextSnapshot" : "2019-04-03T18:30:08Z",
12   "policies" : [ {
13     "id" : "5c95242c87d9d636e70c28ef",
14     "policyItems" : [ {
15       "frequencyInterval" : 6,
16       "frequencyType" : "hourly",
17       "id" : "5c95242c87d9d636e70c28f0",
18       "retentionUnit" : "days",
19       "retentionValue" : 2
20     }, {
21       "frequencyInterval" : 1,
22       "frequencyType" : "weekly",
23       "id" : "5c95242c87d9d636e70c28f2",
24       "retentionUnit" : "weeks",
25       "retentionValue" : 3
26     } ]
27   } ],
28   "referenceHourOfDay" : 12,
29   "referenceMinuteOfHour" : 30
30 }

Give Feedback

← Get Cloud Backup Schedule Shared-Tier Snapshots →

1	curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest --include \
2	--header "Accept: application/json" \
3	--header "Content-Type: application/json" \
4	--request PATCH "https://cloud.mongodb.com/api/atlas/v1.0/groups/5b6212af90dc76637950a2c6/clusters/MyCluster/backup/schedule" \
5	--data '
6	{
7	"referenceHourOfDay": 12,
8	"referenceMinuteOfHour": 30,
9	"policies": [
10	{
11	"id": "5c95242c87d9d636e70c28ef",
12	"policyItems": [
13	{
14	"id": "5c95242c87d9d636e70c28f0",
15	"frequencyType": "hourly",
16	"frequencyInterval": 6,
17	"retentionValue": 2,
18	"retentionUnit": "days"
19	},
20	{
21	"id": "5c95242c87d9d636e70c28f2",
22	"frequencyType": "weekly",
23	"frequencyInterval": 1,
24	"retentionValue": 3,
25	"retentionUnit": "weeks"
26	}
27	]
28	}
29	],
30	"updateSnapshots": true
31	}'

1	{
2	"clusterId" : "5c94f6ea80eef5617167224d",
3	"clusterName" : "Cluster0",
4	"links" : [ {
5	"href" : "https://cloud.mongodb.com/api/atlas/v1.0/groups/5b6212af90dc76637950a2c6/clusters/Cluster0/backup/schedule",
6	"rel" : "self"
7	}, {
8	"href" : "https://cloud.mongodb.com/api/atlas/v1.0/groups/5b6212af90dc76637950a2c6",
9	"rel" : "http://mms.mongodb.com/group"
10	} ],
11	"nextSnapshot" : "2019-04-03T18:30:08Z",
12	"policies" : [ {
13	"id" : "5c95242c87d9d636e70c28ef",
14	"policyItems" : [ {
15	"frequencyInterval" : 6,
16	"frequencyType" : "hourly",
17	"id" : "5c95242c87d9d636e70c28f0",
18	"retentionUnit" : "days",
19	"retentionValue" : 2
20	}, {
21	"frequencyInterval" : 1,
22	"frequencyType" : "weekly",
23	"id" : "5c95242c87d9d636e70c28f2",
24	"retentionUnit" : "weeks",
25	"retentionValue" : 3
26	} ]
27	} ],
28	"referenceHourOfDay" : 12,
29	"referenceMinuteOfHour" : 30
30	}