Sanity

Sync data to Sanity documents via the HTTP Mutations API. Use Zeotap to push structured content such as product listings, articles, localized pages, or any document type to your Sanity Content Lake.

Prerequisites

• A Sanity account with an active project
• A dataset configured in the target project (e.g., production)
• A robot token or personal access token with write access to the project
• The project ID and dataset name

Authentication

Sanity uses an API token (robot token or personal access token) for authentication.

1. Log in to manage.sanity.io 
2. Select your project
3. Navigate to Settings > API > Tokens
4. Click Add API token
5. Give the token a descriptive name (e.g., “Zeotap Sync”)
6. Set the permissions to Editor or Deploy Studio (the token must have write access)
7. Click Save and copy the token
8. Paste the token into the API Token field in Zeotap

Required Permissions

• The token must have write access to the target dataset
• Robot tokens are recommended over personal tokens for production integrations
• Robot tokens persist until deleted; personal tokens expire after one year

Configuration

Supported Operations

Sync Modes

Audience Sync Modes

Sanity does not support audience sync modes. Documents are not membership-based.

Features

• Field Mapping: Yes — map source fields to Sanity document fields
• Schema Introspection: No — field names must be configured manually using your Sanity schema field names

Required Mapping Fields

Default Destination Fields

How It Works

Zeotap writes data to Sanity using the HTTP Mutations API:

1. Insert mode: Each row is sent as a createIfNotExists mutation. If a document with the same _id already exists, the row is silently skipped.
2. Update mode: Each row is sent as a patch mutation with a set operation. All mapped fields (except _id and _type) are set on the existing document. Rows without a primary key (_id) are reported as failures.
3. Upsert mode: Each row is sent as a createOrReplace mutation. If a document with the same _id exists, it is fully replaced with the new data.

Batch Processing

Mutations are sent in batches of up to 100 operations per API request to stay within Sanity’s 4 MB request body limit. Each batch is sent as a single transactional request — either all mutations in the batch succeed or all fail.

Document Structure

Sanity documents are flat JSON objects. The _id field serves as the unique document identifier, and _type determines the document schema. All other fields from your mapping are written directly as document properties:

{
  "mutations": [
    {
      "createOrReplace": {
        "_id": "product-123",
        "_type": "product",
        "title": "Widget Pro",
        "price": 29.99,
        "sku": "WP-123"
      }
    }
  ]
}

Document IDs

When a primary key is mapped, its value is used as the Sanity _id. If no primary key is provided in insert mode, Sanity auto-generates a unique ID. For update and upsert modes, a primary key is required to identify the target document.

Rate Limits

Sanity enforces rate limits on the Mutations API:

If a 429 Too Many Requests response is received, Zeotap automatically retries with exponential backoff.

Best Practices

• Use robot tokens: Robot tokens are preferred over personal tokens for production integrations. They persist until deleted and are not tied to a user session.
• Map _type correctly: Every Sanity document requires a _type field that matches a document type defined in your Sanity schema. Mismatched types will cause validation errors.
• Use stable document IDs: For upsert and update modes, use a stable identifier from your source data (e.g., a product SKU or external ID) as the primary key. This becomes the Sanity _id.
• Test in a development dataset: Create a non-production dataset for testing syncs before writing to your live content.
• Keep batches focused: Sync a single document type per destination. Create separate destinations for different document types.
• Avoid large documents: Keep individual document payloads small to stay within the 4 MB request body limit when batching.

Troubleshooting

Authentication failed: invalid or insufficient API token

Verify that the API token is correct and has write permissions. Tokens can be managed in manage.sanity.io  under Settings > API > Tokens. Revoked tokens or tokens with read-only permissions will fail.

Project or dataset not found

The project ID or dataset name is incorrect. Verify the project ID in manage.sanity.io  and check available datasets under Settings > Datasets. Project IDs are alphanumeric strings (e.g., abc123de).

Missing primary key for update mode

Update mode requires each row to have a primary key that maps to the Sanity _id field. Ensure your source data includes a unique identifier column and that it is mapped as the primary key in Zeotap.

Document type validation errors

Sanity validates documents against the schema defined in your Sanity Studio. Common causes include:

• The _type field does not match any document type in the schema
• A required field defined in the schema is missing from the mapped data
• A field value does not match the expected type (e.g., sending a string to a number field)
• Reference fields require a specific format ({_type: "reference", _ref: "document-id"})

Batch mutation failed

When a mutation batch fails, all mutations in the batch are rolled back (transactional behavior). Check the error message for the specific cause. Common reasons include exceeding the 4 MB body limit or permission errors. Reduce the amount of data per row or the number of fields mapped.

Rate limited (429 Too Many Requests)

Your API token’s rate limit has been exceeded (25 mutation requests per second). Zeotap retries automatically with exponential backoff. For high-volume syncs, consider spacing out sync runs or reducing the number of concurrent syncs targeting the same Sanity project.

Documents not appearing in Sanity Studio

Verify that the _type field matches a document type defined in your Sanity schema. Documents with unknown types are stored in the Content Lake but may not appear in the Studio’s document list unless the schema includes that type. Also check that you are looking at the correct dataset.

Cross-dataset reference errors

If your documents contain references to documents in other datasets, you may need to use weak references or enable cross-dataset reference support. By default, Sanity validates that referenced documents exist in the same dataset.