User Guide: Sanity Mutation Node for n8n

1. Overview

Welcome! This guide will walk you through setting up and using the Sanity Mutation node for n8n. This node is a powerful tool that allows you to connect your n8n workflows directly to your Sanity.io Content Lake.

With this node, you can programmatically create, update (patch), and delete documents in Sanity, enabling you to automate your content management, sync data from other services, and build dynamic, event-driven content workflows.

2. Prerequisites

Before you begin, please ensure you have the following:

• An n8n instance: Either on n8n.cloud or a self-hosted version.

• A Sanity.io account: If you don't have one, you can sign up for free at sanity.io.

• A Sanity Project: You need a project with a defined schema.

• A Sanity API Token: The token must have write permissions to the dataset you want to modify. You can create a new token from your project dashboard at manage.sanity.io -> Your Project -> API -> Tokens.

3. Setup: Creating Credentials

The first step is to securely store your Sanity project details in n8n.

1. In your n8n workflow, add the Sanity node to your canvas.

2. In the node's properties panel on the right, click the Credential dropdown.

3. Select Create New.

4. A dialog box will appear. Fill in the following fields:

   • Project ID: You can find this on your Sanity project dashboard or in your sanity.json file.

   • Dataset: The name of the dataset you want to connect to (e.g., production).

   • API Token: Paste the write-enabled API token you created in the prerequisites.

5. Click Save. Your credentials are now encrypted and stored in n8n, ready to be used.

4. Node Configuration

The Sanity node is configured via the properties panel in the n8n UI.

Operation

This is the most important field, as it determines the action the node will perform.

Document ID

• Required for Delete and Patch: You must provide the ID of the document you want to modify.

• Optional for Create operations: If you provide an ID, Sanity will use it. If you leave it blank, Sanity will automatically generate a unique ID for the new document.

• You can use n8n expressions here to pass in an ID from a previous node.

Document Data (JSON)

This field is where you provide the content for your mutation.

• For Create, Create or Replace, Create if Not Exists: You must provide the full JSON object for the document. The _type property is required and must match a type in your Sanity schema.

  Example:

{
    "_type": "post",
    "title": "A New Post from n8n!",
    "author": {
    "_ref": "author-id-123",
    "_type": "reference"
    }
}

• IMPORTANT: If you're using the Real Threads n8n-sanity-mapper node, you need to stringify the JSON object here.
  • {{ JSON.stringify($json) }}

• For Patch (Update): You must provide a JSON object that specifies the patch operation (e.g., set, unset, inc).

Example: Set a new title and publish the document.

{
    "set": {
    "title": "An Updated Title",
    "status": "published"
    }
}

Options

• Return Documents: (Default: true) When enabled, the node's output will include the full document(s) affected by the mutation. Disabling this will result in a faster, more minimal response.

• API Version: (Default: v2024-06-21) Specify the version of the Sanity API to use. It's generally safe to leave this as the default unless you need a specific feature from another version.

5. Usage Example: Create a Document from a Webhook

This workflow takes incoming data from a webhook (e.g., a "Contact Us" form submission) and creates a new document in Sanity.

1. Webhook Node:

• Add a Webhook node to your canvas. This will be the trigger.

• Copy the Test URL and use it to send a sample JSON payload, like this:

  {
    "name": "John Doe",
    "email": "[email protected]",
    "message": "Hello from your website!"
  }
   

2. Set Node (Optional but recommended):

• Add a Set node after the Webhook. This helps to structure the data cleanly.

• Create a property named _type and set its value to the Sanity document type you want to create (e.g., formSubmission).

• Map the incoming webhook data to the fields you want in your Sanity document.

3. Sanity Node:

• Credential: Select your Sanity API credentials.

• Operation: Choose Create.

• Document Data: Use an expression to pass the entire JSON output from the Set node: {{ $json }}.

When you execute the workflow, the Sanity node will create a new formSubmission document with the data from the webhook.

6. Input and Output

• Input: The node processes each item of incoming data from the previous node in the workflow. It uses the parameters configured in the UI to perform its action.

• Output: If Return Documents is enabled, the node will output a JSON object returned by the Sanity API containing the results of the mutation.

Sample Output for a Create operation:

[
  {
    "results": [
      {
        "id": "generated-id-5678",
        "operation": "create",
        "document": {
          "_id": "generated-id-5678",
          "_rev": "new-revision-id",
          "_type": "post",
          "title": "A New Post from n8n!",
          "author": {
            "_ref": "author-id-123",
            "_type": "reference"
          },
          "_createdAt": "2024-06-21T10:00:00Z",
          "_updatedAt": "2024-06-21T10:00:00Z"
        }
      }
    ]
  }
]

7. Error Handling

If the node encounters an error, the workflow will fail at that step and provide a descriptive error message. Common errors include:

• 401 Unauthorized: Your API Token is invalid or does not have write permissions.

• 400 Bad Request: The JSON in your Document Data field is malformed, or a required field (like _type) is missing.

• 409 Conflict: You used the Create operation with a Document ID that already exists.

Check the node's output for the specific error details to help you debug your workflow.