Menu

Mattering Automations Sanity integration

Connect Sanity to Mattering Automations: GROQ queries, the transactional Mutation API, publish and unpublish actions, asset uploads from a URL, and datasets, CORS origins, tokens and webhooks as workflow steps, authenticated with one project-scoped robot token.

The Mattering Automations Sanity integration puts two Sanity hosts on your automation canvas with one credential: the Content Lake, where your documents and assets live, and the project management API around it. That is 40 nodes, 18 of them reads and 22 of them actions, with 6 flagged destructive. Reads cover GROQ, direct document fetches, revision history, per-document transactions and a full dataset export. Writes cover all five mutation types, the publish and unpublish actions and asset uploads. Management covers projects, datasets, CORS origins, API tokens, roles, permissions, project features and webhooks with their delivery attempts.

The credential is a Sanity robot token plus the project id. Sanity's own documentation recommends generating a dedicated robot token for any application or third-party service, and it is created at sanity.io/manage under the project's Settings and then API and Tokens. The project id is not a secret and sits on the credential rather than on the nodes, because Sanity documents that a project robot token can only act on its own project. The dataset is the opposite: one token reaches every dataset in the project, so it is a per-node field with a picker, backed by an optional default on the credential so a single-dataset project does not retype it 27 times.

The most useful thing to settle before you build anything is what your token is allowed to do. Sanity's built-in roles are a ladder: a viewer reads, a contributor writes drafts, an editor writes and publishes, and a developer additionally manages datasets, CORS origins, tokens and webhooks. Which of them exist depends on the plan, and Sanity documents Free as shipping administrator and viewer with editor, developer and contributor arriving on Growth. Each role also carries a flag for whether it can be given to a robot token at all, so the role you had in mind may not be assignable to one. Two nodes turn all of that from guesswork into a reading: Sanity: List Roles reports which roles can be given to a robot, and Sanity: List Project Permissions reports what the token you connected actually has.

Before you start

  • A Sanity account with a project you can create a token in, and that project's id. The id appears at sanity.io/manage and in your studio configuration file, and it is part of both the content host and every management path.
  • A robot token created under the project's Settings and then API and Tokens. Give it the narrowest role that covers your workflows.
  • A clear idea of which half of the integration you need, because the role decides it. The 18 read nodes work on a viewer token. The content write and publish nodes need an editor or developer role. The 11 management actions need a developer role. Sanity documents Free-plan roles as administrator and viewer, with editor, developer and contributor arriving on Growth, and each role carries a flag for whether it can be given to a robot token, so confirm with Sanity: List Roles which roles your project can actually assign to a robot before designing a workflow around the write half.
  • At least one dataset, or the intent to create one. Sanity: Create Dataset works from the canvas, and the verify path below reads cleanly against a project with a single dataset.
  • Plan-gated surfaces this integration deliberately omits rather than shipping nodes that always fail: Sanity documents its Backups API as available for enterprise plans and the dataset Copy API as part of Advanced Dataset Management on the enterprise plan, so on Free and Growth the pre-delete safety net is Sanity: Export Documents and keeping the output.
  • A Mattering workspace with access to the Automations app.

Create a Sanity robot token

Mattering authenticates to both Sanity hosts with the same bearer token, so there is nothing to compose and no second credential. Sanity calls a machine token a robot token and recommends creating a dedicated one per application rather than reusing a personal token, which also means revoking this integration later does not disturb anything else. The decision that matters at creation time is the role, because it fixes what the connector can do for as long as the token lives.

Sign in at sanity.io/manage and open the project this credential should reach. Copy its Project ID.
Open Settings, then API, then Tokens, and click Add new token.
Choose the role deliberately. A reporting or retrieval automation wants a read-only role. Only workflows that create datasets, add CORS origins, mint tokens or manage webhooks need a developer role.
Sanity shows a token's secret ONCE, at creation. Copy it straight into the Mattering credential form; there is no way to read it again afterwards and the only remedy is to create a replacement and delete the old one.
You do not need a dataset name here unless you want one. The dataset is a per-node field with a picker, and the optional default dataset on the credential only fills in when a node leaves that field blank. It never overrides a field you filled.

