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

# Sanity Agent Actions HTTP endpoints

The Sanity Agent Actions API runs schema-aware LLM instructions against documents in a Sanity dataset. Generate writes new content into an existing or new document from an instruction, Transform rewrites a source document's fields, and Translate converts a document into another language with an optional style guide and protected phrases. Prompt returns a plain or JSON LLM response without touching documents, and Patch applies validated, schema-checked changes without using an LLM. By default the actions write to drafts rather than published documents, and noWrite lets you preview a result without saving it.

## For AI agents

Generate, transform, and translate Sanity documents with schema-aware LLM instructions, prompt an LLM for text or JSON, and apply schema-validated patches, per dataset.

## Scope

Does not publish documents, upload assets, or run GROQ queries on their own. Use for LLM-driven generation, transformation, translation, prompting, and schema-validated patching of Sanity documents only.

## Capabilities

- Generate content into a document from an instruction, editing an existing documentId or creating a targetDocument
- Transform a source document's fields with an instruction, writing to the source or to a separate targetDocument
- Translate a document into a toLanguage, with a styleGuide and protectedPhrases that must stay untranslated
- Prompt the LLM for a string or json response for use in later actions, without reading or writing documents unless asked
- Apply a schema-aware patch whose paths and values are validated against the deployed schema, with no LLM involved
- Preview a result with noWrite or run it in the background with async, and edit published documents only when forcePublishedWrite is set

## Use cases

### AI agent content assistant

A developer's agent works on a Sanity project and needs to draft or revise content that respects the project's schema. Through Jentic the agent searches for 'generate content in a Sanity document', loads the generate operation with its input schema, and sends a schemaId, instruction, and documentId for the dataset while the Sanity token is injected at call time. Changes land in a draft unless forcePublishedWrite is set.

Example prompt: POST `/generate/production` with schemaId _.schemas.default, documentId post-123, and an instruction to write a 150-word summary into the excerpt field, with noWrite true to preview first

### Document localization

Teams publishing in several markets need translated copies of their content. Translate takes a source documentId and a toLanguage, accepts a styleGuide for tone and protectedPhrases for brand terms, and can write the result into a separate targetDocument so the original stays intact.

Example prompt: POST `/translate/production` with schemaId _.schemas.default, documentId article-42, toLanguage id de-DE, and protectedPhrases containing the brand name, writing to a targetDocument

### Tone and style rewrites

Editors often want a whole document reworded for a different audience. Transform applies an instruction to a source document, optionally limited to specific target paths, and writes the rewrite back to the source or to another document, using a default temperature of 0 for predictable output.

Example prompt: POST `/transform/staging` with schemaId _.schemas.default, documentId landing-page, and an instruction to rewrite the body for a beginner audience

### Schema-validated field updates

Some edits do not need an LLM at all, just a safe write. Patch takes a schemaId and a target, validates each path and value against the deployed schema, rejects unknown body properties with a 400, and bills as a regular Sanity API request.

Example prompt: POST `/patch/production` with schemaId _.schemas.default, documentId product-7, and a target that sets the price field, with noWrite true to validate first

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/generate/{dataset}` | Generate content into a document |
| POST | `/transform/{dataset}` | Transform a document |
| POST | `/translate/{dataset}` | Translate a document |
| POST | `/prompt/{dataset}` | Prompt the LLM for a response |
| POST | `/patch/{dataset}` | Make a schema-aware patch to a document |

## Key resources

- **Instructions** — Natural-language instructions with instructionParams that pull in constants, fields, GROQ results, or documents
- **Targets** — Document paths an action may read or write, with include and exclude controls
- **Write options** — noWrite, async, and forcePublishedWrite flags that control whether and where results are saved

## 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: 78 / 100
  - Developer Experience & Jentic Compatibility: 71 / 100
  - AI-Readiness & Agent Experience: 47 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 75 / 100
- **View full report:** https://jentic.com/apis/sanity.io/sanity-agent-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 Sanity Agent Actions by hand means templating the projectId and apiVersion into the host, sending a bearer token, and building nested request bodies with schemaId, instruction, and target shapes, where unknown patch 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:** Every Agent Actions path carries the dataset name (`/translate/{dataset}`, `/patch/{dataset}`), so a rule can pin your agent to one dataset such as staging and to the specific actions you pick. You choose the operations it may call, so document-writing ones like generate or patch are not included unless you add them.
- **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 'translate a Sanity document' or 'generate content in a Sanity document', and Jentic returns the matching Agent Actions operation with its input schema, including the required schemaId.

## Related APIs

- **Sanity Actions API** — Publish, unpublish, and release Sanity documents
- **Sanity HTTP API** — Query and mutate Sanity documents with GROQ
- **OpenAI API** — General-purpose LLM text generation
- **Contentful** — Headless CMS with entries and assets

## FAQ

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

Per its OpenAPI spec, the Sanity Agent Actions API uses bearer authentication with a Sanity API token or a user session token 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.

### Do Sanity Agent Actions overwrite published documents?

Not by default. The spec says Agent Actions never mutate a published document unless forcePublishedWrite is true; given a published ID, they write to its draft. Documents set to liveEdit are treated as if forcePublishedWrite were true. Set noWrite to get the result without creating or changing any document.

### What is the difference between Prompt and Generate in Sanity Agent Actions?

Generate writes LLM output into a document and requires schemaId, instruction, and either documentId or targetDocument. Prompt only returns a response, as a string or as json, and does not interact with documents beyond fetching content as context when requested.

### What are the rate limits for the Sanity Agent Actions API?

The OpenAPI spec does not specify rate limits. Check the Sanity Agent Actions documentation at https://www.sanity.io/docs/agent-actions for current limits and usage on your plan.

### Is there a Sanity Agent Actions MCP server?

You don't need an MCP server to give your agent Sanity Agent Actions. Jentic connects the API directly from the API Directory: import it, store your Sanity token once, and your agent loads the generate, transform, translate, prompt, or patch operation only when it needs one.

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

Search Jentic for 'translate a Sanity document', load the translate operation, and execute POST `/translate/{dataset}` with schemaId, documentId, and toLanguage. 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 Sanity Agent Actions?

Yes. For example, write a rule that allows only translate and prompt under `/translate/staging` and `/prompt/staging`, and the agent can produce translations in staging while generate, transform, and patch, and every other dataset, stay out of reach. Every call it makes is logged.
