Overview
This node allows you to perform mutations on documents in a Sanity.io dataset. It supports creating new documents, updating existing ones partially (patch), deleting documents, and conditional creation operations such as "Create if Not Exists" or "Create or Replace". This is useful for workflows that need to synchronize data with Sanity, automate content updates, or manage datasets programmatically.
Practical examples:
- Automatically create a new blog post document only if it does not already exist.
- Update specific fields of an existing product document without replacing the entire document.
- Delete outdated or irrelevant documents based on external triggers.
- Replace an entire document with new data when a major update is required.
Properties
| Name | Meaning |
|---|---|
| Document ID | The ID of the document to operate on. If creating and left blank, a random ID will be generated automatically. |
| Document Data | The JSON data representing the document content or patch operations. For "Create", this is the full document; for "Patch", it specifies patch instructions. |
| 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 (e.g., "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, including its current state after the operation.
If the option to return documents is enabled, the full document data is included in the output JSON. There is no binary data output from this node.
Dependencies
- Requires valid Sanity.io credentials including:
- Project ID
- Dataset name
- An API authentication token with permissions to mutate documents
- The node makes HTTP POST requests to the Sanity Mutation API endpoint.
- The API version can be specified via node options; defaults to "v2024-06-21".
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: If the "Document Data" field contains malformed JSON, the node reports an error specifying the issue.
- Sanity API Errors: Errors returned by the Sanity API are captured and presented with detailed messages. Check the API token permissions and request payload correctness.
- Continue On Fail: If enabled, the node continues processing subsequent items even if some fail, returning error details per failed item.