Connect Sanity to Mattering

In Mattering Automations, open Connectors and click Add Connector.
Choose Sanity from the list.
Click Create new credential, paste the Project ID and the API Token, optionally set a Default Dataset, and save.
The token is stored encrypted in Google Secret Manager and never appears in workflow logs. The project id is not a secret and is stored as an ordinary field.
Click Test Connection. Mattering calls Sanity's project list on the management host: it takes no parameters and no dataset, so it proves the token on its own even before any content exists. An invalid or revoked token answers 401.
Click Connect. All 40 Sanity nodes appear in your canvas palette.

Verify it works

Open any automation canvas and check the palette for a Sanity section listing the read and action nodes. Drop Sanity: List Datasets onto the canvas and run a test step. It is the integration's natural probe: it needs no parameters beyond the credential, and it returns each dataset with its name and its access mode, where a public dataset is readable without a token and a private one is not. It is also the node every other dataset picker reads from, so a successful run here is what makes the rest of the palette configurable without typing. Note that management endpoints return a BARE ARRAY, so paths read data[].name with no wrapper key.

Now settle what the token can do, before you build anything on top of it. Drop Sanity: List Project Permissions onto the canvas and run it: it reports what the connected token is actually allowed to do in this project. Pair it with Sanity: List Roles, which reports the roles available and, importantly, whether each one can be given to a robot token at all. Doing this now converts a future 403 from a mystery into something you already know the answer to.

Finish with a real content read. Drop Sanity: Run GROQ Query onto the canvas, open the Dataset field and confirm the picker lists your datasets by name, then run a small query. The response carries your rows at data.result plus the server time at data.ms and the query text at data.query. Leave Use CDN off, which is the default: the CDN host can be stale, and it is exactly wrong when an automation is reading back something it just wrote. Everything in this verify path is read-only, so it cannot reach the six destructive nodes and is safe to re-run whenever you rotate the token.

Node reference

40 nodes, generated from the connector itself so this reference always matches what ships.

Read and query nodes 18

Sanity: Count Documents

sanity_count_documents

Count the documents of one type that match an optional filter without transferring them. The answer is a single number at data.result. Use this to gate an automation (only run the digest when there is something new) or to check a delete-by-query's blast radius before running it.

Sanity: Export Documents

sanity_export_documents

Export every document the token can read from a dataset as one stream. Sanity sends newline-delimited JSON; the node parses it into data.documents with a data.count. This is the snapshot to take BEFORE anything destructive - on Free and Growth plans it is the only backup available, since the Backups API is enterprise-only. Export execution is capped at 5 minutes; on a large dataset use cursor mode by setting the cursor field to an empty string and following the cursor Sanity returns.

Sanity: Get Document

sanity_get_document

Fetch one document by _id straight from the Content Lake. This bypasses the caching layers so it always returns the very latest state, which is what you want immediately after a write. Sanity documents it as less scalable than a GROQ query and asks that it be used sparingly - prefer Sanity: Run GROQ Query for anything you will call in a loop. The response carries data.documents as an array even for one id.

Sanity: Get Document Revision

sanity_get_document_revision

Fetch a document as it looked at a past revision or at a point in time. Give either a revision id or a timestamp; the timestamp is matched against when the transaction landed. This is the read half of any restore-what-changed workflow, and the only route back to a document that was deleted without purge. Sanity documents no retention window for history so do not rely on it as a backup.

Sanity: Get Project

sanity_get_project

Fetch the connected project: display name studio host organization members and whether it is blocked or disabled. The project comes from the Sanity connection so this node has nothing to configure. Useful as a health check inside a workflow and to read data.members for who has access.

Sanity: Get Project User

sanity_get_project_user

