Conversations

Talk to a Conversational agent: open conversations, post and stream messages, and work with the files and data frames a conversation produces. To create or configure the agent itself, see Agents.

All paths are relative to the base URL and require an Authorization: Bearer YOUR_API_KEY header. {aid} is the agent ID and {cid} is the conversation ID.

List conversations

GET /agents/{aid}/conversations

Returns a PaginatedResponse of Conversation objects.

Create conversation

POST /agents/{aid}/conversations

Body

curl -X POST 'https://{your-deployment-host}/tenants/{tenant-id}/api/v2/agents/{aid}/conversations' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "Q3 reconciliation" }'

Returns the created Conversation.

Delete conversation

DELETE /agents/{aid}/conversations/{cid}

Deletes a conversation and returns the deleted Conversation.

Messages

Get messages

GET /agents/{aid}/conversations/{cid}/messages

Returns the conversation's messages as a PaginatedResponse.

Post a message (synchronous)

POST /agents/{aid}/conversations/{cid}/messages

Posts a user message and waits for the agent to respond, returning the updated conversation state. Use streaming for incremental output.

Body

curl -X POST 'https://{your-deployment-host}/tenants/{tenant-id}/api/v2/agents/{aid}/conversations/{cid}/messages' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "content": "Summarize the attached invoice." }'

Stream a message

POST /agents/{aid}/conversations/{cid}/stream

Posts a message and streams the response as Server-Sent Events, each event carrying an incremental delta. Set Accept: text/event-stream.

Body — same as the synchronous endpoint (content).

curl -N -X POST 'https://{your-deployment-host}/tenants/{tenant-id}/api/v2/agents/{aid}/conversations/{cid}/stream' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Accept: text/event-stream' \
  -d '{ "content": "Walk me through the reconciliation." }'

Concatenate the data: event deltas to assemble the full reply.

Files

A conversation has its own file space — inputs you upload and outputs the agent produces. See Files.

List files

GET /agents/{aid}/conversations/{cid}/files

Upload files

POST /agents/{aid}/conversations/{cid}/files

Send as multipart/form-data with a repeated files field.

curl -X POST 'https://{your-deployment-host}/tenants/{tenant-id}/api/v2/agents/{aid}/conversations/{cid}/files' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'files=@invoice.pdf' \
  -F 'files=@receipt.png'

Download a file

GET /agents/{aid}/conversations/{cid}/files/download/

Returns the file bytes.

Data frames

Tabular data the agent produced in a conversation. See Data frames.

List data frames

GET /agents/{aid}/conversations/{cid}/data-frames

Get a data frame

GET /agents/{aid}/conversations/{cid}/data-frames/{data_frame_name}

Returns a data frame's contents, with optional slicing, column selection, and ordering.