Ask a question over your documents

Ask a natural-language question over the workspace corpus and get back a cited, verified answer. This is the "replace your RAG stack" endpoint: instead of chunk-embed-retrieve, the Talonic agent plans over the structured field plane (three-plane retrieval: semantic field match, lexical value match, and document text search), runs read-only SQL over extracted cells, extracts-and-persists missing fields at query time, and grounds every load-bearing claim in an exact source span.

Only question is required. The optional fields narrow, route, shape, or thread the turn:

• scope restricts the turn to a slice of the workspace. The scope is compiled into a parameterized SQL predicate applied to every retrieval plane and every virtual table the agent can query, so it bounds what the agent CAN read rather than suggesting where it should look. document_ids is capped at 1000 entries and tags at 100. An explicit "document_ids": [] is an active scope that matches nothing; it never means "unscoped".
• conversation_id continues an existing conversation, so the agent answers with the prior turns in view. Absent, every ask starts a fresh conversation whose id comes back on the response.
• model runs the turn on a named model, and model_class selects a class when model is absent. Resolution order: explicit model, then model_class, then the workspace AI policy binding, then the platform default. A model the workspace AI policy denies fails loudly; it is never silently substituted.
• output_format shapes the final answer with a response-format instruction, a markdown template, or both. It constrains form only, never grounding.
• on_behalf_of opts this single request into compartment-correct retrieval as a named workspace user. Without it the key reads workspace-wide, across every compartment and classification.

The turn runs detached and typically takes 10-60 seconds, so the endpoint is asynchronous: it returns 202 with an ask_id immediately. Poll GET /v1/ask/{id} (about every 2 seconds) or stream GET /v1/ask/{id}/stream for the answer.

Each accepted ask charges one flat agent_ask credit unit at submission, keyed to the turn, so streaming, polling, and retrying the same turn never bill twice (see GET /v1/pricing). The turn is pinned to the least-privilege viewer role: only read tools run, every mutation is denied before it executes.