> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/integrations/catalog/sanity.md).

# Sanity

Manage content in Sanity CMS: run GROQ queries, create / read / update / delete documents, and upload image and file assets.

## Connectors

Choose the connector that matches your authentication method. The options below use the names shown in StackAI.

| Connector | Authentication |
| --------- | -------------- |
| Sanity    | API Token      |

### Sanity

Connect to Sanity CMS with a Project ID, dataset, and project-scoped API token (Editor role recommended). Uses the Content Lake API for GROQ queries, document create / read / update / delete, and asset uploads. The Project ID is not the Organization ID, and organization-level management tokens are not accepted.

#### Set up in Sanity

1. Sign in to sanity.io and open the project you want to connect (note its Project ID, shown in project settings; this is not the Organization ID).
2. Go to the project's API settings and create a new token with the Editor role (recommended for read and write), scoped to this project.
3. Copy the token value immediately and note the dataset name (for example, production).

#### Set up in StackAI

1. Open **Settings → Connections**, add a connection, and select **Sanity**.
2. Enter the credentials and connection details in the fields below.
3. Save the connection and check its connection status. Select this saved connection when configuring an action or feature that uses it.

**Connection fields**

| StackAI field | Required | What to enter                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Project ID    | Yes      | Your Sanity Project ID — NOT the Organization ID. At <https://www.sanity.io/manage> select the project from the top picker, then copy the value shown under 'PROJECT ID' in the project header (next to 'ORGANIZATION ID'). It is typically 8 lowercase alphanumeric characters, e.g. 'abc123de'. Do not paste the ORGANIZATION ID — it will be rejected. [Provider instructions](https://www.sanity.io/manage).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| Dataset       | Yes      | The dataset within the project to connect to, e.g. 'production' or 'staging'. See the project's Datasets tab at <https://www.sanity.io/manage> for the list. Datasets isolate content within a project; pick the one you want to query or mutate.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| API Token     | Yes      | A project-scoped Sanity API token. Create one inside the project at <https://www.sanity.io/manage> → your project → API → Tokens → Add API token. Pick the role based on what the workflow needs: • Writes (create / update / delete documents, upload assets): use 'Editor' (minimum). 'Developer' also works (same data scope plus project-settings access you don't need). • Read-only (query\_groq, get\_document only): 'Viewer' is enough. These roles will NOT work for any workflow: 'Contributor' (drafts only — publishing and non-draft mutations fail), 'Deploy Studio' (Studio / GraphQL deploy only, no data access), 'Access Manager' (project user / role management, no data access). Organization-level tokens (issued from the org's API page with permissions like 'Manage SDK Apps', 'Media Library', 'Canvas', 'Deploy Studios', 'Manage Access') will NOT authenticate against the Content Lake API and will 401. [Provider instructions](https://www.sanity.io/manage). |

