{ "openapi": "3.1.0", "info": { "title": "Introspection API: Data Plane", "description": "Customer data API for tasks, conversations, events, metrics, files, shares, and automations.", "version": "0.1.0" }, "paths": { "/v1/tasks": { "get": { "tags": [ "tasks" ], "summary": "List Tasks", "description": "List tasks for the authenticated project.\n\nRequires scope: `tasks:read`, `read`, or `*`\n\nRows the caller doesn't own (identity tier, else member tier) are excluded.\nThe `tag` filter is ANDed with that ownership predicate, so it only ever\nnarrows. Use the `next` token from the response to fetch subsequent pages.", "operationId": "list_tasks_v1_tasks_get", "security": [ { "HTTPBearer": [ "tasks:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "description": "Maximum number of items per page", "default": 100, "title": "Limit" }, "description": "Maximum number of items per page" }, { "name": "next", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pagination token from previous response", "title": "Next" }, "description": "Pagination token from previous response" }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include total count (expensive for large datasets)", "default": false, "title": "Include Total" }, "description": "Include total count (expensive for large datasets)" }, { "name": "statuses", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/TaskStatus" } }, { "type": "null" } ], "description": "Only include tasks with these statuses", "title": "Statuses" }, "description": "Only include tasks with these statuses" }, { "name": "runtime_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Only include tasks created for this runtime", "title": "Runtime Id" }, "description": "Only include tasks created for this runtime" }, { "name": "runtime_ids", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 100 }, { "type": "null" } ], "description": "Only include tasks created for any of these runtimes (repeatable)", "title": "Runtime Ids" }, "description": "Only include tasks created for any of these runtimes (repeatable)" }, { "name": "updated_after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Only include tasks updated at or after this time", "title": "Updated After" }, "description": "Only include tasks updated at or after this time" }, { "name": "require_automation_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "When true, only tasks linked to an automation (automation_id set) are returned", "title": "Require Automation Id" }, "description": "When true, only tasks linked to an automation (automation_id set) are returned" }, { "name": "automation_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Only include tasks created by this automation", "title": "Automation Id" }, "description": "Only include tasks created by this automation" }, { "name": "member_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Filter by owning member (privileged callers only)", "title": "Member Id" }, "description": "Filter by owning member (privileged callers only)" }, { "name": "conversation_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by the task's conversation id (chat thread → task resolution)", "title": "Conversation Id" }, "description": "Filter by the task's conversation id (chat thread → task resolution)" }, { "name": "conversation_ids", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, { "type": "null" } ], "description": "Only include tasks for any of these conversation ids (repeatable)", "title": "Conversation Ids" }, "description": "Only include tasks for any of these conversation ids (repeatable)" }, { "name": "tag", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by a `key:value` tag, e.g. `customer:acme`", "title": "Tag" }, "description": "Filter by a `key:value` tag, e.g. `customer:acme`" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_Task_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "tasks" ], "summary": "Create Task", "description": "Create a new task.\n\nRuntime + identity resolution is JWT-claim-driven (see\n`docs/design/sdk-api.md`). When the caller authenticates with a\nCP-minted **runner JWT** (`token_type == \"runner\"`), the claims\ncarry the resolved `runtime_id`, optional `experiment_id`, and\n`identity` — DP looks up the recipe pin via the resolver and\nstamps everything onto the task, ignoring any body `runtime_id`.\nA non-runner credential (session/browser, internal service tokens)\ncarries no runtime claim; it may bind a runtime by passing\n`runtime_id` in the body (validated against the caller's project),\notherwise the task runs against the project's default agent path.\n\nProvisions a sandbox. The sandbox reads INTROSPECTION_AGENT_NAME from its\nenvironment to select the managed Pi agent definition.\n\nRequires scope: `tasks:write`, `write`, or `*`", "operationId": "create_task_v1_tasks_post", "security": [ { "HTTPBearer": [ "tasks:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskCreateResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/tasks/{task_id}": { "get": { "tags": [ "tasks" ], "summary": "Get Task", "description": "Get a task by ID.\n\nBy default this is the cheapest read available: a single-row lookup of the\ntask projection from Postgres, with **no** enrichment and **no** Restate\nround-trip. The ``status`` field is maintained on the row by the task\nworkflow, so this is the quick way to check a task's status (e.g. a readiness\npoll or catch-up read) without loading Restate.\n\nAnything that costs more than that bare read is opt-in via ``?include=`` (a\nrepeatable query param, see ``TaskInclude``). ``?include=agent`` enriches an\ninteractive, in-flight task with live sandbox status from the Restate\nworkflow — one extra round-trip — so the interactive task-detail view opts in\nwhile status checks do not. Live, ongoing output belongs on ``/stream`` (SSE);\nthis endpoint never streams.\n\nRequires scope: `tasks:read`, `read`, or `*`", "operationId": "get_task_v1_tasks__task_id__get", "security": [ { "HTTPBearer": [ "tasks:read" ] } ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Task Id" } }, { "name": "include", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/TaskInclude" } }, { "type": "null" } ], "description": "Opt-in non-default enrichments (e.g. `agent` for live sandbox status); repeatable", "title": "Include" }, "description": "Opt-in non-default enrichments (e.g. `agent` for live sandbox status); repeatable" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "tasks" ], "summary": "Update Task", "description": "Update mutable task fields.", "operationId": "update_task_v1_tasks__task_id__patch", "security": [ { "HTTPBearer": [ "tasks:write" ] } ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Task Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "tasks" ], "summary": "Delete Task", "description": "Cancel any active work and soft-delete a task in one operation.\n\nRequires scope: ``tasks:delete``, ``delete``, or ``*``", "operationId": "delete_task_v1_tasks__task_id__delete", "security": [ { "HTTPBearer": [ "tasks:delete" ] } ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Task Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/tasks/{task_id}/runs": { "post": { "tags": [ "tasks" ], "summary": "Create Task Run", "description": "Create a run on an interactive task.\n\nRunning tasks receive steering guidance. Idle/pending tasks receive a prompt.\nCompleted, failed, or unavailable sandboxes are restarted implicitly.\nThis is the existing interactive-task subresource surface; new resources\nshould still use CRUD-shaped routes.", "operationId": "create_task_run_v1_tasks__task_id__runs_post", "security": [ { "HTTPBearer": [ "tasks:write" ] } ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Task Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRunCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRunResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/tasks/{task_id}/runs/{run_id}/cancel": { "post": { "tags": [ "tasks" ], "summary": "Cancel Task Run", "description": "Cancel the current run for an active interactive task.\n\nDefault (including the bodyless call) **aborts**: the in-flight turn is\ninterrupted immediately and the sandbox stays warm, so the task returns to\n``idle`` and the same container is resumable on the next prompt. Pass\n``mode=drain`` to instead let the active turn finish and tear the sandbox\ndown at the next settle boundary so the next prompt cold-boots on the\ncurrent base image — the release/rollover path\n(docs/design/sandbox-drain-on-release.md).", "operationId": "cancel_task_run_v1_tasks__task_id__runs__run_id__cancel_post", "security": [ { "HTTPBearer": [ "tasks:write" ] } ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Task Id" } }, { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Run Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TaskCancelRequest" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskCancelResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/tasks/{task_id}/runs/{run_id}": { "get": { "tags": [ "tasks" ], "summary": "Get Task Run", "description": "Get status for a task run on the existing interactive-task subresource.", "operationId": "get_task_run_v1_tasks__task_id__runs__run_id__get", "security": [ { "HTTPBearer": [ "tasks:read" ] } ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Task Id" } }, { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Run Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRun" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/tasks/{task_id}/runs/{run_id}/stream": { "get": { "tags": [ "tasks" ], "summary": "Stream Task Run", "description": "Stream AG-UI output for one task run.\n\n``wait_for_start`` **defaults to ``true``** — the legacy long-poll: the\nserver holds the stream open, emitting ``queued``/``starting`` lifecycle\nframes, until the run is live. This default exists for backward\ncompatibility with clients that do not send the param (notably the SDKs,\nwhich call the bare endpoint). Pass ``wait_for_start=0`` to opt into the\ntarget \"not ready, retry\" contract: a pre-hardware run first holds up to\nthe advertised ``Retry-After`` window; only if it remains not attachable\ndoes it return ``429`` + ``Retry-After`` + a ``{\"status\": }`` body.\nOur own clients (frontend, capacity harness) send ``0``; the default flips\nto ``0`` (or the param is removed) once every client — including the\nexternal SDKs — has migrated.\n\nThe reconnect resume cursor — the last content-frame seq the client\nreceived (the SSE ``id:`` of worker content frames) — arrives either as\n``since`` (explicit query form, our frontend) or as the SSE-standard\n``Last-Event-ID`` header (the SDKs' ``streamResumable``, see\n``docs/design/sdk-resumable-streams.md``). It is forwarded to the\nruntime-worker so it replays the frames the client missed while\ndisconnected (or emits a ``CUSTOM resume_gap`` frame when the disconnect\noutlived its bounded replay buffer). Non-numeric header values\n(connection-local ``c-…`` control-frame ids) are not cursors and are\nignored.", "operationId": "stream_task_run_v1_tasks__task_id__runs__run_id__stream_get", "security": [ { "HTTPBearer": [ "tasks:read" ] } ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Task Id" } }, { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Run Id" } }, { "name": "wait_for_start", "in": "query", "required": false, "schema": { "type": "boolean", "default": true, "title": "Wait For Start" } }, { "name": "since", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Since" } }, { "name": "last-event-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last-Event-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/tasks/{task_id}/archive": { "post": { "tags": [ "tasks" ], "summary": "Archive Task", "description": "Archive a task, cancelling any active work in the background.\n\nAlways sets ``is_archived = true``. If the task is still active,\nalso cancels the Restate workflow so the sandbox is cleaned up.\n\nRequires scope: ``tasks:write``, ``write``, or ``*``", "operationId": "archive_task_v1_tasks__task_id__archive_post", "security": [ { "HTTPBearer": [ "tasks:write" ] } ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Task Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/tasks/{task_id}/unarchive": { "post": { "tags": [ "tasks" ], "summary": "Unarchive Task", "description": "Unarchive a task so it can accept new runs.", "operationId": "unarchive_task_v1_tasks__task_id__unarchive_post", "security": [ { "HTTPBearer": [ "tasks:write" ] } ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Task Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/automations": { "get": { "tags": [ "automations" ], "summary": "List Automations", "description": "List this project's automations.", "operationId": "list_automations_v1_automations_get", "security": [ { "HTTPBearer": [ "automations:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 100, "title": "Limit" } }, { "name": "next", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next" } }, { "name": "kind", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/AutomationKind" }, { "type": "null" } ], "title": "Kind" } }, { "name": "enabled", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Enabled" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_Automation_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "automations" ], "summary": "Create Automation", "description": "Create an automation.", "operationId": "create_automation_v1_automations_post", "security": [ { "HTTPBearer": [ "automations:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Automation" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/automations/{automation_id}": { "get": { "tags": [ "automations" ], "summary": "Get Automation", "description": "Read one automation.", "operationId": "get_automation_v1_automations__automation_id__get", "security": [ { "HTTPBearer": [ "automations:read" ] } ], "parameters": [ { "name": "automation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Automation Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Automation" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "automations" ], "summary": "Update Automation", "description": "Update an automation. `kind` and `trigger_type` are immutable.", "operationId": "update_automation_v1_automations__automation_id__patch", "security": [ { "HTTPBearer": [ "automations:write" ] } ], "parameters": [ { "name": "automation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Automation Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Automation" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "automations" ], "summary": "Delete Automation", "description": "Soft delete an automation.", "operationId": "delete_automation_v1_automations__automation_id__delete", "security": [ { "HTTPBearer": [ "automations:write" ] } ], "parameters": [ { "name": "automation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Automation Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/automations/{automation_id}/trigger": { "post": { "tags": [ "automations" ], "summary": "Trigger Automation", "description": "Run an automation now.\n\nRetained from the control-plane router it replaces, and synchronous for the\nreason it can now afford to be: the task it creates is local.\n\n⚠️ Every read opens its own short-lived session and closes it. An injected\n`DbReadSession` would pin its pooled connection for the WHOLE request —\nautocommit releases the transaction, not the checkout — and this handler\ngoes on to call the control plane, ClickHouse, Restate and a sandbox\nlaunch. Slow or concurrent manual triggers would exhaust the pool with no\ndatabase work in flight.", "operationId": "trigger_automation_v1_automations__automation_id__trigger_post", "security": [ { "HTTPBearer": [ "automations:write" ] } ], "parameters": [ { "name": "automation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Automation Id" } } ], "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationTriggerResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/tasks/{task_id}/commands": { "post": { "tags": [ "tasks" ], "summary": "Create Task Command", "description": "Record a command and send it to the task's workflow; poll the row (or wait on the read) for the outcome.", "operationId": "create_task_command_v1_tasks__task_id__commands_post", "security": [ { "HTTPBearer": [ "tasks:exec" ] } ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Task Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ExecCommand" }, { "$ref": "#/components/schemas/UploadCommand" }, { "$ref": "#/components/schemas/DownloadCommand" } ], "discriminator": { "propertyName": "kind", "mapping": { "exec": "#/components/schemas/ExecCommand", "upload": "#/components/schemas/UploadCommand", "download": "#/components/schemas/DownloadCommand" } }, "title": "Body" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskCommand" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "tasks" ], "summary": "List Task Commands", "operationId": "list_task_commands_v1_tasks__task_id__commands_get", "security": [ { "HTTPBearer": [ "tasks:exec" ] } ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Task Id" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/TaskCommandStatus" }, { "type": "null" } ], "title": "Status" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Limit" } }, { "name": "next", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_TaskCommand_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/tasks/{task_id}/commands/{command_id}": { "get": { "tags": [ "tasks" ], "summary": "Get Task Command", "description": "Read a command; ``wait_seconds`` turns the poll into a bounded long read.\n\nEach read is its own short session (the connection is released between\npolls), so a waiting read never pins a pooled connection for the wait.", "operationId": "get_task_command_v1_tasks__task_id__commands__command_id__get", "security": [ { "HTTPBearer": [ "tasks:exec" ] } ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Task Id" } }, { "name": "command_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Command Id" } }, { "name": "wait_seconds", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 60, "minimum": 0, "description": "Hold the read up to this long for the command to finish; returns whatever state it is in at the end", "default": 0, "title": "Wait Seconds" }, "description": "Hold the read up to this long for the command to finish; returns whatever state it is in at the end" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskCommand" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/files/{file_id}/versions": { "get": { "tags": [ "files" ], "summary": "List File Versions", "description": "List all versions of a file, newest first.\n\nRequires scope: `files:read`, `read`, or `*`\n\nUse the `next` token from the response to fetch subsequent pages.", "operationId": "list_file_versions_v1_files__file_id__versions_get", "security": [ { "HTTPBearer": [ "files:read" ] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "File Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "description": "Maximum number of items per page", "default": 100, "title": "Limit" }, "description": "Maximum number of items per page" }, { "name": "next", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pagination token from previous response", "title": "Next" }, "description": "Pagination token from previous response" }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include total count (expensive for large datasets)", "default": false, "title": "Include Total" }, "description": "Include total count (expensive for large datasets)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_File_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "files" ], "summary": "Create File Version", "description": "Create a file version up to 50 MB (owner-only).", "operationId": "create_file_version_v1_files__file_id__versions_post", "security": [ { "HTTPBearer": [ "files:write" ] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "File Id" } } ], "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/files/{file_id}/versions/{file_version_id}": { "get": { "tags": [ "files" ], "summary": "Get File Version", "description": "Get a stable file-version row from a file's version chain.", "operationId": "get_file_version_v1_files__file_id__versions__file_version_id__get", "security": [ { "HTTPBearer": [ "files:read" ] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "File Id" } }, { "name": "file_version_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "File Version Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/files": { "get": { "tags": [ "files" ], "summary": "List Files", "description": "List files for the authenticated project.\n\nRequires scope: `files:read`, `read`, or `*`\n\nFilters cover semantic category, content format, name, ownership,\nconversation, version history, tags, and creation/update windows. The tag\nand ownership filters only narrow rows the caller could already read.\nRows the caller doesn't own and aren't shared with them are excluded.\nUse the `next` token from the response to fetch subsequent pages.", "operationId": "list_files_v1_files_get", "security": [ { "HTTPBearer": [ "files:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "description": "Maximum number of items per page", "default": 100, "title": "Limit" }, "description": "Maximum number of items per page" }, { "name": "next", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pagination token from previous response", "title": "Next" }, "description": "Pagination token from previous response" }, { "name": "share_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string", "format": "uuid" } }, { "type": "null" } ], "description": "Include files granted by these /v1/shares capabilities (one or many)", "title": "Share Id" }, "description": "Include files granted by these /v1/shares capabilities (one or many)" }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include total count (expensive for large datasets)", "default": false, "title": "Include Total" }, "description": "Include total count (expensive for large datasets)" }, { "name": "include_versions", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include superseded file versions. Defaults to latest versions only.", "default": false, "title": "Include Versions" }, "description": "Include superseded file versions. Defaults to latest versions only." }, { "name": "name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by file name", "title": "Name" }, "description": "Filter by file name" }, { "name": "name_contains", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Case-insensitive file name search", "title": "Name Contains" }, "description": "Case-insensitive file name search" }, { "name": "file_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by file type (upload, filesystem, other)", "title": "File Type" }, "description": "Filter by file type (upload, filesystem, other)" }, { "name": "category", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "memory", "output", "file" ], "type": "string" }, { "type": "null" } ], "description": "Filter by semantic file category", "title": "Category" }, "description": "Filter by semantic file category" }, { "name": "content_format", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "markdown", "json", "yaml", "pdf", "image", "audio", "video", "csv", "text", "archive" ], "type": "string" }, { "type": "null" } ], "description": "Filter by friendly content format", "title": "Content Format" }, "description": "Filter by friendly content format" }, { "name": "versioned", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Filter to files with or without version history", "title": "Versioned" }, "description": "Filter to files with or without version history" }, { "name": "storage_path", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by storage path", "title": "Storage Path" }, "description": "Filter by storage path" }, { "name": "task_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Filter by originating task (accounting view)", "title": "Task Id" }, "description": "Filter by originating task (accounting view)" }, { "name": "conversation_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by linked conversation or task ID", "title": "Conversation Id" }, "description": "Filter by linked conversation or task ID" }, { "name": "member_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Filter by owning member (privileged callers only)", "title": "Member Id" }, "description": "Filter by owning member (privileged callers only)" }, { "name": "tag", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by a `key:value` tag, e.g. `customer:acme`", "title": "Tag" }, "description": "Filter by a `key:value` tag, e.g. `customer:acme`" }, { "name": "created_after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter by creation time, inclusive", "title": "Created After" }, "description": "Filter by creation time, inclusive" }, { "name": "created_before", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter by creation time, exclusive", "title": "Created Before" }, "description": "Filter by creation time, exclusive" }, { "name": "updated_after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter by update time, inclusive", "title": "Updated After" }, "description": "Filter by update time, inclusive" }, { "name": "updated_before", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter by update time, exclusive", "title": "Updated Before" }, "description": "Filter by update time, exclusive" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_File_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "files" ], "summary": "Upload File", "description": "Create a file.\n\nMultipart requests upload a new binary file. JSON requests create or\nversion text content by name. File content is limited to 50 MB.\n\nRequires scope: `files:write`, `write`, or `*`", "operationId": "upload_file_v1_files_post", "security": [ { "HTTPBearer": [ "files:write" ] } ], "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } } } } } }, "/v1/files/{file_id}": { "get": { "tags": [ "files" ], "summary": "Get File", "description": "Get a file by ID.\n\nWithout `share_id` the file is fetched against the caller's own JWT\ncredentials (owner/member/identity). With a valid `share_id` that grants this\ncaller access to this file, ownership is overridden for this read only.\n\nRequires scope: `files:read`, `read`, or `*`", "operationId": "get_file_v1_files__file_id__get", "security": [ { "HTTPBearer": [ "files:read" ] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "File Id" } }, { "name": "share_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Read via a /v1/shares grant for this file", "title": "Share Id" }, "description": "Read via a /v1/shares grant for this file" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "files" ], "summary": "Update File", "description": "Update a file.\n\nRequires scope: `files:write`, `write`, or `*`", "operationId": "update_file_v1_files__file_id__patch", "security": [ { "HTTPBearer": [ "files:write" ] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "File Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "files" ], "summary": "Delete File", "description": "Soft delete a file.\n\nRequires scope: `files:delete`, `delete`, or `*`", "operationId": "delete_file_v1_files__file_id__delete", "security": [ { "HTTPBearer": [ "files:delete" ] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "File Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/files/{file_id}/content": { "get": { "tags": [ "files" ], "summary": "Get File Content", "description": "Get a file's content.\n\nRequires scope: `files:read`, `read`, or `*`\n\nReturns the raw file bytes with appropriate content-type header.", "operationId": "get_file_content_v1_files__file_id__content_get", "security": [ { "HTTPBearer": [ "files:read" ] } ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "File Id" } }, { "name": "share_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Read via a /v1/shares grant for this file", "title": "Share Id" }, "description": "Read via a /v1/shares grant for this file" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/shares": { "get": { "tags": [ "shares" ], "summary": "List Shares", "description": "List sharing grants the caller created or that target them (privileged sees all).\n\nRequires scope: `shares:read`.", "operationId": "list_shares_v1_shares_get", "security": [ { "HTTPBearer": [ "shares:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "description": "Maximum items per page", "default": 100, "title": "Limit" }, "description": "Maximum items per page" }, { "name": "next", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pagination token from previous response", "title": "Next" }, "description": "Pagination token from previous response" }, { "name": "resource_type", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/ShareResourceType" }, { "type": "null" } ], "description": "Filter by resource family", "title": "Resource Type" }, "description": "Filter by resource family" }, { "name": "resource_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by a specific resource id", "title": "Resource Id" }, "description": "Filter by a specific resource id" }, { "name": "created_by_me", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Only shares the caller created", "default": false, "title": "Created By Me" }, "description": "Only shares the caller created" }, { "name": "granted_to_me", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Only shares targeting the caller", "default": false, "title": "Granted To Me" }, "description": "Only shares targeting the caller" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_ResourceShare_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "shares" ], "summary": "Create Share", "description": "Create a read-sharing grant. The caller must own the target resource.\n\nRequires scope: `shares:write`.", "operationId": "create_share_v1_shares_post", "security": [ { "HTTPBearer": [ "shares:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceShare" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/shares/{share_id}": { "get": { "tags": [ "shares" ], "summary": "Get Share", "description": "Read a single sharing grant.\n\nReturns the grant with a fully-qualified `url` to the shared resource. With\n`?redirect=true`, responds `302` to that resource instead. Scope: `shares:read`.", "operationId": "get_share_v1_shares__share_id__get", "security": [ { "HTTPBearer": [ "shares:read" ] } ], "parameters": [ { "name": "share_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Share Id" } }, { "name": "redirect", "in": "query", "required": false, "schema": { "type": "boolean", "description": "302-redirect to the shared resource instead of returning the grant", "default": false, "title": "Redirect" }, "description": "302-redirect to the shared resource instead of returning the grant" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceShare" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "shares" ], "summary": "Delete Share", "description": "Revoke a sharing grant. Only the grantor or a privileged caller may revoke.\n\nRequires scope: `shares:delete`.", "operationId": "delete_share_v1_shares__share_id__delete", "security": [ { "HTTPBearer": [ "shares:delete" ] } ], "parameters": [ { "name": "share_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Share Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/metrics": { "post": { "tags": [ "metrics" ], "summary": "Query Metrics", "description": "Execute one bounded metrics query for the authenticated project.", "operationId": "query_metrics_v1_metrics_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricQueryRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricQueryResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [ "metrics:read" ] } ] } }, "/v1/conversations": { "get": { "tags": [ "conversations" ], "summary": "List Conversations", "description": "List GenAI conversations with filtering and pagination.\n\nRequires scope: `conversations:read`, `read`, or `*`\n\nReturns aggregated conversation summaries from ClickHouse traces.\nA conversation may contain multiple traces linked by conversation ID, and\nthe summary aggregates metrics across those traces.\n\n**Ownership:**\nNon-privileged callers see only their own conversations (owner-key scoped,\nsame predicate as item/detail reads). Valid `share_id` capabilities widen\nthe page with the conversations those shares grant.\n\n**Pagination:**\nUse the `next` token from the response to fetch subsequent pages.\nThe token encodes the cursor position and must be passed unchanged.\n\n**Filtering:**\nAll filters are optional and combined with AND logic.\nDate range filters are inclusive.", "operationId": "list_conversations_v1_conversations_get", "security": [ { "HTTPBearer": [ "conversations:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "description": "Maximum items per page", "default": 100, "title": "Limit" }, "description": "Maximum items per page" }, { "name": "next", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pagination token from previous response", "title": "Next" }, "description": "Pagination token from previous response" }, { "name": "share_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string", "format": "uuid" } }, { "type": "null" } ], "description": "Include conversations granted by these /v1/shares capabilities (one or many)", "title": "Share Id" }, "description": "Include conversations granted by these /v1/shares capabilities (one or many)" }, { "name": "conversation_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter: conversation ID (exact match)", "title": "Conversation Id" }, "description": "Filter: conversation ID (exact match)" }, { "name": "conversation_ids", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, { "type": "null" } ], "description": "Filter: conversation IDs (exact match, repeatable)", "title": "Conversation Ids" }, "description": "Filter: conversation IDs (exact match, repeatable)" }, { "name": "trace_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by a trace contained in the conversation", "title": "Trace Id" }, "description": "Filter by a trace contained in the conversation" }, { "name": "annotation_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Read the trace assigned by this annotation", "title": "Annotation Id" }, "description": "Read the trace assigned by this annotation" }, { "name": "sort", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ConversationSortField", "description": "Summary field to order by", "default": "created" }, "description": "Summary field to order by" }, { "name": "direction", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/SortDirection", "description": "Sort direction", "default": "desc" }, "description": "Sort direction" }, { "name": "model", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter: requested model on any span (exact match)", "title": "Model" }, "description": "Filter: requested model on any span (exact match)" }, { "name": "agent_name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter: agent name (exact match)", "title": "Agent Name" }, "description": "Filter: agent name (exact match)" }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/SpanStatus" }, { "type": "null" } ], "description": "Filter: status (Ok/Error)", "title": "Status" }, "description": "Filter: status (Ok/Error)" }, { "name": "service_name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter: OTel service name (exact match)", "title": "Service Name" }, "description": "Filter: OTel service name (exact match)" }, { "name": "service_names", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Filter: OTel service names (exact match)", "title": "Service Names" }, "description": "Filter: OTel service names (exact match)" }, { "name": "environment", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter: runtime environment lane", "title": "Environment" }, "description": "Filter: runtime environment lane" }, { "name": "runtime_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Filter: runtime version ID", "title": "Runtime Id" }, "description": "Filter: runtime version ID" }, { "name": "runtime_group_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Filter: stable runtime group ID", "title": "Runtime Group Id" }, "description": "Filter: stable runtime group ID" }, { "name": "experiment_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Filter: experiment ID", "title": "Experiment Id" }, "description": "Filter: experiment ID" }, { "name": "recipe_git_commit_sha", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter: recipe git commit SHA", "title": "Recipe Git Commit Sha" }, "description": "Filter: recipe git commit SHA" }, { "name": "resolution", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "resolved", "blocked", "unresolved", "pending" ], "type": "string" }, { "type": "null" } ], "description": "Filter: synthesized task resolution", "title": "Resolution" }, "description": "Filter: synthesized task resolution" }, { "name": "sentiment", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "positive", "negative", "mixed", "neutral" ], "type": "string" }, { "type": "null" } ], "description": "Filter: synthesized user sentiment", "title": "Sentiment" }, "description": "Filter: synthesized user sentiment" }, { "name": "owner_key", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter: owner key (`user:`/`anon:`/`member:` prefixed)", "title": "Owner Key" }, "description": "Filter: owner key (`user:`/`anon:`/`member:` prefixed)" }, { "name": "metadata", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Filter: customer-defined metadata as `key:value` (e.g. `flow:company`). Matches a conversation carrying the pair on any of its spans, stamped at ingest via the `introspection.metadata.` span attribute. Split on the first colon, so a value may contain colons. Repeat the parameter to require several dimensions at once (`?metadata=flow:company&metadata=tenant:acme`); repeated pairs are ANDed and must co-occur on the same span, whereas a single pair matches if any span carries it. Keys must be distinct. Narrows only — metadata never grants access.", "title": "Metadata" }, "description": "Filter: customer-defined metadata as `key:value` (e.g. `flow:company`). Matches a conversation carrying the pair on any of its spans, stamped at ingest via the `introspection.metadata.` span attribute. Split on the first colon, so a value may contain colons. Repeat the parameter to require several dimensions at once (`?metadata=flow:company&metadata=tenant:acme`); repeated pairs are ANDed and must co-occur on the same span, whereas a single pair matches if any span carries it. Keys must be distinct. Narrows only — metadata never grants access." }, { "name": "start_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Start of date range (inclusive)", "title": "Start Date" }, "description": "Start of date range (inclusive)" }, { "name": "end_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "End of date range (inclusive)", "title": "End Date" }, "description": "End of date range (inclusive)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_Conversation_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/conversations/{conversation_id}/turns": { "get": { "tags": [ "conversations" ], "summary": "List Conversation Turns", "description": "List lightweight user/assistant messages grouped by agent-scoped trace.", "operationId": "list_conversation_turns_v1_conversations__conversation_id__turns_get", "security": [ { "HTTPBearer": [ "conversations:read" ] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Conversation Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Maximum turns per page", "default": 25, "title": "Limit" }, "description": "Maximum turns per page" }, { "name": "next", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque cursor for the next older page", "title": "Next" }, "description": "Opaque cursor for the next older page" }, { "name": "agent", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "description": "'root' or one exact agent id", "default": "root", "title": "Agent" }, "description": "'root' or one exact agent id" }, { "name": "before_trace_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Return turns strictly before this trace", "title": "Before Trace Id" }, "description": "Return turns strictly before this trace" }, { "name": "trace_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by one exact trace id", "title": "Trace Id" }, "description": "Filter by one exact trace id" }, { "name": "lookback_days", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 365, "minimum": 1 }, { "type": "null" } ], "description": "Partition lookback bound", "title": "Lookback Days" }, "description": "Partition lookback bound" }, { "name": "share_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Read via a /v1/shares grant for this conversation", "title": "Share Id" }, "description": "Read via a /v1/shares grant for this conversation" }, { "name": "annotation_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Read via an assigned annotation on this conversation", "title": "Annotation Id" }, "description": "Read via an assigned annotation on this conversation" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationTurnList" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/conversations/{conversation_id}/items": { "get": { "tags": [ "conversations" ], "summary": "List Conversation Items", "description": "List conversation items with OpenAI-style pagination.\n\nWithout `share_id`, scoped to the caller's own conversations (JWT\ncredentials). A valid `share_id` granting this conversation overrides\nownership for this read only.", "operationId": "list_conversation_items_v1_conversations__conversation_id__items_get", "security": [ { "HTTPBearer": [ "conversations:read" ] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Conversation Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "description": "Maximum items per page", "default": 100, "title": "Limit" }, "description": "Maximum items per page" }, { "name": "next", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque cursor for the next page", "title": "Next" }, "description": "Opaque cursor for the next page" }, { "name": "include", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/ConversationItemInclude" } }, { "type": "null" } ], "description": "Optional item expansions", "title": "Include" }, "description": "Optional item expansions" }, { "name": "agent", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent selector: 'root' returns depth-zero items; an exact id returns that agent; omit for all", "title": "Agent" }, "description": "Agent selector: 'root' returns depth-zero items; an exact id returns that agent; omit for all" }, { "name": "service_name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter items by service name (exact match)", "title": "Service Name" }, "description": "Filter items by service name (exact match)" }, { "name": "operation_name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter items by operation name (exact match)", "title": "Operation Name" }, "description": "Filter items by operation name (exact match)" }, { "name": "trace_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter items by trace id (exact match)", "title": "Trace Id" }, "description": "Filter items by trace id (exact match)" }, { "name": "span_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter items by span id (exact match)", "title": "Span Id" }, "description": "Filter items by span id (exact match)" }, { "name": "lookback_days", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 365, "minimum": 1 }, { "type": "null" } ], "description": "Filter items to partitions from today minus this many days", "title": "Lookback Days" }, "description": "Filter items to partitions from today minus this many days" }, { "name": "share_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Read via a /v1/shares grant for this conversation", "title": "Share Id" }, "description": "Read via a /v1/shares grant for this conversation" }, { "name": "annotation_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Read via an assigned annotation on this conversation", "title": "Annotation Id" }, "description": "Read via an assigned annotation on this conversation" }, { "name": "from_compaction", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Resume the read from the latest compaction boundary: only the compacted summary and everything after it, in ascending order. Falls back to the full conversation when no boundary is recorded.", "default": false, "title": "From Compaction" }, "description": "Resume the read from the latest compaction boundary: only the compacted summary and everything after it, in ascending order. Falls back to the full conversation when no boundary is recorded." }, { "name": "start_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Lower bound (inclusive) on item timestamp", "title": "Start Date" }, "description": "Lower bound (inclusive) on item timestamp" }, { "name": "end_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Upper bound (inclusive) on item timestamp", "title": "End Date" }, "description": "Upper bound (inclusive) on item timestamp" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenAiSpanList" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/conversations/{conversation_id}/export": { "get": { "tags": [ "conversations" ], "summary": "Export Conversation", "description": "Stream one complete, decrypted conversation in JSON, Arrow, or trajectory format.", "operationId": "export_conversation_v1_conversations__conversation_id__export_get", "security": [ { "HTTPBearer": [ "conversations:read" ] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Conversation Id" } }, { "name": "agent", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent selector: 'root' returns depth-zero items; an exact id returns that agent; omit for all", "title": "Agent" }, "description": "Agent selector: 'root' returns depth-zero items; an exact id returns that agent; omit for all" }, { "name": "service_name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter items by service name (exact match)", "title": "Service Name" }, "description": "Filter items by service name (exact match)" }, { "name": "operation_name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter items by operation name (exact match)", "title": "Operation Name" }, "description": "Filter items by operation name (exact match)" }, { "name": "lookback_days", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 365, "minimum": 1 }, { "type": "null" } ], "description": "Partition lookback bound", "title": "Lookback Days" }, "description": "Partition lookback bound" }, { "name": "share_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Read via a /v1/shares grant for this conversation", "title": "Share Id" }, "description": "Read via a /v1/shares grant for this conversation" }, { "name": "from_compaction", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Export only from the latest compaction boundary onward — the compacted summary and everything after it, resumed forward from the boundary. Falls back to the full conversation when no boundary is recorded.", "default": false, "title": "From Compaction" }, "description": "Export only from the latest compaction boundary onward — the compacted summary and everything after it, resumed forward from the boundary. Falls back to the full conversation when no boundary is recorded." }, { "name": "start_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Lower bound (inclusive) on item timestamp", "title": "Start Date" }, "description": "Lower bound (inclusive) on item timestamp" }, { "name": "end_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Upper bound (inclusive) on item timestamp", "title": "End Date" }, "description": "Upper bound (inclusive) on item timestamp" } ], "responses": { "200": { "description": "Complete conversation export, including managed Recipe replay", "content": { "application/vnd.apache.arrow.stream": {}, "application/vnd.introspection.conversation-replay+json;version=1": {}, "application/vnd.letta.trajectory+json;version=1": {} } }, "406": { "description": "Unsupported or ambiguous export representation" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/conversations/{conversation_id}/items/{item_id}": { "get": { "tags": [ "conversations" ], "summary": "Get Conversation Item", "description": "Fetch a single conversation item.\n\nA valid `share_id` granting this conversation overrides ownership for this\nread only; otherwise the caller's JWT credentials apply.", "operationId": "get_conversation_item_v1_conversations__conversation_id__items__item_id__get", "security": [ { "HTTPBearer": [ "conversations:read" ] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Conversation Id" } }, { "name": "item_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Item Id" } }, { "name": "include", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/ConversationItemInclude" } }, { "type": "null" } ], "description": "Optional item expansions", "title": "Include" }, "description": "Optional item expansions" }, { "name": "share_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Read via a /v1/shares grant for this conversation", "title": "Share Id" }, "description": "Read via a /v1/shares grant for this conversation" }, { "name": "annotation_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Read via an assigned annotation on this conversation", "title": "Annotation Id" }, "description": "Read via an assigned annotation on this conversation" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenAiSpan" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/conversations/{conversation_id}": { "get": { "tags": [ "conversations" ], "summary": "Get Conversation Summary", "description": "Fetch one conversation summary by exact ID within telemetry retention.\n\nWithout `share_id`, scoped to the caller's own conversations (JWT\ncredentials). A valid `share_id` granting this conversation overrides\nownership for this read only.", "operationId": "get_conversation_summary_v1_conversations__conversation_id__get", "security": [ { "HTTPBearer": [ "conversations:read" ] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Conversation Id" } }, { "name": "share_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Read via a /v1/shares grant for this conversation", "title": "Share Id" }, "description": "Read via a /v1/shares grant for this conversation" }, { "name": "annotation_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Read via an assigned annotation on this conversation", "title": "Annotation Id" }, "description": "Read via an assigned annotation on this conversation" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/events": { "get": { "tags": [ "events" ], "summary": "List Events", "description": "List one family's events with cursor pagination. Filters combine with AND.\n\nRequires scope: `events:read`, `read`, or `*`.", "operationId": "list_events_v1_events_get", "security": [ { "HTTPBearer": [ "events:read" ] } ], "parameters": [ { "name": "event_name", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/IntrospectionEventName", "description": "Canonical event family (required, exactly one)" }, "description": "Canonical event family (required, exactly one)" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "description": "Maximum events per page", "default": 100, "title": "Limit" }, "description": "Maximum events per page" }, { "name": "next", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pagination token from previous response", "title": "Next" }, "description": "Pagination token from previous response" }, { "name": "sort", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Sort field (per-family; defaults to the family's timestamp)", "title": "Sort" }, "description": "Sort field (per-family; defaults to the family's timestamp)" }, { "name": "direction", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/SortDirection", "description": "Sort direction", "default": "desc" }, "description": "Sort direction" }, { "name": "start_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Lower bound (inclusive) on the family timestamp", "title": "Start Date" }, "description": "Lower bound (inclusive) on the family timestamp" }, { "name": "end_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Upper bound (inclusive) on the family timestamp", "title": "End Date" }, "description": "Upper bound (inclusive) on the family timestamp" }, { "name": "conversation_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by conversation ID", "title": "Conversation Id" }, "description": "Filter by conversation ID" }, { "name": "conversation_ids", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Filter by conversation IDs", "title": "Conversation Ids" }, "description": "Filter by conversation IDs" }, { "name": "service_name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by service name", "title": "Service Name" }, "description": "Filter by service name" }, { "name": "environment", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by environment (staging/production)", "title": "Environment" }, "description": "Filter by environment (staging/production)" }, { "name": "runtime_group_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Filter by runtime group ID", "title": "Runtime Group Id" }, "description": "Filter by runtime group ID" }, { "name": "runtime_group_unattributed", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Filter observations with no runtime group", "default": false, "title": "Runtime Group Unattributed" }, "description": "Filter observations with no runtime group" }, { "name": "lens", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Observation/pattern lens filter", "title": "Lens" }, "description": "Observation/pattern lens filter" }, { "name": "pattern_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Observation pattern assignment filter", "title": "Pattern Id" }, "description": "Observation pattern assignment filter" }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pattern status (active/retired), or request status (open/resolved/cancelled) with request=true", "title": "Status" }, "description": "Pattern status (active/retired), or request status (open/resolved/cancelled) with request=true" }, { "name": "include_superseded", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include superseded observations", "default": false, "title": "Include Superseded" }, "description": "Include superseded observations" }, { "name": "trace_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by trace ID", "title": "Trace Id" }, "description": "Filter by trace ID" }, { "name": "span_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by span ID", "title": "Span Id" }, "description": "Filter by span ID" }, { "name": "owner_key", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter: owner key (`user:`/`anon:`/`member:` prefixed)", "title": "Owner Key" }, "description": "Filter: owner key (`user:`/`anon:`/`member:` prefixed)" }, { "name": "judge_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter judgement events by judge ID", "title": "Judge Id" }, "description": "Filter judgement events by judge ID" }, { "name": "issue_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Filter issue events by issue ID", "title": "Issue Id" }, "description": "Filter issue events by issue ID" }, { "name": "event_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Filter by event IDs (max 500)", "title": "Event Id" }, "description": "Filter by event IDs (max 500)" }, { "name": "request", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Return the latest event per human request", "default": false, "title": "Request" }, "description": "Return the latest event per human request" }, { "name": "request_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Select one current human request; requires request=true", "title": "Request Id" }, "description": "Select one current human request; requires request=true" }, { "name": "assignee_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Filter current request assignee; requires request=true", "title": "Assignee Id" }, "description": "Filter current request assignee; requires request=true" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_Annotated_Union_IssueActivityEvent__AnnotationEvent__ObservationEvent__PatternEvent__PatternAssignmentEvent__ClusteringRunEvent__FeedbackEvent__JudgementEvent__TrackEvent___FieldInfo_annotation_NoneType__required_True__discriminator__event_name____" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/events/{event_id}": { "get": { "tags": [ "events" ], "summary": "Get Event", "description": "Read a single event by id within the tenant scope (any family).\n\nRequires scope: `events:read`, `read`, or `*`.", "operationId": "get_event_v1_events__event_id__get", "security": [ { "HTTPBearer": [ "events:read" ] } ], "parameters": [ { "name": "event_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Event Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/IssueActivityEvent" }, { "$ref": "#/components/schemas/AnnotationEvent" }, { "$ref": "#/components/schemas/ObservationEvent" }, { "$ref": "#/components/schemas/PatternEvent" }, { "$ref": "#/components/schemas/PatternAssignmentEvent" }, { "$ref": "#/components/schemas/ClusteringRunEvent" }, { "$ref": "#/components/schemas/FeedbackEvent" }, { "$ref": "#/components/schemas/JudgementEvent" }, { "$ref": "#/components/schemas/TrackEvent" } ], "discriminator": { "propertyName": "event_name", "mapping": { "introspection.issue": "#/components/schemas/IssueActivityEvent", "introspection.annotation": "#/components/schemas/AnnotationEvent", "introspection.observation": "#/components/schemas/ObservationEvent", "introspection.pattern": "#/components/schemas/PatternEvent", "introspection.pattern.assignment": "#/components/schemas/PatternAssignmentEvent", "introspection.observation_clustering.run": "#/components/schemas/ClusteringRunEvent", "introspection.feedback": "#/components/schemas/FeedbackEvent", "introspection.judgement": "#/components/schemas/JudgementEvent", "introspection.track": "#/components/schemas/TrackEvent" } }, "title": "Response Get Event V1 Events Event Id Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/events/feedback": { "post": { "tags": [ "events" ], "summary": "Create Feedback", "description": "Append feedback authored by the authenticated member to OTLP logs.", "operationId": "create_feedback_v1_events_feedback_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackCreate" } } }, "required": true }, "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [ "telemetry:write" ] } ] } } }, "components": { "schemas": { "AgentInfo": { "properties": { "sandbox_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sandbox Status", "description": "Current sandbox pod status" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Session Id", "description": "Agent session ID (for egress credential injection)" } }, "type": "object", "title": "AgentInfo", "description": "Runtime streaming info returned with task responses." }, "AggInterval": { "type": "string", "enum": [ "1m", "5m", "15m", "30m", "1h", "2h", "3h", "6h", "12h", "1d", "2d", "1w", "1mo" ], "title": "AggInterval", "description": "Fixed time-bucket widths (timeseries only)." }, "AnnotationEvent": { "properties": { "id": { "type": "string", "title": "Id", "description": "Event ID (LogAttributes.event.id; the entity id for fold families)" }, "timestamp": { "type": "string", "format": "date-time", "title": "Timestamp", "description": "Event timestamp (per-family semantics; see docs)" }, "event_name": { "type": "string", "const": "introspection.annotation", "title": "Event Name", "default": "introspection.annotation" }, "trace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trace Id", "description": "Trace ID (hex string)" }, "span_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Span Id", "description": "Span ID (hex string)" }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Conversation Id", "description": "Source conversation ID" }, "service_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Service Name", "description": "OTel service name" }, "environment": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Environment", "description": "Environment lane (staging/production)" }, "runtime_group_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Runtime Group Id", "description": "Resolved runtime group ID" }, "runtime_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Runtime Id", "description": "Resolved runtime ID" }, "experiment_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Experiment Id", "description": "Resolved experiment ID" }, "recipe_git_commit_sha": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recipe Git Commit Sha", "description": "Recipe git commit SHA" }, "payload": { "$ref": "#/components/schemas/AnnotationPayload" } }, "type": "object", "required": [ "id", "timestamp", "payload" ], "title": "AnnotationEvent", "description": "One member-authored annotation mutation (stream family)." }, "AnnotationPayload": { "properties": { "member_id": { "type": "string", "format": "uuid", "title": "Member Id", "description": "Authenticated member who authored the mutation" }, "actor_member_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Actor Member Id", "description": "Member that ran the request for the subject (session `act` claim), e.g. an Operator agent" }, "actor_member_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Actor Member Type", "description": "Capacity of the actor: agent, dev, or impersonation" }, "labels": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Labels", "description": "Complete current label snapshot" }, "comment": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Comment", "description": "Immutable comment" }, "assignee_member_ids": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array" }, { "type": "null" } ], "title": "Assignee Member Ids", "description": "Complete current assignee snapshot" } }, "type": "object", "required": [ "member_id" ], "title": "AnnotationPayload", "description": "One member-authored annotation mutation.\n\nAt most one snapshot (labels | assignee_member_ids) is present; a comment\nis an append and may accompany either snapshot on the same event." }, "Automation": { "properties": { "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Record creation timestamp" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "Last update timestamp" }, "org_id": { "type": "string", "format": "uuid", "title": "Org Id", "description": "Organization ID (required for tenant isolation)" }, "project_id": { "type": "string", "format": "uuid", "title": "Project Id", "description": "Project ID" }, "id": { "type": "string", "format": "uuid", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "enabled": { "type": "boolean", "title": "Enabled", "default": true }, "agent_member_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Agent Member Id" }, "created_by_member_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Created By Member Id" }, "execution_blocked_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Execution Blocked Reason" }, "can_manage": { "type": "boolean", "title": "Can Manage", "default": false }, "tags": { "items": { "type": "string" }, "type": "array", "title": "Tags" }, "trigger_type": { "$ref": "#/components/schemas/AutomationTriggerType" }, "cron_schedule": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cron Schedule" }, "kind": { "anyOf": [ { "$ref": "#/components/schemas/AutomationKind" }, { "type": "null" } ] }, "prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Prompt" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "last_triggered_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Triggered At" }, "next_trigger_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Next Trigger At" } }, "type": "object", "required": [ "org_id", "project_id", "name", "trigger_type" ], "title": "Automation", "description": "A stored automation." }, "AutomationCreate": { "properties": { "name": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Name", "description": "Automation name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Human-readable description" }, "trigger_type": { "$ref": "#/components/schemas/AutomationTriggerType", "description": "How the automation is triggered" }, "cron_schedule": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cron Schedule", "description": "Cron expression (cron trigger)" }, "kind": { "anyOf": [ { "$ref": "#/components/schemas/AutomationKind" }, { "type": "null" } ], "description": "Automation kind; omit for a prompt automation" }, "prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Prompt", "description": "Prompt for the agent task" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Typed automation metadata including conditions" }, "enabled": { "type": "boolean", "title": "Enabled", "description": "Whether the automation is active", "default": true }, "tags": { "items": { "type": "string" }, "type": "array", "title": "Tags", "description": "Member tags allowed to read, edit, and run this automation" } }, "additionalProperties": false, "type": "object", "required": [ "name", "trigger_type" ], "title": "AutomationCreate", "description": "Request body for creating an automation." }, "AutomationExecutionStatus": { "type": "string", "enum": [ "triggered", "cancelled", "failed", "skipped" ], "title": "AutomationExecutionStatus", "description": "Outcome of one execution attempt." }, "AutomationKind": { "type": "string", "enum": [ "observation_synthesis", "observation_clustering" ], "title": "AutomationKind", "description": "Both live kinds run platform work rather than an agent conversation." }, "AutomationTriggerResponse": { "properties": { "status": { "$ref": "#/components/schemas/AutomationExecutionStatus" }, "automation_id": { "type": "string", "format": "uuid", "title": "Automation Id" }, "task_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Task Id" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason" } }, "type": "object", "required": [ "status", "automation_id" ], "title": "AutomationTriggerResponse", "description": "Response for a manual trigger." }, "AutomationTriggerType": { "type": "string", "enum": [ "cron", "manual" ], "title": "AutomationTriggerType", "description": "Mirrors the DB enum ``automation_trigger_type``." }, "AutomationUpdate": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 255, "minLength": 1 }, { "type": "null" } ], "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "cron_schedule": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cron Schedule" }, "prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Prompt" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Enabled" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags" } }, "additionalProperties": false, "type": "object", "title": "AutomationUpdate", "description": "Request body for updating an automation." }, "ClusteringRunEvent": { "properties": { "id": { "type": "string", "title": "Id", "description": "Event ID (LogAttributes.event.id; the entity id for fold families)" }, "timestamp": { "type": "string", "format": "date-time", "title": "Timestamp", "description": "Event timestamp (per-family semantics; see docs)" }, "event_name": { "type": "string", "const": "introspection.observation_clustering.run", "title": "Event Name", "default": "introspection.observation_clustering.run" }, "trace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trace Id", "description": "Trace ID (hex string)" }, "span_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Span Id", "description": "Span ID (hex string)" }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Conversation Id", "description": "Source conversation ID" }, "service_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Service Name", "description": "OTel service name" }, "environment": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Environment", "description": "Environment lane (staging/production)" }, "runtime_group_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Runtime Group Id", "description": "Resolved runtime group ID" }, "runtime_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Runtime Id", "description": "Resolved runtime ID" }, "experiment_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Experiment Id", "description": "Resolved experiment ID" }, "recipe_git_commit_sha": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recipe Git Commit Sha", "description": "Recipe git commit SHA" }, "payload": { "$ref": "#/components/schemas/ClusteringRunPayload" } }, "type": "object", "required": [ "id", "timestamp", "payload" ], "title": "ClusteringRunEvent", "description": "One clustering-run audit record (stream family)." }, "ClusteringRunPayload": { "properties": { "run_id": { "type": "string", "title": "Run Id", "description": "Clustering run id" }, "lens": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Lens", "description": "Observation lens the run clustered" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status", "description": "Run outcome status" }, "trigger": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trigger", "description": "What triggered the run" }, "observation_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Observation Count", "description": "Observations considered by the run" }, "pattern_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Pattern Count", "description": "Patterns produced/kept by the run" }, "noise_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Noise Count", "description": "Observations left unassigned as noise" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Params", "description": "Run parameters (stored as a JSON-string attribute)" }, "replaces_run_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Replaces Run Id", "description": "Run this one replaced" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Failure detail for failed runs" } }, "type": "object", "required": [ "run_id" ], "title": "ClusteringRunPayload", "description": "The append-only audit record of one observation clustering run." }, "Conversation": {}, "ConversationItemInclude": { "type": "string", "enum": [ "gen_ai.system_instructions", "gen_ai.tool.definitions", "events", "resource_attributes", "span_attributes" ], "title": "ConversationItemInclude", "description": "Optional conversation item expansions." }, "ConversationSortField": { "type": "string", "enum": [ "created", "duration", "turns", "tool_calls", "llm_calls", "tokens", "cost" ], "title": "ConversationSortField", "description": "Allow-listed fields for conversation summary ordering." }, "ConversationTurnList": { "properties": { "object": { "type": "string", "const": "list", "title": "Object", "default": "list" }, "data": { "items": { "$ref": "#/components/schemas/ConversationTurnResource" }, "type": "array", "title": "Data" }, "first_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Id" }, "last_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Id" }, "has_more": { "type": "boolean", "title": "Has More", "default": false }, "next": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next", "description": "Opaque cursor for the next older page" } }, "type": "object", "title": "ConversationTurnList", "description": "OpenAI-style page of lightweight conversation turns." }, "ConversationTurnResource": {}, "DownloadCommand": { "properties": { "kind": { "type": "string", "const": "download", "title": "Kind", "default": "download" }, "path": { "type": "string", "title": "Path" }, "service": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Service", "description": "Compose service to read from; omit (or `main`) for the agent's own container." } }, "additionalProperties": false, "type": "object", "required": [ "path" ], "title": "DownloadCommand", "description": "Copy the file at ``path`` out of the sandbox into a new Files API object (``output_file_id``)." }, "EffectiveWindow": { "properties": { "start": { "type": "string", "format": "date-time", "title": "Start" }, "end": { "type": "string", "format": "date-time", "title": "End" } }, "type": "object", "required": [ "start", "end" ], "title": "EffectiveWindow", "description": "The time window actually applied (default-filled when the caller omitted it)." }, "ExecCommand": { "properties": { "kind": { "type": "string", "const": "exec", "title": "Kind", "default": "exec" }, "command": { "items": { "type": "string" }, "type": "array", "maxItems": 64, "minItems": 1, "title": "Command" }, "cwd": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cwd" }, "timeout_seconds": { "type": "integer", "maximum": 3600, "minimum": 1, "title": "Timeout Seconds", "default": 300 }, "service": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Service", "description": "Compose service to run in; omit (or `main`) for the agent's own container." } }, "additionalProperties": false, "type": "object", "required": [ "command" ], "title": "ExecCommand", "description": "Run ``command`` (argv, never a shell string) inside the sandbox and record its exit and output." }, "FeedbackCreate": { "properties": { "conversation_id": { "type": "string", "maxLength": 512, "minLength": 1, "title": "Conversation Id" }, "sentiment": { "$ref": "#/components/schemas/FeedbackSentiment" }, "comments": { "anyOf": [ { "type": "string", "maxLength": 10000 }, { "type": "null" } ], "title": "Comments" }, "previous_response_id": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ], "title": "Previous Response Id" }, "message_id": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ], "title": "Message Id" }, "trace_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{32}$" }, { "type": "null" } ], "title": "Trace Id" }, "span_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{16}$" }, { "type": "null" } ], "title": "Span Id" }, "surface": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "Surface" } }, "type": "object", "required": [ "conversation_id", "sentiment" ], "title": "FeedbackCreate", "description": "One append-only feedback event authored from the operator UI." }, "FeedbackEvent": { "properties": { "id": { "type": "string", "title": "Id", "description": "Event ID (LogAttributes.event.id; the entity id for fold families)" }, "timestamp": { "type": "string", "format": "date-time", "title": "Timestamp", "description": "Event timestamp (per-family semantics; see docs)" }, "event_name": { "type": "string", "const": "introspection.feedback", "title": "Event Name", "default": "introspection.feedback" }, "trace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trace Id", "description": "Trace ID (hex string)" }, "span_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Span Id", "description": "Span ID (hex string)" }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Conversation Id", "description": "Source conversation ID" }, "service_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Service Name", "description": "OTel service name" }, "environment": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Environment", "description": "Environment lane (staging/production)" }, "runtime_group_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Runtime Group Id", "description": "Resolved runtime group ID" }, "runtime_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Runtime Id", "description": "Resolved runtime ID" }, "experiment_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Experiment Id", "description": "Resolved experiment ID" }, "recipe_git_commit_sha": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recipe Git Commit Sha", "description": "Recipe git commit SHA" }, "payload": { "$ref": "#/components/schemas/FeedbackPayload" } }, "type": "object", "required": [ "id", "timestamp", "payload" ], "title": "FeedbackEvent", "description": "One end-user feedback event (stream family)." }, "FeedbackPayload": { "properties": { "name": { "type": "string", "title": "Name", "description": "Feedback label (properties.name), e.g. thumbs_up" }, "comments": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Comments", "description": "Free-text comments (properties.comments)" }, "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Value", "description": "Numeric axis when present (properties.value)" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id", "description": "Identified user (identity.user.id)" }, "anonymous_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Anonymous Id", "description": "Anonymous identity (identity.anonymous.id)" }, "author_member_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Author Member Id", "description": "Authenticated member who authored the feedback (introspection.member.id)" }, "sentiment": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sentiment", "description": "Optional EMITTED sentiment (properties.sentiment); never derived server-side — no thumbs_up→positive inference" }, "previous_response_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Previous Response Id", "description": "Response the feedback anchors to (gen_ai.request.previous_response_id)" }, "agent_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Name", "description": "Agent context at emit time (gen_ai.agent.name)" }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id", "description": "Agent context at emit time (gen_ai.agent.id)" }, "properties": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Properties", "description": "Remaining properties.* extras" } }, "type": "object", "required": [ "name" ], "title": "FeedbackPayload", "description": "End-user feedback as the SDK `feedback()` surfaces actually emit it." }, "FeedbackSentiment": { "type": "string", "enum": [ "positive", "negative", "neutral" ], "title": "FeedbackSentiment" }, "File": { "properties": { "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Record creation timestamp" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "Last update timestamp" }, "org_id": { "type": "string", "format": "uuid", "title": "Org Id", "description": "Organization ID (required for tenant isolation)" }, "project_id": { "type": "string", "format": "uuid", "title": "Project Id", "description": "Project ID" }, "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Unique identifier (UUID7)" }, "name": { "type": "string", "maxLength": 512, "minLength": 1, "title": "Name", "description": "Logical file path or name" }, "file_type": { "$ref": "#/components/schemas/FileType", "description": "File type", "default": "other" }, "storage_path": { "type": "string", "title": "Storage Path", "description": "Cloud storage path" }, "mime_type": { "type": "string", "maxLength": 100, "title": "Mime Type", "default": "application/octet-stream" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "tags": { "items": { "type": "string" }, "type": "array", "title": "Tags", "description": "Free-form tags, conventionally `key:value`. Filter with `?tag=team:acme`. Shared: any member whose own tags intersect these can read and write the file. Tags belong to the file rather than to a version, so they carry forward when a new version is uploaded." }, "member_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Member Id", "description": "Member who created this file" }, "task_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Task Id", "description": "Task this file was created from (accounting only)" }, "generated_output_task_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Generated Output Task Id", "description": "Verified generating task for inherited output sharing" }, "size_bytes": { "type": "integer", "title": "Size Bytes", "description": "File size in bytes" }, "version": { "type": "integer", "title": "Version", "default": 1 }, "parent_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Parent Id", "description": "Previous version" }, "storage_version_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Storage Version Id", "description": "Cloud storage version ID" } }, "type": "object", "required": [ "org_id", "project_id", "name", "storage_path", "size_bytes" ], "title": "File", "description": "Full file schema." }, "FileType": { "type": "string", "enum": [ "upload", "filesystem", "other" ], "title": "FileType", "description": "File type enum." }, "FileUpdate": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 512, "minLength": 1 }, { "type": "null" } ], "title": "Name" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags", "description": "Replaces the tag list wholesale. Omit to leave tags untouched; pass [] to clear them. Tags apply to the file, so they carry forward to every future version." } }, "type": "object", "title": "FileUpdate", "description": "Schema for updating a file." }, "GenAiSpan": {}, "GenAiSpanList": { "properties": { "object": { "type": "string", "const": "list", "title": "Object", "default": "list" }, "data": { "items": { "$ref": "#/components/schemas/GenAiSpan" }, "type": "array", "title": "Data" }, "first_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Id", "description": "First span ID in this page" }, "last_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Id", "description": "Last span ID in this page" }, "has_more": { "type": "boolean", "title": "Has More", "description": "Whether additional pages exist after this one", "default": false }, "next": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next", "description": "Opaque cursor for the next page" } }, "type": "object", "title": "GenAiSpanList", "description": "OpenAI-style list envelope for conversation items.\n\n`first_id` and `last_id` are informational; pagination uses the opaque\n`next` cursor." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "IntrospectionEventName": { "type": "string", "enum": [ "introspection.annotation", "introspection.feedback", "introspection.observation", "introspection.observation_clustering.run", "introspection.judgement", "introspection.pattern", "introspection.pattern.assignment", "introspection.track", "introspection.issue" ], "title": "IntrospectionEventName", "description": "The event families served by `/v1/events`." }, "IssueActivityEvent": { "properties": { "id": { "type": "string", "title": "Id", "description": "Event ID (LogAttributes.event.id; the entity id for fold families)" }, "timestamp": { "type": "string", "format": "date-time", "title": "Timestamp", "description": "Event timestamp (per-family semantics; see docs)" }, "event_name": { "type": "string", "const": "introspection.issue", "title": "Event Name", "default": "introspection.issue" }, "trace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trace Id", "description": "Trace ID (hex string)" }, "span_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Span Id", "description": "Span ID (hex string)" }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Conversation Id", "description": "Source conversation ID" }, "service_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Service Name", "description": "OTel service name" }, "environment": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Environment", "description": "Environment lane (staging/production)" }, "runtime_group_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Runtime Group Id", "description": "Resolved runtime group ID" }, "runtime_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Runtime Id", "description": "Resolved runtime ID" }, "experiment_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Experiment Id", "description": "Resolved experiment ID" }, "recipe_git_commit_sha": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recipe Git Commit Sha", "description": "Recipe git commit SHA" }, "payload": { "$ref": "#/components/schemas/IssueActivityPayload" } }, "type": "object", "required": [ "id", "timestamp", "payload" ], "title": "IssueActivityEvent" }, "IssueActivityPayload": { "properties": { "request": { "anyOf": [ { "$ref": "#/components/schemas/IssueRequestPayload" }, { "type": "null" } ] }, "changes": { "anyOf": [ { "additionalProperties": { "additionalProperties": true, "type": "object" }, "type": "object" }, { "type": "null" } ], "title": "Changes" }, "issue_id": { "type": "string", "format": "uuid", "title": "Issue Id" }, "action": { "type": "string", "title": "Action" }, "resource_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Resource Id" }, "revision": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Revision" }, "data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Data" } }, "type": "object", "required": [ "issue_id", "action" ], "title": "IssueActivityPayload" }, "IssueEventReference": { "properties": { "event_id": { "type": "string", "format": "uuid", "title": "Event Id" } }, "additionalProperties": false, "type": "object", "required": [ "event_id" ], "title": "IssueEventReference" }, "IssueFile": { "properties": { "file_id": { "type": "string", "format": "uuid", "title": "File Id" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "checksum": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Checksum" }, "source_event_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "maxItems": 100, "title": "Source Event Ids" } }, "additionalProperties": false, "type": "object", "required": [ "file_id" ], "title": "IssueFile" }, "IssueLink": { "properties": { "url": { "type": "string", "maxLength": 2048, "minLength": 1, "title": "Url" }, "title": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ], "title": "Title" } }, "additionalProperties": false, "type": "object", "required": [ "url" ], "title": "IssueLink" }, "IssueRequestPayload": { "properties": { "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Record creation timestamp" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "Last update timestamp" }, "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Unique identifier (UUID7)" }, "files": { "items": { "$ref": "#/components/schemas/IssueFile" }, "type": "array", "title": "Files" }, "links": { "items": { "$ref": "#/components/schemas/IssueLink" }, "type": "array", "maxItems": 200, "title": "Links" }, "events": { "items": { "$ref": "#/components/schemas/IssueEventReference" }, "type": "array", "maxItems": 50, "title": "Events" }, "spans": { "items": { "$ref": "#/components/schemas/IssueSpanReference" }, "type": "array", "maxItems": 50, "title": "Spans" }, "issue_id": { "type": "string", "format": "uuid", "title": "Issue Id" }, "task_id": { "type": "string", "format": "uuid", "title": "Task Id" }, "question": { "type": "string", "title": "Question" }, "assignee_id": { "type": "string", "format": "uuid", "title": "Assignee Id" }, "status": { "type": "string", "enum": [ "open", "resolved", "cancelled" ], "title": "Status" }, "resolution": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Resolution" }, "revision": { "type": "integer", "title": "Revision" }, "issue_revision": { "type": "integer", "title": "Issue Revision", "default": 1 } }, "type": "object", "required": [ "issue_id", "task_id", "question", "assignee_id", "status", "revision" ], "title": "IssueRequestPayload", "description": "The recorded request snapshot, without redundant tenant identity." }, "IssueSpanReference": { "properties": { "trace_id": { "type": "string", "pattern": "^[0-9a-fA-F]{32}$", "title": "Trace Id" }, "span_id": { "type": "string", "pattern": "^[0-9a-fA-F]{16}$", "title": "Span Id" } }, "additionalProperties": false, "type": "object", "required": [ "trace_id", "span_id" ], "title": "IssueSpanReference" }, "JudgementEvent": { "properties": { "id": { "type": "string", "title": "Id", "description": "Event ID (LogAttributes.event.id; the entity id for fold families)" }, "timestamp": { "type": "string", "format": "date-time", "title": "Timestamp", "description": "Event timestamp (per-family semantics; see docs)" }, "event_name": { "type": "string", "const": "introspection.judgement", "title": "Event Name", "default": "introspection.judgement" }, "trace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trace Id", "description": "Trace ID (hex string)" }, "span_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Span Id", "description": "Span ID (hex string)" }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Conversation Id", "description": "Source conversation ID" }, "service_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Service Name", "description": "OTel service name" }, "environment": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Environment", "description": "Environment lane (staging/production)" }, "runtime_group_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Runtime Group Id", "description": "Resolved runtime group ID" }, "runtime_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Runtime Id", "description": "Resolved runtime ID" }, "experiment_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Experiment Id", "description": "Resolved experiment ID" }, "recipe_git_commit_sha": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recipe Git Commit Sha", "description": "Recipe git commit SHA" }, "payload": { "$ref": "#/components/schemas/JudgementPayload" } }, "type": "object", "required": [ "id", "timestamp", "payload" ], "title": "JudgementEvent", "description": "One judge verdict event (stream family)." }, "JudgementPayload": { "properties": { "judgement_id": { "type": "string", "title": "Judgement Id", "description": "Judgement id (introspection.judgement.id)" }, "judge_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Judge Id", "description": "Judge id (introspection.judge.id)" }, "result": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Result", "description": "Verdict (introspection.judgement.result)" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status", "description": "Execution outcome (ok/error) — distinct from the verdict" }, "error_class": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Class", "description": "Coarse failure class when status is error" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Message", "description": "Why the judgement failed, in the upstream's own words. error_class names the layer; this names the cause — an HTTP 429 is a retryable rate limit or an exhausted credit balance, and only this distinguishes them. Bounded and guarded against echoing the transcript at the emitter. For reading, not for grouping." }, "source_component": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Component", "description": "Which component emitted the judgement (introspection.source.component): 'introspection-judge' for the CLI, 'runtime-agent' for the pre-v3 runtime emitter. The only way to tell the two apart while both are deployed." }, "reasoning": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reasoning", "description": "Grader rationale for the verdict" }, "definition_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Definition Hash", "description": "Judge definition hash (introspection.judge.definition_hash)" }, "engine_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Engine Version", "description": "Judge engine build that produced the verdict" }, "judge_provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Judge Provider", "description": "Grader LLM provider" }, "judge_model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Judge Model", "description": "Grader LLM model" }, "contract_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contract Version", "description": "Judgement contract version" }, "sequence_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sequence Hash", "description": "Judged sequence hash" }, "input_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Input Tokens", "description": "Grader input tokens" }, "output_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Output Tokens", "description": "Grader output tokens" }, "total_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Tokens", "description": "Grader total tokens" }, "experiment_arm_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Experiment Arm Id", "description": "Experiment arm lineage (introspection.experiment.arm_id)" } }, "type": "object", "required": [ "judgement_id" ], "title": "JudgementPayload", "description": "One judge verdict as the runtime-agent judges emitter writes it." }, "MainService": { "properties": { "volumes": { "items": { "type": "string" }, "type": "array", "title": "Volumes" }, "depends_on": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "additionalProperties": { "anyOf": [ { "$ref": "#/components/schemas/SidecarDependsOn" }, { "type": "null" } ] }, "type": "object" }, { "type": "null" } ], "title": "Depends On" } }, "additionalProperties": false, "type": "object", "title": "MainService", "description": "What the compose file may say about ``main``: how the agent binds to the world.\n\nThe Runtime image fills the slot, so an image, a command, ports or an\nenvironment here would describe a container that does not exist and are\nrefused by key." }, "MetricDimension": { "properties": { "field": { "type": "string", "maxLength": 128, "minLength": 1, "title": "Field" } }, "additionalProperties": false, "type": "object", "required": [ "field" ], "title": "MetricDimension" }, "MetricDimensionValue": { "properties": { "field": { "type": "string", "title": "Field" }, "value": { "type": "string", "title": "Value" } }, "type": "object", "required": [ "field", "value" ], "title": "MetricDimensionValue" }, "MetricFilter": { "properties": { "field": { "type": "string", "maxLength": 128, "minLength": 1, "title": "Field" }, "operator": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "nin", "exists", "contains" ], "title": "Operator" }, "value": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" }, { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" } ] }, "type": "array" }, { "type": "null" } ], "title": "Value" } }, "additionalProperties": false, "type": "object", "required": [ "field", "operator" ], "title": "MetricFilter" }, "MetricHaving": { "properties": { "metric_index": { "type": "integer", "exclusiveMaximum": 6, "minimum": 0, "title": "Metric Index" }, "operator": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte" ], "title": "Operator" }, "value": { "type": "number", "title": "Value" } }, "additionalProperties": false, "type": "object", "required": [ "metric_index", "operator", "value" ], "title": "MetricHaving" }, "MetricOrderBy": { "properties": { "type": { "$ref": "#/components/schemas/MetricOrderType" }, "direction": { "$ref": "#/components/schemas/MetricOrderDirection", "default": "asc" }, "metric_index": { "anyOf": [ { "type": "integer", "exclusiveMaximum": 6, "minimum": 0 }, { "type": "null" } ], "title": "Metric Index" }, "field": { "anyOf": [ { "type": "string", "maxLength": 128, "minLength": 1 }, { "type": "null" } ], "title": "Field" } }, "additionalProperties": false, "type": "object", "required": [ "type" ], "title": "MetricOrderBy" }, "MetricOrderDirection": { "type": "string", "enum": [ "asc", "desc" ], "title": "MetricOrderDirection" }, "MetricOrderType": { "type": "string", "enum": [ "metric", "dimension", "time" ], "title": "MetricOrderType" }, "MetricQueryConfig": { "properties": { "row_limit": { "type": "integer", "maximum": 10000, "minimum": 1, "title": "Row Limit", "default": 100 }, "series_limit": { "anyOf": [ { "type": "integer", "maximum": 100, "minimum": 1 }, { "type": "null" } ], "title": "Series Limit" } }, "additionalProperties": false, "type": "object", "title": "MetricQueryConfig" }, "MetricQueryMeta": { "properties": { "view": { "$ref": "#/components/schemas/MetricView" }, "window": { "$ref": "#/components/schemas/EffectiveWindow" }, "row_count": { "type": "integer", "title": "Row Count" }, "row_limit": { "type": "integer", "title": "Row Limit" }, "interval": { "anyOf": [ { "$ref": "#/components/schemas/AggInterval" }, { "type": "null" } ] }, "step_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Step Seconds" }, "approximate": { "type": "boolean", "title": "Approximate", "default": false }, "truncated": { "type": "boolean", "title": "Truncated", "default": false }, "owner_scoped": { "type": "boolean", "title": "Owner Scoped", "default": false }, "order_by": { "items": { "$ref": "#/components/schemas/MetricOrderBy" }, "type": "array", "title": "Order By" } }, "type": "object", "required": [ "view", "window", "row_count", "row_limit" ], "title": "MetricQueryMeta" }, "MetricQueryRequest": { "properties": { "view": { "$ref": "#/components/schemas/MetricView" }, "metrics": { "items": { "$ref": "#/components/schemas/MetricSpec" }, "type": "array", "maxItems": 6, "minItems": 1, "title": "Metrics" }, "dimensions": { "items": { "$ref": "#/components/schemas/MetricDimension" }, "type": "array", "maxItems": 4, "title": "Dimensions" }, "filters": { "items": { "$ref": "#/components/schemas/MetricFilter" }, "type": "array", "maxItems": 20, "title": "Filters" }, "time_dimension": { "anyOf": [ { "$ref": "#/components/schemas/MetricTimeDimension" }, { "type": "null" } ] }, "order_by": { "items": { "$ref": "#/components/schemas/MetricOrderBy" }, "type": "array", "maxItems": 3, "title": "Order By" }, "having": { "items": { "$ref": "#/components/schemas/MetricHaving" }, "type": "array", "maxItems": 6, "title": "Having" }, "from_timestamp": { "type": "string", "format": "date-time", "title": "From Timestamp" }, "to_timestamp": { "type": "string", "format": "date-time", "title": "To Timestamp" }, "config": { "$ref": "#/components/schemas/MetricQueryConfig" } }, "additionalProperties": false, "type": "object", "required": [ "view", "metrics", "from_timestamp", "to_timestamp" ], "title": "MetricQueryRequest" }, "MetricQueryResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/MetricResultRow" }, "type": "array", "title": "Data" }, "meta": { "$ref": "#/components/schemas/MetricQueryMeta" } }, "type": "object", "required": [ "meta" ], "title": "MetricQueryResponse" }, "MetricResultRow": { "properties": { "timestamp": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Timestamp" }, "dimensions": { "items": { "$ref": "#/components/schemas/MetricDimensionValue" }, "type": "array", "title": "Dimensions" }, "metrics": { "items": { "$ref": "#/components/schemas/MetricResultValue" }, "type": "array", "title": "Metrics" } }, "type": "object", "title": "MetricResultRow" }, "MetricResultValue": { "properties": { "metric_index": { "type": "integer", "title": "Metric Index" }, "measure": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Measure" }, "aggregation": { "type": "string", "enum": [ "count", "count_distinct", "sum", "avg", "min", "max", "p50", "p75", "p90", "p95", "p99" ], "title": "Aggregation" }, "value": { "type": "number", "title": "Value" } }, "type": "object", "required": [ "metric_index", "measure", "aggregation", "value" ], "title": "MetricResultValue" }, "MetricSpec": { "properties": { "measure": { "anyOf": [ { "type": "string", "maxLength": 128, "minLength": 1 }, { "type": "null" } ], "title": "Measure" }, "aggregation": { "type": "string", "enum": [ "count", "count_distinct", "sum", "avg", "min", "max", "p50", "p75", "p90", "p95", "p99" ], "title": "Aggregation" } }, "additionalProperties": false, "type": "object", "required": [ "aggregation" ], "title": "MetricSpec" }, "MetricTimeDimension": { "properties": { "granularity": { "anyOf": [ { "$ref": "#/components/schemas/AggInterval" }, { "type": "string", "const": "auto" }, { "type": "null" } ], "title": "Granularity" }, "bins": { "anyOf": [ { "type": "integer", "maximum": 500, "minimum": 1 }, { "type": "null" } ], "title": "Bins" } }, "additionalProperties": false, "type": "object", "title": "MetricTimeDimension" }, "MetricView": { "type": "string", "enum": [ "spans", "conversations", "events", "judgements", "observations", "patterns", "files" ], "title": "MetricView" }, "ObservationEvent": { "properties": { "id": { "type": "string", "title": "Id", "description": "Event ID (LogAttributes.event.id; the entity id for fold families)" }, "timestamp": { "type": "string", "format": "date-time", "title": "Timestamp", "description": "Event timestamp (per-family semantics; see docs)" }, "event_name": { "type": "string", "const": "introspection.observation", "title": "Event Name", "default": "introspection.observation" }, "trace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trace Id", "description": "Trace ID (hex string)" }, "span_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Span Id", "description": "Span ID (hex string)" }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Conversation Id", "description": "Source conversation ID" }, "service_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Service Name", "description": "OTel service name" }, "environment": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Environment", "description": "Environment lane (staging/production)" }, "runtime_group_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Runtime Group Id", "description": "Resolved runtime group ID" }, "runtime_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Runtime Id", "description": "Resolved runtime ID" }, "experiment_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Experiment Id", "description": "Resolved experiment ID" }, "recipe_git_commit_sha": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recipe Git Commit Sha", "description": "Recipe git commit SHA" }, "payload": { "$ref": "#/components/schemas/ObservationPayload" } }, "type": "object", "required": [ "id", "timestamp", "payload" ], "title": "ObservationEvent", "description": "One resolved observation (state family: the fold, not a raw delta)." }, "ObservationLens": { "type": "string", "enum": [ "user_intent", "task_resolution", "user_sentiment", "agent_struggle", "environment_issue" ], "title": "ObservationLens", "description": "Perspective used to extract an observation from a completed conversation." }, "ObservationPayload": { "properties": { "observation_id": { "type": "string", "format": "uuid", "title": "Observation Id", "description": "Observation id (also the generated event's event.id)" }, "lens": { "$ref": "#/components/schemas/ObservationLens", "description": "Extraction lens" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label", "description": "Short discrete label, e.g. competitor_misclassification" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary", "description": "One-sentence summary" }, "confidence": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Confidence", "description": "LLM extraction confidence 0..1" }, "sentiment": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sentiment", "description": "Normalized user sentiment" }, "resolution": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Resolution", "description": "Normalized task resolution" }, "evidence_refs": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Evidence Refs", "description": "Transcript refs cited as evidence" }, "source_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Hash", "description": "Deterministic synthesis identity hash" }, "replaces_observation_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Replaces Observation Id", "description": "Observation this one superseded (later continuation segment)" }, "pattern_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pattern Id", "description": "CURRENT pattern assignment (None = unassigned)" }, "assignment_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Assignment Score", "description": "Centroid cosine similarity of the assignment" }, "assignment_method": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assignment Method", "description": "How the assignment was made (classified/patterned)" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Lens-specific metadata (sentiment, resolution, ...)" } }, "type": "object", "required": [ "observation_id", "lens" ], "title": "ObservationPayload", "description": "One resolved lens observation — the fold: supersession applied,\ncurrent pattern assignment joined from later assignment events." }, "PaginatedResponse_Annotated_Union_IssueActivityEvent__AnnotationEvent__ObservationEvent__PatternEvent__PatternAssignmentEvent__ClusteringRunEvent__FeedbackEvent__JudgementEvent__TrackEvent___FieldInfo_annotation_NoneType__required_True__discriminator__event_name____": { "properties": { "records": { "items": { "oneOf": [ { "$ref": "#/components/schemas/IssueActivityEvent" }, { "$ref": "#/components/schemas/AnnotationEvent" }, { "$ref": "#/components/schemas/ObservationEvent" }, { "$ref": "#/components/schemas/PatternEvent" }, { "$ref": "#/components/schemas/PatternAssignmentEvent" }, { "$ref": "#/components/schemas/ClusteringRunEvent" }, { "$ref": "#/components/schemas/FeedbackEvent" }, { "$ref": "#/components/schemas/JudgementEvent" }, { "$ref": "#/components/schemas/TrackEvent" } ], "discriminator": { "propertyName": "event_name", "mapping": { "introspection.annotation": "#/components/schemas/AnnotationEvent", "introspection.feedback": "#/components/schemas/FeedbackEvent", "introspection.issue": "#/components/schemas/IssueActivityEvent", "introspection.judgement": "#/components/schemas/JudgementEvent", "introspection.observation": "#/components/schemas/ObservationEvent", "introspection.observation_clustering.run": "#/components/schemas/ClusteringRunEvent", "introspection.pattern": "#/components/schemas/PatternEvent", "introspection.pattern.assignment": "#/components/schemas/PatternAssignmentEvent", "introspection.track": "#/components/schemas/TrackEvent" } } }, "type": "array", "title": "Records", "description": "List of items in this page" }, "count": { "type": "integer", "title": "Count", "description": "Number of items in this page" }, "total_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Count", "description": "Total number of items (optional, expensive for large datasets)" }, "next": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next", "description": "Pagination token for the next page (null if no more pages)" } }, "type": "object", "required": [ "records", "count" ], "title": "PaginatedResponse[Annotated[Union[IssueActivityEvent, AnnotationEvent, ObservationEvent, PatternEvent, PatternAssignmentEvent, ClusteringRunEvent, FeedbackEvent, JudgementEvent, TrackEvent], FieldInfo(annotation=NoneType, required=True, discriminator='event_name')]]" }, "PaginatedResponse_Automation_": { "properties": { "records": { "items": { "$ref": "#/components/schemas/Automation" }, "type": "array", "title": "Records", "description": "List of items in this page" }, "count": { "type": "integer", "title": "Count", "description": "Number of items in this page" }, "total_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Count", "description": "Total number of items (optional, expensive for large datasets)" }, "next": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next", "description": "Pagination token for the next page (null if no more pages)" } }, "type": "object", "required": [ "records", "count" ], "title": "PaginatedResponse[Automation]" }, "PaginatedResponse_Conversation_": { "properties": { "records": { "items": { "$ref": "#/components/schemas/Conversation" }, "type": "array", "title": "Records", "description": "List of items in this page" }, "count": { "type": "integer", "title": "Count", "description": "Number of items in this page" }, "total_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Count", "description": "Total number of items (optional, expensive for large datasets)" }, "next": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next", "description": "Pagination token for the next page (null if no more pages)" } }, "type": "object", "required": [ "records", "count" ], "title": "PaginatedResponse[Conversation]" }, "PaginatedResponse_File_": { "properties": { "records": { "items": { "$ref": "#/components/schemas/File" }, "type": "array", "title": "Records", "description": "List of items in this page" }, "count": { "type": "integer", "title": "Count", "description": "Number of items in this page" }, "total_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Count", "description": "Total number of items (optional, expensive for large datasets)" }, "next": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next", "description": "Pagination token for the next page (null if no more pages)" } }, "type": "object", "required": [ "records", "count" ], "title": "PaginatedResponse[File]" }, "PaginatedResponse_ResourceShare_": { "properties": { "records": { "items": { "$ref": "#/components/schemas/ResourceShare" }, "type": "array", "title": "Records", "description": "List of items in this page" }, "count": { "type": "integer", "title": "Count", "description": "Number of items in this page" }, "total_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Count", "description": "Total number of items (optional, expensive for large datasets)" }, "next": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next", "description": "Pagination token for the next page (null if no more pages)" } }, "type": "object", "required": [ "records", "count" ], "title": "PaginatedResponse[ResourceShare]" }, "PaginatedResponse_TaskCommand_": { "properties": { "records": { "items": { "$ref": "#/components/schemas/TaskCommand" }, "type": "array", "title": "Records", "description": "List of items in this page" }, "count": { "type": "integer", "title": "Count", "description": "Number of items in this page" }, "total_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Count", "description": "Total number of items (optional, expensive for large datasets)" }, "next": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next", "description": "Pagination token for the next page (null if no more pages)" } }, "type": "object", "required": [ "records", "count" ], "title": "PaginatedResponse[TaskCommand]" }, "PaginatedResponse_Task_": { "properties": { "records": { "items": { "$ref": "#/components/schemas/Task" }, "type": "array", "title": "Records", "description": "List of items in this page" }, "count": { "type": "integer", "title": "Count", "description": "Number of items in this page" }, "total_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Count", "description": "Total number of items (optional, expensive for large datasets)" }, "next": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next", "description": "Pagination token for the next page (null if no more pages)" } }, "type": "object", "required": [ "records", "count" ], "title": "PaginatedResponse[Task]" }, "PatternAssignmentEvent": { "properties": { "id": { "type": "string", "title": "Id", "description": "Event ID (LogAttributes.event.id; the entity id for fold families)" }, "timestamp": { "type": "string", "format": "date-time", "title": "Timestamp", "description": "Event timestamp (per-family semantics; see docs)" }, "event_name": { "type": "string", "const": "introspection.pattern.assignment", "title": "Event Name", "default": "introspection.pattern.assignment" }, "trace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trace Id", "description": "Trace ID (hex string)" }, "span_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Span Id", "description": "Span ID (hex string)" }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Conversation Id", "description": "Source conversation ID" }, "service_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Service Name", "description": "OTel service name" }, "environment": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Environment", "description": "Environment lane (staging/production)" }, "runtime_group_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Runtime Group Id", "description": "Resolved runtime group ID" }, "runtime_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Runtime Id", "description": "Resolved runtime ID" }, "experiment_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Experiment Id", "description": "Resolved experiment ID" }, "recipe_git_commit_sha": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recipe Git Commit Sha", "description": "Recipe git commit SHA" }, "payload": { "$ref": "#/components/schemas/PatternAssignmentPayload" } }, "type": "object", "required": [ "id", "timestamp", "payload" ], "title": "PatternAssignmentEvent", "description": "One assignment delta (stream family)." }, "PatternAssignmentPayload": { "properties": { "observation_id": { "type": "string", "format": "uuid", "title": "Observation Id", "description": "Assigned observation id" }, "pattern_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pattern Id", "description": "Assigned pattern (None = explicitly unassigned)" }, "method": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Method", "description": "How the assignment was made (classified/patterned/manual)" }, "run_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Run Id", "description": "Clustering run that produced the assignment" }, "score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Score", "description": "Centroid cosine similarity of the assignment" } }, "type": "object", "required": [ "observation_id" ], "title": "PatternAssignmentPayload", "description": "One observation→pattern assignment delta (None pattern = unassignment)." }, "PatternEvent": { "properties": { "id": { "type": "string", "title": "Id", "description": "Event ID (LogAttributes.event.id; the entity id for fold families)" }, "timestamp": { "type": "string", "format": "date-time", "title": "Timestamp", "description": "Event timestamp (per-family semantics; see docs)" }, "event_name": { "type": "string", "const": "introspection.pattern", "title": "Event Name", "default": "introspection.pattern" }, "trace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trace Id", "description": "Trace ID (hex string)" }, "span_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Span Id", "description": "Span ID (hex string)" }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Conversation Id", "description": "Source conversation ID" }, "service_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Service Name", "description": "OTel service name" }, "environment": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Environment", "description": "Environment lane (staging/production)" }, "runtime_group_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Runtime Group Id", "description": "Resolved runtime group ID" }, "runtime_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Runtime Id", "description": "Resolved runtime ID" }, "experiment_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Experiment Id", "description": "Resolved experiment ID" }, "recipe_git_commit_sha": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recipe Git Commit Sha", "description": "Recipe git commit SHA" }, "payload": { "$ref": "#/components/schemas/PatternPayload" } }, "type": "object", "required": [ "id", "timestamp", "payload" ], "title": "PatternEvent", "description": "One folded pattern catalog row (state family)." }, "PatternPayload": { "properties": { "pattern_id": { "type": "string", "title": "Pattern Id", "description": "Pattern ID" }, "action": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Action", "description": "Latest lifecycle action (created/updated/retired)" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Current pattern name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Current pattern description" }, "lens": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Lens", "description": "Observation lens" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status", "description": "Current status: active or retired" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At", "description": "First lifecycle event timestamp" }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updated At", "description": "Latest create/update timestamp" }, "retired_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Retired At", "description": "Retirement timestamp" }, "last_detected_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Detected At", "description": "Latest observation assignment timestamp" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason", "description": "Retirement reason (stale/superseded/manual)" }, "replacement_pattern_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Replacement Pattern Id", "description": "Replacement pattern when retired as superseded" }, "derived_from_pattern_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Derived From Pattern Id", "description": "Broader pattern this one was carved off" }, "run_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Run Id", "description": "Clustering run that last touched the pattern" } }, "type": "object", "required": [ "pattern_id" ], "title": "PatternPayload", "description": "One folded pattern catalog row — the pattern as it currently is." }, "ResourceShare": { "properties": { "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Record creation timestamp" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "Last update timestamp" }, "org_id": { "type": "string", "format": "uuid", "title": "Org Id", "description": "Organization ID (required for tenant isolation)" }, "project_id": { "type": "string", "format": "uuid", "title": "Project Id", "description": "Project ID" }, "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Unique identifier (UUID7)" }, "resource_type": { "$ref": "#/components/schemas/ShareResourceType", "description": "Resource family the grant targets" }, "resource_id": { "type": "string", "title": "Resource Id", "description": "Top-level resource id: file_id or conversation_id" }, "granted_member_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Granted Member Id", "description": "Member-targeted grant. Null means a project-wide grant (everyone in the project)." }, "created_by_member_id": { "type": "string", "format": "uuid", "title": "Created By Member Id", "description": "Grantor member (always set) — the revoke gate" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url", "description": "Fully-qualified canonical GET URL for the shared resource (e.g. https:///v1/files/ or /v1/conversations/). Populated on read; follow it (or GET ?redirect=true) to fetch the resource." } }, "type": "object", "required": [ "org_id", "project_id", "resource_type", "resource_id", "created_by_member_id" ], "title": "ResourceShare", "description": "A single read-sharing grant for one resource." }, "ShareCreate": { "properties": { "resource_type": { "$ref": "#/components/schemas/ShareResourceType", "description": "Resource family the grant targets" }, "resource_id": { "type": "string", "minLength": 1, "title": "Resource Id", "description": "Top-level resource id to share" }, "granted_member_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Granted Member Id", "description": "Target one member; omit for a project-wide grant" } }, "type": "object", "required": [ "resource_type", "resource_id" ], "title": "ShareCreate", "description": "Request body for creating a read-sharing grant.\n\nTarget either a member (`granted_member_id`) or the whole project (omit\nit). An end customer is a member, so there is no separate identity target." }, "ShareResourceType": { "type": "string", "enum": [ "file", "conversation" ], "title": "ShareResourceType", "description": "The resource family a share grant targets. Tasks are deliberately excluded\n— they are owned lifecycle objects, not shareable resources." }, "SidecarBuild": { "properties": { "context": { "type": "string", "format": "uuid", "title": "Context" }, "dockerfile": { "type": "string", "title": "Dockerfile", "default": "Dockerfile" }, "platform": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Platform" } }, "additionalProperties": false, "type": "object", "required": [ "context" ], "title": "SidecarBuild", "description": "Compose ``build``: the context the plane builds this service from.\n\n``context`` is a Files API object id (a ``.tar.gz`` of the build context),\nnever a host path or a git URL: the plane has no filesystem the caller can\nname, and a build's input has always been an object the caller could\nalready write. Compose's short form ``build: `` is accepted and\nmeans the same thing.\n\nEvery other compose ``build`` key (``args``, ``target``, ``secrets``,\n``ssh``, ``cache_from``, ``network``, ``no_cache``, ``pull``, ``labels``\n…) is refused by name through ``extra=\"forbid\"``, like the rest of the\ncompose surface." }, "SidecarDependsOn": { "properties": { "condition": { "type": "string", "enum": [ "service_started", "service_healthy", "service_completed_successfully" ], "title": "Condition", "default": "service_started" }, "required": { "type": "boolean", "title": "Required", "default": true } }, "additionalProperties": false, "type": "object", "title": "SidecarDependsOn" }, "SidecarDeploy": { "properties": { "resources": { "anyOf": [ { "$ref": "#/components/schemas/SidecarResourceSpec" }, { "type": "null" } ] } }, "additionalProperties": false, "type": "object", "title": "SidecarDeploy" }, "SidecarHealthcheck": { "properties": { "test": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "string" }, { "type": "null" } ], "title": "Test" }, "interval": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" } ], "title": "Interval", "default": "30s" }, "timeout": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" } ], "title": "Timeout", "default": "30s" }, "retries": { "type": "integer", "maximum": 100, "minimum": 1, "title": "Retries", "default": 3 }, "start_period": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" } ], "title": "Start Period", "default": "0s" }, "disable": { "type": "boolean", "title": "Disable", "default": false } }, "additionalProperties": false, "type": "object", "title": "SidecarHealthcheck", "description": "Compose ``healthcheck``, rendered as the sidecar's startup probe.\n\nThe agent's container starts only once every sidecar's check has passed,\nwhich is compose's ``depends_on: condition: service_healthy`` for the\n``main`` service, applied unconditionally." }, "SidecarResourceLimits": { "properties": { "cpus": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "null" } ], "title": "Cpus" }, "memory": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "null" } ], "title": "Memory" } }, "additionalProperties": false, "type": "object", "title": "SidecarResourceLimits" }, "SidecarResourceSpec": { "properties": { "limits": { "anyOf": [ { "$ref": "#/components/schemas/SidecarResourceLimits" }, { "type": "null" } ] }, "reservations": { "anyOf": [ { "$ref": "#/components/schemas/SidecarResourceLimits" }, { "type": "null" } ] } }, "additionalProperties": false, "type": "object", "title": "SidecarResourceSpec", "description": "Compose ``deploy.resources``: ``limits`` and ``reservations``." }, "SidecarService": { "properties": { "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Image" }, "build": { "anyOf": [ { "$ref": "#/components/schemas/SidecarBuild" }, { "type": "null" } ] }, "command": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "string" }, { "type": "null" } ], "title": "Command" }, "entrypoint": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "string" }, { "type": "null" } ], "title": "Entrypoint" }, "environment": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "type": "object" }, { "items": { "type": "string" }, "type": "array" } ], "title": "Environment" }, "working_dir": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Working Dir" }, "expose": { "items": { "anyOf": [ { "type": "integer" }, { "type": "string" } ] }, "type": "array", "title": "Expose" }, "ports": { "items": { "anyOf": [ { "type": "integer" }, { "type": "string" } ] }, "type": "array", "title": "Ports" }, "healthcheck": { "anyOf": [ { "$ref": "#/components/schemas/SidecarHealthcheck" }, { "type": "null" } ] }, "volumes": { "items": { "type": "string" }, "type": "array", "title": "Volumes" }, "depends_on": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "additionalProperties": { "anyOf": [ { "$ref": "#/components/schemas/SidecarDependsOn" }, { "type": "null" } ] }, "type": "object" }, { "type": "null" } ], "title": "Depends On" }, "deploy": { "anyOf": [ { "$ref": "#/components/schemas/SidecarDeploy" }, { "type": "null" } ] }, "restart": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Restart" } }, "additionalProperties": false, "type": "object", "title": "SidecarService", "description": "One compose service other than ``main``, rendered as a sidecar container." }, "SidecarVolume": { "properties": {}, "additionalProperties": false, "type": "object", "title": "SidecarVolume", "description": "A named volume: an ``emptyDir`` shared by the containers that mount it.\n\nDrivers, driver options and ``external`` all name storage outside the\npod, so they are refused by key." }, "SortDirection": { "type": "string", "enum": [ "asc", "desc" ], "title": "SortDirection", "description": "Sort direction for pagination ordering." }, "SpanStatus": { "type": "string", "enum": [ "Ok", "Error", "Unset" ], "title": "SpanStatus", "description": "Span status code values." }, "Task": { "properties": { "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Record creation timestamp" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "Last update timestamp" }, "org_id": { "type": "string", "format": "uuid", "title": "Org Id", "description": "Organization ID (required for tenant isolation)" }, "project_id": { "type": "string", "format": "uuid", "title": "Project Id", "description": "Project ID" }, "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Unique identifier (UUID7)" }, "title": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Title", "description": "Task title" }, "display_index": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Display Index" }, "status": { "$ref": "#/components/schemas/TaskStatus", "default": "pending" }, "kind": { "$ref": "#/components/schemas/TaskKind", "description": "Execution shape: agent conversation or one-shot process", "default": "agent" }, "member_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Member Id", "description": "Member who started this task" }, "automation_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Automation Id", "description": "CP automation that created this task (weak FK)" }, "runtime_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Runtime Id", "description": "CP-side Runtime this task is bound to (weak FK). Stamped on telemetry for per-Runtime analytics." }, "is_archived": { "type": "boolean", "title": "Is Archived", "default": false }, "started_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Started At", "description": "Actual compute start time" }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Completed At", "description": "Actual compute end time" }, "last_user_message_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last User Message At" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Mutable runtime state (agent session)" }, "conversation_metadata": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Conversation Metadata", "description": "Immutable filter dimensions stamped onto this task's conversation telemetry." }, "tags": { "items": { "type": "string" }, "type": "array", "title": "Tags", "description": "Free-form `key:value` grouping tags. Filter with `?tag=key:value`." }, "agent": { "anyOf": [ { "$ref": "#/components/schemas/AgentInfo" }, { "type": "null" } ], "description": "Runtime info for tasks that expose an interactive agent session" } }, "type": "object", "required": [ "org_id", "project_id" ], "title": "Task", "description": "Full task schema." }, "TaskCancelMode": { "type": "string", "enum": [ "abort", "drain" ], "title": "TaskCancelMode", "description": "How a task run cancel behaves.\n\n``abort`` interrupts the in-flight turn immediately and keeps the sandbox\nwarm, so the task drops back to ``idle`` and the same container is resumable\non the next prompt — what an interactive \"stop\" button wants. ``drain`` lets\nthe active turn finish and return control to the user, then tears the sandbox\ndown at the next settle boundary (the task lands terminal/``cancelled`` and\nthe next prompt cold-boots on the current base image) — the release path.\nSee docs/design/sandbox-drain-on-release.md." }, "TaskCancelRequest": { "properties": { "mode": { "$ref": "#/components/schemas/TaskCancelMode", "description": "Cancel behaviour: 'abort' (default) interrupts the in-flight turn now and keeps the sandbox warm/resumable; 'drain' lets the turn finish then tears the sandbox down at the next settle boundary (task -> cancelled). The bodyless call aborts.", "default": "abort" }, "drain_within_seconds": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "title": "Drain Within Seconds", "description": "Drain only: force teardown if the task has not reached a settle boundary within this many seconds. Omit to wait, bounded by the deployment drain ceiling." } }, "type": "object", "title": "TaskCancelRequest", "description": "Options for cancelling a task run.\n\nDefault (and the bodyless call) **aborts**: the in-flight turn is interrupted\nimmediately and the sandbox stays warm, so the task returns to ``idle`` and\nthe same container is resumable. Pass ``mode=drain`` to instead let the active\nturn finish and tear the sandbox down at the next settle boundary (the task\nlands ``cancelled`` and the next prompt cold-boots on the current base image);\na drained ``awaiting_user`` task keeps its ``metadata.pending_interrupts`` so\nthe HITL resume path rehydrates the question on the fresh sandbox.\nSee docs/design/sandbox-drain-on-release.md." }, "TaskCancelResponse": { "properties": { "id": { "type": "string", "title": "Id" } }, "type": "object", "required": [ "id" ], "title": "TaskCancelResponse", "description": "Response returned after cancelling a task run." }, "TaskCommand": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "task_id": { "type": "string", "format": "uuid", "title": "Task Id" }, "kind": { "$ref": "#/components/schemas/TaskCommandKind" }, "spec": { "additionalProperties": true, "type": "object", "title": "Spec" }, "status": { "$ref": "#/components/schemas/TaskCommandStatus" }, "exit_code": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Exit Code" }, "stdout": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Stdout" }, "stderr": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Stderr" }, "output_file_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Output File Id" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At" }, "started_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Started At" }, "finished_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Finished At" } }, "type": "object", "required": [ "id", "task_id", "kind", "spec", "status", "created_at", "updated_at" ], "title": "TaskCommand" }, "TaskCommandKind": { "type": "string", "enum": [ "exec", "upload", "download" ], "title": "TaskCommandKind" }, "TaskCommandStatus": { "type": "string", "enum": [ "queued", "running", "completed", "failed" ], "title": "TaskCommandStatus" }, "TaskCompose": { "properties": { "services": { "additionalProperties": { "$ref": "#/components/schemas/SidecarService" }, "type": "object", "title": "Services" }, "main": { "anyOf": [ { "$ref": "#/components/schemas/MainService" }, { "type": "null" } ] }, "volumes": { "additionalProperties": { "anyOf": [ { "$ref": "#/components/schemas/SidecarVolume" }, { "type": "null" } ] }, "type": "object", "title": "Volumes" } }, "additionalProperties": false, "type": "object", "title": "TaskCompose", "description": "The compose document that makes up a task's world: its services and named volumes.\n\nAccepts the compose file's own ``services`` mapping with ``main`` in it\n(Harbor's shape) and lifts ``main`` into its own field, so the persisted\nform is explicit about which entry is the agent slot." }, "TaskCreate": { "properties": { "title": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Title", "description": "Task title" }, "prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Prompt", "description": "Task prompt or description" }, "kind": { "$ref": "#/components/schemas/TaskKind", "description": "Execution shape. `agent` (default) is a conversation; `eval` is the same shape run as an evaluation trial, governed separately at admission. `process` is internal-only and rejected here.", "default": "agent" }, "agent_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Name", "description": "Recipe agent to run; omitted -> the recipe default (agents/agent.yaml)" }, "runtime_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Runtime Id", "description": "Runtime to bind this task to. Ignored when the caller presents a runner credential (the JWT claim is authoritative); honored for non-runner session/browser callers and validated against the caller's project." }, "recipe_patch": { "anyOf": [ { "$ref": "#/components/schemas/TaskRecipePatch" }, { "type": "null" } ], "description": "Operator-only development input. The patch File must belong to the authenticated Operator Task and match the selected Runtime's deployed Recipe checkout. Other callers are rejected." }, "repositories": { "anyOf": [ { "items": { "$ref": "#/components/schemas/TaskRepoRequest" }, "type": "array" }, { "type": "null" } ], "title": "Repositories", "description": "Workspace repositories to clone into the sandbox's workspace/repos/ for this task: {repo, ref?, depth?}. Each repo must be listed in the runtime's runtime.github.repositories grant (and registered to the caller's project) — the recipe decides what may be cloned, this list decides what is cloned and at what ref. Omit `ref` for the repository's default branch — the clone takes the remote's HEAD, so nothing is stored or kept in sync — and `depth` defaults to a shallow clone. An entry outside the grant, or one that fails to resolve at launch, is logged and dropped, never a launch failure." }, "idle_timeout_seconds": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "title": "Idle Timeout Seconds", "description": "Override the interactive idle window (seconds) before the sandbox is torn down. 0 tears down as soon as it's provisioned (e.g. an empty-prompt warm/bake run); omit to use the deployment default. Clamped to the task timeout." }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Optional client task metadata." }, "conversation_metadata": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Conversation Metadata", "description": "Immutable filter dimensions for the conversation this task creates. Filter the resulting conversation with GET /v1/conversations?metadata=key:value. Keys must be one level ([A-Za-z0-9_-], no `.`), values must be non-empty strings of at most 1024 characters, and at most 64 keys are accepted. These dimensions land in append-only telemetry and cannot later be edited or deleted." }, "tags": { "items": { "type": "string" }, "type": "array", "title": "Tags", "description": "Free-form tags to stamp on the task at create time, conventionally 'key:value' (e.g. 'team:acme'). Filter with `?tag=team:acme`. Shared: any member whose own tags intersect these can read and write the task, so tagging is how a task is handed to a cohort." }, "files": { "anyOf": [ { "items": { "$ref": "#/components/schemas/TaskFileRef" }, "type": "array", "maxItems": 100 }, { "type": "null" } ], "title": "Files", "description": "Files API references to attach to this task. Materialized into the sandbox workspace at boot and announced to the agent. Equivalent to setting metadata.conversation_files.uploads, which stays accepted." }, "commands": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Commands", "description": "Accept commands on POST /v1/tasks/{id}/commands (exec, upload, download) for this evaluation trial. Off by default: a trial that only needs its agent to run never opens the exec surface. Requires `kind: eval`." }, "compose": { "anyOf": [ { "$ref": "#/components/schemas/TaskCompose" }, { "type": "null" } ], "description": "Compose services to run beside the agent for an evaluation trial, in the task's own `docker-compose.yaml` shape: a `services` mapping (`main` is the agent slot and may carry only `volumes` and `depends_on`) plus named `volumes`. Each other service becomes a container of the sandbox pod, fresh per task, reachable from the agent by its service name on the pod's loopback, under the same gVisor sandbox and NetworkPolicy as the agent, as a distinct non-root user with none of the runtime's platform environment. Supported per service: image, command, entrypoint, environment, working_dir, expose/ports (container port only), healthcheck, named volumes, depends_on, deploy.resources. Anything a pod cannot honour (network_mode, networks, extra_hosts, privileged, cap_add, devices, bind mounts, build, user) is refused by name. Only `kind: eval` tasks may carry it, and such a task always runs in-cluster." }, "fork_share_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Fork Share Id", "description": "Fork from a shared conversation: the /v1/shares grant id for the source conversation. Persisted into metadata.forked_response and used by the runtime as the read capability when hydrating the forked history — it is itself the permissions boundary, so no share lookup happens at create. The fork seeds the new task with the whole shared conversation." } }, "additionalProperties": false, "type": "object", "title": "TaskCreate", "description": "Schema for creating a task.\n\nRunner credentials remain authoritative for runtime selection: a runner JWT\n(or the in-process MCP override) always wins. Non-runner (session/browser)\ncallers, which carry no runtime claim, may bind a runtime by passing\n``runtime_id`` in the body — it is validated against the caller's project at\ncreate time." }, "TaskCreateResponse": { "properties": { "task": { "$ref": "#/components/schemas/Task" }, "run": { "$ref": "#/components/schemas/TaskRun" } }, "type": "object", "required": [ "task", "run" ], "title": "TaskCreateResponse", "description": "Response returned after creating a task and its initial run." }, "TaskFileRef": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Files API file id" }, "name": { "anyOf": [ { "type": "string", "maxLength": 255, "minLength": 1 }, { "type": "null" } ], "title": "Name", "description": "Workspace-relative name to mount the file as. Optional — the Files API already knows the file's name, so supply this only to override it (mount under a different name, or nest it in a subdirectory)." }, "size_bytes": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "title": "Size Bytes", "description": "Declared size, checked against the runtime's 25 MB cap" } }, "type": "object", "required": [ "id" ], "title": "TaskFileRef", "description": "A reference to an already-uploaded Files API row attached to a task.\n\nBytes go through `POST /v1/files` first; a task only ever carries the\nreference. The name is the workspace-relative path the runtime materializes\nto under the task's files dir, so it is validated here rather than left to\nthe runtime's path guard — a 422 at the boundary beats a file silently\nskipped at boot." }, "TaskInclude": { "type": "string", "enum": [ "agent" ], "title": "TaskInclude", "description": "Opt-in, non-default enrichments for a task read (`GET /v1/tasks/{id}?include=`).\n\nThe default task read is the cheapest path: a single-row Postgres lookup with\nno enrichment. Each value here names an extra projection that costs more than\nthat bare read (an extra round-trip or join) and so is only computed when the\ncaller explicitly asks for it. Repeatable: `?include=agent&include=...`.\n\n- ``agent`` — live sandbox status for an interactive, in-flight task, read\n from the Restate task workflow (one extra round-trip)." }, "TaskKind": { "type": "string", "enum": [ "agent", "eval", "process" ], "title": "TaskKind", "description": "Discriminates the task execution shapes.\n\n``agent`` boots the TypeScript runtime-agent image and runs an interactive\nLLM agent. ``eval`` is the same execution shape run as an evaluation trial\n(a Harbor task, a regression suite): it exists as its own kind so admission\nand concurrency can be governed separately from production conversations\nwithout inspecting metadata. ``process`` boots a one-shot Python script in\nthe separate runtime-process image and reports its result through the\nexisting RESULT event / completion-promise path. See\ndocs/design/process-tasks.md." }, "TaskPrompt": { "properties": { "text": { "type": "string", "minLength": 1, "title": "Text", "description": "Prompt text for the run" }, "images": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Images", "description": "Optional base64-encoded image inputs" } }, "type": "object", "required": [ "text" ], "title": "TaskPrompt", "description": "Cursor-style prompt payload for a task run." }, "TaskRecipePatch": { "properties": { "patch_file_id": { "type": "string", "format": "uuid", "title": "Patch File Id" }, "checkout_base_commit_sha": { "type": "string", "maxLength": 64, "minLength": 40, "pattern": "^[0-9a-fA-F]+$", "title": "Checkout Base Commit Sha" }, "checkout_repository_name": { "type": "string", "pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$", "title": "Checkout Repository Name" }, "checkout_recipe_sub_path": { "type": "string", "maxLength": 1024, "title": "Checkout Recipe Sub Path" } }, "additionalProperties": false, "type": "object", "required": [ "patch_file_id", "checkout_base_commit_sha", "checkout_repository_name", "checkout_recipe_sub_path" ], "title": "TaskRecipePatch", "description": "Operator-owned Recipe patch applied to one development Task.\n\nThe client supplies only File and checkout provenance. The Tasks service\nresolves the checksum and complete spawn contract from trusted server\nstate before it persists the Task." }, "TaskRepoRequest": { "properties": { "repo": { "type": "string", "title": "Repo", "description": "Registered repository slug, \"owner/name\"." }, "ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ref", "description": "Branch, tag, or full 40-character commit sha to check out. Omit it for the repository's default branch — the clone takes the remote's HEAD, so nothing has to be stored or kept in sync. An abbreviated sha is not recognised as a pin: it is passed to git as a branch name, so the clone fails and the repository is dropped." }, "depth": { "type": "integer", "maximum": 1000, "minimum": 0, "title": "Depth", "description": "Shallow-clone depth. 0 clones the full history.", "default": 1 } }, "additionalProperties": false, "type": "object", "required": [ "repo" ], "title": "TaskRepoRequest", "description": "One `POST /v1/tasks` `repositories[]` entry: a repository plus the state to clone it at." }, "TaskRun": { "properties": { "id": { "type": "string", "title": "Id", "description": "Run identifier. Use 'current' until task runs are persisted separately." }, "task_id": { "type": "string", "format": "uuid", "title": "Task Id", "description": "Task that owns this run" }, "status": { "$ref": "#/components/schemas/TaskStatus", "description": "Current run status" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At", "description": "Best available task start timestamp" }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updated At", "description": "Most recent activity timestamp for this run" } }, "type": "object", "required": [ "id", "task_id", "status" ], "title": "TaskRun", "description": "Run-shaped view over the currently active task execution." }, "TaskRunCreate": { "properties": { "delivery_id": { "anyOf": [ { "type": "string", "maxLength": 256, "minLength": 1 }, { "type": "null" } ], "title": "Delivery Id", "description": "Stable identity of this message across HTTP retries" }, "prompt": { "anyOf": [ { "$ref": "#/components/schemas/TaskPrompt" }, { "type": "null" } ], "description": "Prompt payload for the run" }, "kind": { "anyOf": [ { "type": "string", "enum": [ "prompt", "steer" ] }, { "type": "null" } ], "title": "Kind", "description": "Optional caller intent. 'prompt' requests a fresh turn; 'steer' injects into the active turn and falls back to prompt if no turn is active." }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Metadata patch merged into the task before dispatching the run." }, "runtime_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Runtime Id", "description": "Runtime to rebind the task to if this run has to provision a new sandbox — resuming an idle task whose sandbox was reaped, or reopening a terminal one. Ignored while a sandbox is live, so a steer never changes version mid-turn. Omit to keep the task's existing pin." }, "files": { "anyOf": [ { "items": { "$ref": "#/components/schemas/TaskFileRef" }, "type": "array", "maxItems": 100 }, { "type": "null" } ], "title": "Files", "description": "Files API references to attach to this turn. Materialized into the live sandbox before the turn runs (no restart needed) and merged into the task's conversation_files so a later restart replays them." }, "resume": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Resume", "description": "AG-UI resume entries answering the task's pending interrupt." } }, "type": "object", "title": "TaskRunCreate", "description": "Schema for creating a new run on an interactive task." }, "TaskRunResponse": { "properties": { "run": { "$ref": "#/components/schemas/TaskRun" } }, "type": "object", "required": [ "run" ], "title": "TaskRunResponse", "description": "Response returned after creating a task run." }, "TaskStatus": { "type": "string", "enum": [ "pending", "queued", "scheduled", "running", "awaiting_user", "idle", "completed", "failed", "cancelling", "cancelled" ], "title": "TaskStatus", "description": "Task execution status." }, "TaskUpdate": { "properties": { "title": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Title", "description": "Task title" }, "is_archived": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Archived", "description": "Archive state" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Metadata patch (merged into existing)." }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags", "description": "Replaces the tag list wholesale (unlike metadata, which is merged). Omit to leave tags untouched; pass [] to clear them." } }, "type": "object", "title": "TaskUpdate", "description": "Schema for updating mutable task fields." }, "TrackEvent": { "properties": { "id": { "type": "string", "title": "Id", "description": "Event ID (LogAttributes.event.id; the entity id for fold families)" }, "timestamp": { "type": "string", "format": "date-time", "title": "Timestamp", "description": "Event timestamp (per-family semantics; see docs)" }, "event_name": { "type": "string", "const": "introspection.track", "title": "Event Name", "default": "introspection.track" }, "trace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trace Id", "description": "Trace ID (hex string)" }, "span_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Span Id", "description": "Span ID (hex string)" }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Conversation Id", "description": "Source conversation ID" }, "service_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Service Name", "description": "OTel service name" }, "environment": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Environment", "description": "Environment lane (staging/production)" }, "runtime_group_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Runtime Group Id", "description": "Resolved runtime group ID" }, "runtime_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Runtime Id", "description": "Resolved runtime ID" }, "experiment_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Experiment Id", "description": "Resolved experiment ID" }, "recipe_git_commit_sha": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recipe Git Commit Sha", "description": "Recipe git commit SHA" }, "payload": { "$ref": "#/components/schemas/TrackPayload" } }, "type": "object", "required": [ "id", "timestamp", "payload" ], "title": "TrackEvent", "description": "One arbitrary SDK track event projected through a stable family." }, "TrackPayload": { "properties": { "name": { "type": "string", "title": "Name", "description": "Original event.name supplied to track()" }, "properties": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Properties", "description": "Event properties.* values" } }, "type": "object", "required": [ "name" ], "title": "TrackPayload", "description": "One arbitrary event emitted through the SDK ``track()`` surface." }, "UploadCommand": { "properties": { "kind": { "type": "string", "const": "upload", "title": "Kind", "default": "upload" }, "file_id": { "type": "string", "format": "uuid", "title": "File Id" }, "path": { "type": "string", "title": "Path" } }, "additionalProperties": false, "type": "object", "required": [ "file_id", "path" ], "title": "UploadCommand", "description": "Copy a Files API object of the project to ``path`` inside the sandbox." }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } }, "securitySchemes": { "HTTPBearer": { "type": "http", "scheme": "bearer" } } }, "tags": [ { "name": "tasks", "x-displayName": "Tasks" }, { "name": "automations", "x-displayName": "Automations" }, { "name": "files", "x-displayName": "Files" }, { "name": "shares", "x-displayName": "Shares" }, { "name": "metrics", "x-displayName": "Metrics" }, { "name": "conversations", "x-displayName": "Conversations" }, { "name": "events", "x-displayName": "Events" } ] }