Overview
This node allows you to perform mutations on documents stored in Sanity.io, a popular headless CMS platform. It supports creating new documents, conditionally creating documents if they do not exist, replacing existing documents, deleting documents, and patching (partially updating) documents.
Common scenarios include:
- Creating new content entries or assets in your Sanity dataset.
- Updating or patching existing documents with new data without replacing the entire document.
- Deleting obsolete or incorrect documents.
- Conditionally creating documents only if they don't already exist, useful for idempotent workflows.
For example, you might use this node to create a blog post document with specific fields, update an author's profile partially, or delete outdated event entries.
Properties
| Name | Meaning |
|---|---|
| Document ID | The ID of the document to operate on. For creation, if left blank, a random ID will be generated. |
| Document Data | The JSON data representing the full document (for create operations) or patch instructions (for patch). |
| Options | Collection of additional options: • Return Documents: Whether to return the full document(s) in response (true/false). • API Version: The Sanity API version to use (e.g., "v2024-06-21"). |
Output
The output is a JSON array where each item corresponds to the result of a mutation operation performed on the input items. Each output item contains the mutated document(s) returned by the Sanity API, unless the option to not return documents is set.
If the "Return Documents" option is enabled (default), the output JSON includes the full document(s) as returned by Sanity after the mutation.
No binary data output is produced by this node.
Dependencies
- Requires valid Sanity.io credentials including:
- Project ID
- Dataset name
- An API authentication token with permissions to mutate documents.
- The node uses the Sanity HTTP API endpoint constructed from these credentials and the specified API version.
- No other external dependencies are required.
Troubleshooting
- Invalid Credentials: If project ID, dataset, or token are missing or invalid, the node throws an error indicating invalid credentials.
- Missing Document ID: For operations like delete and patch, the Document ID must be provided; otherwise, an error is thrown.
- Invalid JSON in Document Data: If the JSON provided in the "Document Data" field cannot be parsed, an error specifying the JSON parsing issue is raised.
- Sanity API Errors: If the Sanity API returns an error, it is captured and presented with details from the API response.
- Continue On Fail: If enabled, the node continues processing subsequent items even if one fails, returning error details per failed item.