# Rebyte API Version: 1.0.0 Base URL: `https://api.rebyte.ai` Guide: [Rebyte API v1 guide](https://rebyte.ai/docs/agent-computer-api/reference) The complete public /v1 contract for Rebyte Agents, Sessions, Messages, Agent Computers, legacy Tasks, Webhooks, files, workspace artifacts, Agent Context, billing, and restricted partner operations. New integrations should create reusable Agents, create isolated Sessions from an Agent snapshot, and submit Messages asynchronously. The existing Web application and legacy /v1/tasks API remain available and backward-compatible. Session SSE is a live/recent observation transport, not a durable event ledger. Durable cursor replay is intentionally outside this version. Existing organization Webhooks remain best-effort: one delivery attempt, no retry, and delivery failure may be dropped. ## Authentication Send the organization API key in `API_KEY` unless an operation explicitly has no security requirement. Agent and Session reads require `tasks:read`; writes require `tasks:write`. Files use `files:write`, Webhooks use `webhooks:read` or `webhooks:write`, and restricted partner operations use `accounts:write`. Each operation below is authoritative for its required access. ## Quickstart This Bash script requires `curl` and `jq`. It creates an Agent, creates a Session, opens SSE before submitting a Message, then polls the authoritative Message transcript until a durable terminal or paused state. ```bash set -euo pipefail export REBYTE_API_KEY='rbk_replace_me' export REBYTE_BASE_URL='https://api.rebyte.ai' RUN_ID="$(date +%s)-$$" AGENT_ID="$( curl -fsS -X POST "$REBYTE_BASE_URL/v1/agents" \ -H "API_KEY: $REBYTE_API_KEY" \ -H 'Content-Type: application/json' \ -H "Idempotency-Key: quickstart-agent-$RUN_ID" \ -d '{"name":"API quickstart"}' | jq -er '.agent.id' )" SESSION_ID="$( curl -fsS -X POST "$REBYTE_BASE_URL/v1/sessions" \ -H "API_KEY: $REBYTE_API_KEY" \ -H 'Content-Type: application/json' \ -H "Idempotency-Key: quickstart-session-$RUN_ID" \ -d "{\"agentId\":\"$AGENT_ID\",\"title\":\"Quickstart\"}" | jq -er '.session.id' )" # Open the standing stream before submitting the Message so live frames are visible. SSE_FILE="/tmp/rebyte-$SESSION_ID.sse" curl -fsSN "$REBYTE_BASE_URL/v1/sessions/$SESSION_ID/stream" \ -H "API_KEY: $REBYTE_API_KEY" >"$SSE_FILE" & STREAM_PID=$! trap 'kill "$STREAM_PID" 2>/dev/null || true' EXIT CONNECT_DEADLINE=$((SECONDS + 30)) until grep -q '^event: session.connected$' "$SSE_FILE"; do if ! kill -0 "$STREAM_PID" 2>/dev/null; then wait "$STREAM_PID" || true exit 1 fi if ((SECONDS >= CONNECT_DEADLINE)); then printf 'Timed out waiting for session.connected\n' >&2 exit 1 fi sleep 0.1 done ACCEPTED_JSON="$( curl -fsS -X POST "$REBYTE_BASE_URL/v1/sessions/$SESSION_ID/messages" \ -H "API_KEY: $REBYTE_API_KEY" \ -H 'Content-Type: application/json' \ -H "Idempotency-Key: quickstart-message-$RUN_ID" \ -d '{"parts":[{"type":"text","text":"Reply with exactly: hello"}]}' )" printf '%s\n' "$ACCEPTED_JSON" | jq . MESSAGE_ID="$(jq -er '.message.id' <<<"$ACCEPTED_JSON")" # GET is the authoritative transcript read; poll it to a durable terminal state. MESSAGE_DEADLINE=$((SECONDS + 300)) while :; do MESSAGE_JSON="$( curl -fsS "$REBYTE_BASE_URL/v1/sessions/$SESSION_ID/messages/$MESSAGE_ID" \ -H "API_KEY: $REBYTE_API_KEY" )" STATUS="$(jq -r '.message.status' <<<"$MESSAGE_JSON")" case "$STATUS" in completed|failed|canceled) break ;; paused) printf 'Message paused; inspect .message.pendingActions and use the answer endpoint.\n' >&2 break ;; *) if ((SECONDS >= MESSAGE_DEADLINE)); then printf 'Timed out waiting for a terminal Message state\n' >&2 exit 1 fi sleep 1 ;; esac done printf '%s\n' "$MESSAGE_JSON" | jq . printf 'SSE frames were captured in %s\n' "$SSE_FILE" ``` The Message submission returns a `202 Accepted` projection once the turn is accepted or queued. Execution normally continues asynchronously; an idempotent replay may already be terminal, so GET the Message for current authoritative state. A typical acceptance body is: ```json { "message": { "id": "018f47b8-6a2e-7d70-b3ef-879c7643f4d1", "object": "message", "sessionId": "018f47b7-f166-7be1-8d21-094fe47bb760", "status": "running", "warnings": [] } } ``` `message.id` is the public prompt ID used by both SSE `messageId` and the transcript GET endpoints. Multiple submitted text parts are joined with newline characters into one effective prompt; transcript reads return that normalized text as one part. `warnings` contains non-fatal, acceptance-time warnings for this request and does not mean the Message was rejected. ## Idempotency `Idempotency-Key` is optional for Agent and Session creation and required for Session messages. Reusing an Agent or Session key with a different definition, or a Message key with different effective text, returns `409 idempotency_key_conflict`. Message keys are scoped to the organization and Session and are durable through the public prompt identity. ## Session SSE The standing stream is `GET /v1/sessions/{id}/stream`. Each SSE event frame uses the public event type in the `event:` line and a JSON `SessionEvent` envelope in the `data:` line; heartbeat frames are comments: ```text id: msg:: event: message.event data: {"object":"session.event","type":"message.event","sessionId":"...","channel":"message","messageId":"...","runId":"...","createdAt":"...","data":{"sourceType":"...","step":1,"payload":{}}} ``` `messageId` is always the stable public prompt ID when the frame belongs to a Message. `runId` is a separate execution-run correlation ID. The `id:` field is channel-scoped and is not a global or durable cursor. Stable public event types: - `session.connected` — The first frame on a connection; data.session contains the current Session snapshot. - `session.event` — A conversation-level runtime event that is not the start of a Message run. - `message.started` — A public Message was attached to an Agent run. messageId is the public Message ID; runId identifies the run. - `message.event` — A non-terminal output, tool, or progress event for a Message run. tool_ask_user_question exposes data.actionId and data.question for HITL. - `message.completed` — The Message reached the durable completed state. - `message.failed` — The Message reached the durable failed state. - `message.canceled` — The Message reached the durable canceled state. - `message.stream_end` — The live run channel reached its transport boundary; this does not close the standing Session stream. `message.completed`, `message.failed`, and `message.canceled` correspond to durable terminal Message states. `message.stream_end` only marks the end of the live run channel; the standing Session connection remains open for later Messages. SSE is for live/recent observation and does not provide durable cursor recovery in v1. Reconcile with `GET /v1/sessions/{id}/messages` or `GET /v1/sessions/{id}/messages/{messageId}`; these transcript reads are authoritative for status, unresolved HITL questions, final response, and error. Ephemeral tool and progress frames cannot be reconstructed from the transcript. Replay and buffering are deliberately bounded: each channel reads at most 2,000 recent events or 8 MiB of history, initialization buffers at most 512 live events or 4 MiB, at most 100 recent/active run channels are followed, and socket backpressure is capped at 1 MiB. Reconnects can repeat recent events, so deduplicate by the complete SSE `id` value. If a limit is exceeded the server closes the connection; reconcile through Message GETs and use retry backoff because an immediate reconnect can encounter the same retained-history limit. ## Human-in-the-loop answers When a `message.event` has `data.sourceType` equal to `tool_ask_user_question`, read the normalized question and nonnegative integer action identifier from `data.question` and `data.actionId`; use the envelope `messageId` in the answer URL. After a disconnect, the same durable values are available in `message.pendingActions`, where each action includes its canonical `messageId`. `question.questions` always contains the ordered list of one to four questions. POST the answer to that public Message: ```bash MESSAGE_ID='the-message-id-from-the-SSE-envelope' ACTION_ID='42' # data.actionId from the SSE envelope ANSWER_JSON='"Yes"' # Any JSON value: string, object, array, number, boolean, or null curl -fsS -X POST "$REBYTE_BASE_URL/v1/sessions/$SESSION_ID/messages/$MESSAGE_ID/answer" \ -H "API_KEY: $REBYTE_API_KEY" \ -H 'Content-Type: application/json' \ -d "$(jq -cn --argjson actionId "$ACTION_ID" --argjson answer "$ANSWER_JSON" '{actionId:$actionId,answer:$answer}')" ``` For a batched question, submit one answer object shaped like `{"answers":[{"selectedOptions":[0]},{"customResponse":"Free-form answer"}]}`; each array entry corresponds to the same-index item in `question.questions`. A single-question answer may use that question answer shape or any JSON value. A `200` status of `resuming` means this answer resumed the turn. `accepted` means the answer was recorded but another blocked action on the same turn remains. A stale, duplicate, mismatched, or already-resolved action returns `409`. ## Webhooks Existing `/v1/webhooks` registrations continue to receive API task lifecycle events. Delivery is best-effort: one attempt, no retry, and failures may be dropped. Consumers that require reconciliation should read Session and Message state. ## Endpoints ### GET /v1/openapi.json Download the OpenAPI document Responses: - `200` — OpenAPI 3.1 document. Schema: `application/json`: object. ### GET /v1/openapi.md Download the LLM-friendly Markdown contract Responses: - `200` — Markdown generated from this OpenAPI document. Schema: `text/markdown`: string. ### GET /v1/agents List Agents Required API key scopes: `tasks:read`. Responses: - `200` — Organization Agents. Schema: `application/json`: object { data: array }. - `401` — Missing, invalid, or expired API key. Schema: `application/json`: Error. - `403` — The API key lacks the required scope, or policy rejected the request. Schema: `application/json`: Error. - `500` — An unexpected server error occurred. Schema: `application/json`: Error. ### POST /v1/agents Create an Agent Creates configuration only. Each new Session receives an isolated snapshot of the Agent configuration. Required API key scopes: `tasks:write`. Parameters: - `Idempotency-Key` (header, optional; string) — Up to 255 visible ASCII characters. Reusing the key with the same body returns the same resource. JSON request schema: ```json { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "\\S" }, "instructions": { "type": "string", "maxLength": 100000 }, "model": { "type": "string", "enum": [ "deepseek-v4-pro", "glm-5.2", "kimi-k3", "claude-sonnet-5", "claude-opus-5", "gpt-5.6", "gpt-5.4-mini" ] }, "maxSteps": { "type": "integer", "exclusiveMinimum": 0, "maximum": 128 }, "mcpServers": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "internal" }, "name": { "type": "string", "enum": [ "web_search_&_browse", "sandbox", "coding_agent", "ask_user_question", "report_builder", "company", "app_builder_contract", "github", "sound_studio", "speech_generator", "http_client" ] } }, "required": [ "kind", "name" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "composio" }, "toolkit": { "type": "string", "minLength": 1, "maxLength": 300, "pattern": "^\\S(?:[\\s\\S]*\\S)?$" } }, "required": [ "kind", "toolkit" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "custom" }, "serverId": { "type": "string", "format": "uuid" } }, "required": [ "kind", "serverId" ], "additionalProperties": false } ] }, "maxItems": 64, "uniqueItems": true }, "skills": { "type": "array", "items": { "type": "object", "properties": { "repo": { "type": "string", "minLength": 1, "maxLength": 300, "pattern": "^(?!.*\\.[gG][iI][tT]$)[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?\\/[A-Za-z0-9._-]+$" }, "path": { "type": "string", "minLength": 1, "maxLength": 1000, "pattern": "^(?!\\/)(?!.*(?:^|\\/)\\.\\.?(?:\\/|$))(?!.*\\\\)(?!.*[?#\\s])(?!.*(?:^|\\/)[sS][kK][iI][lL][lL]\\.[mM][dD]$)[^/]+(?:\\/[^/]+)*$" } }, "required": [ "repo", "path" ], "additionalProperties": false }, "maxItems": 128, "uniqueItems": true } }, "required": [ "name" ], "additionalProperties": false } ``` Responses: - `201` — Agent created or idempotently replayed. Schema: `application/json`: object { agent: Agent }. - `400` — A path, query, header, or JSON body value is invalid. Schema: `application/json`: Error. - `401` — Missing, invalid, or expired API key. Schema: `application/json`: Error. - `402` — The selected model or turn requires credits or an active subscription. Schema: `application/json`: Error. - `403` — The API key lacks the required scope, or policy rejected the request. Schema: `application/json`: Error. - `409` — The request conflicts with the current resource or idempotency state. Schema: `application/json`: Error. - `500` — An unexpected server error occurred. Schema: `application/json`: Error. ### GET /v1/agents/{id} Get an Agent Required API key scopes: `tasks:read`. Parameters: - `id` (path, required; string (uuid)) — Agent ID. Responses: - `200` — Agent. Schema: `application/json`: object { agent: Agent }. - `400` — A path, query, header, or JSON body value is invalid. Schema: `application/json`: Error. - `401` — Missing, invalid, or expired API key. Schema: `application/json`: Error. - `403` — The API key lacks the required scope, or policy rejected the request. Schema: `application/json`: Error. - `404` — The requested resource was not found in this organization. Schema: `application/json`: Error. - `500` — An unexpected server error occurred. Schema: `application/json`: Error. ### PATCH /v1/agents/{id} Update an Agent Existing Sessions retain their creation-time Agent snapshot. Required API key scopes: `tasks:write`. Parameters: - `id` (path, required; string (uuid)) — Agent ID. JSON request schema: ```json { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "\\S" }, "instructions": { "type": "string", "maxLength": 100000 }, "model": { "type": "string", "enum": [ "deepseek-v4-pro", "glm-5.2", "kimi-k3", "claude-sonnet-5", "claude-opus-5", "gpt-5.6", "gpt-5.4-mini" ] }, "maxSteps": { "type": "integer", "exclusiveMinimum": 0, "maximum": 128 }, "mcpServers": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "internal" }, "name": { "type": "string", "enum": [ "web_search_&_browse", "sandbox", "coding_agent", "ask_user_question", "report_builder", "company", "app_builder_contract", "github", "sound_studio", "speech_generator", "http_client" ] } }, "required": [ "kind", "name" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "composio" }, "toolkit": { "type": "string", "minLength": 1, "maxLength": 300, "pattern": "^\\S(?:[\\s\\S]*\\S)?$" } }, "required": [ "kind", "toolkit" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "custom" }, "serverId": { "type": "string", "format": "uuid" } }, "required": [ "kind", "serverId" ], "additionalProperties": false } ] }, "maxItems": 64, "uniqueItems": true }, "skills": { "type": "array", "items": { "type": "object", "properties": { "repo": { "type": "string", "minLength": 1, "maxLength": 300, "pattern": "^(?!.*\\.[gG][iI][tT]$)[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?\\/[A-Za-z0-9._-]+$" }, "path": { "type": "string", "minLength": 1, "maxLength": 1000, "pattern": "^(?!\\/)(?!.*(?:^|\\/)\\.\\.?(?:\\/|$))(?!.*\\\\)(?!.*[?#\\s])(?!.*(?:^|\\/)[sS][kK][iI][lL][lL]\\.[mM][dD]$)[^/]+(?:\\/[^/]+)*$" } }, "required": [ "repo", "path" ], "additionalProperties": false }, "maxItems": 128, "uniqueItems": true } }, "additionalProperties": false, "minProperties": 1 } ``` Responses: - `200` — Updated Agent. Schema: `application/json`: object { agent: Agent }. - `400` — A path, query, header, or JSON body value is invalid. Schema: `application/json`: Error. - `401` — Missing, invalid, or expired API key. Schema: `application/json`: Error. - `402` — The selected model or turn requires credits or an active subscription. Schema: `application/json`: Error. - `403` — The API key lacks the required scope, or policy rejected the request. Schema: `application/json`: Error. - `404` — The requested resource was not found in this organization. Schema: `application/json`: Error. - `500` — An unexpected server error occurred. Schema: `application/json`: Error. ### DELETE /v1/agents/{id} Delete an Agent Rejected while Sessions still reference the Agent and rejected for the organization default Agent. Required API key scopes: `tasks:write`. Parameters: - `id` (path, required; string (uuid)) — Agent ID. Responses: - `204` — Agent deleted. No response body. - `400` — A path, query, header, or JSON body value is invalid. Schema: `application/json`: Error. - `401` — Missing, invalid, or expired API key. Schema: `application/json`: Error. - `403` — The API key lacks the required scope, or policy rejected the request. Schema: `application/json`: Error. - `404` — The requested resource was not found in this organization. Schema: `application/json`: Error. - `409` — The request conflicts with the current resource or idempotency state. Schema: `application/json`: Error. - `500` — An unexpected server error occurred. Schema: `application/json`: Error. ### GET /v1/sessions List Sessions Required API key scopes: `tasks:read`. Parameters: - `agentId` (query, optional; string (uuid)) — Return only Sessions created from this Agent. - `limit` (query, optional; integer) — Maximum number of records to return. - `offset` (query, optional; integer) — Number of records to skip. Responses: - `200` — Sessions. Schema: `application/json`: object { data: array; total: integer; limit: integer; offset: integer }. - `400` — A path, query, header, or JSON body value is invalid. Schema: `application/json`: Error. - `401` — Missing, invalid, or expired API key. Schema: `application/json`: Error. - `403` — The API key lacks the required scope, or policy rejected the request. Schema: `application/json`: Error. - `500` — An unexpected server error occurred. Schema: `application/json`: Error. ### POST /v1/sessions Create an idle Session Creates the durable Session and isolated runtime snapshot. Execution starts only when the first message is submitted. Required API key scopes: `tasks:write`. Parameters: - `Idempotency-Key` (header, optional; string) — Up to 255 visible ASCII characters. Reusing the key with the same body returns the same resource. JSON request schema: ```json { "type": "object", "properties": { "agentId": { "type": "string", "format": "uuid" }, "title": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "\\S" } }, "required": [ "agentId" ], "additionalProperties": false } ``` Responses: - `201` — Session created or idempotently replayed. Schema: `application/json`: object { session: Session }. - `400` — A path, query, header, or JSON body value is invalid. Schema: `application/json`: Error. - `401` — Missing, invalid, or expired API key. Schema: `application/json`: Error. - `403` — The API key lacks the required scope, or policy rejected the request. Schema: `application/json`: Error. - `404` — The source Agent was not found in this organization. Schema: `application/json`: Error. - `409` — The request conflicts with the current resource or idempotency state. Schema: `application/json`: Error. - `500` — An unexpected server error occurred. Schema: `application/json`: Error. ### GET /v1/sessions/{id} Get Session state Required API key scopes: `tasks:read`. Parameters: - `id` (path, required; string (uuid)) — Session ID. Responses: - `200` — Session. Schema: `application/json`: object { session: Session }. - `400` — A path, query, header, or JSON body value is invalid. Schema: `application/json`: Error. - `401` — Missing, invalid, or expired API key. Schema: `application/json`: Error. - `403` — The API key lacks the required scope, or policy rejected the request. Schema: `application/json`: Error. - `404` — The requested resource was not found in this organization. Schema: `application/json`: Error. - `500` — An unexpected server error occurred. Schema: `application/json`: Error. ### DELETE /v1/sessions/{id} Delete a Session Cancels the active turn, then deletes the Session and its isolated runtime. Webhook delivery remains best-effort. Required API key scopes: `tasks:write`. Parameters: - `id` (path, required; string (uuid)) — Session ID. Responses: - `204` — Session deleted. No response body. - `400` — A path, query, header, or JSON body value is invalid. Schema: `application/json`: Error. - `401` — Missing, invalid, or expired API key. Schema: `application/json`: Error. - `403` — The API key lacks the required scope, or policy rejected the request. Schema: `application/json`: Error. - `404` — The requested resource was not found in this organization. Schema: `application/json`: Error. - `500` — An unexpected server error occurred. Schema: `application/json`: Error. ### GET /v1/sessions/{id}/messages List the durable Session transcript Returns public Messages in transcript order. Use these records, rather than SSE replay, to reconcile authoritative Message status, unresolved HITL actions, response, and error state. Required API key scopes: `tasks:read`. Parameters: - `id` (path, required; string (uuid)) — Session ID. - `limit` (query, optional; integer) — Maximum number of records to return. - `offset` (query, optional; integer) — Number of records to skip. Responses: - `200` — Paginated public Messages. Schema: `application/json`: object { data: array; total: integer; limit: integer; offset: integer }. - `400` — A path, query, header, or JSON body value is invalid. Schema: `application/json`: Error. - `401` — Missing, invalid, or expired API key. Schema: `application/json`: Error. - `403` — The API key lacks the required scope, or policy rejected the request. Schema: `application/json`: Error. - `404` — The requested resource was not found in this organization. Schema: `application/json`: Error. - `500` — An unexpected server error occurred. Schema: `application/json`: Error. ### POST /v1/sessions/{id}/messages Submit a message asynchronously Returns a 202 acceptance projection after the turn is accepted or queued. An idempotent replay may already be terminal; GET the Message for its current authoritative state. The returned message.id is the stable public prompt ID used by SSE and transcript GETs. Multiple input text parts are joined with newline characters into one effective prompt, and transcript reads return that normalized text as one part. Warnings describe only this acceptance attempt and are non-fatal. Required API key scopes: `tasks:write`. Parameters: - `id` (path, required; string (uuid)) — Session ID. - `Idempotency-Key` (header, required; string) — Required. Scoped to the organization and Session. Reusing the key with different message content returns 409. JSON request schema: ```json { "type": "object", "properties": { "parts": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string", "minLength": 1, "maxLength": 100000 } }, "required": [ "type", "text" ], "additionalProperties": false }, "minItems": 1, "maxItems": 32 } }, "required": [ "parts" ], "additionalProperties": false } ``` Responses: - `202` — Message accepted or queued; execution continues asynchronously. Schema: `application/json`: AcceptedMessage. - `400` — A path, query, header, or JSON body value is invalid. Schema: `application/json`: Error. - `401` — Missing, invalid, or expired API key. Schema: `application/json`: Error. - `402` — The selected model or turn requires credits or an active subscription. Schema: `application/json`: Error. - `403` — The API key lacks the required scope, or policy rejected the request. Schema: `application/json`: Error. - `404` — The requested resource was not found in this organization. Schema: `application/json`: Error. - `409` — The request conflicts with the current resource or idempotency state. Schema: `application/json`: Error. - `500` — An unexpected server error occurred. Schema: `application/json`: Error. ### GET /v1/sessions/{id}/messages/{messageId} Get one durable Message The authoritative reconciliation endpoint for a submitted Message, including unresolved HITL actions and terminal response or error state. Required API key scopes: `tasks:read`. Parameters: - `id` (path, required; string (uuid)) — Session ID. - `messageId` (path, required; string (uuid)) — Public Message ID returned by POST /messages. Responses: - `200` — Public Message. Schema: `application/json`: object { message: Message }. - `400` — A path, query, header, or JSON body value is invalid. Schema: `application/json`: Error. - `401` — Missing, invalid, or expired API key. Schema: `application/json`: Error. - `403` — The API key lacks the required scope, or policy rejected the request. Schema: `application/json`: Error. - `404` — The requested resource was not found in this organization. Schema: `application/json`: Error. - `500` — An unexpected server error occurred. Schema: `application/json`: Error. ### POST /v1/sessions/{id}/messages/{messageId}/answer Answer a blocked Message question Answers one human-in-the-loop question emitted as a message.event with data.sourceType tool_ask_user_question. Send data.actionId and the answer value verbatim. Required API key scopes: `tasks:write`. Parameters: - `id` (path, required; string (uuid)) — Session ID. - `messageId` (path, required; string (uuid)) — Public Message ID returned by POST /messages. JSON request schema: ```json { "type": "object", "properties": { "actionId": { "type": "integer", "minimum": 0 }, "answer": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} }, { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "actionId", "answer" ], "additionalProperties": false } ``` Responses: - `200` — Answer recorded; the Message either resumed or is waiting for another blocked action. Schema: `application/json`: object { messageId: string (uuid); actionId: integer; status: "accepted" | "resuming" }. - `400` — A path, query, header, or JSON body value is invalid. Schema: `application/json`: Error. - `401` — Missing, invalid, or expired API key. Schema: `application/json`: Error. - `403` — The API key lacks the required scope, or policy rejected the request. Schema: `application/json`: Error. - `404` — The requested resource was not found in this organization. Schema: `application/json`: Error. - `409` — The action does not exist, does not belong to this Message, or is no longer waiting for an answer. Schema: `application/json`: Error. - `500` — An unexpected server error occurred. Schema: `application/json`: Error. ### GET /v1/sessions/{id}/stream Open the standing Session SSE stream Multiplexes conversation and per-run events. Frames carry channel-scoped wire ids; global ordering and durable Last-Event-ID recovery are not promised in v1. History, initialization buffers, and socket backpressure are bounded; reconnect and reconcile with Message GETs if the connection closes. Each data line decodes to SessionEvent. Required API key scopes: `tasks:read`. Parameters: - `id` (path, required; string (uuid)) — Session ID. Responses: - `200` — Standing SSE stream with heartbeat comments every 15 seconds. Schema: `text/event-stream`: string; decoded `data`: SessionEvent. - `400` — A path, query, header, or JSON body value is invalid. Schema: `application/json`: Error. - `401` — Missing, invalid, or expired API key. Schema: `application/json`: Error. - `403` — The API key lacks the required scope, or policy rejected the request. Schema: `application/json`: Error. - `404` — The requested resource was not found in this organization. Schema: `application/json`: Error. - `500` — An unexpected server error occurred. Schema: `application/json`: Error. ### POST /v1/sessions/{id}/interrupt Interrupt the active turn Required API key scopes: `tasks:write`. Parameters: - `id` (path, required; string (uuid)) — Session ID. Responses: - `200` — Interruption status. Schema: `application/json`: object { status: "interrupting" | "no_turn" }. - `400` — A path, query, header, or JSON body value is invalid. Schema: `application/json`: Error. - `401` — Missing, invalid, or expired API key. Schema: `application/json`: Error. - `403` — The API key lacks the required scope, or policy rejected the request. Schema: `application/json`: Error. - `404` — The requested resource was not found in this organization. Schema: `application/json`: Error. - `500` — An unexpected server error occurred. Schema: `application/json`: Error. ### GET /v1/tasks List API-created Tasks Lists non-deleted Tasks created through the task-based API, newest first. Required scope: `tasks:read`. Required API key scopes: `tasks:read`. Parameters: - `limit` (query, optional; integer) — Maximum records to return. Values above 100 are clamped to 100. - `offset` (query, optional; integer) — Number of records to skip. Responses: - `200` — Paginated API-created Tasks. Schema: `application/json`: LegacyTaskList. - `401` — Missing, invalid, or expired API key. Schema: `application/json`: Error. - `403` — The API key lacks the required scope. Schema: `application/json`: Error. - `500` — An unexpected server error occurred. Schema: `application/json`: Error. ### POST /v1/tasks Create a Task Creates a task-based Agent run. Omit `workspaceId` to create a new Workspace, or supply an existing non-Session Workspace. Required scope: `tasks:write`. Required API key scopes: `tasks:write`. JSON request schema: ```json { "$ref": "#/components/schemas/LegacyCreateTaskRequest" } ``` Responses: - `201` — Task and initial prompt accepted. Schema: `application/json`: LegacyTaskCreated. - `400` — A path, query, or JSON body value is invalid. Schema: `application/json`: Error. - `401` — Missing, invalid, or expired API key. Schema: `application/json`: Error. - `402` — The request requires credits or an active subscription. Schema: `application/json`: Error. - `403` — The API key lacks the required scope. Schema: `application/json`: Error. - `404` — The requested resource was not found in this organization. Schema: `application/json`: Error. - `409` — The selected Workspace is reserved for an Agent API Session. Schema: `application/json`: Error. - `500` — An unexpected server error occurred. Schema: `application/json`: Error. ### GET /v1/tasks/{id} Get a Task Returns Task metadata, derived status, and prompt statuses. Required scope: `tasks:read`. Required API key scopes: `tasks:read`. Parameters: - `id` (path, required; string (uuid)) — API-created Task ID. Responses: - `200` — Task details. Schema: `application/json`: LegacyTask. - `401` — Missing, invalid, or expired API key. Schema: `application/json`: Error. - `403` — The API key lacks the required scope. Schema: `application/json`: Error. - `404` — The requested resource was not found in this organization. Schema: `application/json`: Error. - `500` — An unexpected server error occurred. Schema: `application/json`: Error. ### DELETE /v1/tasks/{id} Delete a Task Soft-deletes an API-created Task. Required scope: `tasks:write`. Required API key scopes: `tasks:write`. Parameters: - `id` (path, required; string (uuid)) — API-created Task ID. Responses: - `204` — Task deleted. No response body. No response body. - `401` — Missing, invalid, or expired API key. Schema: `application/json`: Error. - `403` — The API key lacks the required scope. Schema: `application/json`: Error. - `404` — The requested resource was not found in this organization. Schema: `application/json`: Error. - `500` — An unexpected server error occurred. Schema: `application/json`: Error. ### GET /v1/tasks/{id}/content Get a Task transcript Returns top-level user prompts and final responses. Add `include=events` to include synthesized manager events. Required scope: `tasks:read`. Required API key scopes: `tasks:read`. Parameters: - `id` (path, required; string (uuid)) — API-created Task ID. - `include` (query, optional; "events") — Include the normalized event array for each prompt. Responses: - `200` — Authoritative Task transcript. Schema: `application/json`: LegacyTaskContent. - `401` — Missing, invalid, or expired API key. Schema: `application/json`: Error. - `403` — The API key lacks the required scope. Schema: `application/json`: Error. - `404` — The requested resource was not found in this organization. Schema: `application/json`: Error. - `500` — An unexpected server error occurred. Schema: `application/json`: Error. ### POST /v1/tasks/{id}/prompts Submit a follow-up prompt Submits or queues a follow-up on an existing API-created Task. The optional execution identifiers depend on whether the prompt starts immediately or is queued. Required scope: `tasks:write`. Required API key scopes: `tasks:write`. Parameters: - `id` (path, required; string (uuid)) — API-created Task ID. JSON request schema: ```json { "$ref": "#/components/schemas/LegacyFollowUpRequest" } ``` Responses: - `201` — Follow-up accepted or queued. Schema: `application/json`: LegacyFollowUpAccepted. - `400` — A path, query, or JSON body value is invalid. Schema: `application/json`: Error. - `401` — Missing, invalid, or expired API key. Schema: `application/json`: Error. - `402` — The request requires credits or an active subscription. Schema: `application/json`: Error. - `403` — The API key lacks the required scope. Schema: `application/json`: Error. - `404` — The requested resource was not found in this organization. Schema: `application/json`: Error. - `500` — An unexpected server error occurred. Schema: `application/json`: Error. ### PATCH /v1/tasks/{id}/visibility Change Task visibility Changes the Task Workspace visibility. Public visibility returns a share URL. Required scope: `tasks:write`. Required API key scopes: `tasks:write`. Parameters: - `id` (path, required; string (uuid)) — API-created Task ID. JSON request schema: ```json { "$ref": "#/components/schemas/LegacyVisibilityRequest" } ``` Responses: - `200` — Updated visibility. Schema: `application/json`: LegacyVisibility. - `400` — A path, query, or JSON body value is invalid. Schema: `application/json`: Error. - `401` — Missing, invalid, or expired API key. Schema: `application/json`: Error. - `403` — The API key lacks the required scope. Schema: `application/json`: Error. - `404` — The requested resource was not found in this organization. Schema: `application/json`: Error. - `500` — An unexpected server error occurred. Schema: `application/json`: Error. ### GET /v1/tasks/{id}/events Stream the latest Task prompt Streams the latest visible top-level prompt as SSE. Frames use event name `event` with `LegacyTaskEvent` data and finish with event name `done`; the connection can also end after 15 minutes with status still `running`. Sequence numbers are connection-local, so deduplicate synthesized events by `eventKey`. Required scope: `tasks:read`. Required API key scopes: `tasks:read`. Parameters: - `id` (path, required; string (uuid)) — API-created Task ID. Responses: - `200` — Task execution SSE stream. Schema: `text/event-stream`: string; decoded `data`: LegacyTaskEvent | LegacyTaskStreamDone. - `401` — Missing, invalid, or expired API key. Schema: `application/json`: Error. - `403` — The API key lacks the required scope. Schema: `application/json`: Error. - `404` — The requested resource was not found in this organization. Schema: `application/json`: Error. - `500` — An unexpected server error occurred. Schema: `application/json`: Error. ### GET /v1/tasks/{id}/prompts/{promptId}/events Get sub-prompt events Returns normalized object-storage events for a sub-prompt belonging to this Task. Parent tool events expose the sub-prompt ID. Required scope: `tasks:read`. Required API key scopes: `tasks:read`. Parameters: - `id` (path, required; string (uuid)) — API-created Task ID. - `promptId` (path, required; string (uuid)) — Sub-prompt ID exposed by a parent tool event. - `afterSeq` (query, optional; number) — Return only events with seq greater than this finite number. Responses: - `200` — Sub-prompt events. Schema: `application/json`: LegacySubPromptEvents. - `401` — Missing, invalid, or expired API key. Schema: `application/json`: Error. - `403` — The API key lacks the required scope. Schema: `application/json`: Error. - `404` — The requested resource was not found in this organization. Schema: `application/json`: Error. - `500` — An unexpected server error occurred. Schema: `application/json`: Error. ### POST /v1/tasks/{id}/cancel Cancel a Task Cancels active manager messages, pending prompts, and active sandbox sub-prompts. Required scope: `tasks:write`. Required API key scopes: `tasks:write`. Parameters: - `id` (path, required; string (uuid)) — API-created Task ID. Responses: - `200` — Cancellation result. Schema: `application/json`: LegacyCancelTaskResult. - `401` — Missing, invalid, or expired API key. Schema: `application/json`: Error. - `403` — The API key lacks the required scope. Schema: `application/json`: Error. - `404` — The requested resource was not found in this organization. Schema: `application/json`: Error. - `500` — An unexpected server error occurred. Schema: `application/json`: Error. ### POST /v1/tasks/{id}/answer Answer a blocked Task question Answers the `ask_user_question` identified by the Task event `messageId` and `actionId`, then resumes the same turn. Required scope: `tasks:write`. Required API key scopes: `tasks:write`. Parameters: - `id` (path, required; string (uuid)) — API-created Task ID. JSON request schema: ```json { "$ref": "#/components/schemas/LegacyTaskAnswerRequest" } ``` Responses: - `200` — Answer accepted and Workflow resumed. Schema: `application/json`: LegacyTaskAnswerResult. - `400` — A path, query, or JSON body value is invalid. Schema: `application/json`: Error. - `401` — Missing, invalid, or expired API key. Schema: `application/json`: Error. - `403` — The API key lacks the required scope. Schema: `application/json`: Error. - `404` — The requested resource was not found in this organization. Schema: `application/json`: Error. - `409` — The Task no longer has the identified blocked action. Schema: `application/json`: Error. - `500` — An unexpected server error occurred. Schema: `application/json`: Error. ### POST /v1/files Create a temporary file upload Returns a signed object-storage PUT URL valid for one hour. Upload the bytes separately, then pass `id` and `filename` to a Task request. Required scope: `files:write`. Required API key scopes: `files:write`. JSON request schema: ```json { "$ref": "#/components/schemas/LegacyCreateFileRequest" } ``` Responses: - `201` — Temporary upload reservation. Schema: `application/json`: LegacyFileUpload. - `400` — A path, query, or JSON body value is invalid. Schema: `application/json`: Error. - `401` — Missing, invalid, or expired API key. Schema: `application/json`: Error. - `403` — The API key lacks the required scope. Schema: `application/json`: Error. - `500` — An unexpected server error occurred. Schema: `application/json`: Error. ### GET /v1/webhooks List Webhooks Lists this organization's Webhook registrations. Required scope: `webhooks:read`. Required API key scopes: `webhooks:read`. Responses: - `200` — Webhook registrations. Schema: `application/json`: LegacyWebhookList. - `401` — Missing, invalid, or expired API key. Schema: `application/json`: Error. - `403` — The API key lacks the required scope. Schema: `application/json`: Error. - `500` — An unexpected server error occurred. Schema: `application/json`: Error. ### POST /v1/webhooks Create a Webhook Registers up to three Webhook endpoints per organization. An existing URL is returned idempotently. Lifecycle delivery is best-effort: one attempt, no retry, and failures may be dropped. Required scope: `webhooks:write`. Required API key scopes: `webhooks:write`. JSON request schema: ```json { "$ref": "#/components/schemas/LegacyCreateWebhookRequest" } ``` Responses: - `201` — Webhook registration. Schema: `application/json`: LegacyWebhookCreated. - `400` — The body is invalid or the organization already has three Webhooks. Schema: `application/json`: Error. - `401` — Missing, invalid, or expired API key. Schema: `application/json`: Error. - `403` — The API key lacks the required scope. Schema: `application/json`: Error. - `500` — An unexpected server error occurred. Schema: `application/json`: Error. ### GET /v1/webhooks/{id} Get a Webhook Returns one organization-owned Webhook registration. Required scope: `webhooks:read`. Required API key scopes: `webhooks:read`. Parameters: - `id` (path, required; string) — Webhook registration ID. Responses: - `200` — Webhook registration. Schema: `application/json`: LegacyWebhook. - `401` — Missing, invalid, or expired API key. Schema: `application/json`: Error. - `403` — The API key lacks the required scope. Schema: `application/json`: Error. - `404` — The requested resource was not found in this organization. Schema: `application/json`: Error. - `500` — An unexpected server error occurred. Schema: `application/json`: Error. ### DELETE /v1/webhooks/{id} Delete a Webhook Deletes a Webhook registration. Required scope: `webhooks:write`. Required API key scopes: `webhooks:write`. Parameters: - `id` (path, required; string) — Webhook registration ID. Responses: - `204` — Webhook deleted. No response body. No response body. - `401` — Missing, invalid, or expired API key. Schema: `application/json`: Error. - `403` — The API key lacks the required scope. Schema: `application/json`: Error. - `404` — The requested resource was not found in this organization. Schema: `application/json`: Error. - `500` — An unexpected server error occurred. Schema: `application/json`: Error. ### GET /v1/workspaces/{id}/artifacts List Workspace artifacts Lists files produced in the Workspace artifact store and returns one-hour user-content download URLs. Required scope: `tasks:read`. Required API key scopes: `tasks:read`. Parameters: - `id` (path, required; string (uuid)) — Workspace or Agent Computer ID. Responses: - `200` — Workspace artifacts. Schema: `application/json`: LegacyWorkspaceArtifactList. - `401` — Missing, invalid, or expired API key. Schema: `application/json`: Error. - `403` — The API key lacks the required scope. Schema: `application/json`: Error. - `404` — The requested resource was not found in this organization. Schema: `application/json`: Error. - `500` — An unexpected server error occurred. Schema: `application/json`: Error. ### DELETE /v1/workspaces/{id}/artifacts Delete all Workspace artifacts Deletes every file in the Workspace artifact store. Required scope: `tasks:write`. Required API key scopes: `tasks:write`. Parameters: - `id` (path, required; string (uuid)) — Workspace or Agent Computer ID. Responses: - `204` — All artifacts deleted. No response body. No response body. - `401` — Missing, invalid, or expired API key. Schema: `application/json`: Error. - `403` — The API key lacks the required scope. Schema: `application/json`: Error. - `404` — The requested resource was not found in this organization. Schema: `application/json`: Error. - `500` — An unexpected server error occurred. Schema: `application/json`: Error. ### GET /v1/workspaces/{id}/artifacts/{filename} Download a Workspace artifact Streams one artifact with a Content-Disposition attachment header. Required scope: `tasks:read`. Required API key scopes: `tasks:read`. Parameters: - `id` (path, required; string (uuid)) — Workspace or Agent Computer ID. - `filename` (path, required; string) — Artifact filename, URL encoded as one path segment. Responses: - `200` — Artifact bytes. Content-Type is derived from the filename. Schema: `*/*`: string (binary). - `401` — Missing, invalid, or expired API key. Schema: `application/json`: Error. - `403` — The API key lacks the required scope. Schema: `application/json`: Error. - `404` — The requested resource was not found in this organization. Schema: `application/json`: Error. - `500` — An unexpected server error occurred. Schema: `application/json`: Error. ### DELETE /v1/workspaces/{id}/artifacts/{filename} Delete a Workspace artifact Deletes one artifact after verifying that it exists. Required scope: `tasks:write`. Required API key scopes: `tasks:write`. Parameters: - `id` (path, required; string (uuid)) — Workspace or Agent Computer ID. - `filename` (path, required; string) — Artifact filename, URL encoded as one path segment. Responses: - `204` — Artifact deleted. No response body. No response body. - `401` — Missing, invalid, or expired API key. Schema: `application/json`: Error. - `403` — The API key lacks the required scope. Schema: `application/json`: Error. - `404` — The requested resource was not found in this organization. Schema: `application/json`: Error. - `500` — An unexpected server error occurred. Schema: `application/json`: Error. ### GET /v1/agent-computers List Agent Computers Lists non-deleted organization Workspaces through the Agent Computer projection. The current route does not filter by Workspace kind. List items intentionally omit Microsandbox credentials. Required scope: `tasks:read`. Required API key scopes: `tasks:read`. Parameters: - `limit` (query, optional; integer) — Maximum records to return. The server clamps the value to 1 through 100. - `offset` (query, optional; integer) — Number of records to skip. Responses: - `200` — Paginated Agent Computers. Schema: `application/json`: LegacyAgentComputerList. - `401` — Missing, invalid, or expired API key. Schema: `application/json`: Error. - `403` — The API key lacks the required scope. Schema: `application/json`: Error. - `500` — An unexpected server error occurred. Schema: `application/json`: Error. ### POST /v1/agent-computers Create an Agent Computer Creates a persistent Workspace. Provisioning is asynchronous unless `db9_enabled` is true; the caller can poll GET until `sandboxId` is non-null. The DB9 path waits for provisioning and returns its API key once. Required scope: `tasks:write`. Required API key scopes: `tasks:write`. JSON request schema: ```json { "$ref": "#/components/schemas/LegacyCreateAgentComputerRequest" } ``` Responses: - `201` — Agent Computer created. Schema: `application/json`: LegacyAgentComputerCreated. - `400` — A path, query, or JSON body value is invalid. Schema: `application/json`: Error. - `401` — Missing, invalid, or expired API key. Schema: `application/json`: Error. - `403` — The API key lacks the required scope. Schema: `application/json`: Error. - `404` — The requested resource was not found in this organization. Schema: `application/json`: Error. - `500` — An unexpected server error occurred. Schema: `application/json`: Error. ### GET /v1/agent-computers/{id} Get an Agent Computer Returns details, Microsandbox connection settings, Agent configuration, and up to ten recent Tasks. Required scope: `tasks:read`. Required API key scopes: `tasks:read`. Parameters: - `id` (path, required; string (uuid)) — Workspace or Agent Computer ID. Responses: - `200` — Agent Computer details. Schema: `application/json`: LegacyAgentComputerDetail. - `401` — Missing, invalid, or expired API key. Schema: `application/json`: Error. - `403` — The API key lacks the required scope. Schema: `application/json`: Error. - `404` — The requested resource was not found in this organization. Schema: `application/json`: Error. - `500` — An unexpected server error occurred. Schema: `application/json`: Error. ### PATCH /v1/agent-computers/{id} Configure an Agent Computer Updates its Workspace Agent instructions and/or toggles MCPServerViews by ID. An empty body reads back the current configuration. Required scope: `tasks:write`. Required API key scopes: `tasks:write`. Parameters: - `id` (path, required; string (uuid)) — Workspace or Agent Computer ID. JSON request schema: ```json { "$ref": "#/components/schemas/LegacyUpdateAgentComputerRequest" } ``` Responses: - `200` — Resulting Agent configuration. Schema: `application/json`: LegacyAgentComputerConfiguration. - `400` — The body is invalid or a requested MCPServerView does not belong to this Workspace. Schema: `application/json`: Error. - `401` — Missing, invalid, or expired API key. Schema: `application/json`: Error. - `403` — The API key lacks the required scope. Schema: `application/json`: Error. - `404` — The requested resource was not found in this organization. Schema: `application/json`: Error. - `500` — An unexpected server error occurred. Schema: `application/json`: Error. ### POST /v1/agent-computers/{id}/db9/api-key Mint a DB9 API key Mints a new full-account DB9 key inside a ready, DB9-enabled Agent Computer. The token is returned once and is not stored by the Relay. Required scope: `tasks:write`. Required API key scopes: `tasks:write`. Parameters: - `id` (path, required; string (uuid)) — Workspace or Agent Computer ID. Responses: - `200` — New DB9 API key. Schema: `application/json`: LegacyDb9ApiKey. - `400` — DB9 is not enabled for this Agent Computer. Schema: `application/json`: Error. - `401` — Missing, invalid, or expired API key. Schema: `application/json`: Error. - `403` — The API key lacks the required scope. Schema: `application/json`: Error. - `404` — The Agent Computer does not exist or its VM is not ready. Schema: `application/json`: Error. - `500` — An unexpected server error occurred. Schema: `application/json`: Error. ### POST /v1/agent-computers/{id}/db9/share-token Mint a DB9 share token Mints a new read-write share token for the ready Agent Computer Workspace database. Required scope: `tasks:write`. Required API key scopes: `tasks:write`. Parameters: - `id` (path, required; string (uuid)) — Workspace or Agent Computer ID. Responses: - `200` — New DB9 share token. Schema: `application/json`: LegacyDb9ShareToken. - `400` — DB9 is not enabled for this Agent Computer. Schema: `application/json`: Error. - `401` — Missing, invalid, or expired API key. Schema: `application/json`: Error. - `403` — The API key lacks the required scope. Schema: `application/json`: Error. - `404` — The Agent Computer does not exist or its VM is not ready. Schema: `application/json`: Error. - `500` — An unexpected server error occurred. Schema: `application/json`: Error. ### GET /v1/context-lake/config Get the Context Lake configuration Returns both the serialized YAML and the structured configuration assembled from the organization's datasets and views. Required API key scopes: no named scope (other policy checks may apply). Responses: - `200` — Current Context Lake configuration. Schema: `application/json`: ContextLakeConfigResponse. - `401` — The API key is missing, invalid, expired, or revoked. Schema: `application/json`: Error. - `403` — Context Lake requires an active Pro subscription. This route does not require a named API-key scope. Schema: `application/json`: ContextLakeError. - `500` — Configuration loading failed, or API-key validation failed before the route ran. Schema: `application/json`: Error | ContextLakeError. ### PATCH /v1/context-lake/config Apply an atomic partial configuration update Applies removals, additions, then updates; validates the resulting config; persists it; and redeploys SpiceD. Dataset params and view acceleration objects are shallow replacements, not deep merges. Required API key scopes: no named scope (other policy checks may apply). JSON request schema: ```json { "$ref": "#/components/schemas/ContextLakePatchConfigRequest" } ``` Responses: - `200` — Configuration applied. Schema: `application/json`: ContextLakeMutationResult. - `400` — The requested operations failed or the resulting configuration was invalid. Schema: `application/json`: ContextLakeError. - `401` — The API key is missing, invalid, expired, or revoked. Schema: `application/json`: Error. - `403` — Context Lake requires an active Pro subscription. This route does not require a named API-key scope. Schema: `application/json`: ContextLakeError. - `500` — API-key validation failed before the route ran. Schema: `application/json`: Error | ContextLakeError. ### GET /v1/context-lake/datasets List datasets Required API key scopes: no named scope (other policy checks may apply). Responses: - `200` — Configured datasets. Schema: `application/json`: object { datasets: array }. - `401` — The API key is missing, invalid, expired, or revoked. Schema: `application/json`: Error. - `403` — Context Lake requires an active Pro subscription. This route does not require a named API-key scope. Schema: `application/json`: ContextLakeError. - `500` — Dataset loading failed, or API-key validation failed before the route ran. Schema: `application/json`: Error | ContextLakeError. ### POST /v1/context-lake/datasets Create a dataset Adds a dataset, validates the full configuration, persists it, and redeploys SpiceD. Enabling notifications may also return SQS setup information. Required API key scopes: no named scope (other policy checks may apply). JSON request schema: ```json { "$ref": "#/components/schemas/ContextLakeCreateDatasetRequest" } ``` Responses: - `201` — Dataset created. Schema: `application/json`: ContextLakeCreateDatasetResult. - `400` — The dataset already exists, has invalid connector parameters, or could not be applied. Schema: `application/json`: ContextLakeError. - `401` — The API key is missing, invalid, expired, or revoked. Schema: `application/json`: Error. - `403` — Context Lake requires an active Pro subscription. This route does not require a named API-key scope. Schema: `application/json`: ContextLakeError. - `500` — API-key validation failed before the route ran. Schema: `application/json`: Error | ContextLakeError. ### PUT /v1/context-lake/datasets/{name} Update a dataset Shallow-merges the supplied fields into the named dataset, then validates, persists, and redeploys the full configuration. A supplied params object replaces the previous params object. Required API key scopes: no named scope (other policy checks may apply). Parameters: - `name` (path, required; string) — Dataset or view name. The route performs no additional path-format validation. JSON request schema: ```json { "$ref": "#/components/schemas/ContextLakeUpdateDatasetRequest" } ``` Responses: - `200` — Dataset updated. Schema: `application/json`: ContextLakeMutationResult. - `400` — The dataset was not found, the update was invalid, or the configuration could not be applied. Schema: `application/json`: ContextLakeError. - `401` — The API key is missing, invalid, expired, or revoked. Schema: `application/json`: Error. - `403` — Context Lake requires an active Pro subscription. This route does not require a named API-key scope. Schema: `application/json`: ContextLakeError. - `500` — API-key validation failed before the route ran. Schema: `application/json`: Error | ContextLakeError. ### DELETE /v1/context-lake/datasets/{name} Delete a dataset Removes the named dataset, persists the configuration, and redeploys SpiceD. Required API key scopes: no named scope (other policy checks may apply). Parameters: - `name` (path, required; string) — Dataset or view name. The route performs no additional path-format validation. Responses: - `204` — Dataset deleted. No response body. - `400` — The dataset was not found or the updated configuration could not be applied. Schema: `application/json`: ContextLakeError. - `401` — The API key is missing, invalid, expired, or revoked. Schema: `application/json`: Error. - `403` — Context Lake requires an active Pro subscription. This route does not require a named API-key scope. Schema: `application/json`: ContextLakeError. - `500` — API-key validation failed before the route ran. Schema: `application/json`: Error | ContextLakeError. ### GET /v1/context-lake/views List views Required API key scopes: no named scope (other policy checks may apply). Responses: - `200` — Configured views. Schema: `application/json`: object { views: array }. - `401` — The API key is missing, invalid, expired, or revoked. Schema: `application/json`: Error. - `403` — Context Lake requires an active Pro subscription. This route does not require a named API-key scope. Schema: `application/json`: ContextLakeError. - `500` — View loading failed, or API-key validation failed before the route ran. Schema: `application/json`: Error | ContextLakeError. ### POST /v1/context-lake/views Create a view Adds a view, validates the full configuration, persists it, and redeploys SpiceD. Required API key scopes: no named scope (other policy checks may apply). JSON request schema: ```json { "$ref": "#/components/schemas/ContextLakeCreateViewRequest" } ``` Responses: - `201` — View created. Schema: `application/json`: ContextLakeCreateViewResult. - `400` — The view already exists, is invalid, or could not be applied. Schema: `application/json`: ContextLakeError. - `401` — The API key is missing, invalid, expired, or revoked. Schema: `application/json`: Error. - `403` — Context Lake requires an active Pro subscription. This route does not require a named API-key scope. Schema: `application/json`: ContextLakeError. - `500` — API-key validation failed before the route ran. Schema: `application/json`: Error | ContextLakeError. ### PUT /v1/context-lake/views/{name} Update a view Shallow-merges supplied fields into the named view, then validates, persists, and redeploys the full configuration. A supplied acceleration object replaces the previous object. Required API key scopes: no named scope (other policy checks may apply). Parameters: - `name` (path, required; string) — Dataset or view name. The route performs no additional path-format validation. JSON request schema: ```json { "$ref": "#/components/schemas/ContextLakeUpdateViewRequest" } ``` Responses: - `200` — View updated. Schema: `application/json`: ContextLakeBasicMutationResult. - `400` — The view was not found, the update was invalid, or the configuration could not be applied. Schema: `application/json`: ContextLakeError. - `401` — The API key is missing, invalid, expired, or revoked. Schema: `application/json`: Error. - `403` — Context Lake requires an active Pro subscription. This route does not require a named API-key scope. Schema: `application/json`: ContextLakeError. - `500` — API-key validation failed before the route ran. Schema: `application/json`: Error | ContextLakeError. ### DELETE /v1/context-lake/views/{name} Delete a view Removes the named view, persists the configuration, and redeploys SpiceD. Required API key scopes: no named scope (other policy checks may apply). Parameters: - `name` (path, required; string) — Dataset or view name. The route performs no additional path-format validation. Responses: - `204` — View deleted. No response body. - `400` — The view was not found or the updated configuration could not be applied. Schema: `application/json`: ContextLakeError. - `401` — The API key is missing, invalid, expired, or revoked. Schema: `application/json`: Error. - `403` — Context Lake requires an active Pro subscription. This route does not require a named API-key scope. Schema: `application/json`: ContextLakeError. - `500` — API-key validation failed before the route ran. Schema: `application/json`: Error | ContextLakeError. ### POST /v1/context-lake/sql Run a SQL query Ensures the Context Lake VM is running, waits for SpiceD to become queryable, then proxies the SQL query. The route waits for at most 180 seconds. Required API key scopes: no named scope (other policy checks may apply). JSON request schema: ```json { "$ref": "#/components/schemas/ContextLakeSqlRequest" } ``` Responses: - `200` — SpiceD query result. Schema: `application/json`: ContextLakeSqlResult. - `400` — The query field is missing or SpiceD rejected the query. Schema: `application/json`: ContextLakeError. - `401` — The API key is missing, invalid, expired, or revoked. Schema: `application/json`: Error. - `403` — Context Lake requires an active Pro subscription. This route does not require a named API-key scope. Schema: `application/json`: ContextLakeError. - `500` — The query failed unexpectedly, or API-key validation failed before the route ran. Schema: `application/json`: Error | ContextLakeError. - `504` — The VM did not become queryable within 180 seconds. Schema: `application/json`: ContextLakeTimeoutError. ### GET /v1/context-lake/status Get VM and dataset status Returns the derived VM state and per-dataset health. An unreachable or non-running SpiceD instance is represented as dataset status error rather than failing this request. Required API key scopes: no named scope (other policy checks may apply). Responses: - `200` — Context Lake status. Schema: `application/json`: ContextLakeStatus. - `401` — The API key is missing, invalid, expired, or revoked. Schema: `application/json`: Error. - `403` — Context Lake requires an active Pro subscription. This route does not require a named API-key scope. Schema: `application/json`: ContextLakeError. - `500` — Status loading failed, or API-key validation failed before the route ran. Schema: `application/json`: Error | ContextLakeError. ### POST /v1/context-lake/start Start or provision the Context Lake VM Required API key scopes: no named scope (other policy checks may apply). Responses: - `200` — VM is running. Schema: `application/json`: ContextLakeStartResult. - `401` — The API key is missing, invalid, expired, or revoked. Schema: `application/json`: Error. - `403` — Context Lake requires an active Pro subscription. This route does not require a named API-key scope. Schema: `application/json`: ContextLakeError. - `500` — The VM could not be started, or API-key validation failed before the route ran. Schema: `application/json`: Error | ContextLakeError. ### POST /v1/context-lake/stop Pause the Context Lake VM Succeeds even when no provisioned VM exists. Required API key scopes: no named scope (other policy checks may apply). Responses: - `200` — VM is paused or no VM existed. Schema: `application/json`: ContextLakeBasicMutationResult. - `401` — The API key is missing, invalid, expired, or revoked. Schema: `application/json`: Error. - `403` — Context Lake requires an active Pro subscription. This route does not require a named API-key scope. Schema: `application/json`: ContextLakeError. - `500` — The VM could not be paused, or API-key validation failed before the route ran. Schema: `application/json`: Error | ContextLakeError. ### POST /v1/context-lake/redeploy Redeploy the Context Lake configuration Required API key scopes: no named scope (other policy checks may apply). Responses: - `200` — Configuration redeployed. Schema: `application/json`: ContextLakeBasicMutationResult. - `401` — The API key is missing, invalid, expired, or revoked. Schema: `application/json`: Error. - `403` — Context Lake requires an active Pro subscription. This route does not require a named API-key scope. Schema: `application/json`: ContextLakeError. - `500` — The configuration could not be redeployed, or API-key validation failed before the route ran. Schema: `application/json`: Error | ContextLakeError. ### GET /v1/accounts List partner-created headless accounts Restricted Partner API. Returns headless accounts linked to the caller as their owning partner. Required API key scopes: `accounts:write`. Responses: - `200` — Partner-created headless accounts. Schema: `application/json`: object { accounts: array }. - `401` — The API key is missing, invalid, expired, or revoked. Schema: `application/json`: Error. - `403` — The API key lacks the required scope. Schema: `application/json`: Error. - `500` — API-key validation or the route failed unexpectedly. Schema: `application/json`: Error. ### POST /v1/accounts Create a headless account Restricted Partner API. Creates an API-only child account and returns its plaintext rbk_ API key exactly once. A headless caller cannot create another sub-account. Required API key scopes: `accounts:write`. JSON request schema: ```json { "$ref": "#/components/schemas/CreateHeadlessAccountRequest" } ``` Responses: - `201` — Headless account and one-time API key. Schema: `application/json`: CreateHeadlessAccountResult. - `400` — The JSON request body failed validation. Schema: `application/json`: Error. - `401` — The API key is missing, invalid, expired, or revoked. Schema: `application/json`: Error. - `403` — The API key lacks accounts:write, or a headless account attempted to create a sub-account. Schema: `application/json`: Error. - `500` — API-key validation or the route failed unexpectedly. Schema: `application/json`: Error. ### PATCH /v1/accounts/{id}/billing Change an account billing mode Restricted Partner API. The caller may update itself or an account linked to it as the owning partner. Required API key scopes: `accounts:write`. Parameters: - `id` (path, required; string) — Account ID. The caller may manage only itself or an account linked to it as the owning partner. JSON request schema: ```json { "$ref": "#/components/schemas/UpdateAccountBillingRequest" } ``` Responses: - `200` — Billing mode updated. Schema: `application/json`: UpdateAccountBillingResult. - `400` — The JSON request body failed validation. Schema: `application/json`: Error. - `401` — The API key is missing, invalid, expired, or revoked. Schema: `application/json`: Error. - `403` — The API key lacks accounts:write, or the account is not owned by this partner. Schema: `application/json`: Error. - `404` — The account does not exist. Schema: `application/json`: Error. - `500` — API-key validation or the route failed unexpectedly. Schema: `application/json`: Error. ### GET /v1/billing/credits Get available credits Returns the caller account, the account actually billed after parent-billing resolution, and purchased plus expiring credit balances. Required API key scopes: `tasks:read`. Responses: - `200` — Current credit balances. Schema: `application/json`: BillingCredits. - `401` — The API key is missing, invalid, expired, or revoked. Schema: `application/json`: Error. - `403` — The API key lacks the required scope. Schema: `application/json`: Error. - `500` — API-key validation or the route failed unexpectedly. Schema: `application/json`: Error. ### POST /v1/billing/topups Top up an account Restricted Partner API. externalPaymentId is the idempotency identity within the calling partner: a replay returns 200 and does not add credits twice; a newly processed top-up returns 201. Required API key scopes: `accounts:write`. JSON request schema: ```json { "$ref": "#/components/schemas/CreateBillingTopupRequest" } ``` Responses: - `200` — The external payment was already processed. Schema: `application/json`: ReplayedBillingTopupResult. - `201` — Credits added. Schema: `application/json`: CreatedBillingTopupResult. - `400` — The JSON request body failed validation. Schema: `application/json`: Error. - `401` — The API key is missing, invalid, expired, or revoked. Schema: `application/json`: Error. - `403` — The API key lacks accounts:write, or the target account is not owned by this partner. Schema: `application/json`: Error. - `500` — API-key validation or the route failed unexpectedly. Schema: `application/json`: Error. ### GET /v1/sandbox/api-key Get direct Sandbox gateway credentials Returns the organization's plaintext Microsandbox credential and gateway URL for direct SDK access. The reported expiry is the service's fixed non-expiring compatibility timestamp. Required API key scopes: `tasks:read`. Responses: - `200` — Sandbox gateway credentials. Schema: `application/json`: SandboxApiKeyResult. - `401` — The API key is missing, invalid, expired, or revoked. Schema: `application/json`: Error. - `403` — The API key lacks the required scope. Schema: `application/json`: Error. - `500` — API-key validation or the route failed unexpectedly. Schema: `application/json`: Error. ## Component schemas ### LegacyTaskFileReference ```json { "type": "object", "required": [ "id", "filename" ], "properties": { "id": { "type": "string", "description": "Temporary file ID returned by POST /v1/files." }, "filename": { "type": "string", "description": "Normalized filename returned by POST /v1/files." } }, "additionalProperties": false } ``` ### LegacyCreateTaskRequest ```json { "type": "object", "required": [ "prompt" ], "properties": { "prompt": { "type": "string", "minLength": 1, "maxLength": 100000 }, "workspaceId": { "type": "string", "format": "uuid", "description": "Existing organization Workspace to reuse. Agent API Session Workspaces are rejected." }, "agentProfileId": { "type": "string", "format": "uuid", "description": "Organization Agent Profile copied when a new Workspace is created." }, "githubUrl": { "type": "string" }, "branchName": { "type": "string" }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/LegacyTaskFileReference" } }, "skills": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 300 } } }, "additionalProperties": false } ``` ### LegacyFollowUpRequest ```json { "type": "object", "required": [ "prompt" ], "properties": { "prompt": { "type": "string", "minLength": 1, "maxLength": 100000 }, "skills": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 300 } }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/LegacyTaskFileReference" } } }, "additionalProperties": false } ``` ### LegacyTaskCreated ```json { "type": "object", "required": [ "id", "workspaceId", "url", "status", "createdAt", "promptId", "warnings" ], "properties": { "id": { "type": "string", "format": "uuid" }, "workspaceId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "status": { "type": "string", "const": "running" }, "createdAt": { "type": "string", "format": "date-time" }, "promptId": { "type": "string", "format": "uuid" }, "agentMessageId": { "type": "string" }, "warnings": { "type": "array", "description": "Non-fatal setup warnings; the Task was still accepted.", "items": { "type": "string" } } }, "additionalProperties": false } ``` ### LegacyTaskSummary ```json { "type": "object", "required": [ "id", "url", "title", "createdAt", "completedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": false } ``` ### LegacyTaskList ```json { "type": "object", "required": [ "data", "total", "limit", "offset" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LegacyTaskSummary" } }, "total": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "additionalProperties": false } ``` ### LegacyTaskPromptSummary ```json { "type": "object", "required": [ "id", "status", "submittedAt", "completedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "running", "succeeded", "failed", "canceled" ] }, "submittedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": false } ``` ### LegacyTask ```json { "type": "object", "required": [ "id", "url", "status", "title", "createdAt", "completedAt", "prompts" ], "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "status": { "type": "string", "enum": [ "running", "completed", "failed", "canceled" ] }, "title": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "prompts": { "type": "array", "items": { "$ref": "#/components/schemas/LegacyTaskPromptSummary" } } }, "additionalProperties": false } ``` ### LegacyTaskEvent ```json { "type": "object", "required": [ "seq", "timestamp", "promptId", "eventType", "payload" ], "properties": { "seq": { "type": "integer", "minimum": 0 }, "timestamp": { "type": "number", "description": "Event timestamp in Unix milliseconds." }, "promptId": { "type": "string" }, "eventType": { "type": "string", "enum": [ "init", "thinking", "tool_use", "tool_result", "ask_user_question", "text", "result" ] }, "eventKey": { "type": "string", "description": "Stable identity for deduplication; sequence numbers may change when an event is synthesized later." }, "payload": { "type": "object", "additionalProperties": true } }, "additionalProperties": false } ``` ### LegacyTaskTranscriptPrompt ```json { "type": "object", "required": [ "id", "status", "userPrompt", "response", "submittedAt", "completedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "running", "succeeded", "failed", "canceled", "paused" ] }, "userPrompt": { "type": "string" }, "response": { "type": [ "string", "null" ] }, "submittedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/LegacyTaskEvent" } } }, "additionalProperties": false } ``` ### LegacyTaskContent ```json { "type": "object", "required": [ "id", "status", "prompts" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "running", "completed", "failed", "canceled" ] }, "prompts": { "type": "array", "items": { "$ref": "#/components/schemas/LegacyTaskTranscriptPrompt" } } }, "additionalProperties": false } ``` ### LegacyFollowUpAccepted ```json { "type": "object", "required": [ "promptId", "visibility", "warnings" ], "properties": { "promptId": { "type": "string", "format": "uuid" }, "visibility": { "type": "string", "enum": [ "visible", "pending" ] }, "agentMessageId": { "type": "string" }, "workflowId": { "type": "string" }, "steeringSignaledMessageId": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } ``` ### LegacyVisibilityRequest ```json { "type": "object", "required": [ "visibility" ], "properties": { "visibility": { "type": "string", "enum": [ "private", "shared", "public" ] } }, "additionalProperties": false } ``` ### LegacyVisibility ```json { "type": "object", "required": [ "visibility" ], "properties": { "visibility": { "type": "string", "enum": [ "private", "shared", "public" ] }, "shareUrl": { "type": "string", "format": "uri", "description": "Present when visibility is public." } }, "additionalProperties": false } ``` ### LegacyTaskStreamDone ```json { "type": "object", "required": [ "status", "lastSeq", "finalResult" ], "properties": { "status": { "type": "string", "enum": [ "running", "succeeded", "failed", "canceled" ] }, "lastSeq": { "type": "integer", "minimum": 0 }, "errorMessage": { "type": "string" }, "finalResult": { "type": "string" } }, "additionalProperties": false } ``` ### LegacySubPromptEvents ```json { "type": "object", "required": [ "promptId", "events" ], "properties": { "promptId": { "type": "string" }, "events": { "type": "array", "items": { "type": "object", "required": [ "seq", "eventType", "payload", "timestamp" ], "properties": { "seq": { "type": "number" }, "eventType": { "type": "string" }, "payload": {}, "timestamp": { "type": "number" }, "promptId": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": false } ``` ### LegacyCancelTaskResult ```json { "type": "object", "required": [ "id", "status", "canceledPrompts", "canceledSandboxPrompts" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "const": "canceled" }, "canceledPrompts": { "type": "integer", "minimum": 0 }, "canceledSandboxPrompts": { "type": "integer", "minimum": 0 } }, "additionalProperties": false } ``` ### LegacyTaskAnswerRequest ```json { "type": "object", "required": [ "messageId", "actionId", "answer" ], "properties": { "messageId": { "type": "string", "minLength": 1 }, "actionId": { "type": "number" }, "answer": { "description": "Any JSON value, including null." } }, "additionalProperties": false } ``` ### LegacyTaskAnswerResult ```json { "type": "object", "required": [ "ok", "workflowId" ], "properties": { "ok": { "type": "boolean", "const": true }, "workflowId": { "type": "string" } }, "additionalProperties": false } ``` ### LegacyCreateFileRequest ```json { "type": "object", "required": [ "filename" ], "properties": { "filename": { "type": "string", "minLength": 1, "maxLength": 255 }, "contentType": { "type": "string", "default": "application/octet-stream" } }, "additionalProperties": false } ``` ### LegacyFileUpload ```json { "type": "object", "required": [ "id", "filename", "uploadUrl", "maxFileSize" ], "properties": { "id": { "type": "string", "format": "uuid" }, "filename": { "type": "string" }, "uploadUrl": { "type": "string", "format": "uri", "description": "Signed PUT URL valid for one hour. Upload using the requested Content-Type." }, "maxFileSize": { "type": "integer", "const": 209715200, "description": "Maximum upload size in bytes." } }, "additionalProperties": false } ``` ### LegacyWebhookEvent ```json { "type": "string", "enum": [ "task.created", "task.running", "task.completed", "task.failed", "task.canceled" ] } ``` ### LegacyCreateWebhookRequest ```json { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/LegacyWebhookEvent" } }, "description": { "type": "string", "maxLength": 500 }, "secret": { "type": "string", "maxLength": 500, "writeOnly": true, "description": "Optional value echoed in X-Webhook-Secret on deliveries; never returned." } }, "additionalProperties": false } ``` ### LegacyWebhook ```json { "type": "object", "required": [ "id", "url", "events", "description", "hasSecret", "isActive", "createdAt", "failureCount" ], "properties": { "id": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/LegacyWebhookEvent" } }, "description": { "type": [ "string", "null" ] }, "hasSecret": { "type": "boolean" }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "lastTriggeredAt": { "type": "string", "format": "date-time" }, "failureCount": { "type": "integer", "minimum": 0 } }, "additionalProperties": false } ``` ### LegacyWebhookCreated ```json { "type": "object", "required": [ "id", "url", "events", "description", "hasSecret", "isActive", "createdAt" ], "properties": { "id": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/LegacyWebhookEvent" } }, "description": { "type": [ "string", "null" ] }, "hasSecret": { "type": "boolean" }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false } ``` ### LegacyWebhookList ```json { "type": "object", "required": [ "webhooks" ], "properties": { "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/LegacyWebhook" } } }, "additionalProperties": false } ``` ### LegacyWorkspaceArtifact ```json { "type": "object", "required": [ "name", "size", "contentType", "downloadUrl" ], "properties": { "name": { "type": "string" }, "size": { "type": "integer", "minimum": 0 }, "contentType": { "type": "string" }, "downloadUrl": { "type": "string", "format": "uri", "description": "User-content isolation URL valid for one hour. Re-list for a fresh URL." } }, "additionalProperties": false } ``` ### LegacyWorkspaceArtifactList ```json { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LegacyWorkspaceArtifact" } } }, "additionalProperties": false } ``` ### LegacyAgentComputerViewServer ```json { "type": "object", "required": [ "type", "internalName", "remoteId" ], "properties": { "type": { "type": "string", "enum": [ "internal", "remote" ] }, "internalName": { "type": [ "string", "null" ] }, "remoteId": { "type": [ "string", "null" ] } }, "additionalProperties": false } ``` ### LegacyAgentComputerView ```json { "type": "object", "required": [ "id", "name", "enabled", "server" ], "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "enabled": { "type": "boolean" }, "server": { "$ref": "#/components/schemas/LegacyAgentComputerViewServer" } }, "additionalProperties": false } ``` ### LegacyAgentComputerBase ```json { "type": "object", "required": [ "id", "name", "sandboxId", "icon", "url", "db9Enabled", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "sandboxId": { "type": [ "string", "null" ] }, "icon": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri" }, "db9Enabled": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } ``` ### LegacyAgentComputerSummary ```json { "allOf": [ { "$ref": "#/components/schemas/LegacyAgentComputerBase" } ], "unevaluatedProperties": false } ``` ### LegacyDb9ApiKey ```json { "type": "object", "required": [ "id", "name", "token", "createdAt", "expiresAt" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "token": { "type": "string", "readOnly": true, "description": "Sensitive credential returned once by the mint operation." }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": false } ``` ### LegacyCreateAgentComputerRequest ```json { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "default": "Agent Computer" }, "icon": { "type": "string", "maxLength": 50 }, "agent_instructions": { "type": [ "string", "null" ], "maxLength": 100000 }, "agent_profile_id": { "type": "string", "format": "uuid" }, "db9_enabled": { "type": "boolean", "default": false, "description": "When true, creation waits for provisioning and returns a one-shot DB9 API key." } }, "additionalProperties": false } ``` ### LegacyAgentComputerCreated ```json { "allOf": [ { "$ref": "#/components/schemas/LegacyAgentComputerBase" }, { "type": "object", "required": [ "sandboxBaseUrl", "sandboxApiKey", "agentInstructions", "views" ], "properties": { "sandboxBaseUrl": { "type": "string", "format": "uri" }, "sandboxApiKey": { "type": "string", "readOnly": true, "description": "Sensitive organization-level Microsandbox credential returned to the caller." }, "agentInstructions": { "type": [ "string", "null" ] }, "views": { "type": "array", "items": { "$ref": "#/components/schemas/LegacyAgentComputerView" } }, "db9ApiKey": { "anyOf": [ { "$ref": "#/components/schemas/LegacyDb9ApiKey" }, { "type": "null" } ], "description": "Returned once when db9_enabled is true." } } } ], "unevaluatedProperties": false } ``` ### LegacyAgentComputerList ```json { "type": "object", "required": [ "data", "total", "limit", "offset" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LegacyAgentComputerSummary" } }, "total": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "offset": { "type": "integer", "minimum": 0 } }, "additionalProperties": false } ``` ### LegacyAgentComputerRecentTask ```json { "type": "object", "required": [ "id", "title", "status", "createdAt", "completedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "completed", "failed", "canceled" ] }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": false } ``` ### LegacyAgentComputerDetail ```json { "allOf": [ { "$ref": "#/components/schemas/LegacyAgentComputerBase" }, { "type": "object", "required": [ "sandboxBaseUrl", "sandboxApiKey", "agentInstructions", "views", "taskCount", "recentTasks" ], "properties": { "sandboxBaseUrl": { "type": "string", "format": "uri" }, "sandboxApiKey": { "type": "string", "readOnly": true, "description": "Sensitive organization-level Microsandbox credential returned to the caller." }, "agentInstructions": { "type": [ "string", "null" ] }, "views": { "type": "array", "items": { "$ref": "#/components/schemas/LegacyAgentComputerView" } }, "taskCount": { "type": "integer", "minimum": 0 }, "recentTasks": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/LegacyAgentComputerRecentTask" } } } } ], "unevaluatedProperties": false } ``` ### LegacyUpdateAgentComputerRequest ```json { "type": "object", "properties": { "agent_instructions": { "type": [ "string", "null" ], "maxLength": 100000 }, "views": { "type": "object", "description": "Map of MCPServerView ID to enabled state.", "additionalProperties": { "type": "boolean" } } }, "additionalProperties": false } ``` ### LegacyAgentComputerConfiguration ```json { "type": "object", "required": [ "id", "agentInstructions", "views" ], "properties": { "id": { "type": "string", "format": "uuid" }, "agentInstructions": { "type": [ "string", "null" ] }, "views": { "type": "array", "items": { "$ref": "#/components/schemas/LegacyAgentComputerView" } } }, "additionalProperties": false } ``` ### LegacyDb9ShareToken ```json { "type": "object", "required": [ "token", "expiresAt" ], "properties": { "token": { "type": "string", "readOnly": true, "description": "Sensitive share credential returned by the mint operation." }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": false } ``` ### ContextLakeValidationIssue ```json { "type": "object", "required": [ "path", "message" ], "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": false } ``` ### ContextLakeError ```json { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ContextLakeValidationIssue" } } }, "additionalProperties": false } ``` ### ContextLakeTimeoutError ```json { "type": "object", "required": [ "error", "timeout" ], "properties": { "error": { "type": "string" }, "timeout": { "type": "integer", "const": 180000 } }, "additionalProperties": false } ``` ### ContextLakeDataset ```json { "type": "object", "required": [ "from", "name" ], "properties": { "from": { "type": "string" }, "name": { "type": "string" }, "mode": { "type": "string" }, "params": { "type": "object", "additionalProperties": { "type": "string" } }, "notifications": { "type": "boolean" } }, "additionalProperties": true } ``` ### ContextLakeViewAcceleration ```json { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" }, "engine": { "type": "string" }, "mode": { "type": "string" }, "refresh_mode": { "type": "string" }, "refresh_check_interval": { "type": "string" }, "refresh_retry_enabled": { "type": "boolean" }, "refresh_retry_max_attempts": { "type": "integer" }, "refresh_jitter_enabled": { "type": "boolean" } }, "additionalProperties": true } ``` ### ContextLakeView ```json { "type": "object", "required": [ "name", "sql" ], "properties": { "name": { "type": "string" }, "sql": { "type": "string" }, "acceleration": { "$ref": "#/components/schemas/ContextLakeViewAcceleration" } }, "additionalProperties": true } ``` ### ContextLakeSecret ```json { "type": "object", "required": [ "from", "name" ], "properties": { "from": { "type": "string" }, "name": { "type": "string" }, "params": { "type": "object", "additionalProperties": { "type": "string" } } }, "additionalProperties": true } ``` ### ContextLakeConfig ```json { "type": "object", "required": [ "version", "kind", "name" ], "properties": { "version": { "type": "string" }, "kind": { "type": "string" }, "name": { "type": "string" }, "secrets": { "type": "array", "items": { "$ref": "#/components/schemas/ContextLakeSecret" } }, "runtime": { "type": "object", "additionalProperties": true }, "datasets": { "type": "array", "items": { "$ref": "#/components/schemas/ContextLakeDataset" } }, "views": { "type": "array", "items": { "$ref": "#/components/schemas/ContextLakeView" } }, "x-rebyte": { "type": "object", "properties": { "notifications": { "type": "object", "properties": { "s3_datasets": { "type": "array", "items": { "type": "object", "required": [ "name", "from" ], "properties": { "name": { "type": "string" }, "from": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": true } ``` ### ContextLakeConfigResponse ```json { "type": "object", "required": [ "yaml", "config" ], "properties": { "yaml": { "type": "string" }, "config": { "$ref": "#/components/schemas/ContextLakeConfig" } }, "additionalProperties": false } ``` ### ContextLakeDatasetUpdate ```json { "type": "object", "properties": { "from": { "type": "string" }, "mode": { "type": "string" }, "params": { "type": "object", "additionalProperties": { "type": "string" } }, "notifications": { "type": "boolean" } }, "additionalProperties": true } ``` ### ContextLakeViewUpdate ```json { "type": "object", "properties": { "sql": { "type": "string" }, "acceleration": { "$ref": "#/components/schemas/ContextLakeViewAcceleration" } }, "additionalProperties": true } ``` ### ContextLakePatchConfigRequest ```json { "type": "object", "properties": { "addDatasets": { "type": "array", "items": { "$ref": "#/components/schemas/ContextLakeDataset" } }, "removeDatasets": { "type": "array", "items": { "type": "string" } }, "updateDatasets": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ContextLakeDatasetUpdate" } }, "addViews": { "type": "array", "items": { "$ref": "#/components/schemas/ContextLakeView" } }, "removeViews": { "type": "array", "items": { "type": "string" } }, "updateViews": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ContextLakeViewUpdate" } } }, "additionalProperties": true } ``` ### ContextLakeNotificationInfo ```json { "type": "object", "required": [ "queueArn", "region", "instructions" ], "properties": { "queueArn": { "type": "string" }, "region": { "type": "string" }, "instructions": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } ``` ### ContextLakeBasicMutationResult ```json { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "const": true } }, "additionalProperties": false } ``` ### ContextLakeMutationResult ```json { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "const": true }, "notifications": { "$ref": "#/components/schemas/ContextLakeNotificationInfo" } }, "additionalProperties": false } ``` ### ContextLakeCreateDatasetRequest ```json { "allOf": [ { "$ref": "#/components/schemas/ContextLakeDataset" }, { "type": "object", "required": [ "from", "name" ] } ] } ``` ### ContextLakeUpdateDatasetRequest ```json { "$ref": "#/components/schemas/ContextLakeDatasetUpdate" } ``` ### ContextLakeCreateDatasetResult ```json { "type": "object", "required": [ "ok", "dataset" ], "properties": { "ok": { "type": "boolean", "const": true }, "dataset": { "$ref": "#/components/schemas/ContextLakeDataset" }, "notifications": { "$ref": "#/components/schemas/ContextLakeNotificationInfo" } }, "additionalProperties": false } ``` ### ContextLakeCreateViewRequest ```json { "allOf": [ { "$ref": "#/components/schemas/ContextLakeView" }, { "type": "object", "required": [ "name", "sql" ] } ] } ``` ### ContextLakeUpdateViewRequest ```json { "$ref": "#/components/schemas/ContextLakeViewUpdate" } ``` ### ContextLakeCreateViewResult ```json { "type": "object", "required": [ "ok", "view" ], "properties": { "ok": { "type": "boolean", "const": true }, "view": { "type": "object", "required": [ "name", "sql" ], "properties": { "name": { "type": "string" }, "sql": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false } ``` ### ContextLakeSqlRequest ```json { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "minLength": 1 } }, "additionalProperties": true } ``` ### ContextLakeSqlResult ```json { "type": "object", "required": [ "rows" ], "properties": { "rows": { "description": "The JSON value returned by SpiceD. It is normally an array of row objects." } }, "additionalProperties": false } ``` ### ContextLakeDatasetStatus ```json { "type": "object", "required": [ "ok", "status", "connectorId", "notifications" ], "properties": { "ok": { "type": "boolean" }, "status": { "type": "string", "enum": [ "ready", "error" ] }, "connectorId": { "type": "string" }, "notifications": { "type": "boolean" }, "s3LastEventAt": { "type": [ "string", "null" ], "format": "date-time" }, "s3LastRefreshAt": { "type": [ "string", "null" ], "format": "date-time" }, "s3EventCount": { "type": [ "integer", "null" ] } }, "additionalProperties": false } ``` ### ContextLakeStatus ```json { "type": "object", "required": [ "vmStatus", "datasets" ], "properties": { "vmStatus": { "type": "string", "enum": [ "not_provisioned", "paused", "running", "provisioning" ] }, "datasets": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ContextLakeDatasetStatus" } } }, "additionalProperties": false } ``` ### ContextLakeStartResult ```json { "type": "object", "required": [ "sandboxId", "status" ], "properties": { "sandboxId": { "type": "string" }, "status": { "type": "string", "const": "running" } }, "additionalProperties": false } ``` ### CreateHeadlessAccountRequest ```json { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "billToParent": { "type": "boolean" } }, "additionalProperties": true } ``` ### CreateHeadlessAccountResult ```json { "type": "object", "required": [ "id", "name", "api_key" ], "properties": { "id": { "type": "string", "pattern": "^acct_[A-Za-z0-9_-]{27}$" }, "name": { "type": "string" }, "api_key": { "type": "string", "pattern": "^rbk_[0-9a-f]{40}$", "description": "Plaintext organization API key. Returned only in this response." } }, "additionalProperties": false } ``` ### HeadlessAccount ```json { "type": "object", "required": [ "id", "name", "type", "status", "createdAt" ], "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "status": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false } ``` ### UpdateAccountBillingRequest ```json { "type": "object", "required": [ "billToParent" ], "properties": { "billToParent": { "type": "boolean" } }, "additionalProperties": true } ``` ### UpdateAccountBillingResult ```json { "type": "object", "required": [ "id", "billToParent" ], "properties": { "id": { "type": "string" }, "billToParent": { "type": "boolean" } }, "additionalProperties": false } ``` ### BillingCredits ```json { "type": "object", "required": [ "accountId", "billingOrgId", "balance", "expiringBalance", "expiringAllowance", "totalAvailable", "lifetimePurchased", "lifetimeUsed", "updatedAt" ], "properties": { "accountId": { "type": "string" }, "billingOrgId": { "type": "string" }, "balance": { "type": "integer" }, "expiringBalance": { "type": "integer" }, "expiringAllowance": { "type": "integer" }, "totalAvailable": { "type": "integer" }, "lifetimePurchased": { "type": "integer" }, "lifetimeUsed": { "type": "integer" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": false } ``` ### CreateBillingTopupRequest ```json { "type": "object", "required": [ "accountId", "amount", "externalPaymentId" ], "properties": { "accountId": { "type": "string", "minLength": 1 }, "amount": { "type": "integer", "minimum": 1 }, "externalPaymentId": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 500 }, "metadata": { "type": "object", "additionalProperties": true } }, "additionalProperties": true } ``` ### CreatedBillingTopupResult ```json { "type": "object", "required": [ "success", "accountId", "billingOrgId", "amount", "newBalance", "transactionId" ], "properties": { "success": { "type": "boolean", "const": true }, "accountId": { "type": "string" }, "billingOrgId": { "type": "string" }, "amount": { "type": "integer", "minimum": 1 }, "newBalance": { "type": "integer" }, "transactionId": { "type": [ "string", "null" ], "format": "uuid" } }, "additionalProperties": false } ``` ### ReplayedBillingTopupResult ```json { "type": "object", "required": [ "success", "alreadyProcessed", "accountId", "billingOrgId", "amount", "newBalance", "updatedAt" ], "properties": { "success": { "type": "boolean", "const": true }, "alreadyProcessed": { "type": "boolean", "const": true }, "accountId": { "type": "string" }, "billingOrgId": { "type": "string" }, "amount": { "type": "integer", "minimum": 1 }, "newBalance": { "type": "integer" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": false } ``` ### SandboxApiKeyResult ```json { "type": "object", "required": [ "apiKey", "baseUrl", "expiresAt" ], "properties": { "apiKey": { "type": "string", "minLength": 1, "description": "Plaintext organization Microsandbox API key." }, "baseUrl": { "type": "string", "format": "uri" }, "expiresAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false } ``` ### Agent ```json { "type": "object", "required": [ "id", "object", "name", "instructions", "model", "maxSteps", "mcpServers", "skills" ], "properties": { "id": { "type": "string", "format": "uuid" }, "object": { "type": "string", "const": "agent" }, "name": { "type": "string" }, "instructions": { "type": "string" }, "model": { "type": "string", "enum": [ "deepseek-v4-pro", "glm-5.2", "kimi-k3", "claude-sonnet-5", "claude-opus-5", "gpt-5.6", "gpt-5.4-mini" ] }, "maxSteps": { "type": "integer", "minimum": 1, "maximum": 128 }, "mcpServers": { "type": "array", "items": { "oneOf": [ { "type": "object", "required": [ "kind", "name" ], "properties": { "kind": { "type": "string", "const": "internal" }, "name": { "type": "string", "enum": [ "web_search_&_browse", "sandbox", "skills", "coding_agent", "ask_user_question", "report_builder", "company", "scheduled_tasks", "app_builder_contract", "github", "mock", "statuspage", "clari_copilot", "databricks", "fathom", "front", "gong", "luma", "openai_usage", "productboard", "salesloft", "slab", "ukg_ready", "vanta", "ashby", "freshservice", "sound_studio", "speech_generator", "snowflake", "http_client", "microsoft_excel", "outlook", "outlook_calendar" ] } }, "additionalProperties": false }, { "type": "object", "required": [ "kind", "toolkit" ], "properties": { "kind": { "type": "string", "const": "composio" }, "toolkit": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "kind", "serverId" ], "properties": { "kind": { "type": "string", "const": "custom" }, "serverId": { "type": "string", "format": "uuid" } }, "additionalProperties": false } ], "discriminator": { "propertyName": "kind" } } }, "skills": { "type": "array", "items": { "type": "object", "required": [ "repo", "path" ], "properties": { "repo": { "type": "string" }, "path": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } ``` ### Session ```json { "type": "object", "required": [ "id", "object", "agentId", "title", "status", "latestMessageId", "latestMessageStatus", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "object": { "type": "string", "const": "session" }, "agentId": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "idle", "running", "paused" ] }, "latestMessageId": { "type": [ "string", "null" ], "format": "uuid" }, "latestMessageStatus": { "type": [ "string", "null" ], "enum": [ "queued", "running", "paused", "completed", "failed", "canceled", null ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false } ``` ### UserQuestionOption ```json { "type": "object", "required": [ "label", "description" ], "properties": { "label": { "type": "string" }, "description": { "type": [ "string", "null" ] } }, "additionalProperties": false } ``` ### UserQuestionItem ```json { "type": "object", "required": [ "question", "options", "multiSelect" ], "properties": { "question": { "type": "string" }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/UserQuestionOption" } }, "multiSelect": { "type": "boolean" }, "input": {} }, "additionalProperties": false } ``` ### UserQuestion ```json { "type": "object", "required": [ "question", "options", "multiSelect", "questions" ], "properties": { "question": { "type": "string" }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/UserQuestionOption" } }, "multiSelect": { "type": "boolean" }, "input": {}, "questions": { "type": "array", "minItems": 1, "maxItems": 4, "items": { "$ref": "#/components/schemas/UserQuestionItem" } } }, "additionalProperties": false } ``` ### PendingAction ```json { "type": "object", "required": [ "type", "actionId", "messageId", "question" ], "properties": { "type": { "type": "string", "const": "ask_user_question" }, "actionId": { "type": "integer", "minimum": 0 }, "messageId": { "type": "string", "format": "uuid", "description": "Canonical public Message ID to use in the answer endpoint." }, "question": { "$ref": "#/components/schemas/UserQuestion" } }, "additionalProperties": false } ``` ### Message ```json { "type": "object", "required": [ "id", "object", "sessionId", "status", "parts", "response", "error", "pendingActions", "createdAt", "completedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "object": { "type": "string", "const": "message" }, "sessionId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "queued", "accepted", "running", "paused", "completed", "failed", "canceled" ] }, "parts": { "type": "array", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } }, "additionalProperties": false } }, "response": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "pendingActions": { "type": "array", "description": "Durable unresolved HITL actions. Use these after an SSE disconnect to resume a paused Message.", "items": { "$ref": "#/components/schemas/PendingAction" } }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": false } ``` ### AcceptedMessage ```json { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "object", "required": [ "id", "object", "sessionId", "status", "warnings" ], "properties": { "id": { "type": "string", "format": "uuid" }, "object": { "type": "string", "const": "message" }, "sessionId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "running", "queued" ] }, "warnings": { "type": "array", "description": "Non-fatal setup warnings; the Message was still accepted.", "items": { "type": "string" } } }, "additionalProperties": false } }, "additionalProperties": false } ``` ### SessionEventEnvelope ```json { "type": "object", "required": [ "object", "type", "sessionId", "channel", "messageId", "runId", "createdAt", "data" ], "properties": { "object": { "type": "string", "const": "session.event" }, "type": { "type": "string", "enum": [ "session.connected", "session.event", "message.started", "message.event", "message.completed", "message.failed", "message.canceled", "message.stream_end" ] }, "sessionId": { "type": "string", "format": "uuid" }, "channel": { "type": "string", "enum": [ "conversation", "message" ] }, "messageId": { "type": [ "string", "null" ], "format": "uuid", "description": "Stable public prompt ID used by Message transcript endpoints." }, "runId": { "type": [ "string", "null" ], "format": "uuid", "description": "Internal execution-run correlation ID; distinct from messageId." }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "type": "object" } }, "additionalProperties": false } ``` ### SessionSourceEventData ```json { "type": "object", "required": [ "sourceType", "step", "payload" ], "properties": { "sourceType": { "type": "string" }, "step": { "type": [ "integer", "null" ] }, "payload": { "type": "object", "additionalProperties": true }, "actionId": { "type": "integer", "minimum": 0, "description": "Present when sourceType is tool_ask_user_question; pass this value to the answer endpoint." }, "question": { "$ref": "#/components/schemas/UserQuestion", "description": "Present when sourceType is tool_ask_user_question." } }, "allOf": [ { "if": { "required": [ "sourceType" ], "properties": { "sourceType": { "type": "string", "const": "tool_ask_user_question" } } }, "then": { "required": [ "actionId", "question" ] } } ], "additionalProperties": false } ``` ### SessionSourceEvent ```json { "allOf": [ { "$ref": "#/components/schemas/SessionEventEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SessionSourceEventData" } } } ] } ``` ### SessionConnectedEvent ```json { "allOf": [ { "$ref": "#/components/schemas/SessionEventEnvelope" }, { "type": "object", "properties": { "type": { "type": "string", "const": "session.connected" }, "channel": { "type": "string", "const": "conversation" }, "messageId": { "type": "null" }, "runId": { "type": "null" }, "data": { "type": "object", "required": [ "session" ], "properties": { "session": { "$ref": "#/components/schemas/Session" } }, "additionalProperties": false } } } ] } ``` ### SessionRuntimeEvent ```json { "allOf": [ { "$ref": "#/components/schemas/SessionSourceEvent" }, { "type": "object", "properties": { "type": { "type": "string", "const": "session.event" }, "channel": { "type": "string", "const": "conversation" } } } ] } ``` ### MessageStartedEvent ```json { "allOf": [ { "$ref": "#/components/schemas/SessionSourceEvent" }, { "type": "object", "properties": { "type": { "type": "string", "const": "message.started" }, "channel": { "type": "string", "const": "conversation" }, "messageId": { "type": "string", "format": "uuid" }, "runId": { "type": "string", "format": "uuid" } } } ] } ``` ### MessageRuntimeEvent ```json { "allOf": [ { "$ref": "#/components/schemas/SessionSourceEvent" }, { "type": "object", "properties": { "type": { "type": "string", "const": "message.event" }, "channel": { "type": "string", "const": "message" }, "messageId": { "type": "string", "format": "uuid" }, "runId": { "type": "string", "format": "uuid" } } } ] } ``` ### MessageCompletedEvent ```json { "allOf": [ { "$ref": "#/components/schemas/SessionSourceEvent" }, { "type": "object", "properties": { "type": { "type": "string", "const": "message.completed" }, "channel": { "type": "string", "const": "message" }, "messageId": { "type": "string", "format": "uuid" }, "runId": { "type": "string", "format": "uuid" } } } ] } ``` ### MessageFailedEvent ```json { "allOf": [ { "$ref": "#/components/schemas/SessionSourceEvent" }, { "type": "object", "properties": { "type": { "type": "string", "const": "message.failed" }, "channel": { "type": "string", "const": "message" }, "messageId": { "type": "string", "format": "uuid" }, "runId": { "type": "string", "format": "uuid" } } } ] } ``` ### MessageCanceledEvent ```json { "allOf": [ { "$ref": "#/components/schemas/SessionSourceEvent" }, { "type": "object", "properties": { "type": { "type": "string", "const": "message.canceled" }, "channel": { "type": "string", "const": "message" }, "messageId": { "type": "string", "format": "uuid" }, "runId": { "type": "string", "format": "uuid" } } } ] } ``` ### MessageStreamEndEvent ```json { "allOf": [ { "$ref": "#/components/schemas/SessionSourceEvent" }, { "type": "object", "properties": { "type": { "type": "string", "const": "message.stream_end" }, "channel": { "type": "string", "const": "message" }, "messageId": { "type": "string", "format": "uuid" }, "runId": { "type": "string", "format": "uuid" } } } ] } ``` ### SessionEvent ```json { "type": "object", "required": [ "object", "type", "sessionId", "channel", "messageId", "runId", "createdAt", "data" ], "properties": { "object": { "type": "string", "const": "session.event" }, "type": { "type": "string", "enum": [ "session.connected", "session.event", "message.started", "message.event", "message.completed", "message.failed", "message.canceled", "message.stream_end" ] }, "sessionId": { "type": "string", "format": "uuid" }, "channel": { "type": "string", "enum": [ "conversation", "message" ] }, "messageId": { "type": [ "string", "null" ], "format": "uuid" }, "runId": { "type": [ "string", "null" ], "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "type": "object" } }, "oneOf": [ { "$ref": "#/components/schemas/SessionConnectedEvent" }, { "$ref": "#/components/schemas/SessionRuntimeEvent" }, { "$ref": "#/components/schemas/MessageStartedEvent" }, { "$ref": "#/components/schemas/MessageRuntimeEvent" }, { "$ref": "#/components/schemas/MessageCompletedEvent" }, { "$ref": "#/components/schemas/MessageFailedEvent" }, { "$ref": "#/components/schemas/MessageCanceledEvent" }, { "$ref": "#/components/schemas/MessageStreamEndEvent" } ], "discriminator": { "propertyName": "type", "mapping": { "session.connected": "#/components/schemas/SessionConnectedEvent", "session.event": "#/components/schemas/SessionRuntimeEvent", "message.started": "#/components/schemas/MessageStartedEvent", "message.event": "#/components/schemas/MessageRuntimeEvent", "message.completed": "#/components/schemas/MessageCompletedEvent", "message.failed": "#/components/schemas/MessageFailedEvent", "message.canceled": "#/components/schemas/MessageCanceledEvent", "message.stream_end": "#/components/schemas/MessageStreamEndEvent" } }, "additionalProperties": false } ``` ### Error ```json { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "modelId": { "type": "string" }, "balance": { "type": "number" }, "required": { "type": "number" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } ```