Backups API reference
Reference documentation for the Backups API.
The Backups API lets you enable or disable backups for a dataset, list its backups, and fetch a backup's files for download. Backups are off by default, and you can enable them only if your project's plan includes the backups feature.
Authentication
All requests must be authenticated. To enable or disable backups, the user or token needs the update grant on sanity.project.datasets. To list backups or fetch a backup, it needs the update grant on sanity.project, so a token without that grant receives a 401 response.
Base API server URL
Sanity API base URL
https://api.sanity.io/{apiVersion}/projects/{projectId}Variables
- projectIdstringdefault:
"projectId"Project ID
- apiVersionstringdefault:
"v2025-02-19"API version
Endpoints
Enable or disable backups
/datasets/{datasetName}/settings/backupsPath parameters
Name of the dataset
Request body application/json
Enable or disable backups
application/json{
"enabled": true
}Responses
Successfully updated backup settings
The request body is invalid, or the project's plan doesn't include backups: Your current plan does not include the backups feature.
The request has no valid session, or the user is missing the update grant on sanity.project.datasets: User is missing required grant sanity.project.datasets/update to perform this operation.
The project or dataset doesn't exist (Project not found or Dataset not found), or the API version is earlier than v2024-02-21.
List backups
/datasets/{datasetName}/backupsPath parameters
Name of the dataset
Query parameters
Max number of backups returned. The response contains the most recent backups, ordered oldest first.
- afterstring (date)
Only return backups created on or after this date (
YYYY-MM-DD). Matched against the date in the backup ID. - beforestring (date)
Only return backups created before this date (
YYYY-MM-DD). Backups from this date are excluded. Matched against the date in the backup ID.
Responses
List of backups
The most recent backups, up to
limit, ordered oldest first.The
limitused for the request. This is the default of 10 if you didn't pass one.
application/json{
"backups": [
{
"id": "2024-02-02-19083f95-1741-4e29-997a-76b56c773e24",
"createdAt": "2024-02-02T14:13:06Z"
}
],
"limit": 20
}limit isn't an integer from 1 to 100, or after or before isn't a YYYY-MM-DD date. The message field describes the problem, for example limit must be between 1 and 100.
The request has no valid session, the user isn't a member of the project, or the user is missing the update grant on sanity.project. A project ID that doesn't exist also returns 401. The body is {"code": 401, "message": "Unauthorized"}, with no detail about which check failed.
The dataset doesn't exist, or the API version is earlier than v2024-02-21.
Get a backup
/datasets/{datasetName}/backups/{backupId}This endpoint is primarily designed for use through the Sanity CLI sanity backups download command, which handles paging, downloading all files, and constructing a tarball in the format expected by sanity datasets import.
Path parameters
Name of the dataset
ID of the backup
Query parameters
- nextCursorstring
The
nextCursorvalue from the previous page's response. Omit it to fetch the first page. Max number of files returned per page
Responses
Backup details
Total number of files in the backup, across all pages.
Cursor for the next page of files. Pass it as the
nextCursorquery parameter. An empty string means there are no more pages.
application/json{
"createdAt": "2023-12-12T06:03:01Z",
"totalFiles": 1021,
"files": [
{
"name": "document1",
"url": "https://storage.googleapis.com/example-bucket/document1?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=example%40example-project.iam.gserviceaccount.com%2F20181026%2Fus-central1%2Fstorage%2Fgoog4_request&X-Goog-Date=20181026T181309Z&X-Goog-Expires=86400&X-Goog-SignedHeaders=host&X-Goog-Signature=247a2aa45f169edf4d187d54e7cc46e4731b1e6273242c4f4c39a1d2507a0e58706e25e3a85a7dbb891d62afa8496def8e260c1db863d9ace85ff0a184b894b117fe46d1225c82f2aa19efd52cf21d3e2022b3b868dcc1aca2741951ed5bf3bb25a34f5e9316a2841e8ff4c530b22ceaa1c5ce09c7cbb5732631510c20580e61723f5594de3aea497f195456a2ff2bdd0d13bad47289d8611b6f9cfeef0c46c91a455b94e90a66924f722292d21e24d31dcfb38ce0c0f353ffa5a9756fc2a9f2b40bc2113206a81e324fc4fd6823a29163fa845c8ae7eca1fcf6e5bb48b3200983c56c5ca81fffb151cca7402beddfc4a76b133447032ea7abedc098d2eb14a7",
"type": "document"
}
],
"nextCursor": "MTAwMA=="
}limit isn't an integer from 1 to 1000, or nextCursor is invalid or points past the last file.
The request has no valid session, the user isn't a member of the project, or the user is missing the update grant on sanity.project. A project ID that doesn't exist also returns 401. The body is {"code": 401, "message": "Unauthorized"}, with no detail about which check failed.
The dataset or backup doesn't exist, or the API version is earlier than v2024-02-21.