POST
Ask the agent a question
Request · Response · Guide: Minto
Returns 202 with a job_id and never an answer: a run routinely outlives any HTTP request. Poll poll_url for the result, or let it arrive at the API key’s callback URL when the job settles.A session runs one turn at a time — asking again while a run is live is a 409. Wait for the job to reach a terminal status, or stop the run first.Scope the turn with file_ids, document_ids or directory_id; omit them to inherit the session’s scope, or set use_all_files to search the whole workspace.

Authorizations

​
x-api-key
string
header
required

API key for authentication

Headers

​
Idempotency-Key
string
required

Required opaque key (max 255 chars, UUIDv4 recommended) making this request idempotent for 24h: a retry with the same key and body replays the original response with Idempotent-Replayed: true. Omitting it is a 400; reusing a key with a different body is a 422; retrying while the first request is still in flight is a 409.

Path Parameters

​
session_id
string
required

Session to add the turn to.

Body

application/json
​
user_prompt
string
required

The question to ask.

Maximum string length: 30000
Example:

"Which invoices from Acme are still unpaid?"

​
file_ids
string[]

Restrict this turn to these files. Their documents are resolved for you. Omit to inherit the session's own scope.

Maximum array length: 100
​
document_ids
string[]

Restrict this turn to these documents. Takes precedence over file_ids.

Maximum array length: 100
​
directory_id
string

Restrict this turn to a directory.

Example:

"665f1c2e8a1b4c0012ab34cd"

​
use_all_files
boolean
default:false

Search the workspace's processed documents instead of a fixed list. Overrides file_ids and document_ids.

Bounded: the 100 most recently created processed documents are considered, newest first. A workspace larger than that is NOT searched in full — name the documents you care about with document_ids or file_ids when coverage matters.

​
llm_model
string

Model hint for this turn. Defaults to the workspace-configured model.

Example:

"auto"

​
allow_internet_search
boolean
default:true

Allow the agent to search the public internet.

​
allow_ai_query_subagent
boolean
default:true

Allow the agent to run structured queries over your data as a sub-agent.

​
client_ref
string

Opaque reference of your own, echoed back on the job and on the settlement webhook so you can correlate them with your own records.

Maximum string length: 255
Example:

"order-4417"

​
language_code
string

BCP-47 language tag the agent should answer in.

Example:

"en"

Response

Turn accepted and queued.

​
job_id
string
required

Job handle for this turn. Poll it for the answer.

Example:

"sajob_9f2c1a4b7e8d4c1fa0b3"

​
status
enum<string>
required

Always QUEUED here. The job moves to RUNNING, then to COMPLETED, FAILED or STOPPED.

Available options:
QUEUED
Example:

"QUEUED"

​
session_id
string
required

The session this turn belongs to.

Example:

"665f1c2e8a1b4c0012ab34cd"

​
created_at
string<date-time>
required
​
poll_url
string<uri-reference>
required

URL of GET /v1/jobs/{job_id}.