API reference › Resources
Conversations
Talk to agents with streaming, continue conversations, read the history and cancel runs.
A conversation (task) holds the messages exchanged with an agent. Each new message produces a streamed answer, and the history stays on the server: to continue, you send only the new message and the conversation ID. Conversations show up on the app's Tasks page.
POST/api/agents/{id}/chat#
Sends a message to the agent and returns the answer as NDJSON. You only need to be able to see the agent.
| Field | Type | Description |
|---|---|---|
message | string, 1 to 100,000 | Required. The message. |
taskId | string | Continues an existing conversation with the same agent. Without it, a new conversation is created. |
curl -N https://doublex.ai/api/agents/agt_8f3a2b1c9d0e/chat \
-H "Authorization: Bearer $DOUBLEX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"message": "What did our competitors launch this week?"}'{"type":"task","taskId":"task_5d2c9a3e1f07"}
{"type":"tool_start","id":"toolu_01","name":"pesquisar_web","label":"Searching the web"}
{"type":"tool_end","id":"toolu_01","ok":true}
{"type":"text","delta":"I found 3 launches. "}
{"type":"text","delta":"The most relevant one is…"}
{"type":"done","status":"completed"}Streaming events#
type | Fields | When |
|---|---|---|
task | taskId | First event: the ID of the conversation that was created or continued. Save it. |
text | delta | A chunk of the answer text. Join the delta values in order. |
thinking | delta | A chunk of the model's reasoning, when the model exposes it. |
tool_start | id, name, label | The agent started using a tool. label is a human-readable name. |
tool_end | id, ok | The tool finished. ok: false if it failed. |
notice | message | A notice that doesn't interrupt: a connector that needs to be reconnected, a fallback model was used, the conversation was cancelled. |
error | message | A failure that interrupts the answer. |
done | status | Last event: completed or failed. |
Always detect the end through the done event. Some problems show up only in the stream, with HTTP status 200, even before the task event: credits ran out, the model has no key configured, or the conversation is still answering the previous message. In these cases you get error followed by done with failed.
{"type":"error","message":"Your organization is out of credits."}
{"type":"done","status":"failed"}Continue a conversation#
curl -N https://doublex.ai/api/agents/agt_8f3a2b1c9d0e/chat \
-H "Authorization: Bearer $DOUBLEX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"message": "Build a table comparing them with our products", "taskId": "task_5d2c9a3e1f07"}'A conversation answers one message at a time. To work in parallel, open separate conversations.
If the connection drops#
Closing the connection does not stop the agent: it finishes the work on the server and saves the answer in the conversation. To get the result, use GET /api/tasks/{id}. To actually stop it, use cancel.
GET/api/tasks#
Lists the conversations you can see, newest first, without the messages.
| Query | Description |
|---|---|
agentId | Only one agent's conversations. |
status | processing, completed or failed. |
source | Source: chat, trigger, webhook or subagent. |
curl "https://doublex.ai/api/tasks?agentId=agt_8f3a2b1c9d0e&status=failed" -H "Authorization: Bearer $DOUBLEX_API_KEY"{
"tasks": [
{
"id": "task_5d2c9a3e1f07",
"agentId": "agt_8f3a2b1c9d0e",
"agentName": "CRM Analyst",
"title": "Competitor launches",
"source": "chat",
"status": "completed",
"unread": false,
"usage": { "inputTokens": 18234, "outputTokens": 912, "cacheReadTokens": 12000, "costUsd": 0.041 },
"createdAt": "2026-10-27T13:01:12.000Z",
"updatedAt": "2026-10-27T13:01:58.000Z"
}
]
}Failed conversations include error and, when applicable, errorCode: cancelled (stopped) or refused (the model refused). Conversations created by a trigger include triggerId.
GET/api/tasks/{id}#
Returns the conversation, its messages and whether the agent is still working.
{
"task": { "id": "task_5d2c9a3e1f07", "status": "completed", "...": "..." },
"items": [
{ "kind": "user", "text": "What did our competitors launch this week?" },
{ "kind": "tool", "id": "toolu_01", "name": "pesquisar_web", "ok": true },
{ "kind": "assistant", "text": "I found 3 launches…" }
],
"running": false
}items[].kind can be user, assistant, thinking or tool. To wait for a conversation to finish without streaming, poll this route until running is false.
PATCH/api/tasks/{id}#
Renames the conversation or changes its unread flag.
| Field | Type |
|---|---|
title | string, 1 to 120 |
unread | boolean |
Response: { "ok": true }.
POST/api/tasks/{id}/cancel#
Stops the agent. The conversation ends as failed, with errorCode: "cancelled". Whatever was already processed is charged.
curl -X POST https://doublex.ai/api/tasks/task_5d2c9a3e1f07/cancel -H "Authorization: Bearer $DOUBLEX_API_KEY"Response: { "cancelled": true }. Error 409 if the conversation isn't running.
DELETE/api/tasks/{id}#
Deletes the conversation and its history. Response: { "ok": true }.