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

# Sanity Copy HTTP Endpoint

The Sanity Copy API, also known as Cloud Clone, copies an existing dataset into a new dataset inside Sanity's cloud, as an alternative to exporting and re-importing it. A copy request names the targetDataset and can leave out document history with skipHistory or content releases with skipContentReleases; scheduled releases arrive unscheduled in the copy. Starting a copy returns a jobId whose progress you follow through the Jobs API, and a second operation lists a project's copy jobs newest first, filtered by state. Copying is part of the Advanced Dataset Management offering on Sanity's enterprise plan, while listing jobs is not.

## For AI agents

Clone a Sanity dataset into a new dataset in the cloud, with or without history and content releases, and list a project's copy jobs by state.

## Scope

Does not export documents to files, restore backups, or delete datasets. Use for cloning a Sanity dataset in the cloud and listing copy jobs only.

## Capabilities

- Clone a dataset in the cloud with copyDataset by naming a new targetDataset
- Leave document history out of the copy with skipHistory
- Skip content releases and their document versions with skipContentReleases
- List a project's dataset copy jobs newest first with listCopyJobs, filtered by state such as pending or running
- Read each job's sourceDataset, targetDataset, withHistory, and timestamps to confirm what was copied

## Use cases

### AI agent safe sandbox setup

Before an agent runs a bulk content change, it is safer to work on a clone. Through Jentic the agent searches for 'copy a Sanity dataset', loads the copyDataset operation, and sends a targetDataset for the source dataset while the Sanity token is injected at call time. It keeps the returned jobId to confirm the clone finished before starting work.

Example prompt: PUT `/projects/abcd1234/datasets/production/copy` with targetDataset production-sandbox and skipHistory true, then return the jobId

### Pre-migration snapshot

Schema migrations are easier to roll back with a copy of the dataset taken just before. Cloud Clone duplicates the dataset inside Sanity without downloading it, copies content releases unless skipContentReleases is set, and returns 409 if a dataset with the target name already exists.

Example prompt: PUT `/projects/abcd1234/datasets/production/copy` with targetDataset production-pre-migration and skipContentReleases false

### Copy job monitoring

Large copies run as background jobs. Listing copy jobs with state=pending,running shows what is still in progress, newest first, and each job reports its sourceDataset, targetDataset, whether history was included, and when it was created and last updated.

Example prompt: GET `/projects/abcd1234/datasets/copy` with state pending,running and limit 20, and report each job's id and targetDataset

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| PUT | `/projects/{projectId}/datasets/{dataset}/copy` | Copy a dataset into a new dataset |
| GET | `/projects/{projectId}/datasets/copy` | List copy jobs |

## Key resources

- **Copy jobs** — Background jobs with id, state, sourceDataset, targetDataset, and withHistory
- **Datasets** — The source dataset being copied and the new target dataset it becomes

## 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:** 68 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 93 / 100
  - Developer Experience & Jentic Compatibility: 72 / 100
  - AI-Readiness & Agent Experience: 49 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 75 / 100
- **View full report:** https://jentic.com/apis/sanity.io/sanity-copy/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 Copy API by hand means templating the apiVersion into the host, sending a bearer token with the create grant on sanity.project.datasets, and handling the 400, 402, and 409 cases for plan, quota, and name clashes. Through Jentic you install once, import it from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** The project and source dataset sit in the URL path (`/projects/{projectId}/datasets/{dataset}/copy`), so a rule can pin your agent to one project and one source dataset. The targetDataset travels in the request body, so a rule bounds what may be copied, not what the new dataset is called.
- **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 'copy a Sanity dataset' or 'list Sanity copy jobs', and Jentic returns the matching operation with its path parameters and body schema.

## Related APIs

- **Sanity Export API** — Stream all documents in a dataset as NDJSON
- **Sanity Backups API** — List and download dataset backups
- **Contentful** — Headless CMS with spaces and environments

## FAQ

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

Per its OpenAPI spec, the Sanity Copy API uses bearer authentication with a Sanity token in the Authorization header. Starting a copy needs the create grant on sanity.project.datasets, and a missing grant returns 401 with code missing_grant; listing jobs needs the read grant. Through Jentic the token is stored by your own instance and attached at call time.

### Is the Sanity Copy API free?

Copying a dataset is part of Sanity's Advanced Dataset Management offering on the enterprise plan, and projects without it get a 400 error. Listing copy jobs does not require that feature. A project at its dataset quota gets a 402 Quota exceeded error.

### How do I check whether a Sanity dataset copy has finished?

Use the jobId returned by the copy request with Sanity's Jobs API, or list the project's copy jobs and check each job's state, which is one of pending, running, completed, failed, terminating, or terminated.

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

The OpenAPI spec does not specify rate limits. It does return 409 if a copy from the same source to the same targetDataset is already in progress. Check https://www.sanity.io/docs for current API limits.

### Is there a Sanity Copy MCP server?

You don't need an MCP server to give your agent the Sanity Copy API. Jentic connects it directly from the API Directory: import it, store your Sanity token once, and your agent calls the copy or job-listing operation when needed.

### How do I clone a Sanity dataset through Jentic?

Search Jentic for 'copy a Sanity dataset', load the copyDataset operation, and execute PUT `/projects/{projectId}/datasets/{dataset}/copy` with a targetDataset in the body. 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 Copy API?

Yes. Allow only GET `/projects/abcd1234/datasets/copy` and the agent can report on copy jobs for that one project without starting any new copies, which count toward your dataset quota. Every call it makes is logged.
