Agent Actions

Reference documentation for the Agent Actions HTTP API.

The Agent Actions API gives you full access to Agent Actions through an HTTP endpoint instead of the Sanity client. We highly suggest using this only in situations where you cannot otherwise use the client.

Experimental feature

Agent Actions are experimental, and the API may change at any time. This API requires using vX for the API version.

Want to get started?

Agent Actions

Get started with Agent Actions

Authentication

All requests must be authenticated.

Base API server URL

Parameterized base URL

https://{projectId}.api.sanity.io/{apiVersion}/agent/action

Variables

  • projectIdstringdefault: "your-project-id"

    Sanity project ID

  • apiVersionstringdefault: "vX"

    API version

Endpoints

Send an instruction to Generate

post/generate/{dataset}

Sends an instruction request to Generate for a specific dataset.

Examples and implementation details can be found in the Generate documentation.

Path parameters

Request body application/json

  • schemaIdstringrequired

    The schema identifier reported by sanity deploy or sanity schema deploy.

    Example:_.schemas.default
  • conditionalPathsobject

    Allows the instruction to modify conditional readOnly or hidden fields. Does not apply to fields explicitly set as hidden or readOnly in the schema.

    Show child attributes
    • defaultReadOnlybooleandefault: true

      When false, forces all conditional readOnly fields to be writable.

    • defaultHiddenbooleandefault: true

      When false, forces all conditional hidden fields to be writable.

    • pathsarray

      Override the default behavior of individual conditional paths.

      Show child attributes
      items
      • patharrayrequired

        A list of path segments, from the document root down.

        Example
        ["body",{"_key":"someKey"},"title"]
        Show child attributes
        items
        • string

          Field name

          Example:body
      • readOnlybooleanrequired

        When false, the field is writable.

      • hiddenbooleanrequired

        When false, the field is writable.

  • forcePublishedWritebooleandefault: false

    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.

  • noWritebooleandefault: false

    When true, documents aren't created or mutated.

  • asyncbooleandefault: false

    When true, requests occur in the background. True is incompatible with noWrite: true.

  • temperaturenumber

    Controls the level of variance in the response. A higher value returns more variation in responses, while a lower value returns more predictable responses. Defaults to 0.3 for Generate, and 0 for Transform and Translate.

    Example:0.7
  • localeSettingsobject

    When provided with locale settings, Agent Actions write to date and datetime fields. Otherwise, those fields are ignored.

    Example
    {"locale":"en-US","timeZone":"America/New_York"}
    Show child attributes
    • localestringrequired

      A valid Unicode BCP 47 locale identifier. This will affect how natural language time and date phrases are parsed and presented.

      Example:en-US
    • timeZonestringrequired

      A valid IANA time zone identifier. This will ensure dates and times are interpreted correctly relative to the user's local time.

      Example:America/New_York
  • instructionstringrequired

    Describes the instruction. Reference instructionParams using the $variable syntax.

    Example:Create a new document with a title like $title, that matches the style of $externalTitle, and generate content based on the $backgroundContext.
  • instructionParamsobject

    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'}, or the shorthand paramName: '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. Prompt requests require documentId for field and document parameters. Ex: paramName: { type: 'document', documentId: '123'}
  • target

    Defines which parts of the document will be affected by the Generate instruction.

    Show child attributes
    • path

      A document path: either a single path segment, or an array of segments.

      Examples:

      "body"  // Field name
{ "_key": "section1" }  // Array item by key
["body", { "_key": "section1" }, "title"]  // Path array
      Show child attributes
      • string

        Field name

        Example:body
    • maxPathDepthintegerdefault: 4

      The maximum depth of the document paths the instruction can write to. When target is omitted, Transform and Translate use a depth of 12. Depth is based on field path segments:

      • title has a depth of 1
      • author.name has a depth of 2
      • array[_key="123"].title has a depth of 3

      Use caution when setting this value too high in studios with recursive document schemas as it may cause performance and response quality issues.

    • excludearray

      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" }]
      Show child attributes
      items
      • string

        Field name

        Example:body
    • types

      Configure which schema types to include or exclude from the instruction: array item types, or all fields of a type directly under the target path. include and exclude are mutually exclusive.

      Example:

      {
  "include": ["text", "image", "video"]
}
      Show child attributes
      • includearray
        Example
        ["text","image"]
        Show child attributes
        items
        • string
    • operationstringdefault: "mixed"

      Sets the default operation for all paths in the target.

      Operation types:

      • 'set': Overwrites and replaces the full field value.
      • 'append':
        • array fields: Appends new items to the end of the array.
        • string fields: Appends new content to the end of the string.
        • text fields: Appends new content to a new line after the existing content.
        • number fields: The sum of the new value and the existing value.
        • Other field types not mentioned will use set instead.
      • 'mixed': (Default) Sets non-array fields, and appends array fields.

      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.

    • includearray
      Show child attributes
      items
      • string

        Field name

        Example:body
  • documentIdstringrequired

    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.

