Copilot

The copilot answers a request about the stored data, calling its data tools and answering from their results. For model calls with your own messages, tools, and sampling, use model inference; for a full company report, use research.

Routes

task	route
start a run	POST /v1/agents/copilot/runs
read a run	GET /v1/agents/copilot/runs/{run_id}
cancel a run	POST /v1/agents/copilot/runs/{run_id}/cancel
create, list, read, or delete a conversation	/v1/agents/copilot/conversations (conversations)

Every route needs the ai entitlement (entitlements). Starting a run is AI work; reading, listing, canceling, and deleting count as data requests. Examples, including a conversation, are in Python examples.

Runs

POST /v1/agents/copilot/runs takes input (your message), optionally conversation (the one to continue; omitted, the run starts a new one), stream, and max_output_tokens. Every field is described in the API reference.

Earlier turns are not sent in input; the conversation holds them. Any other field (model, instructions, tools, temperature, …) is refused 400 unsupported_parameter, naming it. input is at most 32,000 characters, and the request body at most 128 KiB. A conversation runs one run at a time: starting a second while one is in progress is 409 conversation_busy.

curl https://api.tauric.ai/v1/agents/copilot/runs \
  -H "Authorization: Bearer $TAURIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "What is the 10-year Treasury yield, and how did it move this week?"}'

The run object

A run has object: "copilot.run" and a status: in_progress, completed, incomplete, failed, or cancelled. Every field is described in the API reference.

output holds the assistant's message items (output_text) and the tool work behind them. Each function_call item is a call the copilot already executed (x_tauric.executed_by: "platform"); you never run it. It is followed by its function_call_output, the tool's result: x_tauric.ok says whether the tool succeeded, and x_tauric.structured carries its data.

When a run is read, model-authored content can be withheld, with the reason.

Answer composition

x_tauric.composition on a completed run is applied or fallback. When a figure matters in a fallback answer, read it from the run's function_call_output items or from the data routes.

Streaming

With stream: true the run sends server-sent events in OpenAI's Responses grammar. It ends on exactly one terminal event: response.completed, response.incomplete, or response.failed. A canceled run ends on response.incomplete with status cancelled.

Closing the connection does not cancel a run: it continues and is stored, so you can read it back or cancel it.

Read or cancel a run

GET /v1/agents/copilot/runs/{run_id} reads a run as JSON, with every output item so far, tool outputs included.

POST /v1/agents/copilot/runs/{run_id}/cancel stops a run that is still in progress. It answers with the run: 200 once the run reads cancelled, 202 while the stop is still settling (read it again). A finished run is returned unchanged.

Retry a start safely

Send an Idempotency-Key header (1–256 characters of [A-Za-z0-9_-]). A retry with the same key and body returns the original run instead of starting a new one. A streamed start cannot be replayed: read the run instead.

Conversations

A conversation keeps the history the copilot reads on each run. Conversations and runs belong to the account: every key of the account sees them.

operation	what it does
POST /v1/agents/copilot/conversations	creates one (201); title is optional, at most 200 characters; Idempotency-Key is supported
GET /v1/agents/copilot/conversations	lists yours, newest first
GET /v1/agents/copilot/conversations/{conversation_id}	reads one
GET /v1/agents/copilot/conversations/{conversation_id}/items	lists its items: your messages and every run's output
DELETE /v1/agents/copilot/conversations/{conversation_id}	deletes it with its runs; 409 conversation_busy while a run is in progress (cancel it or wait)

Both lists page by limit (1–100, default 20) and after (lists). The item list also takes order (asc or desc, default desc) and include.

A run in a conversation, with an Idempotency-Key so a retried start is not run twice (api is an httpx.Client with your key, as in the Python examples):

conv = api.post("/v1/agents/copilot/conversations", json={"title": "Rates"}).json()
run = api.post("/v1/agents/copilot/runs",
               json={"input": "What is the 10-year Treasury yield?", "conversation": conv["id"]},
               headers={"Idempotency-Key": "rates-1"}).json()
for item in run["output"]:
    if item["type"] == "message":
        print(item["content"][0]["text"])

Usage

A run is charged as charges for AI work sets out. Its usage reports input_tokens, output_tokens, and total_tokens. input_tokens includes the copilot's instructions and tool definitions, several thousand tokens even for a one-line message, and input tokens are charged (how credits are counted).

usage is null while the run is in progress, and when any model call went unreported; x_tauric.usage says how many calls were unreported.

A research run the copilot starts as a tool is a separate run (runs started by the copilot).

Errors

These routes use the shared error envelope. The shared codes (invalid_request, not_found, request_too_large, quota_exhausted, concurrency_limit_reached, server_error) are in error codes. The codes specific to the copilot:

code	status	meaning	retry
unsupported_parameter	400	a parameter, field or value the route does not support; param names it	change_request
stream_not_replayable	409	the run's stream cannot be replayed; retrieve the run instead	change_request
idempotency_key_reuse	422	the Idempotency-Key was already used with a different request	change_request
retry_in_progress	409	a request with this Idempotency-Key is still in progress	later
conversation_busy	409	the conversation has a response in progress; retry after it finishes	later
idempotency_mark_failed	500	the run could not be completed; retry with the same Idempotency-Key	later
idempotency_unavailable	503	an Idempotency-Key cannot be honored right now	later
audit_unavailable	503	the request cannot be accepted right now	later