Skip to main content
POST
Get or create a v2 conversation

Authorizations

x-api-key
string
header
required

Body

application/json

Get-or-create a v2 conversation (Phase F2) — CHAT ONLY (D4/ADR-007).

The generic create route creates chat conversations only: sms / voice / email creation stays adapter-owned (/v1/sms/send, voice dispatch, the email pipeline). channel is therefore not a request field (forced server-side), and origin / channel_subtype are gone — both are server-assigned (ADR-005 / ADR-004).

Bind to exactly one of a single Assistant (assistant_id) or a Team (team_id + team_revision_id) — the single_xor_team CHECK on conversations. assistant_revision_id is optional; when omitted it is resolved from the agent's active revision and pinned at bind time.

end_user_id
string<uuid> | null
org_external_end_user_id
string | null
Required string length: 1 - 255
assistant_id
string<uuid> | null
assistant_revision_id
string<uuid> | null
team_id
string<uuid> | null
team_revision_id
string<uuid> | null
session_type
enum<string>
default:live
Available options:
live,
test,
simulation
external_id
string | null
subject
string | null
metadata
Metadata · object | null
tool_input_overrides
Tool Input Overrides · object | null
context_variables
Context Variables · object | null
test_features
TestSessionFeatureInput · object | null

Caller-supplied toggles. Unknown fields are rejected.

Response

Successful Response

id
string<uuid>
required
organization_id
string<uuid>
required
end_user_id
string<uuid>
required
channel
string
required
surface
string
required
status
string
required
session_type
string
required
created_at
string<date-time>
required
updated_at
string<date-time>
required
assistant_id
string<uuid> | null
assistant_revision_id
string<uuid> | null
team_id
string<uuid> | null
team_revision_id
string<uuid> | null
external_id
string | null
subject
string | null
tool_input_overrides
Tool Input Overrides · object | null
test_features
TestSessionFeatures · object | null

Resolved, immutable snapshot persisted on a test conversation.