Responses

200

Request was successful, returning the resulting document.

  • _idstringrequired

    The ID of the document.

    Example:123
  • _typestringrequired

    The type of the document.

    Example:article
  • _createdAtstring (date-time)required

    The creation date of the document.

    Example:2025-03-12T19:28:18Z
  • _updatedAtstring (date-time)required

    The last update date of the document.

    Example:2025-03-12T19:28:18Z
  • _revstring

    The revision number of the document.

    Example:rev123

Transform a document

post/transform/{dataset}

Transforms a source document. By default, the changes are written to the source document. To write them to a different document, set targetDocument.

Examples and implementation details can be found in the Transform documentation.

Path parameters

Request body application/json

  • schemaIdstringrequired

    The schema identifier reported by sanity deploy or sanity schema deploy.

    Example:_.schemas.default
  • conditionalPathsobject

    Allows the instruction to modify conditional readOnly or hidden fields. Does not apply to fields explicitly set as hidden or readOnly in the schema.

    Show child attributes
    • defaultReadOnlybooleandefault: true

      When false, forces all conditional readOnly fields to be writable.

    • defaultHiddenbooleandefault: true

      When false, forces all conditional hidden fields to be writable.

    • pathsarray

      Override the default behavior of individual conditional paths.

      Show child attributes
      items
      • patharrayrequired

        A list of path segments, from the document root down.

        Example
        ["body",{"_key":"someKey"},"title"]
        Show child attributes
        items
        • string

          Field name

          Example:body
      • readOnlybooleanrequired

        When false, the field is writable.

      • hiddenbooleanrequired

        When false, the field is writable.

  • forcePublishedWritebooleandefault: false

    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.

  • noWritebooleandefault: false

    When true, documents aren't created or mutated.

  • asyncbooleandefault: false

    When true, requests occur in the background. True is incompatible with noWrite: true.

  • temperaturenumber

    Controls the level of variance in the response. A higher value returns more variation in responses, while a lower value returns more predictable responses. Defaults to 0.3 for Generate, and 0 for Transform and Translate.

    Example:0.7
  • localeSettingsobject

    When provided with locale settings, Agent Actions write to date and datetime fields. Otherwise, those fields are ignored.

    Example
    {"locale":"en-US","timeZone":"America/New_York"}
    Show child attributes
    • localestringrequired

      A valid Unicode BCP 47 locale identifier. This will affect how natural language time and date phrases are parsed and presented.

      Example:en-US
    • timeZonestringrequired

      A valid IANA time zone identifier. This will ensure dates and times are interpreted correctly relative to the user's local time.

      Example:America/New_York
  • documentIdstringrequired

    The ID of the source document to transform.

    Example:123
  • targetDocument

    The target document to transform and the operation to perform. If omitted, the source document (documentId) will be used as the target.

    Show child attributes
    • _idstringrequired
    • operationstringrequired

      Directly edit the document with the given _id.

  • instructionstringrequired

    Describes the instruction. Reference instructionParams using the $variable syntax.

    Example:Create a new document with a title like $title, that matches the style of $externalTitle, and generate content based on the $backgroundContext.
  • instructionParamsobject

    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'}, or the shorthand paramName: '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. Prompt requests require documentId for field and document parameters. Ex: paramName: { type: 'document', documentId: '123'}
  • target

    Defines which parts of the document will be affected by the Transform instruction.

    Show child attributes
    • path

      A document path: either a single path segment, or an array of segments.

      Examples:

      "body"  // Field name
{ "_key": "section1" }  // Array item by key
["body", { "_key": "section1" }, "title"]  // Path array
      Show child attributes
      • string

        Field name

        Example:body
    • maxPathDepthintegerdefault: 4

      The maximum depth of the document paths the instruction can write to. When target is omitted, Transform and Translate use a depth of 12. Depth is based on field path segments:

      • title has a depth of 1
      • author.name has a depth of 2
      • array[_key="123"].title has a depth of 3

      Use caution when setting this value too high in studios with recursive document schemas as it may cause performance and response quality issues.

    • excludearray

      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" }]
      Show child attributes
      items
      • string

        Field name

        Example:body
    • types

      Configure which schema types to include or exclude from the instruction: array item types, or all fields of a type directly under the target path. include and exclude are mutually exclusive.

      Example:

      {
  "include": ["text", "image", "video"]
}
      Show child attributes
      • includearray
        Example
        ["text","image"]
        Show child attributes
        items
        • string
    • instructionstring

      Describes the instructions for the included targets. References the top-level instructionParams using the $variable syntax.

      Example:Update the $title based on the $backgroundContext.
    • includearray
      Show child attributes
      items
      • string

        Field name

        Example:body
    • operationdefault: "set"

      Sets the default operation for all paths in the target.

      Operation types:

      • 'set': (Default) Overwrites and replaces the full field value.
      • 'image-description': Lets the transform action select an image asset, select a field, and describe the image in the field. You can also set an 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.

      Show child attributes
      • string
        enum:"set"

