Conversations API

Interact with your AI agent, manage session state, and control user variables. Every endpoint requires a valid API key passed as Authorization: Bearer cdt_xxx.

Endpoints

POST

/api/v1/conversations/:userId/interact

Send a message and get a response (non-streaming)

POST

/api/v1/conversations/:userId/interact/stream

Send a message and receive response as SSE stream

GET

/api/v1/conversations/:userId/state

Get the current session state for a user

PUT

/api/v1/conversations/:userId/state

Replace the entire session state

PATCH

/api/v1/conversations/:userId/variables

Merge variables into the current state

DELETE

/api/v1/conversations/:userId/state

Delete the session state (reset conversation)

Interact

Send a user action (text message, button click, media) and receive the agent's response traces.

Request

POST /api/v1/conversations/user_123/interact
Authorization: Bearer cdt_abc123...
Content-Type: application/json

{
  "action": {
    "type": "text",
    "payload": "I need help with my account"
  },
  "versionId": "development"
}

Response

[
  {
    "type": "text",
    "payload": {
      "message": "Of course! I'd be happy to help with your account. What specific issue are you experiencing?"
    }
  }
]

Action Types

Type	Payload	Description
text	string	Text message from user
launch	null	Start or resume conversation
button	{ label, value }	Button click
media	{ url, mimeType }	Media attachment

Stream

Same as interact, but returns traces as Server-Sent Events for real-time streaming. The stream ends with a [DONE] event.

Request

POST /api/v1/conversations/user_123/interact/stream
Authorization: Bearer cdt_abc123...
Content-Type: application/json

{
  "action": { "type": "text", "payload": "Hello" }
}

SSE Response

data: {"type":"text","payload":{"message":"Hi there! "}}

data: {"type":"text","payload":{"message":"How can I help?"}}

data: [DONE]

State Management

Read, replace, patch, or delete the session state for a user. Session state includes variables, conversation history, and internal agent state.

Get state

GET /api/v1/conversations/user_123/state
Authorization: Bearer cdt_abc123...

Patch variables

PATCH /api/v1/conversations/user_123/variables
Authorization: Bearer cdt_abc123...
Content-Type: application/json

{
  "customer_name": "Jane Smith",
  "plan_tier": "premium"
}

Delete state (reset)

DELETE /api/v1/conversations/user_123/state
Authorization: Bearer cdt_abc123...

Parameters

Parameter	Type	Required	Description
userId	string	Yes (path)	Unique identifier for the end user
action	Action	Yes (body)	User action object with type and payload
versionId	string	No (body)	Target version — defaults to "development"