Fetch one user of this project by id, or the caller's own identity by leaving the default value of me. Turns the user id on a transaction or a document's _updatedBy into a name an automation can put in a message.

Sanity: List API Tokens

sanity_list_tokens

List the project's API tokens with their labels and roles. Sanity never reveals a token's value again after creation, so this returns details ABOUT each token and not the secret. Use it to audit what has access and with which role.

Sanity: List CORS Origins

sanity_list_cors_origins

List the browser origins allowed to call this project's API directly, and whether each may send credentials. The first thing to check when a front end works from the server but fails in the browser.

Sanity: List Datasets

sanity_list_datasets

List the datasets in the connected project with their names and access mode (public datasets are readable without a token; private ones are not). Every dataset-scoped node in this connector sources its dataset picker from here, so this is the node that makes the rest of the connector configurable without typing.

Sanity: List Document Transactions

sanity_list_document_transactions

List the transactions that touched specific documents: who changed what and when. Answers audit questions (who last edited this page) and drives change-detection automations. Sanity streams this as newline-delimited JSON; the node parses it into data.transactions with a data.count. Scoped to document ids on purpose - the whole-dataset variant is a firehose and is not built.

Sanity: List Documents by Type

sanity_list_documents_by_type

List documents of one type without writing GROQ by hand. Choose the document type and optionally add a filter fragment an ordering and a projection; this node assembles the GROQ and runs it. The document type is passed as a query parameter rather than pasted into the query text. Results arrive at data.result as an array.

Sanity: List Project Features

sanity_list_project_features

List the features enabled for this project, which is how the plan shows up in the API. Check this before building a workflow on something plan-gated rather than discovering it from a 402 at runtime.

Sanity: List Project Permissions

sanity_list_project_permissions

List what the CURRENT token is actually allowed to do in this project. The right first call when a write returns 403: it separates a wrong token from a wrong request, which is otherwise guesswork.

Sanity: List Projects

sanity_list_projects

List the projects this token can see, with their ids display names and organization. Mostly used once, to find the project id that goes on the Sanity connection - every other node takes the project from the credential rather than from a field, because a project robot token only works against its own project. Also the credential health check: a bad token returns 401.

Sanity: List Roles

sanity_list_roles

List the roles available in this project - the built-in ones and any custom roles - with the grants each carries and whether it can be given to a robot token. Read this before Sanity: Create API Token, because the role decides what the new token can do. Which built-in roles exist depends on the plan: Free ships administrator and viewer while editor, developer and contributor arrive on Growth.

Sanity: List Webhook Attempts

sanity_list_webhook_attempts

List a webhook's recent delivery attempts with the status code the endpoint returned, how long it took and why it failed. The answer to did my webhook actually fire, and the first thing to read when a content-triggered workflow did not run.

Sanity: List Webhooks

sanity_list_webhooks

List the project's webhooks with their target URLs, the dataset and GROQ filter each listens on, and whether they are disabled. Webhooks are how Sanity pushes content changes into an automation, so this is the inventory of what is already wired up.

Sanity: Run GROQ Query

sanity_query

Run a GROQ query against a dataset and get the result. GROQ is Sanity's query language and it is the whole read API - there is no filter-by-field REST surface, so this is how an automation finds content by anything other than a known id. Read-only by construction: GROQ cannot write, so this node can never mutate content. Sent as a POST because Sanity caps GET query URLs at 11 KB. The response carries the result at data.result plus the server time in data.ms.

Action nodes 22

Sanity: Add CORS Origin

sanity_create_cors_origin

Allow a browser origin to call this project's API - the step a preview deployment needs before its front end can read content. Requires a token with infrastructure permissions. Reversible with Sanity: Remove CORS Origin.

Sanity: Create API Token

sanity_create_token

Create a new API token for the project with a chosen role. The secret is returned ONCE at data.key and never again, so whatever consumes this node's output is the only chance to store it - route it to a secret store rather than to a log or a chat message. Robot tokens cannot hold Sanity's default administrator role. Requires a token with infrastructure permissions. Reversible with Sanity: Delete API Token.

Sanity: Create Dataset

sanity_create_dataset

Create a dataset in the connected project. Datasets are how Sanity separates production from staging or one tenant from another, and content does not move between them by itself. Requires a token with infrastructure permissions (administrator or developer). Reversible with Sanity: Delete Dataset while the dataset is still empty.

Sanity: Create Document

sanity_create_document

Create a new document. Fails if the id already exists - use Sanity: Create or Replace Document to overwrite or Sanity: Create Document If Not Exists to skip silently. Leave the id blank and Sanity generates one; end it with a dot to use it as a prefix for a generated id. Create the id as drafts.<id> to write a draft rather than published content. Reversible with Sanity: Delete Document.

Sanity: Create Document If Not Exists

sanity_create_document_if_not_exists

Create a document only if that id is free and do nothing at all if it already exists. The idempotent seeding node: a workflow that runs twice cannot create the record twice and cannot overwrite what someone edited in between. Use a stable id derived from the source system.

Sanity: Create Webhook

sanity_create_webhook

Create a webhook so Sanity calls a URL whenever matching content changes. Point it at an Automations webhook trigger and the workflow starts the moment an editor publishes, instead of on a schedule. The GROQ filter narrows what fires and the projection controls what is sent, so the receiving workflow gets only the fields it needs. Set a secret to sign deliveries. Reversible with Sanity: Delete Webhook.

Sanity: Create or Replace Document

sanity_create_or_replace_document

Create a document with the id you choose or REPLACE it whole if it already exists. This is a replacement and not a merge: any field you leave out is gone from the new revision. Use Sanity: Patch Document to change some fields and keep the rest. The prior revision remains in the document's history so this is recoverable through Sanity: Get Document Revision. The natural node for a sync that mirrors an external system into Sanity.

Sanity: Delete API Token

sanity_delete_token

DESTRUCTIVE: revoke an API token. Everything using it stops working the moment this runs, and the secret cannot be recovered because Sanity only ever shows it once. Access is recoverable by issuing a NEW token and updating every consumer; the old value is not. Check Sanity: List API Tokens and confirm the label before running this - deleting the token this connection uses breaks the connector itself.

Sanity: Delete Dataset

sanity_delete_dataset

DESTRUCTIVE: delete a dataset and everything inside it - every document, every asset and the whole revision history. This is the one delete in this connector that history cannot soften, because the history goes with the dataset. Sanity's Backups API is enterprise-only and dataset copy is Business/Enterprise, so on Free and Growth plans the only safety net is running Sanity: Export Documents first and keeping the output. There is no undelete.

Sanity: Delete Document

sanity_delete_document

DESTRUCTIVE: delete one document by _id. Sanity has no trash and no undelete. Without the purge option the document's transaction history remains so a determined operator can reconstruct it through Sanity: Get Document Revision - Sanity documents no retention window for that history so treat it as a chance and not a backup. With purge on there is nothing left to reconstruct from. Deleting the published document does not delete its draft; delete drafts.<id> too. Run Sanity: Export Documents first if the content matters.

Sanity: Delete Documents by Query

sanity_delete_documents_by_query

DESTRUCTIVE: delete every document a GROQ query matches. The blast radius is whatever the query returns at the moment it runs, so run the SAME query through Sanity: Count Documents or Sanity: Run GROQ Query first and leave the dry run option on for the first execution. Sanity caps this at 10,000 documents per query and asks that larger jobs be split and paginated. Same recovery position as a single delete: history may allow reconstruction unless purge is set.

Sanity: Delete Webhook

sanity_delete_webhook

DESTRUCTIVE: delete a webhook. The definition and its delivery history go with it and nothing restores the history. The definition itself is recoverable only by hand, from a copy of its URL filter and projection - read Sanity: List Webhooks and keep the output first. If the goal is a temporary pause use Sanity: Enable or Disable Webhook instead.

Sanity: Enable or Disable Webhook