Responses

200

Request was successful, returning the resulting document. When some paths failed or were skipped, the response includes the x-transform-* headers.

  • object

    A Sanity document shape.

Translate a document

post/translate/{dataset}

Translates a source document. By default, the translation is written to the source document. To write it to a different document, set targetDocument.

Examples and implementation details can be found in the Translate documentation.

Path parameters

Request body application/json

  • schemaIdstringrequired

    The schema identifier reported by sanity deploy or sanity schema deploy.

    Example:_.schemas.default
  • conditionalPathsobject

    Allows the instruction to modify conditional readOnly or hidden fields. Does not apply to fields explicitly set as hidden or readOnly in the schema.

    Show child attributes
    • defaultReadOnlybooleandefault: true

      When false, forces all conditional readOnly fields to be writable.

    • defaultHiddenbooleandefault: true

      When false, forces all conditional hidden fields to be writable.

    • pathsarray

      Override the default behavior of individual conditional paths.

      Show child attributes
      items
      • patharrayrequired

        A list of path segments, from the document root down.

        Example
        ["body",{"_key":"someKey"},"title"]
        Show child attributes
        items
        • string

          Field name

          Example:body
      • readOnlybooleanrequired

        When false, the field is writable.

      • hiddenbooleanrequired

        When false, the field is writable.

  • forcePublishedWritebooleandefault: false

    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.

  • noWritebooleandefault: false

    When true, documents aren't created or mutated.

  • asyncbooleandefault: false

    When true, requests occur in the background. True is incompatible with noWrite: true.

  • temperaturenumber

    Controls the level of variance in the response. A higher value returns more variation in responses, while a lower value returns more predictable responses. Defaults to 0.3 for Generate, and 0 for Transform and Translate.

    Example:0.7
  • localeSettingsobject

    When provided with locale settings, Agent Actions write to date and datetime fields. Otherwise, those fields are ignored.

    Example
    {"locale":"en-US","timeZone":"America/New_York"}
    Show child attributes
    • localestringrequired

      A valid Unicode BCP 47 locale identifier. This will affect how natural language time and date phrases are parsed and presented.

      Example:en-US
    • timeZonestringrequired

      A valid IANA time zone identifier. This will ensure dates and times are interpreted correctly relative to the user's local time.

      Example:America/New_York
  • documentIdstringrequired

    The ID of the source document to translate.

    Example:123
  • targetDocument

    The target document to transform and the operation to perform. If omitted, the source document (documentId) will be used as the target.

    Show child attributes
    • _idstringrequired
    • operationstringrequired

      Directly edit the document with the given _id.

  • fromLanguageobject
    Show child attributes
    • idstringrequired

      The language code.

      Example:en-US
    • titlestring

      The human-friendly name for the language.

      Example:English
  • toLanguageobjectrequired
    Show child attributes
    • idstringrequired

      The language code.

      Example:en-US
    • titlestring

      The human-friendly name for the language.

      Example:English
  • styleGuidestring

    A style guide for the translation.

    Example:Use a formal tone and avoid using contractions.
  • styleGuideParamsobject

    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'}, or the shorthand paramName: '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. Prompt requests require documentId for field and document parameters. Ex: paramName: { type: 'document', documentId: '123'}
  • protectedPhrasesarray

    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.

    Show child attributes
    items
    • string
  • languageFieldPath

    A document path: either a single path segment, or an array of segments.

    Examples:

    "body"  // Field name
{ "_key": "section1" }  // Array item by key
["body", { "_key": "section1" }, "title"]  // Path array
    Show child attributes
    • string

      Field name

      Example:body
  • target

    Target 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"]
      }
    }
  ]
}
    Show child attributes
    • path

      A document path: either a single path segment, or an array of segments.

      Examples:

      "body"  // Field name
{ "_key": "section1" }  // Array item by key
["body", { "_key": "section1" }, "title"]  // Path array
      Show child attributes
      • string

        Field name

        Example:body
    • maxPathDepthintegerdefault: 4

      The maximum depth of the document paths the instruction can write to. When target is omitted, Transform and Translate use a depth of 12. Depth is based on field path segments:

      • title has a depth of 1
      • author.name has a depth of 2
      • array[_key="123"].title has a depth of 3

      Use caution when setting this value too high in studios with recursive document schemas as it may cause performance and response quality issues.

    • excludearray

      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" }]
      Show child attributes
      items
      • string

        Field name

        Example:body
    • types

      Configure which schema types to include or exclude from the instruction: array item types, or all fields of a type directly under the target path. include and exclude are mutually exclusive.

      Example:

      {
  "include": ["text", "image", "video"]
}
      Show child attributes
      • includearray
        Example
        ["text","image"]
        Show child attributes
        items
        • string
    • styleGuidestring

      Describes the instructions for the included targets. References the top-level instructionParams using the $variable syntax.

      Example:Update the $title based on the $backgroundContext.
    • includearray
      Show child attributes
      items
      • string

        Field name

        Example:body

