HTTP API Reference

Content Agent API reference

HTTP reference documentation for the Content Agent API

The Content Agent API allows you to integrate Content Agent into your own applications via HTTP. It uses Server-Sent Events (SSE) for streaming responses, fully compatible with the Vercel AI SDK.

Base API server URL

Production API (preview)

https://api.sanity.io/vX/agent

Chat

Conversational endpoints with thread management

Send a chat message

post/{organizationId}/threads/{threadId}

Send a message to the agent and receive a streaming response. This endpoint manages conversation threads and persists message history.

Path parameters

  • organizationIdstringrequired

    Your Sanity organization ID

    Example:abc123
  • threadIdstringrequired

    Unique identifier for the conversation thread

    Example:my-conversation-thread

Request body application/json

  • messagesarrayrequired

    Array of message objects

    Show child attributes
    items
    • rolestringrequired

      The role of the message sender

    • contentstringrequired

      The message content

    • idstring

      Optional unique identifier for the message

    • namestring

      Optional name for the message sender

  • applicationobject

    Target Sanity application configuration

    Show child attributes
    • keystring

      Application key in format "projectId.datasetName"

      Example:abc123.production
    • resourceobject
      Show child attributes
      • idstring

        Resource ID in format "projectId.datasetName"

        Example:abc123.production
      • typestring

        Resource type

    • intentBaseUrlstring (uri)

      Base URL for the Sanity Studio

      Example:https://your-studio.sanity.studio
    • bundleVersionstring

      Bundle version

    • namestring

      Application name

    • titlestring

      Application title

    • schemaDescriptorIdstring

      Schema descriptor ID

  • configobject

    Agent configuration. Controls behavior, capabilities, and document access.

    Show child attributes
    • instructionstring

      Custom instruction string to include in the system prompt

      Example:You are a helpful content assistant.
    • userMessageContextobject

      Key-value pairs appended to each user message as XML tags. Each key becomes an XML tag with the value as content. Example: { "slack-channel": "#marketing" } renders as #marketing

      Example
      {"slack-channel":"#marketing","user-role":"editor"}
    • capabilitiesobject

      Agent capabilities that control what operations are allowed. Each capability can be a boolean or an object with a preset.

      Example
      {"read":true,"write":false}
      Show child attributes
      • read

        A capability can be:

        • true: Full access (standard preset)
        • false: No access
        • { preset: 'minimal' | 'standard' }: Explicit preset selection
        Show child attributes
        • boolean

          true = standard preset, false = disabled

      • write

        A capability can be:

        • true: Full access (standard preset)
        • false: No access
        • { preset: 'minimal' | 'standard' }: Explicit preset selection
        Show child attributes
        • boolean

          true = standard preset, false = disabled

      • featuresobject

        Explicit feature overrides applied on top of capability-derived defaults. When not specified, features use values derived from read/write capability presets.

        Show child attributes
        • webSearchboolean

          Override web search availability. By default, web search is enabled when read capability is 'standard'.

    • filterobject

      GROQ filter expressions for document access control

      Show child attributes
      • readstring

        GROQ boolean expression for document visibility. Documents matching this filter are visible to the agent.

        Example:_type in ['post', 'author']
      • writestring

        GROQ boolean expression for mutation permissions. Documents matching this filter can be mutated.

        Example:_type == 'post'
    • perspectivesobject

      Perspective locking configuration. Controls which document perspectives the agent can read from and write to. Values are Sanity perspective IDs: 'drafts', 'published', 'raw', or release/bundle IDs.

      Show child attributes
      • readarray

        Allowed read perspectives. When set, query tools can only use these perspectives. If the agent tries to use a disallowed perspective, the request is rejected with an error.

        Example
        ["drafts","published"]
        Show child attributes
        items
        • string
      • writestring

        The write perspective. When set, new documents are created in this perspective and mutations are restricted to documents whose ID matches it.

        Example:drafts
  • streambooleandefault: true

    Enable or disable streaming responses

  • formatstringdefault: "markdown"

    Controls how directives in the response are formatted.

    • markdown (default): Directives are resolved server-side into standard markdown (e.g., links with titles).
    • directives: Raw directive syntax is preserved (e.g., ::document{id="doc-id"}), useful for clients that render custom UI components.
