---
title: "Ask a question over your documents"
method: POST
path: "/v1/ask"
tags: ["Agent"]
---

# Ask a question over your documents

`POST /v1/ask`

## Request

- Base URL: `https://api.talonic.com`
- URL: `https://api.talonic.com/v1/ask`
- Auth: HTTP bearer

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.

## Request body

- object
  - `question` string, required: The natural-language question to answer over the workspace corpus.
  - `scope` object: Restrict the turn to a slice of the workspace. Present fields are ANDed, and the whole object is enforced as a bound SQL predicate on every retrieval plane. An empty `document_ids` array matches nothing.
    - `document_ids` string[]: Restrict to these documents. An empty array matches nothing.
    - `schema_id` string, uuid: Restrict to documents processed by a pipeline of this Spec.
    - `pipeline_id` string, uuid: Restrict to documents attached to this pipeline run.
    - `data_product_id` string, uuid: Restrict to documents behind this data product's pipeline run.
    - `document_type` string: Restrict to documents of this classification (a document type name).
    - `source_id` string, uuid: Restrict to documents ingested through this source connection.
    - `tags` string[]: Restrict to documents carrying ANY of these user tags.
    - `ingested_after` string, date-time: Restrict to documents ingested at or after this ISO timestamp.
    - `ingested_before` string, date-time: Restrict to documents ingested at or before this ISO timestamp.
  - `conversation_id` string, uuid: Continue this conversation; the agent sees its prior turns.
  - `model` string: Run the turn on a specific model (e.g. `claude-opus`). A model the workspace AI policy denies fails loudly; it is never substituted.
  - `model_class` string: Run the turn on a model class (e.g. `complex`); used when `model` is absent.
  - `output_format` object: Shape the final answer. Constrains form only, never grounding or citation.
    - `instruction` string: Free-text response-format instruction, e.g. "answer as a two-column table".
    - `template` string: A markdown skeleton whose headings and order the answer keeps.
  - `on_behalf_of` string, uuid: Answer as this workspace user would see it, applying that user's compartment and classification visibility. Opt-in per request; the user must be an active member of the calling workspace.

## Response `202`

Ask accepted; poll `poll_url` or stream `stream_url` for the answer.

- object
  - `ask_id` string, uuid
  - `status` 'processing'
  - `poll_url` string
  - `stream_url` string
  - `conversation_id` string, uuid: The conversation this ask threads into (created when none was given).

## Other responses

- `400`: The request is invalid.
- `401`: Missing or invalid API key.
- `402`: Insufficient credits. The body is the agent-actionable `insufficient_credits` contract with `buy_credits_url` and `pricing_url`.
- `429`: Daily rate limit exceeded.

---

[API](https://skmtc.dev/talonic/apis/talonic-api.md) · [All operations](https://skmtc.dev/talonic/apis/talonic-api/llms.txt) · [OpenAPI document](https://skmtc.dev/talonic/apis/talonic-api/revisions/678fe5f8c9c3?raw)