Skip to main content
POST
cURL

Authorizations

Authorization
string
header
required

API key or UI session JWT passed as a Bearer token.

Headers

AiQL-Workspace
string
required

ID of the workspace the request operates on.

Body

application/json
content
string
default:""

Natural-language content of the query. Empty when resuming tools.

parent_id
string | null

Query id to continue, or a new client-chosen id to create. Omit to start a chat with a server-generated id. Returns 404 if the id belongs to another workspace.

mode
enum<string>
default:ask

Inquiry interaction mode: ask, reason, or build.

Available options:
ask,
reason,
build
visualize
boolean
default:false

When true, expose graph visualization tools.

interactive
boolean
default:false

When true, expose follow-up question tools.

context
QueryContext · object | null

Bound artifact ids and selected snippets for this turn.

tool_results
Tool Results · object | null

Client-side tool results used to resume a deferred turn.

Response

Successful Response

id
string
required

Unique identifier of the query.

content
string
required

Natural-language content of the query.

status
string
required

Status of the query: PENDING, PROCESSING, PROCESSED, or FAILED.

output
string | null

Result the query produced.

steps
(QueryTextStep · object | QueryToolStep · object)[]

Ordered steps taken while working toward the final output. Each step is either an assistant text message ({"text": ...}) or a tool invocation ({"tool": ...}). Reasoning parts, tool arguments, and tool outputs are not included, and the final output is not repeated.

run_id
string | null

Active agent run id when a turn was just started.

channel
string | null

Realtime channel for streaming this query.

token
string | null

Centrifugo connection token for streaming.

subscription_token
string | null

Centrifugo subscription token for the query channel.

ws_url
string | null

Centrifugo websocket URL.

since
StreamPosition · object | null

Stream position to subscribe from.