> ## Documentation Index
> Fetch the complete documentation index at: https://slatehq.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Sanity Block

> Create, update, and publish Sanity documents directly from your workflows.

## Overview

The Sanity block connects your workflows to a Sanity dataset. Use it to create new documents, update existing ones, or publish drafts with content generated from your workflow.

You'll find the **Sanity** block in the **Apps** section of the block palette.

***

## Configuration

### Sanity connection

Select the Sanity connection to use. Each connection points to one project and dataset.

To add a new connection:

1. Click the connection dropdown.
2. Select **Add new connection**.
3. Enter your project ID, dataset, and API token.
4. Name your connection for easy identification.

A connection that needs a new token shows **Expired** in the dropdown. For setup details, see the [Sanity integration guide](/docs/integrations/sanity).

<Note>
  Selecting a different connection clears the document type, selected document, and field mappings.
</Note>

***

### Action

Choose the operation to perform.

| Action | Description |
| - | - |
| **Create document** | Add a new document to the dataset |
| **Update document** | Change fields on an existing document |
| **Publish draft** | Publish an existing draft document |

***

### Document type

Enter the document type to work with, for example `post`. Use the exact `_type` from your Sanity Studio schema. Slate suggests types it finds in your dataset as you type.

***

## Create document

### Document ID

Give the new document a stable ID. Slate uses the ID to avoid duplicate documents if the block runs again.

* Use letters, numbers, underscores, dashes, or dots, up to 128 characters.
* Leave **Document ID** empty only if you map a non-empty field named `slug`. Slate then builds the ID from the document type and slug, for example `post.my-first-post`.

If a document with the same ID already has different content, the block fails instead of overwriting it.

***

## Update document

### Exact document and revision

Select the document to update. The list shows up to 100 of the most recently updated documents of the selected type, each labeled **Draft** or **Published**.

Slate pins the document's current revision when you select it. If the document changes after that, including from an earlier run of this block with different values, the update fails. Select the document again to pin its latest revision.

Only the fields you map are changed. With **Save as draft** on, Slate writes your changes to the document's draft and creates the draft if it doesn't exist.

***

## Publish draft

### Exact draft and revision

Select the draft to publish. Only drafts appear in this list. If the type has no drafts, the block shows "No draft documents are available for this type."

Like updates, publishing uses the pinned revision. If the draft changes after you select it, the block fails. Select the draft again to pin its latest revision.

***

## Field mappings

Map your workflow data to document fields. You need at least one mapping.

Slate infers field hints from recent documents of the selected type. Click a suggested field name to add it, or click **Field** to add a row and type the field name. Confirm fields that don't appear in the hints in Sanity Studio.

Each row has a field name, a type, and a value. Field names must match your schema and can't start with an underscore. The value can be static text or a placeholder from a previous step. The type sets how Slate formats the value:

| Type | What Slate sends |
| - | - |
| `string`, `text`, `datetime` | Text |
| `number` | A number |
| `boolean` | True for `true`, `1`, `yes`, or `on` |
| `json`, `object`, `array` | Parsed JSON. `object` must be a JSON object and `array` must be a JSON array. |
| `slug` | A slug with your value |
| `reference` | A reference to the document ID you provide |
| `portableText` | Portable Text converted from your content |

For `portableText`, choose the source format: `auto`, `markdown`, `html`, or `plainText`. Portable Text conversion doesn't support images, tables, figures, video, or inline CSS. Map those to separate schema fields.

**Example mapping:**

| Field name | Type | Value |
| - | - | - |
| `title` | `string` | `{{step_1.output.title}}` |
| `slug` | `slug` | `{{step_1.output.slug}}` |
| `body` | `portableText` | `{{step_2.output}}` |

***

## Save as draft

Toggle whether **Create document** and **Update document** write a draft or the live document.

* **On (default)**: Content is saved as a draft for review in Sanity Studio.
* **Off**: Content is written to the live document immediately. Use this only when the workflow is allowed to write live content.

***

## Output

The Sanity block returns the created, updated, or published document.

```json theme={null}
{
  "id": "drafts.post.ai-content-strategy",
  "documentId": "post.ai-content-strategy",
  "type": "post",
  "revision": "kT9xQm2LpR7vWc4Ns8bZ1e",
  "createdAt": "2026-10-08T09:30:00Z",
  "updatedAt": "2026-10-08T09:30:00Z",
  "isDraft": true,
  "delivery": {
    "providerWriteAccepted": true,
    "idempotent": false,
    "published": false,
    "transactionId": "a8Fz3RkQw9LmT2pXc5Vn1d"
  }
}
```

Access the document ID in subsequent steps using `{{step_n.output.documentId}}`.

***

## Error Handling

Define what happens if the block fails.

**Options:**

1. **Terminate workflow**: Stop the workflow as soon as the block fails.
2. **Continue execution**: Ignore the failure and move on to the next step.
3. **Retry**: Run the block again until it succeeds, up to the **Number of retries** you choose (1–5). If every retry fails, the workflow stops at this block.

Common errors and solutions:

| Error | Cause | Solution |
| - | - | - |
| Requires a documentId or a non-empty slug field | **Document ID** is empty and no `slug` field is mapped | Enter a **Document ID** or map a `slug` field |
| Document already exists with different content | **Create document** used an ID that's taken | Use a different ID, or switch to **Update document** |
| Document changed after inspection | The document changed after you selected it | Select the document again |
| Already published; select an existing draft | The selected draft was already published | Select a current draft |
| Schema sample changed after review | Recent documents of this type have different fields | Open the block so Slate reloads the field hints |
| Does not support these HTML elements | Portable Text content contains images, tables, or video | Remove those elements or map them to other fields |
| Invalid connection | The connection needs a new token | [Fix the connection](/docs/integrations/sanity#fix-a-connection-that-needs-attention) |

***

## Best Practices

* Keep **Save as draft** on while you test the workflow.
* Map a `slug` field or set a **Document ID** so repeat runs don't create duplicates.
* Check field names and types against your Sanity Studio schema.

***

## What's Next

* Read the [Sanity integration guide](/docs/integrations/sanity) to manage connections
* Learn about the [Loop Block](/docs/workflows/blocks/flow/loop) to process multiple items
* See [Liquid Templating](/docs/workflows/liquid-templating) for data transformation
* Explore the [LLM Block](/docs/workflows/blocks/ai/llm) to generate content for Sanity
* Check the [Human Review Block](/docs/workflows/blocks/flow/human-review) for approval workflows


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.