sanity_set_webhook_enabled

Turn a webhook off or back on without deleting it. The way to pause deliveries during a bulk import or a migration so the downstream workflow is not flooded, and then restore it with the same node. Disabling is the only field this endpoint updates - change a URL or filter by deleting and recreating the webhook.

Sanity: Patch Document

sanity_patch_document

Change specific fields on an existing document and leave everything else alone. The surgical alternative to Sanity: Create or Replace Document. Fails if the document does not exist. Sanity applies the operations in a fixed order: set then setIfMissing then unset then inc then dec then insert. Fill the revision field to refuse the write if someone else edited the document since you read it.

Sanity: Publish Document

sanity_publish_document

Publish a draft: promote the draft version onto the published document so the live site sees it. This runs through Sanity's Actions API rather than the Mutation API, which is what makes it a real publish rather than a copy. Reversible with Sanity: Unpublish Document. The optimistic lock fields refuse the publish if either side changed since you read it.

Sanity: Remove CORS Origin

sanity_delete_cors_origin

Remove a browser origin from the allow list. Browser calls from that origin start failing immediately, so check what is deployed there first. Not classed destructive: the entry is a two-field record that Sanity: Add CORS Origin recreates exactly.

Sanity: Run Mutation Batch

sanity_mutate

DESTRUCTIVE: run several mutations as ONE atomic transaction - either every mutation applies or none does. Flagged destructive because a batch may contain delete mutations and the connector cannot know what you put in it; the typed nodes beside this one carry honest per-operation flags and should be preferred when one operation is enough. Use this when several documents must change together (create an author and the post that references it) or to write hundreds of records in one call. Sanity caps a mutation request body at 4 MB so split large imports.

Sanity: Unpublish Document

sanity_unpublish_document

Unpublish a document: remove the published version so the live site stops serving it while the draft remains for editors. This is the safe way to take a page down - the content is not deleted and Sanity: Publish Document puts it straight back. Prefer this over a delete whenever the content might return.

Sanity: Update Dataset

sanity_update_dataset

Change a dataset's access mode between public and private. Flipping a dataset to private immediately stops every tokenless reader - including a live website that reads with no token - so make sure the front end has a token before running it. Reversible by running the node again the other way.

Sanity: Update Project

sanity_update_project

Update the connected project's settings: its display name, the studio host it is served on, its metadata and whether the activity feed is on. Only the fields you fill are sent. Requires a token with infrastructure permissions (administrator or developer role); an editor token gets a 403 here.

Sanity: Upload File from URL

sanity_upload_file_asset

Upload a non-image file (PDF, video, zip) into a dataset by giving its public https URL. Same mechanics as the image node: Sanity takes raw bytes so this node downloads the file and forwards them (https only; capped at 50 MB), and the new asset document comes back at data.document for referencing from a file field.

Sanity: Upload Image from URL

sanity_upload_image_asset

Upload an image into a dataset by giving its public https URL. Sanity's asset endpoint takes raw bytes rather than a URL so this node downloads the image and posts the bytes for you (https only; capped at 50 MB). The response carries the new asset document at data.document - reference data.document._id from an image field on a document you create next. Sanity de-duplicates by content hash so uploading the same bytes twice returns the same asset. Uploads are limited to 25 requests/second.

Using the integration

On the automation canvas

Sanity nodes chain with every other node. A schedule can run Sanity: List Documents by Type and push what changed into a Mattering database or a search index. A form submission can run Sanity: Upload Image from URL and then Sanity: Create Document to stage content for review. A webhook from Sanity can start the workflow the moment an editor publishes. Two values do most of the wiring: the dataset, which is a picker on all 27 dataset-scoped nodes sourced from Sanity: List Datasets, and the document id, which is free text because Sanity ships no document lister at all. Documents are found by GROQ rather than listed, which is why the pattern throughout is query first, then act on the ids the query returned.

From AI assistants over MCP

