Agent Query (Legacy)

POST /v1/agent/query is the legacy alias of POST /v1/ask: same read-only turn, same flat charge, with ?wait=<seconds> for a bounded synchronous 200 answer.

POST /v1/agent/query is the legacy alias of [POST /v1/ask](post-ask). Both endpoints start exactly the same read-only agent turn over the workspace corpus, and both charge the same flat agent_ask unit (100 credits per accepted question, idempotent per turn). The difference is the result surface: the ask endpoints return the full payload with the verification verdict and usage, while the query poll returns a compact {status, answer, tier, citations} body. Scoping, conversations, model selection, output formatting, and streaming likewise exist only on the ask surface. New integrations should use /v1/ask; this alias remains supported for integrations built against the original surface.

The request body carries one field, query (up to 20,000 characters). By default the submission answers 202 Accepted with a turnId; poll GET /v1/agent/query/:id roughly every 2 seconds until status leaves processing. Like the ask surface, the alias requires a workspace-scoped key with the read scope, runs the turn under the least-privilege viewer role with the key's minting user's document visibility, and is tenant-isolated: a turn started by another workspace reads as 404.

Bounded synchronous mode: ?wait

The route is not 202-only: ?wait=<seconds> opts into a bounded synchronous answer. Simple retrieval questions are tried against a cheap deterministic tier before any loop turn starts, so when that fast path answers, the answer already exists before the response is written. With wait, an answer produced inside your budget returns 200 OK with the completed payload — turnId, status: "completed", answer, tier, and citations[] — saving the poll round-trip entirely. Anything else, including a fast-path answer that overran the budget and every question that falls through to the full agent loop, returns the byte-identical 202 {turnId}.

wait is bounded by a configured ceiling (10 seconds by default): a value that is not a number between 0 and the ceiling is rejected with 400 naming the valid range, so a typo never silently degrades to async. An overrun budget costs nothing — the answer is durable the moment it is produced, so your very first poll returns it. Loop turns take 10-60 seconds and are never held open by wait; treat the 202 branch as the normal case and the 200 as a latency optimization for retrieval-shaped questions.

The answer text is a narrative: for fast-path turns it carries the deterministic answer, an echo of the query spec the tier compiled, the coverage it computed, and a source line per cited cell; the raw one-line answer as the deterministic templates rendered it is additionally persisted under the turn's retrieval.answer metadata. For full loop turns, answer is the assistant narrative plus a markdown projection of any generative cards the agent produced (tables, ranked lists), so a headless consumer receives the whole deliverable, not a caption pointing at an invisible table.

curl -s -X POST "https://api.talonic.com/v1/agent/query?wait=5" \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "What is the total gross amount across June invoices?"}'

{
  "turnId": "7c2f1e04-51ab-4b8e-9d2f-3a6c8e0b4d21",
  "status": "completed",
  "answer": "The total gross amount across June invoices is EUR 48,200.00...",
  "tier": "retrieval_fast_path",
  "citations": [
    {
      "quote": "48,200.00",
      "document_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "kind": "cell",
      "reference": "bruttobetrag",
      "filename": "invoice-0847.pdf",
      "app_url": "https://app.talonic.com/documents/c3d4e5f6-..."
    }
  ]
}

TURN_ID=$(curl -s -X POST https://api.talonic.com/v1/agent/query \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Summarize our open invoices by vendor."}' | jq -r '.turnId')

curl -s https://api.talonic.com/v1/agent/query/$TURN_ID \
  -H "Authorization: Bearer $TALONIC_API_KEY"

Errors