POST /orchestrate

Delegation depth of this call. Omit it on a first call. An agent that calls this endpoint while running a turn for another agent call must send its own depth plus one, so a chain of agents calling agents stops after 4 hops. A value above 4 is refused with 400 DELEGATION_DEPTH_EXCEEDED; a value that is not a single non-negative integer is refused with 400 INVALID_DELEGATION_DEPTH. The header is a loop guard you set yourself, not a credential: it grants nothing.

What closing the connection means for the turn (case-insensitive; also accepted as the on_disconnect query parameter). Absent or any other value (error): the turn stops and the jobs it started are cancelled (a guest call's too). stop: the same, recorded as a stop you asked for. continue: the turn does not stop; it finishes on the server within the request time limit, its jobs keep running, and nothing more is sent to the closed connection.

The user prompt for the biomedical agent

Override the model for this turn. Signed-in callers who omit it get the model saved in their AI preferences, as in the web app. The override must belong to a model family your organization allows; otherwise the call returns 403 MODEL_FAMILY_NOT_PERMITTED. Guest calls always run on the guest model.

Resume an existing session (UUID v7). Signed-in callers only: a guest's sessionId is ignored and a fresh session is started

Signed-in callers only. Run the turn inside one of your projects, as a web chat in that project does. A project you cannot access returns 404 PROJECT_NOT_FOUND; a project-scoped API key can only name its own projects.

Signed-in callers only. Run the turn inside one of your campaigns; the campaign's recent job history is added to the agent's context. A campaign you cannot access, or one outside projectId, returns 404 CAMPAIGN_NOT_FOUND.

Signed-in callers only. Ids of files you uploaded, attached to the prompt the way the web app's file picker attaches them. Any id that is not one of your files returns 404 FILE_NOT_FOUND.

Enable SSE streaming (default: true)

Presentation of a streaming turn. sse (default) is the wire contract: named text/event-stream events, as documented below. text writes the same events as labelled plain text (text/plain) for someone reading curl -N output: boxed session / tool sections, status glyphs, the answer as prose, and a done summary — no SSE framing, colour only on a TTY and only when NO_COLOR is unset. The query string form ?format=text is equivalent, and ?format=sse pins the default. Content, events and billing are identical either way.

Opt-in headless diagnostics (IH-19): collect console breadcrumbs + a synthesized TurnReport for offline analysis. Default: false.

Allow-list. When present, only these tools may be offered to the model or run, plus a small exempt set the platform needs (review_tool_registry, get_data, sandbox_read). [] means no domain tools (exempt set only); omit for no restriction. Names are matched as canonical tool names after alias resolution (e.g. diffdock → diffdock_dock). Names must be tools this deployment offers: an unknown, deprecated or disabled name is a 400 UNKNOWN_TOOL (details.unknownTools echoes the first 20, details.unknownCount counts them all). At most 256 names of at most 128 characters each; more is a 400 INVALID_REQUEST. The list only narrows: it never admits a tool your tier or the guest tier refuses, and sub-agents inherit it.

Deny-list. These tools are never offered to the model and a call to one is refused (tool error TOOL_EXCLUDED_BY_REQUEST) — including the exempt set if you name it. Same name matching and UNKNOWN_TOOL rule as tools. Wins over tools. Sub-agents inherit it. Withheld tools are reported in the response's withheldTools.

Most credits this response's model calls may debit. Each model call reserves the size of the largest call so far (at least 1 credit) before it is sent, and is refused when the credits spent plus every reservation of a call still running plus its own would exceed the cap, so calls made in parallel are checked together. Once one more tool round and the answer no longer fit, the tool loop stops and the answer is written from the results gathered; usage.llm.capped is then true. A call larger than every earlier one can overshoot by the difference. Counted: the model calls this response makes itself. Not counted or capped: GPU job credits (they appear in usage.gpu) and model calls a tool makes through a request to another API route. Guests may send it and it is accepted, but it is not applied: a guest call is bounded by the guest limits (the daily call quota and compute budget) instead. Must be a positive number, else 400 INVALID_REQUEST.

Present only when the turn was stopped before it finished (for example at the server time limit); content is then the partial answer. Absent on a completed turn.

Why the turn was stopped. Present only with status: "stopped".

Ivy's full response text

Source citations for the answer. Always present; an empty array means none were emitted. Folded from the turn's citation sets: a set marked final replaces the earlier ones, any other set is appended, deduplicated on source:identifier.

Where to verify this session's audit record. Authenticated callers only: the key is absent for guest calls, whose sessions are not kept. Paths are relative to the API base URL.

Tools the request's tools / excludeTools policy withheld this turn: offered-then-stripped intent or critical tools and refused calls, one entry per tool, at most 20 entries. Always present; an empty array means nothing was withheld.

Tool calls this turn that an approval gate (cost or safety check) would have stopped and that ran without an approval step, because gates are not enabled. One entry per tool and gate, at most 64 entries. Names only. Always present; an empty array means no call would have been gated.

Present only when more distinct gated calls ran than gatesAutoApproved lists: how many were left off it.

Credits this response's model calls debited from your balance (llm), and the credits held for the GPU jobs it submitted (gpu). Authenticated callers only: the key is absent for guest calls, which are not billed. Credits only: no dollar cost and no balance figure. A GPU hold is not the final charge: each job is charged when it finishes.

Approval gates the turn raised. Always present; an empty array means none fired. API and MCP callers have no interactive approver, so a gate auto-proceeds (outcome: auto_proceeded) and the tool runs.

The turn's plan. null means the turn made no plan; the key is absent when the turn ended before its plan could be read.

Sub-agents the turn spawned. Always present; empty means none.

Corrections applied to the answer during the turn. The answer text already reflects them; each entry names why. Always present; empty means none.

Model retries, fallbacks to another model, and whether every model in the selected family failed.

Present when the turn ended while background jobs were still running (signed-in callers only). Poll pollUrl (GET /api/v1/orchestrate/{sessionId}) with the same credential; once the jobs finish, the answer composed from their results appears under resume. Guests get no handle: a guest session is not saved, so it cannot be fetched later.