POST
Create Text Conversation

Authorizations

Authorization
string
header
required

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

Body

application/json

A text thread with one contact, and what runs on it.

vars comes from AgentPlanRequest and is fixed for the life of the thread, exactly as the cast is: whatever turn 1 was started with is what turn 40 reads. POST /v1/conversations/messages takes none, and re-posting here replaces the bag whole.

contact_key
string
required
Required string length: 1 - 256
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.

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 put credentials in a workspace secret and read {{secrets.NAME}} from a tool instead.

Response

Successful Response

One conversation, and the contact it belongs to.

id identifies THIS conversation. contact_key identifies the caller or endpoint it is with, and is shared by every conversation with them - use it to list a contact's whole history (GET /v1/conversations?contact_key=…).

agent_id
string<uuid> | null
required
agent_name
string | null
required
contact_key
string | null
required
created_at
string<date-time>
required
id
string<uuid>
required
last_message_at
string<date-time> | null
required
last_message_text
string | null
required
metadata
Metadata · object
required
ref
ConversationRefSummary · object | null
required

The contact this conversation belongs to: key, binding, and what we know.

summary
string | null
required
surface
string | null
required
updated_at
string<date-time>
required
userdata
Userdata · object
required
vars
Vars · object
required