POST /v1/ask

POST /v1/ask asks a natural-language question over every document in your workspace and returns a cited, verified answer. One flat credit per question, no RAG stack.

POST /v1/ask is the natural-language front door to your document corpus: send a question, get back an answer grounded in your own documents, with a citation for every load-bearing claim and a verification verdict on the answer as a whole. There is no index to build, no embeddings to manage, and no retrieval pipeline to tune. Every document you ingest with ingestion_target: "ingest" (the default on [POST /v1/run](run-spec)) is askable, and the question runs over the entire workspace corpus, not a top-k slice of it.

The endpoint accepts one JSON field, question, up to 20,000 characters. It answers 202 Accepted immediately with an ask_id and a poll_url; the answer itself is produced asynchronously and collected via [GET /v1/ask/:id](ask-results). A turn typically takes 10 to 60 seconds, which is why the surface is async-only by design: a synchronous response would sit inside edge and proxy timeouts. Authentication is a standard tlnc_ Bearer key with the read scope. The key must be workspace-scoped: asks are tenant-isolated end to end.

Why this replaces a RAG stack

A conventional RAG pipeline embeds document chunks, retrieves the top-k nearest ones, and hopes the answer is inside that slice. An ask on Talonic instead runs a read-only agent turn over a corpus that was structured at ingestion. The agent retrieves across three planes at once: a semantic match against the field registry (the deduplicated graph of every field concept discovered in your documents), a lexical match over the extracted cell values themselves, and semantic plus full-text search over the raw document text through a persistent chunk index. A question about a number, a date, or a counterparty does not depend on the right paragraph landing in a context window: the value was already extracted, typed, and bound to a canonical concept.

On top of retrieval, the agent runs read-only SQL over the structured cell plane. Questions RAG is structurally bad at, such as "how many of our contracts auto-renew?" or "what is the total value of invoices from Q2?", become aggregate queries over extracted cells with the denominator taken from real corpus coverage, never estimated from a handful of retrieved chunks. And the corpus improves as it is questioned: when a question exposes a coverage gap, the platform extracts and persists at query time, promoting or mining the concept into the structured plane, so the second time anyone asks, the answer is a plain SQL read. Your corpus gets faster and cheaper to query the more it is used, which is the opposite of a RAG stack.

Two more properties matter for trust. First, the coverage plane turns absence into evidence: "no document in the workspace mentions a termination penalty" is a checkable statement backed by corpus-wide coverage, not a guess from an empty retrieval. Second, every answer passes through a post-answer verification step that re-checks the answer's claims against the evidence the turn itself gathered, and the verdict ships in the response. See [Citations & Verification](ask-citations-verification) for how to consume both.

An ask never modifies your workspace. The turn runs under a least-privilege read-only role: documents, schemas, pipelines, and settings cannot be changed by a question, and every mutating tool is denied before it executes.

POST/v1/ask

Request body (JSON)

question*stringThe natural-language question, up to 20,000 characters. Markdown is fine; the agent reads it as plain intent.

curl

Response (202)

{
  "ask_id": "7c2f0a4e-9d31-4b8a-b3e6-2f1c5d9a8e07",
  "status": "processing",
  "poll_url": "/v1/ask/7c2f0a4e-9d31-4b8a-b3e6-2f1c5d9a8e07"
}

Pricing

Each accepted ask charges one flat agent_ask credit unit: 100 credits, or 0.10 EUR (1,000 credits = 1 EUR). The charge is taken when the ask is accepted and is keyed to the turn, so it is idempotent: a network retry of the same submission, or polling the result any number of times, never bills twice. There is no per-token or per-document component; a question over 10 documents and a question over 10,000 cost the same. The completed response reports the charge back in usage.credits_charged, and the full catalog is public at [GET /v1/pricing](pricing-overview).

When your balance cannot cover one unit, the ask is rejected up front with 402 insufficient_credits before any work starts. The 402 body follows the platform's agent-actionable credits contract: it names the unit, the shortfall, and a buy_credits_url, so an autonomous integration can top up and resubmit without human interpretation.

Rate limits

Ask submissions are metered in their own daily rate-limit namespace, ask, separate from extraction and platform reads. Polling GET /v1/ask/:id counts against the general read namespace, never against the ask budget, so tight polling loops are free with respect to this cap.

Daily ask caps by plan

freetier200 asks per day.

individualtier100 asks per day.

protier5,000 asks per day.

enterprisetierUnlimited.

Getting a key and a corpus

If your workspace already has documents, any read-scoped key works immediately. On deployments where self-serve signup is enabled, there is a zero-dashboard path from email to first answer: POST /v1/auth/register with your email sends a magic link, and following it (GET /v1/auth/register/confirm) returns a scoped tlnc_ key together with a seeded workspace containing two example documents, a Northwind invoice and an Acme/Globex master services agreement, so your very first POST /v1/ask has something real to answer against. To make your own documents askable, ingest them via [POST /v1/run](run-spec) with the default ingestion_target: "ingest".