Skip to main content
POST
/
v1
/
chat
Error
A valid request URL is required to generate request examples
"<string>"
{
  "error": "<string>",
  "details": "<string>"
}
{
  "error": "<string>",
  "details": "<string>"
}
{
  "error": "<string>",
  "message": "<string>",
  "details": {
    "currentUsage": 123,
    "limit": 123,
    "groupLimitRemaining": 123
  }
}
{
  "error": "<string>",
  "details": "<string>"
}

Authorizations

​
Authorization
string
header
required

Org API key (scopes the request to its organization) or the shared trusted key (requires X-Organization-Id on every request).

Headers

​
X-Organization-Id
string

Organization to scope the request to. Optional when authenticating with an org API key (the org is taken from the key; if sent, it must match). Required when authenticating with the trusted key.

​
X-User-Id
string

End-user identity for the request; user-scoped data (threads, memory) resolves to {orgId}_{userId}. Required by endpoints that read or write user-scoped resources. A userId query param (or body field, where documented) is accepted as a fallback.

Body

application/json
​
messages
array
required
Minimum array length: 1
​
agentId
string

Stable agents.id — runs the agent's ACTIVE published version

​
agentVersionId
string

Override: run this EXACT agent_versions.id (e.g. preview a draft or a non-active published version) instead of the active one

​
copilotId
string

Copilot id to route through (alternative to agentId)

​
threadId
string

Conversation thread id

​
groupId
string | null

Optional STABLE caller-supplied chatter group id (chatter_groups.external_id). When sent, group matching is by this id; a differing groupName renames the group.

Required string length: 1 - 255
​
groupName
string | null

Optional chatter group name. Without groupId this matches/provisions by name (legacy behavior); alongside groupId it is display-only (rename on change).

​
runtimeAuth
object

Runtime authentication map: { [providerNameOrId]: { credentials } }

​
context
string[]

Additional context messages to provide to the agent.

​
trigger
enum<string>

AI SDK trigger type

Available options:
submit-message,
regenerate-message
​
tools
object

AI SDK client-side tools

​
metadata
object

AI SDK session metadata

​
use_routing
boolean
default:true

Default true. When the request lands on an orchestrator (copilot routing agent that was not optimized to a subagent), a pre-stream Handoff Agent picks whether to stream the orchestrator (multi-step / synthesis) or a single subagent directly (domain-specific ask). No-op when the resolved agent is not an orchestrator flow. Pass false to disable.

Response

AI SDK v6 UIMessageStream response

The response is of type string.