Conversations

Talk to an agent from your server, for one of your users. Every call below needs your secret key and the Digitorn-User header: a conversation always belongs to a user.

The agents you can use

bash

curl https://api.digitorn.ai/v1/agents -H "Authorization: Bearer sk_..."

json

{ "data": [ { "id": "my-shop-42be", "name": "Kora", "description": "…", "kind": "chat" } ], "next_cursor": null }

• GET /v1/agents/{id}: one agent.
• GET /v1/agents/lookup?name=Kora: by name, ignoring case and accents. Several agents with that name answer 409 agent_ambiguous with their ids.

Open a conversation and get the answer

bash

curl https://api.digitorn.ai/v1/conversations \
  -H "Authorization: Bearer sk_..." \
  -H "Digitorn-User: user_482" \
  -H "Content-Type: application/json" \
  -d '{"agent":"my-shop-42be","message":"Do you have rice?","wait":60}'

json

{
  "id": "34428ad3-7050-42e5-a939-dd5a7dfc933d",
  "agent": "my-shop-42be",
  "status": "completed",
  "reply": "Yes! 25 kg bags at 18 000 FCFA…",
  "replies": [ { "id": "212", "role": "assistant", "content": "Yes! 25 kg bags…" } ],
  "pending_approvals": []
}

Field
agent	Required: an id from GET /v1/agents.
message	The first message (optional).
wait	0 to 100 seconds to wait for the answer. 0 returns at once with status: "running".
title	Optional, up to 200 characters.
context	Optional object (up to 16 KB) the agent knows about the moment: page, cart, order…

status is completed (the agent answered), running (still working when wait ended: read the messages later), or waiting_approval (the agent waits for a decision, see below).

If the first message is refused (for example the user's plan is used up), the conversation is still created and message_error says why.

Continue it

bash

curl https://api.digitorn.ai/v1/conversations/34428ad3-…/messages \
  -H "Authorization: Bearer sk_..." -H "Digitorn-User: user_482" \
  -H "Content-Type: application/json" \
  -d '{"content":"I take two bags","wait":60}'

Same answer shape. Over the user's plan or the project's ceiling, you get 429 quota_reached with the plan, the limit and when it resets; the agent does not run and nothing is billed.

Read

Call
GET /v1/conversations	The user's conversations, newest first (agent, limit, cursor).
GET /v1/conversations/{id}	Its status and the actions waiting for a decision.
GET /v1/conversations/{id}/messages	The user's and the agent's messages (after = a message id, limit).

A conversation of another user, or of another project, answers 404: it does not exist for you.

Stop, decide, delete

Call
POST /v1/conversations/{id}/cancel	Stops the agent's current work.
POST /v1/conversations/{id}/approvals/{approval}	{"decision":"approve"} or {"decision":"deny","reason":"…"} for an action the agent asked to confirm (booking, ordering…). The ids are in pending_approvals.
DELETE /v1/conversations/{id}	Deletes it.