# Sanity

> Query and edit content in your Sanity headless CMS - GROQ queries, document mutations, datasets, and assets - via the HTTP API.

Lets an agent read and write content in your Sanity project. Run GROQ queries to fetch documents, apply mutations to create / update / delete documents, list datasets, get a document by id, and list image and file assets.

## What it can do

| Method | What it does |
| --- | --- |
| `sanity_query` | Run a GROQ query against the dataset, with optional parameters. |
| `sanity_mutate` | Apply mutations: create, createOrReplace, createIfNotExists, patch, or delete documents. |
| `sanity_datasets_list` | List datasets in the project. |
| `sanity_document_get` | Get a single document by its `_id`. |
| `sanity_assets_list` | List image and file assets (url, filename, size, mime type). |
| `sanity_request` | Generic passthrough to any Sanity endpoint (data or project-management host). |

## How to get your token

Sanity authenticates API calls with a project token sent as `Authorization: Bearer <TOKEN>`.

1. Go to [sanity.io/manage](https://www.sanity.io/manage) and open your project.
2. Open the **API** tab, then **Tokens**.
3. Click **Add API token**, give it a name, and choose the permission (Viewer for read-only, Editor / Deploy Studio to also write).
4. Copy the token - it is shown once - and paste it into FlyMyAI.
5. Find your **Project ID** on the same management page (it also appears in your `sanity.config.ts`).
6. Note your **Dataset** name - it is usually `production`.

## Fields to fill

| FlyMyAI field | Where it comes from |
| --- | --- |
| `SANITY_TOKEN` | sanity.io/manage -> project -> API -> Tokens |
| `SANITY_PROJECT_ID` | sanity.io/manage -> project (the short project ID) |
| `SANITY_DATASET` | Optional - the dataset name, usually `production` |

## Troubleshooting

- **`401 Unauthorized`** - the token is wrong or revoked. Create a new one in API -> Tokens.
- **`403 Forbidden` on `sanity_mutate`** - the token is read-only. Issue a token with Editor (or higher) permission to write documents.
- **Empty query results** - check the dataset name. If your content lives in `staging`, set `SANITY_DATASET=staging` (the default is `production`).
- **`project not found`** - the `SANITY_PROJECT_ID` is wrong; copy it exactly from sanity.io/manage.

## Links

- [Sanity HTTP API reference](https://www.sanity.io/docs/http-reference)
- [GROQ query language](https://www.sanity.io/docs/groq)
- [Manage your project (tokens)](https://www.sanity.io/manage)