{ "openapi": "3.0.0", "info": { "title": "Warp Platform API", "version": "1.0.0", "description": "API for creating, managing, and querying factory and cloud agent runs.\n\nThese endpoints allow users to send work to factories, start standalone agents, list runs, and 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": { "/networking/egress-ranges": { "get": { "summary": "List Warp-hosted agent egress ranges", "description": "Return the canonical IP network ranges used by outbound requests from\nWarp-hosted agents.\n", "operationId": "getEgressRanges", "tags": [ "networking" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/TeamUidHeaderParam" } ], "responses": { "200": { "description": "Current Warp-hosted agent egress ranges", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EgressRangesResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory": { "get": { "summary": "List factories", "description": "List factories accessible to the authenticated principal, restricted\nto the request's active team when one is set. An optional team_uid\nquery parameter overrides the active team and restricts results to a\nsingle team, and an optional search query parameter filters by a\ncase-insensitive substring match on the factory name or alias.\n", "operationId": "listFactories", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/TeamUidHeaderParam" }, { "name": "team_uid", "in": "query", "description": "Optional team UID to filter factories by ownership. Takes\nprecedence over the X-Warp-Team-Uid header.\n", "required": false, "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Case-insensitive substring search over the factory name and\nalias.\n", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of factories to return (default 50, max 100).", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor returned by a previous list response.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of factories", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListFactoriesResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory/{uid}": { "get": { "summary": "Get a factory", "description": "Get a factory by its UID.", "operationId": "getFactory", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uid", "in": "path", "description": "The public UID of the factory.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Factory details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Factory" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "404": { "description": "Factory not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory/{uid}/tasks": { "post": { "summary": "Create a factory task", "description": "Create a task in a factory, bound to an existing agent conversation.\ntitle and conversation_id are required. The stage defaults to TRIAGE. The\nconversation's most recent run must be owned by the factory's team,\nand a conversation may be bound to at most one live task across all\nfactories.\n", "operationId": "createFactoryTask", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uid", "in": "path", "description": "The public UID of the factory.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactoryTaskCreateRequest" } } } }, "responses": { "201": { "description": "Factory task created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactoryTask" } } } }, "400": { "description": "Invalid request body or conversation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "404": { "description": "Factory not found or not accessible", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The conversation is already bound to a live task", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List factory tasks", "description": "List the factory's tasks with optional filtering and search. List\nresponses are lean by default; set full_list=true to include\ncanonical ticket metadata and derived outputs for the returned page.\n", "operationId": "listFactoryTasks", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uid", "in": "path", "description": "The public UID of the factory.", "required": true, "schema": { "type": "string" } }, { "name": "stage", "in": "query", "description": "Filter by task stage. Can be specified multiple times to match any\nof the given stages.\n", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FactoryTaskStage" } }, "style": "form", "explode": true }, { "name": "created_by", "in": "query", "description": "Filter to tasks whose seed run was started by any of these\nteammates, each given as their email address. Can be specified\nmultiple times to match any of the given teammates.\n", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "q", "in": "query", "description": "Case-insensitive substring search over the task title.", "required": false, "schema": { "type": "string" } }, { "name": "created_after", "in": "query", "description": "Filter to tasks created after this timestamp (RFC3339 format).", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "description": "Filter to tasks created before this timestamp (RFC3339 format).", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_after", "in": "query", "description": "Filter to tasks updated after this timestamp (RFC3339 format).", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "sort_by", "in": "query", "description": "Sort field for results.", "required": false, "schema": { "type": "string", "enum": [ "created_at", "updated_at" ], "default": "created_at" } }, { "name": "sort_order", "in": "query", "description": "Sort direction.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, { "name": "limit", "in": "query", "description": "Maximum number of tasks to return (default 50, max 100).", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor returned by a previous list response.\nValid only for the sort_by/sort_order it was issued under; omit\nto restart the listing.\n", "required": false, "schema": { "type": "string" } }, { "name": "full_list", "in": "query", "description": "Include canonical ticket_source and ticket_id metadata from each\ntask's bound run, plus its derived outputs. Defaults to false.\n", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "include_current_run", "in": "query", "description": "Include each task's current top-level run, resolved in one batch\nfor the returned page. Defaults to false.\n", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "List of factory tasks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListFactoryTasksResponse" } } } }, "400": { "description": "Invalid filter, sort, limit, cursor, full_list, or include_current_run value", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "404": { "description": "Factory not found or not accessible", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory/{uid}/runs": { "post": { "summary": "Dispatch a run to a factory", "description": "Dispatch a run to a factory, using prompt as the run's\nprompt and an optional title, ticket_ref, and ticket_url. Returns\nthe created run; its factory task is created asynchronously and can\nbe resolved afterwards with GET /factory/{uid}/task-by-run.\n", "operationId": "createFactoryRun", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uid", "in": "path", "description": "The public UID of the factory.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactoryRunRequest" } } } }, "responses": { "201": { "description": "Run dispatched successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactoryRunResponse" } } } }, "400": { "description": "Invalid request body or ticket_ref", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "404": { "description": "Factory not found or not accessible", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The factory has no foreman agent to receive work", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory/{uid}/tasks/{task_uid}": { "get": { "summary": "Get a factory task", "description": "Get a task with its derived outputs, newest-first.\n", "operationId": "getFactoryTask", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uid", "in": "path", "description": "The public UID of the factory.", "required": true, "schema": { "type": "string" } }, { "name": "task_uid", "in": "path", "description": "The public UID of the task.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Factory task details with derived outputs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactoryTask" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "404": { "description": "Factory or task not found under this factory", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update a factory task", "description": "Partially update a task's title, description, and/or stage. Last\nwrite wins. Stage writes are unrestricted: any stage-to-stage\ntransition is allowed, including moving backwards or to completion.\n", "operationId": "updateFactoryTask", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uid", "in": "path", "description": "The public UID of the factory.", "required": true, "schema": { "type": "string" } }, { "name": "task_uid", "in": "path", "description": "The public UID of the task.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactoryTaskPatchRequest" } } } }, "responses": { "200": { "description": "Factory task updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactoryTask" } } } }, "400": { "description": "Invalid request body", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "404": { "description": "Factory or task not found under this factory", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete a factory task", "description": "Soft-delete a task. The task disappears from list and get responses\nimmediately, and its conversation may be bound to a new task.\nDeleting a task never deletes artifacts or the conversation.\n", "operationId": "deleteFactoryTask", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uid", "in": "path", "description": "The public UID of the factory.", "required": true, "schema": { "type": "string" } }, { "name": "task_uid", "in": "path", "description": "The public UID of the task.", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Factory task deleted successfully" }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "404": { "description": "Factory or task not found under this factory", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory/{uid}/tasks/{task_uid}/cancel": { "post": { "summary": "Stop a factory task", "description": "Cancel the task's current top-level run and move the task to\nCANCELLED. Every non-terminal descendant of the root run is\ncancelled as well.\n", "operationId": "cancelFactoryTask", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uid", "in": "path", "description": "The public UID of the factory.", "required": true, "schema": { "type": "string" } }, { "name": "task_uid", "in": "path", "description": "The public UID of the task.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Task stopped. The response reflects the refreshed task, including\nits current run and stage.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactoryTask" } } } }, "400": { "description": "The resolved current run is already in a terminal state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The caller can see the task but lacks access to its resolved\ncurrent run.\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Factory or task not found under this factory, or the task has no\nresolvable current run.\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The resolved current run is PENDING and cannot be cancelled yet.\nRetry after a moment.\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The resolved current run's type does not support server-side cancellation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory/{uid}/task-by-conversation": { "get": { "summary": "Get a factory task by conversation", "description": "Get the factory task bound to an agent conversation. Conversation bindings are\nunique across factories, but the lookup is factory-scoped: a task\nowned by a different factory is 404.\n", "operationId": "getFactoryTaskByConversation", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uid", "in": "path", "description": "The public UID of the factory.", "required": true, "schema": { "type": "string" } }, { "name": "conversation_id", "in": "query", "description": "The agent conversation ID the task is bound to.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Factory task details with derived outputs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactoryTask" } } } }, "400": { "description": "Missing conversation_id", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "404": { "description": "Factory not accessible, or no live task bound to the conversation under this factory", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory/{uid}/task-by-run": { "get": { "summary": "Get a factory task by run", "description": "Get the factory task that owns a run: the task bound to the conversation\nof the run's root ancestor. The lookup is factory-scoped: a task owned by\na different factory is 404.\n", "operationId": "getFactoryTaskByRun", "tags": [ "factory" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uid", "in": "path", "description": "The public UID of the factory.", "required": true, "schema": { "type": "string" } }, { "name": "run_id", "in": "query", "description": "Any run ID in the task's run tree.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Factory task details with derived outputs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactoryTask" } } } }, "400": { "description": "Missing run_id", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/FactoryAccessDenied" }, "404": { "description": "Factory not accessible, the run does not resolve to a live task, or the task belongs to a different factory", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent": { "get": { "summary": "List available agent skills", "description": "Retrieve a list of available agents (skills) that can be used to run tasks.\nAgents are discovered from environments or a specific repository.\n", "operationId": "listAgents", "deprecated": true, "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/TeamUidHeaderParam" }, { "name": "repo", "in": "query", "description": "Optional repository specification to list agents from (format: \"owner/repo\").\nIf not provided, lists agents from all accessible environments.\n", "required": false, "schema": { "type": "string" } }, { "name": "refresh", "in": "query", "description": "When true, clears the agent list cache before fetching.\nUse this to force a refresh of the available agents.\n", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "sort_by", "in": "query", "description": "Sort order for the returned agents.\n- \"name\": Sort alphabetically by name (default)\n- \"last_run\": Sort by most recently used\n", "required": false, "schema": { "type": "string", "enum": [ "name", "last_run" ] } }, { "name": "include_malformed_skills", "in": "query", "description": "When true, includes skills whose SKILL.md file exists but is\nmalformed. These variants will have a non-empty `error` field\ndescribing the parse failure. Defaults to false.\n", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "List of available agents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAgentsResponse" } } } }, "400": { "description": "Invalid repository specification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/connected-self-hosted-workers": { "get": { "summary": "List connected self-hosted workers", "description": "Retrieve currently connected self-hosted workers for the authenticated principal's team.\nWorker presence is derived from worker websocket heartbeats and may be briefly stale.\n", "operationId": "listConnectedSelfHostedWorkers", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/TeamUidHeaderParam" } ], "responses": { "200": { "description": "List of currently connected self-hosted workers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListConnectedSelfHostedWorkersResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not authorized to list connected workers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/runs/{runId}/transcript": { "get": { "summary": "Get run transcript", "description": "Retrieve the raw conversation transcript for an agent run.\nReturns a 302 redirect to a time-limited download URL for the transcript.\n", "operationId": "getRunTranscript", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "runId", "in": "path", "description": "The unique identifier of the run", "required": true, "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to a download URL for the transcript", "headers": { "Location": { "description": "URL to download the transcript", "schema": { "type": "string", "format": "uri" } } } }, "400": { "description": "Missing run ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to access run transcript", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run not found or has no transcript", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/runs/{runId}/harness-usage": { "get": { "summary": "Get raw third-party harness usage", "description": "Return the latest cumulative raw usage snapshot retained for a\nClaude Code or Codex run. Missing metrics are represented as an\nunavailable result rather than zero. Access uses the same run view\nauthorization as transcript reads.\n", "operationId": "getRunHarnessUsage", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Raw harness usage or an unavailable result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetRunHarnessUsageResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to view the run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run not found or has no linked conversation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/run": { "post": { "summary": "Run an agent task", "description": "Spawn a cloud agent with a prompt and optional configuration.\nThe agent will be queued for execution and assigned a unique run ID.\n", "operationId": "runAgent", "deprecated": true, "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/TeamUidHeaderParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunAgentRequest" }, "examples": { "simple": { "summary": "Simple prompt", "value": { "prompt": "Fix the bug in auth.go" } }, "withConfig": { "summary": "With agent config", "value": { "prompt": "Refactor the database layer", "config": { "name": "my-agent", "model_id": "gpt-5-4-high", "base_prompt": "Focus on Go backend code" }, "title": "DB Refactoring Run" } } } } } }, "responses": { "200": { "description": "Run created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunAgentResponse" } } } }, "400": { "description": "Invalid request (missing prompt, invalid config)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to access referenced resources (environment, MCP servers)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/runs": { "post": { "summary": "Run a cloud agent", "description": "Spawn a cloud agent with a prompt and optional configuration.\nThe agent will be queued for execution and assigned a unique run ID.\n", "operationId": "createRun", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/TeamUidHeaderParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunAgentRequest" } } } }, "responses": { "200": { "description": "Run created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunAgentResponse" } } } }, "400": { "description": "Invalid request (missing prompt, invalid config)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to access referenced resources (environment, MCP servers)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List agent runs", "description": "Retrieve a paginated list of agent runs with optional filtering.\nResults default to `sort_by=updated_at` and `sort_order=desc`.\n", "operationId": "listRuns", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/TeamUidHeaderParam" }, { "name": "limit", "in": "query", "description": "Maximum number of runs to return", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 20 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor from previous response", "required": false, "schema": { "type": "string" } }, { "name": "sort_by", "in": "query", "description": "Sort field for results.\n- `updated_at`: Sort by last update timestamp (default)\n- `created_at`: Sort by creation timestamp\n- `title`: Sort alphabetically by run title\n- `agent`: Sort alphabetically by skill. Runs without a skill are grouped last.\n", "required": false, "schema": { "type": "string", "enum": [ "updated_at", "created_at", "title", "agent" ], "default": "updated_at" } }, { "name": "sort_order", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, { "name": "state", "in": "query", "description": "Filter by run state. Can be specified multiple times to match any of the given states.\n", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RunState" } }, "style": "form", "explode": true }, { "name": "task_status", "in": "query", "description": "Filter by high-level task status. Can be specified multiple times to match any value.\n`running` matches when the root or any descendant is queued, pending, claimed, or in progress.\n`failed`, `blocked`, `cancelled`, and `complete` match the root state only.\n", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "running", "failed", "blocked", "cancelled", "complete" ] } }, "style": "form", "explode": true }, { "name": "name", "in": "query", "description": "Filter by agent config name", "required": false, "schema": { "type": "string" } }, { "name": "model_id", "in": "query", "description": "Filter by model ID", "required": false, "schema": { "type": "string" } }, { "name": "creator", "in": "query", "description": "Filter by creator UID (user or service account)", "required": false, "schema": { "type": "string" } }, { "name": "executor", "in": "query", "description": "Filter by the user or agent that executed the run. This will often be the\nsame as the creator, but not always: users may delegate tasks to agents.\n", "required": false, "schema": { "type": "string" } }, { "name": "source", "in": "query", "description": "Filter by run source type. Can be specified multiple times to match any of the given sources.\n", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RunSourceType" } }, "style": "form", "explode": true }, { "name": "execution_location", "in": "query", "description": "Filter by where the run executed", "required": false, "schema": { "$ref": "#/components/schemas/RunExecutionLocation" } }, { "name": "created_after", "in": "query", "description": "Filter runs created after this timestamp (RFC3339 format)", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "description": "Filter runs created before this timestamp (RFC3339 format)", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_after", "in": "query", "description": "Filter runs updated after this timestamp (RFC3339 format)", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "environment_id", "in": "query", "description": "Filter runs by environment ID. Passing the literal value\n`empty-environment` matches runs with no environment configured,\nrather than omitting the parameter, which applies no environment\nfilter at all. `empty-environment` can never collide with a real\nenvironment ID: every environment ID is exactly 22 characters\ndrawn from `[A-Za-z0-9]`, while this sentinel contains a hyphen\nand is a different length.\n", "required": false, "schema": { "type": "string" } }, { "name": "skill", "in": "query", "description": "Filter runs by skill spec (e.g., \"owner/repo:path/to/SKILL.md\").\nAlias for skill_spec.\n", "required": false, "schema": { "type": "string" } }, { "name": "skill_spec", "in": "query", "description": "Filter runs by skill spec (e.g., \"owner/repo:path/to/SKILL.md\")", "required": false, "schema": { "type": "string" } }, { "name": "schedule_id", "in": "query", "description": "Filter runs by the scheduled agent ID that created them", "required": false, "schema": { "type": "string" } }, { "name": "factory_uid", "in": "query", "description": "Filter runs by one or more factories. Repeating this parameter\nmatches runs executed by an agent from any selected factory. A UID\noutside the caller's accessible factories matches nothing.\n", "required": false, "schema": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "style": "form", "explode": true }, { "name": "ancestor_run_id", "in": "query", "description": "Filter runs by ancestor run ID. The referenced run must exist and be accessible to the caller.", "required": false, "schema": { "type": "string" } }, { "name": "metadata", "in": "query", "description": "Filter by exact metadata key/value pairs using object notation\n(e.g. `metadata[ticket_id]=ACME-238`), combining multiple pairs\nwith AND semantics, up to 5 per request. Returns\n`feature_not_available` when metadata filtering is not enabled.\n", "required": false, "schema": { "type": "object", "maxProperties": 5, "additionalProperties": { "type": "string" } }, "style": "deepObject", "explode": true }, { "name": "artifact_type", "in": "query", "description": "Filter runs by artifact type", "required": false, "schema": { "type": "string", "enum": [ "PLAN", "PULL_REQUEST", "SCREENSHOT", "FILE", "EXTERNAL_REFERENCE" ] } }, { "name": "q", "in": "query", "description": "Search by full run ID or run URL, or fuzzy match across run title, prompt, and skill_spec", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of runs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRunsResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Metadata filtering is not enabled for this environment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/run-by-external-reference": { "get": { "summary": "Find the run that produced a given external reference URL", "description": "Reverse-looks up the agent run that created an external reference\nwith the given URL. The URL is matched against the canonical locator stored\nwhen the artifact was reported. Returns 404 when no matching run\nexists or when the caller lacks access.\n", "operationId": "getRunByExternalReferenceURL", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "url", "in": "query", "required": true, "description": "The canonical URL of the external reference artifact to look up.", "schema": { "type": "string", "maxLength": 2048 } } ], "responses": { "200": { "description": "Run found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunByExternalReferenceResponse" } } } }, "400": { "description": "url query parameter is missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No run found with the given external reference URL, or caller lacks access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/runs/{runId}": { "get": { "summary": "Get run details", "description": "Retrieve detailed information about a specific agent run, \nincluding the full prompt, session link, and resolved configuration.\n", "operationId": "getRun", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "runId", "in": "path", "description": "The unique identifier of the run", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Run details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunItem" } } } }, "400": { "description": "Missing run ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to access run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/runs/{runId}/timeline": { "get": { "summary": "Get run timeline", "description": "Retrieve chronological setup and lifecycle timeline events for an agent run.\n", "operationId": "getRunTimeline", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "runId", "in": "path", "description": "The unique identifier of the run", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Run timeline events", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetRunTimelineResponse" } } } }, "400": { "description": "Missing run ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to access run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/runs/{runId}/conversation": { "get": { "summary": "Get normalized run conversation", "description": "Retrieve a run's conversation as a normalized sequence of messages and\nnested steps. The response groups text, tool activity, and event content\ninto structured blocks.\n", "operationId": "getRunConversation", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "runId", "in": "path", "description": "The unique identifier of the run", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Normalized conversation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationResponse" } } } }, "400": { "description": "Missing run ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to access run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run not found, or the run has no conversation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Conversation format is not yet supported by the normalized endpoint\n(error_code: operation_not_supported)\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/runs/{runId}/cancel": { "post": { "summary": "Cancel a run", "description": "Cancel an agent run that is currently queued or in progress; once\ncancelled, the run transitions to a cancelled state. Not all runs can\nbe cancelled: a run already in a terminal state, in PENDING, or of an\nunsupported type (e.g. local, GitHub Action) is rejected\ninstead — see the error responses below for each case.\n", "operationId": "cancelRun", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "runId", "in": "path", "description": "The unique identifier of the run to cancel", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Run cancelled successfully", "content": { "application/json": { "schema": { "type": "string", "description": "The ID of the cancelled run" } } } }, "400": { "description": "Missing run ID, or the run is already in a terminal state.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to cancel run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Run is in PENDING state and cannot be cancelled yet.\nRetry after a moment.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Run cannot be cancelled because the operation is not supported\nfor this run type (e.g. local, or GitHub Action runs)\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/runs/{runId}/followups": { "post": { "summary": "Submit a follow-up message for a run", "description": "Send a follow-up message to an existing run. The server transparently\nroutes the message based on the current state of the run (still\nqueued, actively running, or ended) and will resume the agent in a new\nsandbox if necessary. A 200 response means the follow-up\nwas accepted; updated run state can be observed via\n`GET /agent/runs/{runId}`.\n\nA run that failed during environment setup keeps its retained session\nreachable for a bounded debug window. A follow-up sent to an eligible\nrun in that window is delivered into the retained session to start or\ncontinue a debug agent, without reopening the run: it stays in its\nfailed state, with its original failure message and error code\nunchanged.\n", "operationId": "submitRunFollowup", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "runId", "in": "path", "description": "The unique identifier of the run", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunFollowupRequest" } } } }, "responses": { "200": { "description": "Follow-up accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunFollowupResponse" } } } }, "400": { "description": "Invalid request (e.g. no active sandbox without conversation ID,\nmalformed payload). Empty messages are accepted when continuing a\nrun from saved conversation context or when attachments are\npresent; otherwise they are rejected.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to submit follow-ups for this run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "An `attachment_id` is not recorded on this run (`reason:\nunknown_attachment`), or more than 25 attachments were named\n(`reason: too_many_attachments`).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/runs/{runId}/interrupt": { "post": { "summary": "Interrupt the turn currently running on a run", "description": "Cancel the request the agent is currently working on without ending\nthe run or tearing down its sandbox. The run stays in progress and\naccepts follow-ups afterwards. Only live runs on the Warp harness\ncan be interrupted; use `POST /agent/runs/{runId}/cancel` to end a\nrun outright. A 202 means the platform accepted the cancel; the agent\napplies it asynchronously.\n", "operationId": "interruptRun", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "runId", "in": "path", "description": "The unique identifier of the run", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Interrupt accepted", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Missing run ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to steer this run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The run cannot be interrupted right now. `reason` is one of\n`no_live_session` (no reachable session, or the session has not\nregistered a conversation yet), `session_ended`, or\n`unsupported_harness` (a non-Oz harness has no turn-level cancel).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/conversations/{conversation_id}/followups": { "post": { "summary": "Submit a follow-up message to the run behind a conversation", "description": "The same operation as `POST /agent/runs/{runId}/followups`, targeted\nby the conversation the run is serving rather than the run itself.\n\n`attachments` must name ids prepared through\n`POST /agent/conversations/{conversation_id}/attachments/prepare` (or\nthe run-keyed prepare) for the run that is newest at that time. If a\nnew run appears for the conversation between prepare and follow-up,\nthe follow-up resolves to the new run and answers 422\n`unknown_attachment`; prepare again. A handoff is a new execution of\nthe same run and does not have this problem.\n\n`mode` only takes effect when the follow-up is queued ahead of the run\nstarting or starts a new execution; a follow-up injected into a live\nsession runs in the session's current mode.\n", "operationId": "submitConversationFollowup", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "description": "The UUID of the Warp-native conversation", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunFollowupRequest" } } } }, "responses": { "200": { "description": "Follow-up accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationFollowupResponse" } } } }, "400": { "description": "Invalid conversation ID or malformed payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to view the conversation or to follow up on its run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Conversation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The conversation has no run to steer (`reason: no_run`), for\nexample a purely local, cloud-synced conversation.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "An `attachment_id` is not recorded on the resolved run (`reason:\nunknown_attachment`), or more than 25 attachments were named\n(`reason: too_many_attachments`).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/conversations/{conversation_id}/interrupt": { "post": { "summary": "Interrupt the turn running on the run behind a conversation", "description": "The same operation as `POST /agent/runs/{runId}/interrupt`, addressed\nby the conversation the run is serving. The run is picked with the\nsame policy as the conversation follow-up route, and the caller must\nbe able to view the conversation and the resolved run.\n", "operationId": "interruptConversation", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "description": "The UUID of the Warp-native conversation", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Interrupt accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationInterruptResponse" } } } }, "400": { "description": "Invalid conversation ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to view the conversation or to steer its run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Conversation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The run cannot be interrupted. `reason` is one of `no_run`,\n`no_live_session`, `session_ended` or `unsupported_harness`.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/conversations/{conversation_id}": { "get": { "summary": "Get normalized conversation", "description": "Retrieve a conversation directly by conversation ID in Warp's\nnormalized task/message format.\n", "operationId": "getConversation", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "description": "The unique identifier of the conversation", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Normalized conversation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationResponse" } } } }, "400": { "description": "Missing conversation ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to access conversation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Conversation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Conversation format is not yet supported by the normalized endpoint\n(error_code: operation_not_supported)\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/conversations/{conversation_id}/transcript": { "get": { "summary": "Get conversation transcript", "description": "Retrieve the raw conversation transcript for a conversation.\nReturns a 302 redirect to a time-limited download URL for the transcript.\nSupported for third-party harness conversations (Claude Code, Codex, Gemini).\n", "operationId": "getConversationTranscript", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "description": "The unique identifier of the conversation", "required": true, "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to a download URL for the transcript", "headers": { "Location": { "description": "URL to download the transcript", "schema": { "type": "string", "format": "uri" } } } }, "400": { "description": "Conversation format does not support raw transcript download", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to access conversation transcript", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Conversation not found or has no transcript", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/conversations/{conversation_id}/screenshots/{screenshot_uid}/download": { "get": { "summary": "Download a stored computer-use screenshot", "description": "Download a computer-use screenshot that was offloaded\nfrom the conversation's task history into object storage. The\nresponse is a redirect to a short-lived signed URL, so clients must\nfollow redirects to receive the image. Requires view access to the\nconversation named in the path; a fork's history may reference\nscreenshots stored under its source conversation's ID.\n", "operationId": "downloadConversationScreenshot", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "description": "The unique identifier of the conversation that owns the screenshot", "required": true, "schema": { "type": "string" } }, { "name": "screenshot_uid", "in": "path", "description": "The unique identifier of the stored screenshot", "required": true, "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to a temporary signed screenshot download URL", "headers": { "Location": { "description": "Temporary signed download URL", "schema": { "type": "string", "format": "uri" } }, "Cache-Control": { "description": "Cache directive for the redirect response", "schema": { "type": "string" } }, "X-Content-Type-Options": { "description": "Browser content sniffing protection", "schema": { "type": "string" } } } }, "400": { "description": "Missing conversation ID or screenshot UID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to view the conversation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Conversation or screenshot not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/schedules": { "post": { "summary": "Create a scheduled agent", "description": "Create a new scheduled agent that runs on a cron schedule.\nThe agent will be triggered automatically based on the cron expression.\n", "operationId": "createScheduledAgent", "tags": [ "schedules" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/TeamUidHeaderParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateScheduledAgentRequest" }, "examples": { "simple": { "summary": "Simple daily schedule", "value": { "name": "Daily Code Review", "cron_schedule": "0 9 * * *", "prompt": "Review open pull requests and provide feedback", "enabled": true } }, "withConfig": { "summary": "With agent config", "value": { "name": "Weekly Report", "cron_schedule": "0 10 * * 1", "prompt": "Generate weekly status report", "enabled": true, "agent_config": { "model_id": "claude-4-6-opus-high" } } } } } } }, "responses": { "201": { "description": "Scheduled agent created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledAgentItem" } } } }, "400": { "description": "Invalid request (missing required fields, invalid cron expression)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission or feature not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List scheduled agents", "description": "Retrieve all scheduled agents accessible to the authenticated user.\nResults are sorted alphabetically by name.\n", "operationId": "listScheduledAgents", "tags": [ "schedules" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/TeamUidHeaderParam" } ], "responses": { "200": { "description": "List of scheduled agents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListScheduledAgentsResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/schedules/{scheduleId}": { "get": { "summary": "Get scheduled agent details", "description": "Retrieve detailed information about a specific scheduled agent,\nincluding its configuration, history, and next scheduled run time.\n", "operationId": "getScheduledAgent", "tags": [ "schedules" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "scheduleId", "in": "path", "description": "The unique identifier of the scheduled agent", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Scheduled agent details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledAgentItem" } } } }, "400": { "description": "Missing schedule ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to access schedule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Schedule not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "summary": "Update a scheduled agent", "description": "Update an existing scheduled agent's configuration.\nAll fields except agent_config are required.\n", "operationId": "updateScheduledAgent", "tags": [ "schedules" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "scheduleId", "in": "path", "description": "The unique identifier of the scheduled agent", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateScheduledAgentRequest" } } } }, "responses": { "200": { "description": "Scheduled agent updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledAgentItem" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to update schedule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Schedule not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete a scheduled agent", "description": "Delete a scheduled agent. This will stop all future scheduled runs.\n", "operationId": "deleteScheduledAgent", "tags": [ "schedules" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "scheduleId", "in": "path", "description": "The unique identifier of the scheduled agent", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Scheduled agent deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteScheduledAgentResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to delete schedule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Schedule not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/schedules/{scheduleId}/pause": { "post": { "summary": "Pause a scheduled agent", "description": "Pause a scheduled agent. The agent will not run until resumed.\n", "operationId": "pauseScheduledAgent", "tags": [ "schedules" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "scheduleId", "in": "path", "description": "The unique identifier of the scheduled agent", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Scheduled agent paused successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledAgentItem" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to pause schedule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Schedule not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/schedules/{scheduleId}/resume": { "post": { "summary": "Resume a scheduled agent", "description": "Resume a paused scheduled agent. The agent will start running\naccording to its cron schedule.\n", "operationId": "resumeScheduledAgent", "tags": [ "schedules" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "scheduleId", "in": "path", "description": "The unique identifier of the scheduled agent", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Scheduled agent resumed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledAgentItem" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to resume schedule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Schedule not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/environments": { "get": { "summary": "List environments", "description": "Retrieve cloud environments accessible to the authenticated principal.\nReturns environments the caller owns, has been granted guest access to,\nor has accessed via link sharing.\n", "operationId": "listEnvironments", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/TeamUidHeaderParam" }, { "name": "sort_by", "in": "query", "required": false, "description": "Sort order for the returned environments.\n- `name`: alphabetical by environment name\n- `last_updated`: most recently updated first (default)\n", "schema": { "type": "string", "enum": [ "name", "last_updated" ], "default": "last_updated" } } ], "responses": { "200": { "description": "List of accessible environments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEnvironmentsResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/models": { "get": { "summary": "List available models", "description": "Retrieve the list of LLM models available to the authenticated user for\nagent runs. The response includes which model is the default, as well as\nper-model metadata such as provider, cost, and whether the model is\ncurrently disabled (and why).\n", "operationId": "listModels", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "List of available models", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListModelsResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/artifacts/{artifactUid}": { "get": { "summary": "Get artifact details", "description": "Retrieve an artifact by its UUID: a time-limited signed download URL\nfor downloadable file-like artifacts, or the current plan content\ninline for plan artifacts. Public artifacts can be read without\nauthentication; private artifacts require the caller to be\nauthenticated and authorized.\n", "operationId": "getArtifact", "tags": [ "agent" ], "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "artifactUid", "in": "path", "description": "The unique identifier (UUID) of the artifact", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Artifact details with download information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactResponse" } } } }, "400": { "description": "Missing artifact UID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required for private artifacts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to access private artifact", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Artifact not found or unsupported artifact type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/artifacts/{artifactUid}/download": { "get": { "summary": "Download an artifact", "description": "Redirect to a temporary signed download URL for a downloadable artifact.\nPublic artifacts can be downloaded without authentication; private\nartifacts require the caller to be authenticated and authorized.\n", "operationId": "downloadArtifact", "tags": [ "agent" ], "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "artifactUid", "in": "path", "description": "The unique identifier (UUID) of the artifact", "required": true, "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to a temporary signed artifact download URL", "headers": { "Location": { "description": "Temporary signed download URL", "schema": { "type": "string", "format": "uri" } }, "Cache-Control": { "description": "Cache directive for the redirect response", "schema": { "type": "string" } }, "X-Content-Type-Options": { "description": "Browser content sniffing protection", "schema": { "type": "string" } } } }, "400": { "description": "Missing artifact UID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required for private artifacts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to access private artifact", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Artifact not found or unsupported artifact type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/identities": { "post": { "summary": "Create an agent", "description": "Create a new agent in the caller's active team. Agents act autonomously with their\nown permissions, configuration, and identity.\n", "operationId": "createAgent", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/TeamUidHeaderParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentRequest" } } } }, "responses": { "201": { "description": "Agent created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResponse" } } } }, "400": { "description": "Invalid request (empty name, user on multiple teams, or on no team)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Only human users can manage agents, or plan limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List agents", "description": "List all agents on the caller's team.\n", "operationId": "listAgents", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/TeamUidHeaderParam" }, { "name": "factory_uid", "in": "query", "required": false, "description": "Optional UID of a Factory to filter by. When provided, only agents\nlinked to that factory are returned.\n", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of agents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAgentIdentitiesResponse" } } } }, "400": { "description": "User on multiple teams, or on no team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Only human users can list agents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/identities/{uid}": { "get": { "summary": "Retrieve an agent", "description": "Retrieve a single agent by its unique identifier.\n", "operationId": "getAgent", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uid", "in": "path", "description": "The unique identifier of the agent", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Agent details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "summary": "Update an agent", "description": "Update an existing agent.\n", "operationId": "updateAgent", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uid", "in": "path", "description": "The unique identifier of the agent", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgentRequest" } } } }, "responses": { "200": { "description": "Agent updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResponse" } } } }, "400": { "description": "Missing or invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Only human users can manage agents, or plan limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete an agent", "description": "Delete an agent. All API keys associated with the\nagent are deleted atomically.\n", "operationId": "deleteAgent", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uid", "in": "path", "description": "The unique identifier of the agent", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Agent deleted successfully" }, "400": { "description": "Cannot delete the default agent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Only human users can manage agents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory-files/schemas": { "get": { "summary": "List the supported Factory file schema versions", "description": "Returns every Factory file schema version this server can describe,\nwith a link to each version's schema bundle.\n", "operationId": "listFactoryFileSchemaVersions", "tags": [ "factory" ], "security": [], "parameters": [ { "name": "If-None-Match", "in": "header", "required": false, "description": "A previously returned ETag. A match returns 304 with no body.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The supported schema versions", "headers": { "ETag": { "description": "Strong validator derived from the response bytes", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactoryFileSchemaRegistry" } } } }, "304": { "description": "The cached response is still current" } } } }, "/factory-files/schemas/{schema_version}": { "get": { "summary": "Get the JSON Schema bundle for one Factory file schema version", "description": "Returns every JSON Schema 2020-12 document describing one Factory file\nschema version, as a single bundle so the relative `$id` and `$ref`\nidentities between the documents keep resolving.\n", "operationId": "getFactoryFileSchemaBundle", "tags": [ "factory" ], "security": [], "parameters": [ { "name": "schema_version", "in": "path", "required": true, "description": "A Factory file schema version, for example `v1alpha1`.", "schema": { "type": "string" } }, { "name": "If-None-Match", "in": "header", "required": false, "description": "A previously returned ETag. A match returns 304 with no body.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The schema documents for this version", "headers": { "ETag": { "description": "Strong validator derived from the response bytes", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactoryFileSchemaBundle" } } } }, "304": { "description": "The cached response is still current" }, "404": { "description": "The schema version is not supported by this server", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factory-files/schemas/{schema_version}/{document}": { "get": { "summary": "Get one Factory file schema document", "description": "Returns a single generated JSON Schema document on its own, rather\nthan inside the bundle envelope, so it can be used directly as a\nschema reference. A document served here resolves its relative\n`$ref`s against its siblings at this same path, which is what each\ndocument's `$id` assumes, making the URL usable directly from an\neditor or YAML language server, for example:\n\n```yaml\n# yaml-language-server: $schema=/api/v1/factory-files/schemas/v1alpha1/factory.schema.json\n```\n", "operationId": "getFactoryFileSchemaDocument", "tags": [ "factory" ], "security": [], "parameters": [ { "name": "schema_version", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Factory file schema version, such as v1alpha1" }, { "name": "document", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Document file name: common.schema.json, factory.schema.json,\nagent.schema.json, automation.schema.json, runner.schema.json, or\nscorer.schema.json\n" } ], "responses": { "200": { "description": "The requested JSON Schema document", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "The version or the document is unknown", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Authentication via a Warp API key or a supported Warp-issued user token.\n" } }, "parameters": { "TeamUidHeaderParam": { "name": "X-Warp-Team-Uid", "in": "header", "required": false, "description": "UID of the team to use as the request's active team. Ignored for\nservice-account callers, which always act as their bound team.\n", "schema": { "type": "string" } }, "ConversationHistoryConversationId": { "name": "conversation_id", "in": "path", "description": "The UUID of the Warp-native conversation", "required": true, "schema": { "type": "string", "format": "uuid" } } }, "headers": { "ConversationHistoryCacheControl": { "description": "Prevents storage of canonical conversation history.", "schema": { "type": "string", "example": "no-store" } }, "ConversationHistoryRetryAfter": { "description": "Seconds to wait before re-requesting. Present only when\n`X-Warp-Stream-State` is `pending`.\n", "schema": { "type": "integer", "example": 2 } }, "ConversationHistoryStreamState": { "description": "Whether a shared session can produce events for this conversation.\n`active`: the newest session-linked execution is live; stream from\n`X-Warp-Stream-Session` with `X-Warp-Stream-Cursor`. `pending`: no\nsession is live yet, but a hosted execution of the run is starting\nand has not registered its shared session, or a queued follow-up is\nwaiting to start one; poll again after `Retry-After`. `ended`: no\nexecution is linked to a shared session or the newest one has ended,\nand nothing is starting.\n", "schema": { "type": "string", "enum": [ "active", "pending", "ended" ] } }, "ConversationHistoryStreamSession": { "description": "UUID of the shared session to stream from. Present only when\n`X-Warp-Stream-State` is `active`.\n", "schema": { "type": "string", "format": "uuid" } }, "ConversationHistoryStreamCursor": { "description": "Opaque logical cursor describing where the returned history\nends; pass it verbatim as `?cursor=` on the first connect to\nthe session-sharing event stream. Present only when\n`X-Warp-Stream-State` is `active`. At most 512 bytes.\n", "schema": { "type": "string", "maxLength": 512 } }, "ConversationHistoryRunId": { "description": "The run this conversation is served through: the run whose\nexecution owns the stream when `X-Warp-Stream-State` is\n`active`, else the newest run for the conversation. Absent\nwhen no run references the conversation. The\nconversation-keyed steering routes act on this same run.\n", "schema": { "type": "string" } } }, "responses": { "FactoryAccessDenied": { "description": "Factory access is not enabled for the authenticated principal", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "EgressRangesResponse": { "type": "object", "required": [ "cidrs" ], "properties": { "cidrs": { "type": "array", "items": { "type": "string" }, "description": "Canonical, deduplicated IPv4 and IPv6 network ranges." } } }, "FactoryFileSchemaRegistry": { "type": "object", "description": "The Factory file schema versions a server can describe.", "required": [ "current_version", "versions" ], "properties": { "current_version": { "type": "string", "description": "The version a new Factory tree should declare.", "example": "v1alpha1" }, "versions": { "type": "array", "description": "Every supported version, sorted by schema version.", "items": { "$ref": "#/components/schemas/FactoryFileSchemaVersionRef" } } } }, "FactoryFileSchemaVersionRef": { "type": "object", "required": [ "schema_version", "schema_url" ], "properties": { "schema_version": { "type": "string", "example": "v1alpha1" }, "schema_url": { "type": "string", "description": "Root-relative path of this version's schema bundle.", "example": "/api/v1/factory-files/schemas/v1alpha1" } } }, "FactoryFileSchemaBundle": { "type": "object", "description": "Every JSON Schema document describing one Factory file schema version.\nThe envelope is plain JSON; each value in `documents` is a JSON Schema\n2020-12 document keyed by its `$id`.\n", "required": [ "schema_version", "documents" ], "properties": { "schema_version": { "type": "string", "example": "v1alpha1" }, "documents": { "type": "object", "description": "Schema documents keyed by file name, which is also each document's $id.", "additionalProperties": { "description": "A JSON Schema 2020-12 document." } } } }, "Factory": { "type": "object", "description": "Public representation of a factory.", "required": [ "uid", "team_uid", "name", "description", "alias", "avatar_url", "code_forge", "code_forges", "repositories", "default_environment", "default_model", "scoring", "credential_strategy", "integrations", "agent_defaults", "scorer_defaults", "created_at", "updated_at" ], "properties": { "uid": { "type": "string", "description": "Public UID of the factory." }, "team_uid": { "type": "string", "description": "Public UID of the team that owns the factory." }, "name": { "type": "string", "description": "Display name of the factory." }, "description": { "type": "string", "nullable": true, "description": "Optional description of the factory." }, "alias": { "type": "string", "nullable": true, "description": "Optional display handle for the factory, unique across the team's\nWarp workspace when set.\n" }, "avatar_url": { "type": "string", "nullable": true, "description": "Short-lived signed URL for displaying the factory's avatar. The URL\nmay change between reads.\n" }, "code_forge": { "$ref": "#/components/schemas/FactoryCodeForge" }, "code_forges": { "type": "array", "items": { "$ref": "#/components/schemas/FactoryCodeForge" }, "description": "Effective source-control providers for the factory. When the\neffective set is empty, this contains the primary code_forge.\n" }, "repositories": { "type": "array", "items": { "$ref": "#/components/schemas/FactoryRepository" }, "description": "Repositories scoped to the factory, independent of its default environment." }, "default_environment": { "type": "string", "nullable": true, "description": "Public UID of the factory's default environment. File-managed\nfactories may omit this default.\n" }, "default_model": { "type": "string", "nullable": true, "description": "The default model ID for the factory's runs. File-managed factories\nmay omit this default. Live-managed create and PATCH requests still\ncapture a concrete validated model ID.\n" }, "scoring": { "$ref": "#/components/schemas/FactoryScoringConfig" }, "self_improvement": { "allOf": [ { "$ref": "#/components/schemas/FactorySelfImprovementConfig" } ], "readOnly": true, "description": "Self-improvement settings from GitHub-managed Factory YAML. Omitted when none are declared, in which case team admins are the reviewer pool." }, "credential_strategy": { "allOf": [ { "$ref": "#/components/schemas/FactoryCredentialStrategy" } ], "description": "Default credential strategy for runs executed by the factory's\nnamed agents. Always a concrete value; factories default to\nEXECUTOR unless explicitly set to CREATOR.\n" }, "integrations": { "type": "array", "items": { "$ref": "#/components/schemas/FactoryIntegration" }, "nullable": true, "description": "Integration providers attached to the factory, independent of the\nautomation triggers configured for it. null means the factory has\nnot declared anything yet; an empty array means no providers are\nattached.\n" }, "agent_defaults": { "$ref": "#/components/schemas/FactoryAgentDefaults" }, "scorer_defaults": { "$ref": "#/components/schemas/FactoryScorerDefaults" }, "creator": { "allOf": [ { "$ref": "#/components/schemas/FactoryCreator" } ], "description": "The user who created the factory. Absent when there is no\nresolvable creator: the factory predates creator tracking, it was\ncreated by a service account, or the creating user's account no\nlonger exists.\n" }, "created_at": { "type": "string", "format": "date-time", "description": "Time the factory was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "Time the factory was last updated." } } }, "FactoryCreator": { "type": "object", "description": "The user who created a factory, when resolvable.", "required": [ "uid" ], "properties": { "uid": { "type": "string", "description": "Firebase UID of the user who created the factory." }, "email": { "type": "string", "nullable": true, "description": "Creator's email, when available." } } }, "FactoryAgentDefaults": { "type": "object", "description": "Default execution settings inherited by the factory's named agents\nwhen they declare no override of their own.\n", "required": [ "default_runner_uid", "secrets", "mcp_servers", "worker_host" ], "properties": { "harness": { "allOf": [ { "$ref": "#/components/schemas/Harness" } ], "description": "Default harness for the factory's named agents. Absent when the\nfactory defaults to Warp's built-in harness. model_id and\nreasoning_level carry the harness-scoped default model, which is\nalso reported in the factory's default_model.\n" }, "harness_auth_secrets": { "allOf": [ { "$ref": "#/components/schemas/HarnessAuthSecrets" } ], "description": "Per-harness authentication secrets inherited by the factory's\nnamed agents. Only the secret for the default harness is ever\npopulated. A third-party default harness with no secret here\ntakes its credentials from the worker environment.\n" }, "default_runner_uid": { "type": "string", "description": "Default runner UID for the factory's named agents. Empty when\nunset, in which case the environment's default runner applies.\n" }, "secrets": { "type": "array", "items": { "$ref": "#/components/schemas/SecretRef" }, "description": "Secrets attached to the factory's named agents by default." }, "mcp_servers": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/MCPServerConfig" }, "description": "MCP server configurations attached to the factory's named agents\nby default. Only warp_id (managed MCP) entries are representable\nfor a Warp-managed factory.\n" }, "worker_host": { "type": "string", "description": "Default worker host for the factory's named agents. Empty when\nunset, in which case the workspace default applies.\n" } } }, "FactoryScorerDefaults": { "type": "object", "description": "Sparse execution defaults for scorers. An omitted field inherits the\ncorresponding agent default; an explicit empty collection overrides\nthe agent default with no values.\n", "properties": { "default_runner_uid": { "type": "string", "description": "Default runner UID for scorers. Omitted to inherit the agent default." }, "secrets": { "type": "array", "items": { "$ref": "#/components/schemas/SecretRef" }, "description": "Scorer-default secrets. Omitted to inherit the agent defaults; an\nempty array explicitly clears them.\n" }, "mcp_servers": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/MCPServerConfig" }, "description": "Scorer-default MCP servers. Omitted to inherit the agent defaults;\nan empty object explicitly clears them.\n" } } }, "FactorySelfImprovementConfig": { "type": "object", "required": [ "reviewer_type" ], "properties": { "reviewer_type": { "type": "string", "enum": [ "none", "admins", "team", "custom" ], "description": "Owning-team pool one eligible reviewer is randomly requested from for self-improvement pull requests. `admins` requests a team admin or owner and is the default when the Factory declares no self-improvement settings. `team` requests any team member. `custom` requests a member listed in `reviewer_emails`. `none` explicitly disables reviewer assignment." }, "failed_run_threshold": { "type": "integer", "minimum": 1, "maximum": 50, "description": "Per-agent count of distinct scored-failing source runs required for scheduled self-improvement. Must be between 1 and 50: one self-improvement run can triage at most 50 failure findings. Omitted to use the server default. The age-based flush and manual dispatch are unchanged." }, "reviewer_emails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Owning-team member emails reviewers are chosen from. Only allowed when `reviewer_type` is `custom`: a Factory YAML change that sets emails with any other reviewer type fails validation, including the pull request check." } } }, "FactoryScoringConfig": { "type": "object", "required": [ "default_model" ], "properties": { "default_model": { "type": "string", "nullable": true, "description": "Optional factory override for the model used by managed scorers and\nscorer-creation prefills. null or absent resolves to the platform\njudge default. User-created scorers still require an explicit\nmodel_id on create.\n" } } }, "FactoryIntegration": { "type": "object", "description": "An integration provider attached to a factory.\n", "required": [ "type" ], "properties": { "type": { "$ref": "#/components/schemas/FactoryIntegrationProvider" }, "linear": { "allOf": [ { "$ref": "#/components/schemas/FactoryLinearIntegrationSettings" } ], "nullable": true, "description": "Linear team IDs from earlier integration selections, when present.\nIssue discovery follows enabled agent-session automations instead.\n" }, "jira": { "allOf": [ { "$ref": "#/components/schemas/FactoryJiraIntegrationSettings" } ], "nullable": true, "description": "Jira project keys from earlier integration selections, when present.\nIssue discovery follows enabled agent-session automations instead.\n" }, "slack": { "allOf": [ { "$ref": "#/components/schemas/FactorySlackIntegrationSettings" } ], "nullable": true, "description": "Persisted Slack settings. Present only when type is slack and the\nfactory has declared at least one Slack setting. Omitted fields\nkeep their default-on behavior.\n" }, "microsoft-teams": { "allOf": [ { "$ref": "#/components/schemas/FactoryTeamsIntegrationSettings" } ], "nullable": true, "description": "Persisted Teams reply settings. Valid only when type is\nmicrosoft-teams. Omitted settings remain undeclared.\n" } } }, "FactoryLinearIntegrationSettings": { "type": "object", "required": [ "team_ids" ], "properties": { "team_ids": { "type": "array", "description": "Linear team IDs for the one-time agent-session automation seed.\nDiscovery follows enabled seated automation filters afterward.\n", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "pattern": ".*\\S.*" } } } }, "FactorySlackIntegrationSettings": { "description": "Persisted Slack settings on a factory integration. Omitted fields keep\ntheir default-on behavior.\n", "allOf": [ { "$ref": "#/components/schemas/FactoryThreadReplySettings" } ] }, "FactoryTeamsIntegrationSettings": { "description": "Persisted Teams reply settings on a factory integration.", "allOf": [ { "$ref": "#/components/schemas/FactoryThreadReplySettings" } ] }, "FactoryThreadReplySettings": { "type": "object", "description": "Plain channel-thread reply settings. These apply when the shared\nper-Factory reply-setting rollout is enabled.\n", "properties": { "auto_respond_to_thread_replies": { "type": "boolean", "nullable": true, "description": "When true, eligible plain channel thread replies still reach the\nreply-intent classifier. When false, those replies are ignored\nunless they @-mention the Factory. Each provider defines the\nomitted default. Direct messages are unchanged.\n" } } }, "FactoryJiraIntegrationSettings": { "type": "object", "required": [ "project_keys" ], "properties": { "project_keys": { "type": "array", "description": "Jira project keys (for example APP, not the numeric project ID)\nfor the one-time agent-session automation seed. Discovery follows\nenabled seated automation filters afterward.\n", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "pattern": ".*\\S.*" } } } }, "FactoryIntegrationProvider": { "type": "string", "description": "Integration provider that can be attached to a factory. github is not\naccepted here; repository access comes from the factory's code forge.\n", "enum": [ "jira", "linear", "microsoft-teams", "slack" ] }, "FactoryCodeForge": { "type": "string", "description": "Primary source-control provider for the factory. GITHUB and GITLAB\nidentify the compatibility primary when repositories span one or more\nforges. AZURE_DEVOPS identifies Azure Repos. NONE declares a repo-less factory with no native repositories;\nits environment relies on setup_commands to clone from any host.\n", "enum": [ "GITHUB", "GITLAB", "AZURE_DEVOPS", "NONE" ] }, "FactoryRepositoryCodeForge": { "type": "string", "description": "The concrete source-control provider hosting a repository.", "enum": [ "GITHUB", "GITLAB", "AZURE_DEVOPS" ] }, "FactoryCredentialStrategy": { "type": "string", "description": "Default credential strategy for runs executed by the factory's named\nagents.\n- EXECUTOR (default): runs authenticate with the named agent's own\n credentials (e.g. a GitHub App installation token for the\n factory's team).\n- CREATOR: runs authenticate with the credentials of the principal\n that created the run.\n", "enum": [ "CREATOR", "EXECUTOR" ] }, "FactoryRepository": { "type": "object", "description": "A repository scoped to a factory.", "required": [ "owner", "repo" ], "properties": { "owner": { "type": "string", "description": "Repository owner (or full namespace for GitLab)." }, "repo": { "type": "string", "description": "Repository name." }, "code_forge": { "allOf": [ { "$ref": "#/components/schemas/FactoryRepositoryCodeForge" } ], "description": "The concrete forge hosting this repository. Omitted means the\nfactory's primary code_forge.\n" }, "provider_metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Provider-specific repository identity and settings, such as the Azure DevOps organization, project ID, and repository ID." } } }, "FactoryTaskStage": { "type": "string", "description": "Lifecycle stage of a factory task, mirroring the seeded factory agent\nroles plus the terminal COMPLETE and CANCELLED states. COMPLETE and\nCANCELLED are terminal in intent but not enforced: any stage may be\nwritten explicitly at any time. CANCELLED is set automatically when\nthe task's current top-level run is cancelled, regardless of that\nrun's agent type.\n", "enum": [ "TRIAGE", "SPEC", "IMPLEMENT", "REVIEW", "COMPLETE", "CANCELLED" ] }, "FactoryTaskCurrentRun": { "type": "object", "description": "A factory task's current top-level run, resolved from the bound\nconversation at read time. This differs from FactoryTask.run_id,\nwhich is a creation-time provenance snapshot and is never updated.\n", "required": [ "run_id", "state", "is_run_type_cancellable" ], "properties": { "run_id": { "type": "string", "description": "ID of the task's current top-level (root) run." }, "state": { "$ref": "#/components/schemas/RunState" }, "is_run_type_cancellable": { "type": "boolean", "description": "Whether the current run's type is eligible for cancellation via\nthe API. State-independent; clients should also gate on state.\n" } } }, "FactoryTask": { "type": "object", "description": "A factory task: the unit of work in a factory, bound to the agent\nconversation that owns it.\n", "required": [ "uid", "factory_uid", "conversation_id", "run_id", "title", "stage", "created_at", "updated_at" ], "properties": { "uid": { "type": "string", "description": "Public UID of the task." }, "factory_uid": { "type": "string", "description": "Public UID of the factory the task belongs to. Fixed at creation." }, "conversation_id": { "type": "string", "description": "UUID of the agent conversation the task is bound to." }, "run_id": { "type": "string", "description": "ID of the bound conversation's most recent run at task creation.\nThis is a provenance snapshot and is not updated afterward;\nconsumers needing the conversation's live latest run should\nresolve it via the conversation.\n" }, "author": { "allOf": [ { "$ref": "#/components/schemas/RunCreatorInfo" } ], "description": "Creator of the run captured by run_id. Omitted when the creation\nrun or its creator principal can no longer be resolved.\n" }, "title": { "type": "string", "description": "Human-readable title of the task." }, "ticket_source": { "type": "string", "description": "Canonical ticket source from the bound run. Present on list\nresponses only when full_list=true and ticket metadata exists.\n" }, "ticket_id": { "type": "string", "description": "Canonical ticket ID from the bound run. Present on list responses\nonly when full_list=true and ticket metadata exists.\n" }, "description": { "type": "string", "nullable": true, "description": "Optional description of the task." }, "stage": { "$ref": "#/components/schemas/FactoryTaskStage" }, "created_at": { "type": "string", "format": "date-time", "description": "Time the task was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "Time the task was last created, updated, or deleted. Artifact\nreporting does not bump this; new outputs appear on the next\ndetail read.\n" }, "outputs": { "type": "array", "items": { "$ref": "#/components/schemas/ArtifactItem" }, "description": "Derived outputs, newest-first: PULL_REQUEST, EXTERNAL_REFERENCE,\nSCREENSHOT, and FILE artifacts (video recordings are FILE\nartifacts). Present on single-task reads (by uid, by\nconversation, and by run), where outputs are derived from the\ntask's whole run tree (every run bound to the conversation plus\nthe runs dispatched under them). On list responses with\nfull_list=true, outputs are derived from the bound conversation\nonly, not the wider run tree.\n" }, "current_run": { "allOf": [ { "$ref": "#/components/schemas/FactoryTaskCurrentRun" } ], "description": "The task's current top-level run, resolved at read time. Present\non single-task reads (by uid, by conversation, and after a stop\nrequest), and on list responses when include_current_run=true;\nomitted when no current root run can be resolved.\n" } } }, "FactoryTaskCreateRequest": { "type": "object", "description": "Request body for creating a factory task.", "required": [ "title", "conversation_id" ], "properties": { "title": { "type": "string", "description": "Human-readable title of the task. Required and non-empty." }, "conversation_id": { "type": "string", "description": "UUID of the agent conversation to bind the task to. The\nconversation's most recent run must be owned by the factory's\nteam, and the conversation must not already be bound to a live\ntask.\n" }, "description": { "type": "string", "nullable": true, "description": "Optional description of the task." }, "stage": { "$ref": "#/components/schemas/FactoryTaskStage" } } }, "FactoryTaskPatchRequest": { "type": "object", "description": "Request body for partially updating a factory task. Omitted fields\npreserve their current values; last write wins.\n", "properties": { "title": { "type": "string", "description": "Updated title. Must be non-empty when provided." }, "description": { "type": "string", "nullable": true, "description": "Updated description. null or an empty string clears the description." }, "stage": { "$ref": "#/components/schemas/FactoryTaskStage" } } }, "ListFactoryTasksResponse": { "type": "object", "required": [ "tasks", "page_info" ], "properties": { "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/FactoryTask" }, "description": "One page of the factory's tasks, in the requested sort order." }, "page_info": { "$ref": "#/components/schemas/PageInfo" } } }, "ListFactoriesResponse": { "type": "object", "description": "Response body for listing factories.", "required": [ "factories", "page_info" ], "properties": { "factories": { "type": "array", "items": { "$ref": "#/components/schemas/Factory" } }, "page_info": { "$ref": "#/components/schemas/PageInfo" } } }, "FactoryRunRequest": { "type": "object", "description": "Request body for dispatching a run to a factory.", "required": [ "prompt" ], "properties": { "prompt": { "type": "string", "description": "The prompt sent to the factory's foreman, not wrapped in any\nfactory intake envelope. Required and non-empty.\n" }, "title": { "type": "string", "description": "Human-readable title for the dispatched run and its factory task.\nOmit to derive one automatically from the prompt.\n" }, "ticket_ref": { "type": "string", "description": "Originating ticket reference in : form (for\nexample, linear:REMOTE-123); omit to mint an adhoc reference.\nStamped onto the run as ticket_id/ticket_source metadata.\n" }, "ticket_url": { "type": "string", "description": "Optional URL of the ticket named by ticket_ref. Stamped onto\nthe run as ticket_url metadata when given.\n" } } }, "FactoryRunResponse": { "type": "object", "description": "Response body for a dispatched factory run.", "required": [ "run_id", "state", "factory_uid", "foreman_agent", "ticket_ref" ], "properties": { "run_id": { "type": "string", "description": "Unique identifier for the dispatched run." }, "run_url": { "type": "string", "description": "URL to view the dispatched run in the Factory app. Empty when\nthe Factory app origin is not configured.\n" }, "state": { "$ref": "#/components/schemas/RunState" }, "factory_uid": { "type": "string", "description": "Public UID of the factory the run was dispatched to." }, "foreman_agent": { "type": "string", "description": "Name of the factory's foreman agent that received the run." }, "ticket_ref": { "type": "string", "description": "The canonical : ticket reference the run was\nstamped with, either the caller-supplied ticket_ref or a\nminted adhoc reference.\n" } } }, "ClaudeHarnessUsagePayload": { "type": "object", "additionalProperties": false, "properties": { "usage": { "$ref": "#/components/schemas/ClaudeTokenUsage" }, "attribution": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/ClaudeAttributedUsage" } }, "toolCalls": { "$ref": "#/components/schemas/HarnessToolCalls" } } }, "CodexHarnessUsagePayload": { "type": "object", "additionalProperties": false, "properties": { "usage": { "$ref": "#/components/schemas/CodexTokenUsage" }, "attribution": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/CodexAttributedUsage" } }, "toolCalls": { "$ref": "#/components/schemas/HarnessToolCalls" } } }, "HarnessUsageCounter": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 9223372036854776000, "nullable": true, "description": "A native count. Absent or null means unmeasured, not zero." }, "ClaudeTokenUsage": { "type": "object", "additionalProperties": false, "nullable": true, "description": "Native cumulative token categories; cache counters are not added to input_tokens.", "properties": { "input_tokens": { "$ref": "#/components/schemas/HarnessUsageCounter" }, "output_tokens": { "$ref": "#/components/schemas/HarnessUsageCounter" }, "cache_read_input_tokens": { "$ref": "#/components/schemas/HarnessUsageCounter" }, "cache_creation_input_tokens": { "$ref": "#/components/schemas/HarnessUsageCounter" }, "cache_creation": { "$ref": "#/components/schemas/ClaudeCacheCreationUsage" } } }, "ClaudeCacheCreationUsage": { "type": "object", "additionalProperties": false, "nullable": true, "properties": { "ephemeral_5m_input_tokens": { "$ref": "#/components/schemas/HarnessUsageCounter" }, "ephemeral_1h_input_tokens": { "$ref": "#/components/schemas/HarnessUsageCounter" } } }, "CodexTokenUsage": { "type": "object", "additionalProperties": false, "nullable": true, "description": "Native checkpoint counters. Cached input and reasoning output may overlap other categories; no derived total is inferred.", "properties": { "input_tokens": { "$ref": "#/components/schemas/HarnessUsageCounter" }, "cached_input_tokens": { "$ref": "#/components/schemas/HarnessUsageCounter" }, "cache_write_input_tokens": { "$ref": "#/components/schemas/HarnessUsageCounter" }, "output_tokens": { "$ref": "#/components/schemas/HarnessUsageCounter" }, "reasoning_output_tokens": { "$ref": "#/components/schemas/HarnessUsageCounter" }, "total_tokens": { "$ref": "#/components/schemas/HarnessUsageCounter" } } }, "ClaudeAttributedUsage": { "type": "object", "additionalProperties": false, "required": [ "usage" ], "properties": { "model": { "type": "string", "nullable": true }, "service_tier": { "type": "string", "nullable": true }, "inference_geo": { "type": "string", "nullable": true }, "speed": { "type": "string", "nullable": true }, "usage": { "$ref": "#/components/schemas/ClaudeTokenUsage" } } }, "CodexAttributedUsage": { "type": "object", "additionalProperties": false, "required": [ "usage" ], "properties": { "model": { "type": "string", "nullable": true }, "service_tier": { "type": "string", "nullable": true }, "inference_geo": { "type": "string", "nullable": true }, "speed": { "type": "string", "nullable": true }, "usage": { "$ref": "#/components/schemas/CodexTokenUsage" } } }, "HarnessToolCalls": { "type": "object", "additionalProperties": false, "nullable": true, "required": [ "total", "byName" ], "description": "Native tool invocation counts. Total must equal the sum of byName; tool names are arbitrary map keys.", "properties": { "total": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 9223372036854776000 }, "byName": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 9223372036854776000 } } } }, "GetRunHarnessUsageResponse": { "type": "object", "required": [ "run_id", "conversation_id", "available" ], "properties": { "run_id": { "type": "string" }, "conversation_id": { "type": "string" }, "available": { "type": "boolean" }, "age_seconds": { "type": "integer", "format": "int64", "nullable": true }, "usage": { "$ref": "#/components/schemas/HarnessUsageEnvelope" } } }, "HarnessUsageEnvelope": { "oneOf": [ { "$ref": "#/components/schemas/ClaudeHarnessUsageEnvelope" }, { "$ref": "#/components/schemas/CodexHarnessUsageEnvelope" } ], "discriminator": { "propertyName": "harness", "mapping": { "CLAUDE_CODE": "#/components/schemas/ClaudeHarnessUsageEnvelope", "CODEX": "#/components/schemas/CodexHarnessUsageEnvelope" } } }, "ClaudeHarnessUsageEnvelope": { "type": "object", "additionalProperties": false, "required": [ "metricsVersion", "harness", "executionId", "captureSequence", "capturedAt", "snapshot" ], "properties": { "metricsVersion": { "type": "integer", "enum": [ 1 ], "description": "Server-owned storage format metadata, not the producer's parser version." }, "harness": { "type": "string", "enum": [ "CLAUDE_CODE" ] }, "executionId": { "type": "integer", "format": "int64" }, "captureSequence": { "type": "integer", "format": "int64" }, "capturedAt": { "type": "string", "format": "date-time" }, "snapshot": { "type": "object", "additionalProperties": false, "required": [ "coverage", "payload" ], "properties": { "coverage": { "$ref": "#/components/schemas/RetainedHarnessUsageCoverage" }, "payload": { "$ref": "#/components/schemas/ClaudeHarnessUsagePayload" } } } } }, "CodexHarnessUsageEnvelope": { "type": "object", "additionalProperties": false, "required": [ "metricsVersion", "harness", "executionId", "captureSequence", "capturedAt", "snapshot" ], "properties": { "metricsVersion": { "type": "integer", "enum": [ 1 ], "description": "Server-owned storage format metadata, not the producer's parser version." }, "harness": { "type": "string", "enum": [ "CODEX" ] }, "executionId": { "type": "integer", "format": "int64" }, "captureSequence": { "type": "integer", "format": "int64" }, "capturedAt": { "type": "string", "format": "date-time" }, "snapshot": { "type": "object", "additionalProperties": false, "required": [ "coverage", "payload" ], "properties": { "coverage": { "$ref": "#/components/schemas/RetainedHarnessUsageCoverage" }, "payload": { "$ref": "#/components/schemas/CodexHarnessUsagePayload" } } } } }, "RetainedHarnessUsageCoverage": { "type": "object", "additionalProperties": false, "required": [ "tokenStatus", "toolStatus" ], "properties": { "tokenStatus": { "type": "string", "enum": [ "known", "partial", "unavailable" ] }, "toolStatus": { "type": "string", "enum": [ "known", "partial", "unavailable" ] } } }, "RunAgentRequest": { "type": "object", "description": "Request body for creating a new agent run.\nEither prompt or skill (via skill field, config.skill_spec, or config.skills) is required,\nexcept for handoff requests that set conversation_id.\n", "properties": { "prompt": { "type": "string", "description": "The prompt/instruction for the agent to execute.\nRequired unless a skill is specified via the skill field, config.skill_spec, or config.skills.\nHandoff requests may omit prompt when conversation_id is set.\n" }, "mode": { "$ref": "#/components/schemas/AgentRunMode", "description": "Optional query mode for the run. Defaults to `normal` when omitted.\nThe server does not infer mode from prompt prefixes such as `/plan`,\nso callers should pass this field explicitly to request non-normal behavior.\n" }, "skill": { "type": "string", "description": "Skill specification to use as the base prompt for the agent.\nSupported formats:\n - \"repo:skill_name\" - Simple name in specific repo\n - \"repo:skill_path\" - Full path in specific repo\n - \"org/repo:skill_name\" - Simple name with org and repo\n - \"org/repo:skill_path\" - Full path with org and repo\nWhen provided, this takes precedence over config.skill_spec.\n" }, "config": { "$ref": "#/components/schemas/AmbientAgentConfig" }, "title": { "type": "string", "description": "Custom title for the run (auto-generated if not provided)" }, "team": { "type": "boolean", "description": "Whether to create a team-owned run.\nDefaults to true for users on a single team.\n" }, "agent_identity_uid": { "type": "string", "description": "Optional agent identity UID to use as the execution principal for the run.\nThis is only valid for runs that are team owned.\n" }, "on_behalf_of": { "type": "string", "description": "Optional email address or user ID of a Warp user to attribute\nthe run to; when set, the resolved user becomes the run's\ncreator instead of the caller. Only agent API keys may use this\nfield, only when the calling agent has on_behalf_of enabled in\nits configuration (a team admin must turn this on per agent),\nand only for team-owned runs. The target user must be an active\nmember of the run's owner team.\n" }, "conversation_id": { "type": "string", "description": "Optional conversation ID to continue an existing conversation.\nIf provided, the agent will continue from where the previous run left off.\n" }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/AttachmentInput" }, "description": "Optional file attachments to include with the prompt (max 5).\nAttachments are uploaded to cloud storage and made available to the agent.\n" }, "parent_run_id": { "type": "string", "description": "Optional run ID of the parent that spawned this run, used for\norchestration hierarchies; the parent run must exist and be\nvisible to the caller, or the request is rejected with a 400.\nChild runs are also subject to the server's maximum\norchestration depth, and requests that would exceed it are\nrejected with a 400.\n" }, "interactive": { "type": "boolean", "description": "Whether the run should be interactive.\nIf not set, defaults to false.\n" }, "metadata": { "$ref": "#/components/schemas/RunMetadata" } } }, "RunMetadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom key/value metadata attached to a run at creation time and\nimmutable afterward; at most 20 keys, with keys 1-64 bytes matching\n[a-zA-Z0-9._-]+ (case-sensitive) and values 0-256 bytes of UTF-8 with\nno NUL characters. Requests with invalid metadata are rejected. A\nrun's effective metadata is merged per key at creation: explicit\nrequest keys override keys inherited from the parent run, which\noverride automatic keys (ticket_id and ticket_source on Linear- and\nJira-triggered runs).\n" }, "RunAgentResponse": { "type": "object", "required": [ "run_id", "task_id", "state" ], "properties": { "run_id": { "type": "string", "description": "Unique identifier for the created run" }, "task_id": { "type": "string", "deprecated": true, "description": "Unique identifier for the task (same as run_id). Deprecated - use run_id instead." }, "state": { "$ref": "#/components/schemas/RunState" }, "at_capacity": { "type": "boolean", "description": "Whether the system is at capacity when the run was created" } } }, "AgentRunMode": { "type": "string", "description": "Query mode for an agent run.\n - normal: Standard user query (default).\n - plan: Planning Mode. The agent researches and creates a plan, then waits for approval before execution.\n - orchestrate: Orchestration Mode. The agent proposes an orchestration plan and must not start child agents until approved.\n", "enum": [ "normal", "plan", "orchestrate" ], "default": "normal" }, "ListRunsResponse": { "type": "object", "required": [ "runs", "page_info", "as_of", "team_uid" ], "properties": { "runs": { "type": "array", "items": { "$ref": "#/components/schemas/RunItem" } }, "page_info": { "$ref": "#/components/schemas/PageInfo" }, "as_of": { "type": "string", "format": "date-time", "description": "Time the runs were read (RFC3339). Data can lag live activity by a few minutes." }, "team_uid": { "type": "string", "nullable": true, "description": "UID of the team the request was scoped to: the team selected by the\n`X-Warp-Team-Uid` header, or the API key's team. Null when a user\nrequest has no team selected and the list spans every team the\nuser belongs to.\n" } } }, "RunItem": { "type": "object", "required": [ "run_id", "task_id", "title", "state", "prompt", "created_at", "finished_at", "updated_at", "root_run_id" ], "properties": { "run_id": { "type": "string", "description": "Unique identifier for the run" }, "task_id": { "type": "string", "deprecated": true, "description": "Unique identifier for the task (typically matches run_id). Deprecated - use run_id instead." }, "title": { "type": "string", "description": "Human-readable title for the run" }, "state": { "$ref": "#/components/schemas/RunState" }, "execution_location": { "$ref": "#/components/schemas/RunExecutionLocation" }, "prompt": { "type": "string", "description": "The prompt/instruction for the agent" }, "submitted_prompt": { "type": "string", "description": "The prompt exactly as it was submitted, without any extra context added by Warp. Includes any follow-up messages sent before the run started, separated by blank lines." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the run was created (RFC3339)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the run was last updated (RFC3339)" }, "run_time": { "type": "string", "format": "duration", "description": "Total runtime as an ISO 8601 duration (e.g. \"PT2M30S\"), computed server-side from run executions." }, "started_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the agent started working on the run (RFC3339)" }, "finished_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the run last reached a terminal state (RFC3339). Null\nwhile the run is still active, and for terminal runs with no\nrecorded finish time (runs executed locally, and runs that finished\nbefore finish times were recorded).\n" }, "status_message": { "$ref": "#/components/schemas/RunStatusMessage" }, "source": { "$ref": "#/components/schemas/RunSourceType" }, "schedule": { "$ref": "#/components/schemas/ScheduleInfo" }, "session_id": { "type": "string", "description": "UUID of the shared session (if available)" }, "session_link": { "type": "string", "format": "uri", "description": "URL to view the agent session" }, "trigger_url": { "type": "string", "format": "uri", "description": "URL to the run trigger (e.g. Slack thread, Linear issue, schedule)" }, "creator": { "$ref": "#/components/schemas/RunCreatorInfo" }, "executor": { "$ref": "#/components/schemas/RunCreatorInfo" }, "factory_uid": { "type": "string", "description": "UID of the factory whose agent executed the run. Absent for runs\nnot executed by a factory agent.\n" }, "request_usage": { "$ref": "#/components/schemas/RequestUsage" }, "agent_config": { "$ref": "#/components/schemas/AmbientAgentConfig" }, "conversation_id": { "type": "string", "description": "UUID of the conversation associated with the run" }, "parent_run_id": { "type": "string", "description": "UUID of the parent run that spawned this run" }, "root_run_id": { "type": "string", "description": "UUID of the top-level run of this run's orchestration tree. Equals\n`run_id` for a top-level run.\n" }, "metadata": { "$ref": "#/components/schemas/RunMetadata" }, "is_sandbox_running": { "type": "boolean", "description": "Whether the sandbox environment is currently running" }, "is_run_type_cancellable": { "type": "boolean", "description": "Whether the run's type is eligible for cancellation via the API. State-independent:\nfalse for GitHub Action and local runs; true for all other run types (including\nself-hosted). Clients should still gate the control on the run's current state.\n" }, "debug_agent_available": { "type": "boolean", "description": "Whether a debug agent can currently be started inside this run's retained\nsetup-failure session. Only true for a run that failed during environment setup,\nwhose retained execution is still reachable, and whose debug window has not\nclosed. See `POST /agent/runs/{runId}/followups`.\n" }, "artifacts": { "type": "array", "items": { "$ref": "#/components/schemas/ArtifactItem" }, "description": "Artifacts created during the run (plans, pull requests, etc.)" }, "agent_skill": { "$ref": "#/components/schemas/AgentSkill" }, "scope": { "$ref": "#/components/schemas/Scope" } } }, "GetRunTimelineResponse": { "type": "object", "description": "Response body for listing run timeline events.", "required": [ "events" ], "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/AIRunTimelineEvent" } } } }, "AIRunTimelineEvent": { "type": "object", "description": "A setup or lifecycle event recorded for an agent run.", "required": [ "event_uuid", "run_id", "event_type", "occurred_at" ], "properties": { "event_uuid": { "type": "string", "description": "Unique client- or server-generated identifier for this event." }, "run_id": { "type": "string", "description": "Run that owns this event." }, "execution_id": { "type": "integer", "format": "int64", "description": "Run execution associated with this event, when available." }, "event_type": { "$ref": "#/components/schemas/AIRunTimelineEventType" }, "occurred_at": { "type": "string", "format": "date-time", "description": "Timestamp when the event occurred." }, "payload": { "type": "object", "additionalProperties": true, "description": "Optional event-specific JSON payload. Contents vary by event type." } } }, "AIRunTimelineEventType": { "type": "string", "description": "Type of timeline event recorded for a run.", "enum": [ "oz_run_created", "oz_run_claimed", "worker_container_ready", "shared_session_started", "agent_started", "oz_run_done", "oz_run_blocked", "oz_run_cancelled", "oz_run_failed", "oz_run_errored", "vm_shutdown" ] }, "ConversationResponse": { "type": "object", "required": [ "conversation_id", "steps" ], "properties": { "conversation_id": { "type": "string", "description": "Unique identifier for the conversation" }, "steps": { "type": "array", "description": "Root steps in the conversation", "items": { "$ref": "#/components/schemas/ConversationStep" } } } }, "ConversationStep": { "type": "object", "required": [ "id", "messages", "steps" ], "properties": { "id": { "type": "string", "description": "Unique identifier for the step" }, "description": { "type": "string", "description": "Original instruction or delegated work description for the step" }, "summary": { "type": "string", "description": "Summary of the work completed for the step" }, "started_at": { "type": "string", "format": "date-time", "description": "Earliest transcript message timestamp contained in this step or any nested step (RFC3339)" }, "completed_at": { "type": "string", "format": "date-time", "description": "Latest transcript message timestamp contained in this step or any nested step (RFC3339)" }, "messages": { "type": "array", "description": "Ordered normalized messages for this step", "items": { "$ref": "#/components/schemas/ConversationMessage" } }, "steps": { "type": "array", "description": "Nested delegated work performed as part of this step", "items": { "$ref": "#/components/schemas/ConversationStep" } } } }, "ConversationMessage": { "type": "object", "required": [ "role", "content" ], "properties": { "message_ids": { "type": "array", "description": "Underlying transcript message IDs grouped into this normalized message", "items": { "type": "string" } }, "request_id": { "type": "string", "description": "Request identifier shared by transcript messages from the same request, when available" }, "role": { "$ref": "#/components/schemas/ConversationMessageRole" }, "timestamp": { "type": "string", "format": "date-time", "description": "Timestamp of the first transcript message included in this normalized message (RFC3339)" }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationContentBlock" } } } }, "ConversationMessageRole": { "type": "string", "description": "Role of the normalized message", "enum": [ "user", "assistant", "tool", "system" ] }, "ConversationContentBlock": { "oneOf": [ { "$ref": "#/components/schemas/TextContentBlock" }, { "$ref": "#/components/schemas/ActionContentBlock" }, { "$ref": "#/components/schemas/ActionResultContentBlock" }, { "$ref": "#/components/schemas/EventContentBlock" } ], "discriminator": { "propertyName": "type", "mapping": { "text": "#/components/schemas/TextContentBlock", "action": "#/components/schemas/ActionContentBlock", "action_result": "#/components/schemas/ActionResultContentBlock", "event": "#/components/schemas/EventContentBlock" } } }, "TextContentBlock": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "text" ] }, "message_id": { "type": "string", "description": "Underlying transcript message ID that produced this content block, when available" }, "text": { "type": "string", "description": "Plain text content" } } }, "ActionCategory": { "type": "string", "description": "High-level category of an action performed during the conversation", "enum": [ "command", "files", "search", "integration", "documents", "computer", "review", "skill" ] }, "ActionState": { "type": "string", "description": "State of an action result", "enum": [ "running", "completed", "failed", "denied" ] }, "ActionContentBlock": { "type": "object", "required": [ "type", "id", "category", "name", "input" ], "properties": { "type": { "type": "string", "enum": [ "action" ] }, "message_id": { "type": "string", "description": "Underlying transcript message ID that produced this content block, when available" }, "id": { "type": "string", "description": "Unique identifier for the action" }, "category": { "$ref": "#/components/schemas/ActionCategory" }, "name": { "type": "string", "description": "Public action name, such as run_command or edit_files" }, "input": { "type": "object", "additionalProperties": true, "description": "Curated public input for this action. This object is owned by the API and is not a raw internal tool payload." } } }, "ActionResultContentBlock": { "type": "object", "required": [ "type", "action_id", "category", "name", "state", "output" ], "properties": { "type": { "type": "string", "enum": [ "action_result" ] }, "message_id": { "type": "string", "description": "Underlying transcript message ID that produced this content block, when available" }, "action_id": { "type": "string", "description": "Identifier of the corresponding action" }, "category": { "$ref": "#/components/schemas/ActionCategory" }, "name": { "type": "string", "description": "Public action name matching the corresponding action block" }, "state": { "$ref": "#/components/schemas/ActionState" }, "output": { "type": "object", "additionalProperties": true, "description": "Curated public result for this action. Large or binary internal payloads should be summarized rather than passed through raw." } } }, "EventContentBlock": { "type": "object", "required": [ "type", "name", "data" ], "properties": { "type": { "type": "string", "enum": [ "event" ] }, "message_id": { "type": "string", "description": "Underlying transcript message ID that produced this content block, when available" }, "name": { "type": "string", "description": "Event type for intentionally exposed non-core transcript events" }, "data": { "type": "object", "additionalProperties": true, "description": "Minimal structured metadata for the event" } } }, "ArtifactItem": { "oneOf": [ { "$ref": "#/components/schemas/PlanArtifact" }, { "$ref": "#/components/schemas/PullRequestArtifact" }, { "$ref": "#/components/schemas/ScreenshotArtifact" }, { "$ref": "#/components/schemas/FileArtifact" }, { "$ref": "#/components/schemas/ExternalReferenceArtifact" } ], "discriminator": { "propertyName": "artifact_type", "mapping": { "PLAN": "#/components/schemas/PlanArtifact", "PULL_REQUEST": "#/components/schemas/PullRequestArtifact", "SCREENSHOT": "#/components/schemas/ScreenshotArtifact", "FILE": "#/components/schemas/FileArtifact", "EXTERNAL_REFERENCE": "#/components/schemas/ExternalReferenceArtifact" } } }, "ExternalReferenceArtifact": { "type": "object", "required": [ "artifact_type", "created_at", "data" ], "properties": { "artifact_type": { "type": "string", "enum": [ "EXTERNAL_REFERENCE" ], "description": "Type of the artifact" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the artifact was created (RFC3339)" }, "data": { "$ref": "#/components/schemas/ExternalReferenceArtifactData" } } }, "PlanArtifact": { "type": "object", "required": [ "artifact_type", "created_at", "data" ], "properties": { "artifact_type": { "type": "string", "enum": [ "PLAN" ], "description": "Type of the artifact" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the artifact was created (RFC3339)" }, "data": { "$ref": "#/components/schemas/PlanArtifactData" } } }, "PullRequestArtifact": { "type": "object", "required": [ "artifact_type", "created_at", "data" ], "properties": { "artifact_type": { "type": "string", "enum": [ "PULL_REQUEST" ], "description": "Type of the artifact" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the artifact was created (RFC3339)" }, "data": { "$ref": "#/components/schemas/PullRequestArtifactResponseData" } } }, "ScreenshotArtifact": { "type": "object", "required": [ "artifact_type", "created_at", "data" ], "properties": { "artifact_type": { "type": "string", "enum": [ "SCREENSHOT" ], "description": "Type of the artifact" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the artifact was created (RFC3339)" }, "data": { "$ref": "#/components/schemas/ScreenshotArtifactData" } } }, "FileArtifact": { "type": "object", "required": [ "artifact_type", "created_at", "data" ], "properties": { "artifact_type": { "type": "string", "enum": [ "FILE" ], "description": "Type of the artifact" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the artifact was created (RFC3339)" }, "data": { "$ref": "#/components/schemas/FileArtifactData" } } }, "PlanArtifactData": { "type": "object", "required": [ "document_uid" ], "properties": { "artifact_uid": { "type": "string", "description": "Unique identifier for the plan artifact, usable with the artifact retrieval endpoint" }, "document_uid": { "type": "string", "description": "Unique identifier for the plan document" }, "notebook_uid": { "type": "string", "description": "Unique identifier for the associated notebook" }, "url": { "type": "string", "format": "uri", "description": "URL to open the plan in Warp Drive" }, "title": { "type": "string", "description": "Title of the plan" } } }, "PullRequestArtifactData": { "type": "object", "required": [ "url", "branch" ], "properties": { "url": { "type": "string", "format": "uri", "description": "URL of the pull request" }, "branch": { "type": "string", "description": "Branch name for the pull request" } } }, "PullRequestArtifactResponseData": { "allOf": [ { "$ref": "#/components/schemas/PullRequestArtifactData" }, { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "description": "Current state of the pull request as last reported by the code\nhost's webhooks. `unknown` means Warp has no live provider\nrecord for this pull request (for example, the repository's\ncode host integration is not connected to the run's team).\n", "enum": [ "open", "draft", "merged", "closed", "unknown" ] } } } ] }, "ScreenshotArtifactData": { "type": "object", "required": [ "artifact_uid", "mime_type" ], "properties": { "artifact_uid": { "type": "string", "description": "Unique identifier for the screenshot artifact" }, "mime_type": { "type": "string", "description": "MIME type of the screenshot image" }, "description": { "type": "string", "description": "Optional description of the screenshot" } } }, "FileArtifactData": { "type": "object", "required": [ "artifact_uid", "filepath", "filename", "mime_type" ], "properties": { "artifact_uid": { "type": "string", "description": "Unique identifier for the file artifact" }, "filepath": { "type": "string", "description": "Conversation-relative filepath for the uploaded file. Omitted on\nan anonymous read of a public file artifact.\n" }, "filename": { "type": "string", "description": "Last path component of filepath" }, "title": { "type": "string", "description": "Short, badge-visible label for the artifact. For recording artifacts,\nthis is the agent-authored title shown in Warp web and blocklist badges.\nDistinct from description, which is longer and shown in detail views.\n" }, "description": { "type": "string", "description": "Optional description of the file" }, "mime_type": { "type": "string", "description": "MIME type of the uploaded file" }, "size_bytes": { "type": "integer", "format": "int64", "description": "Size of the uploaded file in bytes" }, "thumbnail": { "$ref": "#/components/schemas/FileArtifactThumbnail" } } }, "FileArtifactThumbnail": { "type": "object", "required": [ "download_url", "expires_at" ], "properties": { "download_url": { "type": "string", "format": "uri", "description": "Time-limited signed URL to download the video's thumbnail image" }, "expires_at": { "type": "string", "format": "date-time", "description": "Timestamp when the thumbnail download URL expires (RFC3339)" } } }, "ScheduleInfo": { "type": "object", "description": "Information about the schedule that triggered this run (only present for scheduled runs)", "required": [ "schedule_id", "schedule_name", "cron_schedule" ], "properties": { "schedule_id": { "type": "string", "description": "Unique identifier for the schedule" }, "schedule_name": { "type": "string", "description": "Name of the schedule at the time the run was created" }, "cron_schedule": { "type": "string", "description": "Cron expression at the time the run was created" } } }, "PageInfo": { "type": "object", "required": [ "has_next_page" ], "properties": { "has_next_page": { "type": "boolean", "description": "Whether there are more results available" }, "next_cursor": { "type": "string", "description": "Opaque cursor for fetching the next page" } } }, "RunStatusMessage": { "type": "object", "description": "Status message for a run. For terminal error states, includes structured\nerror code and retryability info from the platform error catalog.\n", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "Human-readable status message" }, "error_code": { "$ref": "#/components/schemas/PlatformErrorCode" }, "retryable": { "type": "boolean", "description": "Whether the error is transient and the client may retry by submitting\na new run. Only present on terminal error states. When false, retrying\nwithout addressing the underlying cause will not succeed.\n" }, "session_debug_until": { "type": "string", "format": "date-time", "description": "When a failed run's shared session stops being held open for debugging.\nOnly present while that window is open.\n\nThe window is an idle window owned by the agent process: activity in the\nsession pushes this deadline out. The agent republishes it periodically\nrather than on every keystroke, so the value can lag the true deadline by\nup to a throttle interval, and always in the conservative direction.\n" }, "debug_agent_active": { "type": "boolean", "description": "Whether a setup-failure debug turn is actively pinning the idle timer open\nright now. While true, session_debug_until can lag behind the real deadline;\nclients should show an active-debugging state instead of a countdown.\n" } } }, "RequestUsage": { "type": "object", "description": "Resource usage information for the run", "properties": { "inference_cost": { "type": "number", "format": "double", "description": "Credits consumed by LLM inference for the run" }, "compute_cost": { "type": "number", "format": "double", "description": "Credits consumed by compute resources for the run" }, "platform_cost": { "type": "number", "format": "double", "description": "Credits consumed by platform usage for the run" }, "inference_cost_usd": { "type": "number", "format": "double", "description": "What the run's LLM inference was billed at, in US dollars. Runs that\npredate billed-amount tracking fall back to an estimated cost.\n" }, "compute_cost_usd": { "type": "number", "format": "double", "description": "What the run's hosted compute was billed at, in US dollars. Runs that\npredate billed-amount tracking fall back to an estimated cost.\n" }, "platform_cost_usd": { "type": "number", "format": "double", "description": "What the run's platform usage was billed at, in US dollars. Runs that\npredate billed-amount tracking fall back to an estimated cost.\n" }, "total_tokens": { "type": "integer", "format": "int64", "description": "Total LLM token count (summed across every usage category and model) for the run's\nconversation. Omitted when the data is not available.\n" }, "usage_by_category": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ChargedUsageDetail" }, "description": "Full-granularity token and charged-cost breakdown for the run's\nconversation, keyed by usage category (for example,\nprimary_agent or conversation_compaction) and model id. Omitted\nwhen the data is not available.\n" }, "model_token_usage": { "type": "array", "items": { "$ref": "#/components/schemas/ModelTokenUsage" }, "description": "The models that actually served inference for the run, with the\ntokens each consumed. Used to discover what an auto-routing model\nresolves to. If a run is terminated before inference is complete,\noutput a zero-token entry for that model. Omits runs that use\na third-party harness, whose per-model usage is not tracked by Warp.\n" } } }, "ModelTokenUsage": { "type": "object", "description": "Tokens consumed by a single model over a run.\n", "required": [ "model_id", "total_tokens", "usage_type" ], "properties": { "model_id": { "type": "string", "description": "Identifier of the model that served the inference. For `warp` and\n`byok` usage this is a model id drawn from the same set as\n`agent_config.model_id`. For `custom_endpoint` usage this is the\ncaller's own configuration key for the endpoint.\n" }, "total_tokens": { "type": "integer", "format": "int64", "description": "Total tokens this model consumed, across every usage category." }, "usage_type": { "$ref": "#/components/schemas/ModelUsageType" }, "tokens_by_category": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64" }, "description": "total_tokens split by the kind of work the tokens were spent on,\nkeyed by usage category (e.g., primary_agent, tool_summarization, etc).\n" } } }, "ModelUsageType": { "type": "string", "description": "How a model's inference was accessed:\n- warp: through Warp-provided model access\n- byok: through the caller's own provider API key\n- custom_endpoint: through a caller-configured model endpoint\n", "enum": [ "warp", "byok", "custom_endpoint" ] }, "InferenceCostBreakdownInCents": { "type": "object", "description": "Charged cost of LLM inference in US cents, split by token type.\nOmitted when the data is not available.\n", "required": [ "input_cost_in_cents", "input_cache_read_cost_in_cents", "input_cache_write_cost_in_cents", "output_cost_in_cents" ], "properties": { "input_cost_in_cents": { "type": "number", "format": "double", "description": "Cost of non-cached input tokens, in US cents." }, "input_cache_read_cost_in_cents": { "type": "number", "format": "double", "description": "Cost of cache-read input tokens, in US cents." }, "input_cache_write_cost_in_cents": { "type": "number", "format": "double", "description": "Cost of cache-write input tokens, in US cents." }, "output_cost_in_cents": { "type": "number", "format": "double", "description": "Cost of output tokens, in US cents." } } }, "TokenCountBreakdown": { "type": "object", "description": "A per-token-type token count.", "required": [ "input", "output", "input_cache_read", "input_cache_write" ], "properties": { "input": { "type": "integer", "format": "int64", "description": "Count of non-cached input tokens." }, "output": { "type": "integer", "format": "int64", "description": "Count of output tokens." }, "input_cache_read": { "type": "integer", "format": "int64", "description": "Count of cache-read input tokens." }, "input_cache_write": { "type": "integer", "format": "int64", "description": "Count of cache-write input tokens." } } }, "InferenceUsageDetail": { "type": "object", "description": "Full token count and charged-cost detail for inference usage.\nThe counts and cost describe the same usage (e.g. token_count.input\ntokens cost cost_in_cents.input_cost_in_cents in total).\n", "required": [ "token_count", "cost_in_cents", "web_search_count", "web_search_cost_in_cents" ], "properties": { "token_count": { "$ref": "#/components/schemas/TokenCountBreakdown" }, "cost_in_cents": { "$ref": "#/components/schemas/InferenceCostBreakdownInCents" }, "web_search_count": { "type": "integer", "format": "int64", "description": "Number of web searches performed by this model." }, "web_search_cost_in_cents": { "type": "number", "format": "double", "description": "Total cost of those web searches, in US cents." } } }, "ChargedUsageDetail": { "type": "object", "description": "Usage charged for a single usage category, broken down by usage type\n(direct API/BYOK/custom endpoint) and, within each, by model ID.\n", "required": [ "platform_usage_in_cents" ], "properties": { "direct_api_inference_usage": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/InferenceUsageDetail" }, "description": "Inference usage incurred through Warp-provided model access, keyed by model ID." }, "byok_inference_usage": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/InferenceUsageDetail" }, "description": "Inference usage charged using a user's own API key, keyed by model ID." }, "custom_endpoint_inference_usage": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/InferenceUsageDetail" }, "description": "Inference usage charged using a custom endpoint, keyed by the\ncustom model's config key.\n" }, "platform_usage_in_cents": { "type": "number", "format": "double", "description": "Platform usage charged for this category, in US cents." } } }, "RunCreatorInfo": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user", "service_account" ], "description": "Type of the creator principal" }, "uid": { "type": "string", "description": "Unique identifier of the creator" }, "display_name": { "type": "string", "description": "Display name of the creator" }, "email": { "type": "string", "description": "Email address of the creator" }, "photo_url": { "type": "string", "format": "uri", "description": "URL to the creator's photo" } } }, "RunState": { "type": "string", "enum": [ "QUEUED", "PENDING", "CLAIMED", "INPROGRESS", "SUCCEEDED", "FAILED", "BLOCKED", "ERROR", "CANCELLED" ], "description": "Current state of the run:\n- QUEUED: Run is waiting to be picked up\n- PENDING: Run is being prepared\n- CLAIMED: Run has been claimed by a worker\n- INPROGRESS: Run is actively being executed\n- SUCCEEDED: Run completed successfully\n- FAILED: Run failed\n- BLOCKED: Run is blocked (e.g., awaiting user input or approval)\n- ERROR: Run encountered an error\n- CANCELLED: Run was cancelled by user\n" }, "RunSourceType": { "type": "string", "enum": [ "LINEAR", "API", "MCP", "SLACK", "TEAMS", "LOCAL", "SCHEDULED_AGENT", "WEB_APP", "GITHUB_ACTION", "CLOUD_MODE", "CLI", "JIRA", "SELF_IMPROVEMENT", "GITHUB_WEBHOOK", "GITLAB_WEBHOOK", "AZURE_DEVOPS_WEBHOOK", "AUTOFIX", "RUN_SCORER", "ORCHESTRATION", "BENCHMARK_TRIAL", "CREATE_BENCHMARK_TASK", "CUSTOM_WEBHOOK" ], "description": "Source that created the run:\n- LINEAR: Created from Linear integration\n- API: Created via the Warp API\n- MCP: Created through the Factory MCP server's send_task tool\n- SLACK: Created from Slack integration\n- TEAMS: Created from Microsoft Teams integration\n- LOCAL: Created from local CLI/app\n- SCHEDULED_AGENT: Created by a scheduled agent\n- WEB_APP: Created from the Warp web app\n- GITHUB_ACTION: Created from a GitHub action\n- CLOUD_MODE: Created from a Cloud Mode\n- CLI: Created from the CLI\n- JIRA: Created from Jira integration\n- SELF_IMPROVEMENT: Created by Warp's self-improvement pipeline\n- GITHUB_WEBHOOK: Created from a GitHub webhook event\n- GITLAB_WEBHOOK: Created from a GitLab webhook event\n- AZURE_DEVOPS_WEBHOOK: Created from an Azure DevOps webhook event\n- AUTOFIX: Created by Warp's autofix pipeline\n- RUN_SCORER: Created by Warp's run-scoring judge\n- ORCHESTRATION: Created as a child run by the orchestration layer (parent_run_id set)\n- BENCHMARK_TRIAL: Created as a factory benchmark trial\n- CREATE_BENCHMARK_TASK: Created by a Factory foreman authoring a benchmark task from a completed run\n- CUSTOM_WEBHOOK: Created by a factory automation subscribed to a custom webhook source" }, "RunExecutionLocation": { "type": "string", "enum": [ "LOCAL", "REMOTE" ], "description": "Where the run executed:\n- LOCAL: Executed in the user's local Warp environment\n- REMOTE: Executed by a remote/cloud worker\n" }, "AmbientAgentConfig": { "type": "object", "description": "Configuration for a cloud agent run", "properties": { "name": { "type": "string", "description": "Human-readable label for grouping, filtering, and traceability.\nAutomatically set to the skill name when running a skill-based agent.\nSet this explicitly to categorize runs by intent (e.g., \"nightly-dependency-check\")\nso you can filter and track them via the name query parameter on GET /agent/runs.\n" }, "model_id": { "type": "string", "description": "LLM model to use (uses team default if not specified)" }, "base_prompt": { "type": "string", "description": "Custom base prompt for the agent" }, "environment_id": { "type": "string", "description": "UID of the environment to run the agent in" }, "secrets": { "type": "array", "items": { "$ref": "#/components/schemas/SecretRef" }, "description": "Optional run-specific managed secret allowlist. Omission and an\nempty array both add no generic secrets. Secret references from\nthe resolved environment and execution principal are still\nunioned into the run's secret scope.\n" }, "runner_id": { "type": "string", "description": "UID of the runner providing the run's compute (platform, instance\nshape, and setup commands). When omitted on a request, the runner is\nresolved at run creation from the agent's default runner, then the\nenvironment's default runner, and the resolved UID is recorded on\nthe run.\n" }, "skill_spec": { "type": "string", "description": "Skill specification identifying the primary agent skill to use,\nin `{owner}/{repo}:{skill_path}` format (e.g.\n`warpdotdev/warp-server:.claude/skills/deploy/SKILL.md`);\nmutually exclusive with `skills` in create/update requests.\nResponses include the first `skills` entry here for backward\ncompatibility; use the list agents endpoint to discover\navailable skills.\n" }, "skills": { "type": "array", "items": { "type": "string" }, "description": "Ordered skill specifications to attach to the run.\nFormat: \"{owner}/{repo}:{skill_path}\"\nExample: \"warpdotdev/warp-server:.claude/skills/deploy/SKILL.md\"\nMutually exclusive with skill_spec in create/update requests.\n" }, "mcp_servers": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/MCPServerConfig" }, "description": "Map of MCP server configurations by name" }, "computer_use_enabled": { "type": "boolean", "description": "Controls whether computer use is enabled for this agent.\nIf not set, defaults to true.\n" }, "computer_use_model_id": { "type": "string", "description": "Model the computer use subagent runs on; if omitted, the subagent\npicks its own model automatically. Only applies to the built-in\nWarp harness — the value is accepted but has no effect under a\nthird-party harness or when computer use is disabled. Requires an\nagent CLI version that supports the --computer-use-model flag.\n" }, "idle_timeout_minutes": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 60, "description": "Number of minutes to keep the agent environment alive after task completion.\nSet to 0 to shut down immediately after task completion.\nIf not set, defaults to 10 minutes.\nMaximum allowed value is min(60, floor(max_instance_runtime_seconds / 60) for your billing tier).\n" }, "worker_host": { "type": "string", "description": "Self-hosted worker ID that should execute this task.\nIf not specified or set to \"warp\", the task runs on Warp-hosted workers.\n" }, "harness": { "$ref": "#/components/schemas/Harness" }, "harness_auth_secrets": { "$ref": "#/components/schemas/HarnessAuthSecrets" }, "session_sharing": { "$ref": "#/components/schemas/SessionSharingConfig" }, "memory_stores": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryStoreRef" }, "description": "Memory stores to attach to this run." }, "inference_providers": { "allOf": [ { "$ref": "#/components/schemas/InferenceProvidersConfig" } ], "description": "Optional inference provider settings for this run. Run-level\nconfig takes precedence over the agent's stored config and\nthe workspace's admin-configured defaults.\n" }, "credential_strategy": { "type": "string", "nullable": true, "enum": [ "CREATOR", "EXECUTOR" ], "description": "Controls which principal's credentials are used when the\nplatform mints tokens (e.g. GitHub or GitLab OAuth tokens) on\nbehalf of this run.\n- EXECUTOR (default when unset): credentials are sourced from\n the run's execution principal — a GitHub App installation\n token for agent principals, a personal OAuth token for user\n principals.\n- CREATOR: credentials are always sourced from the run creator\n regardless of the execution principal, useful when a service\n account executes the run but Git operations should\n authenticate as the triggering human.\n" } } }, "SessionSharingConfig": { "type": "object", "description": "Configures sharing behavior for the run's shared session; when set,\nthe worker emits `--share public:` and the bundled Warp\nclient applies an anyone-with-link ACL to the shared session once it\nhas bootstrapped. The same ACL is mirrored onto the backing\nconversation so link viewers can read it without being on the run's\nteam, subject to the workspace-level anyone-with-link sharing\nsetting.\n", "properties": { "public_access": { "type": "string", "enum": [ "VIEWER", "EDITOR" ], "description": "Grants anyone-with-link access at the specified level to the\nrun's shared session and backing conversation; link viewers\nmust still be authenticated Warp users (anonymous reads are not\nsupported in this release).\n- VIEWER: link viewers can read the session and conversation.\n- EDITOR: link viewers can also interact with the session.\n" } } }, "Harness": { "type": "object", "description": "Specifies which execution harness to use for the agent run.\nDefault (nil/empty) uses Warp's built-in harness.\nWhen stored as a named agent's default (create/update agent identity),\nthis field replaces the deprecated base_harness/base_model pair: a\nharness other than `oz` here requires the agent's base_model to be\nempty, since the two describe mutually exclusive default models.\n", "properties": { "type": { "type": "string", "enum": [ "oz", "claude", "gemini", "codex" ], "description": "The harness type identifier.\n- oz: Warp's built-in harness (default)\n- claude: Claude Code harness\n- gemini: Gemini CLI harness\n- codex: Codex CLI harness\n" }, "model_id": { "type": "string", "description": "Model to use with a third-party harness (e.g. \"claude-haiku-4-5\").\nOnly applies when type is a harness other than `oz`; the\ntop-level config model_id targets the built-in Warp harness\ninstead. When omitted or empty, the harness uses its own default\nmodel.\nFor an individual Warp-managed Factory Claude Code agent, send\nan explicit empty string to use the environment's model. Omitting\nmodel_id when replacing that agent's harness is invalid.\n" }, "reasoning_level": { "type": "string", "description": "Reasoning effort for harnesses that support it (e.g. Codex).\nOnly applies when type is a harness other than `oz`. Ignored by\nharnesses that do not support reasoning levels.\n" } } }, "HarnessAuthSecrets": { "type": "object", "description": "Authentication secrets for third-party harnesses.\nOnly the secret for the harness specified gets injected into the environment.\n", "properties": { "claude_auth_secret_name": { "type": "string", "description": "Name of a managed secret for Claude Code harness authentication.\nThe secret must exist within the caller's personal or team scope.\nOnly applicable when harness type is \"claude\".\n" }, "codex_auth_secret_name": { "type": "string", "description": "Name of a managed secret for Codex harness authentication.\nThe secret must exist within the caller's personal or team scope.\nOnly applicable when harness type is \"codex\".\n" } } }, "MCPServerConfig": { "type": "object", "description": "Configuration for an MCP server. Must have exactly one of: warp_id, command, or url.\n", "properties": { "warp_id": { "type": "string", "description": "Reference to a Warp shared MCP server by UUID, or a well-known\nintegration MCP id (e.g. \"linear\") backed by the team's integration\nconnection.\n" }, "command": { "type": "string", "description": "Stdio transport - command to run" }, "args": { "type": "array", "items": { "type": "string" }, "description": "Stdio transport - command arguments" }, "url": { "type": "string", "format": "uri", "description": "SSE/HTTP transport - server URL" }, "env": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Environment variables for the server" }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "HTTP headers for SSE/HTTP transport" } } }, "Error": { "type": "object", "description": "Error response following RFC 7807 (Problem Details for HTTP APIs),\nusing the `application/problem+json` content type. Includes\nbackward-compatible extension members; additional ones (e.g.,\n`auth_url`, `provider`) may be present depending on the error code.\n", "required": [ "type", "title", "status", "error" ], "properties": { "type": { "type": "string", "format": "uri", "description": "A URI reference that identifies the problem type (RFC 7807).\nFormat: `https://docs.warp.dev/factories/api-and-sdk/troubleshooting/errors/{error_code}`\nSee PlatformErrorCode for the list of possible error codes.\n" }, "title": { "type": "string", "description": "A short, human-readable summary of the problem type (RFC 7807)" }, "status": { "type": "integer", "description": "The HTTP status code for this occurrence of the problem (RFC 7807)" }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence of the problem (RFC 7807)" }, "instance": { "type": "string", "description": "The request path that generated this error (RFC 7807)" }, "error": { "type": "string", "description": "Human-readable error message combining title and detail.\nBackward-compatible extension member for older clients.\n" }, "retryable": { "type": "boolean", "description": "Whether the request can be retried. When true, the error is transient\nand the request may be retried. When false, retrying without addressing\nthe underlying cause will not succeed.\n" }, "trace_id": { "type": "string", "description": "OpenTelemetry trace ID for debugging and support requests" }, "provider": { "type": "string", "description": "External provider that requires authorization, such as `linear`." }, "auth_url": { "type": "string", "format": "uri", "description": "URL where the caller can reconnect the external provider." } } }, "ArtifactResponse": { "oneOf": [ { "$ref": "#/components/schemas/PlanArtifactResponse" }, { "$ref": "#/components/schemas/ScreenshotArtifactResponse" }, { "$ref": "#/components/schemas/FileArtifactResponse" } ], "discriminator": { "propertyName": "artifact_type", "mapping": { "PLAN": "#/components/schemas/PlanArtifactResponse", "SCREENSHOT": "#/components/schemas/ScreenshotArtifactResponse", "FILE": "#/components/schemas/FileArtifactResponse" } } }, "PlanArtifactResponse": { "type": "object", "description": "Response for retrieving a plan artifact.", "required": [ "artifact_uid", "artifact_type", "created_at", "data" ], "properties": { "artifact_uid": { "type": "string", "description": "Unique identifier (UUID) for the artifact" }, "artifact_type": { "type": "string", "enum": [ "PLAN" ], "description": "Type of the artifact" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the artifact was created (RFC3339)" }, "data": { "$ref": "#/components/schemas/PlanArtifactResponseData" } } }, "PlanArtifactResponseData": { "type": "object", "description": "Response data for a plan artifact, including current markdown content.", "required": [ "document_uid", "notebook_uid", "content", "content_type" ], "properties": { "document_uid": { "type": "string", "description": "Unique identifier for the plan document" }, "notebook_uid": { "type": "string", "description": "Unique identifier for the associated notebook" }, "url": { "type": "string", "format": "uri", "description": "URL to open the plan in Warp Drive" }, "title": { "type": "string", "description": "Current title of the plan" }, "content": { "type": "string", "description": "Current markdown content of the plan" }, "content_type": { "type": "string", "description": "MIME type of the returned plan content" } } }, "ScreenshotArtifactResponse": { "type": "object", "description": "Response for retrieving a screenshot artifact.", "required": [ "artifact_uid", "artifact_type", "created_at", "data" ], "properties": { "artifact_uid": { "type": "string", "description": "Unique identifier (UUID) for the artifact" }, "artifact_type": { "type": "string", "enum": [ "SCREENSHOT" ], "description": "Type of the artifact" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the artifact was created (RFC3339)" }, "source_links": { "$ref": "#/components/schemas/ArtifactSourceLinksResponse" }, "data": { "$ref": "#/components/schemas/ScreenshotArtifactResponseData" } } }, "ArtifactSourceLinksResponse": { "type": "object", "description": "Links to the originating run and pull requests reported in its tree. Destinations enforce their own access rules.", "properties": { "run_url": { "type": "string", "format": "uri", "description": "Factory run page for the originating root run, when bound to a live Factory task." }, "pull_request_urls": { "type": "array", "items": { "type": "string", "format": "uri" }, "description": "Distinct pull requests reported by runs in the same tree." } } }, "ScreenshotArtifactResponseData": { "type": "object", "description": "Response data for a screenshot artifact, including a signed download URL.", "required": [ "download_url", "expires_at", "content_type" ], "properties": { "download_url": { "type": "string", "format": "uri", "description": "Time-limited signed URL to download the screenshot" }, "expires_at": { "type": "string", "format": "date-time", "description": "Timestamp when the download URL expires (RFC3339)" }, "content_type": { "type": "string", "description": "MIME type of the screenshot (e.g., image/png)" }, "description": { "type": "string", "description": "Optional description of the screenshot" } } }, "FileArtifactResponse": { "type": "object", "description": "Response for retrieving a file artifact.", "required": [ "artifact_uid", "artifact_type", "created_at", "data" ], "properties": { "artifact_uid": { "type": "string", "description": "Unique identifier (UUID) for the artifact" }, "artifact_type": { "type": "string", "enum": [ "FILE" ], "description": "Type of the artifact" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the artifact was created (RFC3339)" }, "source_links": { "$ref": "#/components/schemas/ArtifactSourceLinksResponse" }, "data": { "$ref": "#/components/schemas/FileArtifactResponseData" } } }, "FileArtifactResponseData": { "type": "object", "description": "Response data for a file artifact, including a signed download URL.", "required": [ "download_url", "expires_at", "content_type", "filename" ], "properties": { "download_url": { "type": "string", "format": "uri", "description": "Time-limited signed URL to download the file" }, "expires_at": { "type": "string", "format": "date-time", "description": "Timestamp when the download URL expires (RFC3339)" }, "content_type": { "type": "string", "description": "MIME type of the uploaded file" }, "filepath": { "type": "string", "description": "Conversation-relative filepath for the uploaded file. Omitted for\nanonymous reads of public artifacts.\n" }, "filename": { "type": "string", "description": "Last path component of filepath" }, "title": { "type": "string", "description": "Short, badge-visible label for the artifact. For recording artifacts,\nthis is the agent-authored title shown in Warp web and blocklist badges.\nDistinct from description, which is longer and shown in detail views.\n" }, "description": { "type": "string", "description": "Optional description of the file" }, "size_bytes": { "type": "integer", "format": "int64", "description": "Size of the uploaded file in bytes" } } }, "AttachmentInput": { "type": "object", "description": "A base64-encoded file attachment to include with the prompt", "required": [ "file_name", "mime_type", "data" ], "properties": { "file_name": { "type": "string", "description": "Name of the attached file" }, "mime_type": { "type": "string", "description": "MIME type of the attachment.\nSupported image types: image/jpeg, image/png, image/gif, image/webp\n" }, "data": { "type": "string", "format": "byte", "description": "Base64-encoded attachment data" } } }, "ScheduledAgentItem": { "type": "object", "required": [ "id", "name", "cron_schedule", "enabled", "prompt", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "description": "Unique identifier for the scheduled agent" }, "name": { "type": "string", "description": "Human-readable name for the schedule" }, "cron_schedule": { "type": "string", "description": "Cron expression defining when the agent runs (e.g., \"0 9 * * *\" for daily at 9am UTC)" }, "enabled": { "type": "boolean", "description": "Whether the schedule is currently active" }, "prompt": { "type": "string", "description": "The prompt/instruction for the agent to execute" }, "last_spawn_error": { "type": "string", "nullable": true, "description": "Error message from the last failed spawn attempt, if any" }, "agent_config": { "$ref": "#/components/schemas/AmbientAgentConfig" }, "agent_uid": { "type": "string", "format": "uuid", "description": "UID of the agent that this schedule runs as" }, "metadata": { "allOf": [ { "$ref": "#/components/schemas/RunMetadata" } ], "description": "Custom metadata stamped onto every run spawned by this schedule" }, "environment": { "allOf": [ { "$ref": "#/components/schemas/CloudEnvironmentConfig" } ], "description": "Resolved environment configuration (if agent_config references an environment_id)" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the schedule was created (RFC3339)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the schedule was last updated (RFC3339)" }, "created_by": { "$ref": "#/components/schemas/RunCreatorInfo" }, "updated_by": { "$ref": "#/components/schemas/RunCreatorInfo" }, "history": { "$ref": "#/components/schemas/ScheduledAgentHistoryItem" }, "scope": { "$ref": "#/components/schemas/Scope" } } }, "ScheduledAgentHistoryItem": { "type": "object", "description": "Scheduler-derived history metadata for a scheduled agent", "properties": { "last_ran": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp of the last successful run (RFC3339)" }, "next_run": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp of the next scheduled run (RFC3339)" } } }, "CreateScheduledAgentRequest": { "type": "object", "description": "Request body for creating a new scheduled agent.\nEither prompt or agent_config.skill_spec or agent_config.skills is required.\n", "required": [ "name", "cron_schedule" ], "properties": { "name": { "type": "string", "description": "Human-readable name for the schedule" }, "cron_schedule": { "type": "string", "description": "Cron expression defining when the agent runs (e.g., \"0 9 * * *\" for daily at 9am UTC)" }, "prompt": { "type": "string", "description": "The prompt/instruction for the agent to execute.\nRequired unless agent_config.skill_spec or agent_config.skills is provided.\n" }, "mode": { "$ref": "#/components/schemas/AgentRunMode", "description": "Optional query mode applied to every triggered run. Defaults to\n`normal` when omitted. The server does not infer mode from prompt\nprefixes such as `/plan`.\n" }, "enabled": { "type": "boolean", "description": "Whether the schedule should be active immediately", "default": true }, "agent_uid": { "type": "string", "format": "uuid", "description": "Agent UID to use as the execution principal for this schedule.\nOnly valid for team-owned schedules.\n" }, "agent_config": { "$ref": "#/components/schemas/AmbientAgentConfig" }, "team": { "type": "boolean", "description": "Whether to create a team-owned schedule.\nDefaults to true for users on a single team.\n" }, "metadata": { "allOf": [ { "$ref": "#/components/schemas/RunMetadata" } ], "description": "Custom metadata stamped onto every run spawned by this schedule as the run's\nexplicit metadata layer.\n" } } }, "UpdateScheduledAgentRequest": { "type": "object", "description": "Request body for updating a scheduled agent.\nEither prompt or agent_config.skill_spec or agent_config.skills is required.\n", "required": [ "name", "cron_schedule", "enabled" ], "properties": { "name": { "type": "string", "description": "Human-readable name for the schedule" }, "cron_schedule": { "type": "string", "description": "Cron expression defining when the agent runs" }, "prompt": { "type": "string", "description": "The prompt/instruction for the agent to execute.\nRequired unless agent_config.skill_spec or agent_config.skills is provided.\n" }, "mode": { "$ref": "#/components/schemas/AgentRunMode", "description": "Optional query mode applied to every triggered run. Defaults to\n`normal` when omitted. The server does not infer mode from prompt\nprefixes such as `/plan`.\n" }, "enabled": { "type": "boolean", "description": "Whether the schedule should be active" }, "agent_uid": { "type": "string", "format": "uuid", "description": "Agent UID to use as the execution principal for this schedule.\nOnly valid for team-owned schedules.\n" }, "agent_config": { "$ref": "#/components/schemas/AmbientAgentConfig" }, "metadata": { "allOf": [ { "$ref": "#/components/schemas/RunMetadata" } ], "description": "Custom metadata stamped onto every run spawned by this schedule.\nUpdates follow full-replacement PUT semantics: omitting this field\nclears the schedule's metadata. Changes apply only to future runs.\n" } } }, "ListScheduledAgentsResponse": { "type": "object", "required": [ "schedules" ], "properties": { "schedules": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduledAgentItem" }, "description": "List of scheduled agents" } } }, "DeleteScheduledAgentResponse": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean", "description": "Whether the deletion was successful" } } }, "CloudEnvironmentConfig": { "type": "object", "description": "Configuration for a cloud environment used by scheduled agents", "properties": { "name": { "type": "string", "description": "Human-readable name for the environment" }, "description": { "type": "string", "nullable": true, "description": "Optional description of the environment" }, "docker_image": { "type": "string", "description": "Docker image to use (e.g., \"ubuntu:latest\" or \"registry/repo:tag\")" }, "github_repos": { "type": "array", "items": { "$ref": "#/components/schemas/GitHubRepo" }, "description": "List of GitHub repositories to clone into the environment" }, "setup_commands": { "type": "array", "items": { "type": "string" }, "description": "Shell commands to run during environment setup" }, "providers": { "$ref": "#/components/schemas/ProvidersConfig" }, "secrets": { "type": "array", "items": { "$ref": "#/components/schemas/SecretRef" }, "description": "Managed secret references contributed by this environment.\nOmission and an empty array both contribute no secrets. These\nreferences are unioned with references from the run config and\nexecution principal.\n" }, "failure_session_retention_minutes": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 60, "description": "When set (1–60 minutes), a failed run using this environment\nkeeps its session open for this many minutes so it can be\ninspected; null or absent means immediate teardown (disabled by\ndefault). This is an idle window held open by the agent process:\nactivity in the session pushes the deadline out (so an active\nsession is not torn down mid-debug), and it ends early if the\nrun's sandbox reaches its own deadline first. Applies only to\nfuture failures of runs using this environment; opting in keeps\ninjected environment data (including secrets) alive and incurs\ncompute usage for as long as the session is held open.\n" } } }, "ProvidersConfig": { "type": "object", "description": "Optional cloud provider configurations for automatic auth", "properties": { "gcp": { "$ref": "#/components/schemas/GcpProviderConfig" }, "aws": { "$ref": "#/components/schemas/AwsProviderConfig" } } }, "InferenceProvidersConfig": { "type": "object", "description": "Inference provider settings used for LLM calls.", "properties": { "aws": { "$ref": "#/components/schemas/AwsInferenceProviderConfig" } } }, "GcpProviderConfig": { "type": "object", "description": "GCP Workload Identity Federation settings", "required": [ "project_number", "workload_identity_federation_pool_id", "workload_identity_federation_provider_id" ], "externalDocs": { "description": "Google documentation on Workload Identity Federation", "url": "https://docs.cloud.google.com/iam/docs/workload-identity-federation" }, "properties": { "project_number": { "type": "string", "description": "GCP project number" }, "workload_identity_federation_pool_id": { "type": "string", "description": "Workload Identity Federation pool ID" }, "workload_identity_federation_provider_id": { "type": "string", "description": "Workload Identity Federation provider ID" }, "service_account_email": { "type": "string", "description": "Optional GCP service account email to impersonate" } } }, "AwsProviderConfig": { "type": "object", "description": "AWS IAM role assumption settings", "externalDocs": { "description": "AWS documentation on IAM OIDC federation", "url": "https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html" }, "required": [ "role_arn" ], "properties": { "role_arn": { "type": "string", "description": "AWS IAM role ARN to assume" } } }, "AwsInferenceProviderConfig": { "type": "object", "description": "Configures AWS Bedrock as the LLM inference provider for this\nagent or run.\n", "externalDocs": { "description": "AWS documentation on IAM OIDC federation", "url": "https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html" }, "properties": { "disabled": { "type": "boolean", "description": "If true, opt out of Bedrock at this layer." }, "role_arn": { "type": "string", "description": "IAM role ARN to assume when calling Bedrock." }, "region": { "type": "string", "description": "AWS region used for STS when assuming the Bedrock inference role." } } }, "GitHubRepo": { "type": "object", "required": [ "owner", "repo" ], "properties": { "owner": { "type": "string", "description": "GitHub repository owner (user or organization)" }, "repo": { "type": "string", "description": "GitHub repository name" } } }, "ListAgentsResponse": { "type": "object", "required": [ "agents" ], "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/AgentListItem" }, "description": "List of available agents" } } }, "ListConnectedSelfHostedWorkersResponse": { "type": "object", "required": [ "workers" ], "properties": { "workers": { "type": "array", "items": { "$ref": "#/components/schemas/ConnectedSelfHostedWorker" }, "description": "Connected self-hosted workers for the authenticated principal's team" } } }, "ConnectedSelfHostedWorker": { "type": "object", "required": [ "worker_host", "connection_count", "connected_at", "last_seen_at" ], "properties": { "worker_host": { "type": "string", "description": "Logical host identifier provided by the self-hosted worker" }, "connection_count": { "type": "integer", "description": "Number of active websocket connections currently observed for this worker host" }, "connected_at": { "type": "string", "format": "date-time", "description": "Earliest connection timestamp across active connections for this worker host" }, "last_seen_at": { "type": "string", "format": "date-time", "description": "Most recent heartbeat timestamp across active connections for this worker host" } } }, "AgentListItem": { "type": "object", "required": [ "name", "variants" ], "properties": { "name": { "type": "string", "description": "Human-readable name of the agent" }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/AgentListVariant" }, "description": "Available variants of this agent" } } }, "AgentListVariant": { "type": "object", "required": [ "id", "description", "base_prompt", "source", "environments" ], "properties": { "id": { "type": "string", "description": "Stable identifier for this skill variant.\nFormat: \"{owner}/{repo}:{skill_path}\"\nExample: \"warpdotdev/warp-server:.claude/skills/deploy/SKILL.md\"\n" }, "description": { "type": "string", "description": "Description of the agent variant" }, "base_prompt": { "type": "string", "description": "Base prompt/instructions for the agent" }, "source": { "$ref": "#/components/schemas/AgentListSource" }, "environments": { "type": "array", "items": { "$ref": "#/components/schemas/AgentListEnvironment" }, "description": "Environments where this agent variant is available" }, "last_run_timestamp": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp of the last time this skill was run (RFC3339)" }, "error": { "type": "string", "description": "Non-empty when the skill's SKILL.md file exists but is malformed.\nContains a description of the parse failure. Only present when\ninclude_malformed_skills=true is passed to the list agents endpoint.\n" } } }, "AgentListSource": { "type": "object", "required": [ "owner", "name", "skill_path" ], "properties": { "owner": { "type": "string", "description": "GitHub repository owner" }, "name": { "type": "string", "description": "GitHub repository name" }, "skill_path": { "type": "string", "description": "Path to the skill definition file within the repository" }, "worker_host": { "type": "string", "description": "Self-hosted worker host that reported this skill.\nPresent only for skills discovered from self-hosted workers\n(as opposed to skills from GitHub repos linked to environments).\n" } } }, "AgentListEnvironment": { "type": "object", "required": [ "uid", "name" ], "properties": { "uid": { "type": "string", "description": "Unique identifier for the environment" }, "name": { "type": "string", "description": "Human-readable name of the environment" } } }, "Scope": { "type": "object", "description": "Ownership scope for a resource (team or personal)", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "User", "Team" ], "description": "Type of ownership (\"User\" for personal, \"Team\" for team-owned)" }, "uid": { "type": "string", "description": "UID of the owning user or team" } } }, "PlatformErrorCode": { "type": "string", "description": "Machine-readable error code identifying the problem type.\nUsed in the `type` URI of Error responses and in the `error_code`\nfield of RunStatusMessage.\n\nUser errors (run transitions to FAILED):\n- `insufficient_credits` — Team has no remaining add-on credits\n- `feature_not_available` — Required feature not enabled for user's plan\n- `external_authentication_required` — User hasn't authorized a required external service\n- `not_authorized` — Principal lacks permission for the requested operation\n- `invalid_request` — Request is malformed or contains invalid parameters\n- `resource_not_found` — Referenced resource does not exist\n- `budget_exceeded` — Spending budget limit has been reached\n- `integration_disabled` — Integration is disabled and must be enabled\n- `integration_not_configured` — Integration setup is incomplete\n- `operation_not_supported` — Requested operation not supported for this resource/state\n- `environment_setup_failed` — Client-side environment setup failed\n- `content_policy_violation` — Prompt or setup commands violated content policy\n- `conflict` — Request conflicts with the current state of the resource\n\nWarp errors (run transitions to ERROR):\n- `authentication_required` — Request lacks valid authentication credentials\n- `resource_unavailable` — Transient infrastructure issue (retryable)\n- `agent_stream_network_error` — MAA response stream terminally failed because of a transport or EOF error\n- `agent_stream_failure` — MAA server explicitly reported a terminal response stream failure\n- `internal_error` — Unexpected server-side error (retryable)\n", "enum": [ "insufficient_credits", "feature_not_available", "external_authentication_required", "not_authorized", "invalid_request", "resource_not_found", "budget_exceeded", "integration_disabled", "integration_not_configured", "operation_not_supported", "environment_setup_failed", "content_policy_violation", "conflict", "authentication_required", "resource_unavailable", "agent_stream_network_error", "agent_stream_failure", "internal_error" ] }, "RunFollowupRequest": { "type": "object", "description": "Request body for submitting a follow-up message to an existing run.", "properties": { "message": { "type": "string", "description": "The follow-up message to send to the run. May be empty when\n`attachments` is non-empty.\n" }, "mode": { "$ref": "#/components/schemas/AgentRunMode", "description": "Optional query mode for the follow-up. Defaults to `normal` when\nomitted. The server does not infer mode from prompt prefixes such\nas `/plan`. The mode only takes effect when the follow-up is\nqueued ahead of the run starting or starts a new execution; a\nfollow-up injected into a live session runs in the session's\ncurrent mode.\n" }, "attachments": { "type": "array", "maxItems": 25, "items": { "$ref": "#/components/schemas/RunFollowupAttachment" }, "description": "Files to deliver with the message, at most 25. Each entry must\nname an attachment previously prepared for this run through\n`POST /agent/runs/{runId}/attachments/prepare` and uploaded to\nits upload target; an unknown `attachment_id` is rejected with\n422. Files are only materialized for the agent on the Oz\nharness; other harnesses receive a notice naming the files.\n" } } }, "RunFollowupAttachment": { "type": "object", "description": "A prepared attachment to deliver with a follow-up message.", "required": [ "attachment_id" ], "properties": { "attachment_id": { "type": "string", "description": "The `attachment_id` (a UUID) returned by the attachment prepare\nendpoint for this run.\n" }, "file_name": { "type": "string", "description": "Optional display name shown to the agent in place of the name\nrecorded when the attachment was prepared. The stored object is\nunaffected.\n" } } }, "RunFollowupOutcome": { "type": "string", "description": "How an accepted follow-up was routed.\n - live_session: the message was handed to the running session. This means\n the session-sharing service accepted it, not that the agent has started\n on it; observe the session's event stream for the new request.\n - queued_prompt: the run had not started yet, so the message was appended\n to its initial prompt.\n - handoff_execution: the previous execution had ended, so a new execution\n of the same run was created to continue the conversation.\n - queue_pending: the message is durably queued and will be delivered once\n the run can accept it.\n", "enum": [ "live_session", "queued_prompt", "handoff_execution", "queue_pending" ] }, "RunFollowupResponse": { "type": "object", "description": "Acknowledgement of an accepted follow-up.", "required": [ "followup_id", "outcome" ], "properties": { "followup_id": { "type": "string", "nullable": true, "description": "Identifier of the durable follow-up record, or null when the\noutcome did not create one (`queued_prompt`).\n" }, "outcome": { "$ref": "#/components/schemas/RunFollowupOutcome" } } }, "ConversationFollowupResponse": { "type": "object", "description": "Acknowledgement of a follow-up accepted through a conversation-keyed\nroute: the run-keyed acknowledgement plus the run it was delivered to.\n", "required": [ "followup_id", "outcome", "run_id" ], "properties": { "followup_id": { "type": "string", "nullable": true, "description": "Identifier of the durable follow-up record, or null when the\noutcome did not create one (`queued_prompt`).\n" }, "outcome": { "$ref": "#/components/schemas/RunFollowupOutcome" }, "run_id": { "type": "string", "description": "The run the conversation resolved to." } } }, "ConversationInterruptResponse": { "type": "object", "description": "Acknowledgement of an interrupt accepted through a conversation-keyed route.", "required": [ "run_id" ], "properties": { "run_id": { "type": "string", "description": "The run whose turn is being interrupted." } } }, "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" ] }, "CreateAgentRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "A name for the agent" }, "description": { "type": "string", "nullable": true, "description": "Optional description of the agent" }, "prompt": { "type": "string", "nullable": true, "description": "Optional base prompt for this agent\n" }, "environment_id": { "type": "string", "nullable": true, "description": "Optional default cloud environment ID for runs executed by this agent.\nThe environment must be owned by the same team as the agent.\n" }, "default_runner_uid": { "type": "string", "nullable": true, "description": "Optional default runner UID for runs executed by this agent. When set,\nit overrides the selected environment's default runner for runs that\ndo not specify their own `runner_id`. The editor must have View\npermission on the referenced runner.\n" }, "secrets": { "type": "array", "items": { "$ref": "#/components/schemas/SecretRef" }, "description": "Optional list of secrets associated with the agent.\nDuplicate names within a single request are rejected.\nEach entry is unioned into the run-time secret scope when the agent executes.\n" }, "skills": { "type": "array", "items": { "type": "string" }, "description": "Optional list of skill specs to associate with the agent.\nFormat: \"{owner}/{repo}:{skill_path}\" (e.g., \"warpdotdev/warp-server:.claude/skills/deploy/SKILL.md\").\nEach spec is validated and normalized at attach time using the team's GitHub\ncredentials; inaccessible or malformed specs are rejected.\n" }, "base_model": { "type": "string", "nullable": true, "description": "Optional base model for runs executed by this agent.\n" }, "inference_providers": { "allOf": [ { "$ref": "#/components/schemas/InferenceProvidersConfig" } ], "description": "Optional inference provider settings for this agent.\nAgent-level config takes precedence over the workspace's\nadmin-configured defaults.\n" }, "memory": { "allOf": [ { "$ref": "#/components/schemas/AgentMemoryCreateConfig" } ], "description": "Optional memory settings for the agent." }, "mcp_servers": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/MCPServerConfig" }, "description": "Optional map of MCP server configurations by name to attach to runs executed by this agent.\nRun-level MCP config takes precedence over this agent-level default.\n" }, "base_harness": { "type": "string", "nullable": true, "deprecated": true, "description": "Optional default harness for runs executed by this agent.\nDeprecated - use harness instead. Kept for backward compatibility;\nwhen both are sent, harness is authoritative and a conflicting\ntype is rejected with invalid_request.\n" }, "harness": { "allOf": [ { "$ref": "#/components/schemas/Harness" } ], "description": "Optional default harness for runs executed by this agent.\nOmission or an empty object stores no harness default.\n" }, "credential_strategy": { "allOf": [ { "$ref": "#/components/schemas/AgentCredentialStrategy" } ], "nullable": true, "description": "Optional default credential strategy for runs executed by this\nagent. When omitted or null, the agent has no opinion and runs fall\nback to the factory default (for factory-seeded agents) and then to\nEXECUTOR.\n" }, "harness_auth_secrets": { "allOf": [ { "$ref": "#/components/schemas/HarnessAuthSecrets" } ], "description": "Optional per-harness authentication secrets for this agent.\nEach field names a managed secret for the corresponding harness.\nSecrets are resolved at execution time from the agent's team scope.\n" }, "on_behalf_of_enabled": { "type": "boolean", "description": "Whether runs created with this agent's API key may use the on_behalf_of\nfield to attribute runs to another team member. Defaults to false.\nOnly team admins may set this field.\n" }, "worker_host": { "type": "string", "nullable": true, "description": "Optional default worker host for runs executed by this agent;\nomission, null, or an empty value stores no Agent default, in\nwhich case the workspace default applies. A non-empty value is\ntrimmed and stored (use \"warp\" to force Warp-hosted execution\nover a self-hosted workspace default), and is resolved in this\norder:\n1. The host specified on the run itself\n2. The agent's default host\n3. The workspace default host\n" } } }, "UpdateAgentRequest": { "type": "object", "description": "Partial update for an agent; each field is optional:\n * Omitted or `null`: leave the field unchanged.\n * Empty value: clear the field.\n * Non-empty: replace the field wholesale with the provided value.\n`secrets_append` is an exception: it appends secrets idempotently and\nmust be the only supplied field, including fields supplied as `null`.\n", "properties": { "name": { "type": "string", "description": "The new name for the agent" }, "description": { "type": "string", "nullable": true, "description": "Replacement description. Omit or pass `null` to leave unchanged, or use an empty value to clear.\n" }, "prompt": { "type": "string", "nullable": true, "description": "Replacement prompt. Omit or pass `null` to leave unchanged, or use an empty value to clear.\n" }, "environment_id": { "type": "string", "nullable": true, "description": "Replacement default cloud environment ID. Omit or pass `null` to leave unchanged,\nor pass an empty string to clear.\n" }, "default_runner_uid": { "type": "string", "nullable": true, "description": "Replacement default runner UID. Omit or pass `null` to leave unchanged,\nor pass an empty string to clear. A non-empty value must reference a\nrunner the editor can View.\n" }, "secrets": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/SecretRef" }, "description": "Replacement list of secrets. Omit to leave unchanged, pass an\nempty array to clear, or pass a non-empty array to replace.\nDuplicate names are rejected.\n" }, "secrets_append": { "type": "array", "nullable": false, "items": { "$ref": "#/components/schemas/SecretRef" }, "description": "Adds team-owned raw-value secrets to this agent without removing or\nreplacing its existing ones. Secrets it already has and any duplicates\nare skipped, and an empty array is a no-op. If any name is invalid, the\nwhole request is rejected. Send this field by itself. Including any other\nfield returns 400, even if that field is null, and null is not a valid\nvalue here. Appending requires edit and privileged-config-edit access on\nthe agent plus secret-attach access on its Factory. Agents managed in\nexternal source files return 409.\n" }, "skills": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Replacement list of skill specs. Omit to leave unchanged, pass an empty array\nto clear, or pass a non-empty array to replace.\n" }, "base_model": { "type": "string", "nullable": true, "description": "Replacement base model. Omit or pass `null` to leave unchanged,\nor pass an empty string to clear.\n" }, "memory": { "allOf": [ { "$ref": "#/components/schemas/AgentMemoryUpdateConfig" } ], "nullable": true, "description": "Replacement memory settings for this agent." }, "mcp_servers": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/MCPServerConfig" }, "description": "Replacement map of MCP server configurations by name. Omit to leave\nunchanged, pass an empty object to clear, or pass a non-empty object\nto replace. Run-level MCP config takes precedence over this agent-level\ndefault.\n" }, "inference_providers": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/InferenceProvidersConfig" } ], "nullable": true, "description": "Replacement inference provider settings for this agent, which\ntake precedence over the workspace's admin-configured defaults;\nomit or pass `null` to leave unchanged, or pass an empty object\n`{}` to clear.\n" }, "base_harness": { "type": "string", "nullable": true, "deprecated": true, "description": "Replacement default harness; omit or pass `null` to leave\nunchanged, or pass an empty string to clear. Deprecated - use\nharness instead, kept only for backward compatibility: when both\nare sent, harness is authoritative and a conflicting type is\nrejected with invalid_request.\n" }, "harness": { "allOf": [ { "$ref": "#/components/schemas/Harness" } ], "nullable": true, "description": "Replacement default harness for runs executed by this agent. Omit\nor pass `null` to leave unchanged, pass `{}` to clear the stored\ndefault, or pass a populated object to replace it wholesale.\n" }, "credential_strategy": { "allOf": [ { "$ref": "#/components/schemas/AgentCredentialStrategy" } ], "nullable": true, "description": "Replacement default credential strategy. Omit or pass `null` to\nleave unchanged, or pass an empty string to clear the agent's\ndefault. An agent belonging to a file-managed factory cannot clear\nit: its agent file expresses the strategy by declaring it, and a\nfile that declares none keeps the strategy already projected, so a\nclear is rejected with a 400.\n" }, "harness_auth_secrets": { "allOf": [ { "$ref": "#/components/schemas/HarnessAuthSecrets" } ], "nullable": true, "description": "Replacement per-harness authentication secrets. Omit or pass `null`\nto leave unchanged, or pass an empty object to clear all secrets.\n" }, "on_behalf_of_enabled": { "type": "boolean", "nullable": true, "description": "Whether runs created with this agent's API key may use the on_behalf_of\nfield to attribute runs to another team member. Omit or pass `null` to\nleave unchanged. Only team admins may set this field.\n" }, "worker_host": { "type": "string", "nullable": true, "description": "Replacement default worker host. Omit or pass `null` to leave\nunchanged, or pass an empty string to clear (the workspace default\nthen applies). A non-empty value is trimmed and replaces the\nstored default; use \"warp\" to force Warp-hosted execution over a\nself-hosted workspace default.\n" } } }, "AgentResponse": { "type": "object", "required": [ "uid", "name", "available", "created_at", "updated_at", "secrets", "skills", "memory", "default_runner_uid" ], "properties": { "uid": { "type": "string", "description": "Unique identifier for the agent" }, "name": { "type": "string", "description": "Name of the agent" }, "description": { "type": "string", "nullable": true, "description": "Optional description of the agent" }, "prompt": { "type": "string", "nullable": true, "description": "Optional base prompt for this agent\n" }, "environment_id": { "type": "string", "description": "Default cloud environment ID for runs executed by this agent;\nthe precedence order for environment resolution is:\n1. The environment specified on the run itself\n2. The agent's default environment\n3. An empty environment\n" }, "default_runner_uid": { "type": "string", "description": "Default runner UID for runs executed by this agent; when set,\nit overrides the selected environment's default runner for\nruns that do not specify their own `runner_id`. The precedence\norder for runner resolution is:\n1. The runner specified on the run itself\n2. The agent's default runner\n3. The selected environment's default runner\n4. The environment's legacy inline compute fields\n5. System defaults\n" }, "available": { "type": "boolean", "description": "Whether the agent is currently enabled. Defaults to true." }, "created_at": { "type": "string", "format": "date-time", "description": "When the agent was created (RFC3339)" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the agent was last updated (RFC3339)" }, "secrets": { "type": "array", "items": { "$ref": "#/components/schemas/SecretRef" }, "description": "Secrets that this agent may access by default.\n" }, "skills": { "type": "array", "items": { "type": "string" }, "description": "Ordered list of normalized skill specs associated with this agent.\nAlways present; empty when no skills are attached.\n" }, "base_model": { "type": "string", "description": "Base model for runs executed by this agent; the precedence\norder for model resolution is:\n1. The model specified on the run itself\n2. The agent's base model\n3. The team's default model\n" }, "inference_providers": { "allOf": [ { "$ref": "#/components/schemas/InferenceProvidersConfig" } ], "description": "The agent's stored inference provider settings. May be overridden\nby run-level config; if empty, falls back to the workspace's\nadmin-configured defaults.\n" }, "memory": { "allOf": [ { "$ref": "#/components/schemas/AgentMemoryResponse" } ], "description": "Memory settings for this agent.\nAlways present; attached_stores is empty when no team stores are attached.\n" }, "mcp_servers": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/MCPServerConfig" }, "description": "MCP server configurations attached to this agent by default.\nRun-level MCP config takes precedence over this agent-level default.\n" }, "base_harness": { "type": "string", "deprecated": true, "description": "Default harness for runs executed by this agent; the\nprecedence order for harness resolution is:\n1. The harness specified on the run itself\n2. The agent's base harness\n3. Warp\nDeprecated: use harness instead, which carries the full\n{type, model_id, reasoning_level} default.\n" }, "harness": { "allOf": [ { "$ref": "#/components/schemas/Harness" } ], "description": "Default harness for runs executed by this agent. Absent when the\nagent has no harness default. A stored model_id/reasoning_level\npair is still returned even if the model has since left the\nharness's catalog.\n" }, "credential_strategy": { "allOf": [ { "$ref": "#/components/schemas/AgentCredentialStrategy" } ], "description": "Default credential strategy for runs executed by this agent.\nAbsent when the agent has no default. The precedence order for\ncredential strategy resolution is:\n1. The strategy specified on the run itself\n2. The agent's default strategy\n3. The factory's default strategy, for factory-seeded agents\n4. EXECUTOR\nThe resolved strategy is credential-validated at run creation;\nan unavailable credential rejects the request before execution.\n" }, "harness_auth_secrets": { "allOf": [ { "$ref": "#/components/schemas/HarnessAuthSecrets" } ], "description": "Per-harness authentication secrets configured on this agent.\nEach field names a managed secret for the corresponding harness.\nSecrets can be overridden per run.\n" }, "on_behalf_of_enabled": { "type": "boolean", "description": "Whether runs created with this agent's API key may use the on_behalf_of\nfield to attribute runs to another team member.\n" }, "worker_host": { "type": "string", "description": "Default worker host for runs executed by this agent, or empty\nwhen unset; the precedence order for worker host resolution is:\n1. The host specified on the run itself\n2. The agent's default host\n3. The workspace default host\n" } } }, "ListAgentIdentitiesResponse": { "type": "object", "required": [ "agents" ], "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/AgentResponse" } } } }, "EnvironmentLastTask": { "type": "object", "description": "Summary of the most recently created task for an environment", "required": [ "id", "title", "state", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "description": "Unique identifier of the task" }, "title": { "type": "string", "description": "Title of the task" }, "state": { "$ref": "#/components/schemas/RunState" }, "created_at": { "type": "string", "format": "date-time", "description": "When the task was created (RFC3339)" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the task was last updated (RFC3339)" }, "started_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the task started running (RFC3339), null if not yet started" } } } } } }