canonical: https://jentic.com/apis/sanity.io/sanity-backups

# Sanity Backups HTTP Endpoint

The Sanity Backups API turns backups on or off for a dataset, lists the backups that exist, and returns the files inside any one of them. Backup listings can be narrowed with after and before dates and return each backup's ID and creation time. Fetching a backup returns its total file count and a page of document, image, and file entries with signed download URLs that expire after 24 hours. It is the HTTP surface behind the sanity backups download command, which assembles those files into a tarball for sanity datasets import.

## For AI agents

Enable or disable Sanity dataset backups, list backups by date range, and page through a backup's files with signed download URLs.

## Scope

Does not restore datasets, export live documents, or copy datasets. Use for enabling backups and listing and downloading Sanity dataset backups only.

## Capabilities

- Turn backups on or off for a dataset by sending enabled true or false to the backup settings endpoint
- List a dataset's most recent backups, up to 100, filtered to dates on or after after and before before
- Fetch a backup's createdAt time and totalFiles count by backupId
- Page through a backup's document, image, and file entries with nextCursor, up to 1000 files per page
- Download backup files through signed URLs that expire 24 hours after the request

## Use cases

### AI agent backup check

Before an agent runs a risky content migration, it should confirm a recent backup exists. Through Jentic the agent searches for 'list Sanity dataset backups', loads the list operation, and calls it for the dataset while the Sanity token is injected at call time. It reads the newest backup ID and createdAt before going ahead.

Example prompt: GET `/datasets/production/backups` with after set to yesterday's date and report the id and createdAt of the latest backup

### Point-in-time recovery prep

When bad content lands in a dataset, the first step is finding a backup from before the change. Listing backups with a before date returns those created earlier, and fetching one returns its files page by page with signed URLs, ready to download and reassemble for sanity datasets import.

Example prompt: GET `/datasets/production/backups` with before 2026-11-18, pick the latest backup id, then GET `/datasets/production/backups/{backupId}` and follow nextCursor until it is empty

### Backup coverage across datasets

Teams with several datasets need backups switched on where it matters. The settings operation sets enabled for one datasetName at a time and returns 204 on success, or 400 if the project's plan does not include the backups feature.

Example prompt: PUT `/datasets/staging/settings/backups` with body enabled true and confirm a 204 response

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| PUT | `/datasets/{datasetName}/settings/backups` | Enable or disable backups |
| GET | `/datasets/{datasetName}/backups` | List backups |
| GET | `/datasets/{datasetName}/backups/{backupId}` | Get a backup and its files |

## Key resources

- **Backup settings** — The enabled flag that turns backups on or off for a dataset
- **Backups** — Backup records with an ID in YYYY-MM-DD-uuid form and a createdAt time
- **Backup files** — Document, image, and file entries with signed download URLs

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 50 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 100 / 100
  - Developer Experience & Jentic Compatibility: 64 / 100
  - AI-Readiness & Agent Experience: 24 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 58 / 100
- **View full report:** https://jentic.com/apis/sanity.io/sanity-backups/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring the Sanity Backups API by hand means templating the apiVersion and projectId into the base path, sending a bearer token with the right project grants, and following nextCursor until it comes back empty. Through Jentic you install once, import it from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** The Backups paths carry the dataset name (`/datasets/{datasetName}/backups`), so a rule can pin your agent to one dataset and to the read operations you pick. You choose the operations it may call, so the settings change that can switch backups off is not included unless you add it.
- **Credential handling:** Your Sanity token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'list Sanity dataset backups' or 'download a Sanity backup', and Jentic returns the matching Backups operation with its parameters.

## Related APIs

- **Sanity Export API** — Stream a live NDJSON export of a dataset's documents
- **Sanity Copy API** — Clone a dataset into a new dataset in the cloud
- **Contentful** — Headless CMS with its own management API

## FAQ

### What authentication does the Sanity Backups API use?

Per its OpenAPI spec, the Sanity Backups API uses bearer authentication with a Sanity token in the Authorization header. The spec notes that changing settings needs the update grant on sanity.project.datasets, and listing backups returns 401 for users without the update grant on sanity.project. Through Jentic the token is stored by your own instance and attached at call time.

### Can I restore a dataset with the Sanity Backups API?

Not directly. The API lists backups and returns their files with signed download URLs. The sanity backups download CLI command uses it to build a tarball, which you then load with sanity datasets import.

### How long do Sanity backup download links last?

The signed url on each backup file expires 24 hours after the request. Fetch the backup again to get fresh links if a download runs past that window.

### What are the rate limits for the Sanity Backups API?

The OpenAPI spec does not specify rate limits. It does page results: list returns up to 100 backups and each backup page returns up to 1000 files. Check https://www.sanity.io/docs for current API limits for your plan.

### Is there a Sanity Backups MCP server?

You don't need an MCP server to give your agent the Sanity Backups API. Jentic connects it directly from the API Directory: import it, store your Sanity token once, and your agent calls the backup operations when it needs them.

### How do I check for a recent Sanity backup through Jentic?

Search Jentic for 'list Sanity dataset backups', load the list operation, and execute GET `/datasets/{datasetName}/backups` with an after date. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with the Sanity Backups API?

Yes. Write a rule that allows only the two GET operations under `/datasets/production/backups`, and the agent can confirm and inspect production backups but cannot switch backups off for any dataset. Every call it makes is logged.