Responses

200

Request was successful, returning the resulting document. When some paths failed or were skipped, the response includes the x-transform-* headers.

  • object

    A Sanity document shape.

Prompt the LLM for a response

post/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.

Examples and implementation details can be found in the Prompt documentation.

Path parameters

Request body application/json

  • instructionstringrequired

    Describes the instruction. Reference instructionParams using the $variable syntax.

    Example:Create a new document with a title like $title, that matches the style of $externalTitle, and generate content based on the $backgroundContext.
  • instructionParamsobject

    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'}, or the shorthand paramName: '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. Prompt requests require documentId for field and document parameters. Ex: paramName: { type: 'document', documentId: '123'}
  • temperaturenumberdefault: 0.3

    The temperature to use for the prompt. Controls how much variance there will be in responses.

    Example:0.5
  • formatstringdefault: "string"

    The format of the response. If json, the instruction must include the word "json", in any letter case.

Responses

200

Request was successful. Returns text/plain when format is string, and the JSON the instruction asks for when format is json.

  • object
    Example
    {"text":"Hello, world!"}
Other content types: text/plain

Make a schema-aware patch to a document

post/patch/{dataset}

A schema-aware patch API that validates the provided paths and values against the target schema. This operation doesn't use an LLM and only uses regular Sanity billing for API requests. Unknown properties in the request body are rejected with a 400.

Examples and implementation details can be found in the Patch documentation.

Path parameters

Request body application/json

  • schemaIdstringrequired

    The schema identifier reported by sanity deploy or sanity schema deploy.

    Example:_.schemas.default
  • conditionalPathsobject

    Allows the instruction to modify conditional readOnly or hidden fields. Does not apply to fields explicitly set as hidden or readOnly in the schema.

    Show child attributes
    • defaultReadOnlybooleandefault: true

      When false, forces all conditional readOnly fields to be writable.

    • defaultHiddenbooleandefault: true

      When false, forces all conditional hidden fields to be writable.

    • pathsarray

      Override the default behavior of individual conditional paths.

      Show child attributes
      items
      • patharrayrequired

        A list of path segments, from the document root down.

        Example
        ["body",{"_key":"someKey"},"title"]
        Show child attributes
        items
        • string

          Field name

          Example:body
      • readOnlybooleanrequired

        When false, the field is writable.

      • hiddenbooleanrequired

        When false, the field is writable.

  • forcePublishedWritebooleandefault: false

    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.

  • noWritebooleandefault: false

    When true, documents aren't created or mutated.

  • asyncbooleandefault: false

    When true, requests occur in the background. True is incompatible with noWrite: true.

  • documentIdstring

    The ID of the document to patch. Either documentId or targetDocument is required. They're mutually exclusive.

  • targetDocument

    The operation to perform and the target document to transform.

    Show child attributes
  • targetrequired
    Show child attributes
    • operationstringrequired

      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':
        • array fields: appends new items to the end of the array,
        • string fields: '"existing content" "new content"'
        • text fields: '"existing content"\n"new content"'
        • number fields: existing + new
        • other field types not mentioned will set instead (dates, url)
      • 'mixed': sets non-array fields, and appends to array fields
      • 'unset': removes whatever value is on the target path

      All operations except unset require a value.

      Appending in the middle of arrays

      To append to an array, use the 'append' 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 one isn't provided, it will be generated.

    • path

      A document path: either a single path segment, or an array of segments.

      Examples:

      "body"  // Field name
{ "_key": "section1" }  // Array item by key
["body", { "_key": "section1" }, "title"]  // Path array
      Show child attributes
      • string

        Field name

        Example:body
    • value

      The value to write at path. Required for every operation except unset. Can't be null.

Responses

200

Request was successful, returning the resulting document.

  • _idstringrequired

    The ID of the document.

    Example:123
  • _typestringrequired

    The type of the document.

    Example:article
  • _createdAtstring (date-time)required

    The creation date of the document.

    Example:2025-03-12T19:28:18Z
  • _updatedAtstring (date-time)required

    The last update date of the document.

    Example:2025-03-12T19:28:18Z
  • _revstring

    The revision number of the document.

    Example:rev123
sanity.ioAll Systems Operational© Sanity 2026
Change site theme