Examplesapplication/json
Basic chat request
{
  "messages": [
    {
      "role": "user",
      "content": "What blog posts do I have?"
    }
  ]
}

Responses

200

Streaming response

  • string

    Server-Sent Events stream following Vercel AI Data Stream Protocol

Other content types: application/json

Prompt

Stateless prompt endpoints

Send a one-shot prompt

post/prompt

Stateless one-shot prompt endpoint. No thread management or message persistence. Ideal for simple, single-turn interactions.

Request body application/json

  • organizationIdstringrequired

    Your Sanity organization ID

    Example:abc123
  • messagestringrequired

    The prompt message

    Example:Summarize my latest blog posts
  • configobject

    Agent configuration. Controls behavior, capabilities, and document access.

    Show child attributes
    • instructionstring

      Custom instruction string to include in the system prompt

      Example:You are a helpful content assistant.
    • userMessageContextobject

      Key-value pairs appended to each user message as XML tags. Each key becomes an XML tag with the value as content. Example: { "slack-channel": "#marketing" } renders as #marketing

      Example
      {"slack-channel":"#marketing","user-role":"editor"}
    • capabilitiesobject

      Agent capabilities that control what operations are allowed. Each capability can be a boolean or an object with a preset.

      Example
      {"read":true,"write":false}
      Show child attributes
      • read

        A capability can be:

        • true: Full access (standard preset)
        • false: No access
        • { preset: 'minimal' | 'standard' }: Explicit preset selection
        Show child attributes
        • boolean

          true = standard preset, false = disabled

      • write

        A capability can be:

        • true: Full access (standard preset)
        • false: No access
        • { preset: 'minimal' | 'standard' }: Explicit preset selection
        Show child attributes
        • boolean

          true = standard preset, false = disabled

      • featuresobject

        Explicit feature overrides applied on top of capability-derived defaults. When not specified, features use values derived from read/write capability presets.

        Show child attributes
        • webSearchboolean

          Override web search availability. By default, web search is enabled when read capability is 'standard'.

    • filterobject

      GROQ filter expressions for document access control

      Show child attributes
      • readstring

        GROQ boolean expression for document visibility. Documents matching this filter are visible to the agent.

        Example:_type in ['post', 'author']
      • writestring

        GROQ boolean expression for mutation permissions. Documents matching this filter can be mutated.

        Example:_type == 'post'
    • perspectivesobject

      Perspective locking configuration. Controls which document perspectives the agent can read from and write to. Values are Sanity perspective IDs: 'drafts', 'published', 'raw', or release/bundle IDs.

      Show child attributes
      • readarray

        Allowed read perspectives. When set, query tools can only use these perspectives. If the agent tries to use a disallowed perspective, the request is rejected with an error.

        Example
        ["drafts","published"]
        Show child attributes
        items
        • string
      • writestring

        The write perspective. When set, new documents are created in this perspective and mutations are restricted to documents whose ID matches it.

        Example:drafts
  • instructionsstring

    Custom instructions for the agent

    Example:Be concise and use bullet points
  • formatstringdefault: "markdown"

    Controls how directives in the response are formatted.

    • markdown (default): Directives are resolved server-side into standard markdown.
    • directives: Raw directive syntax is preserved for clients that render custom UI.
Examplesapplication/json
Basic prompt request
{
  "organizationId": "abc123",
  "message": "Summarize my latest blog posts",
  "config": {
    "capabilities": {
      "read": true,
      "write": false
    }
  }
}

Responses

200

Streaming response

  • string

    Server-Sent Events stream following Vercel AI Data Stream Protocol