> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atako.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Sanity
> Connect Sanity to your Atako agents — 4 read and 3 write actions.
Let your agents read and write the content of a Sanity project — list datasets, run GROQ queries, fetch documents and past revisions, then create, replace or patch documents.
## Connection
* **Authentication**: API key (Project API token).
* **Required settings**:
* **Project ID** — sanity.io/manage → your project → Project ID (8 lowercase letters and digits).
Sign in at sanity.io/manage → select your project → Settings → API → Tokens → Add new token. Name it and pick the Viewer permission for read-only agents, or Editor if they must write; copy the token (it is shown only once). The Project ID is at the top of the project page in sanity.io/manage; your dataset names (e.g. production) are listed under Datasets.
See [Sanity's documentation](https://www.sanity.io/docs/content-lake/http-auth).
## Read actions (4)
| Action | Description |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `get_document` | Retrieve one document by id, uncached (returns \{"documents":\[…]}, empty when it does not exist). Arguments: dataset (string); id (string, e.g. "post-123", or "drafts.post-123" for its draft). To fetch several documents, use query with \*\[\_id in \$ids] and params \{"ids":\[…]}. |
| `get_document_revision` | Retrieve a past version of a document from its history. Arguments: dataset (string); id (string); then one of revision (optional string, a \_rev value), time (optional ISO 8601 date-time, the document as it was at that instant) or lastRevision (optional boolean, true = last revision, including the state before a deletion). |
| `list_datasets` | List the datasets of the connected project (name and visibility) — their names are the "dataset" argument every other action needs. A cheap way to check the connection works. |
| `query` | Run a GROQ query against a dataset and return its "result". Arguments: dataset (string, from list\_datasets, e.g. "production"); query (string, a GROQ query, e.g. *\[\_type == "post"] \| order(\_createdAt desc)\[0...10]\{\_id, title} or count(*\[\_type == "author"])); params (optional object of GROQ parameters without the $— {"slug":"hello"} for$slug — values are strings, numbers, booleans, arrays or objects); perspective (optional: "published" (default) ignores drafts, "drafts" reads drafts as if published, "raw" returns published, drafts.\* and versions.\* side by side). Very long queries (over \~10 kB once URL-encoded) are rejected: narrow them. |
## Write actions (3)
| Action | Description |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `create_document` | Create a document; fails if its \_id already exists. Arguments: dataset (string); document (object: \_type string required — a schema type of the project, e.g. "post"; \_id optional string, generated when omitted, "drafts.\" creates a draft instead of a published document; every other key is a field of that type, e.g. \{"\_type":"post","title":"Hello","slug":\{"\_type":"slug","current":"hello"}}; a reference is \{"\_type":"reference","\_ref":"\"}); returnDocuments (optional boolean, true returns the full saved documents); dryRun (optional boolean, true validates without writing); autoGenerateArrayKeys (optional boolean, true adds the \_key every array item of objects needs). |
| `create_or_replace_document` | Create a document, or REPLACE it entirely when its \_id exists (fields left out are removed — read it with get\_document first to keep them). Arguments: dataset (string); document (object: \_id string required, \_type string required, every other key is a field, same shape as create\_document); returnDocuments (optional boolean, true returns the full saved documents); dryRun (optional boolean, true validates without writing); autoGenerateArrayKeys (optional boolean, true adds the \_key every array item of objects needs). |
| `patch_document` | Modify fields of ONE existing document, identified by id (fails if it does not exist). Operations run in this order, at least one required: set (optional object, field path → new value, e.g. \{"title":"New","author.name":"Ada"}); setIfMissing (optional object, same shape, only for absent fields); unset (optional array of field-path strings to remove, e.g. \["subtitle"]); inc / dec (optional objects, field path → number to add / subtract, e.g. \{"views":1}). Arguments: dataset (string); id (string — patching "post-123" changes the PUBLISHED document, "drafts.post-123" its draft); ifRevisionID (optional string, the \_rev you read: the patch fails if the document changed since); returnDocuments (optional boolean, true returns the full saved documents); dryRun (optional boolean, true validates without writing); autoGenerateArrayKeys (optional boolean, true adds the \_key every array item of objects needs). |
## Permissions
Every action above must be explicitly granted to an agent before it can be used. See [Permissions](/integrations/permissions) for the grant model and [Security](/integrations/security) for how credentials are protected.