**Provider documentation:** [Setup reference](https://www.sanity.io/docs/http-auth).

### Verify the connection

Check that the connection is healthy. Then run a read operation against a resource the connected account can access. A successful connection check confirms authentication; it does not guarantee permission for every action.

If access is denied, check the credential or OAuth permissions, the selected account or environment, and access to the specific resource. Update expired credentials or reconnect after permissions change.

## Use an action

1. Add the required **Sanity** action to the workflow.
2. Select a connection when the action requests one.
3. Complete the required fields. Use the reference picker when a value comes from another workflow step.
4. Run the workflow and inspect the action’s output. Check the result before using it in a later step.

## Actions

### Query GROQ

Run a GROQ query against a Sanity dataset and return the results.

#### Inputs

| Field            | Type            | Required | Description                                                                                                                                              |
| ---------------- | --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GROQ Query       | textarea        | Yes      | A GROQ query string to run against the dataset.                                                                                                          |
| Query Parameters | object          | No       | Optional JSON object of parameter values for $-placeholders in the query.                                                                                |
| Perspective      | select (string) | No       | Which view of the dataset to query: published documents, preview drafts, or the raw dataset. Available values: Published (default), Preview Drafts, Raw. |

#### Outputs

| Field           | Type    | Description                                                           |
| --------------- | ------- | --------------------------------------------------------------------- |
| Result          | object  | The result of the GROQ query (shape depends on the query).            |
| Query Time (ms) | integer | How long the query took to execute on Sanity's side, in milliseconds. |

### Get Document

Fetch a single Sanity document by its \_id.

#### Inputs

| Field       | Type   | Required | Description                           |
| ----------- | ------ | -------- | ------------------------------------- |
| Document ID | string | Yes      | The Sanity document \_id to retrieve. |

#### Outputs

| Field    | Type    | Description                                               |
| -------- | ------- | --------------------------------------------------------- |
| Document | object  | The document body, or null if the document was not found. |
| Found    | boolean | Whether a document with the given id exists.              |

### Create Document

Create a new Sanity document with a given type, fields, and optional id.

#### Inputs

| Field         | Type            | Required | Description                                                                                                                                                                                                                 |
| ------------- | --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Document Type | string          | Yes      | The schema \_type for the new document (e.g. 'post', 'author').                                                                                                                                                             |
| Fields        | object          | Yes      | The document fields as a JSON object.                                                                                                                                                                                       |
| Document ID   | string          | No       | Optional custom \_id. Sanity auto-generates one if omitted.                                                                                                                                                                 |
| Create Mode   | select (string) | No       | 'Create' fails if the id already exists. 'Create or Replace' overwrites any existing document. 'Create if Not Exists' silently skips when the id exists. Available values: Create, Create or Replace, Create if Not Exists. |

#### Outputs

| Field       | Type   | Description                                        |
| ----------- | ------ | -------------------------------------------------- |
| Document ID | string | The \_id of the created document.                  |
| Document    | object | The full created document body returned by Sanity. |

### Update Document

Patch a Sanity document by id with set, unset, or increment operations.

#### Inputs

| Field            | Type   | Required | Description                                                                 |
| ---------------- | ------ | -------- | --------------------------------------------------------------------------- |
| Document ID      | string | Yes      | The \_id of the document to patch.                                          |
| Set Fields       | object | No       | Fields to set (replace) on the document, as a JSON object.                  |
| Unset Fields     | array  | No       | Names of fields to remove from the document.                                |
| Increment Fields | object | No       | Numeric fields to increment, as a JSON object mapping field name to amount. |

#### Outputs

| Field       | Type   | Description                             |
| ----------- | ------ | --------------------------------------- |
| Document ID | string | The \_id of the updated document.       |
| Document    | object | The full document body after the patch. |

### Delete Document

Delete a Sanity document by its \_id.

#### Inputs

| Field       | Type   | Required | Description                         |
| ----------- | ------ | -------- | ----------------------------------- |
| Document ID | string | Yes      | The \_id of the document to delete. |

#### Outputs

| Field       | Type    | Description                                          |
| ----------- | ------- | ---------------------------------------------------- |
| Document ID | string  | The \_id of the deleted document.                    |
| Deleted     | boolean | True when Sanity confirmed the document was removed. |

### Upload Asset

Upload an image or file to Sanity by URL. Sanity fetches the asset itself.

#### Inputs

| Field      | Type   | Required | Description                                                                                       |
| ---------- | ------ | -------- | ------------------------------------------------------------------------------------------------- |
| Source URL | string | Yes      | Publicly accessible URL of the file to upload. Sanity fetches and stores the asset from this URL. |
| Filename   | string | No       | Optional filename to store the asset under.                                                       |

#### Outputs

| Field     | Type   | Description                                 |
| --------- | ------ | ------------------------------------------- |
| Asset ID  | string | The \_id of the created asset document.     |
| Asset URL | string | The public CDN URL for the uploaded asset.  |
| Asset     | object | The full asset document returned by Sanity. |

## Important behavior

Actions that create, update, send, or delete data can change the connected service. Review their inputs before running them. A retry can repeat an operation; consider this when configuring retries for actions that change data.

The catalog lists the fields and capabilities available in the supplied provider definition. Availability can also depend on your deployment and organization’s Feature Access settings.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/integrations/catalog/sanity.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
