DoubleX AgentesDocs

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.

FieldTypeDescription
messagestring, 1 to 100,000Required. The message.
taskIdstringContinues 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?"}'
NDJSON
{"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#

typeFieldsWhen
tasktaskIdFirst event: the ID of the conversation that was created or continued. Save it.
textdeltaA chunk of the answer text. Join the delta values in order.
thinkingdeltaA chunk of the model's reasoning, when the model exposes it.
tool_startid, name, labelThe agent started using a tool. label is a human-readable name.
tool_endid, okThe tool finished. ok: false if it failed.
noticemessageA notice that doesn't interrupt: a connector that needs to be reconnected, a fallback model was used, the conversation was cancelled.
errormessageA failure that interrupts the answer.
donestatusLast 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.

NDJSON
{"type":"error","message":"Your organization is out of credits."}
{"type":"done","status":"failed"}

Continue a conversation#

Terminal
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.

QueryDescription
agentIdOnly one agent's conversations.
statusprocessing, completed or failed.
sourceSource: chat, trigger, webhook or subagent.
curl "https://doublex.ai/api/tasks?agentId=agt_8f3a2b1c9d0e&status=failed" -H "Authorization: Bearer $DOUBLEX_API_KEY"
JSON
{
  "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.

JSON
{
  "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.

FieldType
titlestring, 1 to 120
unreadboolean

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 }.