POST
Ask the agent a question
This endpoint requires an Idempotency-Key request header — omitting it is a 400. See Idempotent requests.
This endpoint never returns an answer directly — it queues the turn and responds 202 with a job_id. See The async job lifecycle for how to poll poll_url (GET /v2/jobs/{job_id}) through to a result, and for the one run per session rule that makes a second ask a 409 while a turn is live.

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 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 /v2/jobs/{job_id}.