HTTP API Reference

Agent Actions

Reference documentation for the Agent Actions HTTP API.

The Agent Actions API allows 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 store.

    Example:sanity.workspace.schema.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
      • path

        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
        Show child attributes
        • string

          Path string

          Example:body
      • readOnlybooleandefault: true

        When false, the field is writable.

      • hiddenbooleandefault: true

        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.

  • temperaturenumberdefault: 0.3

    Controls the level of variance in the response. A higher value returns more variation in responses, while a lower value returns more predictable responses.

    Example:0.7
  • localeSettingsobject

    When provided with locale settings, Generate will write to date and datetime fields. Otherwise, those fields will be ignored.

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

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

      Example:en-US
    • timeZonestring

      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
  • 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.

  • 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'}
    • 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'}
  • target

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

    Show child attributes
    • path

      A list of paths that define the target area. Each path in the list can be either a string or a key object.

      Show child attributes
        items
        • string

          Path string

          Example:body
    • maxPathDepthnumberdefault: 4

      The maximum depth of the document paths the instruction can write to. 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

        Path string

        Example:body
    • types

      Configure which document types to include or exclude from the instruction.

      Example:

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

        Path string

        Example:body
    • operationstringdefault: "set"

      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 fields types not mentioned will use set instead.
      • 'mixed': 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.

  • 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 modified document shape.

  • _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
  • additionalProperties

    Additional properties of the document depend on the document schema.

    Show child attributes
    • object

Transform a document

post/transform/{dataset}

Transforms a source document into a new document.

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 store.

    Example:sanity.workspace.schema.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
      • path

        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
        Show child attributes
        • string

          Path string

          Example:body
      • readOnlybooleandefault: true

        When false, the field is writable.

      • hiddenbooleandefault: true

        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.

  • temperaturenumberdefault: 0.3

    Controls the level of variance in the response. A higher value returns more variation in responses, while a lower value returns more predictable responses.

    Example:0.7
  • localeSettingsobject

    When provided with locale settings, Generate will write to date and datetime fields. Otherwise, those fields will be ignored.

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

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

      Example:en-US
    • timeZonestring

      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
  • 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.

  • 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.

  • instructionstring

    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'}
    • 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'}
  • target

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

    Show child attributes
    • path

      A list of paths that define the target area. Each path in the list can be either a string or a key object.

      Show child attributes
        items
        • string

          Path string

          Example:body
    • maxPathDepthnumberdefault: 4

      The maximum depth of the document paths the instruction can write to. 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

        Path string

        Example:body
    • types

      Configure which document types to include or exclude from the instruction.

      Example:

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

        Path string

        Example:body
    • 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.
    • operationdefault: "set"

      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 fields types not mentioned will use set instead.
      • 'mixed': Sets non-array fields, and appends array fields.
      • '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", "append", "mixed"

Responses

Translate a document

post/translate/{dataset}

Translates a source document into a new document.

Path parameters

Request body application/json

  • schemaIdstringrequired

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

    Example:sanity.workspace.schema.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
      • path

        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
        Show child attributes
        • string

          Path string

          Example:body
      • readOnlybooleandefault: true

        When false, the field is writable.

      • hiddenbooleandefault: true

        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.

  • temperaturenumberdefault: 0.3

    Controls the level of variance in the response. A higher value returns more variation in responses, while a lower value returns more predictable responses.

    Example:0.7
  • localeSettingsobject

    When provided with locale settings, Generate will write to date and datetime fields. Otherwise, those fields will be ignored.

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

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

      Example:en-US
    • timeZonestring

      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
  • 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.

  • 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'}
    • 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'}
  • 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

    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.

    Show child attributes
    • string

      Path string

      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 list of paths that define the target area. Each path in the list can be either a string or a key object.

      Show child attributes
        items
        • string

          Path string

          Example:body
    • maxPathDepthnumberdefault: 4

      The maximum depth of the document paths the instruction can write to. 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

        Path string

        Example:body
    • types

      Configure which document types to include or exclude from the instruction.

      Example:

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

        Path string

        Example:body
    • 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.

Responses

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.

Path parameters

Request body application/json

  • instructionstring

    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'}
    • 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'}
  • temperaturenumberdefault: 0.3

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

    Example:0.5
  • formatstringdefault: "text"

    The format of the response. If json, the instruction must include the word "JSON" or "json".

Responses

200

OK

  • 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 does not use an LLM and will only use regular Sanity billing for API requests.

Path parameters

Request body application/json

  • schemaIdstring

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

    Example:sanity.workspace.schema.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
      • path

        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
        Show child attributes
        • string

          Path string

          Example:body
      • readOnlybooleandefault: true

        When false, the field is writable.

      • hiddenbooleandefault: true

        When false, the field is writable.

  • target
    Show child attributes
    • operationstringdefault: "set"

      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 requires a value.

      Appending in the middle of arrays

      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.

    • path

      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
      Show child attributes
      • string

        Path string

        Example:body

Responses

200

OK

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