Every node speaks MCP, the open protocol for connecting AI assistants to tools, so Claude, ChatGPT, and Matter, the assistant built into the platform, can drive the same surface. An agent can find content with Sanity: Run GROQ Query, read one document with Sanity: Get Document, change a field with Sanity: Patch Document and push it live with Sanity: Publish Document. Sanity publishes an official MCP server of its own and it is worth knowing before you choose. The original local server shipped as the @sanity/mcp-server npm package; that repository was archived in July 2026 and points users at its replacement, a remote vendor-hosted server at mcp.sanity.io with HTTP transport and OAuth, documented on Sanity's site. For an assistant helping you work inside Sanity, the vendor server is the better fit. This integration is the operations side: the same 40 operations as canvas steps that run on a schedule or a webhook with nobody present, chained with every other connector, with the credential held once in the workspace rather than in each person's client config and destructive nodes flagged so you can gate them.

GROQ is the read API, and that shapes everything

Sanity ships no filter-by-field REST surface. The direct document endpoint fetches by _id and nothing else, so GROQ is how an automation finds content by anything it does not already know the id of. Sanity: Run GROQ Query carries the whole language and is read-only by construction, because Sanity documents mutations as going through the Mutation API rather than through queries. Sanity: List Documents by Type and Sanity: Count Documents build the GROQ for you from a document type, an optional filter fragment, a projection, an ordering and a page window, so nobody has to learn the language for the everyday cases. All three POST rather than GET, which is why the 11 KB cap Sanity documents on query URLs cannot be reached from here. Query errors are unusually useful while you are learning: a syntax problem comes back as HTTP 400 naming the character offset in your query.

Writing documents: which node, and why

Five mutation types exist and each has a node, so you rarely need to hand-write mutation JSON. Sanity: Create Document fails if the id is taken. Sanity: Create Document If Not Exists does nothing at all when the id is taken, which is what an automation that might run twice actually wants, especially with an id derived from the source system. Sanity: Create or Replace Document writes at an id and REPLACES the whole document, so anything you leave out is gone from the new revision; that is the right node for a mirror of an external system and the wrong one for changing a single field. Sanity: Patch Document is the surgical alternative, applying set, then set if missing, then unset, then increment, then decrement, then insert, in that fixed order, and it accepts a revision so the write is refused if somebody edited the document since you read it. Sanity: Run Mutation Batch is for the cases where several documents must change together, because Sanity's mutation API is transactional: every mutation applies or none does.

Drafts, publishing and the two-document rule

A published document and its draft are two separate documents in Sanity, and the draft's id is the published id with a drafts prefix. That single fact explains several surprises. Creating an id with the drafts prefix writes a draft rather than published content. Deleting the published document leaves the draft in place, so a full removal is two deletes. And publishing is not a mutation at all: Sanity: Publish Document runs through Sanity's Actions API, which is what makes it a real publish rather than a copy, and Sanity: Unpublish Document removes the published version while leaving the draft for editors. Prefer unpublish over delete whenever the content might come back, because publish restores it and nothing was lost. Both action nodes carry optimistic lock fields that refuse the operation if either side changed since you read it.

Webhooks: let Sanity start the workflow

Sanity: Create Webhook subscribes a URL to content changes, and its two most useful fields are the GROQ filter, which narrows what fires, and the projection, which controls what is sent, so the receiving workflow gets only the fields it needs rather than a whole document. Point it at an Automations webhook trigger and the workflow starts the moment an editor publishes rather than on the next scheduled sweep. Set a secret and Sanity signs its deliveries so a receiver can verify them. Sanity: List Webhook Attempts is the debugging node and it is genuinely good: the status code the endpoint returned, how long it took, and why it failed. Sanity: Enable or Disable Webhook pauses deliveries during a bulk import so the downstream workflow is not flooded, and it is the reversible alternative to deleting; note that disabling is the only field that endpoint updates, so changing a URL or a filter means deleting and recreating.

Assets, uploaded from a URL

