{ "openapi": "3.0.0", "info": { "title": "Warp Agent API", "version": "1.0.0", "description": "API for creating, managing, and querying Warp cloud agent runs.\n\nThese endpoints allow users to programmatically spawn agents, list runs, \nand retrieve detailed 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" } ], "paths": { "/factory": { "get": { "summary": "List factories", "description": "List factories accessible to the authenticated principal. An optional\nteam_uid query parameter restricts results to a single team, and an\noptional search query parameter filters by a case-insensitive\nsubstring match on the factory name or alias.\n", "operationId": "listFactories", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "team_uid", "in": "query", "description": "Optional team UID to filter factories by ownership.", "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 public 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/{uid}/runs": { "post": { "summary": "Dispatch a run to a factory", "description": "Dispatch a run to a factory by its UID, 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" } } } } } } }, "/agent": { "get": { "summary": "List available agents", "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", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "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": [] } ], "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/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": [] } ], "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": [] } ], "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": [ { "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": "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", "required": false, "schema": { "$ref": "#/components/schemas/RunSourceType" } }, { "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": "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]=VIS-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": "Fuzzy search query 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 artifact\nwith the given URL. The URL is matched against the canonical locator stored\nwhen the artifact was reported via POST /harness-support/report-artifact\nwith artifact_type EXTERNAL_REFERENCE. Returns 404 when no matching run\nexists or when the caller lacks access, to avoid leaking run existence.\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.\nThe response groups text, tool activity, and event content into\nstructured 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 (self-hosted, 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(error_code: invalid_request)\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 (error_code: conflict, retryable: true).\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., self-hosted, local, or GitHub Action runs)\n(error_code: operation_not_supported)\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). A 200 response means the follow-up\nwas accepted; updated run state can be observed via\n`GET /agent/runs/{runId}`.\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": { "type": "object" } } } }, "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; 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" } } } }, "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/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": [] } ], "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": [] } ], "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": [ { "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/scorers/{scorer_id}": { "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_id", "in": "path", "description": "The scorer identifier", "required": true, "schema": { "type": "integer" } } ], "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_id", "in": "path", "description": "The scorer identifier", "required": true, "schema": { "type": "integer" } } ], "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/identities": { "post": { "summary": "Create an agent", "description": "Create a new agent for the caller's team.\nAgents can be used as the execution principal for team-owned runs.\n", "operationId": "createAgent", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "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 for the caller's team. Each agent includes\nan `available` flag indicating whether it is within the team's plan limit\nand may be used for runs.\n", "operationId": "listAgents", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [], "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/scorers": { "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, so\na failure leaves neither behind.\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 owned by the caller's team, including scope agents\nand aggregate scoring stats. Pass factory_uid to narrow the result to a\nsingle factory.\n", "operationId": "listScorers", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Scorers for the caller's team", "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" } } } }, "403": { "description": "Only human users can list scorers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory/scorers/{scorer_id}/results": { "get": { "summary": "List recent results for an 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.\n", "operationId": "listScorerResults", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "scorer_id", "in": "path", "description": "The scorer identifier", "required": true, "schema": { "type": "integer" } }, { "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" } } ], "responses": { "200": { "description": "Recent results for the scorer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListScorerResultsResponse" } } } }, "400": { "description": "Invalid scorer ID, limit, or cursor", "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/scorers/{scorer_id}/results/reasons": { "get": { "summary": "Read judge reasons for a page of scorer results", "description": "Read the judge's reasoning for the given runs in one request, so a page\nof results can show reasons alongside classifications. Reasons are\nstored outside the database and read per run with bounded concurrency;\na run whose reason is missing or unreadable is reported individually so\none unavailable reason never fails the request.\n", "operationId": "listScorerResultReasons", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "scorer_id", "in": "path", "description": "The scorer identifier", "required": true, "schema": { "type": "integer" } }, { "name": "run_id", "in": "query", "description": "Runs to read reasons for. Repeat the parameter once per run; at\nmost 100 distinct runs (the results page maximum) per request.\n", "required": true, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "One entry per requested run, in request order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListScorerResultReasonsResponse" } } } }, "400": { "description": "Invalid scorer ID, missing run_id, or too many runs", "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/scorers/{scorer_id}/metrics/pass-rate": { "get": { "summary": "Get a scorer's pass-rate metric over a date range", "description": "Returns a period-aligned pass-rate series plus a full-range aggregate\nfor the scorer's dashboard chart, computed directly from every live\nscore in [start_date, end_date) rather than the capped,\nunfiltered recent-attempts list /results returns. The headline\npass_rate and the series describe the same window and denominator, so\nthey cannot disagree. Binning follows the same day/week/month rules\nand 365-period cap as GET /factory/{uid}/metrics.\n", "operationId": "getScorerPassRateSeries", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "scorer_id", "in": "path", "description": "The scorer identifier", "required": true, "schema": { "type": "integer" } }, { "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" } } ], "responses": { "200": { "description": "The scorer's pass-rate series and range aggregate", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScorerPassRateSeriesResponse" } } } }, "400": { "description": "Invalid scorer ID, date range, or group_by_period", "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/scorers/{scorer_id}/self-improvement-config": { "get": { "summary": "Get a scorer's self-improvement config", "description": "Retrieve the self-improvement configuration for a scorer: whether self-improvement is\nenabled for it.\n", "operationId": "getScorerSelfImprovementConfig", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "scorer_id", "in": "path", "description": "The scorer identifier", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "The scorer's self-improvement config", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelfImprovementConfigResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "404": { "description": "Scorer not found or self-improvement not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "summary": "Enable self-improvement for a scorer", "description": "Turn self-improvement on for a scorer, marking its config active. Self-improvement acts\non runs the scorer itself already scores as failing (scored label's\nscore below the scorer's threshold); this endpoint carries no\nclassification data of its own.\n", "operationId": "updateScorerSelfImprovementConfig", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "scorer_id", "in": "path", "description": "The scorer identifier", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "The updated self-improvement config", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelfImprovementConfigResponse" } } } }, "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" } } } } } }, "delete": { "summary": "Disable self-improvement for a scorer", "description": "Turn self-improvement off for a scorer by removing its config.", "operationId": "deleteScorerSelfImprovementConfig", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "scorer_id", "in": "path", "description": "The scorer identifier", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Self-improvement config deleted" }, "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/run-scoring/dispatches": { "post": { "summary": "Manually dispatch scoring for one or more runs", "description": "Immediately dispatch judge runs for the named (run, scorer) pairs,\nbypassing the two-hour idle cool-down, automatic sampling, and the\nscorer-created-after-run gate, since the caller selected the exact\nrun — even a 0% sampling rate still accepts a manual dispatch. The\nfull target set is validated before dispatch begins, and each pair's\noutcome (dispatched, already in flight, or failed) is reported\nindependently.\n", "operationId": "dispatchManualScoring", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualScoringDispatchRequest" } } } }, "responses": { "202": { "description": "The request was validated; judge evaluation continues\nasynchronously. Individual pairs may still report a\nfailed_to_dispatch outcome.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualScoringDispatchResponse" } } } }, "400": { "description": "Malformed request, non-named-agent run, judge\nrun, wrong factory, wrong agent scope, or more than 100 pairs\n", "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. Requires\nonly 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/runs/{runId}/scores": { "post": { "summary": "Report evaluation scores for a run", "description": "Report one or more evaluation verdicts for a run, called by the judge\nrun dispatched to score it and authenticated with that judge run's\nAPI key. Each verdict is processed independently — the response\nreports per-verdict acceptance, and a rejected verdict does not block\nthe others — so reporting a subset of the run's evaluations is valid.\n", "operationId": "reportRunScores", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "runId", "in": "path", "description": "The run being scored", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportRunScoresRequest" } } } }, "responses": { "200": { "description": "Every reported verdict was accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportRunScoresResponse" } } } }, "206": { "description": "The request was well-formed but at least one verdict was rejected; inspect each result's status and error before deciding whether to resubmit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportRunScoresResponse" } } } }, "400": { "description": "Malformed request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "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/identities/{uid}": { "get": { "summary": "Retrieve an agent", "description": "Retrieve a single agent by its unique identifier.\nThe response includes an `available` flag indicating whether the agent\nis within the team's plan limit and may be used for runs.\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" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Authentication via a Warp API key.\n" } }, "responses": { "FactoryAccessDenied": { "description": "Factory access is not enabled for the authenticated principal", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Factory": { "type": "object", "description": "Public representation of a factory.", "required": [ "uid", "team_uid", "name", "description", "alias", "avatar_url", "code_forge", "repositories", "default_environment", "default_model", "scoring", "credential_strategy", "integrations", "agent_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" }, "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" }, "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" }, "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" } } }, "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" } } }, "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", "slack" ] }, "FactoryCodeForge": { "type": "string", "description": "Source-control provider hosting the factory's repositories. NONE\ndeclares a repo-less factory with no native repositories; its\nenvironment relies on setup_commands to clone from any host instead.\n", "enum": [ "GITHUB", "GITLAB", "NONE" ] }, "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." } } }, "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" ] }, "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" } } }, "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" ], "properties": { "runs": { "type": "array", "items": { "$ref": "#/components/schemas/RunItem" } }, "page_info": { "$ref": "#/components/schemas/PageInfo" } } }, "RunItem": { "type": "object", "required": [ "run_id", "task_id", "title", "state", "prompt", "created_at", "updated_at" ], "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" }, "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)" }, "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" }, "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" }, "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" }, "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." } } }, "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" ] }, "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/PullRequestArtifactData" } } }, "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" } } }, "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" } } }, "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\ndebugging; only present while that window is open. The window\nis an idle window owned by the agent process: activity in the\nsession pushes this deadline out. The agent republishes it\nperiodically rather than on every keystroke, so the value can\nlag the true deadline by up to a throttle interval, always in\nthe conservative direction.\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": "inference_cost in US dollars, converted at the owning team's\ncurrent credit price. An approximate cost, not a billed amount.\n" }, "compute_cost_usd": { "type": "number", "format": "double", "description": "compute_cost in US dollars, converted at the owning team's\ncurrent credit price. An approximate cost, not a billed amount.\n" }, "platform_cost_usd": { "type": "number", "format": "double", "description": "platform_cost in US dollars, converted at the owning team's\ncurrent credit price. An approximate cost, not a billed amount.\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" }, "inference_cost_breakdown_usd": { "$ref": "#/components/schemas/InferenceCostBreakdownUsd" }, "usage_by_category": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ChargedUsageDetail" }, "description": "Full-granularity token and dollar-cost breakdown for the run's\nconversation, keyed by usage category (for example,\nprimary_agent or conversation_compaction) and model id; differs\nfrom total_tokens/inference_cost_breakdown_usd, which combine\nusage across all categories and models. Omitted when the data\nis not available.\n" } } }, "InferenceCostBreakdownUsd": { "type": "object", "description": "Charged dollar cost of LLM inference, split by token type.\nOmitted when the data is not available.\n", "required": [ "input_cost_usd", "input_cache_read_cost_usd", "input_cache_write_cost_usd", "output_cost_usd" ], "properties": { "input_cost_usd": { "type": "number", "format": "double", "description": "Cost of non-cached input tokens, in US dollars." }, "input_cache_read_cost_usd": { "type": "number", "format": "double", "description": "Cost of cache-read input tokens, in US dollars." }, "input_cache_write_cost_usd": { "type": "number", "format": "double", "description": "Cost of cache-write input tokens, in US dollars." }, "output_cost_usd": { "type": "number", "format": "double", "description": "Cost of output tokens, in US dollars." } } }, "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 dollar-cost detail inference usage.\nThe counts and cost describe the same usage (e.g. token_count.input\ntokens cost cost_usd.input_cost_usd in total).\n", "required": [ "token_count", "cost_usd", "web_search_count", "web_search_cost_usd" ], "properties": { "token_count": { "$ref": "#/components/schemas/TokenCountBreakdown" }, "cost_usd": { "$ref": "#/components/schemas/InferenceCostBreakdownUsd" }, "web_search_count": { "type": "integer", "format": "int64", "description": "Number of web searches performed by this model." }, "web_search_cost_usd": { "type": "number", "format": "double", "description": "Total cost of those web searches, in US dollars." } } }, "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_usd" ], "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_usd": { "type": "number", "format": "double", "description": "Platform usage charged for this category, in US dollars." } } }, "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", "SLACK", "LOCAL", "SCHEDULED_AGENT", "WEB_APP", "GITHUB_ACTION", "CLOUD_MODE", "CLI", "JIRA", "SELF_IMPROVEMENT", "GITHUB_WEBHOOK", "GITLAB_WEBHOOK", "AUTOFIX", "RUN_SCORER", "ORCHESTRATION" ], "description": "Source that created the run:\n- LINEAR: Created from Linear integration\n- API: Created via the Warp API\n- SLACK: Created from Slack 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- 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" }, "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" }, "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": 1, "maximum": 60, "description": "Number of minutes to keep the agent environment alive 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.\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).\nFormat: `https://docs.warp.dev/reference/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)" }, "data": { "$ref": "#/components/schemas/ScreenshotArtifactResponseData" } } }, "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)" }, "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" }, "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- `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", "internal_error" ] }, "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." }, "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`.\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" } } }, "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": [ "factory_uid", "name", "scoring_prompt", "allowed_classifications", "threshold", "scope_mode", "model_id" ], "properties": { "factory_uid": { "type": "string", "minLength": 1, "description": "UID of the factory that owns the scorer" }, "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 only agent_uids" }, "agent_uids": { "type": "array", "description": "Required and non-empty for selected_agents; must be empty for all_agents", "items": { "type": "string" } }, "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, instead of a separate call to\nPUT /factory/scorers/{scorer_id}/self-improvement-config\nafterward; defaults to false. The response does not echo this\nback — a successful (2xx) response means the requested state was\napplied, confirmable at any time with GET .../self-improvement-config.\nSetting this to true requires a human user principal, matching\nthe restriction on the PUT endpoint; a service-account principal\ngets the same error as calling that endpoint directly.\n" } } }, "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": { "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 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.\n", "items": { "type": "string" } }, "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" } } }, "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": [ "id", "factory_uid", "name", "description", "scoring_prompt", "allowed_classifications", "threshold", "scorer_kind", "version", "scope_mode", "agent_uids", "sampling_rate", "model_id", "created_at", "updated_at" ], "properties": { "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" }, "version": { "type": "integer", "description": "Scorer definition version" }, "scope_mode": { "type": "string", "enum": [ "all_agents", "selected_agents" ], "description": "Whether the scorer applies to every factory agent or selected agent_uids" }, "agent_uids": { "type": "array", "description": "Agents attached to a selected_agents scorer; empty for all_agents", "items": { "type": "string" } }, "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" }, "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" ], "properties": { "uid": { "type": "string", "description": "Unique identifier of the agent" }, "name": { "type": "string", "description": "Display name of the agent" } } }, "ScorerListItem": { "type": "object", "required": [ "id", "factory_uid", "name", "description", "scoring_prompt", "allowed_classifications", "threshold", "scope_mode", "agents", "scorer_kind", "version", "sampling_rate", "created_at", "updated_at", "result_count", "model_id", "pass_rate_summary", "self_improvement_enabled" ], "properties": { "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", "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" }, "version": { "type": "integer", "description": "Scorer definition version" }, "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" }, "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" }, "pass_rate_summary": { "$ref": "#/components/schemas/ScorerPassRateSummary" }, "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" }, "ScorerPassRateSummary": { "type": "object", "required": [ "pass_count", "fail_count", "recent_outcomes" ], "properties": { "pass_count": { "type": "integer", "description": "Number of live scores whose derived outcome is pass, within the\nsame recent_outcomes_limit window as recent_outcomes (not the\nscorer's all-time history).\n" }, "fail_count": { "type": "integer", "description": "Number of live scores whose derived outcome is fail, within the\nsame recent_outcomes_limit window as recent_outcomes (not the\nscorer's all-time history).\n" }, "pass_rate": { "type": "number", "format": "double", "nullable": true, "description": "pass_count / (pass_count + fail_count), over the same recent\nwindow as pass_count and fail_count. Null when there are no\nscoreable (pass or fail) scores in that window. Clients must not\nuse result_count as the denominator.\n" }, "recent_outcomes": { "type": "array", "items": { "$ref": "#/components/schemas/ScorerOutcome" }, "description": "The scorer's most recent live scores' outcomes, oldest first,\nfor a compact history strip; length is bounded by\nrecent_outcomes_limit, and failed attempts (no live score) are\nnot included. pass_count and fail_count are computed over this\nexact same windowed set, so the headline rate and the strip\nalways describe the same scores.\n" } } }, "ScorerResultStatus": { "type": "string", "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" }, "ScorerResult": { "type": "object", "required": [ "run_id", "status", "attempted_at", "is_in_flight" ], "properties": { "run_id": { "type": "string", "description": "The scored agent run" }, "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" }, "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": { "allOf": [ { "$ref": "#/components/schemas/ScorerOutcome" } ], "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" } } }, "ScorerPassRateSeriesResponse": { "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 } } } }, "ManualScoringTarget": { "type": "object", "required": [ "run_id", "scorer_ids" ], "properties": { "run_id": { "type": "string", "description": "The run to score" }, "scorer_ids": { "type": "array", "minItems": 1, "items": { "type": "integer" }, "description": "Scorer IDs to invoke against run_id" } } }, "ManualScoringDispatchRequest": { "type": "object", "required": [ "targets" ], "properties": { "targets": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/ManualScoringTarget" }, "description": "One or more (run, scorer) targets, expressed as one entry per run\nwith its scorer IDs. Duplicate (run_id, scorer_id) pairs across\nentries are collapsed. At most 100 unique pairs total.\n" } } }, "ManualScoringDispatchStatus": { "type": "string", "enum": [ "dispatched", "already_in_flight", "failed_no_transcript", "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), or \"failed_to_dispatch\" (an\noperational error occurred after validation passed; retryable).\n" }, "ManualScoringDispatchResult": { "type": "object", "required": [ "run_id", "scorer_id", "status" ], "properties": { "run_id": { "type": "string", "description": "The scored agent run" }, "scorer_id": { "type": "integer", "description": "The invoked scorer" }, "status": { "$ref": "#/components/schemas/ManualScoringDispatchStatus" }, "scoring_run_id": { "type": "string", "nullable": true, "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 the periodic job or a manual dispatch request" }, "RunScoreItem": { "type": "object", "required": [ "scorer_id", "scorer_name", "attempt_status", "is_in_flight", "trigger_source", "attempted_at" ], "properties": { "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" } } }, "ScorerResultReason": { "type": "object", "required": [ "run_id", "status" ], "properties": { "run_id": { "type": "string", "description": "The run this reason belongs to" }, "status": { "type": "string", "enum": [ "available", "absent", "unavailable" ], "description": "Availability of the run's judge reason: \"available\" when the reason\nwas read, \"absent\" when the judge recorded none, and \"unavailable\"\nwhen a recorded reason could not be read back.\n" }, "reason": { "type": "string", "nullable": true, "description": "The judge's reasoning, truncated beyond 8KB when it was recorded;\nabsent unless status is \"available\".\n" } } }, "ListScorerResultReasonsResponse": { "type": "object", "required": [ "reasons" ], "properties": { "reasons": { "type": "array", "items": { "$ref": "#/components/schemas/ScorerResultReason" } } } }, "SelfImprovementConfigResponse": { "type": "object", "required": [ "scorer_id", "status", "created_at", "updated_at" ], "properties": { "scorer_id": { "type": "integer", "description": "Identifier of the scorer this self-improvement config belongs to" }, "status": { "type": "string", "enum": [ "active", "paused" ], "description": "Self-improvement config lifecycle status (active means self-improvement is enabled)" }, "created_at": { "type": "string", "format": "date-time", "description": "When the self-improvement config was created" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the self-improvement config was last updated" } } }, "ReportedRunScore": { "type": "object", "required": [ "scorer_id" ], "properties": { "scorer_id": { "type": "integer", "description": "The evaluation this verdict belongs to" }, "classification": { "type": "string", "description": "The chosen classification. Must exactly match one of the allowed\nlabel values captured when the evaluation was dispatched. Ignored\nwhen `failed` is true.\n" }, "reason": { "type": "string", "description": "Optional judge reasoning. Stored outside the database and truncated\nbeyond 8KB; a storage failure does not reject the verdict.\n" }, "failed": { "type": "boolean", "description": "True when the judge could not evaluate this evaluation. Failed\nverdicts are accepted but record no score.\n" } } }, "ReportRunScoresRequest": { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/ReportedRunScore" } } } }, "ReportedRunScoreOutcome": { "type": "object", "required": [ "scorer_id", "status" ], "properties": { "scorer_id": { "type": "integer", "description": "The evaluation this outcome belongs to" }, "status": { "type": "string", "description": "Whether the verdict was recorded: \"accepted\" or \"rejected\"" }, "error": { "type": "string", "description": "Why the verdict was rejected; absent when accepted" } } }, "ReportRunScoresResponse": { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/ReportedRunScoreOutcome" } } } }, "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", "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" }, "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" } } } } } }