{ "openapi": "3.0.0", "info": { "title": "Warp Platform API", "version": "1.0.0", "description": "API for creating, managing, and querying factory and cloud agent runs.\n\nSend work to factories, start standalone agents, list runs, and retrieve\ndetailed run information.\n", "contact": { "name": "Warp Support", "url": "https://docs.warp.dev", "email": "support@warp.dev" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://app.warp.dev/api/v1", "description": "Warp Server" } ], "tags": [ { "name": "agent", "description": "Operations for running and managing cloud agents" }, { "name": "schedules", "description": "Operations for creating and managing scheduled agents" }, { "name": "factory", "description": "Operations for creating and managing factories" }, { "name": "benchmark", "description": "Operations for managing benchmark suites, tasks, runs, trials, and results" }, { "name": "networking", "description": "Networking information for Warp-hosted agents" } ], "paths": { "/networking/egress-ranges": { "get": { "summary": "List Warp-hosted agent egress ranges", "description": "Return the canonical IP network ranges used by outbound requests from\nWarp-hosted agents.\n", "operationId": "getEgressRanges", "tags": [ "networking" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/TeamUidHeaderParam" } ], "responses": { "200": { "description": "Current Warp-hosted agent egress ranges", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EgressRangesResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory": { "get": { "summary": "List factories", "description": "List factories accessible to the authenticated principal, restricted\nto the request's active team when one is set. An optional team_uid\nquery parameter overrides the active team and restricts results to a\nsingle team, and an optional search query parameter filters by a\ncase-insensitive substring match on the factory name or alias.\n", "operationId": "listFactories", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/TeamUidHeaderParam" }, { "name": "team_uid", "in": "query", "description": "Optional team UID to filter factories by ownership. Takes\nprecedence over the X-Warp-Team-Uid header.\n", "required": false, "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Case-insensitive substring search over the factory name and\nalias.\n", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of factories to return (default 50, max 100).", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor returned by a previous list response.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of factories", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListFactoriesResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory/{uid}": { "get": { "summary": "Get a factory", "description": "Get a factory by its UID.", "operationId": "getFactory", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uid", "in": "path", "description": "The public UID of the factory.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Factory details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Factory" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "404": { "description": "Factory not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory-inbox": { "get": { "summary": "List Factory inbox notifications", "description": "List unresolved notifications across factories authorized for the\nauthenticated principal and active team. The default `mine` scope\npreserves the personal Inbox and requires user credentials. The\n`team` scope lists notifications assigned to any recipient and\ncan be used by user or agent credentials. Personal read state\n(`is_read`) is included only in `mine` scope and omitted in `team`\nscope, including when filtering by recipient.\n", "operationId": "listFactoryInbox", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/TeamUidHeaderParam" }, { "name": "scope", "in": "query", "description": "`mine` returns notifications assigned to the authenticated user\nand is the default. `team` returns notifications across live\nrecipients in the authorized Factory and team scope.\n", "required": false, "schema": { "$ref": "#/components/schemas/FactoryInboxScope" } }, { "name": "factory_uid", "in": "query", "description": "Exact Factory UID filter, intersected with authorized factories.", "required": false, "schema": { "type": "string" } }, { "name": "recipient_uid", "in": "query", "description": "Exact public user UID filter within the authorized Factory and\nteam scope. In `mine` scope this can only match the authenticated\nuser.\n", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of items to return. Defaults to 50.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from page_info.next_cursor.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "One page of inbox notifications.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListFactoryInboxResponse" } } } }, "400": { "description": "Invalid scope, limit, cursor, or principal for the requested scope", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "404": { "description": "Factory task APIs are not available", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory-inbox/notifications/read": { "post": { "summary": "Mark inbox notifications as read", "description": "Mark a batch of notifications as read for the authenticated user after\nchecking access to each factory. The caller must be a recipient of\neach existing notification, and the notification must remain active;\notherwise its outcome is unsuccessful. Missing notifications are\nsuccessful no-ops. Outcomes are returned in request order.\n", "operationId": "markFactoryInboxNotificationsRead", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactoryInboxMutationRequest" } } } }, "responses": { "200": { "description": "Per-notification outcomes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactoryInboxMutationResponse" } } } }, "400": { "description": "Invalid notification list", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Caller is not a user", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory-inbox/notifications/unread": { "post": { "summary": "Mark inbox notifications as unread", "description": "Mark a batch of notifications as unread for the authenticated user\nafter checking access to each factory. The caller must be a recipient\nof each existing notification, and the notification must remain active;\notherwise its outcome is unsuccessful. Missing notifications are\nsuccessful no-ops. Outcomes are returned in request order.\n", "operationId": "markFactoryInboxNotificationsUnread", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactoryInboxMutationRequest" } } } }, "responses": { "200": { "description": "Per-notification outcomes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactoryInboxMutationResponse" } } } }, "400": { "description": "Invalid notification list", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Caller is not a user", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory/{uid}/tasks": { "post": { "summary": "Create a factory task", "description": "Create a task in a factory, bound to an existing agent conversation.\ntitle and conversation_id are required. The stage defaults to TRIAGE. The\nconversation's most recent run must be owned by the factory's team,\nand a conversation may be bound to at most one live task across all\nfactories.\n", "operationId": "createFactoryTask", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uid", "in": "path", "description": "The public UID of the factory.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactoryTaskCreateRequest" } } } }, "responses": { "201": { "description": "Factory task created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactoryTask" } } } }, "400": { "description": "Invalid request body or conversation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "404": { "description": "Factory not found or not accessible", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The conversation is already bound to a live task", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List factory tasks", "description": "List the factory's tasks with optional filtering and search. List\nresponses are lean by default; set full_list=true to include\ncanonical ticket metadata and derived outputs for the returned page.\n", "operationId": "listFactoryTasks", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uid", "in": "path", "description": "The public UID of the factory.", "required": true, "schema": { "type": "string" } }, { "name": "stage", "in": "query", "description": "Filter by task stage. Can be specified multiple times to match any\nof the given stages.\n", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FactoryTaskStage" } }, "style": "form", "explode": true }, { "name": "created_by", "in": "query", "description": "Filter to tasks whose seed run was started by any of these\nteammates, each given as their email address. Can be specified\nmultiple times to match any of the given teammates.\n", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "q", "in": "query", "description": "Case-insensitive substring search over the task title.", "required": false, "schema": { "type": "string" } }, { "name": "created_after", "in": "query", "description": "Filter to tasks created after this timestamp (RFC3339 format).", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "description": "Filter to tasks created before this timestamp (RFC3339 format).", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_after", "in": "query", "description": "Filter to tasks updated after this timestamp (RFC3339 format).", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "sort_by", "in": "query", "description": "Sort field for results.", "required": false, "schema": { "type": "string", "enum": [ "created_at", "updated_at" ], "default": "created_at" } }, { "name": "sort_order", "in": "query", "description": "Sort direction.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, { "name": "limit", "in": "query", "description": "Maximum number of tasks to return (default 50, max 100).", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor returned by a previous list response.\nValid only for the sort_by/sort_order it was issued under; omit\nto restart the listing.\n", "required": false, "schema": { "type": "string" } }, { "name": "full_list", "in": "query", "description": "Include canonical ticket_source and ticket_id metadata from each\ntask's bound run, plus its derived outputs. Defaults to false.\n", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "include_current_run", "in": "query", "description": "Include each task's current top-level run, resolved in one batch\nfor the returned page. Defaults to false.\n", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "List of factory tasks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListFactoryTasksResponse" } } } }, "400": { "description": "Invalid filter, sort, limit, cursor, full_list, or include_current_run value", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "404": { "description": "Factory not found or not accessible", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory/{uid}/runs": { "post": { "summary": "Dispatch a run to a factory", "description": "Dispatch a run to a factory, using prompt as the run's\nprompt and an optional title, ticket_ref, and ticket_url. Returns\nthe created run; its factory task is created asynchronously and can\nbe resolved afterwards with GET /factory/{uid}/task-by-run.\n", "operationId": "createFactoryRun", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uid", "in": "path", "description": "The public UID of the factory.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactoryRunRequest" } } } }, "responses": { "201": { "description": "Run dispatched successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactoryRunResponse" } } } }, "400": { "description": "Invalid request body or ticket_ref", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "404": { "description": "Factory not found or not accessible", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The factory has no foreman agent to receive work", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory/{uid}/tasks/{task_uid}": { "get": { "summary": "Get a factory task", "description": "Get a task with its derived outputs, newest-first.\n", "operationId": "getFactoryTask", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uid", "in": "path", "description": "The public UID of the factory.", "required": true, "schema": { "type": "string" } }, { "name": "task_uid", "in": "path", "description": "The public UID of the task.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Factory task details with derived outputs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactoryTask" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "404": { "description": "Factory or task not found under this factory", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update a factory task", "description": "Partially update a task's title, description, and/or stage. Last\nwrite wins. Stage writes are unrestricted: any stage-to-stage\ntransition is allowed, including moving backwards or to completion.\n", "operationId": "updateFactoryTask", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uid", "in": "path", "description": "The public UID of the factory.", "required": true, "schema": { "type": "string" } }, { "name": "task_uid", "in": "path", "description": "The public UID of the task.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactoryTaskPatchRequest" } } } }, "responses": { "200": { "description": "Factory task updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactoryTask" } } } }, "400": { "description": "Invalid request body", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "404": { "description": "Factory or task not found under this factory", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete a factory task", "description": "Soft-delete a task. The task disappears from list and get responses\nimmediately, and its conversation may be bound to a new task.\nDeleting a task never deletes artifacts or the conversation.\n", "operationId": "deleteFactoryTask", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uid", "in": "path", "description": "The public UID of the factory.", "required": true, "schema": { "type": "string" } }, { "name": "task_uid", "in": "path", "description": "The public UID of the task.", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Factory task deleted successfully" }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "404": { "description": "Factory or task not found under this factory", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory/{uid}/tasks/{task_uid}/cancel": { "post": { "summary": "Stop a factory task", "description": "Cancel the task's current top-level run and move the task to\nCANCELLED. Every non-terminal descendant of the root run is\ncancelled as well.\n", "operationId": "cancelFactoryTask", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uid", "in": "path", "description": "The public UID of the factory.", "required": true, "schema": { "type": "string" } }, { "name": "task_uid", "in": "path", "description": "The public UID of the task.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Task stopped. The response reflects the refreshed task, including\nits current run and stage.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactoryTask" } } } }, "400": { "description": "The resolved current run is already in a terminal state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The caller can see the task but lacks access to its resolved\ncurrent run.\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Factory or task not found under this factory, or the task has no\nresolvable current run.\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The resolved current run is PENDING and cannot be cancelled yet.\nRetry after a moment.\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The resolved current run's type does not support server-side cancellation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory/{uid}/task-by-conversation": { "get": { "summary": "Get a factory task by conversation", "description": "Get the factory task bound to an agent conversation. Conversation bindings are\nunique across factories, but the lookup is factory-scoped: a task\nowned by a different factory is 404.\n", "operationId": "getFactoryTaskByConversation", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uid", "in": "path", "description": "The public UID of the factory.", "required": true, "schema": { "type": "string" } }, { "name": "conversation_id", "in": "query", "description": "The agent conversation ID the task is bound to.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Factory task details with derived outputs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactoryTask" } } } }, "400": { "description": "Missing conversation_id", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "404": { "description": "Factory not accessible, or no live task bound to the conversation under this factory", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory/{uid}/task-by-run": { "get": { "summary": "Get a factory task by run", "description": "Get the factory task that owns a run: the task bound to the conversation\nof the run's root ancestor. The lookup is factory-scoped: a task owned by\na different factory is 404.\n", "operationId": "getFactoryTaskByRun", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uid", "in": "path", "description": "The public UID of the factory.", "required": true, "schema": { "type": "string" } }, { "name": "run_id", "in": "query", "description": "Any run ID in the task's run tree.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Factory task details with derived outputs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactoryTask" } } } }, "400": { "description": "Missing run_id", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "404": { "description": "Factory not accessible, the run does not resolve to a live task, or the task belongs to a different factory", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory/{uid}/metrics": { "get": { "summary": "Get factory metrics", "description": "Aggregate productivity metrics for a factory over a UTC date range:\nrun count, distinct PR count (from PR artifacts, deduped by URL at\nfirst appearance), autonomy, impact, and PR latency. Cost metrics\nlive under /factory/{uid}/costs. Pass group_by_period to additionally\nreceive per-period series aligned to period_list.\n", "operationId": "getFactoryMetrics", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uid", "in": "path", "description": "The public UID of the factory.", "required": true, "schema": { "type": "string" } }, { "name": "start_date", "in": "query", "description": "Inclusive RFC3339 range start (UTC). Defaults to end_date minus 30 days.", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "end_date", "in": "query", "description": "Exclusive RFC3339 range end (UTC). Defaults to now.", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "group_by_period", "in": "query", "description": "Optional binning granularity; when omitted, the response\ncontains aggregates only. Binned requests are capped at 365\nperiods.\n", "required": false, "schema": { "$ref": "#/components/schemas/FactoryMetricsGroupByPeriod" } } ], "responses": { "200": { "description": "Factory metrics for the requested range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactoryMetricsResponse" } } } }, "400": { "description": "Invalid date range or group_by_period, or more than 365 periods requested", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "404": { "description": "Factory not found or not accessible", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/FactoryMetricsRateLimited" }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory/{uid}/costs/per-pr": { "get": { "summary": "Get factory cost per PR", "description": "Mean per-PR attributed cost for a factory over a UTC date range,\nwith per-component dollar breakdowns. Previously served as\ncost_per_pr on GET /factory/{uid}/metrics. Pass group_by_period to\nadditionally receive per-period series aligned to period_list.\n", "operationId": "getFactoryCostPerPR", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uid", "in": "path", "description": "The public UID of the factory.", "required": true, "schema": { "type": "string" } }, { "name": "start_date", "in": "query", "description": "Inclusive RFC3339 range start (UTC). Defaults to end_date minus 30 days.", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "end_date", "in": "query", "description": "Exclusive RFC3339 range end (UTC). Defaults to now.", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "group_by_period", "in": "query", "description": "Optional binning granularity; when omitted, the response\ncontains aggregates only. Binned requests are capped at 365\nperiods.\n", "required": false, "schema": { "$ref": "#/components/schemas/FactoryMetricsGroupByPeriod" } } ], "responses": { "200": { "description": "Cost per PR for the requested range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactoryCostPerPRResponse" } } } }, "400": { "description": "Invalid date range or group_by_period, or more than 365 periods requested", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "404": { "description": "Factory not found or not accessible", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/FactoryMetricsRateLimited" }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory/{uid}/costs/breakdown": { "get": { "summary": "Get factory spend grouped by a dimension", "description": "The factory's spend over a UTC date range, grouped by source, user,\nagent, or model. groups lists every entity with nonzero spend in the\nrange (uncapped); UNKNOWN sorts last. Pass group_by_period to\nadditionally receive per-period series aligned to period_list.\n", "operationId": "getFactoryCostBreakdown", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uid", "in": "path", "description": "The public UID of the factory.", "required": true, "schema": { "type": "string" } }, { "name": "group_by", "in": "query", "description": "The dimension to group spend by.", "required": true, "schema": { "$ref": "#/components/schemas/FactoryCostBreakdownGroupBy" } }, { "name": "start_date", "in": "query", "description": "Inclusive RFC3339 range start (UTC). Defaults to end_date minus 30 days.", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "end_date", "in": "query", "description": "Exclusive RFC3339 range end (UTC). Defaults to now.", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "group_by_period", "in": "query", "description": "Optional binning granularity; when omitted, the response\ncontains aggregates only. Binned requests are capped at 365\nperiods.\n", "required": false, "schema": { "$ref": "#/components/schemas/FactoryMetricsGroupByPeriod" } } ], "responses": { "200": { "description": "Grouped spend for the requested range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactoryCostBreakdownResponse" } } } }, "400": { "description": "Missing or invalid group_by, invalid date range or group_by_period, or more than 365 periods requested", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Factory not found or not accessible", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/FactoryMetricsRateLimited" }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory/{uid}/costs/per-pr/top": { "get": { "summary": "Get the factory's most expensive PRs", "description": "The costliest PRs first seen in the range, most expensive first, with\nper-component cost breakdowns, attribution from each PR's earliest\nlive root run, and PR detail collected from code-forge webhooks.\nPRs that predate webhook PR-fact collection still appear, with null\ndetail fields.\n", "operationId": "getFactoryTopPRs", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uid", "in": "path", "description": "The public UID of the factory.", "required": true, "schema": { "type": "string" } }, { "name": "start_date", "in": "query", "description": "Inclusive RFC3339 range start (UTC). Defaults to end_date minus 30 days.", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "end_date", "in": "query", "description": "Exclusive RFC3339 range end (UTC). Defaults to now.", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "description": "Maximum PRs to return. Defaults to 20; at most 50.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "The factory's most expensive PRs for the requested range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactoryTopPRsResponse" } } } }, "400": { "description": "Invalid date range or limit", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "404": { "description": "Factory not found or not accessible", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/FactoryMetricsRateLimited" }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory/{uid}/pull-requests": { "get": { "summary": "List the factory's pull requests", "description": "One record per pull request produced by the factory's runs, newest\nopened first. A PR someone opened in one of the factory's\nrepositories without a factory run (by hand, for example) is not\nlisted. Each record carries the PR's identity, state and times,\nsize, human interactions, the runs that produced it, and its cycle\ntime. Pages are keyset-paginated: pass page_info.next_cursor back as\ncursor to continue. Pass updated_after to sync incrementally.\n", "operationId": "listFactoryPullRequests", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uid", "in": "path", "description": "The public UID of the factory.", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Records per page. Defaults to 50; at most 500.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from a previous page's page_info.next_cursor.", "required": false, "schema": { "type": "string" } }, { "name": "repo", "in": "query", "description": "Only PRs in this repository, as owner/repo (case-insensitive).", "required": false, "schema": { "type": "string" } }, { "name": "state", "in": "query", "description": "Only PRs in these states. Can be specified multiple times to match any of the given states.\n", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FactoryPullRequestState" } } }, { "name": "opened_after", "in": "query", "description": "Only PRs opened after this RFC3339 time (exclusive).", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "opened_before", "in": "query", "description": "Only PRs opened before this RFC3339 time (exclusive).", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "merged_after", "in": "query", "description": "Only PRs merged after this RFC3339 time (exclusive).", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "merged_before", "in": "query", "description": "Only PRs merged before this RFC3339 time (exclusive).", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_after", "in": "query", "description": "Only PRs whose updated_at is after this RFC3339 time\n(exclusive). updated_at tracks the PR on the code host; fields\nderived from the factory's runs (runs, kickoff_at,\nhuman_interactions.follow_up_message, and the kickoff-based\ncycle_time stages) can change without moving it.\n", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "One page of the factory's pull requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactoryPullRequestsResponse" } } } }, "400": { "description": "Invalid limit, cursor, state, or timestamp filter, or a time window whose *_after bound is not before its *_before bound", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "404": { "description": "Factory not found or not accessible", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/FactoryMetricsRateLimited" }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory/{uid}/metrics/run-breakdown": { "get": { "summary": "Get the factory's run counts grouped by a dimension", "description": "The factory's run counts over a UTC date range, grouped by one\ndimension. Pass group_by_period to additionally receive per-period\nseries aligned to period_list.\n", "operationId": "getFactoryRunBreakdown", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uid", "in": "path", "description": "The public UID of the factory.", "required": true, "schema": { "type": "string" } }, { "name": "group_by", "in": "query", "description": "The dimension to group run counts by.", "required": true, "schema": { "$ref": "#/components/schemas/FactoryRunBreakdownGroupBy" } }, { "name": "start_date", "in": "query", "description": "Inclusive RFC3339 range start (UTC). Defaults to end_date minus 30 days.", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "end_date", "in": "query", "description": "Exclusive RFC3339 range end (UTC). Defaults to now.", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "group_by_period", "in": "query", "description": "Optional binning granularity; when omitted, the response\ncontains aggregates only. Binned requests are capped at 365\nperiods.\n", "required": false, "schema": { "$ref": "#/components/schemas/FactoryMetricsGroupByPeriod" } } ], "responses": { "200": { "description": "Grouped run counts for the requested range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactoryRunBreakdownResponse" } } } }, "400": { "description": "Missing or invalid group_by, invalid date range or group_by_period, or more than 365 periods requested", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Factory not found or not accessible", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/FactoryMetricsRateLimited" }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory/{uid}/costs/per-pr/by-size": { "get": { "summary": "Get the factory's PR cost distribution grouped by PR size", "description": "The mean per-PR attributed cost of the factory's PRs first seen in\na UTC date range, grouped by PR size. Pass group_by_period to\nadditionally receive per-period mean series aligned to\nperiod_list.\n", "operationId": "getFactoryCostByPRSize", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uid", "in": "path", "description": "The public UID of the factory.", "required": true, "schema": { "type": "string" } }, { "name": "start_date", "in": "query", "description": "Inclusive RFC3339 range start (UTC). Defaults to end_date minus 30 days.", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "end_date", "in": "query", "description": "Exclusive RFC3339 range end (UTC). Defaults to now.", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "group_by_period", "in": "query", "description": "Optional binning granularity; when omitted, the response\ncontains aggregates only. Binned requests are capped at 365\nperiods.\n", "required": false, "schema": { "$ref": "#/components/schemas/FactoryMetricsGroupByPeriod" } } ], "responses": { "200": { "description": "Cost-by-size distribution for the requested range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactoryCostByPRSizeResponse" } } } }, "400": { "description": "Invalid date range or group_by_period, or more than 365 periods requested", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Factory not found or not accessible", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/FactoryMetricsRateLimited" }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent": { "get": { "summary": "List available agent skills", "description": "Retrieve a list of available agents (skills) that can be used to run tasks.\nAgents are discovered from environments or a specific repository.\n", "operationId": "listAgents", "deprecated": true, "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/TeamUidHeaderParam" }, { "name": "repo", "in": "query", "description": "Optional repository specification to list agents from (format: \"owner/repo\").\nIf not provided, lists agents from all accessible environments.\n", "required": false, "schema": { "type": "string" } }, { "name": "refresh", "in": "query", "description": "When true, clears the agent list cache before fetching.\nUse this to force a refresh of the available agents.\n", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "sort_by", "in": "query", "description": "Sort order for the returned agents.\n- \"name\": Sort alphabetically by name (default)\n- \"last_run\": Sort by most recently used\n", "required": false, "schema": { "type": "string", "enum": [ "name", "last_run" ] } }, { "name": "include_malformed_skills", "in": "query", "description": "When true, includes skills whose SKILL.md file exists but is\nmalformed. These variants will have a non-empty `error` field\ndescribing the parse failure. Defaults to false.\n", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "List of available agents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAgentsResponse" } } } }, "400": { "description": "Invalid repository specification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/connected-self-hosted-workers": { "get": { "summary": "List connected self-hosted workers", "description": "Retrieve currently connected self-hosted workers for the authenticated principal's team.\nWorker presence is derived from worker websocket heartbeats and may be briefly stale.\n", "operationId": "listConnectedSelfHostedWorkers", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/TeamUidHeaderParam" } ], "responses": { "200": { "description": "List of currently connected self-hosted workers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListConnectedSelfHostedWorkersResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not authorized to list connected workers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/runs/{runId}/transcript": { "get": { "summary": "Get run transcript", "description": "Retrieve the raw conversation transcript for an agent run.\nReturns a 302 redirect to a time-limited download URL for the transcript.\n", "operationId": "getRunTranscript", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "runId", "in": "path", "description": "The unique identifier of the run", "required": true, "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to a download URL for the transcript", "headers": { "Location": { "description": "URL to download the transcript", "schema": { "type": "string", "format": "uri" } } } }, "400": { "description": "Missing run ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to access run transcript", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run not found or has no transcript", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/runs/{runId}/harness-usage": { "get": { "summary": "Get raw third-party harness usage", "description": "Return the latest cumulative raw usage snapshot retained for a\nClaude Code or Codex run. Missing metrics are represented as an\nunavailable result rather than zero. Access uses the same run view\nauthorization as transcript reads.\n", "operationId": "getRunHarnessUsage", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Raw harness usage or an unavailable result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetRunHarnessUsageResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to view the run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run not found or has no linked conversation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/run": { "post": { "summary": "Run an agent task", "description": "Spawn a cloud agent with a prompt and optional configuration.\nThe agent will be queued for execution and assigned a unique run ID.\n", "operationId": "runAgent", "deprecated": true, "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/TeamUidHeaderParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunAgentRequest" }, "examples": { "simple": { "summary": "Simple prompt", "value": { "prompt": "Fix the bug in auth.go" } }, "withConfig": { "summary": "With agent config", "value": { "prompt": "Refactor the database layer", "config": { "name": "my-agent", "model_id": "gpt-5-4-high", "base_prompt": "Focus on Go backend code" }, "title": "DB Refactoring Run" } } } } } }, "responses": { "200": { "description": "Run created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunAgentResponse" } } } }, "400": { "description": "Invalid request (missing prompt, invalid config)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to access referenced resources (environment, MCP servers)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/runs": { "post": { "summary": "Run a cloud agent", "description": "Spawn a cloud agent with a prompt and optional configuration.\nThe agent will be queued for execution and assigned a unique run ID.\n", "operationId": "createRun", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/TeamUidHeaderParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunAgentRequest" } } } }, "responses": { "200": { "description": "Run created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunAgentResponse" } } } }, "400": { "description": "Invalid request (missing prompt, invalid config)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to access referenced resources (environment, MCP servers)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List agent runs", "description": "Retrieve a paginated list of agent runs with optional filtering.\nResults default to `sort_by=updated_at` and `sort_order=desc`.\n", "operationId": "listRuns", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/TeamUidHeaderParam" }, { "name": "limit", "in": "query", "description": "Maximum number of runs to return", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 20 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor from previous response", "required": false, "schema": { "type": "string" } }, { "name": "sort_by", "in": "query", "description": "Sort field for results.\n- `updated_at`: Sort by last update timestamp (default)\n- `created_at`: Sort by creation timestamp\n- `title`: Sort alphabetically by run title\n- `agent`: Sort alphabetically by skill. Runs without a skill are grouped last.\n", "required": false, "schema": { "type": "string", "enum": [ "updated_at", "created_at", "title", "agent" ], "default": "updated_at" } }, { "name": "sort_order", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, { "name": "state", "in": "query", "description": "Filter by run state. Can be specified multiple times to match any of the given states.\n", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RunState" } }, "style": "form", "explode": true }, { "name": "task_status", "in": "query", "description": "Filter by high-level task status. Can be specified multiple times to match any value.\n`running` matches when the root or any descendant is queued, pending, claimed, or in progress.\n`failed`, `blocked`, `cancelled`, and `complete` match the root state only.\n", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "running", "failed", "blocked", "cancelled", "complete" ] } }, "style": "form", "explode": true }, { "name": "name", "in": "query", "description": "Filter by agent config name", "required": false, "schema": { "type": "string" } }, { "name": "model_id", "in": "query", "description": "Filter by model ID", "required": false, "schema": { "type": "string" } }, { "name": "creator", "in": "query", "description": "Filter by creator UID (user or service account)", "required": false, "schema": { "type": "string" } }, { "name": "executor", "in": "query", "description": "Filter by the user or agent that executed the run. This will often be the\nsame as the creator, but not always: users may delegate tasks to agents.\n", "required": false, "schema": { "type": "string" } }, { "name": "source", "in": "query", "description": "Filter by run source type. Can be specified multiple times to match any of the given sources.\n", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RunSourceType" } }, "style": "form", "explode": true }, { "name": "execution_location", "in": "query", "description": "Filter by where the run executed", "required": false, "schema": { "$ref": "#/components/schemas/RunExecutionLocation" } }, { "name": "created_after", "in": "query", "description": "Filter runs created after this timestamp (RFC3339 format)", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "description": "Filter runs created before this timestamp (RFC3339 format)", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_after", "in": "query", "description": "Filter runs updated after this timestamp (RFC3339 format)", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "environment_id", "in": "query", "description": "Filter runs by environment ID. Passing the literal value\n`empty-environment` matches runs with no environment configured,\nrather than omitting the parameter, which applies no environment\nfilter at all. `empty-environment` can never collide with a real\nenvironment ID: every environment ID is exactly 22 characters\ndrawn from `[A-Za-z0-9]`, while this sentinel contains a hyphen\nand is a different length.\n", "required": false, "schema": { "type": "string" } }, { "name": "skill", "in": "query", "description": "Filter runs by skill spec (e.g., \"owner/repo:path/to/SKILL.md\").\nAlias for skill_spec.\n", "required": false, "schema": { "type": "string" } }, { "name": "skill_spec", "in": "query", "description": "Filter runs by skill spec (e.g., \"owner/repo:path/to/SKILL.md\")", "required": false, "schema": { "type": "string" } }, { "name": "schedule_id", "in": "query", "description": "Filter runs by the scheduled agent ID that created them", "required": false, "schema": { "type": "string" } }, { "name": "factory_uid", "in": "query", "description": "Filter runs by one or more factories. Repeating this parameter\nmatches runs executed by an agent from any selected factory. A UID\noutside the caller's accessible factories matches nothing.\n", "required": false, "schema": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "style": "form", "explode": true }, { "name": "ancestor_run_id", "in": "query", "description": "Filter runs by ancestor run ID. The referenced run must exist and be accessible to the caller.", "required": false, "schema": { "type": "string" } }, { "name": "metadata", "in": "query", "description": "Filter by exact metadata key/value pairs using object notation\n(e.g. `metadata[ticket_id]=ACME-238`), combining multiple pairs\nwith AND semantics, up to 5 per request. Returns\n`feature_not_available` when metadata filtering is not enabled.\n", "required": false, "schema": { "type": "object", "maxProperties": 5, "additionalProperties": { "type": "string" } }, "style": "deepObject", "explode": true }, { "name": "artifact_type", "in": "query", "description": "Filter runs by artifact type", "required": false, "schema": { "type": "string", "enum": [ "PLAN", "PULL_REQUEST", "SCREENSHOT", "FILE", "EXTERNAL_REFERENCE" ] } }, { "name": "q", "in": "query", "description": "Search by full run ID or run URL, or fuzzy match across run title, prompt, and skill_spec", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of runs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRunsResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Metadata filtering is not enabled for this environment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/run-by-external-reference": { "get": { "summary": "Find the run that produced a given external reference URL", "description": "Reverse-looks up the agent run that created an external reference\nwith the given URL. The URL is matched against the canonical locator stored\nwhen the artifact was reported. Returns 404 when no matching run\nexists or when the caller lacks access.\n", "operationId": "getRunByExternalReferenceURL", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "url", "in": "query", "required": true, "description": "The canonical URL of the external reference artifact to look up.", "schema": { "type": "string", "maxLength": 2048 } } ], "responses": { "200": { "description": "Run found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunByExternalReferenceResponse" } } } }, "400": { "description": "url query parameter is missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No run found with the given external reference URL, or caller lacks access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/runs/{runId}": { "get": { "summary": "Get run details", "description": "Retrieve detailed information about a specific agent run,\nincluding the full prompt, session link, and resolved configuration.\n", "operationId": "getRun", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "runId", "in": "path", "description": "The unique identifier of the run", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Run details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunItem" } } } }, "400": { "description": "Missing run ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to access run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/runs/{runId}/timeline": { "get": { "summary": "Get run timeline", "description": "Retrieve chronological setup and lifecycle timeline events for an agent run.\n", "operationId": "getRunTimeline", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "runId", "in": "path", "description": "The unique identifier of the run", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Run timeline events", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetRunTimelineResponse" } } } }, "400": { "description": "Missing run ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to access run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/runs/{runId}/conversation": { "get": { "summary": "Get normalized run conversation", "description": "Retrieve a run's conversation as a normalized sequence of messages and\nnested steps. The response groups text, tool activity, and event content\ninto structured blocks.\n", "operationId": "getRunConversation", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "runId", "in": "path", "description": "The unique identifier of the run", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Normalized conversation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationResponse" } } } }, "400": { "description": "Missing run ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to access run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run not found, or the run has no conversation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Conversation format is not yet supported by the normalized endpoint\n(error_code: operation_not_supported)\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/runs/{runId}/cancel": { "post": { "summary": "Cancel a run", "description": "Cancel an agent run that is currently queued or in progress; once\ncancelled, the run transitions to a cancelled state. Not all runs can\nbe cancelled: a run already in a terminal state, in PENDING, or of an\nunsupported type (e.g. local, GitHub Action) is rejected\ninstead — see the error responses below for each case.\n", "operationId": "cancelRun", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "runId", "in": "path", "description": "The unique identifier of the run to cancel", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Run cancelled successfully", "content": { "application/json": { "schema": { "type": "string", "description": "The ID of the cancelled run" } } } }, "400": { "description": "Missing run ID, or the run is already in a terminal state.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to cancel run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Run is in PENDING state and cannot be cancelled yet.\nRetry after a moment.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Run cannot be cancelled because the operation is not supported\nfor this run type (e.g. local, or GitHub Action runs)\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/runs/{runId}/followups": { "post": { "summary": "Submit a follow-up message for a run", "description": "Send a follow-up message to an existing run. The server transparently\nroutes the message based on the current state of the run (still\nqueued, actively running, or ended) and will resume the agent in a new\nsandbox if necessary. A 200 response means the follow-up\nwas accepted; updated run state can be observed via\n`GET /agent/runs/{runId}`.\n\nA run that failed during environment setup keeps its retained session\nreachable for a bounded debug window. A follow-up sent to an eligible\nrun in that window is delivered into the retained session to start or\ncontinue a debug agent, without reopening the run: it stays in its\nfailed state, with its original failure message and error code\nunchanged.\n", "operationId": "submitRunFollowup", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "runId", "in": "path", "description": "The unique identifier of the run", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunFollowupRequest" } } } }, "responses": { "200": { "description": "Follow-up accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunFollowupResponse" } } } }, "400": { "description": "Invalid request (e.g. no active sandbox without conversation ID,\nmalformed payload). Empty messages are accepted when continuing a\nrun from saved conversation context or when attachments are\npresent; otherwise they are rejected.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to submit follow-ups for this run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "An `attachment_id` is not recorded on this run (`reason:\nunknown_attachment`), or more than 25 attachments were named\n(`reason: too_many_attachments`).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/runs/{runId}/interrupt": { "post": { "summary": "Interrupt the turn currently running on a run", "description": "Cancel the request the agent is currently working on without ending\nthe run or tearing down its sandbox. The run stays in progress and\naccepts follow-ups afterwards. Only live runs on the Warp harness\ncan be interrupted; use `POST /agent/runs/{runId}/cancel` to end a\nrun outright. A 202 means the platform accepted the cancel; the agent\napplies it asynchronously.\n", "operationId": "interruptRun", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "runId", "in": "path", "description": "The unique identifier of the run", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Interrupt accepted", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Missing run ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to steer this run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The run cannot be interrupted right now. `reason` is one of\n`no_live_session` (no reachable session, or the session has not\nregistered a conversation yet), `session_ended`, or\n`unsupported_harness` (a non-Oz harness has no turn-level cancel).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/runs/{runId}/handoff/attachments": { "get": { "summary": "List handoff snapshot attachments for a run", "description": "Return fresh presigned download URLs for handoff snapshot files uploaded\nby the latest ended execution of this run. An empty list is returned\nwhen no ended execution exists or no snapshot files were uploaded.\n\nThis endpoint is useful for third-party harnesses that want to download\nthe snapshot files produced by a previous execution before starting a\nhandoff execution themselves.\n", "operationId": "listHandoffSnapshotAttachments", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "runId", "in": "path", "description": "The unique identifier of the run", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Handoff snapshot attachments (possibly empty)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListHandoffSnapshotAttachmentsResponse" } } } }, "400": { "description": "Missing run ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to view the run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/conversations/{conversation_id}/followups": { "post": { "summary": "Submit a follow-up message to the run behind a conversation", "description": "The same operation as `POST /agent/runs/{runId}/followups`, targeted\nby the conversation the run is serving rather than the run itself.\n\n`attachments` must name ids prepared through\n`POST /agent/conversations/{conversation_id}/attachments/prepare` (or\nthe run-keyed prepare) for the run that is newest at that time. If a\nnew run appears for the conversation between prepare and follow-up,\nthe follow-up resolves to the new run and answers 422\n`unknown_attachment`; prepare again. A handoff is a new execution of\nthe same run and does not have this problem.\n\n`mode` only takes effect when the follow-up is queued ahead of the run\nstarting or starts a new execution; a follow-up injected into a live\nsession runs in the session's current mode.\n", "operationId": "submitConversationFollowup", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "description": "The UUID of the Warp-native conversation", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunFollowupRequest" } } } }, "responses": { "200": { "description": "Follow-up accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationFollowupResponse" } } } }, "400": { "description": "Invalid conversation ID or malformed payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to view the conversation or to follow up on its run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Conversation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The conversation has no run to steer (`reason: no_run`), for\nexample a purely local, cloud-synced conversation.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "An `attachment_id` is not recorded on the resolved run (`reason:\nunknown_attachment`), or more than 25 attachments were named\n(`reason: too_many_attachments`).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/conversations/{conversation_id}/interrupt": { "post": { "summary": "Interrupt the turn running on the run behind a conversation", "description": "The same operation as `POST /agent/runs/{runId}/interrupt`, addressed\nby the conversation the run is serving. The run is picked with the\nsame policy as the conversation follow-up route, and the caller must\nbe able to view the conversation and the resolved run.\n", "operationId": "interruptConversation", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "description": "The UUID of the Warp-native conversation", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Interrupt accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationInterruptResponse" } } } }, "400": { "description": "Invalid conversation ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to view the conversation or to steer its run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Conversation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The run cannot be interrupted. `reason` is one of `no_run`,\n`no_live_session`, `session_ended` or `unsupported_harness`.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/conversations/{conversation_id}": { "get": { "summary": "Get normalized conversation", "description": "Retrieve a conversation directly by conversation ID in Warp's\nnormalized task/message format.\n", "operationId": "getConversation", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "description": "The unique identifier of the conversation", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Normalized conversation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationResponse" } } } }, "400": { "description": "Missing conversation ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to access conversation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Conversation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Conversation format is not yet supported by the normalized endpoint\n(error_code: operation_not_supported)\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/conversations/{conversation_id}/transcript": { "get": { "summary": "Get conversation transcript", "description": "Retrieve the raw conversation transcript for a conversation.\nReturns a 302 redirect to a time-limited download URL for the transcript.\nSupported for third-party harness conversations (Claude Code, Codex, Gemini).\n", "operationId": "getConversationTranscript", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "description": "The unique identifier of the conversation", "required": true, "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to a download URL for the transcript", "headers": { "Location": { "description": "URL to download the transcript", "schema": { "type": "string", "format": "uri" } } } }, "400": { "description": "Conversation format does not support raw transcript download", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to access conversation transcript", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Conversation not found or has no transcript", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/conversations/{conversation_id}/screenshots/{screenshot_uid}/download": { "get": { "summary": "Download a stored computer-use screenshot", "description": "Download a computer-use screenshot that was offloaded\nfrom the conversation's task history into object storage. The\nresponse is a redirect to a short-lived signed URL, so clients must\nfollow redirects to receive the image. Requires view access to the\nconversation named in the path; a fork's history may reference\nscreenshots stored under its source conversation's ID.\n", "operationId": "downloadConversationScreenshot", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "description": "The unique identifier of the conversation that owns the screenshot", "required": true, "schema": { "type": "string" } }, { "name": "screenshot_uid", "in": "path", "description": "The unique identifier of the stored screenshot", "required": true, "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to a temporary signed screenshot download URL", "headers": { "Location": { "description": "Temporary signed download URL", "schema": { "type": "string", "format": "uri" } }, "Cache-Control": { "description": "Cache directive for the redirect response", "schema": { "type": "string" } }, "X-Content-Type-Options": { "description": "Browser content sniffing protection", "schema": { "type": "string" } } } }, "400": { "description": "Missing conversation ID or screenshot UID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to view the conversation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Conversation or screenshot not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/schedules": { "post": { "summary": "Create a scheduled agent", "description": "Create a new scheduled agent that runs on a cron schedule.\nThe agent will be triggered automatically based on the cron expression.\n", "operationId": "createScheduledAgent", "tags": [ "schedules" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/TeamUidHeaderParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateScheduledAgentRequest" }, "examples": { "simple": { "summary": "Simple daily schedule", "value": { "name": "Daily Code Review", "cron_schedule": "0 9 * * *", "prompt": "Review open pull requests and provide feedback", "enabled": true } }, "withConfig": { "summary": "With agent config", "value": { "name": "Weekly Report", "cron_schedule": "0 10 * * 1", "prompt": "Generate weekly status report", "enabled": true, "agent_config": { "model_id": "claude-4-6-opus-high" } } } } } } }, "responses": { "201": { "description": "Scheduled agent created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledAgentItem" } } } }, "400": { "description": "Invalid request (missing required fields, invalid cron expression)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission or feature not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List scheduled agents", "description": "Retrieve all scheduled agents accessible to the authenticated user.\nResults are sorted alphabetically by name.\n", "operationId": "listScheduledAgents", "tags": [ "schedules" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/TeamUidHeaderParam" } ], "responses": { "200": { "description": "List of scheduled agents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListScheduledAgentsResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/schedules/{scheduleId}": { "get": { "summary": "Get scheduled agent details", "description": "Retrieve detailed information about a specific scheduled agent,\nincluding its configuration, history, and next scheduled run time.\n", "operationId": "getScheduledAgent", "tags": [ "schedules" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "scheduleId", "in": "path", "description": "The unique identifier of the scheduled agent", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Scheduled agent details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledAgentItem" } } } }, "400": { "description": "Missing schedule ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to access schedule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Schedule not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "summary": "Update a scheduled agent", "description": "Update an existing scheduled agent's configuration.\nAll fields except agent_config are required.\n", "operationId": "updateScheduledAgent", "tags": [ "schedules" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "scheduleId", "in": "path", "description": "The unique identifier of the scheduled agent", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateScheduledAgentRequest" } } } }, "responses": { "200": { "description": "Scheduled agent updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledAgentItem" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to update schedule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Schedule not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete a scheduled agent", "description": "Delete a scheduled agent. This will stop all future scheduled runs.\n", "operationId": "deleteScheduledAgent", "tags": [ "schedules" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "scheduleId", "in": "path", "description": "The unique identifier of the scheduled agent", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Scheduled agent deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteScheduledAgentResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to delete schedule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Schedule not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/schedules/{scheduleId}/pause": { "post": { "summary": "Pause a scheduled agent", "description": "Pause a scheduled agent. The agent will not run until resumed.\n", "operationId": "pauseScheduledAgent", "tags": [ "schedules" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "scheduleId", "in": "path", "description": "The unique identifier of the scheduled agent", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Scheduled agent paused successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledAgentItem" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to pause schedule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Schedule not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/schedules/{scheduleId}/resume": { "post": { "summary": "Resume a scheduled agent", "description": "Resume a paused scheduled agent. The agent will start running\naccording to its cron schedule.\n", "operationId": "resumeScheduledAgent", "tags": [ "schedules" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "scheduleId", "in": "path", "description": "The unique identifier of the scheduled agent", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Scheduled agent resumed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledAgentItem" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to resume schedule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Schedule not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/environments": { "get": { "summary": "List environments", "description": "Retrieve cloud environments accessible to the authenticated principal.\nReturns environments the caller owns, has been granted guest access to,\nor has accessed via link sharing.\n", "operationId": "listEnvironments", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/TeamUidHeaderParam" }, { "name": "sort_by", "in": "query", "required": false, "description": "Sort order for the returned environments.\n- `name`: alphabetical by environment name\n- `last_updated`: most recently updated first (default)\n", "schema": { "type": "string", "enum": [ "name", "last_updated" ], "default": "last_updated" } } ], "responses": { "200": { "description": "List of accessible environments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEnvironmentsResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/models": { "get": { "summary": "List available models", "description": "Retrieve the list of LLM models available to the authenticated user for\nagent runs. The response includes which model is the default, as well as\nper-model metadata such as provider, cost, and whether the model is\ncurrently disabled (and why).\n", "operationId": "listModels", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "List of available models", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListModelsResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/artifacts/{artifactUid}": { "get": { "summary": "Get artifact details", "description": "Retrieve an artifact by its UUID: a time-limited signed download URL\nfor downloadable file-like artifacts, or the current plan content\ninline for plan artifacts. Public artifacts can be read without\nauthentication; private artifacts require the caller to be\nauthenticated and authorized.\n", "operationId": "getArtifact", "tags": [ "agent" ], "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "artifactUid", "in": "path", "description": "The unique identifier (UUID) of the artifact", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Artifact details with download information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactResponse" } } } }, "400": { "description": "Missing artifact UID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required for private artifacts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to access private artifact", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Artifact not found or unsupported artifact type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/artifacts/{artifactUid}/download": { "get": { "summary": "Download an artifact", "description": "Redirect to a temporary signed download URL for a downloadable artifact.\nPublic artifacts can be downloaded without authentication; private\nartifacts require the caller to be authenticated and authorized.\n", "operationId": "downloadArtifact", "tags": [ "agent" ], "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "artifactUid", "in": "path", "description": "The unique identifier (UUID) of the artifact", "required": true, "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to a temporary signed artifact download URL", "headers": { "Location": { "description": "Temporary signed download URL", "schema": { "type": "string", "format": "uri" } }, "Cache-Control": { "description": "Cache directive for the redirect response", "schema": { "type": "string" } }, "X-Content-Type-Options": { "description": "Browser content sniffing protection", "schema": { "type": "string" } } } }, "400": { "description": "Missing artifact UID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required for private artifacts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to access private artifact", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Artifact not found or unsupported artifact type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory/{uid}/scorers/{scorer_uid}": { "parameters": [ { "name": "uid", "in": "path", "description": "UID of the factory that owns the scorer", "required": true, "schema": { "type": "string" } } ], "patch": { "summary": "Update a scorer's definition", "description": "Apply a partial update to a scorer's definition; omitted fields are\nleft unchanged, but at least one field must be provided, and the\nowning factory is immutable. Each update bumps the scorer's version\nwithout invalidating any scoring judge already in flight, since\njudges validate against the definition snapshot taken at dispatch\ntime, and historical scores keep their recorded classification\nvalues. Supplying `scope_mode` or `agent_uids` replaces the scorer's\nscope in full.\n", "operationId": "updateScorer", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "scorer_uid", "in": "path", "description": "The scorer identifier", "required": true, "schema": { "type": "string", "description": "Scorer UUID or temporary positive decimal integer ID." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateScorerRequest" } } } }, "responses": { "200": { "description": "The updated scorer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScorerResponse" } } } }, "400": { "description": "Invalid scorer update", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "404": { "description": "Scorer not found, or the caller cannot manage its factory", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete a scorer", "description": "Permanently delete a scorer. This is not reversible and it is not an\narchive: the scorer's scoring attempts, scores, judge reasoning, self-improvement\nconfig, and self-improvement triage results go with it, and the scorer stops\nbeing readable through this API as soon as the call returns.\n\nThe underlying rows and the judge-reasoning blobs stored outside the\ndatabase are destroyed shortly afterwards by the deletion sweep, which\nremoves each blob before the record that references it and retries until\nboth are gone.\n", "operationId": "deleteScorer", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "scorer_uid", "in": "path", "description": "The scorer identifier", "required": true, "schema": { "type": "string", "description": "Scorer UUID or temporary positive decimal integer ID." } } ], "responses": { "204": { "description": "Scorer deleted" }, "400": { "description": "Invalid scorer ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "404": { "description": "Scorer not found, or the caller cannot manage its factory", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/conversations/{conversationId}/block-snapshot": { "get": { "summary": "Download a conversation's block snapshot", "description": "Redirect to a signed storage URL for the serialized block snapshot.\nSet redirect=false to return the URL as JSON instead. Both modes require\npermission to view the conversation.\n", "operationId": "getConversationBlockSnapshot", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/PresignedDownloadRedirect" } ], "responses": { "200": { "description": "Signed download URL when redirect=false", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PresignedDownloadResponse" } } } }, "307": { "description": "Redirect to the signed storage URL (default)" }, "400": { "description": "Conversation format does not support block snapshots", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to view the conversation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Conversation or snapshot not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/identities": { "post": { "summary": "Create an agent", "description": "Create a new agent in the caller's active team. Agents act autonomously with their\nown permissions, configuration, and identity.\n", "operationId": "createAgent", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/TeamUidHeaderParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentRequest" } } } }, "responses": { "201": { "description": "Agent created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResponse" } } } }, "400": { "description": "Invalid request (empty name, user on multiple teams, or on no team)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Only human users can manage agents, or plan limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List agents", "description": "List all agents on the caller's team.\n", "operationId": "listAgents", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/TeamUidHeaderParam" }, { "name": "factory_uid", "in": "query", "required": false, "description": "Optional UID of a Factory to filter by. When provided, only agents\nlinked to that factory are returned.\n", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of agents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAgentIdentitiesResponse" } } } }, "400": { "description": "User on multiple teams, or on no team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Only human users can list agents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory/{uid}/scorers": { "parameters": [ { "name": "uid", "in": "path", "description": "UID of the factory that owns the scorer", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Create a scorer", "description": "Create an active run scorer for a factory with either selected-agent or\nall-agent scope. Creating a scorer does not start scoring. Pass\nself_improvement_enabled to also turn on self-improvement for the new scorer in the same\nrequest; the scorer and its self-improvement config are created atomically.\n", "operationId": "createScorer", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateScorerRequest" } } } }, "responses": { "201": { "description": "Scorer created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScorerResponse" } } } }, "400": { "description": "Invalid scorer definition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Caller cannot edit the factory", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Factory not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List agent scorers", "description": "List the scorers in the factory named in the path, including scope agents\nand aggregate scoring stats.\n", "operationId": "listScorers", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/TeamUidHeaderParam" }, { "name": "start_date", "in": "query", "deprecated": true, "description": "Legacy summary range start (RFC3339 UTC, inclusive). Accepted\nand validated for compatibility; does not affect the list\nresponse. Must be provided together with end_date and be\nstrictly before it.\n", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "end_date", "in": "query", "deprecated": true, "description": "Legacy summary range end (RFC3339 UTC, exclusive). See start_date.\n", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Scorers for the factory", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListScorersResponse" } } } }, "400": { "description": "Invalid recent_outcomes_limit (not an integer in 1-100), or an\ninvalid start_date/end_date pair: one given without the other,\nan unparseable RFC3339 timestamp, or start_date not strictly\nbefore end_date.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Factory not found or inaccessible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory/{uid}/scorers/{scorer_uid}/results": { "parameters": [ { "name": "uid", "in": "path", "description": "UID of the factory that owns the scorer", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "List results for a scorer", "description": "List the scorer's most recent scoring attempts, newest first. A\nfailed attempt carries no classification. Pagination is a keyset\ncursor over attempted_at with the attempt id as a stable tiebreak.\nRepeat `run_id` to return all matching results without pagination; unknown runs are omitted.\nReasons are read from object storage only when include_reasons is true.\n", "operationId": "listScorerResults", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/TeamUidHeaderParam" }, { "name": "scorer_uid", "in": "path", "description": "The scorer identifier", "required": true, "schema": { "type": "string", "description": "Scorer UUID or temporary positive decimal integer ID." } }, { "name": "limit", "in": "query", "description": "Maximum number of results to return (1-100, default 50)", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor returned by a previous list response.", "required": false, "schema": { "type": "string" } }, { "name": "include_reasons", "in": "query", "description": "Include reason availability and readable judge reasoning.", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "run_id", "in": "query", "description": "Exact run filters, repeated once per run. Values are trimmed and\ndeduplicated; require 1-100 distinct nonblank runs when present.\nCannot be combined with cursor or limit.\n", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Recent results for the scorer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListScorerResultsResponse" } } } }, "400": { "description": "Invalid scorer ID, limit, cursor, include_reasons, or run_id filters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "404": { "description": "Scorer not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory/{uid}/scorers/{scorer_uid}/metrics": { "parameters": [ { "name": "uid", "in": "path", "description": "UID of the factory that owns the scorer", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Get scorer metrics over a date range", "description": "Returns a period-aligned pass-rate series plus a full-range aggregate\nfor the scorer, computed directly from every live\nscore in [start_date, end_date).\nBinning follows the same day/week/month rules and 365-period cap as\n`GET /factory/{uid}/metrics`.\n", "operationId": "getScorerMetrics", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/TeamUidHeaderParam" }, { "name": "scorer_uid", "in": "path", "description": "The scorer identifier", "required": true, "schema": { "type": "string", "description": "Scorer UUID or temporary positive decimal integer ID." } }, { "name": "start_date", "in": "query", "description": "RFC3339 UTC range start, inclusive. Defaults to 30 days before end_date.", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "end_date", "in": "query", "description": "RFC3339 UTC range end, exclusive. Defaults to now.", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "group_by_period", "in": "query", "description": "Binning granularity for the series. Defaults to day.", "required": false, "schema": { "$ref": "#/components/schemas/FactoryMetricsGroupByPeriod" } }, { "name": "include_cost", "in": "query", "description": "Include the scorer's judge-run cost for each period. Defaults to false.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "The scorer's pass-rate series and range aggregate", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScorerMetricsResponse" } } } }, "400": { "description": "Invalid scorer ID, date range, group_by_period, or include_cost", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Scorer not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory/{factory_uid}/runs/{run_id}/scorer_dispatch": { "post": { "summary": "Manually dispatch scorers for a run", "description": "Evaluate one run with the scorers in `scorer_uids`. To evaluate multiple\nruns with one scorer, use\n`/factory/{factory_uid}/scorers/{scorer_uid}/dispatch`.\nManual dispatch skips automatic scoring's cool-down and sampling\n(including 0%) and supports older or previously scored runs.\n\nRequires manage access to the factory and view access to the run.\nThe run must have a conversation and be executed by a factory agent,\nnot be a scoring job. The run and scorers must belong to this factory\nand team. Each scorer must be configured for the run's agent and must\nnot be benchmark-managed.\n\nProvide 1–100 scorer UUIDs. Run and scorer UUIDs must be nonzero.\nInvalid selections reject the whole request before any scoring jobs start.\n\nReturns dispatch outcomes, not completed scores. Valid requests can have\nindividual failures; inspect each result's `status` and `error`.\n", "operationId": "dispatchRunScorers", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "factory_uid", "in": "path", "required": true, "description": "The factory containing the run and scorers.", "schema": { "type": "string" } }, { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunScorerDispatchRequest" }, "example": { "scorer_uids": [ "0199b01b-b7c0-7000-8000-000000000007", "0199b01b-b7c0-7000-8000-000000000008" ] } } } }, "responses": { "202": { "description": "Per-pair dispatch outcomes; scoring completes asynchronously.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualScoringDispatchResponse" } } } }, "400": { "description": "Invalid selection, ineligible run or scorer, or more than 100 scorer UUIDs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "404": { "description": "A named run or scorer does not exist, or the caller lacks access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error; no scoring job was started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory/{factory_uid}/scorers/{scorer_uid}/dispatch": { "post": { "summary": "Manually dispatch a scorer for selected runs", "description": "Evaluate the runs in `run_ids` with one scorer. To evaluate one run with\nmultiple scorers, use\n`/factory/{factory_uid}/runs/{run_id}/scorer_dispatch`.\nManual dispatch skips automatic scoring's cool-down and sampling\n(including 0%) and supports older or previously scored runs.\n\nRequires manage access to the factory and view access to every run.\nRuns must have conversations and be executed by factory agents,\nnot be scoring jobs. The scorer and runs must belong to this factory\nand team. The scorer must be configured for each run's agent and must\nnot be benchmark-managed.\n\nProvide 1–100 run UUIDs. Run and scorer UUIDs must be nonzero.\nInvalid selections reject the whole request before any scoring jobs start.\n\nReturns dispatch outcomes, not completed scores. Valid requests can have\nindividual failures; inspect each result's `status` and `error`.\n", "operationId": "dispatchScorer", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "factory_uid", "in": "path", "required": true, "description": "The factory containing the scorer and runs.", "schema": { "type": "string" } }, { "name": "scorer_uid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScorerDispatchRequest" }, "example": { "run_ids": [ "0199b01b-b7c0-7000-8000-000000000001", "0199b01b-b7c0-7000-8000-000000000002" ] } } } }, "responses": { "202": { "description": "Per-pair dispatch outcomes; scoring completes asynchronously.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualScoringDispatchResponse" } } } }, "400": { "description": "Invalid selection, ineligible run or scorer, or more than 100 run UUIDs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "404": { "description": "A named run or scorer does not exist, or the caller lacks access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error; no judge run was created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory/runs/{run_id}/scores": { "get": { "summary": "Read a run's current scores", "description": "List the current live attempt for each evaluation that has attempted\nthe given run, most recent attempt first. Excludes a deleted\nevaluation's data.\nRequires only view access to the run, since reading scores is part of viewing\nthe run.\n", "operationId": "listRunScores", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "run_id", "in": "path", "description": "The run identifier", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The run's current scores", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetRunScoresResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "404": { "description": "Run not found, or the caller cannot view it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/identities/{uid}": { "get": { "summary": "Retrieve an agent", "description": "Retrieve a single agent by its unique identifier.\n", "operationId": "getAgent", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uid", "in": "path", "description": "The unique identifier of the agent", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Agent details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "summary": "Update an agent", "description": "Update an existing agent.\n", "operationId": "updateAgent", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uid", "in": "path", "description": "The unique identifier of the agent", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgentRequest" } } } }, "responses": { "200": { "description": "Agent updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResponse" } } } }, "400": { "description": "Missing or invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Only human users can manage agents, or plan limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete an agent", "description": "Delete an agent. All API keys associated with the\nagent are deleted atomically.\n", "operationId": "deleteAgent", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uid", "in": "path", "description": "The unique identifier of the agent", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Agent deleted successfully" }, "400": { "description": "Cannot delete the default agent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Only human users can manage agents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/sessions/{sessionUuid}/redirect": { "get": { "summary": "Get session redirect", "description": "Check whether a shared session should redirect to a conversation\ntranscript, returning a conversation_id if the agent sandbox has\nfinished and conversation data is available (or an empty object if\nno redirect is needed). Public and unauthenticated, so anonymous\nviewers can resolve a shared session link before signing in; access\nto the underlying transcript is still gated by conversation\nlink-sharing.\n", "operationId": "getSessionRedirect", "tags": [ "agent" ], "security": [], "parameters": [ { "name": "sessionUuid", "in": "path", "description": "The UUID of the shared session", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Redirect information. Contains conversation_id if redirect is needed,\notherwise an empty object.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "conversation_id": { "type": "string", "description": "The conversation ID to redirect to (only present when redirect is needed)" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/conversations/{conversationId}/redirect": { "get": { "summary": "Get conversation redirect", "description": "Check whether a conversation should redirect to a live shared\nsession, returning a session_id if the underlying ambient agent task\nstill has one (or an empty object if no redirect is needed). Public\nand unauthenticated, so anonymous viewers can resolve a shared\nconversation link before signing in; access to the underlying live\nsession is still gated by the session-sharing service ACLs.\n", "operationId": "getConversationRedirect", "tags": [ "agent" ], "security": [], "parameters": [ { "name": "conversationId", "in": "path", "description": "The ID of the conversation", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Redirect information. Contains session_id if redirect is needed,\notherwise an empty object.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "description": "The shared session UUID to redirect to (only present when redirect is needed)" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory/{factory_uid}/benchmarks": { "post": { "summary": "Create a benchmark suite", "operationId": "createBenchmarkSuite", "tags": [ "factory", "benchmark" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BenchmarkFactoryPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BenchmarkSuiteCreateRequest" } } } }, "responses": { "201": { "description": "Suite created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BenchmarkSuite" } } } }, "400": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "404": { "description": "Factory not found or not accessible", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Suite with this uid already exists for the factory", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List benchmark suites", "operationId": "listBenchmarkSuites", "tags": [ "factory", "benchmark" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BenchmarkFactoryPath" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of suites", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListBenchmarkSuitesResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "404": { "description": "Factory not found or not accessible", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory/{factory_uid}/benchmarks/{suite_uid}": { "get": { "summary": "Get a benchmark suite with its tasks and configurations", "operationId": "getBenchmarkSuite", "tags": [ "factory", "benchmark" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BenchmarkFactoryPath" }, { "$ref": "#/components/parameters/BenchmarkSuitePath" } ], "responses": { "200": { "description": "Suite details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BenchmarkSuiteDetail" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "404": { "description": "Suite not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Edit a benchmark suite", "operationId": "patchBenchmarkSuite", "tags": [ "factory", "benchmark" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BenchmarkFactoryPath" }, { "$ref": "#/components/parameters/BenchmarkSuitePath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BenchmarkSuitePatchRequest" } } } }, "responses": { "200": { "description": "Suite updated with new version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BenchmarkSuiteDetail" } } } }, "400": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "404": { "description": "Suite not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Soft-delete a benchmark suite", "operationId": "deleteBenchmarkSuite", "tags": [ "factory", "benchmark" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BenchmarkFactoryPath" }, { "$ref": "#/components/parameters/BenchmarkSuitePath" } ], "responses": { "204": { "description": "Suite deleted" }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "404": { "description": "Suite not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory/{factory_uid}/benchmarks/{suite_uid}/tasks": { "post": { "summary": "Create a benchmark suite task", "description": "This adds a single hand-authored task to a suite, without needing\nto resend the whole task list. A title, prompt, and success\ncriteria are required, and if a `source_run_id` is included, the\ncaller must have permission to read that run. Adding the exact\nsame task twice simply returns the existing one (so retrying is\nsafe), while reusing a title with different content is rejected\nas a conflict — and on a `code.storage`-managed Factory, the task\nis saved as a file and returned from that file.\n", "operationId": "createBenchmarkSuiteTask", "tags": [ "factory", "benchmark" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BenchmarkFactoryPath" }, { "$ref": "#/components/parameters/BenchmarkSuitePath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BenchmarkSuiteTaskCreateRequest" } } } }, "responses": { "201": { "description": "Task created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BenchmarkSuiteTask" } } } }, "400": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "404": { "description": "Suite not found, or source_run_id is not a run the caller can read", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Another task in this suite already has this title with different content, or the Factory is file-managed and cannot be written through", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory/{factory_uid}/benchmarks/{suite_uid}/tasks/{task_uid}": { "get": { "summary": "Get one benchmark suite task", "operationId": "getBenchmarkSuiteTask", "tags": [ "factory", "benchmark" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BenchmarkFactoryPath" }, { "$ref": "#/components/parameters/BenchmarkSuitePath" }, { "name": "task_uid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Task details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BenchmarkSuiteTask" } } } }, "400": { "description": "task_uid is not a valid UUID", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "404": { "description": "Suite not found, task not found, or task_uid belongs to another suite", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Edit one benchmark suite task", "description": "Edits a single task in place without resending the suite's full task\nlist. Omitted fields keep their current values. title, prompt, and\nsuccess_criteria reject null and empty-after-trim values. An\nexplicit null source_run_id clears provenance. An explicit empty\nstarting_repo_refs or tags clears that field.\n", "operationId": "patchBenchmarkSuiteTask", "tags": [ "factory", "benchmark" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BenchmarkFactoryPath" }, { "$ref": "#/components/parameters/BenchmarkSuitePath" }, { "name": "task_uid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BenchmarkSuiteTaskPatchRequest" } } } }, "responses": { "200": { "description": "Task updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BenchmarkSuiteTask" } } } }, "400": { "description": "Invalid request, or task_uid is not a valid UUID", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "404": { "description": "Suite not found, task not found, or task_uid belongs to another suite", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Another task in this suite already has the requested title", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete one benchmark suite task", "operationId": "deleteBenchmarkSuiteTask", "tags": [ "factory", "benchmark" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BenchmarkFactoryPath" }, { "$ref": "#/components/parameters/BenchmarkSuitePath" }, { "name": "task_uid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Task deleted" }, "400": { "description": "task_uid is not a valid UUID", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "404": { "description": "Suite not found, task not found, or task_uid belongs to another suite", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The managed task source changed concurrently; re-read the current state and retry deletion", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory/{factory_uid}/benchmarks/{suite_uid}/runs": { "post": { "summary": "Launch a benchmark run from the current suite version", "description": "Each successful request creates a new run. Launch is not idempotent:\ndisable automatic retries for this request and reconcile an uncertain\noutcome by listing runs before launching again.\nRetries are a client transport option, not a request-body field.\nIn the TypeScript SDK, pass { maxRetries: 0 } as the request options.\nIn the Python SDK, call create through client.with_options(max_retries=0).\nThese options do not change execution retries within the benchmark run.\n", "operationId": "launchBenchmarkRun", "tags": [ "factory", "benchmark" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BenchmarkFactoryPath" }, { "$ref": "#/components/parameters/BenchmarkSuitePath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LaunchBenchmarkRunRequest" }, "examples": { "full_suite": { "summary": "Launch every current task in the suite", "value": { "repetition_count": 1 } }, "task_subset": { "summary": "Launch a subset selected by task UID", "value": { "repetition_count": 1, "tasks": [ "7d69fb52-71c5-4e27-914e-8764ee9c5246", "ad8ff7dc-a7d1-4ed6-9f50-650010bb39aa" ] } } } } } }, "responses": { "201": { "description": "Run launched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BenchmarkRunLaunchResponse" } } } }, "400": { "description": "Suite not runnable; body contains violations list", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/BenchmarkLaunchViolationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "404": { "description": "Suite not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List benchmark runs", "operationId": "listBenchmarkRuns", "description": "List runs launched from this benchmark suite. Each entry contains the\nrun's status and execution/scoring progress. Use `include` to add launch\nsettings, aggregate results, or the creator's display name to each entry.\nThe response contains a page of runs in `data` and continuation\ninformation in `page_info`. Retained runs remain readable after the\nsuite is deleted; an unknown suite returns an empty list.\n", "tags": [ "factory", "benchmark" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BenchmarkRunInclude" }, { "$ref": "#/components/parameters/BenchmarkFactoryPath" }, { "$ref": "#/components/parameters/BenchmarkSuitePath" }, { "name": "state", "in": "query", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkRunState" } }, "style": "form", "explode": true }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Runs from the frozen suite identity, including deleted suites; empty for an unknown suite", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BenchmarkRunList" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "404": { "description": "Factory not found or not accessible", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory/{factory_uid}/benchmarks/{suite_uid}/runs/{run_uid}": { "get": { "summary": "Get benchmark run detail", "operationId": "getBenchmarkRun", "description": "Retrieve a benchmark run's status and execution/scoring progress.\nBy default, the response omits launch settings and aggregate results.\nUse `include` to add these fields or the creator's display name.\nRetrieve trials separately for individual scores and execution history.\n", "tags": [ "factory", "benchmark" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BenchmarkRunInclude" }, { "$ref": "#/components/parameters/BenchmarkFactoryPath" }, { "$ref": "#/components/parameters/BenchmarkSuitePath" }, { "$ref": "#/components/parameters/BenchmarkRunPath" } ], "responses": { "200": { "description": "Run detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BenchmarkRun" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "404": { "description": "Run not found in this suite", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory/{factory_uid}/benchmarks/{suite_uid}/runs/{run_uid}/cancel": { "post": { "summary": "Cancel an in-flight benchmark run", "operationId": "cancelBenchmarkRun", "tags": [ "factory", "benchmark" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BenchmarkFactoryPath" }, { "$ref": "#/components/parameters/BenchmarkSuitePath" }, { "$ref": "#/components/parameters/BenchmarkRunPath" } ], "responses": { "200": { "description": "Run cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BenchmarkRunLaunchResponse" } } } }, "400": { "description": "Run is already terminal", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "404": { "description": "Run not found in this suite", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory/{factory_uid}/benchmarks/{suite_uid}/runs/{run_uid}/results": { "get": { "summary": "Get benchmark run results", "operationId": "getBenchmarkRunResults", "description": "Retrieve aggregate outcomes, coverage, and costs for the run.\nTask and tag filters select the trials used to calculate the results.\nBy default, the response contains summary fields without detailed\nmetric arrays; use `include` to add those arrays.\nConfiguration and scorer filters limit returned metric rows without\nchanging the summary or comparison populations. Results cover the whole\nselected dataset, independently of trial-list pages, and are not paginated.\n", "tags": [ "factory", "benchmark" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BenchmarkResultsInclude" }, { "$ref": "#/components/parameters/BenchmarkTaskSelection" }, { "$ref": "#/components/parameters/BenchmarkTagSelection" }, { "$ref": "#/components/parameters/BenchmarkConfigurationProjection" }, { "$ref": "#/components/parameters/BenchmarkScorerProjection" }, { "$ref": "#/components/parameters/BenchmarkFactoryPath" }, { "$ref": "#/components/parameters/BenchmarkSuitePath" }, { "$ref": "#/components/parameters/BenchmarkRunPath" } ], "responses": { "200": { "description": "Results aggregate (JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BenchmarkResults" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "404": { "description": "Run not found in this suite", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory/{factory_uid}/benchmarks/{suite_uid}/runs/{run_uid}/trials": { "get": { "summary": "List benchmark trials or find the trial for an agent run", "operationId": "listBenchmarkTrials", "description": "Each trial represents one task, configuration, and repetition within\nthe benchmark run. The response contains a page of trials in `data`\nand continuation information in `page_info`. Use `include` to add\nscores, metrics, or retained execution history to each trial.\nRepeated values match any value within a filter; different filters\nmust all match.\nTo find the trial for a primary agent execution, pass `agent_run_id`.\nThis returns zero or one trial, with `matched_attempt_number` identifying\nthe matching attempt. Judge runs and spawned descendant runs do not match.\nThis lookup accepts `include` and an omitted `limit` or `limit=1`, but\nno cursor or other filters. Filtering by scorer is not supported.\n", "tags": [ "factory", "benchmark" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BenchmarkFactoryPath" }, { "$ref": "#/components/parameters/BenchmarkSuitePath" }, { "$ref": "#/components/parameters/BenchmarkRunPath" }, { "$ref": "#/components/parameters/BenchmarkTrialInclude" }, { "$ref": "#/components/parameters/BenchmarkTaskSelection" }, { "$ref": "#/components/parameters/BenchmarkTagSelection" }, { "name": "configuration_uid", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "state", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkTrialState" } } }, { "name": "agent_run_id", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "description": "Pass the previous response's page_info.next_cursor with the same filters to retrieve the next page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Complete requested Trial rows on one page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BenchmarkTrialList" } } } }, "400": { "description": "Invalid selection, include, or cursor", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Factory or Run not found or not accessible in this suite", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory/{factory_uid}/benchmarks/{suite_uid}/runs/{run_uid}/trials/{trial_uid}": { "get": { "summary": "Retrieve an individual benchmark trial within a run", "operationId": "getBenchmarkTrial", "description": "Retrieve the trial's execution and scoring status for one task,\nconfiguration, and repetition within the run. Include results to\nretrieve its scores and metrics, or details to retrieve retained\nexecution attempts and judge history. Each requested expansion is\ncomplete. Selection and pagination parameters are not supported.\n", "tags": [ "factory", "benchmark" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/BenchmarkFactoryPath" }, { "$ref": "#/components/parameters/BenchmarkSuitePath" }, { "$ref": "#/components/parameters/BenchmarkRunPath" }, { "$ref": "#/components/parameters/BenchmarkTrialInclude" }, { "name": "trial_uid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Logical Trial with complete requested expansions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BenchmarkTrial" } } } }, "400": { "description": "Invalid query", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Trial not found or not accessible in this Run", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory-files/schemas": { "get": { "summary": "List the supported Factory file schema versions", "description": "Returns every Factory file schema version this server can describe,\nwith a link to each version's schema bundle.\n", "operationId": "listFactoryFileSchemaVersions", "tags": [ "factory" ], "security": [], "parameters": [ { "name": "If-None-Match", "in": "header", "required": false, "description": "A previously returned ETag. A match returns 304 with no body.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The supported schema versions", "headers": { "ETag": { "description": "Strong validator derived from the response bytes", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactoryFileSchemaRegistry" } } } }, "304": { "description": "The cached response is still current" } } } }, "/factory-files/schemas/{schema_version}": { "get": { "summary": "Get the JSON Schema bundle for one Factory file schema version", "description": "Returns every JSON Schema 2020-12 document describing one Factory file\nschema version, as a single bundle so the relative `$id` and `$ref`\nidentities between the documents keep resolving.\n", "operationId": "getFactoryFileSchemaBundle", "tags": [ "factory" ], "security": [], "parameters": [ { "name": "schema_version", "in": "path", "required": true, "description": "A Factory file schema version, for example `v1alpha1`.", "schema": { "type": "string" } }, { "name": "If-None-Match", "in": "header", "required": false, "description": "A previously returned ETag. A match returns 304 with no body.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The schema documents for this version", "headers": { "ETag": { "description": "Strong validator derived from the response bytes", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactoryFileSchemaBundle" } } } }, "304": { "description": "The cached response is still current" }, "404": { "description": "The schema version is not supported by this server", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory-files/schemas/{schema_version}/{document}": { "get": { "summary": "Get one Factory file schema document", "description": "Returns a single generated JSON Schema document on its own, rather\nthan inside the bundle envelope, so it can be used directly as a\nschema reference. A document served here resolves its relative\n`$ref`s against its siblings at this same path, which is what each\ndocument's `$id` assumes, making the URL usable directly from an\neditor or YAML language server, for example:\n\n```yaml\n# yaml-language-server: $schema=/api/v1/factory-files/schemas/v1alpha1/factory.schema.json\n```\n", "operationId": "getFactoryFileSchemaDocument", "tags": [ "factory" ], "security": [], "parameters": [ { "name": "schema_version", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Factory file schema version, such as v1alpha1" }, { "name": "document", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Document file name: common.schema.json, factory.schema.json,\nagent.schema.json, automation.schema.json, runner.schema.json, or\nscorer.schema.json\n" } ], "responses": { "200": { "description": "The requested JSON Schema document", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "The version or the document is unknown", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Authentication via a Warp API key or a supported Warp-issued user token.\n" } }, "parameters": { "PresignedDownloadRedirect": { "name": "redirect", "in": "query", "required": false, "description": "Set to false to return a signed storage URL as JSON rather than redirecting.", "schema": { "type": "boolean", "default": true } }, "BenchmarkFactoryPath": { "name": "factory_uid", "in": "path", "description": "UID of the factory that owns the benchmark suite.", "required": true, "schema": { "type": "string" } }, "BenchmarkSuitePath": { "name": "suite_uid", "in": "path", "description": "UID of the benchmark suite within this factory.", "required": true, "schema": { "type": "string" } }, "BenchmarkRunPath": { "name": "run_uid", "in": "path", "description": "UID of the benchmark run within this suite.", "required": true, "schema": { "type": "string" } }, "BenchmarkRunInclude": { "name": "include", "in": "query", "description": "Controls additional fields in each returned run object. `details` adds\nlaunch settings, including tasks, configurations, repetitions, and scorers.\n`summary_results` adds aggregate results for the entire run.\n`creator_display_name` adds `creator.display_name` when the creator is\nknown; the name is null if unavailable. Unrequested fields are omitted.\nRepeat this parameter to include multiple fields, for example\n`include=details&include=summary_results`. Values are case-sensitive;\nempty, comma-separated, and unknown values are invalid.\n", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "details", "summary_results", "creator_display_name" ] } } }, "BenchmarkTrialInclude": { "name": "include", "in": "query", "description": "Controls additional fields in each returned trial object. `results` adds\nscores, metrics, and spend. `details` adds retained execution attempts and\njudge-run history. Request either or both; unrequested fields are omitted.\nEach requested field contains all available entries, not a separate page.\nRepeat this parameter to request both, for example\n`include=results&include=details`. Values are case-sensitive;\nempty, comma-separated, and unknown values are invalid.\n", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "results", "details" ] } } }, "BenchmarkResultsInclude": { "name": "include", "in": "query", "description": "Controls which detailed metric arrays appear alongside the result summary.\nEach value adds the response field with the same name; unrequested arrays\nare omitted. Requested arrays contain every matching entry and are empty,\nnever null, when there are no entries. This response is not paginated.\nRepeat this parameter to request multiple arrays, for example\n`include=configuration_metrics&include=agent_metrics`. Values are\ncase-sensitive; empty, comma-separated, and unknown values are invalid.\n", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "configuration_metrics", "scorer_configuration_metrics", "task_scorer_configuration_metrics", "agent_metrics" ] } } }, "BenchmarkTaskSelection": { "name": "task_uid", "in": "query", "description": "Select trials or result aggregates for these task UIDs, using the tasks\nrecorded when the run was launched. Repeat to match any specified task.\nResult summaries and metrics are calculated only from the selected tasks.\n", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, "BenchmarkTagSelection": { "name": "tag", "in": "query", "description": "Select trials or result aggregates by task tags recorded when the run was\nlaunched. Repeat to match any specified tag; matching is case-sensitive.\nResult summaries and metrics are calculated only from the selected tasks.\n", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, "BenchmarkConfigurationProjection": { "name": "configuration_uid", "in": "query", "description": "Return detailed metric rows only for these configuration UIDs. Summary\ncounts and comparison populations still cover all configurations in the\nselected dataset. Repeat to return multiple configurations.\nRequires at least one metric array requested through `include`.\n", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, "BenchmarkScorerProjection": { "name": "scorer_uid", "in": "query", "description": "Return scorer-specific metric rows only for these scorer UIDs. Overall\nresults and comparison populations still cover all applicable scorers.\nRepeat to return multiple scorers. Requires\n`include=scorer_configuration_metrics` or\n`include=task_scorer_configuration_metrics`.\n", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, "TeamUidHeaderParam": { "name": "X-Warp-Team-Uid", "in": "header", "required": false, "description": "UID of the team to use as the request's active team. Ignored for\nservice-account callers, which always act as their bound team.\n", "schema": { "type": "string" } } }, "responses": { "FactoryAccessDenied": { "description": "Factory access is not enabled for the authenticated principal", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "FactoryMetricsRateLimited": { "description": "The caller has used up the request budget shared by the factory\nmetrics endpoints. Wait the number of seconds in Retry-After, then\nretry.\n", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "EgressRangesResponse": { "type": "object", "required": [ "cidrs" ], "properties": { "cidrs": { "type": "array", "items": { "type": "string" }, "description": "Canonical, deduplicated IPv4 and IPv6 network ranges." } } }, "FactoryFileSchemaRegistry": { "type": "object", "description": "The Factory file schema versions a server can describe.", "required": [ "current_version", "versions" ], "properties": { "current_version": { "type": "string", "description": "The version a new Factory tree should declare.", "example": "v1alpha1" }, "versions": { "type": "array", "description": "Every supported version, sorted by schema version.", "items": { "$ref": "#/components/schemas/FactoryFileSchemaVersionRef" } } } }, "FactoryFileSchemaVersionRef": { "type": "object", "required": [ "schema_version", "schema_url" ], "properties": { "schema_version": { "type": "string", "example": "v1alpha1" }, "schema_url": { "type": "string", "description": "Root-relative path of this version's schema bundle.", "example": "/api/v1/factory-files/schemas/v1alpha1" } } }, "FactoryFileSchemaBundle": { "type": "object", "description": "Every JSON Schema document describing one Factory file schema version.\nThe envelope is plain JSON; each value in `documents` is a JSON Schema\n2020-12 document keyed by its `$id`.\n", "required": [ "schema_version", "documents" ], "properties": { "schema_version": { "type": "string", "example": "v1alpha1" }, "documents": { "type": "object", "description": "Schema documents keyed by file name, which is also each document's $id.", "additionalProperties": { "description": "A JSON Schema 2020-12 document." } } } }, "Factory": { "type": "object", "description": "Public representation of a factory.", "required": [ "uid", "team_uid", "name", "description", "alias", "avatar_url", "code_forge", "code_forges", "repositories", "default_environment", "default_model", "scoring", "credential_strategy", "integrations", "agent_defaults", "scorer_defaults", "created_at", "updated_at" ], "properties": { "uid": { "type": "string", "description": "Public UID of the factory." }, "team_uid": { "type": "string", "description": "Public UID of the team that owns the factory." }, "name": { "type": "string", "description": "Display name of the factory." }, "description": { "type": "string", "nullable": true, "description": "Optional description of the factory." }, "alias": { "type": "string", "nullable": true, "description": "Optional display handle for the factory, unique across the team's\nWarp workspace when set.\n" }, "avatar_url": { "type": "string", "nullable": true, "description": "Short-lived signed URL for displaying the factory's avatar. The URL\nmay change between reads.\n" }, "code_forge": { "$ref": "#/components/schemas/FactoryCodeForge" }, "code_forges": { "type": "array", "items": { "$ref": "#/components/schemas/FactoryCodeForge" }, "description": "Effective source-control providers for the factory. When the\neffective set is empty, this contains the primary code_forge.\n" }, "repositories": { "type": "array", "items": { "$ref": "#/components/schemas/FactoryRepository" }, "description": "Repositories scoped to the factory, independent of its default environment." }, "default_environment": { "type": "string", "nullable": true, "description": "Public UID of the factory's default environment. File-managed\nfactories may omit this default.\n" }, "default_model": { "type": "string", "nullable": true, "description": "The default model ID for the factory's runs. File-managed factories\nmay omit this default. Live-managed create and PATCH requests still\ncapture a concrete validated model ID.\n" }, "scoring": { "$ref": "#/components/schemas/FactoryScoringConfig" }, "self_improvement": { "allOf": [ { "$ref": "#/components/schemas/FactorySelfImprovementConfig" } ], "readOnly": true, "description": "Self-improvement settings from the Factory YAML. Omitted when none are declared, in which case `self_improvement_defaults` apply." }, "self_improvement_defaults": { "allOf": [ { "$ref": "#/components/schemas/FactorySelfImprovementDefaults" } ], "readOnly": true, "description": "Server defaults applied to self-improvement settings the Factory does not declare." }, "credential_strategy": { "allOf": [ { "$ref": "#/components/schemas/FactoryCredentialStrategy" } ], "description": "Default credential strategy for runs executed by the factory's\nnamed agents. Always a concrete value; factories default to\nEXECUTOR unless explicitly set to CREATOR.\n" }, "integrations": { "type": "array", "items": { "$ref": "#/components/schemas/FactoryIntegration" }, "nullable": true, "description": "Integration providers attached to the factory, independent of the\nautomation triggers configured for it. null means the factory has\nnot declared anything yet; an empty array means no providers are\nattached.\n" }, "agent_defaults": { "$ref": "#/components/schemas/FactoryAgentDefaults" }, "scorer_defaults": { "$ref": "#/components/schemas/FactoryScorerDefaults" }, "creator": { "allOf": [ { "$ref": "#/components/schemas/FactoryCreator" } ], "description": "The user who created the factory. Absent when there is no\nresolvable creator: the factory predates creator tracking, it was\ncreated by a service account, or the creating user's account no\nlonger exists.\n" }, "created_at": { "type": "string", "format": "date-time", "description": "Time the factory was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "Time the factory was last updated." } } }, "FactoryCreator": { "type": "object", "description": "The user who created a factory, when resolvable.", "required": [ "uid" ], "properties": { "uid": { "type": "string", "description": "Firebase UID of the user who created the factory." }, "email": { "type": "string", "nullable": true, "description": "Creator's email, when available." } } }, "FactoryAgentDefaults": { "type": "object", "description": "Default execution settings inherited by the factory's named agents\nwhen they declare no override of their own.\n", "required": [ "default_runner_uid", "secrets", "mcp_servers", "worker_host" ], "properties": { "harness": { "allOf": [ { "$ref": "#/components/schemas/Harness" } ], "description": "Default harness for the factory's named agents. Absent when the\nfactory defaults to Warp's built-in harness. model_id and\nreasoning_level carry the harness-scoped default model, which is\nalso reported in the factory's default_model.\n" }, "harness_auth_secrets": { "allOf": [ { "$ref": "#/components/schemas/HarnessAuthSecrets" } ], "description": "Per-harness authentication secrets inherited by the factory's\nnamed agents. Only the secret for the default harness is ever\npopulated. A third-party default harness with no secret here\ntakes its credentials from the worker environment.\n" }, "default_runner_uid": { "type": "string", "description": "Default runner UID for the factory's named agents. Empty when\nunset, in which case the environment's default runner applies.\n" }, "secrets": { "type": "array", "items": { "$ref": "#/components/schemas/SecretRef" }, "description": "Secrets attached to the factory's named agents by default." }, "mcp_servers": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/MCPServerConfig" }, "description": "MCP server configurations attached to the factory's named agents\nby default. Only warp_id (managed MCP) entries are representable\nfor a Warp-managed factory.\n" }, "worker_host": { "type": "string", "description": "Default worker host for the factory's named agents. Empty when\nunset, in which case the workspace default applies.\n" } } }, "FactoryScorerDefaults": { "type": "object", "description": "Sparse execution defaults for scorers. An omitted field inherits the\ncorresponding agent default; an explicit empty collection overrides\nthe agent default with no values.\n", "properties": { "default_runner_uid": { "type": "string", "description": "Default runner UID for scorers. Omitted to inherit the agent default." }, "secrets": { "type": "array", "items": { "$ref": "#/components/schemas/SecretRef" }, "description": "Scorer-default secrets. Omitted to inherit the agent defaults; an\nempty array explicitly clears them.\n" }, "mcp_servers": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/MCPServerConfig" }, "description": "Scorer-default MCP servers. Omitted to inherit the agent defaults;\nan empty object explicitly clears them.\n" } } }, "FactorySelfImprovementConfig": { "type": "object", "properties": { "reviewer_type": { "type": "string", "enum": [ "none", "admins", "team", "custom" ], "description": "Owning-team pool from which one eligible reviewer is randomly selected for self-improvement pull requests and Factory reviews in GitHub-managed or Warp-managed Factories. `admins` requests a team admin or owner. `team` requests any team member. `custom` requests a member listed in `reviewer_emails`. `none` explicitly disables reviewer assignment. Omitted when the Factory declares no pool, in which case `self_improvement_defaults.reviewer_type` applies." }, "failed_run_threshold": { "type": "integer", "minimum": 1, "maximum": 50, "description": "Per-agent count of distinct scored-failing source runs required for scheduled self-improvement. Must be between 1 and 50: one self-improvement run can triage at most 50 failure findings. Omitted to use the server default. The age-based flush and manual dispatch are unchanged." }, "reviewer_emails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Owning-team member emails reviewers are chosen from. Only allowed when `reviewer_type` is `custom`: a Factory YAML change that sets emails with any other reviewer type fails validation, including the pull request check." }, "model": { "type": "string", "description": "The model self-improvement runs use, as a model ID or custom model router key. Falls back to `self_improvement_defaults.model` when not provided." } } }, "FactorySelfImprovementDefaults": { "type": "object", "required": [ "failed_run_threshold", "reviewer_type", "model" ], "properties": { "reviewer_type": { "type": "string", "enum": [ "none", "admins", "team" ], "description": "Reviewer pool used when the Factory declares no `reviewer_type`." }, "model": { "type": "string", "description": "Model self-improvement runs use when the Factory declares no `model`." }, "failed_run_threshold": { "type": "integer", "minimum": 1, "maximum": 50, "description": "Per-agent count of distinct scored-failing source runs that triggers scheduled self-improvement when the Factory declares no `failed_run_threshold`." } } }, "FactoryScoringConfig": { "type": "object", "required": [ "default_model" ], "properties": { "default_model": { "type": "string", "nullable": true, "description": "Optional factory override for the model used by managed scorers and\nscorer-creation prefills. null or absent resolves to the platform\njudge default. User-created scorers still require an explicit\nmodel_id on create.\n" } } }, "FactoryIntegration": { "type": "object", "description": "An integration provider attached to a factory.\n", "required": [ "type" ], "properties": { "type": { "$ref": "#/components/schemas/FactoryIntegrationProvider" }, "linear": { "allOf": [ { "$ref": "#/components/schemas/FactoryLinearIntegrationSettings" } ], "nullable": true, "description": "Linear team IDs from earlier integration selections, when present.\nIssue discovery follows enabled agent-session automations instead.\n" }, "jira": { "allOf": [ { "$ref": "#/components/schemas/FactoryJiraIntegrationSettings" } ], "nullable": true, "description": "Jira project keys from earlier integration selections, when present.\nIssue discovery follows enabled agent-session automations instead.\n" }, "slack": { "allOf": [ { "$ref": "#/components/schemas/FactorySlackIntegrationSettings" } ], "nullable": true, "description": "Persisted Slack settings. Present only when type is slack and the\nfactory has declared at least one Slack setting. Omitted fields\nkeep their default-on behavior.\n" }, "microsoft-teams": { "allOf": [ { "$ref": "#/components/schemas/FactoryTeamsIntegrationSettings" } ], "nullable": true, "description": "Persisted Teams reply settings. Valid only when type is\nmicrosoft-teams. Omitted settings remain undeclared.\n" } } }, "FactoryLinearIntegrationSettings": { "type": "object", "required": [ "team_ids" ], "properties": { "team_ids": { "type": "array", "description": "Linear team IDs for the one-time agent-session automation seed.\nDiscovery follows enabled seated automation filters afterward.\n", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "pattern": ".*\\S.*" } } } }, "FactorySlackIntegrationSettings": { "description": "Persisted Slack settings on a factory integration. Omitted fields keep\ntheir default-on behavior.\n", "allOf": [ { "$ref": "#/components/schemas/FactoryThreadReplySettings" } ] }, "FactoryTeamsIntegrationSettings": { "description": "Persisted Teams reply settings on a factory integration.", "allOf": [ { "$ref": "#/components/schemas/FactoryThreadReplySettings" } ] }, "FactoryThreadReplySettings": { "type": "object", "description": "Plain channel-thread reply settings. These apply when the shared\nper-Factory reply-setting rollout is enabled.\n", "properties": { "auto_respond_to_thread_replies": { "type": "boolean", "nullable": true, "description": "When true, eligible plain channel thread replies still reach the\nreply-intent classifier. When false, those replies are ignored\nunless they @-mention the Factory. Each provider defines the\nomitted default. Direct messages are unchanged.\n" } } }, "FactoryJiraIntegrationSettings": { "type": "object", "required": [ "project_keys" ], "properties": { "project_keys": { "type": "array", "description": "Jira project keys (for example APP, not the numeric project ID)\nfor the one-time agent-session automation seed. Discovery follows\nenabled seated automation filters afterward.\n", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "pattern": ".*\\S.*" } } } }, "FactoryIntegrationProvider": { "type": "string", "description": "Integration provider that can be attached to a factory. github is not\naccepted here; repository access comes from the factory's code forge.\n", "enum": [ "jira", "linear", "microsoft-teams", "slack" ] }, "FactoryCodeForge": { "type": "string", "description": "Primary source-control provider for the factory. GITHUB and GITLAB\nidentify the compatibility primary when repositories span one or more\nforges. AZURE_DEVOPS identifies Azure Repos. NONE declares a repo-less factory with no native repositories;\nits environment relies on setup_commands to clone from any host.\n", "enum": [ "GITHUB", "GITLAB", "AZURE_DEVOPS", "NONE" ] }, "FactoryRepositoryCodeForge": { "type": "string", "description": "The concrete source-control provider hosting a repository.", "enum": [ "GITHUB", "GITLAB", "AZURE_DEVOPS" ] }, "FactoryCredentialStrategy": { "type": "string", "description": "Default credential strategy for runs executed by the factory's named\nagents.\n- EXECUTOR (default): runs authenticate with the named agent's own\n credentials (e.g. a GitHub App installation token for the\n factory's team).\n- CREATOR: runs authenticate with the credentials of the principal\n that created the run.\n", "enum": [ "CREATOR", "EXECUTOR" ] }, "FactoryRepository": { "type": "object", "description": "A repository scoped to a factory.", "required": [ "owner", "repo" ], "properties": { "owner": { "type": "string", "description": "Repository owner (or full namespace for GitLab)." }, "repo": { "type": "string", "description": "Repository name." }, "code_forge": { "allOf": [ { "$ref": "#/components/schemas/FactoryRepositoryCodeForge" } ], "description": "The concrete forge hosting this repository. Omitted means the\nfactory's primary code_forge.\n" }, "provider_metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Provider-specific repository identity and settings, such as the Azure DevOps organization, project ID, and repository ID." } } }, "FactoryTaskStage": { "type": "string", "description": "Lifecycle stage of a factory task, mirroring the seeded factory agent\nroles plus the terminal COMPLETE and CANCELLED states. COMPLETE and\nCANCELLED are terminal in intent but not enforced: any stage may be\nwritten explicitly at any time. CANCELLED is set automatically when\nthe task's current top-level run is cancelled, regardless of that\nrun's agent type.\n", "enum": [ "TRIAGE", "SPEC", "IMPLEMENT", "REVIEW", "COMPLETE", "CANCELLED" ] }, "FactoryTaskCurrentRun": { "type": "object", "description": "A factory task's current top-level run, resolved from the bound\nconversation at read time. This differs from FactoryTask.run_id,\nwhich is a creation-time provenance snapshot and is never updated.\n", "required": [ "run_id", "state", "is_run_type_cancellable" ], "properties": { "run_id": { "type": "string", "description": "ID of the task's current top-level (root) run." }, "state": { "$ref": "#/components/schemas/RunState" }, "is_run_type_cancellable": { "type": "boolean", "description": "Whether the current run's type is eligible for cancellation via\nthe API. State-independent; clients should also gate on state.\n" } } }, "FactoryTask": { "type": "object", "description": "A factory task: the unit of work in a factory, bound to the agent\nconversation that owns it.\n", "required": [ "uid", "factory_uid", "conversation_id", "run_id", "title", "stage", "created_at", "updated_at" ], "properties": { "uid": { "type": "string", "description": "Public UID of the task." }, "factory_uid": { "type": "string", "description": "Public UID of the factory the task belongs to. Fixed at creation." }, "conversation_id": { "type": "string", "description": "UUID of the agent conversation the task is bound to." }, "run_id": { "type": "string", "description": "ID of the bound conversation's most recent run at task creation.\nThis is a provenance snapshot and is not updated afterward;\nconsumers needing the conversation's live latest run should\nresolve it via the conversation.\n" }, "author": { "allOf": [ { "$ref": "#/components/schemas/RunCreatorInfo" } ], "description": "Creator of the run captured by run_id. Omitted when the creation\nrun or its creator principal can no longer be resolved.\n" }, "title": { "type": "string", "description": "Human-readable title of the task." }, "ticket_source": { "type": "string", "description": "Canonical ticket source from the bound run. Present on list\nresponses only when full_list=true and ticket metadata exists.\n" }, "ticket_id": { "type": "string", "description": "Canonical ticket ID from the bound run. Present on list responses\nonly when full_list=true and ticket metadata exists.\n" }, "description": { "type": "string", "nullable": true, "description": "Optional description of the task." }, "stage": { "$ref": "#/components/schemas/FactoryTaskStage" }, "created_at": { "type": "string", "format": "date-time", "description": "Time the task was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "Time the task was last created, updated, or deleted. Artifact\nreporting does not bump this; new outputs appear on the next\ndetail read.\n" }, "outputs": { "type": "array", "items": { "$ref": "#/components/schemas/ArtifactItem" }, "description": "Derived outputs, newest-first: PULL_REQUEST, EXTERNAL_REFERENCE,\nSCREENSHOT, and FILE artifacts (video recordings are FILE\nartifacts). Present on single-task reads (by uid, by\nconversation, and by run), where outputs are derived from the\ntask's whole run tree (every run bound to the conversation plus\nthe runs dispatched under them). On list responses with\nfull_list=true, outputs are derived from the bound conversation\nonly, not the wider run tree.\n" }, "current_run": { "allOf": [ { "$ref": "#/components/schemas/FactoryTaskCurrentRun" } ], "description": "The task's current top-level run, resolved at read time. Present\non single-task reads (by uid, by conversation, and after a stop\nrequest), and on list responses when include_current_run=true;\nomitted when no current root run can be resolved.\n" } } }, "FactoryTaskNotificationKind": { "type": "string", "description": "The action requested by a Factory notification.", "enum": [ "question", "answer_question", "spec_review", "pr_review", "blocked", "failed" ] }, "FactoryInboxScope": { "type": "string", "description": "Personal or team-wide Factory Inbox visibility.", "enum": [ "mine", "team" ], "default": "mine" }, "FactoryInboxRecipient": { "type": "object", "description": "Minimal public identity for a live notification recipient.", "required": [ "uid" ], "properties": { "uid": { "type": "string", "description": "Public Warp user UID." }, "email": { "type": "string", "format": "email", "description": "Recipient email, when available." } } }, "FactoryAttentionQuestion": { "type": "object", "required": [ "id", "question", "type", "options" ], "properties": { "id": { "type": "string" }, "question": { "type": "string" }, "type": { "type": "string", "enum": [ "single_select", "multi_select" ] }, "options": { "type": "array", "items": { "type": "string" } }, "recommended_option_index": { "type": "integer" } } }, "FactoryInboxArtifact": { "type": "object", "description": "An inbox artifact link with an optional provider PR/MR title.", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "Artifact URL." }, "title": { "type": "string", "description": "Known provider PR/MR title, when available." } } }, "FactoryInboxItem": { "type": "object", "description": "One shared unresolved notification in the Factory Inbox.", "required": [ "notification_uid", "factory_uid", "factory_task_uid", "title", "stage", "kind", "created_at", "recipients" ], "properties": { "notification_uid": { "type": "string", "description": "Identifier accepted by the dismiss endpoint." }, "factory_uid": { "type": "string" }, "factory_task_uid": { "type": "string" }, "title": { "type": "string", "description": "Notification headline." }, "stage": { "$ref": "#/components/schemas/FactoryTaskStage" }, "kind": { "allOf": [ { "$ref": "#/components/schemas/FactoryTaskNotificationKind" } ] }, "is_read": { "type": "boolean", "description": "Whether the authenticated user has read this notification.\nAlways present in `mine` scope, including when false.\nOmitted in `team` scope, even when filtering by recipient.\n" }, "description": { "type": "string", "description": "Notification body, when present." }, "questions": { "type": "array", "items": { "$ref": "#/components/schemas/FactoryAttentionQuestion" } }, "origin_link": { "type": "string", "description": "Server-derived link back to the task's origin, when present." }, "url": { "type": "string", "description": "Legacy first artifact URL supplied by a review notification." }, "urls": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "string" }, "description": "Legacy artifact URLs; prefer artifacts for links and titles." }, "artifacts": { "type": "array", "items": { "$ref": "#/components/schemas/FactoryInboxArtifact" }, "description": "Ordered artifact links with optional provider PR/MR titles." }, "run_id": { "type": "string", "minLength": 1, "description": "Producing run ID from factory_task_notifications.created_by_run_id.\nPresent when the producing run is known.\n" }, "created_at": { "type": "string", "format": "date-time", "description": "Notification declaration time." }, "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/FactoryInboxRecipient" }, "description": "Live, undismissed recipients for this shared notification, sorted\ndeterministically. Slack routing and personal dismissal state are\nnot exposed.\n" } } }, "ListFactoryInboxResponse": { "type": "object", "required": [ "items", "page_info" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/FactoryInboxItem" } }, "page_info": { "$ref": "#/components/schemas/PageInfo" } } }, "FactoryInboxMutationRequest": { "type": "object", "required": [ "notification_uids" ], "properties": { "notification_uids": { "type": "array", "minItems": 1, "maxItems": 10000, "uniqueItems": true, "items": { "type": "string" } } } }, "FactoryInboxMutationOutcome": { "type": "object", "required": [ "notification_uid", "ok" ], "properties": { "notification_uid": { "type": "string" }, "ok": { "type": "boolean" } } }, "FactoryInboxMutationResponse": { "type": "object", "required": [ "outcomes" ], "properties": { "outcomes": { "type": "array", "items": { "$ref": "#/components/schemas/FactoryInboxMutationOutcome" } } } }, "FactoryTaskCreateRequest": { "type": "object", "description": "Request body for creating a factory task.", "required": [ "title", "conversation_id" ], "properties": { "title": { "type": "string", "description": "Human-readable title of the task. Required and non-empty." }, "conversation_id": { "type": "string", "description": "UUID of the agent conversation to bind the task to. The\nconversation's most recent run must be owned by the factory's\nteam, and the conversation must not already be bound to a live\ntask.\n" }, "description": { "type": "string", "nullable": true, "description": "Optional description of the task." }, "stage": { "$ref": "#/components/schemas/FactoryTaskStage" } } }, "FactoryTaskPatchRequest": { "type": "object", "description": "Request body for partially updating a factory task. Omitted fields\npreserve their current values; last write wins.\n", "properties": { "title": { "type": "string", "description": "Updated title. Must be non-empty when provided." }, "description": { "type": "string", "nullable": true, "description": "Updated description. null or an empty string clears the description." }, "stage": { "$ref": "#/components/schemas/FactoryTaskStage" } } }, "ListFactoryTasksResponse": { "type": "object", "required": [ "tasks", "page_info" ], "properties": { "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/FactoryTask" }, "description": "One page of the factory's tasks, in the requested sort order." }, "page_info": { "$ref": "#/components/schemas/PageInfo" } } }, "FactoryMetricsGroupByPeriod": { "type": "string", "description": "Binning granularity for factory metrics series. Weeks start on\nSunday (UTC), consistent with existing Warp analytics.\n", "enum": [ "day", "week", "month" ] }, "FactoryDollarsBreakdown": { "type": "object", "description": "US dollars the owning team was billed, split by source component:\ncompute (run execution), platform, and inference (recorded per\nconversation and counted once per distinct conversation). total is\nthe sum of the three. Each charge contributes its recorded billed\namount; charges recorded before billed amounts were tracked fall\nback to an estimated cost.\n", "required": [ "compute", "platform", "inference", "total" ], "properties": { "compute": { "type": "number", "format": "double" }, "platform": { "type": "number", "format": "double" }, "inference": { "type": "number", "format": "double" }, "total": { "type": "number", "format": "double" } } }, "FactoryDollarsBreakdownSeries": { "type": "object", "description": "Per-period dollar series aligned to period_list, zero-filled for\nperiods with no attributed cost.\n", "required": [ "compute", "platform", "inference", "total" ], "properties": { "compute": { "type": "array", "items": { "type": "number", "format": "double" } }, "platform": { "type": "array", "items": { "type": "number", "format": "double" } }, "inference": { "type": "array", "items": { "type": "number", "format": "double" } }, "total": { "type": "array", "items": { "type": "number", "format": "double" } } } }, "FactoryMetricCount": { "type": "object", "description": "A count metric: the aggregate total over the range, plus a\nper-period series when group_by_period was requested. Grouped\nbreakdowns (drill-down) may be added as new fields in the future.\n", "required": [ "total" ], "properties": { "total": { "type": "integer", "format": "int64" }, "series": { "type": "array", "description": "One entry per period_list entry, zero-filled. Present only when\ngroup_by_period was requested.\n", "items": { "type": "integer", "format": "int64" } } } }, "FactoryAverageMetric": { "type": "object", "description": "An average-valued metric: the aggregate average over the range,\nplus a per-period series when group_by_period was requested.\nThe aggregate and periods with no qualifying PRs read zero.\n", "required": [ "average" ], "properties": { "average": { "type": "number", "format": "double", "description": "Average value over the range; zero when no PRs qualified." }, "series": { "type": "array", "description": "One entry per period_list entry, zero-filled. Present only when\ngroup_by_period was requested.\n", "items": { "type": "number", "format": "double" } } } }, "FactoryCostPerPRSeries": { "type": "object", "description": "Per-period cost-per-PR series, aligned to period_list.", "required": [ "pr_count", "dollars", "mean", "compute_mean", "platform_mean", "inference_mean" ], "properties": { "pr_count": { "type": "array", "description": "Distinct PRs first seen in each period.", "items": { "type": "integer", "format": "int64" } }, "dollars": { "$ref": "#/components/schemas/FactoryDollarsBreakdownSeries" }, "mean": { "type": "array", "description": "Mean per-PR attributed cost per period, in US dollars; null\nfor periods with zero PRs.\n", "items": { "type": "number", "format": "double", "nullable": true } }, "compute_mean": { "type": "array", "description": "Mean per-PR compute cost per period, in US dollars; null for\nperiods with zero PRs.\n", "items": { "type": "number", "format": "double", "nullable": true } }, "platform_mean": { "type": "array", "description": "Mean per-PR platform cost per period, in US dollars; null for\nperiods with zero PRs.\n", "items": { "type": "number", "format": "double", "nullable": true } }, "inference_mean": { "type": "array", "description": "Mean per-PR inference cost per period, in US dollars; null for\nperiods with zero PRs.\n", "items": { "type": "number", "format": "double", "nullable": true } } } }, "FactoryCostPerPRMetric": { "type": "object", "description": "Cost per PR over the range, in US dollars: the cost of the run trees\nthat produced PRs (split evenly across each tree's PRs so a cost is\nnever double-counted), reported as the arithmetic mean of the\nper-PR costs.\n", "required": [ "pr_count", "dollars", "mean" ], "properties": { "pr_count": { "type": "integer", "format": "int64", "description": "Distinct PRs (deduped by URL) first seen in the range. Matches\npr_count.total today; kept separate so the cost denominator can\ndiverge (e.g. merged-only) in the future.\n" }, "dollars": { "$ref": "#/components/schemas/FactoryDollarsBreakdown" }, "mean": { "type": "number", "format": "double", "nullable": true, "description": "Mean per-PR attributed cost, in US dollars; null when\npr_count is 0.\n" }, "series": { "$ref": "#/components/schemas/FactoryCostPerPRSeries" } } }, "FactoryCostPerPRResponse": { "allOf": [ { "$ref": "#/components/schemas/FactoryMetricsEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "group_by_period": { "$ref": "#/components/schemas/FactoryMetricsGroupByPeriod" }, "period_list": { "type": "array", "description": "Period labels every series aligns to (dates like 2026-07-01;\nweeks labeled by their Sunday start date). Present only when\ngroup_by_period was requested.\n", "items": { "type": "string" } }, "data": { "$ref": "#/components/schemas/FactoryCostPerPRMetric" } } } ] }, "FactoryCostBreakdownGroupBy": { "type": "string", "description": "Grouping dimension for the cost-breakdown metric. source and user\nroll each run tree's cost to the root run; agent and model keep\neach run's own cost.\n", "enum": [ "source", "user", "agent", "model" ] }, "FactoryCostBreakdownGroup": { "type": "object", "description": "One group of the cost breakdown. key is the group's stable identity\n(dimension-specific: source type, user principal, agent uuid, or\nmodel id); UNKNOWN is reserved for missing/unresolvable values.\nlabel carries a server-resolved display name and is absent where\nthe key is already the display form. deleted is true when the\nentity behind a User or Agent key has been soft-deleted since\nincurring the spend; always false for Source/Model and UNKNOWN.\n", "required": [ "key", "deleted", "dollars" ], "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "deleted": { "type": "boolean" }, "photo_url": { "type": "string", "description": "Avatar URL when the group is a user with a resolvable photo." }, "dollars": { "$ref": "#/components/schemas/FactoryDollarsBreakdown" }, "series": { "allOf": [ { "$ref": "#/components/schemas/FactoryDollarsBreakdownSeries" } ], "description": "One entry per period_list entry, zero-filled. Present only when\ngroup_by_period was requested.\n" } } }, "FactoryCostBreakdownData": { "type": "object", "description": "Grouped spend. Groups are ordered by total descending (key\nascending on ties) with UNKNOWN always last. The server never caps\nor folds groups — every entity with nonzero spend is listed.\n", "required": [ "total", "groups" ], "properties": { "total": { "$ref": "#/components/schemas/FactoryDollarsBreakdown" }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/FactoryCostBreakdownGroup" } } } }, "FactoryCostBreakdownResponse": { "allOf": [ { "$ref": "#/components/schemas/FactoryMetricsEnvelope" }, { "type": "object", "required": [ "group_by", "data" ], "properties": { "group_by": { "$ref": "#/components/schemas/FactoryCostBreakdownGroupBy" }, "group_by_period": { "$ref": "#/components/schemas/FactoryMetricsGroupByPeriod" }, "period_list": { "type": "array", "description": "Period labels every series aligns to (dates like 2026-07-01;\nweeks labeled by their Sunday start date). Present only when\ngroup_by_period was requested.\n", "items": { "type": "string" } }, "data": { "$ref": "#/components/schemas/FactoryCostBreakdownData" } } } ] }, "FactoryMetricsData": { "type": "object", "required": [ "run_count", "pr_count", "merged_pr_count", "autonomy_funnel", "impact", "pr_latency", "average_human_interactions_per_pr" ], "properties": { "run_count": { "$ref": "#/components/schemas/FactoryMetricCount" }, "pr_count": { "$ref": "#/components/schemas/FactoryMetricCount" }, "merged_pr_count": { "allOf": [ { "$ref": "#/components/schemas/FactoryMetricCount" } ], "description": "Merged PRs, bucketed by the day the PR was created (merge day\nwhen the creation time was never observed) so the series reads\nas a cohort of pr_count: of the PRs from a period, how many\neventually merged. A recent period's value can therefore rise\nlater as its open PRs merge. Sourced from webhook-collected PR\nfacts, so coverage starts when collection began; earlier periods\nread zero.\n" }, "autonomy_funnel": { "$ref": "#/components/schemas/FactoryAutonomyFunnel" }, "impact": { "$ref": "#/components/schemas/FactoryImpact" }, "pr_latency": { "$ref": "#/components/schemas/FactoryPRLatency" }, "average_human_interactions_per_pr": { "allOf": [ { "$ref": "#/components/schemas/FactoryAverageMetric" } ], "description": "Average qualifying human interactions per factory-attributed PR\nin the range. The numerator includes live PR interactions with a\npresent, non-bot, non-GitHub-App actor and live delivered human\nSlack or Linear follow-ups. Every attributed PR is included in\nthe denominator, including those with zero interactions. Sourced\nfrom webhook-collected PR facts, so coverage starts when\ncollection began.\n" } } }, "FactoryAutonomyFunnel": { "type": "object", "description": "Autonomy funnel over PRs merged in the range, counted by merge time\n(merged_at in [start_date, end_date)); merged rows with no recorded\nmerge time are excluded, unlike merged_pr_count's opened-day cohort.\ntotal_merged is scoped to the factory's configured repositories\nwhile the factory_* stages follow run linkage regardless of\nrepository, so factory_merged can exceed total_merged when a\nrepository was renamed or removed — clients should clamp. Human\ncode-change verdicts are only complete for PRs whose open event was\nobserved (factory_merged_observed); sourced from webhook-collected PR\nfacts, so coverage starts when collection began.\n", "required": [ "total_merged", "factory_merged", "factory_merged_observed", "merged_without_human_code_change", "repos" ], "properties": { "total_merged": { "type": "integer", "format": "int64", "description": "All merged PRs — human- and agent-authored — in the factory's\nconfigured repositories.\n" }, "factory_merged": { "type": "integer", "format": "int64", "description": "Merged PRs produced by this factory's runs." }, "factory_merged_observed": { "type": "integer", "format": "int64", "description": "factory_merged restricted to PRs whose full history was\nobserved; the autonomy denominator.\n" }, "merged_without_human_code_change": { "type": "integer", "format": "int64", "description": "Observed merges where no person changed the code — the autonomy\nnumerator. A person opening the PR or pushing to it is a code\nchange; comments, reviews, and PR actions are not.\n" }, "repos": { "type": "array", "items": { "type": "string" }, "description": "The repositories total_merged was scoped to, as \"owner/repo\",\ndeduplicated in configuration order: the factory's configured\nrepositories as of this request, matched against PR facts by\ntheir current provider name.\n" } } }, "FactoryImpact": { "type": "object", "description": "Lines-changed impact of the factory's PRs merged in the range,\ncounted by merge time like autonomy_funnel; merged rows with no\nrecorded merge time are excluded. Line counts are snapshotted from\nwebhook payloads and can be unobserved, so additions/deletions sum\nonly the measured_pr_count PRs where both were recorded.\n", "required": [ "additions", "deletions", "merged_pr_count", "measured_pr_count" ], "properties": { "additions": { "type": "integer", "format": "int64", "description": "Lines added across the measured merged PRs." }, "deletions": { "type": "integer", "format": "int64", "description": "Lines deleted across the measured merged PRs." }, "merged_pr_count": { "type": "integer", "format": "int64", "description": "PRs produced by this factory's runs and merged in the range." }, "measured_pr_count": { "type": "integer", "format": "int64", "description": "merged_pr_count restricted to PRs whose line counts were\nobserved; the denominator for additions/deletions.\n" } } }, "FactoryLatencyStage": { "type": "object", "description": "One stage of the PR latency pipeline: the median duration across the\nPRs where both of the stage's endpoints were observed, plus how many\nPRs that was.\n", "required": [ "median_seconds", "measured_pr_count" ], "properties": { "median_seconds": { "type": "number", "format": "double", "nullable": true, "description": "p50 stage duration in seconds; null when measured_pr_count is\nzero. Durations are clamped at zero, so out-of-order provider\ntimestamps never produce negative values.\n" }, "measured_pr_count": { "type": "integer", "format": "int64", "description": "PRs with both stage endpoints observed." } } }, "FactoryPRLatency": { "type": "object", "description": "Median PR throughput/latency pipeline stages over the factory's PRs\nmerged in the range, counted by merge time like autonomy_funnel;\nkickoff is the creation time of the earliest of the factory's runs\nlinked to the PR (measured from the subrun when only a subrun\nreported it). First review is the earliest observed HUMAN review\nevent with a recorded time — any review state qualifies except bot\nreviews and GitHub App reviews (agent reviewers, CI) — so\nreview-anchored stages can be empty when the provider's review\nwebhooks are absent. Every stage is computed independently over the\nPRs where both endpoints were observed, so stage medians do not sum\nto kickoff_to_merge's median.\n", "required": [ "merged_pr_count", "kickoff_to_pr", "pr_to_first_review", "first_review_to_merge", "kickoff_to_merge" ], "properties": { "merged_pr_count": { "type": "integer", "format": "int64", "description": "PRs produced by this factory's runs and merged in the range." }, "kickoff_to_pr": { "allOf": [ { "$ref": "#/components/schemas/FactoryLatencyStage" } ], "description": "Run kickoff to PR creation." }, "pr_to_first_review": { "allOf": [ { "$ref": "#/components/schemas/FactoryLatencyStage" } ], "description": "PR creation to the first observed human review." }, "first_review_to_merge": { "allOf": [ { "$ref": "#/components/schemas/FactoryLatencyStage" } ], "description": "First observed human review to merge." }, "kickoff_to_merge": { "allOf": [ { "$ref": "#/components/schemas/FactoryLatencyStage" } ], "description": "Run kickoff to merge, measured end to end per PR." } } }, "FactoryPullRequestState": { "type": "string", "description": "The pull request's current state.", "enum": [ "open", "draft", "merged", "closed" ] }, "FactoryPullRequestHumanInteractions": { "type": "object", "description": "Actions people took on the pull request, counted by type. A person is\nnot a bot and not an app acting on a person's behalf. A review that\nwas later dismissed is not counted. A follow-up a person sent to the\nrun that produced the PR counts when it came through Slack, Linear,\nJira, Teams, the web app, or the API; messages relayed through the\nFactory MCP or a local agent do not count, and a follow-up sent as a\nGitHub comment counts once, as a PR comment or review. total is the\nsum of every type.\n", "required": [ "opened", "code_push", "review_approved", "review_changes_requested", "review_commented", "comment", "review_comment", "pr_action", "follow_up_message", "total" ], "properties": { "opened": { "type": "integer", "format": "int64", "description": "A person opened the PR." }, "code_push": { "type": "integer", "format": "int64", "description": "A person pushed code to the PR. Pushes are attributed to whoever\ntriggered them, so the code host's \"update branch\" button and\nrebases count.\n" }, "review_approved": { "type": "integer", "format": "int64", "description": "A person approved the PR." }, "review_changes_requested": { "type": "integer", "format": "int64", "description": "A person requested changes." }, "review_commented": { "type": "integer", "format": "int64", "description": "A person reviewed with comments only." }, "comment": { "type": "integer", "format": "int64", "description": "A person commented on the PR." }, "review_comment": { "type": "integer", "format": "int64", "description": "A person commented on a line of code." }, "pr_action": { "type": "integer", "format": "int64", "description": "Other PR actions by a person, such as closed, reopened, or marked ready." }, "follow_up_message": { "type": "integer", "format": "int64", "description": "A person sent a follow-up message to the run that produced the PR." }, "total": { "type": "integer", "format": "int64", "description": "The sum of every interaction type." } } }, "FactoryPullRequestRun": { "type": "object", "description": "One of the factory's runs that produced the pull request.", "required": [ "run_id", "root_run_id", "created_at" ], "properties": { "run_id": { "type": "string" }, "root_run_id": { "type": "string", "description": "The top-level run of the run's tree; equals run_id for a top-level run." }, "created_at": { "type": "string", "format": "date-time" } } }, "FactoryPullRequestCycleTime": { "type": "object", "description": "The pull request's pipeline-stage durations in seconds. Each stage\nis null when either end was not observed, and never negative.\nKickoff is when the earliest run that produced the PR was created;\nfirst review is the first review by a person.\n", "required": [ "kickoff_to_pr", "pr_to_first_review", "first_review_to_merge", "kickoff_to_merge" ], "properties": { "kickoff_to_pr": { "type": "number", "format": "double", "nullable": true }, "pr_to_first_review": { "type": "number", "format": "double", "nullable": true }, "first_review_to_merge": { "type": "number", "format": "double", "nullable": true }, "kickoff_to_merge": { "type": "number", "format": "double", "nullable": true } } }, "FactoryPullRequest": { "type": "object", "description": "One pull request produced by the factory's runs. Fields the code\nhost has not reported yet (title, size counts, times) are null.\n", "required": [ "provider", "repo_full_name", "pr_number", "url", "title", "author_login", "factory_uid", "team_uid", "state", "opened_at", "first_human_review_at", "merged_at", "closed_at", "updated_at", "additions", "deletions", "changed_files", "num_commits", "human_interactions", "human_code_change", "history_complete", "runs", "kickoff_at", "cycle_time" ], "properties": { "provider": { "$ref": "#/components/schemas/FactoryRepositoryCodeForge" }, "repo_full_name": { "type": "string", "description": "The repository as owner/repo." }, "pr_number": { "type": "integer", "description": "The provider's PR number." }, "url": { "type": "string", "description": "Canonical PR URL." }, "title": { "type": "string", "nullable": true, "description": "The PR title; null until the code host reports it." }, "author_login": { "type": "string", "nullable": true, "description": "The code-host login that opened the PR." }, "factory_uid": { "type": "string", "description": "Public UID of the factory whose runs produced the PR." }, "team_uid": { "type": "string", "description": "Public UID of the team that owns the factory." }, "state": { "$ref": "#/components/schemas/FactoryPullRequestState" }, "opened_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the PR was opened; null when Warp did not see it being opened." }, "first_human_review_at": { "type": "string", "format": "date-time", "nullable": true, "description": "The first review by a person; null when none was observed." }, "merged_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the PR was merged; null while it is not merged." }, "closed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the PR was closed, by merging or otherwise; null while it is open or when the code host did not report it." }, "updated_at": { "type": "string", "format": "date-time", "description": "When the PR itself last changed; the updated_after filter compares against it." }, "additions": { "type": "integer", "nullable": true, "description": "Lines added; null until the code host reports it." }, "deletions": { "type": "integer", "nullable": true, "description": "Lines deleted; null until the code host reports it." }, "changed_files": { "type": "integer", "nullable": true, "description": "Files changed; null until the code host reports it." }, "num_commits": { "type": "integer", "nullable": true, "description": "Commits on the PR; null until the code host reports it." }, "human_interactions": { "$ref": "#/components/schemas/FactoryPullRequestHumanInteractions" }, "human_code_change": { "type": "boolean", "description": "Whether a person changed the PR's code: any opened or code_push\ninteraction. False only means autonomous when history_complete\nis true.\n" }, "history_complete": { "type": "boolean", "description": "Whether Warp observed the PR from the moment it was opened. When\nfalse, interactions before Warp started watching the PR are\nmissing from the counts.\n" }, "runs": { "type": "array", "description": "The factory's runs that produced the PR, earliest first.", "items": { "$ref": "#/components/schemas/FactoryPullRequestRun" } }, "kickoff_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the earliest run that produced the PR was created." }, "cycle_time": { "$ref": "#/components/schemas/FactoryPullRequestCycleTime" } } }, "FactoryPullRequestsResponse": { "allOf": [ { "$ref": "#/components/schemas/FactoryMetricsEnvelope" }, { "type": "object", "required": [ "data", "page_info" ], "properties": { "data": { "type": "array", "description": "Newest opened first.", "items": { "$ref": "#/components/schemas/FactoryPullRequest" } }, "page_info": { "$ref": "#/components/schemas/PageInfo" } } } ] }, "FactoryTopPR": { "type": "object", "description": "One PR in the most-expensive-PRs listing: the pull request record\nfields plus cost and attribution. Cost fields are always present;\nattribution fields are null when every root run that produced the\nPR has been deleted; the remaining fields are null when the PR\npredates webhook PR-fact collection.\n", "required": [ "url", "dollars", "models" ], "properties": { "url": { "type": "string", "description": "Canonical PR URL; the listing's identity." }, "dollars": { "$ref": "#/components/schemas/FactoryDollarsBreakdown" }, "creator": { "allOf": [ { "$ref": "#/components/schemas/RunCreatorInfo" } ], "nullable": true, "description": "Who started the run that kicked off the PR." }, "source": { "type": "string", "nullable": true, "description": "Public source name of the run that kicked off the PR (e.g.\nGITHUB_WEBHOOK, SLACK, API). New values may appear over time.\n" }, "requested_model_id": { "type": "string", "nullable": true, "description": "Model the kicking-off run was configured with; null means the\nserver default was used.\n" }, "models": { "type": "array", "description": "Models recorded in the PR's run trees' conversation usage\nmetadata, most expensive first, each with its token-weighted\nshare of the PR's inference dollars. Shares sum approximately\nto dollars.inference: conversations without per-model token\ncounts contribute inference dollars but no shares. Empty when\nno per-model usage was recorded.\n", "items": { "$ref": "#/components/schemas/FactoryTopPRModel" } }, "provider": { "allOf": [ { "$ref": "#/components/schemas/FactoryRepositoryCodeForge" } ], "nullable": true, "description": "The code host the PR lives on." }, "repo_full_name": { "type": "string", "nullable": true, "description": "The repository as owner/repo." }, "pr_number": { "type": "integer", "nullable": true, "description": "The provider's PR number." }, "title": { "type": "string", "nullable": true, "description": "The PR title; null until the code host reports it." }, "author_login": { "type": "string", "nullable": true, "description": "The code-host login that opened the PR." }, "factory_uid": { "type": "string", "nullable": true, "description": "Public UID of the factory whose runs produced the PR." }, "team_uid": { "type": "string", "nullable": true, "description": "Public UID of the team that owns the factory." }, "state": { "allOf": [ { "$ref": "#/components/schemas/FactoryPullRequestState" } ], "nullable": true, "description": "The PR's current state." }, "opened_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the PR was opened; null when Warp did not see it being opened." }, "first_human_review_at": { "type": "string", "format": "date-time", "nullable": true, "description": "The first review by a person; null when none was observed." }, "merged_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the PR was merged; null while it is not merged." }, "closed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the PR was closed, by merging or otherwise; null while it is open or when the code host did not report it." }, "updated_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the PR itself last changed." }, "additions": { "type": "integer", "nullable": true, "description": "Lines added; null until the code host reports it." }, "deletions": { "type": "integer", "nullable": true, "description": "Lines deleted; null until the code host reports it." }, "changed_files": { "type": "integer", "nullable": true, "description": "Files changed; null until the code host reports it." }, "num_commits": { "type": "integer", "nullable": true, "description": "Commits on the PR; null until the code host reports it." }, "human_interactions": { "allOf": [ { "$ref": "#/components/schemas/FactoryPullRequestHumanInteractions" } ], "nullable": true, "description": "Actions people took on the PR, counted by type." }, "human_code_change": { "type": "boolean", "nullable": true, "description": "Whether a person changed the PR's code: any opened or code_push\ninteraction. False only means autonomous when history_complete\nis true.\n" }, "history_complete": { "type": "boolean", "nullable": true, "description": "Whether Warp observed the PR from the moment it was opened. When\nfalse, interactions before Warp started watching the PR are\nmissing from the counts.\n" }, "runs": { "type": "array", "nullable": true, "description": "The factory's runs that produced the PR, earliest first.", "items": { "$ref": "#/components/schemas/FactoryPullRequestRun" } }, "kickoff_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the earliest run that produced the PR was created." }, "cycle_time": { "allOf": [ { "$ref": "#/components/schemas/FactoryPullRequestCycleTime" } ], "nullable": true, "description": "The PR's pipeline-stage durations in seconds." } } }, "FactoryTopPRModel": { "type": "object", "description": "One model's share of a top PR's inference cost.", "required": [ "model_id", "inference_dollars" ], "properties": { "model_id": { "type": "string" }, "inference_dollars": { "type": "number", "format": "double", "description": "The model's token-weighted share of the PR's inference dollars.\nInference only; compute and platform costs have no model\nattribution.\n" } } }, "FactoryTopPRsResponse": { "allOf": [ { "$ref": "#/components/schemas/FactoryMetricsEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "Most expensive first.", "items": { "$ref": "#/components/schemas/FactoryTopPR" } } } } ] }, "FactoryMetricsEnvelope": { "type": "object", "description": "Fields every factory-scoped metrics response carries alongside its\ndata, so responses from several factories can be combined or told\napart.\n", "required": [ "as_of", "team_uid", "factory_uid" ], "properties": { "as_of": { "type": "string", "format": "date-time", "description": "The time the data is current as of. Data can lag live activity\nby a few minutes.\n" }, "team_uid": { "type": "string", "description": "Public UID of the team that owns the factory." }, "factory_uid": { "type": "string", "description": "Public UID of the factory the response is scoped to." } } }, "FactoryMetricsResponse": { "allOf": [ { "$ref": "#/components/schemas/FactoryMetricsEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "group_by_period": { "$ref": "#/components/schemas/FactoryMetricsGroupByPeriod" }, "period_list": { "type": "array", "description": "Period labels every series aligns to (dates like 2026-07-01;\nweeks labeled by their Sunday start date). Present only when\ngroup_by_period was requested.\n", "items": { "type": "string" } }, "data": { "$ref": "#/components/schemas/FactoryMetricsData" } } } ] }, "FactoryRunBreakdownGroupBy": { "type": "string", "description": "Grouping dimension for the run-breakdown metric. source counts\ntop-level runs only; every other dimension counts subruns\nindividually.\n", "enum": [ "agent_type", "status", "source", "root_vs_subrun", "model", "harness" ] }, "FactoryRunBreakdownGroup": { "type": "object", "description": "One group of the run breakdown. key is the group's stable identity\n(dimension-specific: agent type, run state, source type,\nROOT/SUBRUN, model id, or harness name); OTHER and UNKNOWN are\nreserved for the top-K rollup and missing/unresolvable values\nrespectively. label carries a server-resolved display name (harness\nnames, source aliases) and is absent where the key is already the\ndisplay form.\n", "required": [ "key", "total" ], "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "total": { "type": "integer", "format": "int64" }, "series": { "type": "array", "description": "One entry per period_list entry, zero-filled. Present only when\ngroup_by_period was requested.\n", "items": { "type": "integer", "format": "int64" } } } }, "FactoryRunBreakdownData": { "type": "object", "description": "Grouped run counts. Groups are ordered by total descending (key\nascending on ties) with the reserved buckets always last — UNKNOWN,\nthen OTHER; group totals and series sum to total and its per-period\ndistribution.\n", "required": [ "total", "root_run_count", "groups" ], "properties": { "total": { "type": "integer", "format": "int64", "description": "Sum over groups — top-level runs only when root_runs_only is\ntrue, so it can undercount the run_count metric there.\n" }, "root_run_count": { "type": "integer", "format": "int64", "description": "The factory's top-level runs (no parent run) in the range,\nwhatever the dimension — the dashboard's companion stat to the\nall-runs headline. Equals total on root-scoped dimensions.\n" }, "root_runs_only": { "type": "boolean", "description": "Present and true for the source dimension, which counts\ntop-level runs only.\n" }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/FactoryRunBreakdownGroup" } } } }, "FactoryRunBreakdownResponse": { "allOf": [ { "$ref": "#/components/schemas/FactoryMetricsEnvelope" }, { "type": "object", "required": [ "group_by", "data" ], "properties": { "group_by": { "$ref": "#/components/schemas/FactoryRunBreakdownGroupBy" }, "group_by_period": { "$ref": "#/components/schemas/FactoryMetricsGroupByPeriod" }, "period_list": { "type": "array", "description": "Period labels every series aligns to (dates like 2026-07-01;\nweeks labeled by their Sunday start date). Present only when\ngroup_by_period was requested.\n", "items": { "type": "string" } }, "data": { "$ref": "#/components/schemas/FactoryRunBreakdownData" } } } ] }, "FactoryPRSizeBucket": { "type": "string", "description": "A PR's T-shirt size, derived from its webhook-collected line counts\n(additions + deletions): S < 100, M < 500, L < 1000, XL >= 1000.\n", "enum": [ "S", "M", "L", "XL" ] }, "FactoryCostByPRSizeBucket": { "type": "object", "description": "One size bucket's cost distribution. Mean cost follows the\ncost_per_pr attribution (even run-tree split, in the US dollars the\nowning team was billed).\n", "required": [ "size", "pr_count", "mean" ], "properties": { "size": { "$ref": "#/components/schemas/FactoryPRSizeBucket" }, "pr_count": { "type": "integer", "format": "int64", "description": "Sized PRs in this bucket first seen in the range." }, "mean": { "type": "number", "format": "double", "nullable": true, "description": "Mean per-PR attributed cost in US dollars; null when the\nbucket has no PRs in the range.\n" }, "mean_series": { "type": "array", "description": "Mean per-PR cost per period, aligned to period_list; null\nfor periods where the bucket has no PRs. Present only when\ngroup_by_period was requested.\n", "items": { "type": "number", "format": "double", "nullable": true } } } }, "FactoryCostByPRSizeData": { "type": "object", "description": "PR cost distribution by size. buckets always lists every size,\nsmallest first, so the roster is stable; empty buckets carry\npr_count 0 and a null mean. sized_pr_count <= pr_count — the\ndifference is the PRs whose line counts were never observed and\nare excluded from every bucket.\n", "required": [ "pr_count", "sized_pr_count", "buckets" ], "properties": { "pr_count": { "type": "integer", "format": "int64", "description": "Every PR first seen in the range, sized or not." }, "sized_pr_count": { "type": "integer", "format": "int64", "description": "PRs with observed line counts — the buckets' coverage." }, "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/FactoryCostByPRSizeBucket" } } } }, "FactoryCostByPRSizeResponse": { "allOf": [ { "$ref": "#/components/schemas/FactoryMetricsEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "group_by_period": { "$ref": "#/components/schemas/FactoryMetricsGroupByPeriod" }, "period_list": { "type": "array", "description": "Period labels every series aligns to (dates like 2026-07-01;\nweeks labeled by their Sunday start date). Present only when\ngroup_by_period was requested.\n", "items": { "type": "string" } }, "data": { "$ref": "#/components/schemas/FactoryCostByPRSizeData" } } } ] }, "ListFactoriesResponse": { "type": "object", "description": "Response body for listing factories.", "required": [ "factories", "page_info" ], "properties": { "factories": { "type": "array", "items": { "$ref": "#/components/schemas/Factory" } }, "page_info": { "$ref": "#/components/schemas/PageInfo" } } }, "FactoryRunRequest": { "type": "object", "description": "Request body for dispatching a run to a factory.", "required": [ "prompt" ], "properties": { "prompt": { "type": "string", "description": "The prompt sent to the factory's foreman, not wrapped in any\nfactory intake envelope. Required and non-empty.\n" }, "title": { "type": "string", "description": "Human-readable title for the dispatched run and its factory task.\nOmit to derive one automatically from the prompt.\n" }, "ticket_ref": { "type": "string", "description": "Originating ticket reference in : form (for\nexample, linear:REMOTE-123); omit to mint an adhoc reference.\nStamped onto the run as ticket_id/ticket_source metadata.\n" }, "ticket_url": { "type": "string", "description": "Optional URL of the ticket named by ticket_ref. Stamped onto\nthe run as ticket_url metadata when given.\n" } } }, "FactoryRunResponse": { "type": "object", "description": "Response body for a dispatched factory run.", "required": [ "run_id", "state", "factory_uid", "foreman_agent", "ticket_ref" ], "properties": { "run_id": { "type": "string", "description": "Unique identifier for the dispatched run." }, "run_url": { "type": "string", "description": "URL to view the dispatched run in the Factory app. Empty when\nthe Factory app origin is not configured.\n" }, "state": { "$ref": "#/components/schemas/RunState" }, "factory_uid": { "type": "string", "description": "Public UID of the factory the run was dispatched to." }, "foreman_agent": { "type": "string", "description": "Name of the factory's foreman agent that received the run." }, "ticket_ref": { "type": "string", "description": "The canonical : ticket reference the run was\nstamped with, either the caller-supplied ticket_ref or a\nminted adhoc reference.\n" } } }, "ClaudeHarnessUsagePayload": { "type": "object", "additionalProperties": false, "properties": { "usage": { "$ref": "#/components/schemas/ClaudeTokenUsage" }, "attribution": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/ClaudeAttributedUsage" } }, "toolCalls": { "$ref": "#/components/schemas/HarnessToolCalls" } } }, "CodexHarnessUsagePayload": { "type": "object", "additionalProperties": false, "properties": { "usage": { "$ref": "#/components/schemas/CodexTokenUsage" }, "attribution": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/CodexAttributedUsage" } }, "toolCalls": { "$ref": "#/components/schemas/HarnessToolCalls" } } }, "HarnessUsageCounter": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 9223372036854776000, "nullable": true, "description": "A native count. Absent or null means unmeasured, not zero." }, "ClaudeTokenUsage": { "type": "object", "additionalProperties": false, "nullable": true, "description": "Native cumulative token categories; cache counters are not added to input_tokens.", "properties": { "input_tokens": { "$ref": "#/components/schemas/HarnessUsageCounter" }, "output_tokens": { "$ref": "#/components/schemas/HarnessUsageCounter" }, "cache_read_input_tokens": { "$ref": "#/components/schemas/HarnessUsageCounter" }, "cache_creation_input_tokens": { "$ref": "#/components/schemas/HarnessUsageCounter" }, "cache_creation": { "$ref": "#/components/schemas/ClaudeCacheCreationUsage" } } }, "ClaudeCacheCreationUsage": { "type": "object", "additionalProperties": false, "nullable": true, "properties": { "ephemeral_5m_input_tokens": { "$ref": "#/components/schemas/HarnessUsageCounter" }, "ephemeral_1h_input_tokens": { "$ref": "#/components/schemas/HarnessUsageCounter" } } }, "CodexTokenUsage": { "type": "object", "additionalProperties": false, "nullable": true, "description": "Native checkpoint counters. Cached input and reasoning output may overlap other categories; no derived total is inferred.", "properties": { "input_tokens": { "$ref": "#/components/schemas/HarnessUsageCounter" }, "cached_input_tokens": { "$ref": "#/components/schemas/HarnessUsageCounter" }, "cache_write_input_tokens": { "$ref": "#/components/schemas/HarnessUsageCounter" }, "output_tokens": { "$ref": "#/components/schemas/HarnessUsageCounter" }, "reasoning_output_tokens": { "$ref": "#/components/schemas/HarnessUsageCounter" }, "total_tokens": { "$ref": "#/components/schemas/HarnessUsageCounter" } } }, "ClaudeAttributedUsage": { "type": "object", "additionalProperties": false, "required": [ "usage" ], "properties": { "model": { "type": "string", "nullable": true }, "service_tier": { "type": "string", "nullable": true }, "inference_geo": { "type": "string", "nullable": true }, "speed": { "type": "string", "nullable": true }, "usage": { "$ref": "#/components/schemas/ClaudeTokenUsage" } } }, "CodexAttributedUsage": { "type": "object", "additionalProperties": false, "required": [ "usage" ], "properties": { "model": { "type": "string", "nullable": true }, "service_tier": { "type": "string", "nullable": true }, "inference_geo": { "type": "string", "nullable": true }, "speed": { "type": "string", "nullable": true }, "usage": { "$ref": "#/components/schemas/CodexTokenUsage" } } }, "HarnessToolCalls": { "type": "object", "additionalProperties": false, "nullable": true, "required": [ "total", "byName" ], "description": "Native tool invocation counts. Total must equal the sum of byName; tool names are arbitrary map keys.", "properties": { "total": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 9223372036854776000 }, "byName": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 9223372036854776000 } } } }, "GetRunHarnessUsageResponse": { "type": "object", "required": [ "run_id", "conversation_id", "available" ], "properties": { "run_id": { "type": "string" }, "conversation_id": { "type": "string" }, "available": { "type": "boolean" }, "age_seconds": { "type": "integer", "format": "int64", "nullable": true }, "usage": { "$ref": "#/components/schemas/HarnessUsageEnvelope" } } }, "HarnessUsageEnvelope": { "oneOf": [ { "$ref": "#/components/schemas/ClaudeHarnessUsageEnvelope" }, { "$ref": "#/components/schemas/CodexHarnessUsageEnvelope" } ], "discriminator": { "propertyName": "harness", "mapping": { "CLAUDE_CODE": "#/components/schemas/ClaudeHarnessUsageEnvelope", "CODEX": "#/components/schemas/CodexHarnessUsageEnvelope" } } }, "ClaudeHarnessUsageEnvelope": { "type": "object", "additionalProperties": false, "required": [ "metricsVersion", "harness", "executionId", "captureSequence", "capturedAt", "snapshot" ], "properties": { "metricsVersion": { "type": "integer", "enum": [ 1 ], "description": "Server-owned storage format metadata, not the producer's parser version." }, "harness": { "type": "string", "enum": [ "CLAUDE_CODE" ] }, "executionId": { "type": "integer", "format": "int64" }, "captureSequence": { "type": "integer", "format": "int64" }, "capturedAt": { "type": "string", "format": "date-time" }, "snapshot": { "type": "object", "additionalProperties": false, "required": [ "coverage", "payload" ], "properties": { "coverage": { "$ref": "#/components/schemas/RetainedHarnessUsageCoverage" }, "payload": { "$ref": "#/components/schemas/ClaudeHarnessUsagePayload" } } } } }, "CodexHarnessUsageEnvelope": { "type": "object", "additionalProperties": false, "required": [ "metricsVersion", "harness", "executionId", "captureSequence", "capturedAt", "snapshot" ], "properties": { "metricsVersion": { "type": "integer", "enum": [ 1 ], "description": "Server-owned storage format metadata, not the producer's parser version." }, "harness": { "type": "string", "enum": [ "CODEX" ] }, "executionId": { "type": "integer", "format": "int64" }, "captureSequence": { "type": "integer", "format": "int64" }, "capturedAt": { "type": "string", "format": "date-time" }, "snapshot": { "type": "object", "additionalProperties": false, "required": [ "coverage", "payload" ], "properties": { "coverage": { "$ref": "#/components/schemas/RetainedHarnessUsageCoverage" }, "payload": { "$ref": "#/components/schemas/CodexHarnessUsagePayload" } } } } }, "RetainedHarnessUsageCoverage": { "type": "object", "additionalProperties": false, "required": [ "tokenStatus", "toolStatus" ], "properties": { "tokenStatus": { "type": "string", "enum": [ "known", "partial", "unavailable" ] }, "toolStatus": { "type": "string", "enum": [ "known", "partial", "unavailable" ] } } }, "RunAgentRequest": { "type": "object", "description": "Request body for creating a new agent run.\nEither prompt or skill (via skill field, config.skill_spec, or config.skills) is required,\nexcept for handoff requests that set conversation_id.\n", "properties": { "prompt": { "type": "string", "description": "The prompt/instruction for the agent to execute.\nRequired unless a skill is specified via the skill field, config.skill_spec, or config.skills.\nHandoff requests may omit prompt when conversation_id is set.\n" }, "mode": { "$ref": "#/components/schemas/AgentRunMode", "description": "Optional query mode for the run. Defaults to `normal` when omitted.\nThe server does not infer mode from prompt prefixes such as `/plan`,\nso callers should pass this field explicitly to request non-normal behavior.\n" }, "skill": { "type": "string", "description": "Skill specification to use as the base prompt for the agent.\nSupported formats:\n - \"repo:skill_name\" - Simple name in specific repo\n - \"repo:skill_path\" - Full path in specific repo\n - \"org/repo:skill_name\" - Simple name with org and repo\n - \"org/repo:skill_path\" - Full path with org and repo\nWhen provided, this takes precedence over config.skill_spec.\n" }, "config": { "$ref": "#/components/schemas/AmbientAgentConfig" }, "title": { "type": "string", "description": "Custom title for the run (auto-generated if not provided)" }, "team": { "type": "boolean", "description": "Whether to create a team-owned run.\nDefaults to true for users on a single team.\n" }, "agent_identity_uid": { "type": "string", "description": "Optional agent identity UID to use as the execution principal for the run.\nThis is only valid for runs that are team owned.\n" }, "on_behalf_of": { "type": "string", "description": "Optional email address or user ID of a Warp user to attribute\nthe run to; when set, the resolved user becomes the run's\ncreator instead of the caller. Only agent API keys may use this\nfield, only when the calling agent has on_behalf_of enabled in\nits configuration (a team admin must turn this on per agent),\nand only for team-owned runs. The target user must be an active\nmember of the run's owner team.\n" }, "conversation_id": { "type": "string", "description": "Optional conversation ID to continue an existing conversation.\nIf provided, the agent will continue from where the previous run left off.\n" }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/AttachmentInput" }, "description": "Optional file attachments to include with the prompt (max 5).\nAttachments are uploaded to cloud storage and made available to the agent.\n" }, "parent_run_id": { "type": "string", "description": "Optional run ID of the parent that spawned this run, used for\norchestration hierarchies; the parent run must exist and be\nvisible to the caller, or the request is rejected with a 400.\nChild runs are also subject to the server's maximum\norchestration depth, and requests that would exceed it are\nrejected with a 400.\n" }, "interactive": { "type": "boolean", "description": "Whether the run should be interactive.\nIf not set, defaults to false.\n" }, "metadata": { "$ref": "#/components/schemas/RunMetadata" } } }, "RunMetadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom key/value metadata attached to a run at creation time and\nimmutable afterward; at most 20 keys, with keys 1-64 bytes matching\n[a-zA-Z0-9._-]+ (case-sensitive) and values 0-256 bytes of UTF-8 with\nno NUL characters. Requests with invalid metadata are rejected. A\nrun's effective metadata is merged per key at creation: explicit\nrequest keys override keys inherited from the parent run, which\noverride automatic keys (ticket_id and ticket_source on Linear- and\nJira-triggered runs).\n" }, "RunAgentResponse": { "type": "object", "required": [ "run_id", "task_id", "state" ], "properties": { "run_id": { "type": "string", "description": "Unique identifier for the created run" }, "task_id": { "type": "string", "deprecated": true, "description": "Unique identifier for the task (same as run_id). Deprecated - use run_id instead." }, "state": { "$ref": "#/components/schemas/RunState" }, "at_capacity": { "type": "boolean", "description": "Whether the system is at capacity when the run was created" } } }, "AgentRunMode": { "type": "string", "description": "Query mode for an agent run.\n - normal: Standard user query (default).\n - plan: Planning Mode. The agent researches and creates a plan, then waits for approval before execution.\n - orchestrate: Orchestration Mode. The agent proposes an orchestration plan and must not start child agents until approved.\n", "enum": [ "normal", "plan", "orchestrate" ], "default": "normal" }, "ListRunsResponse": { "type": "object", "required": [ "runs", "page_info", "as_of", "team_uid" ], "properties": { "runs": { "type": "array", "items": { "$ref": "#/components/schemas/RunItem" } }, "page_info": { "$ref": "#/components/schemas/PageInfo" }, "as_of": { "type": "string", "format": "date-time", "description": "Time the runs were read (RFC3339). Data can lag live activity by a few minutes." }, "team_uid": { "type": "string", "nullable": true, "description": "UID of the team the request was scoped to: the team selected by the\n`X-Warp-Team-Uid` header, or the API key's team. Null when a user\nrequest has no team selected and the list spans every team the\nuser belongs to.\n" } } }, "RunItem": { "type": "object", "required": [ "run_id", "task_id", "title", "state", "prompt", "created_at", "finished_at", "updated_at", "root_run_id" ], "properties": { "run_id": { "type": "string", "description": "Unique identifier for the run" }, "task_id": { "type": "string", "deprecated": true, "description": "Unique identifier for the task (typically matches run_id). Deprecated - use run_id instead." }, "title": { "type": "string", "description": "Human-readable title for the run" }, "state": { "$ref": "#/components/schemas/RunState" }, "execution_location": { "$ref": "#/components/schemas/RunExecutionLocation" }, "prompt": { "type": "string", "description": "The prompt/instruction for the agent" }, "submitted_prompt": { "type": "string", "description": "The prompt exactly as it was submitted, without any extra context added by Warp. Includes any follow-up messages sent before the run started, separated by blank lines." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the run was created (RFC3339)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the run was last updated (RFC3339)" }, "run_time": { "type": "string", "format": "duration", "description": "Total runtime as an ISO 8601 duration (e.g. \"PT2M30S\"), computed server-side from run executions." }, "started_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the agent started working on the run (RFC3339)" }, "finished_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the run last reached a terminal state (RFC3339). Null\nwhile the run is still active, and for terminal runs with no\nrecorded finish time (runs executed locally, and runs that finished\nbefore finish times were recorded).\n" }, "status_message": { "$ref": "#/components/schemas/RunStatusMessage" }, "source": { "$ref": "#/components/schemas/RunSourceType" }, "schedule": { "$ref": "#/components/schemas/ScheduleInfo" }, "session_id": { "type": "string", "description": "UUID of the shared session (if available)" }, "session_link": { "type": "string", "format": "uri", "description": "URL to view the agent session" }, "trigger_url": { "type": "string", "format": "uri", "description": "URL to the run trigger (e.g. Slack thread, Linear issue, schedule)" }, "creator": { "$ref": "#/components/schemas/RunCreatorInfo" }, "executor": { "$ref": "#/components/schemas/RunCreatorInfo" }, "factory_uid": { "type": "string", "description": "UID of the factory whose agent executed the run. Absent for runs\nnot executed by a factory agent.\n" }, "request_usage": { "$ref": "#/components/schemas/RequestUsage" }, "agent_config": { "$ref": "#/components/schemas/AmbientAgentConfig" }, "conversation_id": { "type": "string", "description": "UUID of the conversation associated with the run" }, "parent_run_id": { "type": "string", "description": "UUID of the parent run that spawned this run" }, "root_run_id": { "type": "string", "description": "UUID of the top-level run of this run's orchestration tree. Equals\n`run_id` for a top-level run.\n" }, "metadata": { "$ref": "#/components/schemas/RunMetadata" }, "is_sandbox_running": { "type": "boolean", "description": "Whether the sandbox environment is currently running" }, "is_run_type_cancellable": { "type": "boolean", "description": "Whether the run's type is eligible for cancellation via the API. State-independent:\nfalse for GitHub Action and local runs; true for all other run types (including\nself-hosted). Clients should still gate the control on the run's current state.\n" }, "debug_agent_available": { "type": "boolean", "description": "Whether a debug agent can currently be started inside this run's retained\nsetup-failure session. Only true for a run that failed during environment setup,\nwhose retained execution is still reachable, and whose debug window has not\nclosed. See `POST /agent/runs/{runId}/followups`.\n" }, "artifacts": { "type": "array", "items": { "$ref": "#/components/schemas/ArtifactItem" }, "description": "Artifacts created during the run (plans, pull requests, etc.)" }, "agent_skill": { "$ref": "#/components/schemas/AgentSkill" }, "scope": { "$ref": "#/components/schemas/Scope" } } }, "GetRunTimelineResponse": { "type": "object", "description": "Response body for listing run timeline events.", "required": [ "events" ], "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/AIRunTimelineEvent" } } } }, "AIRunTimelineEvent": { "type": "object", "description": "A setup or lifecycle event recorded for an agent run.", "required": [ "event_uuid", "run_id", "event_type", "occurred_at" ], "properties": { "event_uuid": { "type": "string", "description": "Unique client- or server-generated identifier for this event." }, "run_id": { "type": "string", "description": "Run that owns this event." }, "execution_id": { "type": "integer", "format": "int64", "description": "Run execution associated with this event, when available." }, "event_type": { "$ref": "#/components/schemas/AIRunTimelineEventType" }, "occurred_at": { "type": "string", "format": "date-time", "description": "Timestamp when the event occurred." }, "payload": { "type": "object", "additionalProperties": true, "description": "Optional event-specific JSON payload. Contents vary by event type." } } }, "AIRunTimelineEventType": { "type": "string", "description": "Type of timeline event recorded for a run.", "enum": [ "oz_run_created", "oz_run_claimed", "worker_container_ready", "shared_session_started", "agent_started", "oz_run_done", "oz_run_blocked", "oz_run_cancelled", "oz_run_failed", "oz_run_errored", "vm_shutdown", "run_retry_scheduled" ] }, "ConversationResponse": { "type": "object", "required": [ "conversation_id", "steps" ], "properties": { "conversation_id": { "type": "string", "description": "Unique identifier for the conversation" }, "steps": { "type": "array", "description": "Root steps in the conversation", "items": { "$ref": "#/components/schemas/ConversationStep" } } } }, "ConversationStep": { "type": "object", "required": [ "id", "messages", "steps" ], "properties": { "id": { "type": "string", "description": "Unique identifier for the step" }, "description": { "type": "string", "description": "Original instruction or delegated work description for the step" }, "summary": { "type": "string", "description": "Summary of the work completed for the step" }, "started_at": { "type": "string", "format": "date-time", "description": "Earliest transcript message timestamp contained in this step or any nested step (RFC3339)" }, "completed_at": { "type": "string", "format": "date-time", "description": "Latest transcript message timestamp contained in this step or any nested step (RFC3339)" }, "messages": { "type": "array", "description": "Ordered normalized messages for this step", "items": { "$ref": "#/components/schemas/ConversationMessage" } }, "steps": { "type": "array", "description": "Nested delegated work performed as part of this step", "items": { "$ref": "#/components/schemas/ConversationStep" } } } }, "ConversationMessage": { "type": "object", "required": [ "role", "content" ], "properties": { "message_ids": { "type": "array", "description": "Underlying transcript message IDs grouped into this normalized message", "items": { "type": "string" } }, "request_id": { "type": "string", "description": "Request identifier shared by transcript messages from the same request, when available" }, "role": { "$ref": "#/components/schemas/ConversationMessageRole" }, "timestamp": { "type": "string", "format": "date-time", "description": "Timestamp of the first transcript message included in this normalized message (RFC3339)" }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationContentBlock" } } } }, "ConversationMessageRole": { "type": "string", "description": "Role of the normalized message", "enum": [ "user", "assistant", "tool", "system" ] }, "ConversationContentBlock": { "oneOf": [ { "$ref": "#/components/schemas/TextContentBlock" }, { "$ref": "#/components/schemas/ActionContentBlock" }, { "$ref": "#/components/schemas/ActionResultContentBlock" }, { "$ref": "#/components/schemas/EventContentBlock" } ], "discriminator": { "propertyName": "type", "mapping": { "text": "#/components/schemas/TextContentBlock", "action": "#/components/schemas/ActionContentBlock", "action_result": "#/components/schemas/ActionResultContentBlock", "event": "#/components/schemas/EventContentBlock" } } }, "TextContentBlock": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "text" ] }, "message_id": { "type": "string", "description": "Underlying transcript message ID that produced this content block, when available" }, "text": { "type": "string", "description": "Plain text content" } } }, "ActionCategory": { "type": "string", "description": "High-level category of an action performed during the conversation", "enum": [ "command", "files", "search", "integration", "documents", "computer", "review", "skill" ] }, "ActionState": { "type": "string", "description": "State of an action result", "enum": [ "running", "completed", "failed", "denied" ] }, "ActionContentBlock": { "type": "object", "required": [ "type", "id", "category", "name", "input" ], "properties": { "type": { "type": "string", "enum": [ "action" ] }, "message_id": { "type": "string", "description": "Underlying transcript message ID that produced this content block, when available" }, "id": { "type": "string", "description": "Unique identifier for the action" }, "category": { "$ref": "#/components/schemas/ActionCategory" }, "name": { "type": "string", "description": "Public action name, such as run_command or edit_files" }, "input": { "type": "object", "additionalProperties": true, "description": "Curated public input for this action. This object is owned by the API and is not a raw internal tool payload." } } }, "ActionResultContentBlock": { "type": "object", "required": [ "type", "action_id", "category", "name", "state", "output" ], "properties": { "type": { "type": "string", "enum": [ "action_result" ] }, "message_id": { "type": "string", "description": "Underlying transcript message ID that produced this content block, when available" }, "action_id": { "type": "string", "description": "Identifier of the corresponding action" }, "category": { "$ref": "#/components/schemas/ActionCategory" }, "name": { "type": "string", "description": "Public action name matching the corresponding action block" }, "state": { "$ref": "#/components/schemas/ActionState" }, "output": { "type": "object", "additionalProperties": true, "description": "Curated public result for this action. Large or binary internal payloads should be summarized rather than passed through raw." } } }, "EventContentBlock": { "type": "object", "required": [ "type", "name", "data" ], "properties": { "type": { "type": "string", "enum": [ "event" ] }, "message_id": { "type": "string", "description": "Underlying transcript message ID that produced this content block, when available" }, "name": { "type": "string", "description": "Event type for intentionally exposed non-core transcript events" }, "data": { "type": "object", "additionalProperties": true, "description": "Minimal structured metadata for the event" } } }, "ArtifactItem": { "oneOf": [ { "$ref": "#/components/schemas/PlanArtifact" }, { "$ref": "#/components/schemas/PullRequestArtifact" }, { "$ref": "#/components/schemas/ScreenshotArtifact" }, { "$ref": "#/components/schemas/FileArtifact" }, { "$ref": "#/components/schemas/ExternalReferenceArtifact" } ], "discriminator": { "propertyName": "artifact_type", "mapping": { "PLAN": "#/components/schemas/PlanArtifact", "PULL_REQUEST": "#/components/schemas/PullRequestArtifact", "SCREENSHOT": "#/components/schemas/ScreenshotArtifact", "FILE": "#/components/schemas/FileArtifact", "EXTERNAL_REFERENCE": "#/components/schemas/ExternalReferenceArtifact" } } }, "ExternalReferenceArtifact": { "type": "object", "required": [ "artifact_type", "created_at", "data" ], "properties": { "artifact_type": { "type": "string", "enum": [ "EXTERNAL_REFERENCE" ], "description": "Type of the artifact" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the artifact was created (RFC3339)" }, "data": { "$ref": "#/components/schemas/ExternalReferenceArtifactData" } } }, "PlanArtifact": { "type": "object", "required": [ "artifact_type", "created_at", "data" ], "properties": { "artifact_type": { "type": "string", "enum": [ "PLAN" ], "description": "Type of the artifact" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the artifact was created (RFC3339)" }, "data": { "$ref": "#/components/schemas/PlanArtifactData" } } }, "PullRequestArtifact": { "type": "object", "required": [ "artifact_type", "created_at", "data" ], "properties": { "artifact_type": { "type": "string", "enum": [ "PULL_REQUEST" ], "description": "Type of the artifact" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the artifact was created (RFC3339)" }, "data": { "$ref": "#/components/schemas/PullRequestArtifactResponseData" } } }, "ScreenshotArtifact": { "type": "object", "required": [ "artifact_type", "created_at", "data" ], "properties": { "artifact_type": { "type": "string", "enum": [ "SCREENSHOT" ], "description": "Type of the artifact" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the artifact was created (RFC3339)" }, "data": { "$ref": "#/components/schemas/ScreenshotArtifactData" } } }, "FileArtifact": { "type": "object", "required": [ "artifact_type", "created_at", "data" ], "properties": { "artifact_type": { "type": "string", "enum": [ "FILE" ], "description": "Type of the artifact" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the artifact was created (RFC3339)" }, "data": { "$ref": "#/components/schemas/FileArtifactData" } } }, "PlanArtifactData": { "type": "object", "required": [ "document_uid" ], "properties": { "artifact_uid": { "type": "string", "description": "Unique identifier for the plan artifact, usable with the artifact retrieval endpoint" }, "document_uid": { "type": "string", "description": "Unique identifier for the plan document" }, "notebook_uid": { "type": "string", "description": "Unique identifier for the associated notebook" }, "url": { "type": "string", "format": "uri", "description": "URL to open the plan in Warp Drive" }, "title": { "type": "string", "description": "Title of the plan" } } }, "PullRequestArtifactData": { "type": "object", "required": [ "url", "branch" ], "properties": { "url": { "type": "string", "format": "uri", "description": "URL of the pull request" }, "branch": { "type": "string", "description": "Branch name for the pull request" } } }, "PullRequestArtifactResponseData": { "allOf": [ { "$ref": "#/components/schemas/PullRequestArtifactData" }, { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "description": "Current state of the pull request as last reported by the code\nhost's webhooks. `unknown` means Warp has no live provider\nrecord for this pull request (for example, the repository's\ncode host integration is not connected to the run's team).\n", "enum": [ "open", "draft", "merged", "closed", "unknown" ] } } } ] }, "ScreenshotArtifactData": { "type": "object", "required": [ "artifact_uid", "mime_type" ], "properties": { "artifact_uid": { "type": "string", "description": "Unique identifier for the screenshot artifact" }, "mime_type": { "type": "string", "description": "MIME type of the screenshot image" }, "description": { "type": "string", "description": "Optional description of the screenshot" } } }, "FileArtifactData": { "type": "object", "required": [ "artifact_uid", "filepath", "filename", "mime_type" ], "properties": { "artifact_uid": { "type": "string", "description": "Unique identifier for the file artifact" }, "filepath": { "type": "string", "description": "Conversation-relative filepath for the uploaded file. Omitted on\nan anonymous read of a public file artifact.\n" }, "filename": { "type": "string", "description": "Last path component of filepath" }, "title": { "type": "string", "description": "Short, badge-visible label for the artifact. For recording artifacts,\nthis is the agent-authored title shown in Warp web and blocklist badges.\nDistinct from description, which is longer and shown in detail views.\n" }, "description": { "type": "string", "description": "Optional description of the file" }, "mime_type": { "type": "string", "description": "MIME type of the uploaded file" }, "size_bytes": { "type": "integer", "format": "int64", "description": "Size of the uploaded file in bytes" }, "thumbnail": { "$ref": "#/components/schemas/FileArtifactThumbnail" } } }, "FileArtifactThumbnail": { "type": "object", "description": "The companion thumbnail image of a video recording.", "required": [ "download_url" ], "properties": { "download_url": { "type": "string", "format": "uri", "description": "Stable URL of the thumbnail image. Requires authentication." } } }, "ScheduleInfo": { "type": "object", "description": "Information about the schedule that triggered this run (only present for scheduled runs)", "required": [ "schedule_id", "schedule_name", "cron_schedule" ], "properties": { "schedule_id": { "type": "string", "description": "Unique identifier for the schedule" }, "schedule_name": { "type": "string", "description": "Name of the schedule at the time the run was created" }, "cron_schedule": { "type": "string", "description": "Cron expression at the time the run was created" } } }, "PageInfo": { "type": "object", "required": [ "has_next_page" ], "properties": { "has_next_page": { "type": "boolean", "description": "Whether there are more results available" }, "next_cursor": { "type": "string", "description": "Opaque cursor for fetching the next page" } } }, "RunStatusMessage": { "type": "object", "description": "Status message for a run. For terminal error states, includes structured\nerror code and retryability info from the platform error catalog.\n", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "Human-readable status message" }, "error_code": { "$ref": "#/components/schemas/PlatformErrorCode" }, "retryable": { "type": "boolean", "description": "Whether the error is transient and the client may retry by submitting\na new run. Only present on terminal error states. When false, retrying\nwithout addressing the underlying cause will not succeed.\n" }, "session_debug_until": { "type": "string", "format": "date-time", "description": "When a failed run's shared session stops being held open for debugging.\nOnly present while that window is open.\n\nThe window is an idle window owned by the agent process: activity in the\nsession pushes this deadline out. The agent republishes it periodically\nrather than on every keystroke, so the value can lag the true deadline by\nup to a throttle interval, and always in the conservative direction.\n" }, "debug_agent_active": { "type": "boolean", "description": "Whether a setup-failure debug turn is actively pinning the idle timer open\nright now. While true, session_debug_until can lag behind the real deadline;\nclients should show an active-debugging state instead of a countdown.\n" } } }, "RequestUsage": { "type": "object", "description": "Resource usage information for the run", "properties": { "inference_cost": { "type": "number", "format": "double", "description": "Credits consumed by LLM inference for the run" }, "compute_cost": { "type": "number", "format": "double", "description": "Credits consumed by compute resources for the run" }, "platform_cost": { "type": "number", "format": "double", "description": "Credits consumed by platform usage for the run" }, "inference_cost_usd": { "type": "number", "format": "double", "description": "What the run's LLM inference was billed at, in US dollars. Runs that\npredate billed-amount tracking fall back to an estimated cost.\n" }, "compute_cost_usd": { "type": "number", "format": "double", "description": "What the run's hosted compute was billed at, in US dollars. Runs that\npredate billed-amount tracking fall back to an estimated cost.\n" }, "platform_cost_usd": { "type": "number", "format": "double", "description": "What the run's platform usage was billed at, in US dollars. Runs that\npredate billed-amount tracking fall back to an estimated cost.\n" }, "total_tokens": { "type": "integer", "format": "int64", "description": "Total LLM token count (summed across every usage category and model) for the run's\nconversation. Omitted when the data is not available.\n" }, "usage_by_category": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ChargedUsageDetail" }, "description": "Full-granularity token and charged-cost breakdown for the run's\nconversation, keyed by usage category (for example,\nprimary_agent or conversation_compaction) and model id. Omitted\nwhen the data is not available.\n" }, "model_token_usage": { "type": "array", "items": { "$ref": "#/components/schemas/ModelTokenUsage" }, "description": "The models that actually served inference for the run, with the\ntokens each consumed. Used to discover what an auto-routing model\nresolves to. If a run is terminated before inference is complete,\noutput a zero-token entry for that model. Omits runs that use\na third-party harness, whose per-model usage is not tracked by Warp.\n" } } }, "ModelTokenUsage": { "type": "object", "description": "Tokens consumed by a single model over a run.\n", "required": [ "model_id", "total_tokens", "usage_type" ], "properties": { "model_id": { "type": "string", "description": "Identifier of the model that served the inference. For `warp` and\n`byok` usage this is a model id drawn from the same set as\n`agent_config.model_id`. For `custom_endpoint` usage this is the\ncaller's own configuration key for the endpoint.\n" }, "total_tokens": { "type": "integer", "format": "int64", "description": "Total tokens this model consumed, across every usage category." }, "usage_type": { "$ref": "#/components/schemas/ModelUsageType" }, "tokens_by_category": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64" }, "description": "total_tokens split by the kind of work the tokens were spent on,\nkeyed by usage category (e.g., primary_agent, tool_summarization, etc).\n" } } }, "ModelUsageType": { "type": "string", "description": "How a model's inference was accessed:\n- warp: through Warp-provided model access\n- byok: through the caller's own provider API key\n- custom_endpoint: through a caller-configured model endpoint\n", "enum": [ "warp", "byok", "custom_endpoint" ] }, "InferenceCostBreakdownInCents": { "type": "object", "description": "Charged cost of LLM inference in US cents, split by token type.\nOmitted when the data is not available.\n", "required": [ "input_cost_in_cents", "input_cache_read_cost_in_cents", "input_cache_write_cost_in_cents", "output_cost_in_cents" ], "properties": { "input_cost_in_cents": { "type": "number", "format": "double", "description": "Cost of non-cached input tokens, in US cents." }, "input_cache_read_cost_in_cents": { "type": "number", "format": "double", "description": "Cost of cache-read input tokens, in US cents." }, "input_cache_write_cost_in_cents": { "type": "number", "format": "double", "description": "Cost of cache-write input tokens, in US cents." }, "output_cost_in_cents": { "type": "number", "format": "double", "description": "Cost of output tokens, in US cents." } } }, "TokenCountBreakdown": { "type": "object", "description": "A per-token-type token count.", "required": [ "input", "output", "input_cache_read", "input_cache_write" ], "properties": { "input": { "type": "integer", "format": "int64", "description": "Count of non-cached input tokens." }, "output": { "type": "integer", "format": "int64", "description": "Count of output tokens." }, "input_cache_read": { "type": "integer", "format": "int64", "description": "Count of cache-read input tokens." }, "input_cache_write": { "type": "integer", "format": "int64", "description": "Count of cache-write input tokens." } } }, "InferenceUsageDetail": { "type": "object", "description": "Full token count and charged-cost detail for inference usage.\nThe counts and cost describe the same usage (e.g. token_count.input\ntokens cost cost_in_cents.input_cost_in_cents in total).\n", "required": [ "token_count", "cost_in_cents", "web_search_count", "web_search_cost_in_cents" ], "properties": { "token_count": { "$ref": "#/components/schemas/TokenCountBreakdown" }, "cost_in_cents": { "$ref": "#/components/schemas/InferenceCostBreakdownInCents" }, "web_search_count": { "type": "integer", "format": "int64", "description": "Number of web searches performed by this model." }, "web_search_cost_in_cents": { "type": "number", "format": "double", "description": "Total cost of those web searches, in US cents." } } }, "ChargedUsageDetail": { "type": "object", "description": "Usage charged for a single usage category, broken down by usage type\n(direct API/BYOK/custom endpoint) and, within each, by model ID.\n", "required": [ "platform_usage_in_cents" ], "properties": { "direct_api_inference_usage": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/InferenceUsageDetail" }, "description": "Inference usage incurred through Warp-provided model access, keyed by model ID." }, "byok_inference_usage": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/InferenceUsageDetail" }, "description": "Inference usage charged using a user's own API key, keyed by model ID." }, "custom_endpoint_inference_usage": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/InferenceUsageDetail" }, "description": "Inference usage charged using a custom endpoint, keyed by the\ncustom model's config key.\n" }, "platform_usage_in_cents": { "type": "number", "format": "double", "description": "Platform usage charged for this category, in US cents." } } }, "RunCreatorInfo": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user", "service_account" ], "description": "Type of the creator principal" }, "uid": { "type": "string", "description": "Unique identifier of the creator" }, "display_name": { "type": "string", "description": "Display name of the creator" }, "email": { "type": "string", "description": "Email address of the creator" }, "photo_url": { "type": "string", "format": "uri", "description": "URL to the creator's photo" } } }, "RunState": { "type": "string", "enum": [ "QUEUED", "PENDING", "CLAIMED", "INPROGRESS", "SUCCEEDED", "FAILED", "BLOCKED", "ERROR", "CANCELLED" ], "description": "Current state of the run:\n- QUEUED: Run is waiting to be picked up\n- PENDING: Run is being prepared\n- CLAIMED: Run has been claimed by a worker\n- INPROGRESS: Run is actively being executed\n- SUCCEEDED: Run completed successfully\n- FAILED: Run failed\n- BLOCKED: Run is blocked (e.g., awaiting user input or approval)\n- ERROR: Run encountered an error\n- CANCELLED: Run was cancelled by user\n" }, "RunSourceType": { "type": "string", "enum": [ "LINEAR", "API", "MCP", "SLACK", "TEAMS", "LOCAL", "SCHEDULED_AGENT", "WEB_APP", "GITHUB_ACTION", "CLOUD_MODE", "CLI", "JIRA", "SELF_IMPROVEMENT", "GITHUB_WEBHOOK", "GITLAB_WEBHOOK", "AZURE_DEVOPS_WEBHOOK", "AUTOFIX", "RUN_SCORER", "ORCHESTRATION", "BENCHMARK_TRIAL", "CREATE_BENCHMARK_TASK", "CUSTOM_WEBHOOK" ], "description": "Source that created the run:\n- LINEAR: Created from Linear integration\n- API: Created via the Warp API\n- MCP: Created through the Factory MCP server's send_task tool\n- SLACK: Created from Slack integration\n- TEAMS: Created from Microsoft Teams integration\n- LOCAL: Created from local CLI/app\n- SCHEDULED_AGENT: Created by a scheduled agent\n- WEB_APP: Created from the Warp web app\n- GITHUB_ACTION: Created from a GitHub action\n- CLOUD_MODE: Created from a Cloud Mode\n- CLI: Created from the CLI\n- JIRA: Created from Jira integration\n- SELF_IMPROVEMENT: Created by Warp's self-improvement pipeline\n- GITHUB_WEBHOOK: Created from a GitHub webhook event\n- GITLAB_WEBHOOK: Created from a GitLab webhook event\n- AZURE_DEVOPS_WEBHOOK: Created from an Azure DevOps webhook event\n- AUTOFIX: Created by Warp's autofix pipeline\n- RUN_SCORER: Created by Warp's run-scoring judge\n- ORCHESTRATION: Created as a child run by the orchestration layer (parent_run_id set)\n- BENCHMARK_TRIAL: Created as a factory benchmark trial\n- CREATE_BENCHMARK_TASK: Created by a Factory foreman authoring a benchmark task from a completed run\n- CUSTOM_WEBHOOK: Created by a factory automation subscribed to a custom webhook source\n" }, "RunExecutionLocation": { "type": "string", "enum": [ "LOCAL", "REMOTE" ], "description": "Where the run executed:\n- LOCAL: Executed in the user's local Warp environment\n- REMOTE: Executed by a remote/cloud worker\n" }, "AmbientAgentConfig": { "type": "object", "description": "Configuration for a cloud agent run", "properties": { "name": { "type": "string", "description": "Human-readable label for grouping, filtering, and traceability.\nAutomatically set to the skill name when running a skill-based agent.\nSet this explicitly to categorize runs by intent (e.g., \"nightly-dependency-check\")\nso you can filter and track them via the name query parameter on GET /agent/runs.\n" }, "model_id": { "type": "string", "description": "LLM model to use (uses team default if not specified)" }, "base_prompt": { "type": "string", "description": "Custom base prompt for the agent" }, "environment_id": { "type": "string", "description": "UID of the environment to run the agent in" }, "secrets": { "type": "array", "items": { "$ref": "#/components/schemas/SecretRef" }, "description": "Optional run-specific managed secret allowlist. Omission and an\nempty array both add no generic secrets. Secret references from\nthe resolved environment and execution principal are still\nunioned into the run's secret scope.\n" }, "runner_id": { "type": "string", "description": "UID of the runner providing the run's compute (platform, instance\nshape, and setup commands). When omitted on a request, the runner is\nresolved at run creation from the agent's default runner, then the\nenvironment's default runner, and the resolved UID is recorded on\nthe run.\n" }, "skill_spec": { "type": "string", "description": "Skill specification identifying the primary agent skill to use,\nin `{owner}/{repo}:{skill_path}` format (e.g.\n`warpdotdev/warp-server:.claude/skills/deploy/SKILL.md`);\nmutually exclusive with `skills` in create/update requests.\nResponses include the first `skills` entry here for backward\ncompatibility; use the list agents endpoint to discover\navailable skills.\n" }, "skills": { "type": "array", "items": { "type": "string" }, "description": "Ordered skill specifications to attach to the run.\nFormat: \"{owner}/{repo}:{skill_path}\"\nExample: \"warpdotdev/warp-server:.claude/skills/deploy/SKILL.md\"\nMutually exclusive with skill_spec in create/update requests.\n" }, "mcp_servers": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/MCPServerConfig" }, "description": "Map of MCP server configurations by name" }, "computer_use_enabled": { "type": "boolean", "description": "Controls whether computer use is enabled for this agent.\nIf not set, defaults to true.\n" }, "computer_use_model_id": { "type": "string", "description": "Model the computer use subagent runs on; if omitted, the subagent\npicks its own model automatically. Only applies to the built-in\nWarp harness — the value is accepted but has no effect under a\nthird-party harness or when computer use is disabled. Requires an\nagent CLI version that supports the --computer-use-model flag.\n" }, "idle_timeout_minutes": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 60, "description": "Number of minutes to keep the agent environment alive after task completion.\nSet to 0 to shut down immediately after task completion.\nIf not set, defaults to 10 minutes.\nMaximum allowed value is min(60, floor(max_instance_runtime_seconds / 60) for your billing tier).\n" }, "worker_host": { "type": "string", "description": "Self-hosted worker ID that should execute this task.\nIf not specified or set to \"warp\", the task runs on Warp-hosted workers.\n" }, "harness": { "$ref": "#/components/schemas/Harness" }, "harness_auth_secrets": { "$ref": "#/components/schemas/HarnessAuthSecrets" }, "session_sharing": { "$ref": "#/components/schemas/SessionSharingConfig" }, "memory_stores": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryStoreRef" }, "description": "Memory stores to attach to this run." }, "inference_providers": { "allOf": [ { "$ref": "#/components/schemas/InferenceProvidersConfig" } ], "description": "Optional inference provider settings for this run. Run-level\nconfig takes precedence over the agent's stored config and\nthe workspace's admin-configured defaults.\n" }, "credential_strategy": { "type": "string", "nullable": true, "enum": [ "CREATOR", "EXECUTOR" ], "description": "Controls which principal's credentials are used when the\nplatform mints tokens (e.g. GitHub or GitLab OAuth tokens) on\nbehalf of this run.\n- EXECUTOR (default when unset): credentials are sourced from\n the run's execution principal — a GitHub App installation\n token for agent principals, a personal OAuth token for user\n principals.\n- CREATOR: credentials are always sourced from the run creator\n regardless of the execution principal, useful when a service\n account executes the run but Git operations should\n authenticate as the triggering human.\n" } } }, "SessionSharingConfig": { "type": "object", "description": "Configures sharing behavior for the run's shared session; when set,\nthe worker emits `--share public:` and the bundled Warp\nclient applies an anyone-with-link ACL to the shared session once it\nhas bootstrapped. The same ACL is mirrored onto the backing\nconversation so link viewers can read it without being on the run's\nteam, subject to the workspace-level anyone-with-link sharing\nsetting.\n", "properties": { "public_access": { "type": "string", "enum": [ "VIEWER", "EDITOR" ], "description": "Grants anyone-with-link access at the specified level to the\nrun's shared session and backing conversation; link viewers\nmust still be authenticated Warp users (anonymous reads are not\nsupported in this release).\n- VIEWER: link viewers can read the session and conversation.\n- EDITOR: link viewers can also interact with the session.\n" } } }, "Harness": { "type": "object", "description": "Specifies which execution harness to use for the agent run.\nDefault (nil/empty) uses Warp's built-in harness.\nWhen stored as a named agent's default (create/update agent identity),\nthis field replaces the deprecated base_harness/base_model pair: a\nharness other than `oz` here requires the agent's base_model to be\nempty, since the two describe mutually exclusive default models.\n", "properties": { "type": { "type": "string", "enum": [ "oz", "claude", "gemini", "codex" ], "description": "The harness type identifier.\n- oz: Warp's built-in harness (default)\n- claude: Claude Code harness\n- gemini: Gemini CLI harness\n- codex: Codex CLI harness\n" }, "model_id": { "type": "string", "description": "Model to use with a third-party harness (e.g. \"claude-haiku-4-5\").\nOnly applies when type is a harness other than `oz`; the\ntop-level config model_id targets the built-in Warp harness\ninstead. When omitted or empty, the harness uses its own default\nmodel.\nFor an individual Warp-managed Factory Claude Code agent, send\nan explicit empty string to use the environment's model. Omitting\nmodel_id when replacing that agent's harness is invalid.\n" }, "reasoning_level": { "type": "string", "description": "Reasoning effort for harnesses that support it (e.g. Codex).\nOnly applies when type is a harness other than `oz`. Ignored by\nharnesses that do not support reasoning levels.\n" } } }, "HarnessAuthSecrets": { "type": "object", "description": "Authentication secrets for third-party harnesses.\nOnly the secret for the harness specified gets injected into the environment.\n", "properties": { "claude_auth_secret_name": { "type": "string", "description": "Name of a managed secret for Claude Code harness authentication.\nThe secret must exist within the caller's personal or team scope.\nOnly applicable when harness type is \"claude\".\n" }, "codex_auth_secret_name": { "type": "string", "description": "Name of a managed secret for Codex harness authentication.\nThe secret must exist within the caller's personal or team scope.\nOnly applicable when harness type is \"codex\".\n" } } }, "MCPServerConfig": { "type": "object", "description": "Configuration for an MCP server. Must have exactly one of: warp_id, command, or url.\n", "properties": { "warp_id": { "type": "string", "description": "Reference to a Warp shared MCP server by UUID, or a well-known\nintegration MCP id (e.g. \"linear\") backed by the team's integration\nconnection.\n" }, "command": { "type": "string", "description": "Stdio transport - command to run" }, "args": { "type": "array", "items": { "type": "string" }, "description": "Stdio transport - command arguments" }, "url": { "type": "string", "format": "uri", "description": "SSE/HTTP transport - server URL" }, "env": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Environment variables for the server" }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "HTTP headers for SSE/HTTP transport" } } }, "Error": { "type": "object", "description": "Error response following RFC 7807 (Problem Details for HTTP APIs),\nusing the `application/problem+json` content type. Includes\nbackward-compatible extension members; additional ones (e.g.,\n`auth_url`, `provider`) may be present depending on the error code.\n", "required": [ "type", "title", "status", "error" ], "properties": { "type": { "type": "string", "format": "uri", "description": "A URI reference that identifies the problem type (RFC 7807).\nDocumentation: `https://docs.warp.dev/factories/api-and-sdk/troubleshooting/errors/{error_code}`\nSee PlatformErrorCode for the list of possible error codes.\n" }, "title": { "type": "string", "description": "A short, human-readable summary of the problem type (RFC 7807)" }, "status": { "type": "integer", "description": "The HTTP status code for this occurrence of the problem (RFC 7807)" }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence of the problem (RFC 7807)" }, "instance": { "type": "string", "description": "The request path that generated this error (RFC 7807)" }, "error": { "type": "string", "description": "Human-readable error message combining title and detail.\nBackward-compatible extension member for older clients.\n" }, "retryable": { "type": "boolean", "description": "Whether the request can be retried. When true, the error is transient\nand the request may be retried. When false, retrying without addressing\nthe underlying cause will not succeed.\n" }, "trace_id": { "type": "string", "description": "OpenTelemetry trace ID for debugging and support requests" }, "provider": { "type": "string", "description": "External provider that requires authorization, such as `linear`." }, "auth_url": { "type": "string", "format": "uri", "description": "URL where the caller can reconnect the external provider." } } }, "ArtifactResponse": { "oneOf": [ { "$ref": "#/components/schemas/PlanArtifactResponse" }, { "$ref": "#/components/schemas/ScreenshotArtifactResponse" }, { "$ref": "#/components/schemas/FileArtifactResponse" } ], "discriminator": { "propertyName": "artifact_type", "mapping": { "PLAN": "#/components/schemas/PlanArtifactResponse", "SCREENSHOT": "#/components/schemas/ScreenshotArtifactResponse", "FILE": "#/components/schemas/FileArtifactResponse" } } }, "PlanArtifactResponse": { "type": "object", "description": "Response for retrieving a plan artifact.", "required": [ "artifact_uid", "artifact_type", "created_at", "data" ], "properties": { "artifact_uid": { "type": "string", "description": "Unique identifier (UUID) for the artifact" }, "artifact_type": { "type": "string", "enum": [ "PLAN" ], "description": "Type of the artifact" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the artifact was created (RFC3339)" }, "data": { "$ref": "#/components/schemas/PlanArtifactResponseData" } } }, "PlanArtifactResponseData": { "type": "object", "description": "Response data for a plan artifact, including current markdown content.", "required": [ "document_uid", "notebook_uid", "content", "content_type" ], "properties": { "document_uid": { "type": "string", "description": "Unique identifier for the plan document" }, "notebook_uid": { "type": "string", "description": "Unique identifier for the associated notebook" }, "url": { "type": "string", "format": "uri", "description": "URL to open the plan in Warp Drive" }, "title": { "type": "string", "description": "Current title of the plan" }, "content": { "type": "string", "description": "Current markdown content of the plan" }, "content_type": { "type": "string", "description": "MIME type of the returned plan content" } } }, "ScreenshotArtifactResponse": { "type": "object", "description": "Response for retrieving a screenshot artifact.", "required": [ "artifact_uid", "artifact_type", "created_at", "data" ], "properties": { "artifact_uid": { "type": "string", "description": "Unique identifier (UUID) for the artifact" }, "artifact_type": { "type": "string", "enum": [ "SCREENSHOT" ], "description": "Type of the artifact" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the artifact was created (RFC3339)" }, "source_links": { "$ref": "#/components/schemas/ArtifactSourceLinksResponse" }, "data": { "$ref": "#/components/schemas/ScreenshotArtifactResponseData" } } }, "ArtifactSourceLinksResponse": { "type": "object", "description": "Links to the originating run and pull requests reported in its tree. Destinations enforce their own access rules.", "properties": { "run_url": { "type": "string", "format": "uri", "description": "Factory run page for the originating root run, when bound to a live Factory task." }, "pull_request_urls": { "type": "array", "items": { "type": "string", "format": "uri" }, "description": "Distinct pull requests reported by runs in the same tree." } } }, "ScreenshotArtifactResponseData": { "type": "object", "description": "Response data for a screenshot artifact, including a signed download URL.", "required": [ "download_url", "expires_at", "content_type" ], "properties": { "download_url": { "type": "string", "format": "uri", "description": "Time-limited signed URL to download the screenshot" }, "expires_at": { "type": "string", "format": "date-time", "description": "Timestamp when the download URL expires (RFC3339)" }, "content_type": { "type": "string", "description": "MIME type of the screenshot (e.g., image/png)" }, "description": { "type": "string", "description": "Optional description of the screenshot" } } }, "FileArtifactResponse": { "type": "object", "description": "Response for retrieving a file artifact.", "required": [ "artifact_uid", "artifact_type", "created_at", "data" ], "properties": { "artifact_uid": { "type": "string", "description": "Unique identifier (UUID) for the artifact" }, "artifact_type": { "type": "string", "enum": [ "FILE" ], "description": "Type of the artifact" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the artifact was created (RFC3339)" }, "source_links": { "$ref": "#/components/schemas/ArtifactSourceLinksResponse" }, "data": { "$ref": "#/components/schemas/FileArtifactResponseData" } } }, "FileArtifactResponseData": { "type": "object", "description": "Response data for a file artifact, including a signed download URL.", "required": [ "download_url", "expires_at", "content_type", "filename" ], "properties": { "download_url": { "type": "string", "format": "uri", "description": "Time-limited signed URL to download the file" }, "expires_at": { "type": "string", "format": "date-time", "description": "Timestamp when the download URL expires (RFC3339)" }, "content_type": { "type": "string", "description": "MIME type of the uploaded file" }, "filepath": { "type": "string", "description": "Conversation-relative filepath for the uploaded file. Omitted for\nanonymous reads of public artifacts.\n" }, "filename": { "type": "string", "description": "Last path component of filepath" }, "title": { "type": "string", "description": "Short, badge-visible label for the artifact. For recording artifacts,\nthis is the agent-authored title shown in Warp web and blocklist badges.\nDistinct from description, which is longer and shown in detail views.\n" }, "description": { "type": "string", "description": "Optional description of the file" }, "size_bytes": { "type": "integer", "format": "int64", "description": "Size of the uploaded file in bytes" } } }, "AttachmentInput": { "type": "object", "description": "A base64-encoded file attachment to include with the prompt", "required": [ "file_name", "mime_type", "data" ], "properties": { "file_name": { "type": "string", "description": "Name of the attached file" }, "mime_type": { "type": "string", "description": "MIME type of the attachment.\nSupported image types: image/jpeg, image/png, image/gif, image/webp\n" }, "data": { "type": "string", "format": "byte", "description": "Base64-encoded attachment data" } } }, "ScheduledAgentItem": { "type": "object", "required": [ "id", "name", "cron_schedule", "enabled", "prompt", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "description": "Unique identifier for the scheduled agent" }, "name": { "type": "string", "description": "Human-readable name for the schedule" }, "cron_schedule": { "type": "string", "description": "Cron expression defining when the agent runs (e.g., \"0 9 * * *\" for daily at 9am UTC)" }, "enabled": { "type": "boolean", "description": "Whether the schedule is currently active" }, "prompt": { "type": "string", "description": "The prompt/instruction for the agent to execute" }, "last_spawn_error": { "type": "string", "nullable": true, "description": "Error message from the last failed spawn attempt, if any" }, "agent_config": { "$ref": "#/components/schemas/AmbientAgentConfig" }, "agent_uid": { "type": "string", "format": "uuid", "description": "UID of the agent that this schedule runs as" }, "metadata": { "allOf": [ { "$ref": "#/components/schemas/RunMetadata" } ], "description": "Custom metadata stamped onto every run spawned by this schedule" }, "environment": { "allOf": [ { "$ref": "#/components/schemas/CloudEnvironmentConfig" } ], "description": "Resolved environment configuration (if agent_config references an environment_id)" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the schedule was created (RFC3339)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the schedule was last updated (RFC3339)" }, "created_by": { "$ref": "#/components/schemas/RunCreatorInfo" }, "updated_by": { "$ref": "#/components/schemas/RunCreatorInfo" }, "history": { "$ref": "#/components/schemas/ScheduledAgentHistoryItem" }, "scope": { "$ref": "#/components/schemas/Scope" } } }, "ScheduledAgentHistoryItem": { "type": "object", "description": "Scheduler-derived history metadata for a scheduled agent", "properties": { "last_ran": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp of the last successful run (RFC3339)" }, "next_run": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp of the next scheduled run (RFC3339)" } } }, "CreateScheduledAgentRequest": { "type": "object", "description": "Request body for creating a new scheduled agent.\nEither prompt or agent_config.skill_spec or agent_config.skills is required.\n", "required": [ "name", "cron_schedule" ], "properties": { "name": { "type": "string", "description": "Human-readable name for the schedule" }, "cron_schedule": { "type": "string", "description": "Cron expression defining when the agent runs (e.g., \"0 9 * * *\" for daily at 9am UTC)" }, "prompt": { "type": "string", "description": "The prompt/instruction for the agent to execute.\nRequired unless agent_config.skill_spec or agent_config.skills is provided.\n" }, "mode": { "$ref": "#/components/schemas/AgentRunMode", "description": "Optional query mode applied to every triggered run. Defaults to\n`normal` when omitted. The server does not infer mode from prompt\nprefixes such as `/plan`.\n" }, "enabled": { "type": "boolean", "description": "Whether the schedule should be active immediately", "default": true }, "agent_uid": { "type": "string", "format": "uuid", "description": "Agent UID to use as the execution principal for this schedule.\nOnly valid for team-owned schedules.\n" }, "agent_config": { "$ref": "#/components/schemas/AmbientAgentConfig" }, "team": { "type": "boolean", "description": "Whether to create a team-owned schedule.\nDefaults to true for users on a single team.\n" }, "metadata": { "allOf": [ { "$ref": "#/components/schemas/RunMetadata" } ], "description": "Custom metadata stamped onto every run spawned by this schedule as the run's\nexplicit metadata layer.\n" } } }, "UpdateScheduledAgentRequest": { "type": "object", "description": "Request body for updating a scheduled agent.\nEither prompt or agent_config.skill_spec or agent_config.skills is required.\n", "required": [ "name", "cron_schedule", "enabled" ], "properties": { "name": { "type": "string", "description": "Human-readable name for the schedule" }, "cron_schedule": { "type": "string", "description": "Cron expression defining when the agent runs" }, "prompt": { "type": "string", "description": "The prompt/instruction for the agent to execute.\nRequired unless agent_config.skill_spec or agent_config.skills is provided.\n" }, "mode": { "$ref": "#/components/schemas/AgentRunMode", "description": "Optional query mode applied to every triggered run. Defaults to\n`normal` when omitted. The server does not infer mode from prompt\nprefixes such as `/plan`.\n" }, "enabled": { "type": "boolean", "description": "Whether the schedule should be active" }, "agent_uid": { "type": "string", "format": "uuid", "description": "Agent UID to use as the execution principal for this schedule.\nOnly valid for team-owned schedules.\n" }, "agent_config": { "$ref": "#/components/schemas/AmbientAgentConfig" }, "metadata": { "allOf": [ { "$ref": "#/components/schemas/RunMetadata" } ], "description": "Custom metadata stamped onto every run spawned by this schedule.\nUpdates follow full-replacement PUT semantics: omitting this field\nclears the schedule's metadata. Changes apply only to future runs.\n" } } }, "ListScheduledAgentsResponse": { "type": "object", "required": [ "schedules" ], "properties": { "schedules": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduledAgentItem" }, "description": "List of scheduled agents" } } }, "DeleteScheduledAgentResponse": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean", "description": "Whether the deletion was successful" } } }, "CloudEnvironmentConfig": { "type": "object", "description": "Configuration for a cloud environment used by scheduled agents", "properties": { "name": { "type": "string", "description": "Human-readable name for the environment" }, "description": { "type": "string", "nullable": true, "description": "Optional description of the environment" }, "docker_image": { "type": "string", "description": "Docker image to use (e.g., \"ubuntu:latest\" or \"registry/repo:tag\")" }, "github_repos": { "type": "array", "items": { "$ref": "#/components/schemas/GitHubRepo" }, "description": "List of GitHub repositories to clone into the environment" }, "setup_commands": { "type": "array", "items": { "type": "string" }, "description": "Shell commands to run during environment setup" }, "providers": { "$ref": "#/components/schemas/ProvidersConfig" }, "secrets": { "type": "array", "items": { "$ref": "#/components/schemas/SecretRef" }, "description": "Managed secret references contributed by this environment.\nOmission and an empty array both contribute no secrets. These\nreferences are unioned with references from the run config and\nexecution principal.\n" }, "failure_session_retention_minutes": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 60, "description": "When set (1–60 minutes), a failed run using this environment\nkeeps its session open for this many minutes so it can be\ninspected; null or absent means immediate teardown (disabled by\ndefault). This is an idle window held open by the agent process:\nactivity in the session pushes the deadline out (so an active\nsession is not torn down mid-debug), and it ends early if the\nrun's sandbox reaches its own deadline first. Applies only to\nfuture failures of runs using this environment; opting in keeps\ninjected environment data (including secrets) alive and incurs\ncompute usage for as long as the session is held open.\n" } } }, "ProvidersConfig": { "type": "object", "description": "Optional cloud provider configurations for automatic auth", "properties": { "gcp": { "$ref": "#/components/schemas/GcpProviderConfig" }, "aws": { "$ref": "#/components/schemas/AwsProviderConfig" } } }, "InferenceProvidersConfig": { "type": "object", "description": "Inference provider settings used for LLM calls.", "properties": { "aws": { "$ref": "#/components/schemas/AwsInferenceProviderConfig" } } }, "GcpProviderConfig": { "type": "object", "description": "GCP Workload Identity Federation settings", "required": [ "project_number", "workload_identity_federation_pool_id", "workload_identity_federation_provider_id" ], "externalDocs": { "description": "Google documentation on Workload Identity Federation", "url": "https://docs.cloud.google.com/iam/docs/workload-identity-federation" }, "properties": { "project_number": { "type": "string", "description": "GCP project number" }, "workload_identity_federation_pool_id": { "type": "string", "description": "Workload Identity Federation pool ID" }, "workload_identity_federation_provider_id": { "type": "string", "description": "Workload Identity Federation provider ID" }, "service_account_email": { "type": "string", "description": "Optional GCP service account email to impersonate" } } }, "AwsProviderConfig": { "type": "object", "description": "AWS IAM role assumption settings", "externalDocs": { "description": "AWS documentation on IAM OIDC federation", "url": "https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html" }, "required": [ "role_arn" ], "properties": { "role_arn": { "type": "string", "description": "AWS IAM role ARN to assume" } } }, "AwsInferenceProviderConfig": { "type": "object", "description": "Configures AWS Bedrock as the LLM inference provider for this\nagent or run.\n", "externalDocs": { "description": "AWS documentation on IAM OIDC federation", "url": "https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html" }, "properties": { "disabled": { "type": "boolean", "description": "If true, opt out of Bedrock at this layer." }, "role_arn": { "type": "string", "description": "IAM role ARN to assume when calling Bedrock." }, "region": { "type": "string", "description": "AWS region used for STS when assuming the Bedrock inference role." } } }, "GitHubRepo": { "type": "object", "required": [ "owner", "repo" ], "properties": { "owner": { "type": "string", "description": "GitHub repository owner (user or organization)" }, "repo": { "type": "string", "description": "GitHub repository name" } } }, "ListAgentsResponse": { "type": "object", "required": [ "agents" ], "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/AgentListItem" }, "description": "List of available agents" } } }, "ListConnectedSelfHostedWorkersResponse": { "type": "object", "required": [ "workers" ], "properties": { "workers": { "type": "array", "items": { "$ref": "#/components/schemas/ConnectedSelfHostedWorker" }, "description": "Connected self-hosted workers for the authenticated principal's team" } } }, "ConnectedSelfHostedWorker": { "type": "object", "required": [ "worker_host", "connection_count", "connected_at", "last_seen_at" ], "properties": { "worker_host": { "type": "string", "description": "Logical host identifier provided by the self-hosted worker" }, "connection_count": { "type": "integer", "description": "Number of active websocket connections currently observed for this worker host" }, "connected_at": { "type": "string", "format": "date-time", "description": "Earliest connection timestamp across active connections for this worker host" }, "last_seen_at": { "type": "string", "format": "date-time", "description": "Most recent heartbeat timestamp across active connections for this worker host" } } }, "AgentListItem": { "type": "object", "required": [ "name", "variants" ], "properties": { "name": { "type": "string", "description": "Human-readable name of the agent" }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/AgentListVariant" }, "description": "Available variants of this agent" } } }, "AgentListVariant": { "type": "object", "required": [ "id", "description", "base_prompt", "source", "environments" ], "properties": { "id": { "type": "string", "description": "Stable identifier for this skill variant.\nFormat: \"{owner}/{repo}:{skill_path}\"\nExample: \"warpdotdev/warp-server:.claude/skills/deploy/SKILL.md\"\n" }, "description": { "type": "string", "description": "Description of the agent variant" }, "base_prompt": { "type": "string", "description": "Base prompt/instructions for the agent" }, "source": { "$ref": "#/components/schemas/AgentListSource" }, "environments": { "type": "array", "items": { "$ref": "#/components/schemas/AgentListEnvironment" }, "description": "Environments where this agent variant is available" }, "last_run_timestamp": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp of the last time this skill was run (RFC3339)" }, "error": { "type": "string", "description": "Non-empty when the skill's SKILL.md file exists but is malformed.\nContains a description of the parse failure. Only present when\ninclude_malformed_skills=true is passed to the list agents endpoint.\n" } } }, "AgentListSource": { "type": "object", "required": [ "owner", "name", "skill_path" ], "properties": { "owner": { "type": "string", "description": "GitHub repository owner" }, "name": { "type": "string", "description": "GitHub repository name" }, "skill_path": { "type": "string", "description": "Path to the skill definition file within the repository" }, "worker_host": { "type": "string", "description": "Self-hosted worker host that reported this skill.\nPresent only for skills discovered from self-hosted workers\n(as opposed to skills from GitHub repos linked to environments).\n" } } }, "AgentListEnvironment": { "type": "object", "required": [ "uid", "name" ], "properties": { "uid": { "type": "string", "description": "Unique identifier for the environment" }, "name": { "type": "string", "description": "Human-readable name of the environment" } } }, "Scope": { "type": "object", "description": "Ownership scope for a resource (team or personal)", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "User", "Team" ], "description": "Type of ownership (\"User\" for personal, \"Team\" for team-owned)" }, "uid": { "type": "string", "description": "UID of the owning user or team" } } }, "PlatformErrorCode": { "type": "string", "description": "Machine-readable error code identifying the problem type.\nUsed in the `type` URI of Error responses and in the `error_code`\nfield of RunStatusMessage.\n\nUser errors (run transitions to FAILED):\n- `insufficient_credits` — Team has no remaining add-on credits\n- `feature_not_available` — Required feature not enabled for user's plan\n- `external_authentication_required` — User hasn't authorized a required external service\n- `not_authorized` — Principal lacks permission for the requested operation\n- `invalid_request` — Request is malformed or contains invalid parameters\n- `resource_not_found` — Referenced resource does not exist\n- `budget_exceeded` — Spending budget limit has been reached\n- `integration_disabled` — Integration is disabled and must be enabled\n- `integration_not_configured` — Integration setup is incomplete\n- `operation_not_supported` — Requested operation not supported for this resource/state\n- `environment_setup_failed` — Client-side environment setup failed\n- `content_policy_violation` — Prompt or setup commands violated content policy\n- `conflict` — Request conflicts with the current state of the resource\n\nWarp errors (run transitions to ERROR):\n- `authentication_required` — Request lacks valid authentication credentials\n- `resource_unavailable` — Transient infrastructure issue (retryable)\n- `agent_stream_network_error` — MAA response stream terminally failed because of a transport or EOF error\n- `agent_stream_failure` — MAA server explicitly reported a terminal response stream failure\n- `internal_error` — Unexpected server-side error (retryable)\n", "enum": [ "insufficient_credits", "feature_not_available", "external_authentication_required", "not_authorized", "invalid_request", "resource_not_found", "budget_exceeded", "integration_disabled", "integration_not_configured", "operation_not_supported", "environment_setup_failed", "content_policy_violation", "conflict", "authentication_required", "resource_unavailable", "agent_stream_network_error", "agent_stream_failure", "internal_error" ] }, "PresignedDownloadResponse": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "Temporary signed storage URL. Fetch without Warp API headers or credentials." } } }, "RunFollowupRequest": { "type": "object", "description": "Request body for submitting a follow-up message to an existing run.", "properties": { "message": { "type": "string", "description": "The follow-up message to send to the run. May be empty when\n`attachments` is non-empty.\n" }, "mode": { "$ref": "#/components/schemas/AgentRunMode", "description": "Optional query mode for the follow-up. Defaults to `normal` when\nomitted. The server does not infer mode from prompt prefixes such\nas `/plan`. The mode only takes effect when the follow-up is\nqueued ahead of the run starting or starts a new execution; a\nfollow-up injected into a live session runs in the session's\ncurrent mode.\n" }, "attachments": { "type": "array", "maxItems": 25, "items": { "$ref": "#/components/schemas/RunFollowupAttachment" }, "description": "Files to deliver with the message, at most 25. Each entry must\nname an attachment previously prepared for this run through\n`POST /agent/runs/{runId}/attachments/prepare` and uploaded to\nits upload target; an unknown `attachment_id` is rejected with\n422. Files are only materialized for the agent on the Oz\nharness; other harnesses receive a notice naming the files.\n" } } }, "RunFollowupAttachment": { "type": "object", "description": "A prepared attachment to deliver with a follow-up message.", "required": [ "attachment_id" ], "properties": { "attachment_id": { "type": "string", "description": "The `attachment_id` (a UUID) returned by the attachment prepare\nendpoint for this run.\n" }, "file_name": { "type": "string", "description": "Optional display name shown to the agent in place of the name\nrecorded when the attachment was prepared. The stored object is\nunaffected.\n" } } }, "RunFollowupOutcome": { "type": "string", "description": "How an accepted follow-up was routed.\n - live_session: the message was handed to the running session. This means\n the session-sharing service accepted it, not that the agent has started\n on it; observe the session's event stream for the new request.\n - queued_prompt: the run had not started yet, so the message was appended\n to its initial prompt.\n - handoff_execution: the previous execution had ended, so a new execution\n of the same run was created to continue the conversation.\n - queue_pending: the message is durably queued and will be delivered once\n the run can accept it.\n", "enum": [ "live_session", "queued_prompt", "handoff_execution", "queue_pending" ] }, "RunFollowupResponse": { "type": "object", "description": "Acknowledgement of an accepted follow-up.", "required": [ "followup_id", "outcome" ], "properties": { "followup_id": { "type": "string", "nullable": true, "description": "Identifier of the durable follow-up record, or null when the\noutcome did not create one (`queued_prompt`).\n" }, "outcome": { "$ref": "#/components/schemas/RunFollowupOutcome" } } }, "ConversationFollowupResponse": { "type": "object", "description": "Acknowledgement of a follow-up accepted through a conversation-keyed\nroute: the run-keyed acknowledgement plus the run it was delivered to.\n", "required": [ "followup_id", "outcome", "run_id" ], "properties": { "followup_id": { "type": "string", "nullable": true, "description": "Identifier of the durable follow-up record, or null when the\noutcome did not create one (`queued_prompt`).\n" }, "outcome": { "$ref": "#/components/schemas/RunFollowupOutcome" }, "run_id": { "type": "string", "description": "The run the conversation resolved to." } } }, "ConversationInterruptResponse": { "type": "object", "description": "Acknowledgement of an interrupt accepted through a conversation-keyed route.", "required": [ "run_id" ], "properties": { "run_id": { "type": "string", "description": "The run whose turn is being interrupted." } } }, "HandoffSnapshotAttachmentInfo": { "type": "object", "description": "A handoff snapshot attachment exposed for download.", "required": [ "attachment_id", "filename", "download_url" ], "properties": { "attachment_id": { "type": "string", "description": "Identifier for the snapshot attachment within the run." }, "filename": { "type": "string", "description": "Original filename of the snapshot attachment." }, "download_url": { "type": "string", "format": "uri", "description": "Time-limited signed URL to download the snapshot attachment." }, "mime_type": { "type": "string", "description": "MIME type of the snapshot attachment, if known." } } }, "ListHandoffSnapshotAttachmentsResponse": { "type": "object", "description": "Response body for listing handoff snapshot attachments.", "required": [ "attachments" ], "properties": { "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/HandoffSnapshotAttachmentInfo" }, "description": "Handoff snapshot attachments exposed by the latest ended execution.\nEmpty when no ended execution exists or no files were uploaded.\n" } } }, "ListModelsResponse": { "type": "object", "required": [ "default_model_id", "models" ], "properties": { "default_model_id": { "type": "string", "description": "The ID of the default model for agent runs" }, "models": { "type": "array", "items": { "$ref": "#/components/schemas/ModelInfo" }, "description": "List of available models" } } }, "ModelInfo": { "type": "object", "required": [ "id", "display_name", "provider", "vision_supported" ], "properties": { "id": { "type": "string", "description": "Unique identifier for the model (e.g. \"claude-4-6-opus-high\" or \"gpt-5-4-high\")" }, "display_name": { "type": "string", "description": "Human-readable name of the model" }, "provider": { "type": "string", "enum": [ "OPENAI", "ANTHROPIC", "GOOGLE", "UNKNOWN" ], "description": "The LLM provider" }, "vision_supported": { "type": "boolean", "description": "Whether the model supports vision/image inputs" }, "description": { "type": "string", "description": "Optional extra descriptor for the model" }, "reasoning_level": { "type": "string", "description": "Reasoning level descriptor, if any (e.g. \"low\", \"medium\", \"high\")" }, "disable_reason": { "type": "string", "enum": [ "PROVIDER_OUTAGE", "OUT_OF_REQUESTS", "ADMIN_DISABLED", "REQUIRES_UPGRADE" ], "description": "If set, the model is currently unavailable for the given reason" } } }, "ExternalReferenceArtifactData": { "type": "object", "description": "Data for a generic external reference artifact.", "required": [ "reference_type", "url" ], "properties": { "reference_type": { "type": "string", "maxLength": 256, "description": "Free-form category identifier for this reference (e.g. \"linear_issue\",\n\"spec_link\", \"jira_ticket\"). Used for filtering and display.\n" }, "url": { "type": "string", "maxLength": 2048, "description": "Canonical URL for the reference. Used as the key for reverse lookups\n(\"which run produced this URL?\").\n" }, "title": { "type": "string", "description": "Optional human-readable label for the reference." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Optional category-specific extra fields." } } }, "RunByExternalReferenceResponse": { "type": "object", "description": "Response for a run reverse-lookup by external reference URL.", "required": [ "run_id" ], "properties": { "run_id": { "type": "string", "description": "The ID of the run that produced the external reference." } } }, "AgentSkill": { "type": "object", "description": "Information about the agent skill used for the run.\nEither full_path or bundled_skill_id will be set, but not both.\n", "properties": { "name": { "type": "string", "description": "Human-readable name of the skill" }, "description": { "type": "string", "description": "Description of the skill" }, "full_path": { "type": "string", "description": "Path to the SKILL.md file (for file-based skills)" }, "bundled_skill_id": { "type": "string", "description": "Unique identifier for bundled skills" } } }, "ListEnvironmentsResponse": { "type": "object", "required": [ "environments" ], "properties": { "environments": { "type": "array", "items": { "$ref": "#/components/schemas/CloudEnvironment" }, "description": "List of accessible cloud environments" } } }, "CloudEnvironment": { "type": "object", "description": "A cloud environment for running agents", "required": [ "uid", "config", "last_updated", "setup_failed" ], "properties": { "uid": { "type": "string", "description": "Unique identifier for the environment" }, "config": { "$ref": "#/components/schemas/CloudEnvironmentConfig" }, "last_updated": { "type": "string", "format": "date-time", "description": "Timestamp when the environment was last updated (RFC3339)" }, "last_task_run_timestamp": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp of the most recent task run in this environment (RFC3339)" }, "last_task_created": { "$ref": "#/components/schemas/EnvironmentLastTask" }, "setup_failed": { "type": "boolean", "description": "True when the most recent task failed during setup before it started running" }, "scope": { "$ref": "#/components/schemas/Scope" }, "creator": { "$ref": "#/components/schemas/RunCreatorInfo" }, "last_editor": { "$ref": "#/components/schemas/RunCreatorInfo" } } }, "SecretRef": { "type": "object", "description": "Reference to a managed secret by name.\n", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Name of the managed secret." } } }, "MemoryStoreRef": { "type": "object", "description": "Reference to a memory store to attach to an agent.", "required": [ "uid", "access", "instructions" ], "properties": { "uid": { "type": "string", "description": "UID of the memory store." }, "access": { "type": "string", "enum": [ "read_write", "read_only" ], "description": "Access level for the store." }, "instructions": { "type": "string", "description": "Instructions for how the agent should use this memory store. Must not be empty." } } }, "MemoryStoreAttachmentResponse": { "type": "object", "description": "Memory store attached to an agent.", "required": [ "uid", "access", "instructions", "owner_type", "owner_uid" ], "properties": { "uid": { "type": "string", "description": "UID of the memory store." }, "access": { "type": "string", "enum": [ "read_write", "read_only" ], "description": "Access level for the store." }, "instructions": { "type": "string", "description": "Instructions for how the agent should use this memory store." }, "owner_type": { "type": "string", "description": "Public owner type.", "enum": [ "user", "service_account", "team" ] }, "owner_uid": { "type": "string", "description": "Public UID of the user, service account, or team that owns the memory store." }, "description": { "type": "string", "description": "Optional description for the memory store." } } }, "AgentAutoMemoryCreateConfig": { "type": "object", "description": "Auto-memory settings for creating an agent.", "properties": { "enabled": { "type": "boolean", "description": "Whether to create and attach a default service-account-owned memory store for this agent.\nDefaults to true when omitted.\n" } } }, "AgentMemoryCreateConfig": { "type": "object", "description": "Memory settings for creating an agent.", "properties": { "auto_memory": { "allOf": [ { "$ref": "#/components/schemas/AgentAutoMemoryCreateConfig" } ], "description": "Agent-owned memory settings. Defaults to enabled when omitted." }, "attached_stores": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryStoreRef" }, "description": "Existing team memory stores to attach to the agent.\nDuplicate UIDs within a single request are rejected.\n" } } }, "AgentMemoryUpdateConfig": { "type": "object", "description": "Memory settings for updating an agent.", "properties": { "attached_stores": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/MemoryStoreRef" }, "description": "Replacement list of attached team memory stores. Omit to leave unchanged,\npass an empty array to clear, or pass a non-empty array to replace.\n" } } }, "AgentAutoMemoryResponse": { "type": "object", "description": "Auto-memory state for an agent.", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean", "description": "Whether this agent has an agent-owned memory store." }, "store": { "$ref": "#/components/schemas/MemoryStoreAttachmentResponse" } } }, "AgentMemoryResponse": { "type": "object", "description": "Memory settings for an agent.", "required": [ "auto_memory", "attached_stores" ], "properties": { "auto_memory": { "$ref": "#/components/schemas/AgentAutoMemoryResponse" }, "attached_stores": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryStoreRef" }, "description": "Team memory stores attached to the agent." } } }, "AgentCredentialStrategy": { "type": "string", "description": "Default credential strategy for runs executed by a named agent; an\nagent may leave this unset (see AgentResponse.credential_strategy\nfor the full resolution order).\n- EXECUTOR: runs authenticate with the named agent's own credentials\n (e.g. a GitHub App installation token for the agent's team).\n- CREATOR: runs authenticate with the credentials of the principal\n that created the run.\n", "enum": [ "CREATOR", "EXECUTOR" ] }, "ScorerClassification": { "type": "object", "required": [ "value", "score" ], "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 1048576, "description": "Classification value returned by the scorer" }, "description": { "type": "string", "nullable": true, "maxLength": 1048576, "description": "Optional free-text meaning of this classification, surfaced to the\njudge alongside the value. Omit or leave blank for a score-only\nlabel.\n" }, "score": { "type": "number", "format": "double", "minimum": 0, "maximum": 1, "description": "Score this classification carries, from 0 to 1. A run passes when\nits scored label's score is greater than or equal to the scorer's\nthreshold. A score of exactly 0 is valid, so this is not enforced\nwith a \"required\" binding (which would reject the zero value);\nhandlers validate its range explicitly instead.\n" } } }, "ScorerAgentConfig": { "type": "object", "description": "Scorer-specific execution overrides for its hidden judge agent. An\nomitted or null field inherits the corresponding Factory agent default.\nA non-empty value replaces that default. Empty secrets and mcp_servers\ncollections explicitly clear the optional Factory defaults.\n", "properties": { "default_runner_uid": { "type": "string", "nullable": true, "description": "Runner used by scorer judge runs. Omit or set null to inherit the\nFactory agent default.\n" }, "secrets": { "type": "array", "nullable": true, "description": "Managed secrets attached to scorer judge runs. Omit or set null to\ninherit the Factory agent defaults; an empty array attaches none.\n", "items": { "$ref": "#/components/schemas/SecretRef" } }, "mcp_servers": { "type": "object", "nullable": true, "description": "MCP servers attached to scorer judge runs. Omit or set null to\ninherit the Factory agent defaults; an empty object attaches none.\n", "additionalProperties": { "$ref": "#/components/schemas/MCPServerConfig" } } } }, "CreateScorerRequest": { "type": "object", "description": "Scorer definition. Text fields are trimmed of surrounding whitespace\nbefore validation; required text fields must not be blank after trimming,\nand no text field may exceed 1 MiB (1048576 bytes).\n", "required": [ "name", "scoring_prompt", "allowed_classifications", "threshold", "scope_mode", "model_id" ], "properties": { "factory_uid": { "type": "string", "minLength": 1, "description": "Optional compatibility scope; must match the factory_uid in the path.", "deprecated": true }, "name": { "type": "string", "minLength": 1, "maxLength": 1048576, "description": "Display name for the scorer" }, "description": { "type": "string", "nullable": true, "maxLength": 1048576, "description": "Optional description of the scorer" }, "scoring_prompt": { "type": "string", "minLength": 1, "maxLength": 1048576, "description": "Instructions used to score matching runs" }, "allowed_classifications": { "type": "array", "minItems": 1, "maxItems": 20, "description": "Values the scorer may return; classification values must be unique", "items": { "$ref": "#/components/schemas/ScorerClassification" } }, "threshold": { "type": "number", "format": "double", "minimum": 0, "maximum": 1, "description": "Score a run's classified label must meet or exceed to pass, from 0\nto 1.\n" }, "scope_mode": { "type": "string", "enum": [ "all_agents", "selected_agents" ], "description": "Whether the scorer applies to every factory agent or selected agents" }, "agent_uids": { "type": "array", "description": "Legacy shorthand for selected agents with include_descendants=false.\nRequired and non-empty for selected_agents when agents is omitted;\nmust be empty for all_agents and cannot be combined with agents.\n", "items": { "type": "string" } }, "agents": { "type": "array", "description": "Selected agents and their evidence policy. Required and non-empty\nfor selected_agents when agent_uids is omitted; must be empty for\nall_agents and cannot be combined with agent_uids.\n", "items": { "$ref": "#/components/schemas/ScorerAgentInput" } }, "sampling_rate": { "type": "number", "format": "double", "nullable": true, "minimum": 0, "maximum": 100, "description": "Percentage of the scorer's eligible runs to score, from 0 to\n100; omit to score every eligible run, and 0 stops automatic\nscoring (manual dispatch still works). A value with more than\ntwo decimal places is rounded to two rather than rejected, and\nthe rounded value is what is stored. Sampling applies to\nperiodic scoring only, and runs are chosen deterministically per\n(scorer, run), so lowering the rate reduces how many runs are\nscored rather than how often.\n" }, "model_id": { "type": "string", "minLength": 1, "maxLength": 255, "description": "LLM model dispatched judge runs use to evaluate this scorer's\nrubric.\n" }, "self_improvement_enabled": { "type": "boolean", "description": "Optionally enable self-improvement for the newly created scorer\nin the same transactional request. Defaults to false; the response\nincludes the resulting state.\n" }, "agent_config": { "$ref": "#/components/schemas/ScorerAgentConfig" } } }, "UpdateScorerRequest": { "type": "object", "description": "Partial scorer definition update. Every field is optional, but at least\none must be present. Text fields are trimmed of surrounding whitespace\nbefore validation; a provided required text field must not be blank after\ntrimming, and no text field may exceed 1 MiB (1048576 bytes).\n", "properties": { "self_improvement_enabled": { "type": "boolean", "description": "Enable or disable self-improvement atomically with definition edits.\nOmission leaves the state unchanged. Null is invalid. Enabling\nrequires a classification below the merged pass threshold.\n" }, "name": { "type": "string", "minLength": 1, "maxLength": 1048576, "description": "New display name for the scorer" }, "description": { "type": "string", "maxLength": 1048576, "description": "New description; an empty string clears it" }, "scoring_prompt": { "type": "string", "minLength": 1, "maxLength": 1048576, "description": "New instructions used to score matching runs" }, "allowed_classifications": { "type": "array", "minItems": 1, "maxItems": 20, "description": "Replacement set of values the scorer may return; classification\nvalues must be unique. Removing a classification the scorer's\nself-improvement config still targets is rejected.\n", "items": { "$ref": "#/components/schemas/ScorerClassification" } }, "threshold": { "type": "number", "format": "double", "minimum": 0, "maximum": 1, "description": "New score a run's classified label must meet or exceed to pass,\nfrom 0 to 1.\n" }, "sampling_rate": { "type": "number", "format": "double", "minimum": 0, "maximum": 100, "description": "New percentage of eligible runs this scorer should score, rounded\nto two decimal places. 0 stops automatic scoring; manual dispatch\nstill works.\n" }, "scope_mode": { "type": "string", "enum": [ "all_agents", "selected_agents" ], "description": "New scope mode. Defaults to the scorer's current mode when only\nagent_uids or agents is supplied.\n" }, "agent_uids": { "type": "array", "description": "Complete replacement membership for the scorer's scope. Required and\nnon-empty when the resulting scope_mode is selected_agents; must be\nempty for all_agents. Legacy shorthand for agents whose\ninclude_descendants value is false; cannot be combined with agents.\n", "items": { "type": "string" } }, "agents": { "type": "array", "description": "Complete replacement selected-agent configuration. Required and\nnon-empty when the resulting scope_mode is selected_agents and\nagent_uids is omitted; must be empty for all_agents and cannot be\ncombined with agent_uids.\n", "items": { "$ref": "#/components/schemas/ScorerAgentInput" } }, "model_id": { "type": "string", "minLength": 1, "maxLength": 255, "description": "New LLM model dispatched judge runs use to evaluate this scorer's\nrubric. Must not be blank when provided.\n" }, "agent_config": { "type": "object", "nullable": true, "anyOf": [ { "$ref": "#/components/schemas/ScorerAgentConfig" }, { "type": "object", "nullable": true, "enum": [ null ] } ], "description": "Partial execution override update. A null object resets every\noverride to inherit the Factory agent defaults. Otherwise, omitted\nnested fields stay unchanged, a null nested field resets that\noverride to inheritance, and empty secrets and mcp_servers\ncollections explicitly attach none.\n" } } }, "ScorerUID": { "type": "string", "format": "uuid", "description": "Stable scorer UUID; new scorers use UUIDv4. Nil UUIDs are invalid." }, "ScorerKind": { "type": "string", "description": "Whether the scorer is user-defined or a platform-owned managed scorer.\nRead-only on responses; create input does not accept scorer_kind.\n", "enum": [ "user", "benchmark_task_correctness" ] }, "ScorerResponse": { "type": "object", "required": [ "scorer_uid", "id", "factory_uid", "name", "description", "scoring_prompt", "allowed_classifications", "threshold", "self_improvement_enabled", "scorer_kind", "scope_mode", "agent_uids", "agents", "sampling_rate", "model_id", "agent_config", "created_at", "updated_at" ], "properties": { "scorer_uid": { "$ref": "#/components/schemas/ScorerUID" }, "self_improvement_enabled": { "type": "boolean", "description": "Whether self-improvement is enabled for this scorer" }, "id": { "type": "integer", "description": "Scorer identifier" }, "factory_uid": { "type": "string", "description": "UID of the factory that owns the scorer" }, "name": { "type": "string", "description": "Display name for the scorer" }, "description": { "type": "string", "description": "Description of the scorer" }, "scoring_prompt": { "type": "string", "description": "Instructions used to score matching runs" }, "allowed_classifications": { "type": "array", "items": { "$ref": "#/components/schemas/ScorerClassification" } }, "threshold": { "type": "number", "format": "double", "description": "Score a run's classified label must meet or exceed to pass, from 0 to 1" }, "scorer_kind": { "$ref": "#/components/schemas/ScorerKind" }, "scope_mode": { "type": "string", "enum": [ "all_agents", "selected_agents" ], "description": "Whether the scorer applies to every factory agent or selected agents" }, "agent_uids": { "type": "array", "description": "Agents attached to a selected_agents scorer; empty for all_agents", "items": { "type": "string" } }, "agents": { "type": "array", "description": "Selected agents and whether each evaluation includes its run descendants", "items": { "$ref": "#/components/schemas/ScorerAgentInput" } }, "sampling_rate": { "type": "number", "format": "double", "description": "Percentage of the scorer's eligible runs that periodic scoring scores,\nto two decimal places. 0 stops automatic scoring.\n" }, "model_id": { "type": "string", "description": "LLM model dispatched judge runs use to evaluate this scorer's\nrubric.\n" }, "agent_config": { "$ref": "#/components/schemas/ScorerAgentConfig" }, "created_at": { "type": "string", "format": "date-time", "description": "When the scorer was created" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the scorer was updated" } } }, "ScorerScopeAgent": { "type": "object", "required": [ "uid", "name", "include_descendants" ], "properties": { "uid": { "type": "string", "description": "Unique identifier of the agent" }, "name": { "type": "string", "description": "Display name of the agent" }, "include_descendants": { "type": "boolean", "description": "Whether scoring this agent's run includes its descendant subtree" } } }, "ScorerAgentInput": { "type": "object", "required": [ "uid" ], "properties": { "uid": { "type": "string", "description": "Unique identifier of the selected agent" }, "include_descendants": { "type": "boolean", "default": false, "description": "Whether scoring this agent's run includes its descendant subtree" } } }, "ScorerListItem": { "type": "object", "required": [ "scorer_uid", "id", "factory_uid", "name", "description", "scoring_prompt", "allowed_classifications", "threshold", "scope_mode", "agents", "scorer_kind", "sampling_rate", "created_at", "updated_at", "result_count", "model_id", "agent_config", "self_improvement_enabled" ], "properties": { "scorer_uid": { "$ref": "#/components/schemas/ScorerUID" }, "id": { "type": "integer", "description": "Scorer identifier" }, "factory_uid": { "type": "string", "description": "Public UID of the factory that owns the scorer" }, "name": { "type": "string", "description": "Display name for the scorer" }, "description": { "type": "string", "description": "Description of the scorer" }, "scoring_prompt": { "type": "string", "description": "Instructions used to score the agent's runs" }, "allowed_classifications": { "type": "array", "items": { "$ref": "#/components/schemas/ScorerClassification" } }, "threshold": { "type": "number", "format": "double", "description": "Score a run's classified label must meet or exceed to pass, from 0 to 1" }, "scope_mode": { "type": "string", "enum": [ "all_agents", "selected_agents" ], "description": "all_agents (every agent in the scorer's factory) or selected_agents" }, "agents": { "type": "array", "items": { "$ref": "#/components/schemas/ScorerScopeAgent" }, "description": "Named agents in scope; empty when the scorer covers all factory agents" }, "scorer_kind": { "$ref": "#/components/schemas/ScorerKind" }, "sampling_rate": { "type": "number", "format": "double", "description": "Percentage of the scorer's eligible runs that periodic scoring scores,\nto two decimal places. 0 stops automatic scoring.\n" }, "agent_config": { "$ref": "#/components/schemas/ScorerAgentConfig" }, "created_at": { "type": "string", "format": "date-time", "description": "When the scorer was created" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the scorer was last updated" }, "result_count": { "type": "integer", "description": "Number of live scores recorded for the scorer" }, "last_scored_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the scorer last recorded a score" }, "model_id": { "type": "string", "description": "LLM model dispatched judge runs use to evaluate this scorer's\nrubric.\n" }, "self_improvement_enabled": { "type": "boolean", "description": "Whether self-improvement is enabled for this scorer" } } }, "ListScorersResponse": { "type": "object", "required": [ "scorers" ], "properties": { "scorers": { "type": "array", "items": { "$ref": "#/components/schemas/ScorerListItem" } } } }, "ScorerOutcome": { "type": "string", "enum": [ "pass", "fail" ], "description": "Pass/fail verdict of a recorded score, derived at read time against\nthe evaluation's current threshold rather than frozen at scoring\ntime — editing the threshold retroactively changes the outcome of\nalready-scored runs. Today this is \"pass\" or \"fail\"; clients should\ntolerate additional values so future non-scoreable verdicts (for\nexample, excluded from scoring) do not break them. Do not use\nresult_count as a pass-rate denominator: only pass and fail count.\n" }, "ScorerResultStatus": { "type": "string", "enum": [ "scored", "failed", "in_flight" ], "description": "Outcome of a scoring attempt: \"scored\", \"failed\", or \"in_flight\" (no\nlive score yet and a judge is currently running). A failed or\nin_flight attempt has no classification. A scored attempt whose\nis_in_flight is also true has a live classification while a\nreplacement judge runs.\n" }, "ScorerReasonStatus": { "type": "string", "enum": [ "available", "absent", "unavailable" ], "description": "Available when the judge reason was read, absent when none was\nrecorded, and unavailable when a recorded reason could not be read.\n" }, "ScorerResult": { "type": "object", "required": [ "run_id", "status", "attempted_at", "is_in_flight" ], "properties": { "run_id": { "type": "string", "description": "The selected agent run that anchors the scoring attempt" }, "conversation_id": { "type": "string", "nullable": true, "description": "Conversation whose transcript was judged" }, "conversation_title": { "type": "string", "nullable": true, "description": "Title of the judged conversation" }, "status": { "$ref": "#/components/schemas/ScorerResultStatus" }, "reason_status": { "allOf": [ { "$ref": "#/components/schemas/ScorerReasonStatus" } ], "description": "Present only when include_reasons is true." }, "reason": { "type": "string", "description": "Judge reasoning; present only when reason_status is available." }, "classification": { "type": "string", "nullable": true, "description": "The chosen classification; absent when the attempt failed" }, "attempted_at": { "type": "string", "format": "date-time", "description": "When the scorer last attempted this run" }, "scored_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the live score was recorded; absent for failed attempts" }, "scoring_run_id": { "type": "string", "nullable": true, "description": "The Warp run that performed the judging; absent when scoring was never dispatched for this attempt" }, "scoring_run_usage": { "allOf": [ { "$ref": "#/components/schemas/RequestUsage" } ], "description": "Cost of the scoring run (the Warp judge run), independent of the\nscored run's own cost. Absent when there is no scoring run yet, or\nits usage is not yet available (e.g. the judge is still in flight).\n" }, "scoring_run_time": { "type": "string", "nullable": true, "description": "Total runtime of the scoring run as an ISO 8601 duration. Absent\nwhen there is no scoring run or its execution duration is not yet\navailable.\n" }, "score": { "type": "number", "format": "double", "nullable": true, "description": "Numeric score of the classified label, resolved from the attempt's\nconfig snapshot at scoring time. Absent when the attempt failed.\n" }, "outcome": { "type": "string", "anyOf": [ { "$ref": "#/components/schemas/ScorerOutcome" }, { "type": "string", "nullable": true, "enum": [ null ] } ], "nullable": true, "description": "Pass/fail verdict for this score, derived at read time against the\nevaluation's current threshold. Absent when the attempt failed.\n" }, "is_in_flight": { "type": "boolean", "description": "True when a non-terminal judge run currently holds this pair.\nIndependent of status/classification: a previous live\nclassification stays visible while a replacement judge runs.\n" } } }, "ListScorerResultsResponse": { "type": "object", "required": [ "results", "page_info" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/ScorerResult" } }, "page_info": { "$ref": "#/components/schemas/PageInfo" } } }, "ScorerMetricsResponse": { "type": "object", "description": "A scorer's pass-rate series over one date range, period-aligned to\nperiod_list, plus a full-range aggregate computed over the exact\nsame set of live scores as the series.\n", "required": [ "group_by_period", "period_list", "pass_count", "fail_count", "pass_rate", "pass_count_series", "fail_count_series", "pass_rate_series" ], "properties": { "group_by_period": { "$ref": "#/components/schemas/FactoryMetricsGroupByPeriod" }, "period_list": { "type": "array", "description": "Period labels every series aligns to (dates like 2026-07-01;\nweeks labeled by their Sunday start date).\n", "items": { "type": "string" } }, "pass_count": { "type": "integer", "format": "int64", "description": "Live scores whose derived outcome is pass, over the whole range." }, "fail_count": { "type": "integer", "format": "int64", "description": "Live scores whose derived outcome is fail, over the whole range." }, "pass_rate": { "type": "number", "format": "double", "nullable": true, "description": "pass_count / (pass_count + fail_count) over the whole range; null\nwhen the range has no pass/fail scores. The dashboard headline\nshould use this field, not a per-period value, so it always\ndescribes the same window as the chart.\n" }, "pass_count_series": { "type": "array", "description": "One entry per period_list entry, zero-filled.", "items": { "type": "integer", "format": "int64" } }, "fail_count_series": { "type": "array", "description": "One entry per period_list entry, zero-filled.", "items": { "type": "integer", "format": "int64" } }, "pass_rate_series": { "type": "array", "description": "One entry per period_list entry; pass_count_series[i] /\n(pass_count_series[i] + fail_count_series[i]). Null for a period\nwith no pass/fail scores, so the chart renders a gap there\ninstead of a false 0%.\n", "items": { "type": "number", "format": "double", "nullable": true } }, "cost_usd_series": { "type": "array", "description": "What the owning team was billed for the scorer's judge runs in\neach period_list entry, in US dollars; charges recorded before\nbilled amounts were tracked fall back to an estimated cost.\nPresent only when include_cost=true.\n", "items": { "type": "number", "format": "double" } }, "total_cost_usd": { "type": "number", "format": "double", "description": "What the owning team was billed for all of the scorer's live\njudge runs, in US dollars, with the same estimated fallback as\ncost_usd_series. Present only when include_cost=true.\n" } } }, "RunScorerDispatchRequest": { "type": "object", "required": [ "scorer_uids" ], "properties": { "scorer_uids": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/ScorerUID" }, "description": "Scorer UUIDs to apply to the run." } } }, "ScorerDispatchRequest": { "type": "object", "required": [ "run_ids" ], "properties": { "run_ids": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string", "format": "uuid" }, "description": "Run UUIDs to evaluate with the scorer." } } }, "ManualScoringDispatchStatus": { "type": "string", "enum": [ "dispatched", "already_in_flight", "failed_no_transcript", "failed_run_tree_not_ready", "failed_run_tree_incomplete", "failed_run_tree_too_large", "failed_to_dispatch" ], "description": "Outcome of one dispatched (run, scorer) pair: \"dispatched\" (stamped\nwith a new or shared judge run), \"already_in_flight\" (an existing live\njudge already holds the pair; it is not queued, cancelled, or\nreplaced), \"failed_no_transcript\" (no scoreable transcript existed, so\na failed attempt was stamped instead), \"failed_run_tree_not_ready\"\n(the selected run or a descendant can be retried after execution or\nsynchronization finishes), \"failed_run_tree_incomplete\" or\n\"failed_run_tree_too_large\" (a failed anchor attempt was stamped), or\n\"failed_to_dispatch\" (validation rejected the target or an operational\nerror occurred; inspect error before retrying).\n" }, "ManualScoringDispatchResult": { "type": "object", "required": [ "scorer_uid", "run_id", "status" ], "properties": { "scorer_uid": { "$ref": "#/components/schemas/ScorerUID" }, "run_id": { "type": "string", "format": "uuid", "description": "The selected agent run that anchors the scoring attempt" }, "status": { "$ref": "#/components/schemas/ManualScoringDispatchStatus" }, "scoring_run_id": { "type": "string", "nullable": true, "format": "uuid", "description": "The judge run covering this pair; present for dispatched and\nalready_in_flight, absent otherwise. Multiple pairs for the same\nrun can share one scoring_run_id.\n" }, "error": { "type": "string", "nullable": true, "description": "Safe error detail; present only for failed_to_dispatch" } } }, "ManualScoringDispatchResponse": { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/ManualScoringDispatchResult" }, "description": "One entry per requested pair, in no particular order" } } }, "RunScoreAttemptStatus": { "type": "string", "enum": [ "in_flight", "scored", "failed" ], "description": "Classification of a run's current attempt against one evaluation.\n\"scored\" takes precedence over in-flight: a live score reads as\nscored even while a replacement judge runs, and is_in_flight reports\nthat overlap independently.\n" }, "RunScoreTriggerSource": { "type": "string", "enum": [ "automatic", "manual" ], "description": "Whether the current attempt was requested by an automatic scoring dispatch or a manual dispatch request" }, "RunScoreItem": { "type": "object", "required": [ "scorer_uid", "scorer_id", "scorer_name", "attempt_status", "is_in_flight", "trigger_source", "attempted_at" ], "properties": { "scorer_uid": { "$ref": "#/components/schemas/ScorerUID" }, "scorer_id": { "type": "integer", "description": "The evaluation that attempted this run" }, "scorer_name": { "type": "string", "description": "Display name of the evaluation" }, "attempt_status": { "$ref": "#/components/schemas/RunScoreAttemptStatus" }, "is_in_flight": { "type": "boolean", "description": "True when a non-terminal judge run currently holds this pair" }, "trigger_source": { "$ref": "#/components/schemas/RunScoreTriggerSource" }, "classification": { "type": "string", "nullable": true, "description": "The live classification; absent when there is no live score" }, "attempted_at": { "type": "string", "format": "date-time", "description": "When the evaluation last attempted this run" }, "scored_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the live score was recorded; absent when there is no live score" }, "scoring_run_id": { "type": "string", "nullable": true, "description": "The Warp run that performed the judging; absent when scoring was never dispatched for this attempt" } } }, "GetRunScoresResponse": { "type": "object", "required": [ "run_id", "scores" ], "properties": { "run_id": { "type": "string", "description": "The run these scores belong to" }, "scores": { "type": "array", "items": { "$ref": "#/components/schemas/RunScoreItem" }, "description": "One entry per evaluation that has attempted the run, most recent attempt first" } } }, "CreateAgentRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "A name for the agent" }, "description": { "type": "string", "nullable": true, "description": "Optional description of the agent" }, "prompt": { "type": "string", "nullable": true, "description": "Optional base prompt for this agent\n" }, "environment_id": { "type": "string", "nullable": true, "description": "Optional default cloud environment ID for runs executed by this agent.\nThe environment must be owned by the same team as the agent.\n" }, "default_runner_uid": { "type": "string", "nullable": true, "description": "Optional default runner UID for runs executed by this agent. When set,\nit overrides the selected environment's default runner for runs that\ndo not specify their own `runner_id`. The editor must have View\npermission on the referenced runner.\n" }, "secrets": { "type": "array", "items": { "$ref": "#/components/schemas/SecretRef" }, "description": "Optional list of secrets associated with the agent.\nDuplicate names within a single request are rejected.\nEach entry is unioned into the run-time secret scope when the agent executes.\n" }, "skills": { "type": "array", "items": { "type": "string" }, "description": "Optional list of skill specs to associate with the agent.\nFormat: \"{owner}/{repo}:{skill_path}\" (e.g., \"warpdotdev/warp-server:.claude/skills/deploy/SKILL.md\").\nEach spec is validated and normalized at attach time using the team's GitHub\ncredentials; inaccessible or malformed specs are rejected.\n" }, "base_model": { "type": "string", "nullable": true, "description": "Optional base model for runs executed by this agent.\n" }, "inference_providers": { "allOf": [ { "$ref": "#/components/schemas/InferenceProvidersConfig" } ], "description": "Optional inference provider settings for this agent.\nAgent-level config takes precedence over the workspace's\nadmin-configured defaults.\n" }, "memory": { "allOf": [ { "$ref": "#/components/schemas/AgentMemoryCreateConfig" } ], "description": "Optional memory settings for the agent." }, "mcp_servers": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/MCPServerConfig" }, "description": "Optional map of MCP server configurations by name to attach to runs executed by this agent.\nRun-level MCP config takes precedence over this agent-level default.\n" }, "base_harness": { "type": "string", "nullable": true, "deprecated": true, "description": "Optional default harness for runs executed by this agent.\nDeprecated - use harness instead. Kept for backward compatibility;\nwhen both are sent, harness is authoritative and a conflicting\ntype is rejected with invalid_request.\n" }, "harness": { "allOf": [ { "$ref": "#/components/schemas/Harness" } ], "description": "Optional default harness for runs executed by this agent.\nOmission or an empty object stores no harness default.\n" }, "credential_strategy": { "allOf": [ { "$ref": "#/components/schemas/AgentCredentialStrategy" } ], "nullable": true, "description": "Optional default credential strategy for runs executed by this\nagent. When omitted or null, the agent has no opinion and runs fall\nback to the factory default (for factory-seeded agents) and then to\nEXECUTOR.\n" }, "harness_auth_secrets": { "allOf": [ { "$ref": "#/components/schemas/HarnessAuthSecrets" } ], "description": "Optional per-harness authentication secrets for this agent.\nEach field names a managed secret for the corresponding harness.\nSecrets are resolved at execution time from the agent's team scope.\n" }, "on_behalf_of_enabled": { "type": "boolean", "description": "Whether runs created with this agent's API key may use the on_behalf_of\nfield to attribute runs to another team member. Defaults to false.\nOnly team admins may set this field.\n" }, "worker_host": { "type": "string", "nullable": true, "description": "Optional default worker host for runs executed by this agent;\nomission, null, or an empty value stores no Agent default, in\nwhich case the workspace default applies. A non-empty value is\ntrimmed and stored (use \"warp\" to force Warp-hosted execution\nover a self-hosted workspace default), and is resolved in this\norder:\n1. The host specified on the run itself\n2. The agent's default host\n3. The workspace default host\n" } } }, "UpdateAgentRequest": { "type": "object", "description": "Partial update for an agent; each field is optional:\n * Omitted or `null`: leave the field unchanged.\n * Empty value: clear the field.\n * Non-empty: replace the field wholesale with the provided value.\n`secrets_append` is an exception: it appends secrets idempotently and\nmust be the only supplied field, including fields supplied as `null`.\n`network_policy` is also an exception: omission preserves the policy,\nnull clears it, and an object replaces it wholesale. An object with\nno rules stores a deny-all policy.\n", "properties": { "name": { "type": "string", "description": "The new name for the agent" }, "description": { "type": "string", "nullable": true, "description": "Replacement description. Omit or pass `null` to leave unchanged, or use an empty value to clear.\n" }, "prompt": { "type": "string", "nullable": true, "description": "Replacement prompt. Omit or pass `null` to leave unchanged, or use an empty value to clear.\n" }, "environment_id": { "type": "string", "nullable": true, "description": "Replacement default cloud environment ID. Omit or pass `null` to leave unchanged,\nor pass an empty string to clear.\n" }, "default_runner_uid": { "type": "string", "nullable": true, "description": "Replacement default runner UID. Omit or pass `null` to leave unchanged,\nor pass an empty string to clear. A non-empty value must reference a\nrunner the editor can View.\n" }, "secrets": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/SecretRef" }, "description": "Replacement list of secrets. Omit to leave unchanged, pass an\nempty array to clear, or pass a non-empty array to replace.\nDuplicate names are rejected.\n" }, "secrets_append": { "type": "array", "nullable": false, "items": { "$ref": "#/components/schemas/SecretRef" }, "description": "Adds team-owned raw-value secrets to this agent without removing or\nreplacing its existing ones. Secrets it already has and any duplicates\nare skipped, and an empty array is a no-op. If any name is invalid, the\nwhole request is rejected. Send this field by itself. Including any other\nfield returns 400, even if that field is null, and null is not a valid\nvalue here. Appending requires edit and privileged-config-edit access on\nthe agent plus secret-attach access on its Factory. Agents managed in\nexternal source files return 409.\n" }, "skills": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Replacement list of skill specs. Omit to leave unchanged, pass an empty array\nto clear, or pass a non-empty array to replace.\n" }, "base_model": { "type": "string", "nullable": true, "description": "Replacement base model. Omit or pass `null` to leave unchanged,\nor pass an empty string to clear.\n" }, "memory": { "allOf": [ { "$ref": "#/components/schemas/AgentMemoryUpdateConfig" } ], "nullable": true, "description": "Replacement memory settings for this agent." }, "mcp_servers": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/MCPServerConfig" }, "description": "Replacement map of MCP server configurations by name. Omit to leave\nunchanged, pass an empty object to clear, or pass a non-empty object\nto replace. Run-level MCP config takes precedence over this agent-level\ndefault.\n" }, "inference_providers": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/InferenceProvidersConfig" } ], "nullable": true, "description": "Replacement inference provider settings for this agent, which\ntake precedence over the workspace's admin-configured defaults;\nomit or pass `null` to leave unchanged, or pass an empty object\n`{}` to clear.\n" }, "base_harness": { "type": "string", "nullable": true, "deprecated": true, "description": "Replacement default harness; omit or pass `null` to leave\nunchanged, or pass an empty string to clear. Deprecated - use\nharness instead, kept only for backward compatibility: when both\nare sent, harness is authoritative and a conflicting type is\nrejected with invalid_request.\n" }, "harness": { "allOf": [ { "$ref": "#/components/schemas/Harness" } ], "nullable": true, "description": "Replacement default harness for runs executed by this agent. Omit\nor pass `null` to leave unchanged, pass `{}` to clear the stored\ndefault, or pass a populated object to replace it wholesale.\n" }, "credential_strategy": { "allOf": [ { "$ref": "#/components/schemas/AgentCredentialStrategy" } ], "nullable": true, "description": "Replacement default credential strategy. Omit or pass `null` to\nleave unchanged, or pass an empty string to clear the agent's\ndefault. An agent belonging to a file-managed factory cannot clear\nit: its agent file expresses the strategy by declaring it, and a\nfile that declares none keeps the strategy already projected, so a\nclear is rejected with a 400.\n" }, "harness_auth_secrets": { "allOf": [ { "$ref": "#/components/schemas/HarnessAuthSecrets" } ], "nullable": true, "description": "Replacement per-harness authentication secrets. Omit or pass `null`\nto leave unchanged, or pass an empty object to clear all secrets.\n" }, "on_behalf_of_enabled": { "type": "boolean", "nullable": true, "description": "Whether runs created with this agent's API key may use the on_behalf_of\nfield to attribute runs to another team member. Omit or pass `null` to\nleave unchanged. Only team admins may set this field.\n" }, "worker_host": { "type": "string", "nullable": true, "description": "Replacement default worker host. Omit or pass `null` to leave\nunchanged, or pass an empty string to clear (the workspace default\nthen applies). A non-empty value is trimmed and replaces the\nstored default; use \"warp\" to force Warp-hosted execution over a\nself-hosted workspace default.\n" } } }, "AgentResponse": { "type": "object", "required": [ "uid", "name", "available", "created_at", "updated_at", "secrets", "skills", "memory", "default_runner_uid" ], "properties": { "uid": { "type": "string", "description": "Unique identifier for the agent" }, "name": { "type": "string", "description": "Name of the agent" }, "description": { "type": "string", "nullable": true, "description": "Optional description of the agent" }, "prompt": { "type": "string", "nullable": true, "description": "Optional base prompt for this agent\n" }, "environment_id": { "type": "string", "description": "Default cloud environment ID for runs executed by this agent;\nthe precedence order for environment resolution is:\n1. The environment specified on the run itself\n2. The agent's default environment\n3. An empty environment\n" }, "default_runner_uid": { "type": "string", "description": "Default runner UID for runs executed by this agent; when set,\nit overrides the selected environment's default runner for\nruns that do not specify their own `runner_id`. The precedence\norder for runner resolution is:\n1. The runner specified on the run itself\n2. The agent's default runner\n3. The selected environment's default runner\n4. The environment's legacy inline compute fields\n5. System defaults\n" }, "available": { "type": "boolean", "description": "Whether the agent is currently enabled. Defaults to true." }, "created_at": { "type": "string", "format": "date-time", "description": "When the agent was created (RFC3339)" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the agent was last updated (RFC3339)" }, "secrets": { "type": "array", "items": { "$ref": "#/components/schemas/SecretRef" }, "description": "Secrets that this agent may access by default.\n" }, "skills": { "type": "array", "items": { "type": "string" }, "description": "Ordered list of normalized skill specs associated with this agent.\nAlways present; empty when no skills are attached.\n" }, "base_model": { "type": "string", "description": "Base model for runs executed by this agent; the precedence\norder for model resolution is:\n1. The model specified on the run itself\n2. The agent's base model\n3. The team's default model\n" }, "inference_providers": { "allOf": [ { "$ref": "#/components/schemas/InferenceProvidersConfig" } ], "description": "The agent's stored inference provider settings. May be overridden\nby run-level config; if empty, falls back to the workspace's\nadmin-configured defaults.\n" }, "memory": { "allOf": [ { "$ref": "#/components/schemas/AgentMemoryResponse" } ], "description": "Memory settings for this agent.\nAlways present; attached_stores is empty when no team stores are attached.\n" }, "mcp_servers": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/MCPServerConfig" }, "description": "MCP server configurations attached to this agent by default.\nRun-level MCP config takes precedence over this agent-level default.\n" }, "base_harness": { "type": "string", "deprecated": true, "description": "Default harness for runs executed by this agent; the\nprecedence order for harness resolution is:\n1. The harness specified on the run itself\n2. The agent's base harness\n3. Warp\nDeprecated: use harness instead, which carries the full\n{type, model_id, reasoning_level} default.\n" }, "harness": { "allOf": [ { "$ref": "#/components/schemas/Harness" } ], "description": "Default harness for runs executed by this agent. Absent when the\nagent has no harness default. A stored model_id/reasoning_level\npair is still returned even if the model has since left the\nharness's catalog.\n" }, "credential_strategy": { "allOf": [ { "$ref": "#/components/schemas/AgentCredentialStrategy" } ], "description": "Default credential strategy for runs executed by this agent.\nAbsent when the agent has no default. The precedence order for\ncredential strategy resolution is:\n1. The strategy specified on the run itself\n2. The agent's default strategy\n3. The factory's default strategy, for factory-seeded agents\n4. EXECUTOR\nThe resolved strategy is credential-validated at run creation;\nan unavailable credential rejects the request before execution.\n" }, "harness_auth_secrets": { "allOf": [ { "$ref": "#/components/schemas/HarnessAuthSecrets" } ], "description": "Per-harness authentication secrets configured on this agent.\nEach field names a managed secret for the corresponding harness.\nSecrets can be overridden per run.\n" }, "on_behalf_of_enabled": { "type": "boolean", "description": "Whether runs created with this agent's API key may use the on_behalf_of\nfield to attribute runs to another team member.\n" }, "worker_host": { "type": "string", "description": "Default worker host for runs executed by this agent, or empty\nwhen unset; the precedence order for worker host resolution is:\n1. The host specified on the run itself\n2. The agent's default host\n3. The workspace default host\n" } } }, "ListAgentIdentitiesResponse": { "type": "object", "required": [ "agents" ], "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/AgentResponse" } } } }, "EnvironmentLastTask": { "type": "object", "description": "Summary of the most recently created task for an environment", "required": [ "id", "title", "state", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "description": "Unique identifier of the task" }, "title": { "type": "string", "description": "Title of the task" }, "state": { "$ref": "#/components/schemas/RunState" }, "created_at": { "type": "string", "format": "date-time", "description": "When the task was created (RFC3339)" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the task was last updated (RFC3339)" }, "started_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the task started running (RFC3339), null if not yet started" } } }, "BenchmarkRunState": { "type": "string", "description": "Lifecycle state of a benchmark run.", "enum": [ "pending", "running", "scoring", "completed", "failed", "cancelled" ] }, "BenchmarkTrialState": { "type": "string", "description": "Lifecycle state of a benchmark trial.", "enum": [ "pending", "running", "succeeded", "failed", "cancelled" ] }, "BenchmarkRepoRef": { "type": "object", "description": "A repository location and optional starting ref for a suite task.", "required": [ "code_forge", "owner", "repo" ], "properties": { "code_forge": { "type": "string" }, "owner": { "type": "string" }, "repo": { "type": "string" }, "ref": { "type": "string" } } }, "BenchmarkSuiteTask": { "type": "object", "required": [ "uid", "title", "prompt", "success_criteria" ], "properties": { "uid": { "type": "string", "format": "uuid", "description": "Immutable public task identifier." }, "title": { "type": "string" }, "prompt": { "type": "string" }, "success_criteria": { "type": "string", "description": "Plain-text criteria the built-in Correctness scorer grades each trial\nagainst, as the authoritative requirements. The task prompt provides\ncontext only.\n" }, "source_run_id": { "type": "string", "nullable": true }, "labels": { "type": "object", "additionalProperties": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "starting_repo_refs": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkRepoRef" } } } }, "BenchmarkAgentConfigInput": { "type": "object", "required": [ "agent_uid", "harness", "model" ], "properties": { "agent_uid": { "type": "string", "format": "uuid" }, "agent_name": { "type": "string" }, "harness": { "type": "string" }, "model": { "type": "string" }, "harness_auth_secret_name": { "type": "string", "nullable": true } } }, "BenchmarkSuite": { "type": "object", "required": [ "uid", "factory_uid", "name", "agent_uid", "factory_agent_type", "created_at", "updated_at" ], "properties": { "uid": { "type": "string" }, "factory_uid": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "agent_uid": { "type": "string", "description": "UID of the concrete Factory agent every task in this suite dispatches\nas. Must resolve to a live, available agent linked to this Factory\nwhose agent_type equals factory_agent_type.\n" }, "factory_agent_type": { "type": "string", "description": "Coarse Factory agent type of the selected agent_uid, kept in sync with\nit at save time.\n" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "creator": { "allOf": [ { "$ref": "#/components/schemas/BenchmarkSuiteCreator" } ], "description": "The suite's creator, when known. Absent when creator identity is\nunknown or no longer retained.\n" }, "configurations": { "type": "array", "description": "File-authored launch defaults. Omitted on suites without persistent configurations.", "items": { "$ref": "#/components/schemas/BenchmarkConfigurationInput" } } } }, "BenchmarkSuiteCreator": { "type": "object", "required": [ "type", "uid" ], "properties": { "type": { "type": "string", "enum": [ "user", "agent" ] }, "uid": { "type": "string" }, "display_name": { "type": "string" } } }, "BenchmarkSuiteDetail": { "allOf": [ { "$ref": "#/components/schemas/BenchmarkSuite" }, { "type": "object", "required": [ "spawnable_descendant_agent_uids" ], "properties": { "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkSuiteTask" } }, "spawnable_descendant_agent_uids": { "type": "array", "items": { "type": "string" }, "description": "Stable UID-sorted list of live, non-system Factory agents\ntransitively reachable from this suite's selected root under\nthe server's effective delegation policy.\n" } } } ] }, "BenchmarkSuiteCreateRequest": { "type": "object", "required": [ "uid", "name", "agent_uid", "factory_agent_type" ], "properties": { "uid": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "agent_uid": { "type": "string" }, "factory_agent_type": { "type": "string" }, "tasks": { "type": "array", "description": "The array order is not significant: a task's identity comes from its\nuid (when editing an existing task) or title (when creating one),\nnever its position. Reads return tasks in creation order.\n", "items": { "$ref": "#/components/schemas/BenchmarkSuiteTaskInput" } } } }, "BenchmarkSuiteTaskInput": { "type": "object", "required": [ "title", "prompt", "success_criteria" ], "properties": { "uid": { "type": "string", "format": "uuid", "description": "Existing task UID. Accepted only when editing its current suite." }, "title": { "type": "string" }, "prompt": { "type": "string" }, "success_criteria": { "type": "string", "description": "Plain-text criteria the built-in Correctness scorer grades each trial\nagainst, as the authoritative requirements. The task prompt provides\ncontext only.\n" }, "source_run_id": { "type": "string", "nullable": true }, "labels": { "type": "object", "additionalProperties": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "starting_repo_refs": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkRepoRef" } } } }, "BenchmarkSuiteTaskCreateRequest": { "type": "object", "required": [ "title", "prompt", "success_criteria" ], "properties": { "title": { "type": "string" }, "prompt": { "type": "string" }, "success_criteria": { "type": "string", "description": "Plain-text criteria the built-in Correctness scorer grades each trial\nagainst, as the authoritative requirements. The task prompt provides\ncontext only.\n" }, "source_run_id": { "type": "string", "nullable": true, "description": "Optional provenance. The caller must be able to read the run.\n" }, "tags": { "type": "array", "items": { "type": "string" } }, "starting_repo_refs": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkRepoRef" } } } }, "BenchmarkSuiteTaskPatchRequest": { "type": "object", "properties": { "title": { "type": "string" }, "prompt": { "type": "string" }, "success_criteria": { "type": "string" }, "source_run_id": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "starting_repo_refs": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkRepoRef" } } } }, "BenchmarkConfigurationInput": { "type": "object", "properties": { "display_name": { "type": "string", "description": "Optional name for this configuration." }, "harness": { "type": "string" }, "model": { "type": "string" }, "runner_id": { "type": "string", "nullable": true, "description": "Optional runner UID, constrained to the Factory's existing runner\nroster. Omitted or empty uses the agent's or environment's default.\n" }, "harness_auth_secret_name": { "type": "string", "nullable": true, "description": "Optional managed-secret name this configuration's third-party harness\nauthenticates with. Empty or omitted is valid for Oz. For a third-party\nharness that requires auth, empty or omitted means from the worker\nenvironment on a self-hosted host, or a launch violation on Warp-hosted.\n" }, "agent_configs": { "type": "array", "description": "Optional per-named-Agent overrides keyed by stable Agent UID.", "items": { "$ref": "#/components/schemas/BenchmarkAgentConfigInput" } } } }, "BenchmarkSuitePatchRequest": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "agent_uid": { "type": "string", "description": "Must be supplied together with factory_agent_type, or omitted with it,\nto leave the saved selection unchanged.\n" }, "factory_agent_type": { "type": "string" }, "tasks": { "type": "array", "nullable": true, "description": "The array order is not significant: a task's identity comes from its\nuid (when editing an existing task) or title (when creating one),\nnever its position. Reads return tasks in creation order.\n", "items": { "$ref": "#/components/schemas/BenchmarkSuiteTaskInput" } } } }, "LaunchBenchmarkRunRequest": { "type": "object", "required": [ "repetition_count" ], "properties": { "configurations": { "type": "array", "description": "Optional launch-time configurations. When omitted, the suite's\npersistent configurations are used. An explicit empty list, or a\nsuite with neither launch-time nor persistent configurations, is\nrejected.\n", "items": { "$ref": "#/components/schemas/BenchmarkConfigurationInput" } }, "repetition_count": { "type": "integer", "description": "Number of repetitions per (task, configuration) pair, frozen onto the\nrun. Like configurations and scorer_selection, this is chosen fresh\nat each launch rather than persisted on the suite.\n" }, "scorer_selection": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/ScorerUID" }, { "type": "integer", "minimum": 1 } ] }, "description": "Allowlist of live scorer UUIDs (or temporary positive numeric IDs) for this factory, applied to every trial\nin the run. Empty or absent means all applicable scorers. IDs must\nbelong to the suite's factory and team (any status except deleted).\n" }, "tasks": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string" }, "example": [ "7d69fb52-71c5-4e27-914e-8764ee9c5246", "ad8ff7dc-a7d1-4ed6-9f50-650010bb39aa" ], "description": "Optional allowlist of immutable UIDs for current tasks in the addressed\nsuite. Omitted runs all current suite tasks. Explicit empty, invalid,\nunknown, stale, cross-suite, and duplicate selections are rejected.\n" } } }, "BenchmarkRunLaunchResponse": { "type": "object", "required": [ "uid", "state" ], "properties": { "uid": { "type": "string" }, "state": { "$ref": "#/components/schemas/BenchmarkRunState" } } }, "BenchmarkRunList": { "type": "object", "required": [ "data", "page_info" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkRun" }, "description": "complete requested Run rows on this page, newest first." }, "page_info": { "$ref": "#/components/schemas/BenchmarkPageInfo", "description": "continuation for this Run list only." } } }, "BenchmarkTrialList": { "type": "object", "required": [ "data", "page_info" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkTrial" }, "description": "complete requested logical Trial rows on this page, or zero/one targeted match." }, "page_info": { "$ref": "#/components/schemas/BenchmarkPageInfo", "description": "continuation for the Trial list; targeted lookup always has `has_next_page=false`." } } }, "BenchmarkPageInfo": { "type": "object", "required": [ "has_next_page" ], "properties": { "has_next_page": { "type": "boolean", "description": "true when another complete list page exists." }, "next_cursor": { "type": "string", "description": "opaque scoped keyset cursor, present only when `has_next_page=true`, never null." } } }, "BenchmarkRun": { "type": "object", "required": [ "uid", "factory_uid", "suite_uid", "suite_name", "agent_uid", "agent_name", "state", "created_at", "updated_at", "started_at", "completed_at", "creator", "execution", "scoring" ], "properties": { "uid": { "type": "string", "description": "existing benchmark Run UID, including legacy non-UUID identities." }, "factory_uid": { "type": "string", "description": "authorized owning Factory UID." }, "factory_version_sha": { "type": "string", "description": "The commit SHA identifying the factory version at the time the benchmark run was launched.\n\nNote: This currently does not ensure that the factory configuration stays fixed for the duration of the benchmark run.\n" }, "suite_uid": { "type": "string", "description": "suite UID verified against the frozen Run context." }, "suite_name": { "type": "string", "nullable": true, "description": "retained frozen suite name; unknown legacy name is null." }, "agent_uid": { "type": "string", "nullable": true, "description": "tested root agent's frozen UID when retained." }, "agent_name": { "type": "string", "nullable": true, "description": "tested root agent's frozen name, not today's catalog name." }, "state": { "$ref": "#/components/schemas/BenchmarkRunState", "description": "captured benchmark Run lifecycle state." }, "created_at": { "type": "string", "format": "date-time", "description": "stored Run creation time." }, "updated_at": { "type": "string", "format": "date-time", "description": "stored Run update time, not a complete source-validity watermark." }, "started_at": { "type": "string", "format": "date-time", "nullable": true, "description": "stored Run start time; null before start or if not retained." }, "completed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "stored Run terminal time; null while active or if not retained." }, "creator": { "allOf": [ { "$ref": "#/components/schemas/BenchmarkRunCreator" } ], "nullable": true, "description": "safe retained creator identity, or null when it cannot be resolved." }, "execution": { "$ref": "#/components/schemas/BenchmarkExecutionProgress", "description": "logical Trial counts, never attempt/descendant counts." }, "scoring": { "$ref": "#/components/schemas/BenchmarkRunScoring", "description": "existing raw ledger and logical-Trial judging progress, without score values." }, "details": { "$ref": "#/components/schemas/BenchmarkRunDetails", "description": "present only for `include=details`; always non-null when requested." }, "summary_results": { "$ref": "#/components/schemas/BenchmarkResultsSummary", "description": "present only for `include=summary_results`; whole-run, on-request summary without metric arrays." } } }, "BenchmarkRunCreator": { "type": "object", "required": [ "type", "uid" ], "properties": { "type": { "type": "string", "enum": [ "user", "agent" ], "description": "resolved creator type; agent includes identities behind API keys." }, "uid": { "type": "string", "description": "creator's public UID, never its database ID." }, "display_name": { "type": "string", "nullable": true, "description": "present only for an authorized creator-display-name include; null if the name is unknown, with no email fallback." } } }, "BenchmarkExecutionProgress": { "type": "object", "required": [ "planned_total", "total", "pending", "running", "succeeded", "failed", "cancelled", "completed" ], "properties": { "planned_total": { "type": "integer", "description": "frozen selected task/configuration/repetition matrix size for this scope." }, "total": { "type": "integer", "description": "observed stored logical Trial row count." }, "pending": { "type": "integer", "description": "Trials without a currently executing attempt, including queued/claimed attempts." }, "running": { "type": "integer", "description": "Trials with a currently executing attempt." }, "succeeded": { "type": "integer", "description": "successfully completed logical Trials." }, "failed": { "type": "integer", "description": "failed logical Trials after existing retry rules." }, "cancelled": { "type": "integer", "description": "cancelled logical Trials." }, "completed": { "type": "integer", "description": "`succeeded + failed + cancelled`, not merely successful Trials." } } }, "BenchmarkRunScoring": { "type": "object", "required": [ "total", "awaiting_trial", "pending", "judging", "scored", "finished_unscored", "not_scoreable", "received", "expected", "settled", "trials_being_judged", "trials_scoring_finished" ], "properties": { "total": { "type": "integer", "nullable": true, "description": "all applicable ledger pairs; null before materialization, zero only for known zero work." }, "awaiting_trial": { "type": "integer", "description": "raw pairs still waiting for execution to finish." }, "pending": { "type": "integer", "description": "raw pairs awaiting judge dispatch after becoming eligible." }, "judging": { "type": "integer", "description": "raw pairs with an active judge." }, "scored": { "type": "integer", "description": "raw pairs marked scored in the durable ledger, even if bound evidence is now absent." }, "finished_unscored": { "type": "integer", "description": "raw pairs settled without a score." }, "not_scoreable": { "type": "integer", "description": "raw pairs skipped because execution failed or was cancelled." }, "received": { "type": "integer", "description": "exactly raw `scored`, not effective retained-score coverage." }, "expected": { "type": "integer", "nullable": true, "description": "`pending + judging + scored + finished_unscored` once materialized; otherwise null." }, "settled": { "type": "integer", "description": "raw `scored + finished_unscored + not_scoreable`." }, "trials_being_judged": { "type": "integer", "description": "succeeded Trials with at least one pending/judging applicable pair." }, "trials_scoring_finished": { "type": "integer", "description": "succeeded Trials with applicable work all scored/finished-unscored." } } }, "BenchmarkRunDetails": { "type": "object", "required": [ "configurations", "task_uids", "repetition_count", "scorer_selection", "scorers", "tags" ], "properties": { "configurations": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkRecordedConfiguration" }, "description": "complete frozen configurations in launch order, including tooltip settings." }, "task_uids": { "type": "array", "items": { "type": "string" }, "description": "complete selected frozen task identities in launch order, including derived legacy identities." }, "repetition_count": { "type": "integer", "description": "frozen repetitions per task/configuration." }, "scorer_selection": { "$ref": "#/components/schemas/BenchmarkScorerSelection", "description": "recorded launch selection, not the materialized roster." }, "scorers": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkScorer" }, "description": "safe descriptors for this Run's resolved scorers, using the existing authorized resolver." }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkTagTasks" }, "description": "complete unfiltered frozen tag-to-task mapping; derive each tag's task count from its UID-array length." } } }, "BenchmarkRecordedConfiguration": { "type": "object", "required": [ "uid", "display_name", "harness", "model", "runner_id", "harness_auth_secret_name", "agent_configs" ], "properties": { "uid": { "type": "string", "description": "stable Run-local public configuration identity, without exposing its stored integer ID." }, "display_name": { "type": "string", "description": "frozen user-supplied name; the existing empty string means no supplied name." }, "harness": { "type": "string", "nullable": true, "description": "recorded effective root harness; unknown legacy values remain null." }, "model": { "type": "string", "nullable": true, "description": "recorded effective root model; never filled from live defaults." }, "runner_id": { "type": "string", "nullable": true, "description": "recorded root runner identity; no per-agent runner is introduced." }, "harness_auth_secret_name": { "type": "string", "nullable": true, "description": "retained root credential-name reference, including unavailable names." }, "agent_configs": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkRecordedAgentConfiguration" }, "description": "complete retained named-agent settings, including the root when recorded." } } }, "BenchmarkRecordedAgentConfiguration": { "type": "object", "required": [ "agent_uid", "agent_name", "harness", "model", "harness_auth_secret_name" ], "properties": { "agent_uid": { "type": "string", "description": "frozen named Factory agent UID." }, "agent_name": { "type": "string", "nullable": true, "description": "retained frozen named-agent label." }, "harness": { "type": "string", "nullable": true, "description": "named agent's recorded effective harness." }, "model": { "type": "string", "nullable": true, "description": "named agent's recorded effective model." }, "harness_auth_secret_name": { "type": "string", "nullable": true, "description": "retained named-agent credential-name reference." } } }, "BenchmarkScorerSelection": { "type": "object", "required": [ "mode", "scorer_uids" ], "properties": { "mode": { "type": "string", "enum": [ "all_applicable", "selected" ], "description": "preserved launch selection mode, even if selected scorers later disappear." }, "scorer_uids": { "type": "array", "items": { "type": "string" }, "description": "complete known canonical scorer UUIDs in the selected allowlist; empty for all-applicable." } } }, "BenchmarkScorer": { "type": "object", "required": [ "scorer_uid", "name", "kind", "output_type", "output_labels" ], "properties": { "scorer_uid": { "type": "string", "description": "canonical scorer UUID supplied by the integrated identity adapter." }, "name": { "type": "string", "description": "existing resolved scorer name, not a promised launch-frozen name." }, "kind": { "$ref": "#/components/schemas/ScorerKind", "description": "existing resolved scorer kind." }, "output_type": { "type": "string", "enum": [ "classification" ], "description": "current benchmark results support classification only." }, "output_labels": { "type": "array", "items": { "type": "string" }, "description": "existing resolved classification label values in configuration order." } } }, "BenchmarkTagTasks": { "type": "object", "required": [ "tag", "task_uids" ], "properties": { "tag": { "type": "string", "description": "exact frozen tag value, ordered lexically." }, "task_uids": { "type": "array", "items": { "type": "string" }, "description": "complete distinct selected frozen task UIDs carrying this tag, in the containing `details.task_uids` order." } } }, "BenchmarkTrial": { "type": "object", "required": [ "uid", "run_uid", "task_uid", "task_title", "task_tags", "configuration_uid", "repetition_index", "state", "terminal_reason", "current_agent_run_id", "attempt_count", "scoring" ], "properties": { "uid": { "type": "string", "description": "stable logical Trial identity for task/configuration/repetition." }, "run_uid": { "type": "string", "description": "containing benchmark Run UID." }, "task_uid": { "type": "string", "description": "frozen task UID, or stable Run-local public identity for a legacy task." }, "task_title": { "type": "string", "nullable": true, "description": "frozen task title; unknown legacy title remains null." }, "task_tags": { "type": "array", "items": { "type": "string" }, "description": "complete frozen task tags, not live tags." }, "configuration_uid": { "type": "string", "description": "containing Run's stable public configuration identity." }, "repetition_index": { "type": "integer", "description": "zero-based repetition coordinate; UI labels can add one." }, "state": { "$ref": "#/components/schemas/BenchmarkTrialState", "description": "captured logical Trial state after queued/claimed normalization." }, "terminal_reason": { "type": "string", "enum": [ "timeout", "failure" ], "nullable": true, "description": "existing failed-Trial distinction; cancellation is already in `state`." }, "current_agent_run_id": { "type": "string", "nullable": true, "description": "current execution attempt ID; null before dispatch." }, "attempt_count": { "type": "integer", "description": "stored dispatch count; zero before dispatch, legacy dispatched fallback one." }, "scoring": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkTrialScoringStatus" }, "description": "complete resolved classification-scorer rows with existing ledger status when present, without values/verdicts or scorer projection." }, "matched_attempt_number": { "type": "integer", "description": "one-based retained/current execution match on targeted lookup only; omitted elsewhere." }, "results": { "$ref": "#/components/schemas/BenchmarkTrialResults", "description": "present only for `include=results`; non-null individual evidence/metrics." }, "details": { "$ref": "#/components/schemas/BenchmarkTrialDetails", "description": "present only for `include=details`; non-null complete retained history/derived times." } } }, "BenchmarkTrialScoringStatus": { "type": "object", "required": [ "scorer_uid", "state" ], "properties": { "scorer_uid": { "type": "string", "description": "resolved canonical scorer UUID." }, "state": { "allOf": [ { "$ref": "#/components/schemas/BenchmarkTrialScoringState" } ], "nullable": true, "description": "existing effective ledger status after binding/cutoff checks; null when no ledger row exists." } } }, "BenchmarkTrialResults": { "type": "object", "required": [ "scoring", "metrics", "spend" ], "properties": { "scoring": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkTrialScoringResult" }, "description": "complete resolved scorer rows with existing evidence/status, including pending/unscored or absent-work rows." }, "metrics": { "$ref": "#/components/schemas/BenchmarkTrialMetrics", "description": "current retained retry-inclusive execution measurements under existing loader semantics." }, "spend": { "$ref": "#/components/schemas/BenchmarkSpend", "description": "retained execution/judging/combined totals under existing arithmetic." }, "agent_metrics": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkTrialAgentMetric" }, "description": "complete existing named-agent breakdown when available; omitted when the existing loader suppresses an empty/incomplete breakdown." } } }, "BenchmarkTrialScoringResult": { "type": "object", "required": [ "scorer_uid", "state", "name", "kind", "score", "label", "outcome", "latest_judge_run_id" ], "properties": { "scorer_uid": { "type": "string", "description": "resolved canonical scorer UUID." }, "state": { "allOf": [ { "$ref": "#/components/schemas/BenchmarkTrialScoringState" } ], "nullable": true, "description": "existing effective ledger status after binding/cutoff checks; null when no ledger row exists." }, "name": { "type": "string", "description": "existing authorized resolver name for this scorer." }, "kind": { "$ref": "#/components/schemas/ScorerKind", "description": "existing authorized resolver kind." }, "score": { "type": "number", "format": "double", "nullable": true, "description": "exact retained bound classification value at/before cutoff; zero is a real score." }, "label": { "type": "string", "nullable": true, "description": "label from that same bound score; null when no score evidence survives." }, "outcome": { "type": "string", "enum": [ "pass", "fail" ], "nullable": true, "description": "existing SQL-derived current-threshold verdict; null when no verdict is supplied." }, "latest_judge_run_id": { "type": "string", "nullable": true, "description": "latest retained judge execution ID by dispatch order; no full judge history is implied." } } }, "BenchmarkTrialMetrics": { "type": "object", "required": [ "compute_credits", "platform_credits", "inference_credits", "total_credits", "wall_time_s", "compute_cost_usd", "platform_cost_usd", "inference_cost_usd", "cost_usd" ], "properties": { "compute_credits": { "type": "string", "description": "summed retained execution-attempt compute credits." }, "platform_credits": { "type": "string", "description": "summed retained execution-attempt platform credits." }, "inference_credits": { "type": "string", "description": "summed retained execution-attempt inference credits." }, "total_credits": { "type": "string", "description": "sum of those three credit components." }, "wall_time_s": { "type": "number", "format": "double", "description": "summed retained attempt working durations, excluding teardown; not the span between Trial.details timestamps." }, "compute_cost_usd": { "type": "number", "format": "double", "description": "existing compute billed/fallback dollars over retained attempts." }, "platform_cost_usd": { "type": "number", "format": "double", "description": "existing platform billed/fallback dollars over retained attempts." }, "inference_cost_usd": { "type": "number", "format": "double", "description": "existing inference dollars, including applicable third-party provider estimates." }, "cost_usd": { "type": "number", "format": "double", "description": "sum of the three dollar components, not guaranteed exact billed cost." }, "provider_cost_estimate": { "$ref": "#/components/schemas/BenchmarkProviderCostEstimate", "description": "existing provider estimate/attribution, omitted when unavailable; never an invented zero estimate." }, "output_tokens": { "type": "integer", "description": "sum of reported retained output-token counts; omitted when unreported, but reported zero remains present." }, "tool_calls": { "type": "integer", "description": "sum of reported retained tool-call counts; omitted when unreported, but reported zero remains present." } } }, "BenchmarkSpend": { "type": "object", "required": [ "execution", "judging", "combined" ], "properties": { "execution": { "$ref": "#/components/schemas/BenchmarkSpendTotal", "description": "retry-inclusive retained execution totals under existing attribution." }, "judging": { "$ref": "#/components/schemas/BenchmarkSpendTotal", "description": "totals for distinct durably linked retained judge runs, including repeated rescores." }, "combined": { "$ref": "#/components/schemas/BenchmarkSpendTotal", "description": "execution plus judging totals." } } }, "BenchmarkSpendTotal": { "type": "object", "required": [ "cost_usd", "total_credits" ], "properties": { "cost_usd": { "type": "number", "format": "double", "description": "existing mixed billed/fallback/provider-estimate dollar total." }, "total_credits": { "type": "string", "description": "existing Warp credit total for this spend group." } } }, "BenchmarkTrialAgentMetric": { "type": "object", "required": [ "agent_uid", "agent_name", "cost_usd" ], "properties": { "agent_uid": { "type": "string", "description": "existing named-agent identity; the empty string retains the Unknown-agent fallback." }, "agent_name": { "type": "string", "description": "existing resolved label, including `\"Unknown agent\"` when identity is unavailable." }, "cost_usd": { "type": "number", "format": "double", "description": "existing exclusive named-agent cost summed across retained retries and non-system descendants." }, "sandbox_time_s": { "type": "number", "format": "double", "description": "existing summed claim-to-completion seconds, omitted when any contributing duration is unknown; measured zero is present." }, "cost_breakdown": { "$ref": "#/components/schemas/BenchmarkAgentCostBreakdown", "description": "Retained exclusive costs and public-model attribution, omitted when the existing loader gate or availability suppresses it." } } }, "BenchmarkAgentCostBreakdown": { "type": "object", "required": [ "compute_cost_usd", "platform_cost_usd", "inference_cost_usd" ], "properties": { "compute_cost_usd": { "type": "number", "format": "double" }, "platform_cost_usd": { "type": "number", "format": "double" }, "inference_cost_usd": { "type": "number", "format": "double" }, "categories": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/BenchmarkCategoryCost" } } } }, "BenchmarkCategoryCost": { "type": "object", "required": [ "cost_usd" ], "properties": { "cost_usd": { "type": "number", "format": "double" }, "model_costs_usd": { "type": "object", "additionalProperties": { "type": "number", "format": "double" } } } }, "BenchmarkProviderCostEstimate": { "type": "object", "required": [ "cost_usd", "incomplete" ], "properties": { "cost_usd": { "type": "string", "description": "public-rate estimated provider total, not a Warp-billed amount." }, "incomplete": { "type": "boolean", "description": "existing signal that estimate inputs/pricing are incomplete." }, "attributions": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkProviderCostAttribution" }, "description": "complete retained safe model attributions; omitted when the existing array is empty/unavailable." } } }, "BenchmarkProviderCostAttribution": { "type": "object", "required": [ "model", "cost_usd", "incomplete" ], "properties": { "model": { "type": "string", "description": "provider model identity used for this estimate." }, "cost_usd": { "type": "string", "description": "estimate subtotal for this model." }, "incomplete": { "type": "boolean", "description": "existing model-estimate incomplete signal." }, "tokens": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkProviderTokenCost" }, "description": "complete retained priced token buckets, omitted when empty/unavailable." }, "adjustments": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkProviderCostAdjustment" }, "description": "complete retained price multipliers, omitted when empty/unavailable." } } }, "BenchmarkProviderTokenCost": { "type": "object", "required": [ "kind", "tokens", "rate_usd_per_million", "cost_usd" ], "properties": { "kind": { "type": "string", "description": "existing token bucket kind; preserve source values without a new enum." }, "tokens": { "type": "integer", "description": "retained nonnegative token count in this bucket." }, "rate_usd_per_million": { "type": "string", "description": "provider USD rate per million tokens for this bucket." }, "cost_usd": { "type": "string", "description": "estimated USD subtotal for this token bucket." } } }, "BenchmarkProviderCostAdjustment": { "type": "object", "required": [ "kind", "multiplier" ], "properties": { "kind": { "type": "string", "description": "existing adjustment kind, not credential metadata." }, "multiplier": { "type": "string", "description": "dimensionless multiplier applied after token subtotals." } } }, "BenchmarkTrialDetails": { "type": "object", "required": [ "started_at", "completed_at", "attempts", "judge_runs" ], "properties": { "started_at": { "type": "string", "format": "date-time", "nullable": true, "description": "earliest retained execution claim across the Trial's attempts." }, "completed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "current attempt's retained terminal time only when the logical Trial is terminal." }, "attempts": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkExecutionAttempt" }, "description": "every retained execution attempt, ordered by one-based attempt number." }, "judge_runs": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkRetainedJudgeRun" }, "description": "every retained durable judge dispatch across scorers/rescores, ordered by dispatch time and internal row tie-breaker." } } }, "BenchmarkExecutionAttempt": { "type": "object", "required": [ "attempt_number", "agent_run_id", "state" ], "properties": { "attempt_number": { "type": "integer", "description": "one-based position in the original attempt chain, not an array index after retention loss." }, "agent_run_id": { "type": "string", "description": "retained execution attempt ID." }, "state": { "$ref": "#/components/schemas/BenchmarkExecutionState", "description": "underlying retained execution state, without logical Trial-state normalization." } } }, "BenchmarkRetainedJudgeRun": { "type": "object", "required": [ "scorer_uid", "name", "kind", "agent_run_id" ], "properties": { "scorer_uid": { "type": "string", "description": "resolved canonical identity of the scorer that dispatched this judge." }, "name": { "type": "string", "description": "existing resolved scorer label." }, "kind": { "$ref": "#/components/schemas/ScorerKind", "description": "existing resolved scorer kind." }, "agent_run_id": { "type": "string", "description": "judge execution ID retained in the durable dispatch row." } } }, "BenchmarkResultsSummary": { "type": "object", "required": [ "factory_uid", "suite_uid", "run_uid", "state", "as_of", "provisional", "incomplete_reason", "coverage", "compute_credits", "platform_credits", "spend", "elapsed_s", "task_count", "scorer_count", "narrative" ], "properties": { "factory_uid": { "type": "string", "description": "authorized owning Factory UID." }, "suite_uid": { "type": "string", "description": "verified frozen suite UID." }, "run_uid": { "type": "string", "description": "containing benchmark Run UID." }, "state": { "$ref": "#/components/schemas/BenchmarkRunState", "description": "Run lifecycle captured with the calculated sections." }, "as_of": { "type": "string", "format": "date-time", "description": "calculation time for the agreed on-request summary; not a source snapshot or provider-final time." }, "provisional": { "type": "boolean", "description": "true for pending/running/scoring Runs whose values can still change." }, "incomplete_reason": { "type": "string", "nullable": true, "description": "existing safe failed/cancelled partial-results explanation; null in other states." }, "coverage": { "$ref": "#/components/schemas/BenchmarkResultsCoverage", "description": "count-only execution/scoring evidence coverage, separate from raw progress." }, "compute_credits": { "type": "string", "description": "existing selected execution compute-credit total from RunMetrics." }, "platform_credits": { "type": "string", "description": "existing selected execution platform-credit total from RunMetrics." }, "spend": { "allOf": [ { "$ref": "#/components/schemas/BenchmarkSpend" } ], "nullable": true, "description": "selected-dataset retry/judge totals; null before any selected Trial dispatch." }, "elapsed_s": { "type": "number", "format": "double", "nullable": true, "description": "Run span from start through completion/calculation time, including scoring; null before start or if start is unknown." }, "task_count": { "type": "integer", "description": "distinct selected frozen tasks, independent of display projections and Trial pages." }, "scorer_count": { "type": "integer", "nullable": true, "description": "count of resolved scorer descriptors, as in current history statistics; null before any selected Trial dispatch." }, "narrative": { "$ref": "#/components/schemas/BenchmarkNarrative", "description": "independent stored-narrative availability and eligible text." } } }, "BenchmarkResultsCoverage": { "type": "object", "required": [ "execution", "scoring" ], "properties": { "execution": { "$ref": "#/components/schemas/BenchmarkExecutionCoverage", "description": "planned versus observed logical Trial rows." }, "scoring": { "$ref": "#/components/schemas/BenchmarkScoringCoverage", "description": "effective retained bound scores versus expected scoring work." } } }, "BenchmarkExecutionCoverage": { "type": "object", "required": [ "planned_trial_count", "materialized_trial_count" ], "properties": { "planned_trial_count": { "type": "integer", "description": "selected frozen matrix size, equal to `execution.planned_total`." }, "materialized_trial_count": { "type": "integer", "description": "observed selected logical Trial rows, equal to `execution.total`." } } }, "BenchmarkScoringCoverage": { "type": "object", "required": [ "effective_scored_pair_count", "expected_pair_count" ], "properties": { "effective_scored_pair_count": { "type": "integer", "description": "pairs whose exact bound score resolves under retention/access and at/before cutoff." }, "expected_pair_count": { "type": "integer", "nullable": true, "description": "materialized `pending + judging + scored + finished_unscored`; excludes awaiting-trial/not-scoreable and is null before membership is known." } } }, "BenchmarkNarrative": { "type": "object", "required": [ "availability", "text" ], "properties": { "availability": { "type": "string", "enum": [ "pending", "available", "unavailable" ], "description": "current stored generation/lifecycle gate, not metric completeness." }, "text": { "type": "string", "nullable": true, "description": "nonempty retained narrative only when available; null otherwise." } } }, "BenchmarkResults": { "type": "object", "required": [ "factory_uid", "suite_uid", "run_uid", "state", "as_of", "provisional", "incomplete_reason", "coverage", "compute_credits", "platform_credits", "spend", "elapsed_s", "task_count", "scorer_count", "narrative", "execution", "scoring" ], "properties": { "factory_uid": { "type": "string", "description": "authorized owning Factory UID." }, "suite_uid": { "type": "string", "description": "verified frozen suite UID." }, "run_uid": { "type": "string", "description": "containing benchmark Run UID." }, "state": { "$ref": "#/components/schemas/BenchmarkRunState", "description": "Run lifecycle captured with the calculated sections." }, "as_of": { "type": "string", "format": "date-time", "description": "calculation time for the agreed on-request summary; not a source snapshot or provider-final time." }, "provisional": { "type": "boolean", "description": "true for pending/running/scoring Runs whose values can still change." }, "incomplete_reason": { "type": "string", "nullable": true, "description": "existing safe failed/cancelled partial-results explanation; null in other states." }, "coverage": { "$ref": "#/components/schemas/BenchmarkResultsCoverage", "description": "count-only execution/scoring evidence coverage, separate from raw progress." }, "compute_credits": { "type": "string", "description": "existing selected execution compute-credit total from RunMetrics." }, "platform_credits": { "type": "string", "description": "existing selected execution platform-credit total from RunMetrics." }, "spend": { "allOf": [ { "$ref": "#/components/schemas/BenchmarkSpend" } ], "nullable": true, "description": "selected-dataset retry/judge totals; null before any selected Trial dispatch." }, "elapsed_s": { "type": "number", "format": "double", "nullable": true, "description": "Run span from start through completion/calculation time, including scoring; null before start or if start is unknown." }, "task_count": { "type": "integer", "description": "distinct selected frozen tasks, independent of display projections and Trial pages." }, "scorer_count": { "type": "integer", "nullable": true, "description": "count of resolved scorer descriptors, as in current history statistics; null before any selected Trial dispatch." }, "narrative": { "$ref": "#/components/schemas/BenchmarkNarrative", "description": "independent stored-narrative availability and eligible text." }, "execution": { "$ref": "#/components/schemas/BenchmarkExecutionProgress", "description": "selected-dataset logical Trial counts and frozen plan size." }, "scoring": { "$ref": "#/components/schemas/BenchmarkRunScoring", "description": "selected-dataset raw ledger/judging counts; display projection does not narrow them." }, "configuration_metrics": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkConfigurationAggregate" }, "description": "present only for its include; complete selected configuration totals/averages/Overall rows." }, "scorer_configuration_metrics": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkScorerConfigurationAggregate" }, "description": "present only for its include; complete scorer/configuration evidence and comparison rows." }, "task_scorer_configuration_metrics": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkTaskScorerConfigurationAggregate" }, "description": "present only for its include; complete task/configuration/scorer cells across repetitions." }, "agent_metrics": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkAgentMetricAggregate" }, "description": "present only for its include; complete existing available per-configuration named-agent rows." } } }, "BenchmarkConfigurationAggregate": { "type": "object", "required": [ "configuration_uid", "execution", "metrics", "scoring", "retried_trial_count", "retry_count", "overall_mean" ], "properties": { "configuration_uid": { "type": "string", "description": "stable Run-local public configuration identity; labels/settings remain in Run.details." }, "execution": { "$ref": "#/components/schemas/BenchmarkExecutionProgress", "description": "logical Trial execution counts for this configuration in the selected dataset." }, "metrics": { "$ref": "#/components/schemas/BenchmarkConfigurationMetrics", "description": "existing retry totals and final-successful-attempt averages." }, "scoring": { "$ref": "#/components/schemas/BenchmarkOutcomeCounts", "description": "existing pass/fail counts and rate over retained applicable scores." }, "retried_trial_count": { "type": "integer", "description": "logical Trials with more than one execution attempt." }, "retry_count": { "type": "integer", "description": "sum of each logical Trial's `max(attempt_count-1,0)`." }, "overall_mean": { "type": "number", "format": "double", "nullable": true, "description": "unweighted mean of available comparable scorer means, null when none exists." } } }, "BenchmarkConfigurationMetrics": { "type": "object", "required": [ "compute_credits", "platform_credits", "inference_credits", "total_credits", "cost_usd", "avg_total_credits_per_trial", "avg_total_credits_per_task", "avg_wall_time_s", "avg_cost_usd_per_trial" ], "properties": { "compute_credits": { "type": "string", "description": "retry-inclusive execution compute-credit total." }, "platform_credits": { "type": "string", "description": "retry-inclusive execution platform-credit total." }, "inference_credits": { "type": "string", "description": "retry-inclusive execution inference-credit total." }, "total_credits": { "type": "string", "description": "sum of the three execution credit components." }, "cost_usd": { "type": "number", "format": "double", "description": "retry-inclusive execution dollar total under existing mixed-cost arithmetic." }, "avg_total_credits_per_trial": { "type": "string", "description": "credits averaged over final successful attempts, with existing decimal rounding." }, "avg_total_credits_per_task": { "type": "string", "description": "final-successful-attempt credits divided by distinct succeeded tasks, with existing rounding." }, "avg_wall_time_s": { "type": "number", "format": "double", "description": "final successful attempt working-duration average, not retry-chain duration average." }, "avg_cost_usd_per_trial": { "type": "number", "format": "double", "description": "final successful attempt cost average, not retry-chain cost average." }, "avg_output_tokens": { "type": "number", "format": "double", "description": "average of available retained per-Trial reported token values; omitted if none reports the field." }, "avg_tool_calls": { "type": "number", "format": "double", "description": "average of available retained per-Trial reported tool values; omitted if none reports the field." } } }, "BenchmarkScorerConfigurationAggregate": { "type": "object", "required": [ "scorer_uid", "configuration_uid", "scored", "pending", "failed", "unscored", "no_result", "outcomes", "labels", "mean", "expected_task_count", "scored_task_count", "comparable" ], "properties": { "scorer_uid": { "type": "string", "description": "resolved canonical scorer identity." }, "configuration_uid": { "type": "string", "description": "configuration coordinate for this aggregate." }, "scored": { "type": "integer", "description": "existing retained bound-score count for this scorer/configuration." }, "pending": { "type": "integer", "description": "existing awaiting-trial/pending/judging pair count." }, "failed": { "type": "integer", "description": "existing not-scoreable execution-failure count." }, "unscored": { "type": "integer", "description": "existing finished-unscored or unresolved/post-cutoff scored pair count." }, "no_result": { "type": "string", "nullable": true, "description": "existing safe no-scored-trials explanation." }, "outcomes": { "$ref": "#/components/schemas/BenchmarkOutcomeCounts", "description": "existing pass/fail counts and rate for retained bound scores." }, "labels": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkLabelCount" }, "description": "complete retained classification-label distribution, including known unseen labels at zero." }, "mean": { "type": "number", "format": "double", "nullable": true, "description": "unweighted counted task-cell mean for this scorer/configuration; null when no cell contributes." }, "expected_task_count": { "type": "integer", "description": "existing `applies_to_tasks` selected-dataset ledger task count across configurations, before comparison neutralization." }, "scored_task_count": { "type": "integer", "description": "distinct selected tasks with a bound score here, capped at expected_task_count, as in the chart coverage warning." }, "comparable": { "type": "boolean", "description": "true if some configuration has a scored succeeded Trial for this scorer in the selected dataset." } } }, "BenchmarkOutcomeCounts": { "type": "object", "required": [ "pass", "fail", "pass_rate" ], "properties": { "pass": { "type": "integer", "description": "retained bound scores whose current-threshold outcome is pass." }, "fail": { "type": "integer", "description": "retained bound scores whose current-threshold outcome is fail." }, "pass_rate": { "type": "number", "format": "double", "nullable": true, "description": "`pass/(pass+fail)`, null when that denominator is zero; not a scoring-coverage rate." } } }, "BenchmarkLabelCount": { "type": "object", "required": [ "label", "count" ], "properties": { "label": { "type": "string", "description": "retained classification label value." }, "count": { "type": "integer", "description": "bound scores with this label in the aggregate, including real zero counts for known labels." } } }, "BenchmarkTaskScorerConfigurationAggregate": { "type": "object", "required": [ "task_uid", "task_title", "configuration_uid", "scorer_uid", "expected_repetition_count", "scored_repetition_count", "mean", "task_overall_mean" ], "properties": { "task_uid": { "type": "string", "description": "frozen/derived legacy task coordinate." }, "task_title": { "type": "string", "nullable": true, "description": "retained frozen title for row display." }, "configuration_uid": { "type": "string", "description": "configuration coordinate." }, "scorer_uid": { "type": "string", "description": "resolved canonical scorer coordinate." }, "expected_repetition_count": { "type": "integer", "description": "logical Trial repetitions in this cell under existing comparison arithmetic, including execution failures." }, "scored_repetition_count": { "type": "integer", "description": "succeeded repetitions with permitted retained bound numeric scores." }, "mean": { "type": "number", "format": "double", "nullable": true, "description": "average of those scored repetitions; null when none contributes, never fabricated zero." }, "task_overall_mean": { "type": "number", "format": "double", "nullable": true, "description": "mean of available comparable scorer means for this task/configuration, before scorer display projection." } } }, "BenchmarkAgentMetricAggregate": { "type": "object", "required": [ "agent_uid", "agent_name", "cost_usd", "configuration_uid" ], "properties": { "agent_uid": { "type": "string", "description": "existing named-agent identity; the empty string retains the Unknown-agent fallback." }, "agent_name": { "type": "string", "description": "existing resolved label, including `\"Unknown agent\"` when identity is unavailable." }, "cost_usd": { "type": "number", "format": "double", "description": "existing exclusive named-agent cost summed across retained retries and non-system descendants." }, "sandbox_time_s": { "type": "number", "format": "double", "description": "existing summed claim-to-completion seconds, omitted when any contributing duration is unknown; measured zero is present." }, "configuration_uid": { "type": "string", "description": "containing configuration for the existing summed named-agent breakdown." }, "cost_breakdown": { "$ref": "#/components/schemas/BenchmarkAgentCostBreakdown", "description": "Retained exclusive costs and public-model attribution, omitted when the existing loader gate or availability suppresses it." } } }, "BenchmarkExecutionState": { "type": "string", "enum": [ "QUEUED", "PENDING", "CLAIMED", "INPROGRESS", "SUCCEEDED", "FAILED", "ERROR", "BLOCKED", "CANCELLED" ] }, "BenchmarkTrialScoringState": { "type": "string", "enum": [ "awaiting_trial", "pending", "judging", "scored", "finished_unscored", "not_scoreable" ] }, "BenchmarkViolation": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Machine-readable violation code" }, "message": { "type": "string", "description": "Human-readable explanation" } } }, "BenchmarkLaunchViolationError": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "violations": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkViolation" } } } } ] }, "ListBenchmarkSuitesResponse": { "type": "object", "required": [ "data", "page_info" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkSuite" } }, "page_info": { "$ref": "#/components/schemas/BenchmarkPageInfo" } } } } } }