Reference documentation for the Agent Actions HTTP API.
Use AI and LLMs to interact with and modify your content.
Parameterized base URL
https://{projectId}.api.sanity.io/{apiVersion}/agent/action"your-project-id"Sanity project ID
"vX"API version
/generate/{dataset}Sends an instruction request to Generate for a specific dataset.
Examples and implementation details can be found in the Generate documentation.
application/jsonThe schema identifier reported by sanity deploy or sanity schema store.
sanity.workspace.schema.defaultAllows the instruction to modify conditional readOnly or hidden fields. Does not apply to fields explicitly set as hidden or readOnly in the schema.
When false, forces all conditional readOnly fields to be writable.
trueWhen false, forces all conditional hidden fields to be writable.
Override the default behavior of individual conditional paths.
Defines the starting point, or root, of the area to affect.
To further control the behavior, use include, exclude, types.include, and types.exclude.
Examples:
"body" // Simple string path
{ "_key": "section1" } // Array item by key
Path string
bodyWhen false, the field is writable.
Set to true to mutate published documents. By default, Agent Actions will never mutate a published document. They will use a draftId if a publishedId is provided.
Operations on drafts receive initial state from the published document, if no draft exists. If a draft exists, it is used as the initial state.
The returned _id will be that of the modified document.
Documents set to liveEdit: true will be mutated as if forcePublishedWrite: true.
Controls the level of variance in the response. A higher value returns more variation in responses, while a lower value returns more predictable responses.
0.7When provided with locale settings, Generate will write to date and datetime fields.
Otherwise, those fields will be ignored.
{"locale":"en-US","timeZone":"America/New_York"}A valid unicode BCP 47 locale identifier. This will affect how natural language time and date phrases are parsed and presented.
en-USA valid IANA time zone identifier. This will ensure dates and times are interpreted correctly relative to the user's local time.
America/New_YorkWhen true, documents aren't created or mutated.
When true, requests occur in the background. True is incompatible with noWrite: true.
Describes the instruction. Reference instructionParams using the $variable syntax.
Create a new document with a title like $title, that matches the style of $externalTitle, and generate content based on the $backgroundContext.
Parameter values available to reference in the instruction.
There are four types of parameters:
constant: Set a static value. Ex: paramName: { type: 'constant', value: 'New title'}field: Target a field in the document to set the parameter to its value. Also takes an optional documentId to target a field in a different document. Ex: paramName: { type: 'field', path: 'poster'}groq: Set the parameter to the result of a GROQ query. Ex: paramName: { type: 'groq', query: '*[_type == $docType]', params: { 'docType': 'article'} }document: Set the parameter to the value of the entire document. If no documentID is provided, the current document is returned. Ex: paramName: { type: 'document', documentId: '123'}Defines which parts of the document will be affected by the Generate instruction.
A list of paths that define the target area.
Each path in the list can be either a string or a key object.
Path string
bodyThe maximum depth of the document paths the instruction can write to.
Depth is based on field path segments:
title has a depth of 1author.name has a depth of 2array[_key="123"].title has a depth of 3Use caution when setting this value too high in studios with recursive document schemas
as it may cause performance and response quality issues.
Define fields or array items to exclude from the instruction. Any omitted fields or array items are implicitly included.
By default, all children up to the maxPathDepth are included.
Example:
["metadata", "draft", { "_key": "tempSection" }]
Path string
bodyConfigure which document types to include or exclude from the instruction.
Example:
{
"include": ["text", "image", "video"]
}
["text","image"]Path string
bodySets the default operation for all paths in the target.
Operation types:
set instead.Use include to override the default operation for specific paths.
Nested fields inherit the operation of their parent, and fall back
to the top level target operation unless otherwise specified.
Set to the document ID of the document you want to modify.
This is the shorthand equivalent of targetDocument: { _id: '123', operation: 'edit' }.
Mutually exclusive with targetDocument.
Request was successful, returning the modified document shape.
The ID of the document.
123The type of the document.
articleThe creation date of the document.
2025-03-12T19:28:18ZThe last update date of the document.
2025-03-12T19:28:18ZThe revision number of the document.
rev123Additional properties of the document depend on the document schema.
/transform/{dataset}Transforms a source document into a new document.
Examples and implementation details can be found in the Transform documentation.
application/jsonThe schema identifier reported by sanity deploy or sanity schema store.
sanity.workspace.schema.defaultAllows the instruction to modify conditional readOnly or hidden fields. Does not apply to fields explicitly set as hidden or readOnly in the schema.
When false, forces all conditional readOnly fields to be writable.
trueWhen false, forces all conditional hidden fields to be writable.
Override the default behavior of individual conditional paths.
Defines the starting point, or root, of the area to affect.
To further control the behavior, use include, exclude, types.include, and types.exclude.
Examples:
"body" // Simple string path
{ "_key": "section1" } // Array item by key
Path string
bodyWhen false, the field is writable.
Set to true to mutate published documents. By default, Agent Actions will never mutate a published document. They will use a draftId if a publishedId is provided.
Operations on drafts receive initial state from the published document, if no draft exists. If a draft exists, it is used as the initial state.
The returned _id will be that of the modified document.
Documents set to liveEdit: true will be mutated as if forcePublishedWrite: true.
Controls the level of variance in the response. A higher value returns more variation in responses, while a lower value returns more predictable responses.
0.7When provided with locale settings, Generate will write to date and datetime fields.
Otherwise, those fields will be ignored.
{"locale":"en-US","timeZone":"America/New_York"}A valid unicode BCP 47 locale identifier. This will affect how natural language time and date phrases are parsed and presented.
en-USA valid IANA time zone identifier. This will ensure dates and times are interpreted correctly relative to the user's local time.
America/New_YorkWhen true, documents aren't created or mutated.
When true, requests occur in the background. True is incompatible with noWrite: true.
The ID of the source document to transform.
123The target document to transform and the operation to perform.
If omitted, the source document (documentId) will be used as the target.
Describes the instruction. Reference instructionParams using the $variable syntax.
Create a new document with a title like $title, that matches the style of $externalTitle, and generate content based on the $backgroundContext.
Parameter values available to reference in the instruction.
There are four types of parameters:
constant: Set a static value. Ex: paramName: { type: 'constant', value: 'New title'}field: Target a field in the document to set the parameter to its value. Also takes an optional documentId to target a field in a different document. Ex: paramName: { type: 'field', path: 'poster'}groq: Set the parameter to the result of a GROQ query. Ex: paramName: { type: 'groq', query: '*[_type == $docType]', params: { 'docType': 'article'} }document: Set the parameter to the value of the entire document. If no documentID is provided, the current document is returned. Ex: paramName: { type: 'document', documentId: '123'}Defines which parts of the document will be affected by the Transform instruction.
A list of paths that define the target area.
Each path in the list can be either a string or a key object.
Path string
bodyThe maximum depth of the document paths the instruction can write to.
Depth is based on field path segments:
title has a depth of 1author.name has a depth of 2array[_key="123"].title has a depth of 3Use caution when setting this value too high in studios with recursive document schemas
as it may cause performance and response quality issues.
Define fields or array items to exclude from the instruction. Any omitted fields or array items are implicitly included.
By default, all children up to the maxPathDepth are included.
Example:
["metadata", "draft", { "_key": "tempSection" }]
Path string
bodyConfigure which document types to include or exclude from the instruction.
Example:
{
"include": ["text", "image", "video"]
}
["text","image"]Path string
bodyDescribes the instructions for the included targets. References the top-level instructionParams using the $variable syntax.
Update the $title based on the $backgroundContext.
"set"Sets the default operation for all paths in the target.
Operation types:
set instead.imageUrl to describe remote images.Use include to override the default operation for specific paths.
Nested fields inherit the operation of their parent, and fall back
to the top level target operation unless otherwise specified.
"set", "append", "mixed"application/jsonThe schema identifier reported by sanity deploy or sanity schema store.
sanity.workspace.schema.defaultAllows the instruction to modify conditional readOnly or hidden fields. Does not apply to fields explicitly set as hidden or readOnly in the schema.
When false, forces all conditional readOnly fields to be writable.
trueWhen false, forces all conditional hidden fields to be writable.
Override the default behavior of individual conditional paths.
Defines the starting point, or root, of the area to affect.
To further control the behavior, use include, exclude, types.include, and types.exclude.
Examples:
"body" // Simple string path
{ "_key": "section1" } // Array item by key
Path string
bodyWhen false, the field is writable.
Set to true to mutate published documents. By default, Agent Actions will never mutate a published document. They will use a draftId if a publishedId is provided.
Operations on drafts receive initial state from the published document, if no draft exists. If a draft exists, it is used as the initial state.
The returned _id will be that of the modified document.
Documents set to liveEdit: true will be mutated as if forcePublishedWrite: true.
Controls the level of variance in the response. A higher value returns more variation in responses, while a lower value returns more predictable responses.
0.7When provided with locale settings, Generate will write to date and datetime fields.
Otherwise, those fields will be ignored.
{"locale":"en-US","timeZone":"America/New_York"}A valid unicode BCP 47 locale identifier. This will affect how natural language time and date phrases are parsed and presented.
en-USA valid IANA time zone identifier. This will ensure dates and times are interpreted correctly relative to the user's local time.
America/New_YorkWhen true, documents aren't created or mutated.
When true, requests occur in the background. True is incompatible with noWrite: true.
The ID of the source document to translate.
123The target document to transform and the operation to perform.
If omitted, the source document (documentId) will be used as the target.
A style guide for the translation.
Use a formal tone and avoid using contractions.Parameter values available to reference in the instruction.
There are four types of parameters:
constant: Set a static value. Ex: paramName: { type: 'constant', value: 'New title'}field: Target a field in the document to set the parameter to its value. Also takes an optional documentId to target a field in a different document. Ex: paramName: { type: 'field', path: 'poster'}groq: Set the parameter to the result of a GROQ query. Ex: paramName: { type: 'groq', query: '*[_type == $docType]', params: { 'docType': 'article'} }document: Set the parameter to the value of the entire document. If no documentID is provided, the current document is returned. Ex: paramName: { type: 'document', documentId: '123'}A list of phrases that should not be translated.
Use this instead of the style guide for phrases or words you want the translation to leave unchanged.
Set this to the path of the field where the language code is set in your document schema.
This will ensure the new document has the correct language code added after translation.
This has no affect on the translation process.
Path string
bodyTarget defines which parts of the document are affected by the instruction.
You can configure multiple parts of the document separately.
Omitting target will set the document as the root.
When multiple targets are provided, they will coalesce into a single target sharing a common root.
Example:
{
"path": "body",
"operation": "append",
"maxPathDepth": 3,
"include": {
"path": "sections",
"types": {
"include": ["text", "image"]
}
}
}
A list of paths that define the target area.
Each path in the list can be either a string or a key object.
Path string
bodyThe maximum depth of the document paths the instruction can write to.
Depth is based on field path segments:
title has a depth of 1author.name has a depth of 2array[_key="123"].title has a depth of 3Use caution when setting this value too high in studios with recursive document schemas
as it may cause performance and response quality issues.
Define fields or array items to exclude from the instruction. Any omitted fields or array items are implicitly included.
By default, all children up to the maxPathDepth are included.
Example:
["metadata", "draft", { "_key": "tempSection" }]
Path string
bodyConfigure which document types to include or exclude from the instruction.
Example:
{
"include": ["text", "image", "video"]
}
["text","image"]Path string
bodyDescribes the instructions for the included targets. References the top-level instructionParams using the $variable syntax.
Update the $title based on the $backgroundContext.
/prompt/{dataset}Prompt the LLM for a response. Does not interact with documents beyond fetching content as context when requested.
Use for tasks that don't require manipulating documents, such as generating details that you may want to use with other Agent Actions.
application/jsonDescribes the instruction. Reference instructionParams using the $variable syntax.
Create a new document with a title like $title, that matches the style of $externalTitle, and generate content based on the $backgroundContext.
Parameter values available to reference in the instruction.
There are four types of parameters:
constant: Set a static value. Ex: paramName: { type: 'constant', value: 'New title'}field: Target a field in the document to set the parameter to its value. Also takes an optional documentId to target a field in a different document. Ex: paramName: { type: 'field', path: 'poster'}groq: Set the parameter to the result of a GROQ query. Ex: paramName: { type: 'groq', query: '*[_type == $docType]', params: { 'docType': 'article'} }document: Set the parameter to the value of the entire document. If no documentID is provided, the current document is returned. Ex: paramName: { type: 'document', documentId: '123'}The temperature to use for the prompt. Controls how much variance there will be in responses.
0.5The format of the response. If json, the instruction must include the word "JSON" or "json".
OK
{"text":"Hello, world!"}text/plain/patch/{dataset}A schema-aware patch API that validates the provided paths and values against the target schema.
This operation does not use an LLM and will only use regular Sanity billing for API requests.
application/jsonThe schema identifier reported by sanity deploy or sanity schema store.
sanity.workspace.schema.defaultAllows the instruction to modify conditional readOnly or hidden fields. Does not apply to fields explicitly set as hidden or readOnly in the schema.
When false, forces all conditional readOnly fields to be writable.
trueWhen false, forces all conditional hidden fields to be writable.
Override the default behavior of individual conditional paths.
Defines the starting point, or root, of the area to affect.
To further control the behavior, use include, exclude, types.include, and types.exclude.
Examples:
"body" // Simple string path
{ "_key": "section1" } // Array item by key
Path string
bodyWhen false, the field is writable.
Determines how the target path will be patched.
'set': an overwriting operation: sets the full field value for primitive targets, and merges the provided value with existing values for objects'append':
'mixed': sets non-array fields, and appends to array fields'unset': removes whatever value is on the target pathAll operations except unset requires a value.
To append to an array, use 'append' the operation and provide an array value with one or more array items.
target: {path: ['array'], operation: 'append', value: [{_type: 'item' _key: 'a'}]} will append the items in the value to the existing array.
To insert in the middle of the array, use target: {path: ['array', {_key: 'appendAfterKey'}], operation: 'append', value: [{_type: 'item' _key: 'a'}]}.
Here, {_type: 'item' _key: 'a'} will be appended after the array item with key 'appendAfterKey'
It is optional to provide a _key for inserted array items; if non is not provided, it will be generated.
Defines the starting point, or root, of the area to affect.
To further control the behavior, use include, exclude, types.include, and types.exclude.
Examples:
"body" // Simple string path
{ "_key": "section1" } // Array item by key
Path string
bodyOK
{"text":"Hello, world!"}text/plain