Overview
This node allows you to perform mutations on documents stored in Sanity.io, a popular headless CMS platform. It supports creating new documents, updating existing ones partially (patch), replacing or conditionally creating documents, and deleting documents by their ID.
Common scenarios include:
- Creating new content entries dynamically from other data sources.
- Updating specific fields of existing documents without overwriting the entire document.
- Deleting obsolete or unwanted documents programmatically.
- Conditionally creating documents only if they do not already exist.
For example, you might use this node to patch a product document with updated pricing information or create a new blog post document when a new article is published.
Properties
| Name | Meaning |
|---|---|
| Document ID | The ID of the document to operate on. Required for patch, delete, createOrReplace, and createIfNotExists operations. If left blank during creation, a random ID will be generated. |
| Document Data | JSON data representing the document or patch operations. For "Create" and similar operations, this is the full document JSON. For "Patch", this specifies the partial update operations. |
| Options | Collection of additional options: • Return Documents: Whether to return the full document(s) in the response (true/false). • API Version: The Sanity API version to use (default: "v2024-06-21"). |
Output
The output is an array of JSON objects representing the results of the mutation operations performed on each input item. Each object corresponds to a mutated document returned by the Sanity API, containing the updated or created document data.
If the option "Return Documents" is enabled, the full document(s) after mutation are included in the output.
No binary data output is produced by this node.
Dependencies
- Requires an API key credential with access to the Sanity project.
- Needs the following credential details configured in n8n:
- Project ID
- Dataset name
- API token with appropriate permissions
- Uses the Sanity HTTP API endpoint constructed as
https://{projectId}.api.sanity.io/{apiVersion}/data/mutate/{dataset}. - Supports specifying the API version; defaults to
"v2024-06-21".
Troubleshooting
- Invalid Credentials: If project ID, dataset, or token are missing or invalid, the node throws an error indicating credentials are not valid. Ensure all required credential fields are correctly set.
- Missing Document ID: For operations like patch and delete, the Document ID must be provided. Omitting it causes an error.
- Invalid JSON in Document Data: The node expects valid JSON in the "Document Data" field. Malformed JSON will cause a parsing error.
- Sanity API Errors: If the Sanity API returns an error (e.g., permission denied, invalid mutation), the node surfaces the detailed API error message. Check your API token permissions and mutation payload format.
- Continue On Fail: If enabled, the node continues processing subsequent items even if one fails, returning error details per failed item.