{ "openapi": "3.0.0", "info": { "title": "Oz Agent API", "version": "1.0.0", "description": "API for creating, managing, and querying Oz cloud agent runs.\n\nThese endpoints allow users to programmatically spawn agents, list runs, \nand retrieve detailed run information.\n", "contact": { "name": "Warp Support", "url": "https://docs.warp.dev", "email": "support@warp.dev" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://app.warp.dev/api/v1", "description": "Warp Server" } ], "tags": [ { "name": "agent", "description": "Operations for running and managing cloud agents" }, { "name": "schedules", "description": "Operations for creating and managing scheduled agents" } ], "paths": { "/agent": { "get": { "summary": "List available agents", "description": "Retrieve a list of available agents (skills) that can be used to run tasks.\nAgents are discovered from environments or a specific repository.\n", "operationId": "listAgents", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "repo", "in": "query", "description": "Optional repository specification to list agents from (format: \"owner/repo\").\nIf not provided, lists agents from all accessible environments.\n", "required": false, "schema": { "type": "string" } }, { "name": "refresh", "in": "query", "description": "When true, clears the agent list cache before fetching.\nUse this to force a refresh of the available agents.\n", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "sort_by", "in": "query", "description": "Sort order for the returned agents.\n- \"name\": Sort alphabetically by name (default)\n- \"last_run\": Sort by most recently used\n", "required": false, "schema": { "type": "string", "enum": [ "name", "last_run" ] } }, { "name": "include_malformed_skills", "in": "query", "description": "When true, includes skills whose SKILL.md file exists but is\nmalformed. These variants will have a non-empty `error` field\ndescribing the parse failure. Defaults to false.\n", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "List of available agents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAgentsResponse" } } } }, "400": { "description": "Invalid repository specification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/connected-self-hosted-workers": { "get": { "summary": "List connected self-hosted workers", "description": "Retrieve currently connected self-hosted workers for the authenticated principal's team.\nWorker presence is derived from worker websocket heartbeats and may be briefly stale.\n", "operationId": "listConnectedSelfHostedWorkers", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "List of currently connected self-hosted workers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListConnectedSelfHostedWorkersResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not authorized to list connected workers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/runs/{runId}/transcript": { "get": { "summary": "Get run transcript", "description": "Retrieve the raw conversation transcript for an agent run.\nReturns a 302 redirect to a time-limited download URL for the transcript.\n", "operationId": "getRunTranscript", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "runId", "in": "path", "description": "The unique identifier of the run", "required": true, "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to a download URL for the transcript", "headers": { "Location": { "description": "URL to download the transcript", "schema": { "type": "string", "format": "uri" } } } }, "400": { "description": "Missing run ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to access run transcript", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run not found or has no transcript", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/run": { "post": { "summary": "Run an agent task", "description": "Spawn a cloud agent with a prompt and optional configuration.\nThe agent will be queued for execution and assigned a unique run ID.\n", "operationId": "runAgent", "deprecated": true, "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunAgentRequest" }, "examples": { "simple": { "summary": "Simple prompt", "value": { "prompt": "Fix the bug in auth.go" } }, "withConfig": { "summary": "With agent config", "value": { "prompt": "Refactor the database layer", "config": { "name": "my-agent", "model_id": "gpt-5-4-high", "base_prompt": "Focus on Go backend code" }, "title": "DB Refactoring Run" } } } } } }, "responses": { "200": { "description": "Run created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunAgentResponse" } } } }, "400": { "description": "Invalid request (missing prompt, invalid config)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to access referenced resources (environment, MCP servers)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/runs": { "post": { "summary": "Run a cloud agent", "description": "Spawn a cloud agent with a prompt and optional configuration.\nThe agent will be queued for execution and assigned a unique run ID.\n", "operationId": "createRun", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunAgentRequest" } } } }, "responses": { "200": { "description": "Run created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunAgentResponse" } } } }, "400": { "description": "Invalid request (missing prompt, invalid config)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to access referenced resources (environment, MCP servers)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List agent runs", "description": "Retrieve a paginated list of agent runs with optional filtering.\nResults default to `sort_by=updated_at` and `sort_order=desc`.\n", "operationId": "listRuns", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of runs to return", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 20 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor from previous response", "required": false, "schema": { "type": "string" } }, { "name": "sort_by", "in": "query", "description": "Sort field for results.\n- `updated_at`: Sort by last update timestamp (default)\n- `created_at`: Sort by creation timestamp\n- `title`: Sort alphabetically by run title\n- `agent`: Sort alphabetically by skill. Runs without a skill are grouped last.\n", "required": false, "schema": { "type": "string", "enum": [ "updated_at", "created_at", "title", "agent" ], "default": "updated_at" } }, { "name": "sort_order", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, { "name": "state", "in": "query", "description": "Filter by run state. Can be specified multiple times to match any of the given states.\n", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RunState" } }, "style": "form", "explode": true }, { "name": "name", "in": "query", "description": "Filter by agent config name", "required": false, "schema": { "type": "string" } }, { "name": "model_id", "in": "query", "description": "Filter by model ID", "required": false, "schema": { "type": "string" } }, { "name": "creator", "in": "query", "description": "Filter by creator UID (user or service account)", "required": false, "schema": { "type": "string" } }, { "name": "executor", "in": "query", "description": "Filter by the user or agent that executed the run. This will often be the\nsame as the creator, but not always: users may delegate tasks to agents.\n", "required": false, "schema": { "type": "string" } }, { "name": "source", "in": "query", "description": "Filter by run source type", "required": false, "schema": { "$ref": "#/components/schemas/RunSourceType" } }, { "name": "execution_location", "in": "query", "description": "Filter by where the run executed", "required": false, "schema": { "$ref": "#/components/schemas/RunExecutionLocation" } }, { "name": "created_after", "in": "query", "description": "Filter runs created after this timestamp (RFC3339 format)", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "description": "Filter runs created before this timestamp (RFC3339 format)", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_after", "in": "query", "description": "Filter runs updated after this timestamp (RFC3339 format)", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "environment_id", "in": "query", "description": "Filter runs by environment ID", "required": false, "schema": { "type": "string" } }, { "name": "skill", "in": "query", "description": "Filter runs by skill spec (e.g., \"owner/repo:path/to/SKILL.md\").\nAlias for skill_spec.\n", "required": false, "schema": { "type": "string" } }, { "name": "skill_spec", "in": "query", "description": "Filter runs by skill spec (e.g., \"owner/repo:path/to/SKILL.md\")", "required": false, "schema": { "type": "string" } }, { "name": "schedule_id", "in": "query", "description": "Filter runs by the scheduled agent ID that created them", "required": false, "schema": { "type": "string" } }, { "name": "ancestor_run_id", "in": "query", "description": "Filter runs by ancestor run ID. The referenced run must exist and be accessible to the caller.", "required": false, "schema": { "type": "string" } }, { "name": "artifact_type", "in": "query", "description": "Filter runs by artifact type", "required": false, "schema": { "type": "string", "enum": [ "PLAN", "PULL_REQUEST", "SCREENSHOT", "FILE" ] } }, { "name": "q", "in": "query", "description": "Fuzzy search query across run title, prompt, and skill_spec", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of runs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRunsResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/runs/{runId}": { "get": { "summary": "Get run details", "description": "Retrieve detailed information about a specific agent run, \nincluding the full prompt, session link, and resolved configuration.\n", "operationId": "getRun", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "runId", "in": "path", "description": "The unique identifier of the run", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Run details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunItem" } } } }, "400": { "description": "Missing run ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to access run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/runs/{runId}/timeline": { "get": { "summary": "Get run timeline", "description": "Retrieve chronological setup and lifecycle timeline events for an agent run.\n", "operationId": "getRunTimeline", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "runId", "in": "path", "description": "The unique identifier of the run", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Run timeline events", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetRunTimelineResponse" } } } }, "400": { "description": "Missing run ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to access run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/runs/{runId}/conversation": { "get": { "summary": "Get normalized run conversation", "description": "Retrieve a run's conversation as a normalized sequence of messages and\nnested steps.\nThe response groups text, tool activity, and event content into\nstructured blocks.\n", "operationId": "getRunConversation", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "runId", "in": "path", "description": "The unique identifier of the run", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Normalized conversation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationResponse" } } } }, "400": { "description": "Missing run ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to access run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run not found, or the run has no conversation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Conversation format is not yet supported by the normalized endpoint\n(error_code: operation_not_supported)\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/runs/{runId}/cancel": { "post": { "summary": "Cancel a run", "description": "Cancel an agent run that is currently queued or in progress.\nOnce cancelled, the run will transition to a cancelled state.\n\nNot all runs can be cancelled. Runs that are in a terminal state\n(SUCCEEDED, FAILED, ERROR, BLOCKED, CANCELLED) return 400. Runs in\nPENDING state return 409 (retry after a moment). Self-hosted, local,\nand GitHub Action runs return 422.\n", "operationId": "cancelRun", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "runId", "in": "path", "description": "The unique identifier of the run to cancel", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Run cancelled successfully", "content": { "application/json": { "schema": { "type": "string", "description": "The ID of the cancelled run" } } } }, "400": { "description": "Missing run ID, or the run is already in a terminal state\n(error_code: invalid_request)\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to cancel run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Run is in PENDING state and cannot be cancelled yet.\nRetry after a moment (error_code: conflict, retryable: true).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Run cannot be cancelled because the operation is not supported\nfor this run type (e.g., self-hosted, local, or GitHub Action runs)\n(error_code: operation_not_supported)\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/runs/{runId}/followups": { "post": { "summary": "Submit a follow-up message for a run", "description": "Send a follow-up message to an existing run. The server transparently\nroutes the message based on the current state of the run (still\nqueued, actively running, or ended). A 200 response means the follow-up\nwas accepted; updated run state can be observed via\n`GET /agent/runs/{runId}`.\n", "operationId": "submitRunFollowup", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "runId", "in": "path", "description": "The unique identifier of the run", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunFollowupRequest" } } } }, "responses": { "200": { "description": "Follow-up accepted", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request (e.g. no active sandbox without conversation ID,\nmalformed payload). Empty messages are accepted when continuing a\nrun from saved conversation context; otherwise they are rejected.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to submit follow-ups for this run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/conversations/{conversation_id}": { "get": { "summary": "Get normalized conversation", "description": "Retrieve a conversation directly by conversation ID in Warp's\nnormalized task/message format.\n", "operationId": "getConversation", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "description": "The unique identifier of the conversation", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Normalized conversation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationResponse" } } } }, "400": { "description": "Missing conversation ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to access conversation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Conversation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Conversation format is not yet supported by the normalized endpoint\n(error_code: operation_not_supported)\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/schedules": { "post": { "summary": "Create a scheduled agent", "description": "Create a new scheduled agent that runs on a cron schedule.\nThe agent will be triggered automatically based on the cron expression.\n", "operationId": "createScheduledAgent", "tags": [ "schedules" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateScheduledAgentRequest" }, "examples": { "simple": { "summary": "Simple daily schedule", "value": { "name": "Daily Code Review", "cron_schedule": "0 9 * * *", "prompt": "Review open pull requests and provide feedback", "enabled": true } }, "withConfig": { "summary": "With agent config", "value": { "name": "Weekly Report", "cron_schedule": "0 10 * * 1", "prompt": "Generate weekly status report", "enabled": true, "agent_config": { "model_id": "claude-4-6-opus-high" } } } } } } }, "responses": { "201": { "description": "Scheduled agent created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledAgentItem" } } } }, "400": { "description": "Invalid request (missing required fields, invalid cron expression)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission or feature not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List scheduled agents", "description": "Retrieve all scheduled agents accessible to the authenticated user.\nResults are sorted alphabetically by name.\n", "operationId": "listScheduledAgents", "tags": [ "schedules" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "List of scheduled agents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListScheduledAgentsResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/schedules/{scheduleId}": { "get": { "summary": "Get scheduled agent details", "description": "Retrieve detailed information about a specific scheduled agent,\nincluding its configuration, history, and next scheduled run time.\n", "operationId": "getScheduledAgent", "tags": [ "schedules" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "scheduleId", "in": "path", "description": "The unique identifier of the scheduled agent", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Scheduled agent details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledAgentItem" } } } }, "400": { "description": "Missing schedule ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to access schedule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Schedule not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "summary": "Update a scheduled agent", "description": "Update an existing scheduled agent's configuration.\nAll fields except agent_config are required.\n", "operationId": "updateScheduledAgent", "tags": [ "schedules" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "scheduleId", "in": "path", "description": "The unique identifier of the scheduled agent", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateScheduledAgentRequest" } } } }, "responses": { "200": { "description": "Scheduled agent updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledAgentItem" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to update schedule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Schedule not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete a scheduled agent", "description": "Delete a scheduled agent. This will stop all future scheduled runs.\n", "operationId": "deleteScheduledAgent", "tags": [ "schedules" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "scheduleId", "in": "path", "description": "The unique identifier of the scheduled agent", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Scheduled agent deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteScheduledAgentResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to delete schedule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Schedule not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/schedules/{scheduleId}/pause": { "post": { "summary": "Pause a scheduled agent", "description": "Pause a scheduled agent. The agent will not run until resumed.\n", "operationId": "pauseScheduledAgent", "tags": [ "schedules" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "scheduleId", "in": "path", "description": "The unique identifier of the scheduled agent", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Scheduled agent paused successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledAgentItem" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to pause schedule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Schedule not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/schedules/{scheduleId}/resume": { "post": { "summary": "Resume a scheduled agent", "description": "Resume a paused scheduled agent. The agent will start running\naccording to its cron schedule.\n", "operationId": "resumeScheduledAgent", "tags": [ "schedules" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "scheduleId", "in": "path", "description": "The unique identifier of the scheduled agent", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Scheduled agent resumed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledAgentItem" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to resume schedule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Schedule not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/environments": { "get": { "summary": "List environments", "description": "Retrieve cloud environments accessible to the authenticated principal.\nReturns environments the caller owns, has been granted guest access to,\nor has accessed via link sharing.\n", "operationId": "listEnvironments", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "sort_by", "in": "query", "required": false, "description": "Sort order for the returned environments.\n- `name`: alphabetical by environment name\n- `last_updated`: most recently updated first (default)\n", "schema": { "type": "string", "enum": [ "name", "last_updated" ], "default": "last_updated" } } ], "responses": { "200": { "description": "List of accessible environments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEnvironmentsResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/models": { "get": { "summary": "List available models", "description": "Retrieve the list of LLM models available to the authenticated user for\nagent runs. The response includes which model is the default, as well as\nper-model metadata such as provider, cost, and whether the model is\ncurrently disabled (and why).\n", "operationId": "listModels", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "List of available models", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListModelsResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/artifacts/{artifactUid}": { "get": { "summary": "Get artifact details", "description": "Retrieve an artifact by its UUID. For downloadable file-like artifacts,\nreturns a time-limited signed download URL. For plan artifacts, returns\nthe current plan content inline.\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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No permission to access 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" } } } } } } }, "/harness-support/transcript": { "get": { "summary": "Download the raw third-party harness transcript", "description": "Redirects to a signed download URL for the raw third-party harness transcript\n(e.g. `claude_code.json`) of the current task's conversation. Only supported\nfor conversations produced by non-Oz harnesses; Oz conversations 400.\n\nThis may only be called from within a cloud agent execution environment whose\ntask already has an associated conversation (e.g. on a resumed run).\n", "operationId": "getTranscriptDownload", "tags": [ "harness-support" ], "security": [ { "bearerAuth": [] } ], "responses": { "307": { "description": "Redirect to a signed download URL for the transcript" }, "400": { "description": "Task has no conversation, or conversation format does not support transcript downloads", "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 the conversation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Conversation or transcript not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/identities": { "post": { "summary": "Create an agent", "description": "Create a new agent for the caller's team.\nAgents can be used as the execution principal for team-owned runs.\n", "operationId": "createAgent", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentRequest" } } } }, "responses": { "201": { "description": "Agent created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResponse" } } } }, "400": { "description": "Invalid request (empty name, user on multiple teams, or on no team)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Only human users can manage agents, or plan limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List agents", "description": "List all agents for the caller's team. Each agent includes\nan `available` flag indicating whether it is within the team's plan limit\nand may be used for runs.\n", "operationId": "listAgents", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "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.\nThe response includes an `available` flag indicating whether the agent\nis within the team's plan limit and may be used for runs.\n", "operationId": "getAgent", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uid", "in": "path", "description": "The unique identifier of the agent", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Agent details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "summary": "Update an agent", "description": "Update an existing agent.\n", "operationId": "updateAgent", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uid", "in": "path", "description": "The unique identifier of the agent", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgentRequest" } } } }, "responses": { "200": { "description": "Agent updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResponse" } } } }, "400": { "description": "Missing or invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Only human users can manage agents, or plan limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete an agent", "description": "Delete an agent. All API keys associated with the\nagent are deleted atomically.\n", "operationId": "deleteAgent", "tags": [ "agent" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uid", "in": "path", "description": "The unique identifier of the agent", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Agent deleted successfully" }, "400": { "description": "Cannot delete the default agent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Only human users can manage agents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Authentication via a Warp API key.\n" } }, "schemas": { "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" }, "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.\nUsed for orchestration hierarchies.\n" }, "interactive": { "type": "boolean", "description": "Whether the run should be interactive.\nIf not set, defaults to false.\n" } } }, "RunAgentResponse": { "type": "object", "required": [ "run_id", "task_id", "state" ], "properties": { "run_id": { "type": "string", "description": "Unique identifier for the created run" }, "task_id": { "type": "string", "deprecated": true, "description": "Unique identifier for the task (same as run_id). Deprecated - use run_id instead." }, "state": { "$ref": "#/components/schemas/RunState" }, "at_capacity": { "type": "boolean", "description": "Whether the system is at capacity when the run was created" } } }, "AgentRunMode": { "type": "string", "description": "Query mode for an agent run.\n - normal: Standard user query (default).\n - plan: Planning Mode. The agent researches and creates a plan, then waits for approval before execution.\n - orchestrate: Orchestration Mode. The agent proposes an orchestration plan and must not start child agents until approved.\n", "enum": [ "normal", "plan", "orchestrate" ], "default": "normal" }, "ListRunsResponse": { "type": "object", "required": [ "runs", "page_info" ], "properties": { "runs": { "type": "array", "items": { "$ref": "#/components/schemas/RunItem" } }, "page_info": { "$ref": "#/components/schemas/PageInfo" } } }, "RunItem": { "type": "object", "required": [ "run_id", "task_id", "title", "state", "prompt", "created_at", "updated_at" ], "properties": { "run_id": { "type": "string", "description": "Unique identifier for the run" }, "task_id": { "type": "string", "deprecated": true, "description": "Unique identifier for the task (typically matches run_id). Deprecated - use run_id instead." }, "title": { "type": "string", "description": "Human-readable title for the run" }, "state": { "$ref": "#/components/schemas/RunState" }, "execution_location": { "$ref": "#/components/schemas/RunExecutionLocation" }, "prompt": { "type": "string", "description": "The prompt/instruction for the agent" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the run was created (RFC3339)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the run was last updated (RFC3339)" }, "run_time": { "type": "string", "format": "duration", "description": "Total runtime as an ISO 8601 duration (e.g. \"PT2M30S\"), computed server-side from run executions." }, "started_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the agent started working on the run (RFC3339)" }, "status_message": { "$ref": "#/components/schemas/RunStatusMessage" }, "source": { "$ref": "#/components/schemas/RunSourceType" }, "schedule": { "$ref": "#/components/schemas/ScheduleInfo" }, "session_id": { "type": "string", "description": "UUID of the shared session (if available)" }, "session_link": { "type": "string", "format": "uri", "description": "URL to view the agent session" }, "trigger_url": { "type": "string", "format": "uri", "description": "URL to the run trigger (e.g. Slack thread, Linear issue, schedule)" }, "creator": { "$ref": "#/components/schemas/RunCreatorInfo" }, "executor": { "$ref": "#/components/schemas/RunCreatorInfo" }, "request_usage": { "$ref": "#/components/schemas/RequestUsage" }, "agent_config": { "$ref": "#/components/schemas/AmbientAgentConfig" }, "conversation_id": { "type": "string", "description": "UUID of the conversation associated with the run" }, "parent_run_id": { "type": "string", "description": "UUID of the parent run that spawned this run" }, "is_sandbox_running": { "type": "boolean", "description": "Whether the sandbox environment is currently running" }, "artifacts": { "type": "array", "items": { "$ref": "#/components/schemas/ArtifactItem" }, "description": "Artifacts created during the run (plans, pull requests, etc.)" }, "agent_skill": { "$ref": "#/components/schemas/AgentSkill" }, "scope": { "$ref": "#/components/schemas/Scope" } } }, "GetRunTimelineResponse": { "type": "object", "description": "Response body for listing run timeline events.", "required": [ "events" ], "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/AIRunTimelineEvent" } } } }, "AIRunTimelineEvent": { "type": "object", "description": "A setup or lifecycle event recorded for an agent run.", "required": [ "event_uuid", "run_id", "event_type", "occurred_at" ], "properties": { "event_uuid": { "type": "string", "description": "Unique client- or server-generated identifier for this event." }, "run_id": { "type": "string", "description": "Run that owns this event." }, "execution_id": { "type": "integer", "format": "int64", "description": "Run execution associated with this event, when available." }, "event_type": { "$ref": "#/components/schemas/AIRunTimelineEventType" }, "occurred_at": { "type": "string", "format": "date-time", "description": "Timestamp when the event occurred." }, "payload": { "type": "object", "additionalProperties": true, "description": "Optional event-specific JSON payload." } } }, "AIRunTimelineEventType": { "type": "string", "description": "Type of timeline event recorded for a run.", "enum": [ "oz_run_created", "oz_run_claimed", "worker_container_ready", "shared_session_started", "agent_started", "oz_run_finished", "oz_run_failure" ] }, "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" } ], "discriminator": { "propertyName": "artifact_type", "mapping": { "PLAN": "#/components/schemas/PlanArtifact", "PULL_REQUEST": "#/components/schemas/PullRequestArtifact", "SCREENSHOT": "#/components/schemas/ScreenshotArtifact", "FILE": "#/components/schemas/FileArtifact" } } }, "PlanArtifact": { "type": "object", "required": [ "artifact_type", "created_at", "data" ], "properties": { "artifact_type": { "type": "string", "enum": [ "PLAN" ], "description": "Type of the artifact" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the artifact was created (RFC3339)" }, "data": { "$ref": "#/components/schemas/PlanArtifactData" } } }, "PullRequestArtifact": { "type": "object", "required": [ "artifact_type", "created_at", "data" ], "properties": { "artifact_type": { "type": "string", "enum": [ "PULL_REQUEST" ], "description": "Type of the artifact" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the artifact was created (RFC3339)" }, "data": { "$ref": "#/components/schemas/PullRequestArtifactData" } } }, "ScreenshotArtifact": { "type": "object", "required": [ "artifact_type", "created_at", "data" ], "properties": { "artifact_type": { "type": "string", "enum": [ "SCREENSHOT" ], "description": "Type of the artifact" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the artifact was created (RFC3339)" }, "data": { "$ref": "#/components/schemas/ScreenshotArtifactData" } } }, "FileArtifact": { "type": "object", "required": [ "artifact_type", "created_at", "data" ], "properties": { "artifact_type": { "type": "string", "enum": [ "FILE" ], "description": "Type of the artifact" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the artifact was created (RFC3339)" }, "data": { "$ref": "#/components/schemas/FileArtifactData" } } }, "PlanArtifactData": { "type": "object", "required": [ "document_uid" ], "properties": { "artifact_uid": { "type": "string", "description": "Unique identifier for the plan artifact, usable with the artifact retrieval endpoint" }, "document_uid": { "type": "string", "description": "Unique identifier for the plan document" }, "notebook_uid": { "type": "string", "description": "Unique identifier for the associated notebook" }, "url": { "type": "string", "format": "uri", "description": "URL to open the plan in Warp Drive" }, "title": { "type": "string", "description": "Title of the plan" } } }, "PullRequestArtifactData": { "type": "object", "required": [ "url", "branch" ], "properties": { "url": { "type": "string", "format": "uri", "description": "URL of the pull request" }, "branch": { "type": "string", "description": "Branch name for the pull request" } } }, "ScreenshotArtifactData": { "type": "object", "required": [ "artifact_uid", "mime_type" ], "properties": { "artifact_uid": { "type": "string", "description": "Unique identifier for the screenshot artifact" }, "mime_type": { "type": "string", "description": "MIME type of the screenshot image" }, "description": { "type": "string", "description": "Optional description of the screenshot" } } }, "FileArtifactData": { "type": "object", "required": [ "artifact_uid", "filepath", "filename", "mime_type" ], "properties": { "artifact_uid": { "type": "string", "description": "Unique identifier for the file artifact" }, "filepath": { "type": "string", "description": "Conversation-relative filepath for the uploaded file" }, "filename": { "type": "string", "description": "Last path component of filepath" }, "description": { "type": "string", "description": "Optional description of the file" }, "mime_type": { "type": "string", "description": "MIME type of the uploaded file" }, "size_bytes": { "type": "integer", "format": "int64", "description": "Size of the uploaded file in bytes" } } }, "ScheduleInfo": { "type": "object", "description": "Information about the schedule that triggered this run (only present for scheduled runs)", "required": [ "schedule_id", "schedule_name", "cron_schedule" ], "properties": { "schedule_id": { "type": "string", "description": "Unique identifier for the schedule" }, "schedule_name": { "type": "string", "description": "Name of the schedule at the time the run was created" }, "cron_schedule": { "type": "string", "description": "Cron expression at the time the run was created" } } }, "PageInfo": { "type": "object", "required": [ "has_next_page" ], "properties": { "has_next_page": { "type": "boolean", "description": "Whether there are more results available" }, "next_cursor": { "type": "string", "description": "Opaque cursor for fetching the next page" } } }, "RunStatusMessage": { "type": "object", "description": "Status message for a run. For terminal error states, includes structured\nerror code and retryability info from the platform error catalog.\n", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "Human-readable status message" }, "error_code": { "$ref": "#/components/schemas/PlatformErrorCode" }, "retryable": { "type": "boolean", "description": "Whether the error is transient and the client may retry by submitting\na new run. Only present on terminal error states. When false, retrying\nwithout addressing the underlying cause will not succeed.\n" } } }, "RequestUsage": { "type": "object", "description": "Resource usage information for the run", "properties": { "inference_cost": { "type": "number", "format": "double", "description": "Cost of LLM inference for the run" }, "compute_cost": { "type": "number", "format": "double", "description": "Cost of compute resources for the run" }, "platform_cost": { "type": "number", "format": "double", "description": "Cost of platform usage for the run" } } }, "RunCreatorInfo": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user", "service_account" ], "description": "Type of the creator principal" }, "uid": { "type": "string", "description": "Unique identifier of the creator" }, "display_name": { "type": "string", "description": "Display name of the creator" }, "email": { "type": "string", "description": "Email address of the creator" }, "photo_url": { "type": "string", "format": "uri", "description": "URL to the creator's photo" } } }, "RunState": { "type": "string", "enum": [ "QUEUED", "PENDING", "CLAIMED", "INPROGRESS", "SUCCEEDED", "FAILED", "BLOCKED", "ERROR", "CANCELLED" ], "description": "Current state of the run:\n- QUEUED: Run is waiting to be picked up\n- PENDING: Run is being prepared\n- CLAIMED: Run has been claimed by a worker\n- INPROGRESS: Run is actively being executed\n- SUCCEEDED: Run completed successfully\n- FAILED: Run failed\n- BLOCKED: Run is blocked (e.g., awaiting user input or approval)\n- ERROR: Run encountered an error\n- CANCELLED: Run was cancelled by user\n" }, "RunSourceType": { "type": "string", "enum": [ "LINEAR", "API", "SLACK", "LOCAL", "SCHEDULED_AGENT", "WEB_APP", "GITHUB_ACTION", "CLOUD_MODE", "CLI" ], "description": "Source that created the run:\n- LINEAR: Created from Linear integration\n- API: Created via the Warp API\n- SLACK: Created from Slack integration\n- LOCAL: Created from local CLI/app\n- SCHEDULED_AGENT: Created by a scheduled agent\n- WEB_APP: Created from the Warp web app\n- GITHUB_ACTION: Created from a GitHub action\n- CLOUD_MODE: Created from a Cloud Mode\n- CLI: Created from the CLI\n" }, "RunExecutionLocation": { "type": "string", "enum": [ "LOCAL", "REMOTE" ], "description": "Where the run executed:\n- LOCAL: Executed in the user's local Oz 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" }, "skill_spec": { "type": "string", "description": "Skill specification identifying the primary agent skill to use.\nFormat: \"{owner}/{repo}:{skill_path}\"\nExample: \"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 compatibility.\nUse the list agents endpoint to discover available 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 false.\n" }, "idle_timeout_minutes": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 60, "description": "Number of minutes to keep the agent environment alive after task completion.\nIf not set, defaults to 10 minutes.\nMaximum allowed value is min(60, floor(max_instance_runtime_seconds / 60) for your billing tier).\n" }, "worker_host": { "type": "string", "description": "Self-hosted worker ID that should execute this task.\nIf not specified or set to \"warp\", the task runs on Warp-hosted workers.\n" }, "harness": { "$ref": "#/components/schemas/Harness" }, "harness_auth_secrets": { "$ref": "#/components/schemas/HarnessAuthSecrets" }, "session_sharing": { "$ref": "#/components/schemas/SessionSharingConfig" }, "memory_stores": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryStoreRef" }, "description": "Memory stores to attach to this run." }, "inference_providers": { "allOf": [ { "$ref": "#/components/schemas/InferenceProvidersConfig" } ], "description": "Optional inference provider settings for this run. Run-level\nconfig takes precedence over the agent's stored config and\nthe workspace's admin-configured defaults.\n" } } }, "SessionSharingConfig": { "type": "object", "description": "Configures sharing behavior for the run's shared session.\nWhen set, the worker emits `--share public:` and the bundled Warp\nclient applies an anyone-with-link ACL to the shared session once it has\nbootstrapped. The same ACL is mirrored onto the backing conversation so\nlink viewers can read the conversation without being on the run's team.\nSubject to the workspace-level anyone-with-link sharing setting.\n", "properties": { "public_access": { "type": "string", "enum": [ "VIEWER", "EDITOR" ], "description": "Grants anyone-with-link access at the specified level to the run's\nshared session and backing conversation.\n- VIEWER: link viewers can read the session and conversation.\n- EDITOR: link viewers can also interact with the session.\nAnonymous (unauthenticated) reads are not supported in this release;\nlink viewers must still be authenticated Warp users.\n" } } }, "Harness": { "type": "object", "description": "Specifies which execution harness to use for the agent run.\nDefault (nil/empty) uses Warp's built-in harness.\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" } } }, "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" }, "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).\nIncludes backward-compatible extension members.\n\nThe response uses the `application/problem+json` content type.\nAdditional extension members (e.g., `auth_url`, `provider`) may be\npresent depending on the error code.\n", "required": [ "type", "title", "status", "error" ], "properties": { "type": { "type": "string", "format": "uri", "description": "A URI reference that identifies the problem type (RFC 7807).\nFormat: `https://docs.warp.dev/reference/api-and-sdk/troubleshooting/errors/{error_code}`\nSee PlatformErrorCode for the list of possible error codes.\n" }, "title": { "type": "string", "description": "A short, human-readable summary of the problem type (RFC 7807)" }, "status": { "type": "integer", "description": "The HTTP status code for this occurrence of the problem (RFC 7807)" }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence of the problem (RFC 7807)" }, "instance": { "type": "string", "description": "The request path that generated this error (RFC 7807)" }, "error": { "type": "string", "description": "Human-readable error message combining title and detail.\nBackward-compatible extension member for older clients.\n" }, "retryable": { "type": "boolean", "description": "Whether the request can be retried. When true, the error is transient\nand the request may be retried. When false, retrying without addressing\nthe underlying cause will not succeed.\n" }, "trace_id": { "type": "string", "description": "OpenTelemetry trace ID for debugging and support requests" } } }, "ArtifactResponse": { "oneOf": [ { "$ref": "#/components/schemas/PlanArtifactResponse" }, { "$ref": "#/components/schemas/ScreenshotArtifactResponse" }, { "$ref": "#/components/schemas/FileArtifactResponse" } ], "discriminator": { "propertyName": "artifact_type", "mapping": { "PLAN": "#/components/schemas/PlanArtifactResponse", "SCREENSHOT": "#/components/schemas/ScreenshotArtifactResponse", "FILE": "#/components/schemas/FileArtifactResponse" } } }, "PlanArtifactResponse": { "type": "object", "description": "Response for retrieving a plan artifact.", "required": [ "artifact_uid", "artifact_type", "created_at", "data" ], "properties": { "artifact_uid": { "type": "string", "description": "Unique identifier (UUID) for the artifact" }, "artifact_type": { "type": "string", "enum": [ "PLAN" ], "description": "Type of the artifact" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the artifact was created (RFC3339)" }, "data": { "$ref": "#/components/schemas/PlanArtifactResponseData" } } }, "PlanArtifactResponseData": { "type": "object", "description": "Response data for a plan artifact, including current markdown content.", "required": [ "document_uid", "notebook_uid", "content", "content_type" ], "properties": { "document_uid": { "type": "string", "description": "Unique identifier for the plan document" }, "notebook_uid": { "type": "string", "description": "Unique identifier for the associated notebook" }, "url": { "type": "string", "format": "uri", "description": "URL to open the plan in Warp Drive" }, "title": { "type": "string", "description": "Current title of the plan" }, "content": { "type": "string", "description": "Current markdown content of the plan" }, "content_type": { "type": "string", "description": "MIME type of the returned plan content" } } }, "ScreenshotArtifactResponse": { "type": "object", "description": "Response for retrieving a screenshot artifact.", "required": [ "artifact_uid", "artifact_type", "created_at", "data" ], "properties": { "artifact_uid": { "type": "string", "description": "Unique identifier (UUID) for the artifact" }, "artifact_type": { "type": "string", "enum": [ "SCREENSHOT" ], "description": "Type of the artifact" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the artifact was created (RFC3339)" }, "data": { "$ref": "#/components/schemas/ScreenshotArtifactResponseData" } } }, "ScreenshotArtifactResponseData": { "type": "object", "description": "Response data for a screenshot artifact, including a signed download URL.", "required": [ "download_url", "expires_at", "content_type" ], "properties": { "download_url": { "type": "string", "format": "uri", "description": "Time-limited signed URL to download the screenshot" }, "expires_at": { "type": "string", "format": "date-time", "description": "Timestamp when the download URL expires (RFC3339)" }, "content_type": { "type": "string", "description": "MIME type of the screenshot (e.g., image/png)" }, "description": { "type": "string", "description": "Optional description of the screenshot" } } }, "FileArtifactResponse": { "type": "object", "description": "Response for retrieving a file artifact.", "required": [ "artifact_uid", "artifact_type", "created_at", "data" ], "properties": { "artifact_uid": { "type": "string", "description": "Unique identifier (UUID) for the artifact" }, "artifact_type": { "type": "string", "enum": [ "FILE" ], "description": "Type of the artifact" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the artifact was created (RFC3339)" }, "data": { "$ref": "#/components/schemas/FileArtifactResponseData" } } }, "FileArtifactResponseData": { "type": "object", "description": "Response data for a file artifact, including a signed download URL.", "required": [ "download_url", "expires_at", "content_type", "filepath", "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" }, "filename": { "type": "string", "description": "Last path component of filepath" }, "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" }, "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" } } }, "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" } } }, "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" } } }, "ProvidersConfig": { "type": "object", "description": "Optional cloud provider configurations for automatic auth", "properties": { "gcp": { "$ref": "#/components/schemas/GcpProviderConfig" }, "aws": { "$ref": "#/components/schemas/AwsProviderConfig" } } }, "InferenceProvidersConfig": { "type": "object", "description": "Inference provider settings used for LLM calls.", "properties": { "aws": { "$ref": "#/components/schemas/AwsInferenceProviderConfig" } } }, "GcpProviderConfig": { "type": "object", "description": "GCP Workload Identity Federation settings", "required": [ "project_number", "workload_identity_federation_pool_id", "workload_identity_federation_provider_id" ], "externalDocs": { "description": "Google documentation on Workload Identity Federation", "url": "https://docs.cloud.google.com/iam/docs/workload-identity-federation" }, "properties": { "project_number": { "type": "string", "description": "GCP project number" }, "workload_identity_federation_pool_id": { "type": "string", "description": "Workload Identity Federation pool ID" }, "workload_identity_federation_provider_id": { "type": "string", "description": "Workload Identity Federation provider ID" }, "service_account_email": { "type": "string", "description": "Optional GCP service account email to impersonate" } } }, "AwsProviderConfig": { "type": "object", "description": "AWS IAM role assumption settings", "externalDocs": { "description": "AWS documentation on IAM OIDC federation", "url": "https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html" }, "required": [ "role_arn" ], "properties": { "role_arn": { "type": "string", "description": "AWS IAM role ARN to assume" } } }, "AwsInferenceProviderConfig": { "type": "object", "description": "Configures AWS Bedrock as the LLM inference provider for this\nagent or run.\n", "externalDocs": { "description": "AWS documentation on IAM OIDC federation", "url": "https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html" }, "properties": { "disabled": { "type": "boolean", "description": "If true, opt out of Bedrock at this layer." }, "role_arn": { "type": "string", "description": "IAM role ARN to assume when calling Bedrock." }, "region": { "type": "string", "description": "AWS region used for STS when assuming the Bedrock inference role." } } }, "GitHubRepo": { "type": "object", "required": [ "owner", "repo" ], "properties": { "owner": { "type": "string", "description": "GitHub repository owner (user or organization)" }, "repo": { "type": "string", "description": "GitHub repository name" } } }, "ListAgentsResponse": { "type": "object", "required": [ "agents" ], "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/AgentListItem" }, "description": "List of available agents" } } }, "ListConnectedSelfHostedWorkersResponse": { "type": "object", "required": [ "workers" ], "properties": { "workers": { "type": "array", "items": { "$ref": "#/components/schemas/ConnectedSelfHostedWorker" }, "description": "Connected self-hosted workers for the authenticated principal's team" } } }, "ConnectedSelfHostedWorker": { "type": "object", "required": [ "worker_host", "connection_count", "connected_at", "last_seen_at" ], "properties": { "worker_host": { "type": "string", "description": "Logical host identifier provided by the self-hosted worker" }, "connection_count": { "type": "integer", "description": "Number of active websocket connections currently observed for this worker host" }, "connected_at": { "type": "string", "format": "date-time", "description": "Earliest connection timestamp across active connections for this worker host" }, "last_seen_at": { "type": "string", "format": "date-time", "description": "Most recent heartbeat timestamp across active connections for this worker host" } } }, "AgentListItem": { "type": "object", "required": [ "name", "variants" ], "properties": { "name": { "type": "string", "description": "Human-readable name of the agent" }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/AgentListVariant" }, "description": "Available variants of this agent" } } }, "AgentListVariant": { "type": "object", "required": [ "id", "description", "base_prompt", "source", "environments" ], "properties": { "id": { "type": "string", "description": "Stable identifier for this skill variant.\nFormat: \"{owner}/{repo}:{skill_path}\"\nExample: \"warpdotdev/warp-server:.claude/skills/deploy/SKILL.md\"\n" }, "description": { "type": "string", "description": "Description of the agent variant" }, "base_prompt": { "type": "string", "description": "Base prompt/instructions for the agent" }, "source": { "$ref": "#/components/schemas/AgentListSource" }, "environments": { "type": "array", "items": { "$ref": "#/components/schemas/AgentListEnvironment" }, "description": "Environments where this agent variant is available" }, "last_run_timestamp": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp of the last time this skill was run (RFC3339)" }, "error": { "type": "string", "description": "Non-empty when the skill's SKILL.md file exists but is malformed.\nContains a description of the parse failure. Only present when\ninclude_malformed_skills=true is passed to the list agents endpoint.\n" } } }, "AgentListSource": { "type": "object", "required": [ "owner", "name", "skill_path" ], "properties": { "owner": { "type": "string", "description": "GitHub repository owner" }, "name": { "type": "string", "description": "GitHub repository name" }, "skill_path": { "type": "string", "description": "Path to the skill definition file within the repository" }, "worker_host": { "type": "string", "description": "Self-hosted worker host that reported this skill.\nPresent only for skills discovered from self-hosted workers\n(as opposed to skills from GitHub repos linked to environments).\n" } } }, "AgentListEnvironment": { "type": "object", "required": [ "uid", "name" ], "properties": { "uid": { "type": "string", "description": "Unique identifier for the environment" }, "name": { "type": "string", "description": "Human-readable name of the environment" } } }, "Scope": { "type": "object", "description": "Ownership scope for a resource (team or personal)", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "User", "Team" ], "description": "Type of ownership (\"User\" for personal, \"Team\" for team-owned)" }, "uid": { "type": "string", "description": "UID of the owning user or team" } } }, "PlatformErrorCode": { "type": "string", "description": "Machine-readable error code identifying the problem type.\nUsed in the `type` URI of Error responses and in the `error_code`\nfield of RunStatusMessage.\n\nUser errors (run transitions to FAILED):\n- `insufficient_credits` — Team has no remaining add-on credits\n- `feature_not_available` — Required feature not enabled for user's plan\n- `external_authentication_required` — User hasn't authorized a required external service\n- `not_authorized` — Principal lacks permission for the requested operation\n- `invalid_request` — Request is malformed or contains invalid parameters\n- `resource_not_found` — Referenced resource does not exist\n- `budget_exceeded` — Spending budget limit has been reached\n- `integration_disabled` — Integration is disabled and must be enabled\n- `integration_not_configured` — Integration setup is incomplete\n- `operation_not_supported` — Requested operation not supported for this resource/state\n- `environment_setup_failed` — Client-side environment setup failed\n- `content_policy_violation` — Prompt or setup commands violated content policy\n- `conflict` — Request conflicts with the current state of the resource\n\nWarp errors (run transitions to ERROR):\n- `authentication_required` — Request lacks valid authentication credentials\n- `resource_unavailable` — Transient infrastructure issue (retryable)\n- `internal_error` — Unexpected server-side error (retryable)\n", "enum": [ "insufficient_credits", "feature_not_available", "external_authentication_required", "not_authorized", "invalid_request", "resource_not_found", "budget_exceeded", "integration_disabled", "integration_not_configured", "operation_not_supported", "environment_setup_failed", "content_policy_violation", "conflict", "authentication_required", "resource_unavailable", "internal_error" ] }, "RunFollowupRequest": { "type": "object", "description": "Request body for submitting a follow-up message to an existing run.", "properties": { "message": { "type": "string", "description": "The follow-up message to send to the run." }, "mode": { "$ref": "#/components/schemas/AgentRunMode", "description": "Optional query mode for the follow-up. Defaults to `normal` when\nomitted. The server does not infer mode from prompt prefixes such\nas `/plan`.\n" } } }, "ListModelsResponse": { "type": "object", "required": [ "default_model_id", "models" ], "properties": { "default_model_id": { "type": "string", "description": "The ID of the default model for agent runs" }, "models": { "type": "array", "items": { "$ref": "#/components/schemas/ModelInfo" }, "description": "List of available models" } } }, "ModelInfo": { "type": "object", "required": [ "id", "display_name", "provider", "vision_supported" ], "properties": { "id": { "type": "string", "description": "Unique identifier for the model (e.g. \"claude-4-6-opus-high\" or \"gpt-5-4-high\")" }, "display_name": { "type": "string", "description": "Human-readable name of the model" }, "provider": { "type": "string", "enum": [ "OPENAI", "ANTHROPIC", "GOOGLE", "UNKNOWN" ], "description": "The LLM provider" }, "vision_supported": { "type": "boolean", "description": "Whether the model supports vision/image inputs" }, "description": { "type": "string", "description": "Optional extra descriptor for the model" }, "reasoning_level": { "type": "string", "description": "Reasoning level descriptor, if any (e.g. \"low\", \"medium\", \"high\")" }, "disable_reason": { "type": "string", "enum": [ "PROVIDER_OUTAGE", "OUT_OF_REQUESTS", "ADMIN_DISABLED", "REQUIRES_UPGRADE" ], "description": "If set, the model is currently unavailable for the given reason" } } }, "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." } } }, "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" }, "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_stores": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryStoreRef" }, "description": "Optional list of memory stores to attach to the agent.\nEach store must be team-owned by the same team as the agent.\nDuplicate UIDs within a single request are rejected.\n" }, "base_harness": { "type": "string", "nullable": true, "description": "Optional default harness for runs executed by this agent.\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" } } }, "UpdateAgentRequest": { "type": "object", "description": "Partial update for an agent. Each field is optional:\n * Omitted or `null`: leave the field unchanged.\n * Empty value: clear the field.\n * Non-empty: replace the field wholesale with the provided value.\n", "properties": { "name": { "type": "string", "description": "The new name for the agent" }, "description": { "type": "string", "nullable": true, "description": "Replacement description. Omit or pass `null` to leave unchanged, or use an empty value to clear.\n" }, "prompt": { "type": "string", "nullable": true, "description": "Replacement prompt. Omit or pass `null` to leave unchanged, or use an empty value to clear.\n" }, "environment_id": { "type": "string", "nullable": true, "description": "Replacement default cloud environment ID. Omit or pass `null` to leave unchanged,\nor pass an empty string to clear.\n" }, "secrets": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/SecretRef" }, "description": "Replacement list of secrets. Omit to leave unchanged, pass an\nempty array to clear, or pass a non-empty array to replace.\nDuplicate names are rejected.\n" }, "skills": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Replacement list of skill specs. Omit to leave unchanged, pass an empty array\nto clear, or pass a non-empty array to replace.\n" }, "base_model": { "type": "string", "nullable": true, "description": "Replacement base model. Omit or pass `null` to leave unchanged,\nor pass an empty string to clear.\n" }, "memory_stores": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/MemoryStoreRef" }, "description": "Replacement list of memory stores. Omit to leave unchanged, pass an empty array\nto clear, or pass a non-empty array to replace.\n" }, "inference_providers": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/InferenceProvidersConfig" } ], "nullable": true, "description": "Replacement inference provider settings for this agent.\nAgent-level config takes precedence over the workspace's\nadmin-configured defaults. Omit or pass `null` to leave\nunchanged. Pass an empty object `{}` to clear.\n" }, "base_harness": { "type": "string", "nullable": true, "description": "Replacement default harness. Omit or pass `null` to leave unchanged,\nor pass an empty string to clear.\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" } } }, "AgentResponse": { "type": "object", "required": [ "uid", "name", "available", "created_at", "updated_at", "secrets", "skills", "memory_stores" ], "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. The 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" }, "available": { "type": "boolean", "description": "Whether this agent is within the team's plan limit and can be used for runs" }, "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 order 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_stores": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryStoreRef" }, "description": "Memory stores attached to this agent.\nAlways present; empty when no stores are attached.\n" }, "base_harness": { "type": "string", "description": "Default harness for runs executed by this agent. The precedence order for harness resolution is:\n1. The harness specified on the run itself\n2. The agent's base harness\n3. Oz\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" } } }, "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" } } } } } }