Agent

Ask the agent (legacy alias of /v1/ask)

Legacy alias of POST /v1/ask with a minimal response shape. Starts a read-only agent turn (202) to poll via GET /v1/agent/query/{id}, which returns only status and the plain answer text. New integrations should use /v1/ask, which adds structured citations, the verification verdict, and usage. Charges the same flat agent_ask unit.

Bounded synchronous mode (?wait=). Some questions are answered by a cheap deterministic retrieval tier that runs inline, in roughly 1.5-2.5s, rather than by the agent loop. For those, the 202 makes the caller spend a whole poll interval rediscovering an answer the server already has. Send ?wait=<seconds> and an answer produced inside that budget comes back as 200 with the completed payload — the poll body plus turnId. Every other outcome, including a fast-tier answer that overran the budget and every question that goes to the agent loop, still returns 202 { "turnId": ... } exactly as before.

wait is opt-in and additive: a request without it is unchanged. It bounds how long you block before being handed an INLINE answer; it does not cancel work already running, and it never waits on an agent-loop turn. Overrunning the budget costs nothing — the answer is already stored, so your first poll returns it.

post/v1/agent/query

Request

  • Base URL: https://api.talonic.com
  • URL: https://api.talonic.com/v1/agent/query
  • Auth: HTTP bearer

Query parameters

waitnumber

Seconds to hold the request open for an inline answer. Omit for the asynchronous 202 contract. Values above the server ceiling (10s) are rejected.

Request body

querystring required

Response

Only when wait was sent and the fast retrieval tier answered inside it. The body is the GET /v1/agent/query/{id} body plus turnId, so the same code can read it.

turnIdstring uuid
status'completed'
answerstring
tierstring

Which engine answered; retrieval_fast_path for every 200.

Changes

No recorded changes to this operation across all 1 revision of this API.