Sanity's asset endpoints take raw bytes and document no URL-based upload, so Sanity: Upload Image from URL and Sanity: Upload File from URL download the URL you give them server side and post the bytes. Downloads are https only and capped at 50 MB. The new asset document comes back at data.document, and data.document._id is what an image or file field on the next document should reference. Sanity de-duplicates by content hash, so uploading the same bytes twice returns the same asset rather than a second copy, which makes re-running an import cheap. Uploads are rate limited at 25 requests per second. One diagnostic note worth carrying: when these nodes fail, the failure is often the DOWNLOAD rather than Sanity, and the error text distinguishes the two.

The six destructive nodes, gated

The recovery position here is precise rather than reassuring, because the reassuring version would be wrong. Sanity: Delete Document, Sanity: Delete Documents by Query and Sanity: Run Mutation Batch can remove content, and Sanity has no trash and no undelete. Without the purge option the transaction history remains, so a determined operator can reconstruct a document through Sanity: Get Document Revision, but Sanity documents no retention window for that history: treat it as a chance, not a backup. With purge on there is nothing left to reconstruct from. Sanity: Delete Dataset is the delete history cannot soften, because the history goes with the dataset, and with the Backups API documented as enterprise only, Sanity: Export Documents and keeping the output is the safety net on Free and Growth. Sanity: Delete API Token revokes access immediately and the secret is gone for good, though access itself is recoverable by minting a replacement; deleting the token THIS connection uses breaks the integration. Sanity: Delete Webhook takes the delivery history with it and the definition is only recoverable by hand from a saved copy. The two widest write nodes, Sanity: Run Mutation Batch and Sanity: Delete Documents by Query, default their dry run option ON, so the first execution is a report. Leave it that way for the first run every time.

Limits worth designing around

Three of Sanity's documented limits change how a bulk workflow should be built. A mutation request body is capped at 4 MB, which is the nastiest one because an import that works at 200 documents can start failing at some larger number with nothing in the workflow having changed: split the batch. Delete by query operates on at most 10,000 documents and Sanity asks that larger jobs be paginated with an id cursor. Mutations and asset uploads are each limited to 25 requests per second, inside an overall ceiling of 500 requests per second. Execution timeouts are real but generous: one minute for a query, three minutes for a mutation, five minutes for an export. Dataset size limits are documented by plan, at 10,000 documents on Free and 50,000 on Growth, with 1,000 attributes per document. Two response shapes catch workflows out: management endpoints return bare arrays rather than an envelope, and Sanity: Export Documents and Sanity: List Document Transactions arrive as newline-delimited JSON, which the integration parses into data.documents and data.transactions with a count beside each.

Troubleshooting

