canonical: https://jentic.com/apis/sanity.io/sanity-projects-api

# Sanity Projects API

The Sanity Projects API administers Sanity projects and the datasets inside them. It lists, creates, updates, and deletes projects, and within a project creates datasets with a public, private, or custom ACL mode, updates or deletes them, copies one dataset into a new one, and lists the history of copy jobs. Projects also carry CORS origins, API tokens with assigned roles, tags that can be assigned to datasets, per-dataset embeddings index settings, active features, and the caller's own permissions. Role and permission management lives in Sanity's separate Access API.

## For AI agents

Create and configure Sanity projects and datasets, copy datasets, manage CORS origins, project tokens, and dataset tags, and read a project's features and your permissions.

## Scope

Does not read or write documents, run GROQ queries, or manage custom roles. Use for administering Sanity projects, datasets, CORS origins, tokens, and tags only.

## Capabilities

- Create a Sanity project with a displayName, optionally inside an existing organizationId
- Create a dataset with a public, private, or custom aclMode, or update and delete it
- Copy a dataset to a targetDataset, optionally with skipHistory for a faster copy, and list past copy jobs by state
- Add a CORS origin with allowCredentials, or remove one, so a browser app can call the project
- Create a project token with a label and a roleName such as viewer or editor, and list or delete tokens
- Create project tags and assign them to datasets to group environments
- Read and update a dataset's embeddings index settings

## Use cases

### AI agent provisioning environments

An agent setting up a test environment needs a fresh dataset and a way for the app to reach it. Through Jentic it searches for 'create a Sanity dataset', loads the dataset create operation, and creates a private dataset in the project, then adds the app's CORS origin, while the Sanity token is injected at call time. Each step is a separate operation, so the rule can allow provisioning without allowing deletion.

Example prompt: PUT `/projects/{projectId}/datasets/{name}` for dataset 'qa' with aclMode 'private', then POST `/projects/{projectId}/cors` with origin 'https://qa.example.com' and allowCredentials true

### Cloning production for testing

Testing migrations safely means working on a copy of real content. The copy operation clones a dataset into a new targetDataset, with skipHistory to speed it up and skipContentReleases to leave release documents behind; it requires Sanity's Advanced Dataset Management feature on the Enterprise plan. Past copies, including their state, are listed from the copy jobs history.

Example prompt: PUT `/projects/{projectId}/datasets/{name}/copy` for dataset 'production' with targetDataset 'migration-test' and skipHistory true, then GET `/projects/{projectId}/datasets/copy` to confirm the job

### Token and access housekeeping

Old tokens and stray CORS origins accumulate. The API lists every project token and CORS entry, deletes the ones no longer needed, creates new tokens with a unique label and roleName, and reports the caller's own permissions on the project so an audit can confirm who can do what.

Example prompt: Call GET `/projects/{projectId}/tokens` and GET `/projects/{projectId}/cors`, and report any token whose label mentions 'old' along with every origin allowed

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/projects` | List all projects |
| POST | `/projects` | Create a project |
| GET | `/projects/{projectId}/datasets` | List a project's datasets |
| PUT | `/projects/{projectId}/datasets/{name}` | Create a dataset |
| PUT | `/projects/{projectId}/datasets/{name}/copy` | Copy a dataset |
| POST | `/projects/{projectId}/cors` | Create a CORS entry |
| POST | `/projects/{projectId}/tokens` | Create a project token |
| GET | `/projects/{projectId}/permissions` | List your permissions for the project |

## Key resources

- **Projects** — Sanity projects with members, features, and organization
- **Datasets** — Datasets with ACL mode, copy, tags, and embeddings settings
- **CORS entries** — Allowed browser origins for the project
- **Tokens** — Project API tokens with labels and roles
- **Tags** — Project tags that can be assigned to datasets

## 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:** 66 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 85 / 100
  - Developer Experience & Jentic Compatibility: 59 / 100
  - AI-Readiness & Agent Experience: 51 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 75 / 100
- **View full report:** https://jentic.com/apis/sanity.io/sanity-projects-api/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 Projects API by hand means templating the apiVersion into the host, sending a bearer token with project-level permissions, and knowing which dataset features each plan allows. Through Jentic you install once, import it from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Sanity puts the project id and dataset name in the URL path (`/projects/{projectId}/datasets/{name}`), so a rule can pin your agent to one project or one dataset. You choose the operations it may call, so destructive ones like deleting a project or dataset, or creating tokens, are not included unless you add them.
- **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 'create a Sanity dataset' or 'add a CORS origin to a Sanity project', and Jentic returns the matching Projects API operation with its input schema.

## Related APIs

- **Sanity Copy API** — Dedicated dataset copy endpoint
- **Sanity Backups API** — List and download dataset backups
- **Sanity Embeddings Index API** — Create and query embeddings indexes for a dataset
- **Contentful** — Headless CMS with spaces and environments

## FAQ

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

Per its OpenAPI spec, the Sanity Projects API uses a bearer token in the Authorization header. What a token can do depends on its permissions, which GET `/projects/{projectId}/permissions` lists for the caller. Through Jentic the token is stored by your own instance and attached at call time, so it stays out of the agent's context.

### Can I copy a Sanity dataset with the Projects API?

Yes, with PUT `/projects/{projectId}/datasets/{name}/copy` and a targetDataset name. The spec says this is part of Advanced Dataset Management on the Enterprise plan; without it the request fails. Set skipHistory to true for a faster copy that leaves revision history behind.

### Where do I manage Sanity roles and permissions?

The spec points role and permission management to Sanity's separate Access API. The Projects API reads your own permissions for a project and assigns a roleName or roleNames when creating a token, and on a Free plan roleName must be viewer, editor, or deploy-studio.

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

The OpenAPI spec does not specify rate limits. Check the Sanity documentation at https://www.sanity.io/docs for current API limits for your plan.

### Is there a Sanity MCP server?

You don't need an MCP server to give your agent the Sanity Projects API. Jentic connects it directly from the API Directory: import it, store your Sanity token once, and your agent discovers the project, dataset, CORS, and token operations on demand.

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

Search Jentic for 'create a Sanity dataset', load the createDataset operation, and execute PUT `/projects/{projectId}/datasets/{name}` with an aclMode of public or private. Private datasets need the private datasets feature on the project. 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 Projects API?

Yes. Write a rule that allows GET `/projects/abc123/datasets` and PUT `/projects/abc123/datasets/{name}` only, and the agent can list and create datasets in that one project but cannot delete datasets, change CORS, or mint tokens. Every call it makes is logged.
