Overview
This node allows you to perform mutations on documents stored in Sanity.io, a popular headless CMS platform. It supports creating, updating (patching), replacing, conditionally creating, and deleting documents within a specified Sanity dataset.
Common scenarios where this node is beneficial include:
- Automating content updates or deletions in your Sanity dataset based on external triggers.
- Creating new documents programmatically with dynamic data.
- Patching existing documents partially without replacing the entire document.
- Ensuring a document exists by creating it only if it does not already exist.
- Deleting obsolete or unwanted documents automatically.
For example, you could use this node to delete a document by its ID when a certain event occurs, such as removing outdated blog posts or cleaning up test data.
Properties
| Name | Meaning |
|---|---|
| Document ID | The ID of the document to operate on. Required for delete, patch, createOrReplace, and createIfNotExists operations. If creating and left blank, a random ID will be generated. |
| 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 node outputs an array of JSON objects representing the results of the mutation operations performed on each input item. Each output item corresponds to one input item and contains the mutated document(s) returned from Sanity, depending on the "Return Documents" option.
If enabled, the full document(s) affected by the mutation are included in the output JSON under the json property.
This node does not output binary data.
Dependencies
- Requires valid Sanity API 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 using these credentials.
- The user must configure these credentials securely in n8n before using the node.
Troubleshooting
- Missing Credentials: If project ID, dataset, or token are missing or invalid, the node throws an error "Credentials are not valid!" Ensure all required credential fields are correctly set.
- Invalid JSON in Document Data: If the "Document Data" field contains malformed JSON, the node throws an error indicating invalid JSON with details. Verify and correct the JSON syntax.
- Missing Document ID for Delete or Patch: These operations require a document ID. Omitting it causes an error "Document ID is required for delete operation." or similar for patch. Provide a valid document ID.
- 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 the API token permissions and mutation payload format.
- Continue On Fail: If enabled, the node continues processing subsequent items even if some fail, returning error details per failed item.