Agent Actions
generate
agentActions.generate
Have Sanity’s AI write content into a document’s fields from an instruction, following the schema. Writes to the draft unless forcePublishedWrite; noWrite returns it without saving. Costs one Sanity AI credit.
Risk: write
documentId to write into an existing document, or targetDocument to create one. target limits which fields it writes. It can’t write file fields or fields the schema marks hidden or read-only, and it writes date fields only with localeSettings. Long generations can outlast a Corsair script, so pass async: true and read the document later.
localeSettings full type
localeSettings full type
targetDocument full type
targetDocument full type
document full type
document full type
prompt
agentActions.prompt
Ask Sanity’s AI a question, optionally about documents passed as params, and get text or JSON back. Writes nothing. Costs one Sanity AI credit.
Risk: read
format: 'json', the instruction must contain the word json.
Output
transform
agentActions.transform
Have Sanity’s AI rewrite a document’s existing content by an instruction (tone, length, style), in place or into another document. Costs one Sanity AI credit.
Risk: write
localeSettings full type
localeSettings full type
targetDocument full type
targetDocument full type
document full type
document full type
translate
agentActions.translate
Have Sanity’s AI translate a document into another language, usually into a new document. Costs one Sanity AI credit.
Risk: write
targetDocument set to create, so the source stays as it is.
localeSettings full type
localeSettings full type
toLanguage full type
toLanguage full type
fromLanguage full type
fromLanguage full type
targetDocument full type
targetDocument full type
document full type
document full type
Assets
upload
assets.upload
Upload an image or file (base64, up to 25 MB) as a Sanity asset and get its asset document and CDN URL, ready to reference from a document.
Risk: write
{ _type: 'image', asset: { _type: 'reference', _ref: asset._id } }.
Output
asset full type
asset full type
Datasets
create
datasets.create
Create an empty dataset in the project. Needs an administrator token.
Risk: write
delete
datasets.delete
Delete a dataset with every document and asset in it, for good. Needs the name twice and an administrator token.
Risk: destructive · Irreversible
confirmName must repeat the name.
Output
list
datasets.list
The project’s datasets and whether each is public.
Risk: read
datasets full type
datasets full type
Documents
create
documents.create
Create a document as a draft (default) or, with publish: true, publish it at once. Returns its id and draft id.
Risk: write
ifExists only checks the draft. With the _id of a published document, a new draft is made over it.
document full type
document full type
delete
documents.delete
Delete up to 100 documents, published and draft together. Documents that reference them must drop the references first. With purge, they also leave the history.
Risk: destructive
discardDraft
documents.discardDraft
Throw away a document’s unpublished changes (its draft). The published version stays. With purge, the draft also leaves the history.
Risk: destructive
edit
documents.edit
Change a document the way the Studio does: the patch goes to its draft, made from the published version if needed, and nothing goes live until documents.publish (or publish: true).
Risk: write
documents.patch with ifRevisionId when two writers might collide.
insert full type
insert full type
get
documents.get
Fetch up to 100 documents by exact id (drafts.<id> for a draft). Ids that are missing or unreadable come back in omitted.
Risk: read
omitted with the reason.
Output
documents full type
documents full type
omitted full type
omitted full type
history
documents.history
A document as it stood at a revision or a point in time. How far back depends on the plan’s history retention.
Risk: read
lastRevision: true reads a deleted document as it was just before the delete, which is how you recover one. How far back history goes depends on the plan.
Output
document full type
document full type
mutate
documents.mutate
Apply raw Sanity mutations (create, createOrReplace, createIfNotExists, patch, delete, by id or by query) in one transaction. For anything documents.create, edit, patch and delete can’t express.
Risk: destructive
transactionId to make a retry safe, since Sanity refuses a used one with a 409.
Output
results full type
results full type
patch
documents.patch
Patch one exact document id directly and get it back. A published id changes the live document at once; use documents.edit to go through a draft. ifRevisionId guards against overwriting someone else’s change.
Risk: write
ifRevisionId gets a 409 and changes nothing.
insert full type
insert full type
document full type
document full type
publish
documents.publish
Publish a document’s draft: the draft replaces the published version and goes away. Fails when there is no draft.
Risk: write
query
documents.query
Run a GROQ query against a dataset and get its result. Reads published documents unless perspective says otherwise. Pass user input as params.
Risk: read
perspective (drafts, raw, or a list of release names). Pass user input as params, never inside the query string. Project the fields you need and slice the results, since answers above 1 MB can be cut off on Corsair’s cloud.
Output
transactions
documents.transactions
The transactions that changed some documents: when, by whom and which revisions, optionally with each mutation.
Risk: read
documents.history. Sanity merges quick successive edits by one author into one entry.
Output
transactions full type
transactions full type
unpublish
documents.unpublish
Take a published document off the published perspective; its content stays as a draft.
Risk: write
Schemas
list
schemas.list
The schemas deployed to a dataset: their ids (the schemaId Agent Actions take) and each type’s fields. Pass type for one type’s full definition. Read this before writing documents of a type you don’t know.
Risk: read
sanity schemas list uses, which Sanity’s HTTP reference doesn’t cover yet.
Output
schemas full type
schemas full type
Webhooks
attempts
webhooks.attempts
Recent delivery attempts of a webhook with the status your endpoint answered, to debug failing deliveries.
Risk: read
attempts full type
attempts full type
create
webhooks.create
Create a webhook that POSTs to a URL when documents matching a GROQ filter are created, updated or deleted. Set a secret so deliveries can be verified.
Risk: write
webhook full type
webhook full type
delete
webhooks.delete
Delete a webhook; deliveries stop at once.
Risk: destructive
list
webhooks.list
The project’s GROQ-powered webhooks: url, dataset, filter, projection and whether each is signed (never the secret).
Risk: read
hasSecret instead.
Output
webhooks full type
webhooks full type
update
webhooks.update
Change a webhook’s url, filter, projection, events or secret, or pause and resume it with disabled.
Risk: write
on, filter or projection keeps the parts of the rule you leave out.
Output
webhook full type
webhook full type