Sanity

Sanity

This connector works with the content of a Sanity project (the headless CMS and Content Lake) through the official HTTP API (https://<projectId>.api.sanity.io/v2025-02-19). Its main tool runs GROQ queries against one dataset; others read a document by id, its earlier revisions and change history, list document types, datasets and projects, and create, change and publish drafts after you confirm.

Setup (about 3 minutes)

1. Open https://www.sanity.io/manage, pick the project and copy its Project ID (8 characters, e.g. abc12xyz) into SANITY_PROJECT_ID.
2. Under Datasets note the dataset name (usually production) for SANITY_DATASET.
3. Under API, Tokens, click Add API token, give it a name and choose the permission:
   • Viewer: reads published documents and drafts, history included. Enough for every read tool; writes are refused.
   • Editor: reads and writes documents. Needed for sanity_create_draft, sanity_patch_draft and sanity_publish_draft. Avoid Developer and Administrator tokens: they can also change project settings and datasets.
4. Copy the token into SANITY_API_TOKEN (Sanity shows it once), install and run sanity_list_document_types.

Writes: confirm first, drafts by default. sanity_create_draft and sanity_patch_draft only ever write the draft (drafts.<id>), the version editors see in Sanity Studio; nothing goes live until sanity_publish_draft, which replaces the published document visitors see. Before any of them, show the user the document, the change and whether it will go live, and wait for a clear yes. Pass dry_run: true to check an action without saving. sanity_delete_document is installed switched off.

GROQ in short (sanity_query)

• Filter, then project only the fields you need, then slice: *[_type == "post" && defined(slug.current)] | order(publishedAt desc) [0...10] {_id, title, "slug": slug.current, publishedAt}.
• Always add a slice such as [0...20] and a projection {...}: a bare *[_type == "post"] returns whole documents and is cut off at about 60 KB.
• Pass values as params instead of pasting them into the query: query *[_type == $type && title match $q], params {"type": "post", "q": "launch*"}.
• Count with count(*[_type == "post"]); follow references with author->name; full text with title match "word*"; drafts have ids starting with drafts..
• Field names come from the project's schema: look at a few documents first (*[_type == "post"][0...3]) when you do not know them. sanity_list_document_types lists the types.
• perspective: published (default) ignores drafts, drafts shows content as if all drafts were published, raw returns published documents and drafts side by side.

How to work

1. sanity_list_document_types, then sanity_query to find documents.
2. sanity_get_document reads documents by id (published or drafts.<id>).
3. History: sanity_list_document_transactions lists who changed a document and when (no content); sanity_get_document_revision returns the document as it was at a revision id or a time.
4. Edit: sanity_create_draft for a new document, sanity_patch_draft to change one (it starts the draft from the published version when there is none), sanity_publish_draft to make the draft live.
5. Setup questions: sanity_list_datasets for this project, sanity_list_projects for all projects the token can see.

Rich text fields (Portable Text) are arrays of blocks; to write plain paragraphs use blocks like {"_type": "block", "_key": "a1", "style": "normal", "children": [{"_type": "span", "_key": "a2", "text": "Hello"}]}. Every array item needs a unique _key.

Common errors

• 401 Session not found: the token is wrong or was deleted.
• 403 or "Insufficient permissions": a Viewer token tried to write, or the token belongs to another project.
• 404 Dataset not found: check SANITY_DATASET; documents that do not exist come back empty from queries and in omitted from sanity_get_document.
• 400 queryParseError: the GROQ query has a syntax error; the message shows where.

Out of scope: assets (image and file uploads), content releases and scheduled publishing, unpublishing, deleting (switched off), dataset and project management, webhooks, CORS and members, and real-time listening.