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

# Sanity Actions HTTP Endpoint

The Sanity Actions API runs content authoring actions against a Sanity dataset, the same higher-level operations Sanity Studio uses for everyday editing. A single request carries an ordered list of actions that execute in one transaction and roll back together if any fails. Document actions create, edit with a patch, publish, unpublish, and delete documents, version actions stage document changes inside a release, and release actions create, edit, schedule, publish, archive, and delete releases. It is a higher-level alternative to the Sanity Mutations API and requires API version v2024-05-23 or later, with version and release actions needing v2025-02-19.

## For AI agents

Create, patch, publish, and unpublish Sanity documents, and create, schedule, or publish content releases, in one transactional call per dataset.

## Scope

Does not run GROQ queries, upload assets, or manage project members. Use for transactional document, version, and release actions in a Sanity dataset only.

## Capabilities

- Create a document with a publishedId and document body, optionally using ifExists to control conflicts
- Edit a draft or release version of a document by applying a patch, then publish it
- Unpublish or delete a document, including named drafts and release versions through includeDrafts
- Stage document changes in a release with sanity.action.document.version.create
- Create, schedule with publishAt, publish, archive, or delete a content release
- Run several document actions in order inside one transaction that rolls back if any action fails

## Use cases

### AI agent content editor

An AI agent drafting or correcting site copy needs to save its changes as Sanity drafts and publish them when approved. Through Jentic the agent searches for 'publish a Sanity document', loads the actions operation with its input schema, and posts an actions array for a dataset while the Sanity API token is injected at call time. Because edits and publishes run in one transaction, a failed step leaves the content unchanged.

Example prompt: POST `/data/actions/{dataset}` with a sanity.action.document.edit action patching the title of post-123, followed by a sanity.action.document.publish action for the same publishedId and versionId

### Scheduled content releases

Marketing launches bundle many document changes that must go live together. The Actions API creates a release with a releaseId, stages document versions into it, and schedules it with a required publishAt time, or publishes it immediately. Releases can be unscheduled, archived, unarchived, or deleted as plans change.

Example prompt: Send a sanity.action.release.create action with releaseId spring-2024, stage a document version into it, then schedule it with sanity.action.release.schedule and a publishAt timestamp

### Bulk content migration

Importing content from another CMS means creating many documents reliably. A request can carry an ordered list of sanity.action.document.create actions, each with a publishedId and document, executed as one transaction so a partial import cannot be left behind. Different action families, such as release and document actions, must go in separate calls.

Example prompt: POST a batch of sanity.action.document.create actions for ten articles to the staging dataset and confirm the returned transactionId

## Key resources

- **Document actions** — Create, edit, publish, unpublish, and delete documents
- **Version actions** — Create, discard, replace, or mark for unpublish a document version inside a release
- **Release actions** — Create, edit, schedule, unschedule, publish, archive, unarchive, delete, and import releases

## 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:** 74 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 89 / 100
  - Developer Experience & Jentic Compatibility: 72 / 100
  - AI-Readiness & Agent Experience: 68 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 63 / 100
- **View full report:** https://jentic.com/apis/sanity.io/sanity-actions/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 Actions API by hand means templating the projectId and apiVersion into the host, sending a bearer token with the right permissions, and matching action field names exactly, since unknown fields return 400. 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 dataset name in the URL path (`/data/actions/{dataset}`), so a rule can pin your agent to one dataset such as staging. The action type itself travels in the request body, so a rule bounds where the agent can act, not which action types it sends; use a Sanity token whose own permissions match the job.
- **Credential handling:** Your Sanity API 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 'publish a Sanity document' or 'schedule a content release', and Jentic returns the Sanity actions operation with its input schema, including the action shapes it accepts.

## Related APIs

- **Sanity HTTP API** — Query and mutate Sanity documents with GROQ and lower-level writes
- **Contentful** — Headless CMS with entries, assets, and publishing
- **Storyblok** — Headless CMS with a visual editor
- **Prismic** — Headless website builder with slices and releases

## FAQ

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

Per its OpenAPI spec, the Sanity Actions API uses a bearer token: a Sanity API token with permissions for the actions you perform, sent in the Authorization header. Through Jentic the token is stored by your own instance and attached at call time, so it stays out of the agent's context.

### What is the difference between the Sanity Actions API and the Mutations API?

The spec describes the Actions API as a higher-level alternative to the Mutations API. It works in authoring terms such as publish, unpublish, and release scheduling, the operations Sanity Studio uses, rather than raw document writes, and runs each request's actions as one transaction.

### Can I mix release and document actions in one Sanity Actions request?

No. The spec states that different types of actions, such as release and document actions, cannot be mixed in a single API call. Send them as separate requests to POST `/data/actions/{dataset}.`

### What are the rate limits for the Sanity Actions 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 Actions API. Jentic connects it directly from the API Directory: import it, store your Sanity token once, and your agent calls the actions operation with the right input schema when it needs to.

### How do I publish a Sanity document through Jentic?

Search Jentic for 'publish a Sanity document', load the actions operation, and execute POST `/data/actions/{dataset}` with an actions array containing a sanity.action.document.publish action with publishedId and versionId. 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 Actions API?

Yes, by dataset. Write a rule that allows the actions operation only at `/data/actions/staging`, and the agent can edit and publish in staging while production stays untouched. Every call it makes is logged.