Test Connection fails with a 401 error
The token itself is the problem rather than the project id or the dataset. Check for whitespace picked up in the copy, and confirm the token still exists under the project's Settings and then API and Tokens at sanity.io/manage. Sanity shows a token's secret only once at creation, so a value reconstructed from memory or a partially copied string will fail here. If the token was deleted, or if a workflow ran Sanity: Delete API Token against the token this connection uses, the only fix is a new token and an updated credential.
A write returns 403 while reads work perfectly
This is a role question, not a request question. Sanity's roles are a ladder: a viewer reads, a contributor writes drafts only, an editor writes and publishes, and a developer additionally manages datasets, CORS origins, tokens and webhooks. A viewer token passing Test Connection and then failing a mutation is documented behaviour. Run Sanity: List Project Permissions, which exists precisely to separate a wrong token from a wrong request, and Sanity: List Roles, which shows which roles this project can assign and whether each one applies to a robot token. Check that flag before assuming a token carries what you expected, because a role you had in mind may not be assignable to a robot at all.
A dataset-scoped node fails while management nodes work
The dataset is the likely culprit rather than the credential, since the two live on different hosts and prove different things. Open the failing node's Dataset field and use the picker rather than typing: it is sourced from Sanity: List Datasets and stores the name Sanity itself returned. If the field is blank the integration falls back to the default dataset on the credential, so a blank field with no default set is a silent misconfiguration rather than an error you can read. If the picker is empty, run Sanity: List Datasets on its own first and confirm it returns anything for this credential's project.
A GROQ query returns HTTP 400
Read the error rather than the query: Sanity answers a query parse failure with a structured body naming the character offset where parsing stopped, which is usually enough to spot the problem immediately. If the query itself is valid, check the parameters map, since a parameter referenced in the query but missing from the map fails in the same place. Query URL length is not a possible cause here, because every query node in this integration POSTs rather than GETs and Sanity's 11 KB cap applies only to GET.
A query returns stale data right after a write
Check whether Use CDN was turned on. Sanity's CDN host serves cached responses, which is exactly what you want for a public front end and exactly wrong when an automation reads back something it just wrote. It defaults to off on all three query nodes for that reason. For the strongest guarantee, Sanity: Get Document fetches straight from the Content Lake and bypasses the caching layers entirely, which is why it is the right node immediately after a write. Sanity documents it as less scalable than a query, so use it for the read-after-write case rather than inside a loop.
A document was deleted but it is still showing in the studio
A published document and its draft are two separate documents. Deleting a published id leaves the draft, whose id is the same id with a drafts prefix, so the editor still sees content that no public query returns. Delete both if a full removal was intended. The reverse case catches people too: creating an id with the drafts prefix writes a draft, so a workflow that expects its output to be live needs Sanity: Publish Document afterwards.
A create or replace wiped fields that were already on the document
That is the documented behaviour rather than a fault: Sanity: Create or Replace Document replaces the whole document, so anything omitted is gone from the new revision. The prior revision remains in the document's history, so Sanity: Get Document Revision can show you what was there. If the intent was to change part of the document, Sanity: Patch Document is the node for it, changing only the fields you name. If the intent really was a full rewrite, make sure the workflow carries the complete document into the write, for instance by reading it first with Sanity: Get Document.
A bulk import works for a while and then starts failing
Check the batch size against Sanity's 4 MB cap on a mutation request body. This is the failure that looks like intermittency: a batch of 200 documents succeeds, a batch of 800 does not, and nothing in the workflow changed. Split the mutations into smaller batches rather than raising a timeout. Two neighbouring limits are worth ruling out at the same time: mutations are rate limited at 25 requests per second, so a fan-out can trip a 429, and mutation execution is capped at three minutes.
A delete by query removed fewer documents than expected
Sanity caps a delete by query at 10,000 documents per query and asks that larger jobs be split and paginated, typically with a query that also filters on an id greater than the last one processed. Run the SAME query through Sanity: Count Documents first to see the real total, and leave the dry run option on for the first execution so the first result is a report of what would go rather than a change. The blast radius is whatever the query matches at the moment it runs, which is why counting first is the habit worth keeping.
A Sanity webhook is not starting the workflow
Read Sanity: List Webhook Attempts first: it reports whether Sanity attempted a delivery at all, the status code your endpoint returned and why it failed, which splits the problem cleanly into a Sanity-side and a receiver-side question. If no attempts appear, check Sanity: List Webhooks for whether the subscription is disabled and whether its GROQ filter actually matches the documents you are changing, since a filter that is narrower than you think produces exactly this silence. If attempts appear with a failure status, the receiving endpoint is the thing to fix, and the recorded response body usually says how.
A website stopped loading content right after a dataset change
Check whether Sanity: Update Dataset flipped the dataset to private. A private dataset immediately stops every tokenless reader, including a live website that reads with no token, and it takes effect at once rather than at the next deploy. The node is reversible by running it the other way. A second candidate is CORS: if the failure is in the browser but a server-side fetch still works, Sanity: List CORS Origins will show whether the origin is still allowed, since Sanity: Remove CORS Origin takes effect immediately too.

Sanity is a trademark of its respective owner. Mattering uses platform names to identify the services these integrations connect to; no endorsement or affiliation is implied.

Start Free Explore our Products