Skip to main content
Create conversation

Authorizations

Authorization
string
header
required

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

Path Parameters

app_id
string
required

The unique identifier of the app.

Body

application/json
external_user_id
string | null

Your application's unique identifier for the user. When provided, conversations are linked to this user for retrieval via the list user conversations endpoint.

title
string | null

A custom title for the conversation. If not provided, the system will auto-generate a title after the first exchange.

metadata
Metadata · object | null

Arbitrary key-value context to enrich the AI agent's responses for this conversation. Injected into the agent's runtime context on every response. Can be updated by passing metadata on subsequent message requests. Maximum 16KB.

Response

OK

id
string
required

Unique identifier for the conversation.

created_at
integer
required

Unix timestamp (in seconds) of when the conversation was created.

object
string
default:conversation

The object type. Always 'conversation'.

external_user_id
string | null

The external user identifier associated with this conversation, if one was provided at creation.

title
string | null

The custom title set for this conversation, if any.

generated_title
Generated Title · object | null

AI-generated conversation title in supported locales. Keys are locale codes (e.g. 'en-ca', 'fr-ca').

Example:
metadata
Metadata · object | null

The latest metadata snapshot associated with this conversation, if any has been provided.