POST
Create Chat

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Who the chat is with, what it starts knowing, and what runs.

vars comes from AgentPlanRequest and secrets from SessionSecretsField; both are fixed for the life of the chat.

agent
AgentConfig · object | null

A complete agent definition, run for this call and stored nowhere. Mutually exclusive with agent_id.

agent_id
string<uuid> | null

An agent in this workspace. Mutually exclusive with agent.

agent_override
AgentOverride · object | null

Changes layered on top of whichever base was named. Absent keys keep the base value, an explicit null clears the field, objects deep-merge and lists replace.

agent_team
AgentTeam · object | null

Run several agents on this call, defined here. Mutually exclusive with agent_id / agent / agent_version / agent_override.

agent_version

Which version of agent_id to run. Omit for the published one. "draft" runs the unpublished working copy — validated and tool-pinned at request time, and refused with the publish errors if it does not hold together.

contact_key
string | null
Required string length: 1 - 256
secrets
Secrets · object | null

Secrets for this session only, read by tools as {{secrets.NAME}}; a name here overrides the workspace secret. Never shown to the model or returned.

userdata
Userdata · object | null
vars
Vars · object | null

Values for the variables the agents on this session declare, read as {{vars.name}} in a prompt, a greeting and a tool. They override each agent's declared default and reach every agent the session runs, including a handoff target. Unlike userdata, which describes the PERSON and is kept on their contact record, these describe THIS session and are gone with it. Strings only; an empty string is a deliberate blank, not a request for the default. The model can see them, so credentials go in secrets (this session's own, where the request takes them) or a workspace secret, read as {{secrets.NAME}} by a tool.

Response

Successful Response

One chat: a text session from its first message to its end.

agent
AgentMetadata · object
required
analysis
AnalysisResponse · object | null
required

The analysis of one call, as every reader sees it.

Shared verbatim by the calls API and the session.completed webhook so an integration that reads one can read the other.

close_reason
string | null
required
contact_key
string | null
required
conversation_id
string<uuid> | null
required
cost
CostResponse · object | null
required
created_at
string<date-time>
required
ended_at
string<date-time> | null
required
id
string<uuid>
required
metadata
Metadata · object
required

Your own labels for this session, set by your inbound webhook.

started_at
string<date-time> | null
required
status
enum<string>
required
Available options:
open,
ended
userdata
Userdata · object
required