diff --git a/.agents/skills/sync-openapi-spec/references/sync-policy.md b/.agents/skills/sync-openapi-spec/references/sync-policy.md index 2c36c72e6..6cc0eb196 100644 --- a/.agents/skills/sync-openapi-spec/references/sync-policy.md +++ b/.agents/skills/sync-openapi-spec/references/sync-policy.md @@ -83,8 +83,8 @@ These tags back Agent Memory, which is a research preview. The tag was renamed ` ### `harness-support` The `/harness-support/*` endpoints form the worker-to-server contract used by Oz workers (transcripts, snapshots, finish-task signaling, etc.). They are not part of the public API contract — customers should not call them directly. Excluded permanently. -### `factory` -Oz Factory has not shipped publicly. Its `FactoryMcp` flag is dogfood and the `@warp/factory` front end is internal, so none of its endpoints belong in the public reference. Remove this tag when Factory goes GA. +### `factory` (no longer excluded) +The `factory` tag was excluded while Warp Factories was pre-launch. It came out of `EXCLUDED_TAGS` (and `/factory` out of `EXCLUDED_PATH_PREFIXES`) when Warp Factories shipped in Early Access and `/factories/factory-api/` began documenting `GET /factory`, `GET /factory/{uid}`, and `POST /factory/{uid}/runs`. Factory operations now follow the `x-internal` markers like every other kept tag: the server spec marks each private factory operation individually, so only the public discover-and-dispatch and scorer operations reach the reference. Do not re-add a blanket exclusion; ask the server team to mark specific operations `x-internal` instead. ## Excluded paths (within otherwise-public tags) @@ -99,7 +99,7 @@ If any of these become stable public surfaces, remove them from `EXCLUDED_PATHS` ## Excluded path prefixes -`EXCLUDED_PATH_PREFIXES` drops a path by prefix regardless of how its operations are tagged. Today it holds a single entry, `/factory`, because some Factory operations are tagged `agent` upstream — `GET /factory/scorers/{scorer_id}/results` is one — so a tags-only rule leaks them into the public reference. Use a prefix only when a whole URL namespace is private; prefer a tag or an explicit path everywhere else. +`EXCLUDED_PATH_PREFIXES` drops a path by prefix regardless of how its operations are tagged or marked. It is empty today; `/factory` was its only entry while Warp Factories was pre-launch (see "`factory` (no longer excluded)" above). Use a prefix only when a whole URL namespace is private; prefer a tag or an explicit path everywhere else. ## `x-internal` operations are dropped diff --git a/.agents/skills/sync-openapi-spec/scripts/sync_openapi.py b/.agents/skills/sync-openapi-spec/scripts/sync_openapi.py index 7ef73d01d..4a8a3eff2 100644 --- a/.agents/skills/sync-openapi-spec/scripts/sync_openapi.py +++ b/.agents/skills/sync-openapi-spec/scripts/sync_openapi.py @@ -53,11 +53,16 @@ # Tags whose paths and tag entry should be removed entirely. # `memory_stores` / `memory` back Agent Memory, which is a research preview. # `harness-support` is the worker-to-server contract — not a public API. -# `factory` is Oz Factory, which has not shipped publicly. # These are belt-and-braces on top of the `x-internal` filter below: a tag can # be private even when individual operations aren't marked internal yet. +# +# `factory` is deliberately NOT excluded. Warp Factories shipped in Early +# Access, /factories/factory-api/ documents the public endpoints, and the +# server spec marks every private factory operation `x-internal` +# individually — so the `x-internal` filter is the source of truth for +# which factory operations are public, same as the `agent` tag. EXCLUDED_TAGS: frozenset[str] = frozenset( - {"memory_stores", "memory", "harness-support", "factory"} + {"memory_stores", "memory", "harness-support"} ) # OpenAPI extension warp-server uses to mark an operation private. Mirrors @@ -98,11 +103,12 @@ } ) -# Path prefixes that are private no matter how the operation is tagged. Tag -# checks alone are not enough here: some Factory operations are tagged `agent` -# upstream (for example `GET /factory/scorers/{scorer_id}/results`), so a -# tags-only rule would leak them into the public reference. -EXCLUDED_PATH_PREFIXES: tuple[str, ...] = ("/factory",) +# Path prefixes that are private no matter how the operation is tagged, +# regardless of `x-internal` markers. Empty today: `/factory` was listed here +# while Warp Factories was pre-launch, and came out when the factory API went +# public (see references/sync-policy.md). Use a prefix only when a whole URL +# namespace is private. +EXCLUDED_PATH_PREFIXES: tuple[str, ...] = () # Default checkout layout: docs/ and warp-server/ as siblings. DEFAULT_SOURCE = Path("../warp-server/public_api/openapi.yaml") @@ -470,11 +476,11 @@ def _summarize_drift( def _unknown_classifications(source: dict[str, Any]) -> list[str]: """Flag tags or paths the policy doesn't already cover. - The skill's policy currently knows about the `agent` and `schedules` - tags (kept) and `memory_stores`/`harness-support` (dropped). Anything - else needs human triage. + The skill's policy currently knows about the `agent`, `schedules`, and + `factory` tags (kept) and `memory_stores`/`memory`/`harness-support` + (dropped). Anything else needs human triage. """ - KNOWN_TAGS = {"agent", "schedules"} | set(EXCLUDED_TAGS) + KNOWN_TAGS = {"agent", "schedules", "factory"} | set(EXCLUDED_TAGS) notes: list[str] = [] for tag in source.get("tags") or []: diff --git a/developers/agent-api-openapi.yaml b/developers/agent-api-openapi.yaml index 0d50c00dd..a4faf8d9b 100644 --- a/developers/agent-api-openapi.yaml +++ b/developers/agent-api-openapi.yaml @@ -1,8 +1,8 @@ openapi: 3.0.0 info: - title: Oz Agent API + title: Warp 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" + description: "API for creating, managing, and querying Warp cloud agent runs.\n\nThese endpoints allow users to programmatically spawn agents, list runs, \nand retrieve detailed run information.\n" contact: name: Warp Support url: https://docs.warp.dev @@ -18,6 +18,177 @@ tags: - name: schedules description: Operations for creating and managing scheduled agents paths: + /factory: + get: + summary: List factories + description: | + List factories accessible to the authenticated principal. An optional + team_uid query parameter restricts results to a single team, and an + optional search query parameter filters by a case-insensitive + substring match on the factory name or alias. + operationId: listFactories + tags: + - factory + security: + - bearerAuth: [] + parameters: + - name: team_uid + in: query + description: Optional team UID to filter factories by ownership. + required: false + schema: + type: string + - name: search + in: query + description: | + Case-insensitive substring search over the factory name and + alias. + required: false + schema: + type: string + - name: limit + in: query + description: Maximum number of factories to return (default 50, max 100). + required: false + schema: + type: integer + minimum: 1 + maximum: 100 + - name: cursor + in: query + description: Opaque cursor returned by a previous list response. + required: false + schema: + type: string + responses: + '200': + description: List of factories + content: + application/json: + schema: + $ref: '#/components/schemas/ListFactoriesResponse' + '401': + description: Authentication required + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Error' + '403': + $ref: '#/components/responses/FactoryAccessDenied' + '500': + description: Internal server error + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Error' + /factory/{uid}: + get: + summary: Get a factory + description: Get a factory by its public UID. + operationId: getFactory + tags: + - factory + security: + - bearerAuth: [] + parameters: + - name: uid + in: path + description: The public UID of the factory. + required: true + schema: + type: string + responses: + '200': + description: Factory details + content: + application/json: + schema: + $ref: '#/components/schemas/Factory' + '401': + description: Authentication required + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Error' + '403': + $ref: '#/components/responses/FactoryAccessDenied' + '404': + description: Factory not found + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Error' + '500': + description: Internal server error + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Error' + /factory/{uid}/runs: + post: + summary: Dispatch a run to a factory + description: | + Dispatch a run to a factory by its UID, using prompt as the run's + prompt and an optional title, ticket_ref, and ticket_url. Returns + the created run; its factory task is created asynchronously and can + be resolved afterwards with GET /factory/{uid}/task-by-run. + operationId: createFactoryRun + tags: + - factory + security: + - bearerAuth: [] + parameters: + - name: uid + in: path + description: The public UID of the factory. + required: true + schema: + type: string + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/FactoryRunRequest' + responses: + '201': + description: Run dispatched successfully + content: + application/json: + schema: + $ref: '#/components/schemas/FactoryRunResponse' + '400': + description: Invalid request body or ticket_ref + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Error' + '401': + description: Authentication required + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Error' + '403': + $ref: '#/components/responses/FactoryAccessDenied' + '404': + description: Factory not found or not accessible + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Error' + '409': + description: The factory has no foreman agent to receive work + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Error' + '500': + description: Internal server error + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Error' /agent: get: summary: List available agents @@ -433,10 +604,10 @@ paths: - name: metadata in: query description: | - Filter by exact metadata key/value pairs using object notation (e.g. - `metadata[ticket_id]=VIS-238`). Multiple pairs combine with AND semantics. - At most 5 pairs per request. Returns `feature_not_available` when metadata - filtering is not enabled. + Filter by exact metadata key/value pairs using object notation + (e.g. `metadata[ticket_id]=VIS-238`), combining multiple pairs + with AND semantics, up to 5 per request. Returns + `feature_not_available` when metadata filtering is not enabled. required: false schema: type: object @@ -699,13 +870,11 @@ paths: post: summary: Cancel a run description: | - Cancel an agent run that is currently queued or in progress. - Once cancelled, the run will transition to a cancelled state. - - Not all runs can be cancelled. Runs that are in a terminal state - (SUCCEEDED, FAILED, ERROR, BLOCKED, CANCELLED) return 400. Runs in - PENDING state return 409 (retry after a moment). Self-hosted, local, - and GitHub Action runs return 422. + Cancel an agent run that is currently queued or in progress; once + cancelled, the run transitions to a cancelled state. Not all runs can + be cancelled: a run already in a terminal state, in PENDING, or of an + unsupported type (self-hosted, local, GitHub Action) is rejected + instead — see the error responses below for each case. operationId: cancelRun tags: - agent @@ -1309,13 +1478,11 @@ paths: get: summary: Get artifact details description: | - Retrieve an artifact by its UUID. For downloadable file-like artifacts, - returns a time-limited signed download URL. For plan artifacts, returns - the current plan content inline. - - Public artifacts can be read without authentication; private artifacts - require the caller to be authenticated and authorized. Anonymous reads - of public file artifacts omit the `filepath` field. + Retrieve an artifact by its UUID: a time-limited signed download URL + for downloadable file-like artifacts, or the current plan content + inline for plan artifacts. Public artifacts can be read without + authentication; private artifacts require the caller to be + authenticated and authorized. operationId: getArtifact tags: - agent @@ -1421,32 +1588,45 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /agent/identities: - post: - summary: Create an agent + /factory/scorers/{scorer_id}: + patch: + summary: Update a scorer's definition description: | - Create a new agent for the caller's team. - Agents can be used as the execution principal for team-owned runs. - operationId: createAgent + Apply a partial update to a scorer's definition; omitted fields are + left unchanged, but at least one field must be provided, and the + owning factory is immutable. Each update bumps the scorer's version + without invalidating any scoring judge already in flight, since + judges validate against the definition snapshot taken at dispatch + time, and historical scores keep their recorded classification + values. Supplying `scope_mode` or `agent_uids` replaces the scorer's + scope in full. + operationId: updateScorer tags: - - agent + - factory security: - bearerAuth: [] + parameters: + - name: scorer_id + in: path + description: The scorer identifier + required: true + schema: + type: integer requestBody: required: true content: application/json: schema: - $ref: '#/components/schemas/CreateAgentRequest' + $ref: '#/components/schemas/UpdateScorerRequest' responses: - '201': - description: Agent created successfully + '200': + description: The updated scorer content: application/json: schema: - $ref: '#/components/schemas/AgentResponse' + $ref: '#/components/schemas/ScorerResponse' '400': - description: Invalid request (empty name, user on multiple teams, or on no team) + description: Invalid scorer update content: application/json: schema: @@ -1458,7 +1638,9 @@ paths: schema: $ref: '#/components/schemas/Error' '403': - description: Only human users can manage agents, or plan limit exceeded + $ref: '#/components/responses/FactoryAccessDenied' + '404': + description: Scorer not found, or the caller cannot manage its factory content: application/json: schema: @@ -1469,27 +1651,35 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - get: - summary: List agents + delete: + summary: Delete a scorer description: | - List all agents for the caller's team. Each agent includes - an `available` flag indicating whether it is within the team's plan limit - and may be used for runs. - operationId: listAgents + Permanently delete a scorer. This is not reversible and it is not an + archive: the scorer's scoring attempts, scores, judge reasoning, self-improvement + config, and self-improvement triage results go with it, and the scorer stops + being readable through this API as soon as the call returns. + + The underlying rows and the judge-reasoning blobs stored outside the + database are destroyed shortly afterwards by the deletion sweep, which + removes each blob before the record that references it and retries until + both are gone. + operationId: deleteScorer tags: - - agent + - factory security: - bearerAuth: [] - parameters: [] + parameters: + - name: scorer_id + in: path + description: The scorer identifier + required: true + schema: + type: integer responses: - '200': - description: List of agents - content: - application/json: - schema: - $ref: '#/components/schemas/ListAgentIdentitiesResponse' + '204': + description: Scorer deleted '400': - description: User on multiple teams, or on no team + description: Invalid scorer ID content: application/json: schema: @@ -1501,7 +1691,9 @@ paths: schema: $ref: '#/components/schemas/Error' '403': - description: Only human users can list agents + $ref: '#/components/responses/FactoryAccessDenied' + '404': + description: Scorer not found, or the caller cannot manage its factory content: application/json: schema: @@ -1512,48 +1704,32 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /agent/runs/{runId}/scores: + /agent/identities: post: - summary: Report evaluation scores for a run + summary: Create an agent description: | - Report one or more evaluation verdicts for a run. Called by the judge run - that was dispatched to score this run, authenticating with that judge - run's API key. Each verdict is processed independently: the response - reports per-verdict acceptance, and a rejected verdict does not block the - others. Reporting a subset of the run's evaluations is valid. - operationId: reportRunScores + Create a new agent for the caller's team. + Agents can be used as the execution principal for team-owned runs. + operationId: createAgent tags: - agent security: - bearerAuth: [] - parameters: - - name: runId - in: path - description: The run being scored - required: true - schema: - type: string requestBody: required: true content: application/json: schema: - $ref: '#/components/schemas/ReportRunScoresRequest' + $ref: '#/components/schemas/CreateAgentRequest' responses: - '200': - description: Every reported verdict was accepted - content: - application/json: - schema: - $ref: '#/components/schemas/ReportRunScoresResponse' - '206': - description: The request was well-formed but at least one verdict was rejected; inspect each result's status and error before deciding whether to resubmit + '201': + description: Agent created successfully content: application/json: schema: - $ref: '#/components/schemas/ReportRunScoresResponse' + $ref: '#/components/schemas/AgentResponse' '400': - description: Malformed request body + description: Invalid request (empty name, user on multiple teams, or on no team) content: application/json: schema: @@ -1564,46 +1740,51 @@ paths: 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' - /agent/identities/{uid}: get: - summary: Retrieve an agent + summary: List agents description: | - Retrieve a single agent by its unique identifier. - The response includes an `available` flag indicating whether the agent - is within the team's plan limit and may be used for runs. - operationId: getAgent + List all agents for the caller's team. Each agent includes + an `available` flag indicating whether it is within the team's plan limit + and may be used for runs. + operationId: listAgents tags: - agent security: - bearerAuth: [] - parameters: - - name: uid - in: path - description: The unique identifier of the agent - required: true - schema: - type: string + parameters: [] responses: '200': - description: Agent details + description: List of agents content: application/json: schema: - $ref: '#/components/schemas/AgentResponse' + $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' - '404': - description: Agent not found + '403': + description: Only human users can list agents content: application/json: schema: @@ -1614,37 +1795,35 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - put: - summary: Update an agent + /factory/scorers: + post: + summary: Create a scorer description: | - Update an existing agent. - operationId: updateAgent + Create an active run scorer for a factory with either selected-agent or + all-agent scope. Creating a scorer does not start scoring. Pass + self_improvement_enabled to also turn on self-improvement for the new scorer in the same + request; the scorer and its self-improvement config are created atomically, so + a failure leaves neither behind. + operationId: createScorer tags: - - agent + - factory 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' + $ref: '#/components/schemas/CreateScorerRequest' responses: - '200': - description: Agent updated successfully + '201': + description: Scorer created successfully content: application/json: schema: - $ref: '#/components/schemas/AgentResponse' + $ref: '#/components/schemas/ScorerResponse' '400': - description: Missing or invalid request body + description: Invalid scorer definition content: application/json: schema: @@ -1656,13 +1835,13 @@ paths: schema: $ref: '#/components/schemas/Error' '403': - description: Only human users can manage agents, or plan limit exceeded + description: Caller cannot edit the factory content: application/json: schema: $ref: '#/components/schemas/Error' '404': - description: Agent not found + description: Factory not found content: application/json: schema: @@ -1673,28 +1852,96 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - delete: - summary: Delete an agent + get: + summary: List agent scorers description: | - Delete an agent. All API keys associated with the - agent are deleted atomically. - operationId: deleteAgent + List the scorers owned by the caller's team, including scope agents + and aggregate scoring stats. Pass factory_uid to narrow the result to a + single factory. + operationId: listScorers + tags: + - agent + security: + - bearerAuth: [] + parameters: [] + responses: + '200': + description: Scorers for the caller's team + content: + application/json: + schema: + $ref: '#/components/schemas/ListScorersResponse' + '400': + description: | + Invalid recent_outcomes_limit (not an integer in 1-100), or an + invalid start_date/end_date pair: one given without the other, + an unparseable RFC3339 timestamp, or start_date not strictly + before end_date. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '401': + description: Authentication required + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '403': + description: Only human users can list scorers + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '500': + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /factory/scorers/{scorer_id}/results: + get: + summary: List recent results for an scorer + description: | + List the scorer's most recent scoring attempts, newest first. A + failed attempt carries no classification. Pagination is a keyset + cursor over attempted_at with the attempt id as a stable tiebreak. + operationId: listScorerResults tags: - agent security: - bearerAuth: [] parameters: - - name: uid + - name: scorer_id in: path - description: The unique identifier of the agent + description: The scorer identifier required: true + schema: + type: integer + - name: limit + in: query + description: Maximum number of results to return (1-100, default 50) + required: false + schema: + type: integer + minimum: 1 + maximum: 100 + default: 50 + - name: cursor + in: query + description: Opaque cursor returned by a previous list response. + required: false schema: type: string responses: - '204': - description: Agent deleted successfully + '200': + description: Recent results for the scorer + content: + application/json: + schema: + $ref: '#/components/schemas/ListScorerResultsResponse' '400': - description: Cannot delete the default agent + description: Invalid scorer ID, limit, or cursor content: application/json: schema: @@ -1706,13 +1953,73 @@ paths: schema: $ref: '#/components/schemas/Error' '403': - description: Only human users can manage agents + $ref: '#/components/responses/FactoryAccessDenied' + '404': + description: Scorer not found + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '500': + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /factory/scorers/{scorer_id}/results/reasons: + get: + summary: Read judge reasons for a page of scorer results + description: | + Read the judge's reasoning for the given runs in one request, so a page + of results can show reasons alongside classifications. Reasons are + stored outside the database and read per run with bounded concurrency; + a run whose reason is missing or unreadable is reported individually so + one unavailable reason never fails the request. + operationId: listScorerResultReasons + tags: + - agent + security: + - bearerAuth: [] + parameters: + - name: scorer_id + in: path + description: The scorer identifier + required: true + schema: + type: integer + - name: run_id + in: query + description: | + Runs to read reasons for. Repeat the parameter once per run; at + most 100 distinct runs (the results page maximum) per request. + required: true + schema: + type: array + items: + type: string + responses: + '200': + description: One entry per requested run, in request order + content: + application/json: + schema: + $ref: '#/components/schemas/ListScorerResultReasonsResponse' + '400': + description: Invalid scorer ID, missing run_id, or too many runs + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '401': + description: Authentication required content: application/json: schema: $ref: '#/components/schemas/Error' + '403': + $ref: '#/components/responses/FactoryAccessDenied' '404': - description: Agent not found + description: Scorer not found content: application/json: schema: @@ -1723,134 +2030,979 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' -components: - securitySchemes: - bearerAuth: - type: http - scheme: bearer - description: | - Authentication via a Warp API key. - schemas: - RunAgentRequest: - type: object - description: | - Request body for creating a new agent run. - Either prompt or skill (via skill field, config.skill_spec, or config.skills) is required, - except for handoff requests that set conversation_id. - properties: - prompt: - type: string - description: | - The prompt/instruction for the agent to execute. - Required unless a skill is specified via the skill field, config.skill_spec, or config.skills. - Handoff requests may omit prompt when conversation_id is set. - mode: - $ref: '#/components/schemas/AgentRunMode' - description: | - Optional query mode for the run. Defaults to `normal` when omitted. - The server does not infer mode from prompt prefixes such as `/plan`, - so callers should pass this field explicitly to request non-normal behavior. - skill: - type: string - description: | - Skill specification to use as the base prompt for the agent. - Supported formats: - - "repo:skill_name" - Simple name in specific repo - - "repo:skill_path" - Full path in specific repo - - "org/repo:skill_name" - Simple name with org and repo - - "org/repo:skill_path" - Full path with org and repo - When provided, this takes precedence over config.skill_spec. - 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. - Defaults to true for users on a single team. - agent_identity_uid: - type: string - description: | - Optional agent identity UID to use as the execution principal for the run. - This is only valid for runs that are team owned. - on_behalf_of: - type: string - description: | - Optional email address or user ID of a Warp user to attribute the run to. - When set, the resolved user becomes the run's creator instead of the caller. - Only agent API keys may use this field, and the calling agent must have - on_behalf_of enabled in its configuration (`on_behalf_of_enabled`), which a - team admin must intentionally turn on per agent. The target user must be an - active member of the run's owner team. Only valid for team-owned runs. - conversation_id: - type: string - description: | - Optional conversation ID to continue an existing conversation. - If provided, the agent will continue from where the previous run left off. - attachments: - type: array - items: - $ref: '#/components/schemas/AttachmentInput' - description: | - Optional file attachments to include with the prompt (max 5). - Attachments are uploaded to cloud storage and made available to the agent. - parent_run_id: - type: string - description: | - Optional run ID of the parent that spawned this run. - Used for orchestration hierarchies. - The parent run must exist and be visible to the caller; otherwise the - request is rejected with a 400. Child runs are also subject to the - server's maximum orchestration depth, and requests that would exceed - it are rejected with a 400. - interactive: - type: boolean - description: | - Whether the run should be interactive. - If not set, defaults to false. - metadata: - $ref: '#/components/schemas/RunMetadata' - RunMetadata: - type: object - additionalProperties: - type: string + /factory/scorers/{scorer_id}/metrics/pass-rate: + get: + summary: Get a scorer's pass-rate metric over a date range description: | - Custom key/value metadata attached to a run at creation time and immutable afterward. - At most 20 keys. Keys are 1-64 bytes matching [a-zA-Z0-9._-]+ (case-sensitive); - values are 0-256 bytes of UTF-8 and cannot contain NUL characters. - Requests with invalid metadata are rejected. - A run's effective metadata is merged per key at creation: explicit request keys - override keys inherited from the parent run, which override automatic keys - (ticket_id and ticket_source on Linear- and Jira-triggered runs). - RunAgentResponse: - type: object - required: - - run_id - - task_id - - state - properties: - run_id: + Returns a period-aligned pass-rate series plus a full-range aggregate + for the scorer's dashboard chart, computed directly from every live + score in [start_date, end_date) rather than the capped, + unfiltered recent-attempts list /results returns. The headline + pass_rate and the series describe the same window and denominator, so + they cannot disagree. Binning follows the same day/week/month rules + and 365-period cap as GET /factory/{uid}/metrics. + operationId: getScorerPassRateSeries + tags: + - factory + security: + - bearerAuth: [] + parameters: + - name: scorer_id + in: path + description: The scorer identifier + required: true + schema: + type: integer + - name: start_date + in: query + description: RFC3339 UTC range start, inclusive. Defaults to 30 days before end_date. + required: false + schema: type: string - description: Unique identifier for the created run - task_id: + format: date-time + - name: end_date + in: query + description: RFC3339 UTC range end, exclusive. Defaults to now. + required: false + schema: 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 + format: date-time + - name: group_by_period + in: query + description: Binning granularity for the series. Defaults to day. + required: false + schema: + $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' + responses: + '200': + description: The scorer's pass-rate series and range aggregate + content: + application/json: + schema: + $ref: '#/components/schemas/ScorerPassRateSeriesResponse' + '400': + description: Invalid scorer ID, date range, or group_by_period + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '401': + description: Authentication required + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: Scorer not found + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '500': + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /factory/scorers/{scorer_id}/self-improvement-config: + get: + summary: Get a scorer's self-improvement config description: | - Query mode for an agent run. - - normal: Standard user query (default). - - plan: Planning Mode. The agent researches and creates a plan, then waits for approval before execution. - - orchestrate: Orchestration Mode. The agent proposes an orchestration plan and must not start child agents until approved. - enum: + Retrieve the self-improvement configuration for a scorer: whether self-improvement is + enabled for it. + operationId: getScorerSelfImprovementConfig + tags: + - factory + security: + - bearerAuth: [] + parameters: + - name: scorer_id + in: path + description: The scorer identifier + required: true + schema: + type: integer + responses: + '200': + description: The scorer's self-improvement config + content: + application/json: + schema: + $ref: '#/components/schemas/SelfImprovementConfigResponse' + '401': + description: Authentication required + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '403': + $ref: '#/components/responses/FactoryAccessDenied' + '404': + description: Scorer not found or self-improvement not configured + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '500': + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + put: + summary: Enable self-improvement for a scorer + description: | + Turn self-improvement on for a scorer, marking its config active. Self-improvement acts + on runs the scorer itself already scores as failing (scored label's + score below the scorer's threshold); this endpoint carries no + classification data of its own. + operationId: updateScorerSelfImprovementConfig + tags: + - factory + security: + - bearerAuth: [] + parameters: + - name: scorer_id + in: path + description: The scorer identifier + required: true + schema: + type: integer + responses: + '200': + description: The updated self-improvement config + content: + application/json: + schema: + $ref: '#/components/schemas/SelfImprovementConfigResponse' + '401': + description: Authentication required + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '403': + $ref: '#/components/responses/FactoryAccessDenied' + '404': + description: Scorer not found + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '500': + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + delete: + summary: Disable self-improvement for a scorer + description: Turn self-improvement off for a scorer by removing its config. + operationId: deleteScorerSelfImprovementConfig + tags: + - factory + security: + - bearerAuth: [] + parameters: + - name: scorer_id + in: path + description: The scorer identifier + required: true + schema: + type: integer + responses: + '204': + description: Self-improvement config deleted + '401': + description: Authentication required + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '403': + $ref: '#/components/responses/FactoryAccessDenied' + '404': + description: Scorer not found + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '500': + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /factory/run-scoring/dispatches: + post: + summary: Manually dispatch scoring for one or more runs + description: | + Immediately dispatch judge runs for the named (run, scorer) pairs, + bypassing the two-hour idle cool-down, automatic sampling, and the + scorer-created-after-run gate, since the caller selected the exact + run — even a 0% sampling rate still accepts a manual dispatch. The + full target set is validated before dispatch begins, and each pair's + outcome (dispatched, already in flight, or failed) is reported + independently. + operationId: dispatchManualScoring + tags: + - factory + security: + - bearerAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ManualScoringDispatchRequest' + responses: + '202': + description: | + The request was validated; judge evaluation continues + asynchronously. Individual pairs may still report a + failed_to_dispatch outcome. + content: + application/json: + schema: + $ref: '#/components/schemas/ManualScoringDispatchResponse' + '400': + description: | + Malformed request, non-named-agent run, judge + run, wrong factory, wrong agent scope, or more than 100 pairs + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '401': + description: Authentication required + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '403': + $ref: '#/components/responses/FactoryAccessDenied' + '404': + description: A named run or scorer does not exist, or the caller lacks access + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '500': + description: Internal server error; no judge run was created + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /factory/runs/{run_id}/scores: + get: + summary: Read a run's current scores + description: | + List the current live attempt for each evaluation that has attempted + the given run, most recent attempt first. Excludes a deleted + evaluation's data. Requires + only view access to the run, since reading scores is part of viewing + the run. + operationId: listRunScores + tags: + - factory + security: + - bearerAuth: [] + parameters: + - name: run_id + in: path + description: The run identifier + required: true + schema: + type: string + responses: + '200': + description: The run's current scores + content: + application/json: + schema: + $ref: '#/components/schemas/GetRunScoresResponse' + '401': + description: Authentication required + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '403': + $ref: '#/components/responses/FactoryAccessDenied' + '404': + description: Run not found, or the caller cannot view it + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '500': + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /agent/runs/{runId}/scores: + post: + summary: Report evaluation scores for a run + description: | + Report one or more evaluation verdicts for a run, called by the judge + run dispatched to score it and authenticated with that judge run's + API key. Each verdict is processed independently — the response + reports per-verdict acceptance, and a rejected verdict does not block + the others — so reporting a subset of the run's evaluations is valid. + operationId: reportRunScores + tags: + - agent + security: + - bearerAuth: [] + parameters: + - name: runId + in: path + description: The run being scored + required: true + schema: + type: string + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ReportRunScoresRequest' + responses: + '200': + description: Every reported verdict was accepted + content: + application/json: + schema: + $ref: '#/components/schemas/ReportRunScoresResponse' + '206': + description: The request was well-formed but at least one verdict was rejected; inspect each result's status and error before deciding whether to resubmit + content: + application/json: + schema: + $ref: '#/components/schemas/ReportRunScoresResponse' + '400': + description: Malformed request body + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '401': + description: Authentication required + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '500': + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /agent/identities/{uid}: + get: + summary: Retrieve an agent + description: | + Retrieve a single agent by its unique identifier. + The response includes an `available` flag indicating whether the agent + is within the team's plan limit and may be used for runs. + 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. + 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 + agent are deleted atomically. + 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. + responses: + FactoryAccessDenied: + description: Factory access is not enabled for the authenticated principal + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Error' + schemas: + Factory: + type: object + description: Public representation of a factory. + required: + - uid + - team_uid + - name + - description + - alias + - avatar_url + - code_forge + - repositories + - default_environment + - default_model + - scoring + - credential_strategy + - integrations + - agent_defaults + - created_at + - updated_at + properties: + uid: + type: string + description: Public UID of the factory. + team_uid: + type: string + description: Public UID of the team that owns the factory. + name: + type: string + description: Display name of the factory. + description: + type: string + nullable: true + description: Optional description of the factory. + alias: + type: string + nullable: true + description: | + Optional display handle for the factory, unique across the team's + Warp workspace when set. + avatar_url: + type: string + nullable: true + description: | + Short-lived signed URL for displaying the factory's avatar. The URL + may change between reads. + code_forge: + $ref: '#/components/schemas/FactoryCodeForge' + repositories: + type: array + items: + $ref: '#/components/schemas/FactoryRepository' + description: Repositories scoped to the factory, independent of its default environment. + default_environment: + type: string + nullable: true + description: | + Public UID of the factory's default environment. File-managed + factories may omit this default. + default_model: + type: string + nullable: true + description: | + The default model ID for the factory's runs. File-managed factories + may omit this default. Live-managed create and PATCH requests still + capture a concrete validated model ID. + scoring: + $ref: '#/components/schemas/FactoryScoringConfig' + credential_strategy: + allOf: + - $ref: '#/components/schemas/FactoryCredentialStrategy' + description: | + Default credential strategy for runs executed by the factory's + named agents. Always a concrete value; factories default to + EXECUTOR unless explicitly set to CREATOR. + integrations: + type: array + items: + $ref: '#/components/schemas/FactoryIntegration' + nullable: true + description: | + Integration providers attached to the factory, independent of the + automation triggers configured for it. null means the factory has + not declared anything yet; an empty array means no providers are + attached. + agent_defaults: + $ref: '#/components/schemas/FactoryAgentDefaults' + creator: + allOf: + - $ref: '#/components/schemas/FactoryCreator' + description: | + The user who created the factory. Absent when there is no + resolvable creator: the factory predates creator tracking, it was + created by a service account, or the creating user's account no + longer exists. + created_at: + type: string + format: date-time + description: Time the factory was created. + updated_at: + type: string + format: date-time + description: Time the factory was last updated. + FactoryCreator: + type: object + description: The user who created a factory, when resolvable. + required: + - uid + properties: + uid: + type: string + description: Firebase UID of the user who created the factory. + email: + type: string + nullable: true + description: Creator's email, when available. + FactoryAgentDefaults: + type: object + description: | + Default execution settings inherited by the factory's named agents + when they declare no override of their own. + required: + - default_runner_uid + - secrets + - mcp_servers + - worker_host + properties: + harness: + allOf: + - $ref: '#/components/schemas/Harness' + description: | + Default harness for the factory's named agents. Absent when the + factory defaults to Warp's built-in harness. model_id and + reasoning_level carry the harness-scoped default model, which is + also reported in the factory's default_model. + harness_auth_secrets: + allOf: + - $ref: '#/components/schemas/HarnessAuthSecrets' + description: | + Per-harness authentication secrets inherited by the factory's + named agents. Only the secret for the default harness is ever + populated. A third-party default harness with no secret here + takes its credentials from the worker environment. + default_runner_uid: + type: string + description: | + Default runner UID for the factory's named agents. Empty when + unset, in which case the environment's default runner applies. + secrets: + type: array + items: + $ref: '#/components/schemas/SecretRef' + description: Secrets attached to the factory's named agents by default. + mcp_servers: + type: object + additionalProperties: + $ref: '#/components/schemas/MCPServerConfig' + description: | + MCP server configurations attached to the factory's named agents + by default. Only warp_id (managed MCP) entries are representable + for a Warp-managed factory. + worker_host: + type: string + description: | + Default worker host for the factory's named agents. Empty when + unset, in which case the workspace default applies. + FactoryScoringConfig: + type: object + required: + - default_model + properties: + default_model: + type: string + nullable: true + description: | + Optional factory override for the model used by managed scorers and + scorer-creation prefills. null or absent resolves to the platform + judge default. User-created scorers still require an explicit + model_id on create. + FactoryIntegration: + type: object + description: | + An integration provider attached to a factory. + required: + - type + properties: + type: + $ref: '#/components/schemas/FactoryIntegrationProvider' + FactoryIntegrationProvider: + type: string + description: | + Integration provider that can be attached to a factory. github is not + accepted here; repository access comes from the factory's code forge. + enum: + - jira + - linear + - slack + FactoryCodeForge: + type: string + description: | + Source-control provider hosting the factory's repositories. NONE + declares a repo-less factory with no native repositories; its + environment relies on setup_commands to clone from any host instead. + enum: + - GITHUB + - GITLAB + - NONE + FactoryCredentialStrategy: + type: string + description: | + Default credential strategy for runs executed by the factory's named + agents. + - EXECUTOR (default): runs authenticate with the named agent's own + credentials (e.g. a GitHub App installation token for the + factory's team). + - CREATOR: runs authenticate with the credentials of the principal + that created the run. + enum: + - CREATOR + - EXECUTOR + FactoryRepository: + type: object + description: A repository scoped to a factory. + required: + - owner + - repo + properties: + owner: + type: string + description: Repository owner (or full namespace for GitLab). + repo: + type: string + description: Repository name. + FactoryMetricsGroupByPeriod: + type: string + description: | + Binning granularity for factory metrics series. Weeks start on + Sunday (UTC), consistent with existing Warp analytics. + enum: + - day + - week + - month + ListFactoriesResponse: + type: object + description: Response body for listing factories. + required: + - factories + - page_info + properties: + factories: + type: array + items: + $ref: '#/components/schemas/Factory' + page_info: + $ref: '#/components/schemas/PageInfo' + FactoryRunRequest: + type: object + description: Request body for dispatching a run to a factory. + required: + - prompt + properties: + prompt: + type: string + description: | + The prompt sent to the factory's foreman, not wrapped in any + factory intake envelope. Required and non-empty. + title: + type: string + description: | + Human-readable title for the dispatched run and its factory task. + Omit to derive one automatically from the prompt. + ticket_ref: + type: string + description: | + Originating ticket reference in : form (for + example, linear:REMOTE-123); omit to mint an adhoc reference. + Stamped onto the run as ticket_id/ticket_source metadata. + ticket_url: + type: string + description: | + Optional URL of the ticket named by ticket_ref. Stamped onto + the run as ticket_url metadata when given. + FactoryRunResponse: + type: object + description: Response body for a dispatched factory run. + required: + - run_id + - state + - factory_uid + - foreman_agent + - ticket_ref + properties: + run_id: + type: string + description: Unique identifier for the dispatched run. + run_url: + type: string + description: | + URL to view the dispatched run in the Factory app. Empty when + the Factory app origin is not configured. + state: + $ref: '#/components/schemas/RunState' + factory_uid: + type: string + description: Public UID of the factory the run was dispatched to. + foreman_agent: + type: string + description: Name of the factory's foreman agent that received the run. + ticket_ref: + type: string + description: | + The canonical : ticket reference the run was + stamped with, either the caller-supplied ticket_ref or a + minted adhoc reference. + RunAgentRequest: + type: object + description: | + Request body for creating a new agent run. + Either prompt or skill (via skill field, config.skill_spec, or config.skills) is required, + except for handoff requests that set conversation_id. + properties: + prompt: + type: string + description: | + The prompt/instruction for the agent to execute. + Required unless a skill is specified via the skill field, config.skill_spec, or config.skills. + Handoff requests may omit prompt when conversation_id is set. + mode: + $ref: '#/components/schemas/AgentRunMode' + description: | + Optional query mode for the run. Defaults to `normal` when omitted. + The server does not infer mode from prompt prefixes such as `/plan`, + so callers should pass this field explicitly to request non-normal behavior. + skill: + type: string + description: | + Skill specification to use as the base prompt for the agent. + Supported formats: + - "repo:skill_name" - Simple name in specific repo + - "repo:skill_path" - Full path in specific repo + - "org/repo:skill_name" - Simple name with org and repo + - "org/repo:skill_path" - Full path with org and repo + When provided, this takes precedence over config.skill_spec. + 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. + Defaults to true for users on a single team. + agent_identity_uid: + type: string + description: | + Optional agent identity UID to use as the execution principal for the run. + This is only valid for runs that are team owned. + on_behalf_of: + type: string + description: | + Optional email address or user ID of a Warp user to attribute + the run to; when set, the resolved user becomes the run's + creator instead of the caller. Only agent API keys may use this + field, only when the calling agent has on_behalf_of enabled in + its configuration (a team admin must turn this on per agent), + and only for team-owned runs. The target user must be an active + member of the run's owner team. + conversation_id: + type: string + description: | + Optional conversation ID to continue an existing conversation. + If provided, the agent will continue from where the previous run left off. + attachments: + type: array + items: + $ref: '#/components/schemas/AttachmentInput' + description: | + Optional file attachments to include with the prompt (max 5). + Attachments are uploaded to cloud storage and made available to the agent. + parent_run_id: + type: string + description: | + Optional run ID of the parent that spawned this run, used for + orchestration hierarchies; the parent run must exist and be + visible to the caller, or the request is rejected with a 400. + Child runs are also subject to the server's maximum + orchestration depth, and requests that would exceed it are + rejected with a 400. + interactive: + type: boolean + description: | + Whether the run should be interactive. + If not set, defaults to false. + metadata: + $ref: '#/components/schemas/RunMetadata' + RunMetadata: + type: object + additionalProperties: + type: string + description: | + Custom key/value metadata attached to a run at creation time and + immutable afterward; at most 20 keys, with keys 1-64 bytes matching + [a-zA-Z0-9._-]+ (case-sensitive) and values 0-256 bytes of UTF-8 with + no NUL characters. Requests with invalid metadata are rejected. A + run's effective metadata is merged per key at creation: explicit + request keys override keys inherited from the parent run, which + override automatic keys (ticket_id and ticket_source on Linear- and + Jira-triggered runs). + 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. + - normal: Standard user query (default). + - plan: Planning Mode. The agent researches and creates a plan, then waits for approval before execution. + - orchestrate: Orchestration Mode. The agent proposes an orchestration plan and must not start child agents until approved. + enum: - normal - plan - orchestrate @@ -1858,1633 +3010,2418 @@ components: ListRunsResponse: type: object required: - - runs - - page_info + - runs + - page_info + properties: + runs: + type: array + items: + $ref: '#/components/schemas/RunItem' + page_info: + $ref: '#/components/schemas/PageInfo' + RunItem: + type: object + required: + - run_id + - task_id + - title + - state + - prompt + - created_at + - updated_at + properties: + run_id: + type: string + description: Unique identifier for the run + task_id: + type: string + deprecated: true + description: Unique identifier for the task (typically matches run_id). Deprecated - use run_id instead. + title: + type: string + description: Human-readable title for the run + state: + $ref: '#/components/schemas/RunState' + execution_location: + $ref: '#/components/schemas/RunExecutionLocation' + prompt: + type: string + description: The prompt/instruction for the agent + created_at: + type: string + format: date-time + description: Timestamp when the run was created (RFC3339) + updated_at: + type: string + format: date-time + description: Timestamp when the run was last updated (RFC3339) + run_time: + type: string + format: duration + description: Total runtime as an ISO 8601 duration (e.g. "PT2M30S"), computed server-side from run executions. + started_at: + type: string + format: date-time + nullable: true + description: Timestamp when the agent started working on the run (RFC3339) + status_message: + $ref: '#/components/schemas/RunStatusMessage' + source: + $ref: '#/components/schemas/RunSourceType' + schedule: + $ref: '#/components/schemas/ScheduleInfo' + session_id: + type: string + description: UUID of the shared session (if available) + session_link: + type: string + format: uri + description: URL to view the agent session + trigger_url: + type: string + format: uri + description: URL to the run trigger (e.g. Slack thread, Linear issue, schedule) + creator: + $ref: '#/components/schemas/RunCreatorInfo' + executor: + $ref: '#/components/schemas/RunCreatorInfo' + request_usage: + $ref: '#/components/schemas/RequestUsage' + agent_config: + $ref: '#/components/schemas/AmbientAgentConfig' + conversation_id: + type: string + description: UUID of the conversation associated with the run + parent_run_id: + type: string + description: UUID of the parent run that spawned this run + metadata: + $ref: '#/components/schemas/RunMetadata' + is_sandbox_running: + type: boolean + description: Whether the sandbox environment is currently running + is_run_type_cancellable: + type: boolean + description: | + Whether the run's type is eligible for cancellation via the API. State-independent: + false for GitHub Action and local runs; true for all other run types (including + self-hosted). Clients should still gate the control on the run's current state. + artifacts: + type: array + items: + $ref: '#/components/schemas/ArtifactItem' + description: Artifacts created during the run (plans, pull requests, etc.) + agent_skill: + $ref: '#/components/schemas/AgentSkill' + scope: + $ref: '#/components/schemas/Scope' + GetRunTimelineResponse: + type: object + description: Response body for listing run timeline events. + required: + - events + properties: + events: + type: array + items: + $ref: '#/components/schemas/AIRunTimelineEvent' + AIRunTimelineEvent: + type: object + description: A setup or lifecycle event recorded for an agent run. + required: + - event_uuid + - run_id + - event_type + - occurred_at + properties: + event_uuid: + type: string + description: Unique client- or server-generated identifier for this event. + run_id: + type: string + description: Run that owns this event. + execution_id: + type: integer + format: int64 + description: Run execution associated with this event, when available. + event_type: + $ref: '#/components/schemas/AIRunTimelineEventType' + occurred_at: + type: string + format: date-time + description: Timestamp when the event occurred. + payload: + type: object + additionalProperties: true + description: Optional event-specific JSON payload. + AIRunTimelineEventType: + type: string + description: Type of timeline event recorded for a run. + enum: + - oz_run_created + - oz_run_claimed + - worker_container_ready + - shared_session_started + - agent_started + - oz_run_done + - oz_run_blocked + - oz_run_cancelled + - oz_run_failed + - oz_run_errored + - vm_shutdown + ConversationResponse: + type: object + required: + - conversation_id + - steps + properties: + conversation_id: + type: string + description: Unique identifier for the conversation + steps: + type: array + description: Root steps in the conversation + items: + $ref: '#/components/schemas/ConversationStep' + ConversationStep: + type: object + required: + - id + - messages + - steps + properties: + id: + type: string + description: Unique identifier for the step + description: + type: string + description: Original instruction or delegated work description for the step + summary: + type: string + description: Summary of the work completed for the step + started_at: + type: string + format: date-time + description: Earliest transcript message timestamp contained in this step or any nested step (RFC3339) + completed_at: + type: string + format: date-time + description: Latest transcript message timestamp contained in this step or any nested step (RFC3339) + messages: + type: array + description: Ordered normalized messages for this step + items: + $ref: '#/components/schemas/ConversationMessage' + steps: + type: array + description: Nested delegated work performed as part of this step + items: + $ref: '#/components/schemas/ConversationStep' + ConversationMessage: + type: object + required: + - role + - content + properties: + message_ids: + type: array + description: Underlying transcript message IDs grouped into this normalized message + items: + type: string + request_id: + type: string + description: Request identifier shared by transcript messages from the same request, when available + role: + $ref: '#/components/schemas/ConversationMessageRole' + timestamp: + type: string + format: date-time + description: Timestamp of the first transcript message included in this normalized message (RFC3339) + content: + type: array + items: + $ref: '#/components/schemas/ConversationContentBlock' + ConversationMessageRole: + type: string + description: Role of the normalized message + enum: + - user + - assistant + - tool + - system + ConversationContentBlock: + oneOf: + - $ref: '#/components/schemas/TextContentBlock' + - $ref: '#/components/schemas/ActionContentBlock' + - $ref: '#/components/schemas/ActionResultContentBlock' + - $ref: '#/components/schemas/EventContentBlock' + discriminator: + propertyName: type + mapping: + text: '#/components/schemas/TextContentBlock' + action: '#/components/schemas/ActionContentBlock' + action_result: '#/components/schemas/ActionResultContentBlock' + event: '#/components/schemas/EventContentBlock' + TextContentBlock: + type: object + required: + - type + - text + properties: + type: + type: string + enum: + - text + message_id: + type: string + description: Underlying transcript message ID that produced this content block, when available + text: + type: string + description: Plain text content + ActionCategory: + type: string + description: High-level category of an action performed during the conversation + enum: + - command + - files + - search + - integration + - documents + - computer + - review + - skill + ActionState: + type: string + description: State of an action result + enum: + - running + - completed + - failed + - denied + ActionContentBlock: + type: object + required: + - type + - id + - category + - name + - input + properties: + type: + type: string + enum: + - action + message_id: + type: string + description: Underlying transcript message ID that produced this content block, when available + id: + type: string + description: Unique identifier for the action + category: + $ref: '#/components/schemas/ActionCategory' + name: + type: string + description: Public action name, such as run_command or edit_files + input: + type: object + additionalProperties: true + description: Curated public input for this action. This object is owned by the API and is not a raw internal tool payload. + ActionResultContentBlock: + type: object + required: + - type + - action_id + - category + - name + - state + - output + properties: + type: + type: string + enum: + - action_result + message_id: + type: string + description: Underlying transcript message ID that produced this content block, when available + action_id: + type: string + description: Identifier of the corresponding action + category: + $ref: '#/components/schemas/ActionCategory' + name: + type: string + description: Public action name matching the corresponding action block + state: + $ref: '#/components/schemas/ActionState' + output: + type: object + additionalProperties: true + description: Curated public result for this action. Large or binary internal payloads should be summarized rather than passed through raw. + EventContentBlock: + type: object + required: + - type + - name + - data + properties: + type: + type: string + enum: + - event + message_id: + type: string + description: Underlying transcript message ID that produced this content block, when available + name: + type: string + description: Event type for intentionally exposed non-core transcript events + data: + type: object + additionalProperties: true + description: Minimal structured metadata for the event + ArtifactItem: + oneOf: + - $ref: '#/components/schemas/PlanArtifact' + - $ref: '#/components/schemas/PullRequestArtifact' + - $ref: '#/components/schemas/ScreenshotArtifact' + - $ref: '#/components/schemas/FileArtifact' + - $ref: '#/components/schemas/ExternalReferenceArtifact' + discriminator: + propertyName: artifact_type + mapping: + PLAN: '#/components/schemas/PlanArtifact' + PULL_REQUEST: '#/components/schemas/PullRequestArtifact' + SCREENSHOT: '#/components/schemas/ScreenshotArtifact' + FILE: '#/components/schemas/FileArtifact' + EXTERNAL_REFERENCE: '#/components/schemas/ExternalReferenceArtifact' + ExternalReferenceArtifact: + type: object + required: + - artifact_type + - created_at + - data + properties: + artifact_type: + type: string + enum: + - EXTERNAL_REFERENCE + description: Type of the artifact + created_at: + type: string + format: date-time + description: Timestamp when the artifact was created (RFC3339) + data: + $ref: '#/components/schemas/ExternalReferenceArtifactData' + PlanArtifact: + type: object + required: + - artifact_type + - created_at + - data + properties: + artifact_type: + type: string + enum: + - PLAN + description: Type of the artifact + created_at: + type: string + format: date-time + description: Timestamp when the artifact was created (RFC3339) + data: + $ref: '#/components/schemas/PlanArtifactData' + PullRequestArtifact: + type: object + required: + - artifact_type + - created_at + - data + properties: + artifact_type: + type: string + enum: + - PULL_REQUEST + description: Type of the artifact + created_at: + type: string + format: date-time + description: Timestamp when the artifact was created (RFC3339) + data: + $ref: '#/components/schemas/PullRequestArtifactData' + ScreenshotArtifact: + type: object + required: + - artifact_type + - created_at + - data + properties: + artifact_type: + type: string + enum: + - SCREENSHOT + description: Type of the artifact + created_at: + type: string + format: date-time + description: Timestamp when the artifact was created (RFC3339) + data: + $ref: '#/components/schemas/ScreenshotArtifactData' + FileArtifact: + type: object + required: + - artifact_type + - created_at + - data properties: - runs: - type: array - items: - $ref: '#/components/schemas/RunItem' - page_info: - $ref: '#/components/schemas/PageInfo' - RunItem: + 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: - - run_id - - task_id - - title - - state - - prompt - - created_at - - updated_at + - document_uid properties: - run_id: + artifact_uid: type: string - description: Unique identifier for the run - task_id: + description: Unique identifier for the plan artifact, usable with the artifact retrieval endpoint + document_uid: type: string - deprecated: true - description: Unique identifier for the task (typically matches run_id). Deprecated - use run_id instead. - title: + description: Unique identifier for the plan document + notebook_uid: type: string - description: Human-readable title for the run - state: - $ref: '#/components/schemas/RunState' - execution_location: - $ref: '#/components/schemas/RunExecutionLocation' - prompt: + description: Unique identifier for the associated notebook + url: type: string - description: The prompt/instruction for the agent - created_at: + format: uri + description: URL to open the plan in Warp Drive + title: type: string - format: date-time - description: Timestamp when the run was created (RFC3339) - updated_at: + description: Title of the plan + PullRequestArtifactData: + type: object + required: + - url + - branch + properties: + url: type: string - format: date-time - description: Timestamp when the run was last updated (RFC3339) - run_time: + format: uri + description: URL of the pull request + branch: type: string - format: duration - description: Total runtime as an ISO 8601 duration (e.g. "PT2M30S"), computed server-side from run executions. - started_at: + description: Branch name for the pull request + ScreenshotArtifactData: + type: object + required: + - artifact_uid + - mime_type + properties: + artifact_uid: 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: + description: Unique identifier for the screenshot artifact + mime_type: type: string - description: UUID of the shared session (if available) - session_link: + description: MIME type of the screenshot image + description: type: string - format: uri - description: URL to view the agent session - trigger_url: + description: Optional description of the screenshot + FileArtifactData: + type: object + required: + - artifact_uid + - filepath + - filename + - mime_type + properties: + artifact_uid: 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: + description: Unique identifier for the file artifact + filepath: type: string - description: UUID of the conversation associated with the run - parent_run_id: + description: | + Conversation-relative filepath for the uploaded file. Omitted on + an anonymous read of a public file artifact. + filename: + type: string + description: Last path component of filepath + title: type: string - description: UUID of the parent run that spawned this run - metadata: - $ref: '#/components/schemas/RunMetadata' - is_sandbox_running: - type: boolean - description: Whether the sandbox environment is currently running - is_run_type_cancellable: - type: boolean description: | - Whether the run's type is eligible for cancellation via the API. State-independent: - false for GitHub Action and local runs; true for all other run types (including - self-hosted). Clients should still gate the control on the run's current state. - 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: + Short, badge-visible label for the artifact. For recording artifacts, + this is the agent-authored title shown in Warp web and blocklist badges. + Distinct from description, which is longer and shown in detail views. + 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: Response body for listing run timeline events. + description: Information about the schedule that triggered this run (only present for scheduled runs) required: - - events + - schedule_id + - schedule_name + - cron_schedule properties: - events: - type: array - items: - $ref: '#/components/schemas/AIRunTimelineEvent' - AIRunTimelineEvent: + 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 - description: A setup or lifecycle event recorded for an agent run. required: - - event_uuid - - run_id - - event_type - - occurred_at + - has_next_page properties: - event_uuid: + has_next_page: + type: boolean + description: Whether there are more results available + next_cursor: type: string - description: Unique client- or server-generated identifier for this event. - run_id: + description: Opaque cursor for fetching the next page + RunStatusMessage: + type: object + description: | + Status message for a run. For terminal error states, includes structured + error code and retryability info from the platform error catalog. + required: + - message + properties: + message: type: string - description: Run that owns this event. - execution_id: + 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 + a new run. Only present on terminal error states. When false, retrying + without addressing the underlying cause will not succeed. + session_debug_until: + type: string + format: date-time + description: | + When a failed run's shared session stops being held open for + debugging; only present while that window is open. The window + is an idle window owned by the agent process: activity in the + session pushes this deadline out. The agent republishes it + periodically rather than on every keystroke, so the value can + lag the true deadline by up to a throttle interval, always in + the conservative direction. + RequestUsage: + type: object + description: Resource usage information for the run + properties: + inference_cost: + type: number + format: double + description: Credits consumed by LLM inference for the run + compute_cost: + type: number + format: double + description: Credits consumed by compute resources for the run + platform_cost: + type: number + format: double + description: Credits consumed by platform usage for the run + inference_cost_usd: + type: number + format: double + description: | + inference_cost in US dollars, converted at the owning team's + current credit price. An approximate cost, not a billed amount. + compute_cost_usd: + type: number + format: double + description: | + compute_cost in US dollars, converted at the owning team's + current credit price. An approximate cost, not a billed amount. + platform_cost_usd: + type: number + format: double + description: | + platform_cost in US dollars, converted at the owning team's + current credit price. An approximate cost, not a billed amount. + total_tokens: 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: + description: | + Total LLM token count (summed across every usage category and model) for the run's + conversation. Omitted when the data is not available. + inference_cost_breakdown_usd: + $ref: '#/components/schemas/InferenceCostBreakdownUsd' + usage_by_category: type: object - additionalProperties: true - description: Optional event-specific JSON payload. - AIRunTimelineEventType: - type: string - description: Type of timeline event recorded for a run. - enum: - - oz_run_created - - oz_run_claimed - - worker_container_ready - - shared_session_started - - agent_started - - oz_run_done - - oz_run_blocked - - oz_run_cancelled - - oz_run_failed - - oz_run_errored - - vm_shutdown - ConversationResponse: + additionalProperties: + $ref: '#/components/schemas/ChargedUsageDetail' + description: | + Full-granularity token and dollar-cost breakdown for the run's + conversation, keyed by usage category (for example, + primary_agent or conversation_compaction) and model id; differs + from total_tokens/inference_cost_breakdown_usd, which combine + usage across all categories and models. Omitted when the data + is not available. + InferenceCostBreakdownUsd: type: object + description: | + Charged dollar cost of LLM inference, split by token type. + Omitted when the data is not available. required: - - conversation_id - - steps + - input_cost_usd + - input_cache_read_cost_usd + - input_cache_write_cost_usd + - output_cost_usd 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: + input_cost_usd: + type: number + format: double + description: Cost of non-cached input tokens, in US dollars. + input_cache_read_cost_usd: + type: number + format: double + description: Cost of cache-read input tokens, in US dollars. + input_cache_write_cost_usd: + type: number + format: double + description: Cost of cache-write input tokens, in US dollars. + output_cost_usd: + type: number + format: double + description: Cost of output tokens, in US dollars. + TokenCountBreakdown: type: object + description: A per-token-type token count. required: - - id - - messages - - steps + - input + - output + - input_cache_read + - input_cache_write 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: + input: + type: integer + format: int64 + description: Count of non-cached input tokens. + output: + type: integer + format: int64 + description: Count of output tokens. + input_cache_read: + type: integer + format: int64 + description: Count of cache-read input tokens. + input_cache_write: + type: integer + format: int64 + description: Count of cache-write input tokens. + InferenceUsageDetail: type: object + description: | + Full token count and dollar-cost detail inference usage. + The counts and cost describe the same usage (e.g. token_count.input + tokens cost cost_usd.input_cost_usd in total). required: - - role - - content + - token_count + - cost_usd + - web_search_count + - web_search_cost_usd 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: + token_count: + $ref: '#/components/schemas/TokenCountBreakdown' + cost_usd: + $ref: '#/components/schemas/InferenceCostBreakdownUsd' + web_search_count: + type: integer + format: int64 + description: Number of web searches performed by this model. + web_search_cost_usd: + type: number + format: double + description: Total cost of those web searches, in US dollars. + ChargedUsageDetail: type: object + description: | + Usage charged for a single usage category, broken down by usage type + (direct API/BYOK/custom endpoint) and, within each, by model ID. required: - - type - - text + - platform_usage_usd + properties: + direct_api_inference_usage: + type: object + additionalProperties: + $ref: '#/components/schemas/InferenceUsageDetail' + description: Inference usage incurred through Warp-provided model access, keyed by model ID. + byok_inference_usage: + type: object + additionalProperties: + $ref: '#/components/schemas/InferenceUsageDetail' + description: Inference usage charged using a user's own API key, keyed by model ID. + custom_endpoint_inference_usage: + type: object + additionalProperties: + $ref: '#/components/schemas/InferenceUsageDetail' + description: | + Inference usage charged using a custom endpoint, keyed by the + custom model's config key. + platform_usage_usd: + type: number + format: double + description: Platform usage charged for this category, in US dollars. + RunCreatorInfo: + type: object properties: type: type: string enum: - - text - message_id: + - user + - service_account + description: Type of the creator principal + uid: type: string - description: Underlying transcript message ID that produced this content block, when available - text: + description: Unique identifier of the creator + display_name: type: string - description: Plain text content - ActionCategory: + 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 - description: High-level category of an action performed during the conversation enum: - - command - - files - - search - - integration - - documents - - computer - - review - - skill - ActionState: + - QUEUED + - PENDING + - CLAIMED + - INPROGRESS + - SUCCEEDED + - FAILED + - BLOCKED + - ERROR + - CANCELLED + description: | + Current state of the run: + - QUEUED: Run is waiting to be picked up + - PENDING: Run is being prepared + - CLAIMED: Run has been claimed by a worker + - INPROGRESS: Run is actively being executed + - SUCCEEDED: Run completed successfully + - FAILED: Run failed + - BLOCKED: Run is blocked (e.g., awaiting user input or approval) + - ERROR: Run encountered an error + - CANCELLED: Run was cancelled by user + RunSourceType: type: string - description: State of an action result enum: - - running - - completed - - failed - - denied - ActionContentBlock: + - LINEAR + - API + - SLACK + - LOCAL + - SCHEDULED_AGENT + - WEB_APP + - GITHUB_ACTION + - CLOUD_MODE + - CLI + - JIRA + - SELF_IMPROVEMENT + - GITHUB_WEBHOOK + - GITLAB_WEBHOOK + - AUTOFIX + - RUN_SCORER + - ORCHESTRATION + description: | + Source that created the run: + - LINEAR: Created from Linear integration + - API: Created via the Warp API + - SLACK: Created from Slack integration + - LOCAL: Created from local CLI/app + - SCHEDULED_AGENT: Created by a scheduled agent + - WEB_APP: Created from the Warp web app + - GITHUB_ACTION: Created from a GitHub action + - CLOUD_MODE: Created from a Cloud Mode + - CLI: Created from the CLI + - JIRA: Created from Jira integration + - SELF_IMPROVEMENT: Created by Warp's self-improvement pipeline + - GITHUB_WEBHOOK: Created from a GitHub webhook event + - GITLAB_WEBHOOK: Created from a GitLab webhook event + - AUTOFIX: Created by Warp's autofix pipeline + - RUN_SCORER: Created by Warp's run-scoring judge + - ORCHESTRATION: Created as a child run by the orchestration layer (parent_run_id set) + RunExecutionLocation: + type: string + enum: + - LOCAL + - REMOTE + description: | + Where the run executed: + - LOCAL: Executed in the user's local Warp environment + - REMOTE: Executed by a remote/cloud worker + AmbientAgentConfig: type: object - required: - - type - - id - - category - - name - - input + description: Configuration for a cloud agent run 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: + description: | + Human-readable label for grouping, filtering, and traceability. + Automatically set to the skill name when running a skill-based agent. + Set this explicitly to categorize runs by intent (e.g., "nightly-dependency-check") + so you can filter and track them via the name query parameter on GET /agent/runs. + model_id: type: string - description: Identifier of the corresponding action - category: - $ref: '#/components/schemas/ActionCategory' - name: + description: LLM model to use (uses team default if not specified) + base_prompt: 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: + description: Custom base prompt for the agent + environment_id: type: string - enum: - - event - message_id: + description: UID of the environment to run the agent in + runner_id: type: string - description: Underlying transcript message ID that produced this content block, when available - name: + description: | + UID of the runner providing the run's compute (platform, instance + shape, and setup commands). When omitted on a request, the runner is + resolved at run creation from the agent's default runner, then the + environment's default runner, and the resolved UID is recorded on + the run. + skill_spec: type: string - description: Event type for intentionally exposed non-core transcript events - data: + description: | + Skill specification identifying the primary agent skill to use, + in `{owner}/{repo}:{skill_path}` format (e.g. + `warpdotdev/warp-server:.claude/skills/deploy/SKILL.md`); + mutually exclusive with `skills` in create/update requests. + Responses include the first `skills` entry here for backward + compatibility; use the list agents endpoint to discover + available skills. + skills: + type: array + items: + type: string + description: | + Ordered skill specifications to attach to the run. + Format: "{owner}/{repo}:{skill_path}" + Example: "warpdotdev/warp-server:.claude/skills/deploy/SKILL.md" + Mutually exclusive with skill_spec in create/update requests. + mcp_servers: type: object - additionalProperties: true - description: Minimal structured metadata for the event - ArtifactItem: - oneOf: - - $ref: '#/components/schemas/PlanArtifact' - - $ref: '#/components/schemas/PullRequestArtifact' - - $ref: '#/components/schemas/ScreenshotArtifact' - - $ref: '#/components/schemas/FileArtifact' - - $ref: '#/components/schemas/ExternalReferenceArtifact' - discriminator: - propertyName: artifact_type - mapping: - PLAN: '#/components/schemas/PlanArtifact' - PULL_REQUEST: '#/components/schemas/PullRequestArtifact' - SCREENSHOT: '#/components/schemas/ScreenshotArtifact' - FILE: '#/components/schemas/FileArtifact' - EXTERNAL_REFERENCE: '#/components/schemas/ExternalReferenceArtifact' - ExternalReferenceArtifact: - type: object - required: - - artifact_type - - created_at - - data - properties: - artifact_type: - type: string - enum: - - EXTERNAL_REFERENCE - description: Type of the artifact - created_at: - type: string - format: date-time - description: Timestamp when the artifact was created (RFC3339) - data: - $ref: '#/components/schemas/ExternalReferenceArtifactData' - PlanArtifact: - type: object - required: - - artifact_type - - created_at - - data - properties: - artifact_type: - type: string - enum: - - PLAN - description: Type of the artifact - created_at: - type: string - format: date-time - description: Timestamp when the artifact was created (RFC3339) - data: - $ref: '#/components/schemas/PlanArtifactData' - PullRequestArtifact: - type: object - required: - - artifact_type - - created_at - - data - properties: - artifact_type: + 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. + If not set, defaults to true. + computer_use_model_id: type: string - enum: - - PULL_REQUEST - description: Type of the artifact - created_at: + description: | + Model the computer use subagent runs on; if omitted, the subagent + picks its own model automatically. Only applies to the built-in + Warp harness — the value is accepted but has no effect under a + third-party harness or when computer use is disabled. Requires an + agent CLI version that supports the --computer-use-model flag. + idle_timeout_minutes: + type: integer + format: int32 + minimum: 1 + maximum: 60 + description: | + Number of minutes to keep the agent environment alive after task completion. + If not set, defaults to 10 minutes. + Maximum allowed value is min(60, floor(max_instance_runtime_seconds / 60) for your billing tier). + worker_host: 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: + description: | + Self-hosted worker ID that should execute this task. + If not specified or set to "warp", the task runs on Warp-hosted workers. + 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 + config takes precedence over the agent's stored config and + the workspace's admin-configured defaults. + credential_strategy: type: string + nullable: true 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: + - CREATOR + - EXECUTOR + description: | + Controls which principal's credentials are used when the + platform mints tokens (e.g. GitHub or GitLab OAuth tokens) on + behalf of this run. + - EXECUTOR (default when unset): credentials are sourced from + the run's execution principal — a GitHub App installation + token for agent principals, a personal OAuth token for user + principals. + - CREATOR: credentials are always sourced from the run creator + regardless of the execution principal, useful when a service + account executes the run but Git operations should + authenticate as the triggering human. + SessionSharingConfig: type: object - required: - - artifact_type - - created_at - - data + description: | + Configures sharing behavior for the run's shared session; when set, + the worker emits `--share public:` and the bundled Warp + client applies an anyone-with-link ACL to the shared session once it + has bootstrapped. The same ACL is mirrored onto the backing + conversation so link viewers can read it without being on the run's + team, subject to the workspace-level anyone-with-link sharing + setting. properties: - artifact_type: + public_access: 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: + - VIEWER + - EDITOR + description: | + Grants anyone-with-link access at the specified level to the + run's shared session and backing conversation; link viewers + must still be authenticated Warp users (anonymous reads are not + supported in this release). + - VIEWER: link viewers can read the session and conversation. + - EDITOR: link viewers can also interact with the session. + Harness: type: object - required: - - document_uid + description: | + Specifies which execution harness to use for the agent run. + Default (nil/empty) uses Warp's built-in harness. + When stored as a named agent's default (create/update agent identity), + this field replaces the deprecated base_harness/base_model pair: a + harness other than `oz` here requires the agent's base_model to be + empty, since the two describe mutually exclusive default models. 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: type: string - description: Unique identifier for the associated notebook - url: + enum: + - oz + - claude + - gemini + - codex + description: | + The harness type identifier. + - oz: Warp's built-in harness (default) + - claude: Claude Code harness + - gemini: Gemini CLI harness + - codex: Codex CLI harness + model_id: type: string - format: uri - description: URL to open the plan in Warp Drive - title: + description: | + Model to use with a third-party harness (e.g. "claude-haiku-4-5"). + Only applies when type is a harness other than `oz`; the + top-level config model_id targets the built-in Warp harness + instead. When omitted or empty, the harness uses its own default + model. + reasoning_level: type: string - description: Title of the plan - PullRequestArtifactData: + description: | + Reasoning effort for harnesses that support it (e.g. Codex). + Only applies when type is a harness other than `oz`. Ignored by + harnesses that do not support reasoning levels. + HarnessAuthSecrets: type: object - required: - - url - - branch + description: | + Authentication secrets for third-party harnesses. + Only the secret for the harness specified gets injected into the environment. properties: - url: + claude_auth_secret_name: type: string - format: uri - description: URL of the pull request - branch: + description: | + Name of a managed secret for Claude Code harness authentication. + The secret must exist within the caller's personal or team scope. + Only applicable when harness type is "claude". + codex_auth_secret_name: type: string - description: Branch name for the pull request - ScreenshotArtifactData: + description: | + Name of a managed secret for Codex harness authentication. + The secret must exist within the caller's personal or team scope. + Only applicable when harness type is "codex". + MCPServerConfig: type: object - required: - - artifact_uid - - mime_type + description: | + Configuration for an MCP server. Must have exactly one of: warp_id, command, or url. properties: - artifact_uid: + warp_id: type: string - description: Unique identifier for the screenshot artifact - mime_type: + description: | + Reference to a Warp shared MCP server by UUID, or a well-known + integration MCP id (e.g. "linear") backed by the team's integration + connection. + command: type: string - description: MIME type of the screenshot image - description: + description: Stdio transport - command to run + args: + type: array + items: + type: string + description: Stdio transport - command arguments + url: type: string - description: Optional description of the screenshot - FileArtifactData: + 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), + using the `application/problem+json` content type. Includes + backward-compatible extension members; additional ones (e.g., + `auth_url`, `provider`) may be present depending on the error code. required: - - artifact_uid - - filepath - - filename - - mime_type + - type + - title + - status + - error 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 - title: + type: type: string + format: uri description: | - Short, badge-visible label for the artifact. For recording artifacts, - this is the agent-authored title shown in Oz web and blocklist badges. - Distinct from description, which is longer and shown in detail views. - description: - type: string - description: Optional description of the file - mime_type: + A URI reference that identifies the problem type (RFC 7807). + Format: `https://docs.warp.dev/reference/api-and-sdk/troubleshooting/errors/{error_code}` + See PlatformErrorCode for the list of possible error codes. + title: type: string - description: MIME type of the uploaded file - size_bytes: + description: A short, human-readable summary of the problem type (RFC 7807) + status: 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: + description: The HTTP status code for this occurrence of the problem (RFC 7807) + detail: type: string - description: Unique identifier for the schedule - schedule_name: + description: A human-readable explanation specific to this occurrence of the problem (RFC 7807) + instance: type: string - description: Name of the schedule at the time the run was created - cron_schedule: + description: The request path that generated this error (RFC 7807) + error: type: string - description: Cron expression at the time the run was created - PageInfo: - type: object - required: - - has_next_page - properties: - has_next_page: + description: | + Human-readable error message combining title and detail. + Backward-compatible extension member for older clients. + retryable: type: boolean - description: Whether there are more results available - next_cursor: + description: | + Whether the request can be retried. When true, the error is transient + and the request may be retried. When false, retrying without addressing + the underlying cause will not succeed. + trace_id: type: string - description: Opaque cursor for fetching the next page - RunStatusMessage: + description: OpenTelemetry trace ID for debugging and support requests + provider: + type: string + description: External provider that requires authorization, such as `linear`. + auth_url: + type: string + format: uri + description: URL where the caller can reconnect the external provider. + ArtifactResponse: + oneOf: + - $ref: '#/components/schemas/PlanArtifactResponse' + - $ref: '#/components/schemas/ScreenshotArtifactResponse' + - $ref: '#/components/schemas/FileArtifactResponse' + discriminator: + propertyName: artifact_type + mapping: + PLAN: '#/components/schemas/PlanArtifactResponse' + SCREENSHOT: '#/components/schemas/ScreenshotArtifactResponse' + FILE: '#/components/schemas/FileArtifactResponse' + PlanArtifactResponse: type: object - description: | - Status message for a run. For terminal error states, includes structured - error code and retryability info from the platform error catalog. + description: Response for retrieving a plan artifact. required: - - message + - artifact_uid + - artifact_type + - created_at + - data properties: - message: + artifact_uid: 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 - a new run. Only present on terminal error states. When false, retrying - without addressing the underlying cause will not succeed. - session_debug_until: + 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: | - When a failed run's shared session stops being held open for debugging. - Only present while that window is open. - - The window is an idle window owned by the agent process: activity in the - session pushes this deadline out. The agent republishes it periodically - rather than on every keystroke, so the value can lag the true deadline by - up to a throttle interval, and always in the conservative direction. - RequestUsage: + description: Timestamp when the artifact was created (RFC3339) + data: + $ref: '#/components/schemas/PlanArtifactResponseData' + PlanArtifactResponseData: type: object - description: Resource usage information for the run - properties: - inference_cost: - type: number - format: double - description: Credits consumed by LLM inference for the run - compute_cost: - type: number - format: double - description: Credits consumed by compute resources for the run - platform_cost: - type: number - format: double - description: Credits consumed by platform usage for the run - inference_cost_usd: - type: number - format: double - description: | - inference_cost in US dollars, converted at a fixed rate. An - approximate cost, not a billed amount. - compute_cost_usd: - type: number - format: double - description: | - compute_cost in US dollars, converted at a fixed rate. An - approximate cost, not a billed amount. - platform_cost_usd: - type: number - format: double - description: | - platform_cost in US dollars, converted at a fixed rate. An - approximate cost, not a billed amount. - RunCreatorInfo: + 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: - type: + artifact_uid: + type: string + description: Unique identifier (UUID) for the artifact + artifact_type: type: string enum: - - user - - service_account - description: Type of the creator principal - uid: + - SCREENSHOT + description: Type of the artifact + created_at: type: string - description: Unique identifier of the creator - display_name: + 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 - description: Display name of the creator - email: + format: uri + description: Time-limited signed URL to download the screenshot + expires_at: type: string - description: Email address of the creator - photo_url: + format: date-time + description: Timestamp when the download URL expires (RFC3339) + content_type: 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: - - QUEUED: Run is waiting to be picked up - - PENDING: Run is being prepared - - CLAIMED: Run has been claimed by a worker - - INPROGRESS: Run is actively being executed - - SUCCEEDED: Run completed successfully - - FAILED: Run failed - - BLOCKED: Run is blocked (e.g., awaiting user input or approval) - - ERROR: Run encountered an error - - CANCELLED: Run was cancelled by user - RunSourceType: - type: string - enum: - - LINEAR - - API - - SLACK - - LOCAL - - SCHEDULED_AGENT - - WEB_APP - - GITHUB_ACTION - - CLOUD_MODE - - CLI - - JIRA - - SELF_IMPROVEMENT - - GITHUB_WEBHOOK - - GITLAB_WEBHOOK - - AUTOFIX - - RUN_SCORER - - ORCHESTRATION - description: | - Source that created the run: - - LINEAR: Created from Linear integration - - API: Created via the Warp API - - SLACK: Created from Slack integration - - LOCAL: Created from local CLI/app - - SCHEDULED_AGENT: Created by a scheduled agent - - WEB_APP: Created from the Warp web app - - GITHUB_ACTION: Created from a GitHub action - - CLOUD_MODE: Created from a Cloud Mode - - CLI: Created from the CLI - - JIRA: Created from Jira integration - - SELF_IMPROVEMENT: Created by Warp's self-improvement pipeline - - GITHUB_WEBHOOK: Created from a GitHub webhook event - - GITLAB_WEBHOOK: Created from a GitLab webhook event - - AUTOFIX: Created by Warp's autofix pipeline - - RUN_SCORER: Created by Warp's run-scoring judge - - ORCHESTRATION: Created as a child run by the orchestration layer (parent_run_id set) - RunExecutionLocation: - type: string - enum: - - LOCAL - - REMOTE - description: | - Where the run executed: - - LOCAL: Executed in the user's local Oz environment - - REMOTE: Executed by a remote/cloud worker - AmbientAgentConfig: + description: MIME type of the screenshot (e.g., image/png) + description: + type: string + description: Optional description of the screenshot + FileArtifactResponse: type: object - description: Configuration for a cloud agent run + description: Response for retrieving a file artifact. + required: + - artifact_uid + - artifact_type + - created_at + - data properties: - name: + artifact_uid: type: string - description: | - Human-readable label for grouping, filtering, and traceability. - Automatically set to the skill name when running a skill-based agent. - Set this explicitly to categorize runs by intent (e.g., "nightly-dependency-check") - so you can filter and track them via the name query parameter on GET /agent/runs. - model_id: + description: Unique identifier (UUID) for the artifact + artifact_type: type: string - description: LLM model to use (uses team default if not specified) - base_prompt: + enum: + - FILE + description: Type of the artifact + created_at: type: string - description: Custom base prompt for the agent - environment_id: + format: date-time + description: Timestamp when the artifact was created (RFC3339) + data: + $ref: '#/components/schemas/FileArtifactResponseData' + FileArtifactResponseData: + type: object + description: Response data for a file artifact, including a signed download URL. + required: + - download_url + - expires_at + - content_type + - filename + properties: + download_url: type: string - description: UID of the environment to run the agent in - runner_id: + format: uri + description: Time-limited signed URL to download the file + expires_at: type: string - description: | - UID of the runner providing the run's compute (platform, instance - shape, and setup commands). When omitted on a request, the runner is - resolved at run creation from the agent's default runner, then the - environment's default runner, and the resolved UID is recorded on - the run. - skill_spec: + format: date-time + description: Timestamp when the download URL expires (RFC3339) + content_type: type: string - description: | - Skill specification identifying the primary agent skill to use. - Format: "{owner}/{repo}:{skill_path}" - Example: "warpdotdev/warp-server:.claude/skills/deploy/SKILL.md" - Mutually exclusive with skills in create/update requests. - Responses include the first skills entry here for backward compatibility. - Use the list agents endpoint to discover available skills. - skills: - type: array - items: - type: string - description: | - Ordered skill specifications to attach to the run. - Format: "{owner}/{repo}:{skill_path}" - Example: "warpdotdev/warp-server:.claude/skills/deploy/SKILL.md" - Mutually exclusive with skill_spec in create/update requests. - 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. - If not set, defaults to true. - idle_timeout_minutes: - type: integer - format: int32 - minimum: 1 - maximum: 60 - description: | - Number of minutes to keep the agent environment alive after task completion. - If not set, defaults to 10 minutes. - Maximum allowed value is min(60, floor(max_instance_runtime_seconds / 60) for your billing tier). - worker_host: + description: MIME type of the uploaded file + filepath: type: string description: | - Self-hosted worker ID that should execute this task. - If not specified or set to "warp", the task runs on Warp-hosted workers. - 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 - config takes precedence over the agent's stored config and - the workspace's admin-configured defaults. - credential_strategy: + Conversation-relative filepath for the uploaded file. Omitted for + anonymous reads of public artifacts. + filename: + type: string + description: Last path component of filepath + title: type: string - nullable: true - enum: - - CREATOR - - EXECUTOR description: | - Controls which principal's credentials are used when the platform mints - tokens (e.g. GitHub or GitLab OAuth tokens) on behalf of this run. - - EXECUTOR (default when unset): credentials are sourced from the run's - execution principal. For agent principals this produces a - GitHub App installation token; for user principals this produces their - personal OAuth token. - - CREATOR: credentials are always sourced from the run creator, - regardless of the execution principal. Useful when a service account - executes the run but Git operations should authenticate as the human - who triggered it. - When unset, behavior is identical to EXECUTOR and no additional - pre-flight validation is performed. - SessionSharingConfig: + Short, badge-visible label for the artifact. For recording artifacts, + this is the agent-authored title shown in Warp web and blocklist badges. + Distinct from description, which is longer and shown in detail views. + 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: | - Configures sharing behavior for the run's shared session. - When set, the worker emits `--share public:` and the bundled Warp - client applies an anyone-with-link ACL to the shared session once it has - bootstrapped. The same ACL is mirrored onto the backing conversation so - link viewers can read the conversation without being on the run's team. - Subject to the workspace-level anyone-with-link sharing setting. + description: A base64-encoded file attachment to include with the prompt + required: + - file_name + - mime_type + - data properties: - public_access: + file_name: + type: string + description: Name of the attached file + mime_type: type: string - enum: - - VIEWER - - EDITOR description: | - Grants anyone-with-link access at the specified level to the run's - shared session and backing conversation. - - VIEWER: link viewers can read the session and conversation. - - EDITOR: link viewers can also interact with the session. - Anonymous (unauthenticated) reads are not supported in this release; - link viewers must still be authenticated Warp users. - Harness: + MIME type of the attachment. + Supported image types: image/jpeg, image/png, image/gif, image/webp + data: + type: string + format: byte + description: Base64-encoded attachment data + ScheduledAgentItem: type: object - description: | - Specifies which execution harness to use for the agent run. - Default (nil/empty) uses Warp's built-in harness. - When stored as a named agent's default (create/update agent identity), - this field replaces the deprecated base_harness/base_model pair: a - non-oz type here requires the agent's base_model to be empty, since - the two describe mutually exclusive default models. + required: + - id + - name + - cron_schedule + - enabled + - prompt + - created_at + - updated_at properties: - type: + id: type: string - enum: - - oz - - claude - - gemini - - codex - description: | - The harness type identifier. - - oz: Warp's built-in harness (default) - - claude: Claude Code harness - - gemini: Gemini CLI harness - - codex: Codex CLI harness - model_id: + description: Unique identifier for the scheduled agent + name: type: string - description: | - Model to use with a third-party harness (e.g. "claude-haiku-4-5"). - Only applies when type is a non-oz harness; the top-level config - model_id targets the built-in Oz harness instead. When omitted or - empty, the harness uses its own default model. - reasoning_level: + description: Human-readable name for the schedule + cron_schedule: type: string - description: | - Reasoning effort for harnesses that support it (e.g. Codex). - Only applies when type is a non-oz harness. Ignored by harnesses - that do not support reasoning levels. - HarnessAuthSecrets: + description: Cron expression defining when the agent runs (e.g., "0 9 * * *" for daily at 9am UTC) + enabled: + type: boolean + description: Whether the schedule is currently active + prompt: + type: string + description: The prompt/instruction for the agent to execute + last_spawn_error: + type: string + nullable: true + description: Error message from the last failed spawn attempt, if any + agent_config: + $ref: '#/components/schemas/AmbientAgentConfig' + agent_uid: + type: string + format: uuid + description: UID of the agent that this schedule runs as + metadata: + allOf: + - $ref: '#/components/schemas/RunMetadata' + description: Custom metadata stamped onto every run spawned by this schedule + environment: + allOf: + - $ref: '#/components/schemas/CloudEnvironmentConfig' + description: Resolved environment configuration (if agent_config references an environment_id) + created_at: + type: string + format: date-time + description: Timestamp when the schedule was created (RFC3339) + updated_at: + type: string + format: date-time + description: Timestamp when the schedule was last updated (RFC3339) + created_by: + $ref: '#/components/schemas/RunCreatorInfo' + updated_by: + $ref: '#/components/schemas/RunCreatorInfo' + history: + $ref: '#/components/schemas/ScheduledAgentHistoryItem' + scope: + $ref: '#/components/schemas/Scope' + ScheduledAgentHistoryItem: type: object - description: | - Authentication secrets for third-party harnesses. - Only the secret for the harness specified gets injected into the environment. + description: Scheduler-derived history metadata for a scheduled agent properties: - claude_auth_secret_name: + last_ran: type: string - description: | - Name of a managed secret for Claude Code harness authentication. - The secret must exist within the caller's personal or team scope. - Only applicable when harness type is "claude". - codex_auth_secret_name: + format: date-time + nullable: true + description: Timestamp of the last successful run (RFC3339) + next_run: type: string - description: | - Name of a managed secret for Codex harness authentication. - The secret must exist within the caller's personal or team scope. - Only applicable when harness type is "codex". - MCPServerConfig: + format: date-time + nullable: true + description: Timestamp of the next scheduled run (RFC3339) + CreateScheduledAgentRequest: type: object description: | - Configuration for an MCP server. Must have exactly one of: warp_id, command, or url. + Request body for creating a new scheduled agent. + Either prompt or agent_config.skill_spec or agent_config.skills is required. + required: + - name + - cron_schedule properties: - warp_id: + name: type: string - description: | - Reference to a Warp shared MCP server by UUID, or a well-known - integration MCP id (e.g. "linear") backed by the team's integration - connection. - command: + description: Human-readable name for the schedule + cron_schedule: type: string - description: Stdio transport - command to run - args: - type: array - items: - type: string - description: Stdio transport - command arguments - url: + description: Cron expression defining when the agent runs (e.g., "0 9 * * *" for daily at 9am UTC) + prompt: 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: + description: | + The prompt/instruction for the agent to execute. + Required unless agent_config.skill_spec or agent_config.skills is provided. + mode: + $ref: '#/components/schemas/AgentRunMode' + description: | + Optional query mode applied to every triggered run. Defaults to + `normal` when omitted. The server does not infer mode from prompt + prefixes such as `/plan`. + 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. + Only valid for team-owned schedules. + agent_config: + $ref: '#/components/schemas/AmbientAgentConfig' + team: + type: boolean + description: | + Whether to create a team-owned schedule. + Defaults to true for users on a single team. + metadata: + allOf: + - $ref: '#/components/schemas/RunMetadata' + description: | + Custom metadata stamped onto every run spawned by this schedule as the run's + explicit metadata layer. + UpdateScheduledAgentRequest: type: object description: | - Error response following RFC 7807 (Problem Details for HTTP APIs). - Includes backward-compatible extension members. - - The response uses the `application/problem+json` content type. - Additional extension members (e.g., `auth_url`, `provider`) may be - present depending on the error code. + Request body for updating a scheduled agent. + Either prompt or agent_config.skill_spec or agent_config.skills is required. required: - - type - - title - - status - - error + - name + - cron_schedule + - enabled properties: - type: - type: string - format: uri - description: | - A URI reference that identifies the problem type (RFC 7807). - Format: `https://docs.warp.dev/reference/api-and-sdk/troubleshooting/errors/{error_code}` - See PlatformErrorCode for the list of possible error codes. - title: + name: 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: + description: Human-readable name for the schedule + cron_schedule: type: string - description: A human-readable explanation specific to this occurrence of the problem (RFC 7807) - instance: + description: Cron expression defining when the agent runs + prompt: type: string - description: The request path that generated this error (RFC 7807) - error: + description: | + The prompt/instruction for the agent to execute. + Required unless agent_config.skill_spec or agent_config.skills is provided. + mode: + $ref: '#/components/schemas/AgentRunMode' + description: | + Optional query mode applied to every triggered run. Defaults to + `normal` when omitted. The server does not infer mode from prompt + prefixes such as `/plan`. + enabled: + type: boolean + description: Whether the schedule should be active + agent_uid: type: string + format: uuid description: | - Human-readable error message combining title and detail. - Backward-compatible extension member for older clients. - retryable: - type: boolean + Agent UID to use as the execution principal for this schedule. + Only valid for team-owned schedules. + agent_config: + $ref: '#/components/schemas/AmbientAgentConfig' + metadata: + allOf: + - $ref: '#/components/schemas/RunMetadata' description: | - Whether the request can be retried. When true, the error is transient - and the request may be retried. When false, retrying without addressing - the underlying cause will not succeed. - trace_id: - type: string - description: OpenTelemetry trace ID for debugging and support requests - provider: - type: string - description: External provider that requires authorization, such as `linear`. - auth_url: - type: string - format: uri - description: URL where the caller can reconnect the external provider. - ArtifactResponse: - oneOf: - - $ref: '#/components/schemas/PlanArtifactResponse' - - $ref: '#/components/schemas/ScreenshotArtifactResponse' - - $ref: '#/components/schemas/FileArtifactResponse' - discriminator: - propertyName: artifact_type - mapping: - PLAN: '#/components/schemas/PlanArtifactResponse' - SCREENSHOT: '#/components/schemas/ScreenshotArtifactResponse' - FILE: '#/components/schemas/FileArtifactResponse' - PlanArtifactResponse: + Custom metadata stamped onto every run spawned by this schedule. + Updates follow full-replacement PUT semantics: omitting this field + clears the schedule's metadata. Changes apply only to future runs. + ListScheduledAgentsResponse: type: object - description: Response for retrieving a plan artifact. required: - - artifact_uid - - artifact_type - - created_at - - data + - schedules properties: - artifact_uid: + 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: Unique identifier (UUID) for the artifact - artifact_type: + description: Human-readable name for the environment + description: type: string - enum: - - PLAN - description: Type of the artifact - created_at: + nullable: true + description: Optional description of the environment + docker_image: type: string - format: date-time - description: Timestamp when the artifact was created (RFC3339) - data: - $ref: '#/components/schemas/PlanArtifactResponseData' - PlanArtifactResponseData: + description: Docker image to use (e.g., "ubuntu:latest" or "registry/repo:tag") + github_repos: + type: array + items: + $ref: '#/components/schemas/GitHubRepo' + description: List of GitHub repositories to clone into the environment + setup_commands: + type: array + items: + type: string + description: Shell commands to run during environment setup + providers: + $ref: '#/components/schemas/ProvidersConfig' + failure_session_retention_minutes: + type: integer + nullable: true + minimum: 1 + maximum: 60 + description: | + When set (1–60 minutes), a failed run using this environment + keeps its session open for this many minutes so it can be + inspected; null or absent means immediate teardown (disabled by + default). This is an idle window held open by the agent process: + activity in the session pushes the deadline out (so an active + session is not torn down mid-debug), and it ends early if the + run's sandbox reaches its own deadline first. Applies only to + future failures of runs using this environment; opting in keeps + injected environment data (including secrets) alive and incurs + compute usage for as long as the session is held open. + ProvidersConfig: type: object - description: Response data for a plan artifact, including current markdown content. + 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: - - document_uid - - notebook_uid - - content - - content_type + - 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: - document_uid: - type: string - description: Unique identifier for the plan document - notebook_uid: - type: string - description: Unique identifier for the associated notebook - url: + project_number: type: string - format: uri - description: URL to open the plan in Warp Drive - title: + description: GCP project number + workload_identity_federation_pool_id: type: string - description: Current title of the plan - content: + description: Workload Identity Federation pool ID + workload_identity_federation_provider_id: type: string - description: Current markdown content of the plan - content_type: + description: Workload Identity Federation provider ID + service_account_email: type: string - description: MIME type of the returned plan content - ScreenshotArtifactResponse: + description: Optional GCP service account email to impersonate + AwsProviderConfig: type: object - description: Response for retrieving a screenshot artifact. + 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: - - artifact_uid - - artifact_type - - created_at - - data + - role_arn properties: - artifact_uid: + role_arn: type: string - description: Unique identifier (UUID) for the artifact - artifact_type: + description: AWS IAM role ARN to assume + AwsInferenceProviderConfig: + type: object + description: | + Configures AWS Bedrock as the LLM inference provider for this + agent or run. + 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 - enum: - - SCREENSHOT - description: Type of the artifact - created_at: + description: IAM role ARN to assume when calling Bedrock. + region: type: string - format: date-time - description: Timestamp when the artifact was created (RFC3339) - data: - $ref: '#/components/schemas/ScreenshotArtifactResponseData' - ScreenshotArtifactResponseData: + description: AWS region used for STS when assuming the Bedrock inference role. + GitHubRepo: type: object - description: Response data for a screenshot artifact, including a signed download URL. required: - - download_url - - expires_at - - content_type + - owner + - repo 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: + owner: type: string - description: MIME type of the screenshot (e.g., image/png) - description: + description: GitHub repository owner (user or organization) + repo: type: string - description: Optional description of the screenshot - FileArtifactResponse: + description: GitHub repository name + ListAgentsResponse: type: object - description: Response for retrieving a file artifact. required: - - artifact_uid - - artifact_type - - created_at - - data + - agents 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: + 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 - description: Response data for a file artifact, including a signed download URL. required: - - download_url - - expires_at - - content_type - - filename + - worker_host + - connection_count + - connected_at + - last_seen_at properties: - download_url: + worker_host: type: string - format: uri - description: Time-limited signed URL to download the file - expires_at: + 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: Timestamp when the download URL expires (RFC3339) - content_type: - type: string - description: MIME type of the uploaded file - filepath: - type: string - description: | - Conversation-relative filepath for the uploaded file. Omitted for - anonymous reads of public artifacts. - filename: - type: string - description: Last path component of filepath - title: - type: string - description: | - Short, badge-visible label for the artifact. For recording artifacts, - this is the agent-authored title shown in Oz web and blocklist badges. - Distinct from description, which is longer and shown in detail views. - description: + description: Earliest connection timestamp across active connections for this worker host + last_seen_at: type: string - description: Optional description of the file - size_bytes: - type: integer - format: int64 - description: Size of the uploaded file in bytes - AttachmentInput: + format: date-time + description: Most recent heartbeat timestamp across active connections for this worker host + AgentListItem: type: object - description: A base64-encoded file attachment to include with the prompt required: - - file_name - - mime_type - - data + - name + - variants properties: - file_name: - type: string - description: Name of the attached file - mime_type: - type: string - description: | - MIME type of the attachment. - Supported image types: image/jpeg, image/png, image/gif, image/webp - data: + name: type: string - format: byte - description: Base64-encoded attachment data - ScheduledAgentItem: + 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 - - name - - cron_schedule - - enabled - - prompt - - created_at - - updated_at + - description + - base_prompt + - source + - environments 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: + description: | + Stable identifier for this skill variant. + Format: "{owner}/{repo}:{skill_path}" + Example: "warpdotdev/warp-server:.claude/skills/deploy/SKILL.md" + description: type: string - nullable: true - description: Error message from the last failed spawn attempt, if any - agent_config: - $ref: '#/components/schemas/AmbientAgentConfig' - agent_uid: + description: Description of the agent variant + base_prompt: type: string - format: uuid - description: UID of the agent that this schedule runs as - metadata: - allOf: - - $ref: '#/components/schemas/RunMetadata' - description: Custom metadata stamped onto every run spawned by this schedule - environment: - allOf: - - $ref: '#/components/schemas/CloudEnvironmentConfig' - description: Resolved environment configuration (if agent_config references an environment_id) - created_at: + 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 - description: Timestamp when the schedule was created (RFC3339) - updated_at: + nullable: true + description: Timestamp of the last time this skill was run (RFC3339) + error: 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: + description: | + Non-empty when the skill's SKILL.md file exists but is malformed. + Contains a description of the parse failure. Only present when + include_malformed_skills=true is passed to the list agents endpoint. + AgentListSource: type: object - description: Scheduler-derived history metadata for a scheduled agent + required: + - owner + - name + - skill_path properties: - last_ran: + owner: type: string - format: date-time - nullable: true - description: Timestamp of the last successful run (RFC3339) - next_run: + description: GitHub repository owner + name: type: string - format: date-time - nullable: true - description: Timestamp of the next scheduled run (RFC3339) - CreateScheduledAgentRequest: + 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. + Present only for skills discovered from self-hosted workers + (as opposed to skills from GitHub repos linked to environments). + AgentListEnvironment: type: object - description: | - Request body for creating a new scheduled agent. - Either prompt or agent_config.skill_spec or agent_config.skills is required. required: + - uid - name - - cron_schedule properties: + uid: + type: string + description: Unique identifier for the environment name: type: string - description: Human-readable name for the schedule - cron_schedule: + 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 - description: Cron expression defining when the agent runs (e.g., "0 9 * * *" for daily at 9am UTC) - prompt: + 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. + Used in the `type` URI of Error responses and in the `error_code` + field of RunStatusMessage. + + User errors (run transitions to FAILED): + - `insufficient_credits` — Team has no remaining add-on credits + - `feature_not_available` — Required feature not enabled for user's plan + - `external_authentication_required` — User hasn't authorized a required external service + - `not_authorized` — Principal lacks permission for the requested operation + - `invalid_request` — Request is malformed or contains invalid parameters + - `resource_not_found` — Referenced resource does not exist + - `budget_exceeded` — Spending budget limit has been reached + - `integration_disabled` — Integration is disabled and must be enabled + - `integration_not_configured` — Integration setup is incomplete + - `operation_not_supported` — Requested operation not supported for this resource/state + - `environment_setup_failed` — Client-side environment setup failed + - `content_policy_violation` — Prompt or setup commands violated content policy + - `conflict` — Request conflicts with the current state of the resource + + Warp errors (run transitions to ERROR): + - `authentication_required` — Request lacks valid authentication credentials + - `resource_unavailable` — Transient infrastructure issue (retryable) + - `internal_error` — Unexpected server-side error (retryable) + 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 prompt/instruction for the agent to execute. - Required unless agent_config.skill_spec or agent_config.skills is provided. + description: The follow-up message to send to the run. mode: $ref: '#/components/schemas/AgentRunMode' description: | - Optional query mode applied to every triggered run. Defaults to - `normal` when omitted. The server does not infer mode from prompt - prefixes such as `/plan`. - enabled: - type: boolean - description: Whether the schedule should be active immediately - default: true - agent_uid: + Optional query mode for the follow-up. Defaults to `normal` when + omitted. The server does not infer mode from prompt prefixes such + as `/plan`. + ListModelsResponse: + type: object + required: + - default_model_id + - models + properties: + default_model_id: type: string - format: uuid - description: | - Agent UID to use as the execution principal for this schedule. - Only valid for team-owned schedules. - agent_config: - $ref: '#/components/schemas/AmbientAgentConfig' - team: - type: boolean - description: | - Whether to create a team-owned schedule. - Defaults to true for users on a single team. - metadata: - allOf: - - $ref: '#/components/schemas/RunMetadata' - description: | - Custom metadata stamped onto every run spawned by this schedule as the run's - explicit metadata layer. - UpdateScheduledAgentRequest: + 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 - description: | - Request body for updating a scheduled agent. - Either prompt or agent_config.skill_spec or agent_config.skills is required. required: - - name - - cron_schedule - - enabled + - id + - display_name + - provider + - vision_supported properties: - name: + id: type: string - description: Human-readable name for the schedule - cron_schedule: + description: Unique identifier for the model (e.g. "claude-4-6-opus-high" or "gpt-5-4-high") + display_name: type: string - description: Cron expression defining when the agent runs - prompt: + description: Human-readable name of the model + provider: type: string - description: | - The prompt/instruction for the agent to execute. - Required unless agent_config.skill_spec or agent_config.skills is provided. - mode: - $ref: '#/components/schemas/AgentRunMode' - description: | - Optional query mode applied to every triggered run. Defaults to - `normal` when omitted. The server does not infer mode from prompt - prefixes such as `/plan`. - enabled: + enum: + - OPENAI + - ANTHROPIC + - GOOGLE + - UNKNOWN + description: The LLM provider + vision_supported: type: boolean - description: Whether the schedule should be active - agent_uid: + description: Whether the model supports vision/image inputs + description: type: string - format: uuid - description: | - Agent UID to use as the execution principal for this schedule. - Only valid for team-owned schedules. - agent_config: - $ref: '#/components/schemas/AmbientAgentConfig' - metadata: - allOf: - - $ref: '#/components/schemas/RunMetadata' - description: | - Custom metadata stamped onto every run spawned by this schedule. - Updates follow full-replacement PUT semantics: omitting this field - clears the schedule's metadata. Changes apply only to future runs. - ListScheduledAgentsResponse: + description: Optional extra descriptor for the model + reasoning_level: + type: string + description: Reasoning level descriptor, if any (e.g. "low", "medium", "high") + disable_reason: + type: string + enum: + - PROVIDER_OUTAGE + - OUT_OF_REQUESTS + - ADMIN_DISABLED + - REQUIRES_UPGRADE + description: If set, the model is currently unavailable for the given reason + ExternalReferenceArtifactData: type: object + description: Data for a generic external reference artifact. required: - - schedules + - reference_type + - url properties: - schedules: - type: array - items: - $ref: '#/components/schemas/ScheduledAgentItem' - description: List of scheduled agents - DeleteScheduledAgentResponse: + reference_type: + type: string + maxLength: 256 + description: | + Free-form category identifier for this reference (e.g. "linear_issue", + "spec_link", "jira_ticket"). Used for filtering and display. + url: + type: string + maxLength: 2048 + description: | + Canonical URL for the reference. Used as the key for reverse lookups + ("which run produced this URL?"). + title: + type: string + description: Optional human-readable label for the reference. + metadata: + type: object + additionalProperties: true + description: Optional category-specific extra fields. + RunByExternalReferenceResponse: type: object + description: Response for a run reverse-lookup by external reference URL. required: - - success + - run_id properties: - success: - type: boolean - description: Whether the deletion was successful - CloudEnvironmentConfig: + run_id: + type: string + description: The ID of the run that produced the external reference. + AgentSkill: type: object - description: Configuration for a cloud environment used by scheduled agents + description: | + Information about the agent skill used for the run. + Either full_path or bundled_skill_id will be set, but not both. properties: name: type: string - description: Human-readable name for the environment + description: Human-readable name of the skill description: type: string - nullable: true - description: Optional description of the environment - docker_image: + description: Description of the skill + full_path: type: string - description: Docker image to use (e.g., "ubuntu:latest" or "registry/repo:tag") - github_repos: - type: array - items: - $ref: '#/components/schemas/GitHubRepo' - description: List of GitHub repositories to clone into the environment - setup_commands: - type: array - items: - type: string - description: Shell commands to run during environment setup - providers: - $ref: '#/components/schemas/ProvidersConfig' - failure_session_retention_minutes: - type: integer - nullable: true - minimum: 1 - maximum: 60 - description: | - When set (1–60 minutes), a failed run using this environment keeps its session open - for this many minutes so it can be inspected. null or absent means immediate teardown - (disabled by default). - - The window is an idle window held open by the agent process itself: working in the - session pushes the deadline out, so a session in active use is not torn down - mid-debug. It ends early if the run's sandbox reaches its own deadline first. - - This policy applies to future failures of runs using this environment; it does not - change the window a currently-failed run was already started with. Opting in keeps - injected environment data (including secrets) alive and incurs compute usage for as - long as the session is held open. - ProvidersConfig: - type: object - description: Optional cloud provider configurations for automatic auth - properties: - gcp: - $ref: '#/components/schemas/GcpProviderConfig' - aws: - $ref: '#/components/schemas/AwsProviderConfig' - InferenceProvidersConfig: + 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 - description: Inference provider settings used for LLM calls. + required: + - environments properties: - aws: - $ref: '#/components/schemas/AwsInferenceProviderConfig' - GcpProviderConfig: + environments: + type: array + items: + $ref: '#/components/schemas/CloudEnvironment' + description: List of accessible cloud environments + CloudEnvironment: type: object - description: GCP Workload Identity Federation settings + description: A cloud environment for running agents 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 + - uid + - config + - last_updated + - setup_failed properties: - project_number: - type: string - description: GCP project number - workload_identity_federation_pool_id: + uid: type: string - description: Workload Identity Federation pool ID - workload_identity_federation_provider_id: + description: Unique identifier for the environment + config: + $ref: '#/components/schemas/CloudEnvironmentConfig' + last_updated: type: string - description: Workload Identity Federation provider ID - service_account_email: + format: date-time + description: Timestamp when the environment was last updated (RFC3339) + last_task_run_timestamp: type: string - description: Optional GCP service account email to impersonate - AwsProviderConfig: + 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: 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 + description: | + Reference to a managed secret by name. required: - - role_arn + - name properties: - role_arn: + name: type: string - description: AWS IAM role ARN to assume - AwsInferenceProviderConfig: + description: Name of the managed secret. + MemoryStoreRef: type: object - description: | - Configures AWS Bedrock as the LLM inference provider for this - agent or run. - externalDocs: - description: AWS documentation on IAM OIDC federation - url: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html + description: Reference to a memory store to attach to an agent. + required: + - uid + - access + - instructions properties: - disabled: - type: boolean - description: If true, opt out of Bedrock at this layer. - role_arn: + uid: type: string - description: IAM role ARN to assume when calling Bedrock. - region: + description: UID of the memory store. + access: type: string - description: AWS region used for STS when assuming the Bedrock inference role. - GitHubRepo: + enum: + - read_write + - read_only + description: Access level for the store. + instructions: + type: string + description: Instructions for how the agent should use this memory store. Must not be empty. + MemoryStoreAttachmentResponse: type: object + description: Memory store attached to an agent. required: - - owner - - repo + - uid + - access + - instructions + - owner_type + - owner_uid properties: - owner: + uid: type: string - description: GitHub repository owner (user or organization) - repo: + description: UID of the memory store. + access: type: string - description: GitHub repository name - ListAgentsResponse: + enum: + - read_write + - read_only + description: Access level for the store. + instructions: + type: string + description: Instructions for how the agent should use this memory store. + owner_type: + type: string + description: Public owner type. + enum: + - user + - service_account + - team + owner_uid: + type: string + description: Public UID of the user, service account, or team that owns the memory store. + description: + type: string + description: Optional description for the memory store. + AgentAutoMemoryCreateConfig: type: object - required: - - agents + description: Auto-memory settings for creating an agent. properties: - agents: + enabled: + type: boolean + description: | + Whether to create and attach a default service-account-owned memory store for this agent. + Defaults to true when omitted. + AgentMemoryCreateConfig: + type: object + description: Memory settings for creating an agent. + properties: + auto_memory: + allOf: + - $ref: '#/components/schemas/AgentAutoMemoryCreateConfig' + description: Agent-owned memory settings. Defaults to enabled when omitted. + attached_stores: type: array items: - $ref: '#/components/schemas/AgentListItem' - description: List of available agents - ListConnectedSelfHostedWorkersResponse: + $ref: '#/components/schemas/MemoryStoreRef' + description: | + Existing team memory stores to attach to the agent. + Duplicate UIDs within a single request are rejected. + AgentMemoryUpdateConfig: + type: object + description: Memory settings for updating an agent. + properties: + attached_stores: + type: array + nullable: true + items: + $ref: '#/components/schemas/MemoryStoreRef' + description: | + Replacement list of attached team memory stores. Omit to leave unchanged, + pass an empty array to clear, or pass a non-empty array to replace. + AgentAutoMemoryResponse: type: object + description: Auto-memory state for an agent. required: - - workers + - enabled properties: - workers: + enabled: + type: boolean + description: Whether this agent has an agent-owned memory store. + store: + $ref: '#/components/schemas/MemoryStoreAttachmentResponse' + AgentMemoryResponse: + type: object + description: Memory settings for an agent. + required: + - auto_memory + - attached_stores + properties: + auto_memory: + $ref: '#/components/schemas/AgentAutoMemoryResponse' + attached_stores: type: array items: - $ref: '#/components/schemas/ConnectedSelfHostedWorker' - description: Connected self-hosted workers for the authenticated principal's team - ConnectedSelfHostedWorker: + $ref: '#/components/schemas/MemoryStoreRef' + description: Team memory stores attached to the agent. + AgentCredentialStrategy: + type: string + description: | + Default credential strategy for runs executed by a named agent; an + agent may leave this unset (see AgentResponse.credential_strategy + for the full resolution order). + - EXECUTOR: runs authenticate with the named agent's own credentials + (e.g. a GitHub App installation token for the agent's team). + - CREATOR: runs authenticate with the credentials of the principal + that created the run. + enum: + - CREATOR + - EXECUTOR + ScorerClassification: type: object required: - - worker_host - - connection_count - - connected_at - - last_seen_at + - value + - score 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: + value: type: string - format: date-time - description: Earliest connection timestamp across active connections for this worker host - last_seen_at: + minLength: 1 + maxLength: 1048576 + description: Classification value returned by the scorer + description: type: string - format: date-time - description: Most recent heartbeat timestamp across active connections for this worker host - AgentListItem: + nullable: true + maxLength: 1048576 + description: | + Optional free-text meaning of this classification, surfaced to the + judge alongside the value. Omit or leave blank for a score-only + label. + score: + type: number + format: double + minimum: 0 + maximum: 1 + description: | + Score this classification carries, from 0 to 1. A run passes when + its scored label's score is greater than or equal to the scorer's + threshold. A score of exactly 0 is valid, so this is not enforced + with a "required" binding (which would reject the zero value); + handlers validate its range explicitly instead. + CreateScorerRequest: type: object + description: | + Scorer definition. Text fields are trimmed of surrounding whitespace + before validation; required text fields must not be blank after trimming, + and no text field may exceed 1 MiB (1048576 bytes). required: + - factory_uid - name - - variants + - scoring_prompt + - allowed_classifications + - threshold + - scope_mode + - model_id properties: + factory_uid: + type: string + minLength: 1 + description: UID of the factory that owns the scorer name: type: string - description: Human-readable name of the agent - variants: + minLength: 1 + maxLength: 1048576 + description: Display name for the scorer + description: + type: string + nullable: true + maxLength: 1048576 + description: Optional description of the scorer + scoring_prompt: + type: string + minLength: 1 + maxLength: 1048576 + description: Instructions used to score matching runs + allowed_classifications: type: array + minItems: 1 + maxItems: 20 + description: Values the scorer may return; classification values must be unique items: - $ref: '#/components/schemas/AgentListVariant' - description: Available variants of this agent - AgentListVariant: + $ref: '#/components/schemas/ScorerClassification' + threshold: + type: number + format: double + minimum: 0 + maximum: 1 + description: | + Score a run's classified label must meet or exceed to pass, from 0 + to 1. + scope_mode: + type: string + enum: + - all_agents + - selected_agents + description: Whether the scorer applies to every factory agent or only agent_uids + agent_uids: + type: array + description: Required and non-empty for selected_agents; must be empty for all_agents + items: + type: string + sampling_rate: + type: number + format: double + nullable: true + minimum: 0 + maximum: 100 + description: | + Percentage of the scorer's eligible runs to score, from 0 to + 100; omit to score every eligible run, and 0 stops automatic + scoring (manual dispatch still works). A value with more than + two decimal places is rounded to two rather than rejected, and + the rounded value is what is stored. Sampling applies to + periodic scoring only, and runs are chosen deterministically per + (scorer, run), so lowering the rate reduces how many runs are + scored rather than how often. + model_id: + type: string + minLength: 1 + maxLength: 255 + description: | + LLM model dispatched judge runs use to evaluate this scorer's + rubric. + self_improvement_enabled: + type: boolean + description: | + Optionally enable self-improvement for the newly created scorer + in the same transactional request, instead of a separate call to + PUT /factory/scorers/{scorer_id}/self-improvement-config + afterward; defaults to false. The response does not echo this + back — a successful (2xx) response means the requested state was + applied, confirmable at any time with GET .../self-improvement-config. + Setting this to true requires a human user principal, matching + the restriction on the PUT endpoint; a service-account principal + gets the same error as calling that endpoint directly. + UpdateScorerRequest: type: object - required: - - id - - description - - base_prompt - - source - - environments + description: | + Partial scorer definition update. Every field is optional, but at least + one must be present. Text fields are trimmed of surrounding whitespace + before validation; a provided required text field must not be blank after + trimming, and no text field may exceed 1 MiB (1048576 bytes). properties: - id: + name: type: string - description: | - Stable identifier for this skill variant. - Format: "{owner}/{repo}:{skill_path}" - Example: "warpdotdev/warp-server:.claude/skills/deploy/SKILL.md" + minLength: 1 + maxLength: 1048576 + description: New display name for the scorer description: type: string - description: Description of the agent variant - base_prompt: + maxLength: 1048576 + description: New description; an empty string clears it + scoring_prompt: type: string - description: Base prompt/instructions for the agent - source: - $ref: '#/components/schemas/AgentListSource' - environments: + minLength: 1 + maxLength: 1048576 + description: New instructions used to score matching runs + allowed_classifications: type: array + minItems: 1 + maxItems: 20 + description: | + Replacement set of values the scorer may return; classification + values must be unique. Removing a classification the scorer's + self-improvement config still targets is rejected. items: - $ref: '#/components/schemas/AgentListEnvironment' - description: Environments where this agent variant is available - last_run_timestamp: + $ref: '#/components/schemas/ScorerClassification' + threshold: + type: number + format: double + minimum: 0 + maximum: 1 + description: | + New score a run's classified label must meet or exceed to pass, + from 0 to 1. + sampling_rate: + type: number + format: double + minimum: 0 + maximum: 100 + description: | + New percentage of eligible runs this scorer should score, rounded + to two decimal places. 0 stops automatic scoring; manual dispatch + still works. + scope_mode: type: string - format: date-time - nullable: true - description: Timestamp of the last time this skill was run (RFC3339) - error: + enum: + - all_agents + - selected_agents + description: | + New scope mode. Defaults to the scorer's current mode when only + agent_uids is supplied. + agent_uids: + type: array + description: | + Complete replacement membership for the scorer's scope. Required and + non-empty when the resulting scope_mode is selected_agents; must be + empty for all_agents. + items: + type: string + model_id: type: string + minLength: 1 + maxLength: 255 description: | - Non-empty when the skill's SKILL.md file exists but is malformed. - Contains a description of the parse failure. Only present when - include_malformed_skills=true is passed to the list agents endpoint. - AgentListSource: + New LLM model dispatched judge runs use to evaluate this scorer's + rubric. Must not be blank when provided. + ScorerKind: + type: string + description: | + Whether the scorer is user-defined or a platform-owned managed scorer. + Read-only on responses; create input does not accept scorer_kind. + enum: + - user + - benchmark_task_correctness + ScorerResponse: type: object required: - - owner + - id + - factory_uid - name - - skill_path + - description + - scoring_prompt + - allowed_classifications + - threshold + - scorer_kind + - version + - scope_mode + - agent_uids + - sampling_rate + - model_id + - created_at + - updated_at properties: - owner: + id: + type: integer + description: Scorer identifier + factory_uid: type: string - description: GitHub repository owner + description: UID of the factory that owns the scorer name: type: string - description: GitHub repository name - skill_path: + description: Display name for the scorer + description: type: string - description: Path to the skill definition file within the repository - worker_host: + description: Description of the scorer + scoring_prompt: + type: string + description: Instructions used to score matching runs + allowed_classifications: + type: array + items: + $ref: '#/components/schemas/ScorerClassification' + threshold: + type: number + format: double + description: Score a run's classified label must meet or exceed to pass, from 0 to 1 + scorer_kind: + $ref: '#/components/schemas/ScorerKind' + version: + type: integer + description: Scorer definition version + scope_mode: type: string + enum: + - all_agents + - selected_agents + description: Whether the scorer applies to every factory agent or selected agent_uids + agent_uids: + type: array + description: Agents attached to a selected_agents scorer; empty for all_agents + items: + type: string + sampling_rate: + type: number + format: double description: | - Self-hosted worker host that reported this skill. - Present only for skills discovered from self-hosted workers - (as opposed to skills from GitHub repos linked to environments). - AgentListEnvironment: + Percentage of the scorer's eligible runs that periodic scoring scores, + to two decimal places. 0 stops automatic scoring. + model_id: + type: string + description: | + LLM model dispatched judge runs use to evaluate this scorer's + rubric. + created_at: + type: string + format: date-time + description: When the scorer was created + updated_at: + type: string + format: date-time + description: When the scorer was updated + ScorerScopeAgent: type: object required: - uid @@ -3492,374 +5429,528 @@ components: properties: uid: type: string - description: Unique identifier for the environment + description: Unique identifier of the agent name: type: string - description: Human-readable name of the environment - Scope: + description: Display name of the agent + ScorerListItem: type: object - description: Ownership scope for a resource (team or personal) required: - - type + - id + - factory_uid + - name + - description + - scoring_prompt + - allowed_classifications + - threshold + - scope_mode + - agents + - scorer_kind + - version + - sampling_rate + - created_at + - updated_at + - result_count + - model_id + - pass_rate_summary + - self_improvement_enabled properties: - type: + id: + type: integer + description: Scorer identifier + factory_uid: type: string - enum: - - User - - Team - description: Type of ownership ("User" for personal, "Team" for team-owned) - uid: + description: Public UID of the factory that owns the scorer + name: type: string - description: UID of the owning user or team - PlatformErrorCode: - type: string - description: | - Machine-readable error code identifying the problem type. - Used in the `type` URI of Error responses and in the `error_code` - field of RunStatusMessage. - - User errors (run transitions to FAILED): - - `insufficient_credits` — Team has no remaining add-on credits - - `feature_not_available` — Required feature not enabled for user's plan - - `external_authentication_required` — User hasn't authorized a required external service - - `not_authorized` — Principal lacks permission for the requested operation - - `invalid_request` — Request is malformed or contains invalid parameters - - `resource_not_found` — Referenced resource does not exist - - `budget_exceeded` — Spending budget limit has been reached - - `integration_disabled` — Integration is disabled and must be enabled - - `integration_not_configured` — Integration setup is incomplete - - `operation_not_supported` — Requested operation not supported for this resource/state - - `environment_setup_failed` — Client-side environment setup failed - - `content_policy_violation` — Prompt or setup commands violated content policy - - `conflict` — Request conflicts with the current state of the resource - - Warp errors (run transitions to ERROR): - - `authentication_required` — Request lacks valid authentication credentials - - `resource_unavailable` — Transient infrastructure issue (retryable) - - `internal_error` — Unexpected server-side error (retryable) - 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: + description: Display name for the scorer + description: type: string - description: The follow-up message to send to the run. - mode: - $ref: '#/components/schemas/AgentRunMode' + description: Description of the scorer + scoring_prompt: + type: string + description: Instructions used to score the agent's runs + allowed_classifications: + type: array + items: + $ref: '#/components/schemas/ScorerClassification' + threshold: + type: number + format: double + description: Score a run's classified label must meet or exceed to pass, from 0 to 1 + scope_mode: + type: string + description: all_agents (every agent in the scorer's factory) or selected_agents + agents: + type: array + items: + $ref: '#/components/schemas/ScorerScopeAgent' + description: Named agents in scope; empty when the scorer covers all factory agents + scorer_kind: + $ref: '#/components/schemas/ScorerKind' + version: + type: integer + description: Scorer definition version + sampling_rate: + type: number + format: double description: | - Optional query mode for the follow-up. Defaults to `normal` when - omitted. The server does not infer mode from prompt prefixes such - as `/plan`. - ListModelsResponse: + Percentage of the scorer's eligible runs that periodic scoring scores, + to two decimal places. 0 stops automatic scoring. + created_at: + type: string + format: date-time + description: When the scorer was created + updated_at: + type: string + format: date-time + description: When the scorer was last updated + result_count: + type: integer + description: Number of live scores recorded for the scorer + last_scored_at: + type: string + format: date-time + nullable: true + description: When the scorer last recorded a score + model_id: + type: string + description: | + LLM model dispatched judge runs use to evaluate this scorer's + rubric. + pass_rate_summary: + $ref: '#/components/schemas/ScorerPassRateSummary' + self_improvement_enabled: + type: boolean + description: Whether self-improvement is enabled for this scorer + ListScorersResponse: type: object required: - - default_model_id - - models + - scorers properties: - default_model_id: - type: string - description: The ID of the default model for agent runs - models: + scorers: type: array items: - $ref: '#/components/schemas/ModelInfo' - description: List of available models - ModelInfo: + $ref: '#/components/schemas/ScorerListItem' + ScorerOutcome: + type: string + enum: + - pass + - fail + description: | + Pass/fail verdict of a recorded score, derived at read time against + the evaluation's current threshold rather than frozen at scoring + time — editing the threshold retroactively changes the outcome of + already-scored runs. Today this is "pass" or "fail"; clients should + tolerate additional values so future non-scoreable verdicts (for + example, excluded from scoring) do not break them. Do not use + result_count as a pass-rate denominator: only pass and fail count. + ScorerPassRateSummary: type: object required: - - id - - display_name - - provider - - vision_supported + - pass_count + - fail_count + - recent_outcomes properties: - id: + pass_count: + type: integer + description: | + Number of live scores whose derived outcome is pass, within the + same recent_outcomes_limit window as recent_outcomes (not the + scorer's all-time history). + fail_count: + type: integer + description: | + Number of live scores whose derived outcome is fail, within the + same recent_outcomes_limit window as recent_outcomes (not the + scorer's all-time history). + pass_rate: + type: number + format: double + nullable: true + description: | + pass_count / (pass_count + fail_count), over the same recent + window as pass_count and fail_count. Null when there are no + scoreable (pass or fail) scores in that window. Clients must not + use result_count as the denominator. + recent_outcomes: + type: array + items: + $ref: '#/components/schemas/ScorerOutcome' + description: | + The scorer's most recent live scores' outcomes, oldest first, + for a compact history strip; length is bounded by + recent_outcomes_limit, and failed attempts (no live score) are + not included. pass_count and fail_count are computed over this + exact same windowed set, so the headline rate and the strip + always describe the same scores. + ScorerResultStatus: + type: string + description: | + Outcome of a scoring attempt: "scored", "failed", or "in_flight" (no + live score yet and a judge is currently running). A failed or + in_flight attempt has no classification. A scored attempt whose + is_in_flight is also true has a live classification while a + replacement judge runs. + ScorerResult: + type: object + required: + - run_id + - status + - attempted_at + - is_in_flight + properties: + run_id: type: string - description: Unique identifier for the model (e.g. "claude-4-6-opus-high" or "gpt-5-4-high") - display_name: + description: The scored agent run + conversation_id: type: string - description: Human-readable name of the model - provider: + nullable: true + description: Conversation whose transcript was judged + conversation_title: type: string - enum: - - OPENAI - - ANTHROPIC - - GOOGLE - - UNKNOWN - description: The LLM provider - vision_supported: - type: boolean - description: Whether the model supports vision/image inputs - description: + nullable: true + description: Title of the judged conversation + status: + $ref: '#/components/schemas/ScorerResultStatus' + classification: type: string - description: Optional extra descriptor for the model - reasoning_level: + nullable: true + description: The chosen classification; absent when the attempt failed + attempted_at: type: string - description: Reasoning level descriptor, if any (e.g. "low", "medium", "high") - disable_reason: + format: date-time + description: When the scorer last attempted this run + scored_at: type: string - enum: - - PROVIDER_OUTAGE - - OUT_OF_REQUESTS - - ADMIN_DISABLED - - REQUIRES_UPGRADE - description: If set, the model is currently unavailable for the given reason - ExternalReferenceArtifactData: + format: date-time + nullable: true + description: When the live score was recorded; absent for failed attempts + scoring_run_id: + type: string + nullable: true + description: The Warp run that performed the judging; absent when scoring was never dispatched for this attempt + scoring_run_usage: + allOf: + - $ref: '#/components/schemas/RequestUsage' + description: | + Cost of the scoring run (the Warp judge run), independent of the + scored run's own cost. Absent when there is no scoring run yet, or + its usage is not yet available (e.g. the judge is still in flight). + scoring_run_time: + type: string + nullable: true + description: | + Total runtime of the scoring run as an ISO 8601 duration. Absent + when there is no scoring run or its execution duration is not yet + available. + score: + type: number + format: double + nullable: true + description: | + Numeric score of the classified label, resolved from the attempt's + config snapshot at scoring time. Absent when the attempt failed. + outcome: + allOf: + - $ref: '#/components/schemas/ScorerOutcome' + nullable: true + description: | + Pass/fail verdict for this score, derived at read time against the + evaluation's current threshold. Absent when the attempt failed. + is_in_flight: + type: boolean + description: | + True when a non-terminal judge run currently holds this pair. + Independent of status/classification: a previous live + classification stays visible while a replacement judge runs. + ListScorerResultsResponse: type: object - description: Data for a generic external reference artifact. required: - - reference_type - - url + - results + - page_info properties: - reference_type: - type: string - maxLength: 256 + results: + type: array + items: + $ref: '#/components/schemas/ScorerResult' + page_info: + $ref: '#/components/schemas/PageInfo' + ScorerPassRateSeriesResponse: + type: object + description: | + A scorer's pass-rate series over one date range, period-aligned to + period_list, plus a full-range aggregate computed over the exact + same set of live scores as the series. + required: + - group_by_period + - period_list + - pass_count + - fail_count + - pass_rate + - pass_count_series + - fail_count_series + - pass_rate_series + properties: + group_by_period: + $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' + period_list: + type: array + description: | + Period labels every series aligns to (dates like 2026-07-01; + weeks labeled by their Sunday start date). + items: + type: string + pass_count: + type: integer + format: int64 + description: Live scores whose derived outcome is pass, over the whole range. + fail_count: + type: integer + format: int64 + description: Live scores whose derived outcome is fail, over the whole range. + pass_rate: + type: number + format: double + nullable: true description: | - Free-form category identifier for this reference (e.g. "linear_issue", - "spec_link", "jira_ticket"). Used for filtering and display. - url: - type: string - maxLength: 2048 + pass_count / (pass_count + fail_count) over the whole range; null + when the range has no pass/fail scores. The dashboard headline + should use this field, not a per-period value, so it always + describes the same window as the chart. + pass_count_series: + type: array + description: One entry per period_list entry, zero-filled. + items: + type: integer + format: int64 + fail_count_series: + type: array + description: One entry per period_list entry, zero-filled. + items: + type: integer + format: int64 + pass_rate_series: + type: array description: | - Canonical URL for the reference. Used as the key for reverse lookups - ("which run produced this URL?"). - title: - type: string - description: Optional human-readable label for the reference. - metadata: - type: object - additionalProperties: true - description: Optional category-specific extra fields. - RunByExternalReferenceResponse: + One entry per period_list entry; pass_count_series[i] / + (pass_count_series[i] + fail_count_series[i]). Null for a period + with no pass/fail scores, so the chart renders a gap there + instead of a false 0%. + items: + type: number + format: double + nullable: true + ManualScoringTarget: type: object - description: Response for a run reverse-lookup by external reference URL. required: - run_id + - scorer_ids properties: run_id: type: string - description: The ID of the run that produced the external reference. - AgentSkill: + description: The run to score + scorer_ids: + type: array + minItems: 1 + items: + type: integer + description: Scorer IDs to invoke against run_id + ManualScoringDispatchRequest: type: object + required: + - targets + properties: + targets: + type: array + minItems: 1 + maxItems: 100 + items: + $ref: '#/components/schemas/ManualScoringTarget' + description: | + One or more (run, scorer) targets, expressed as one entry per run + with its scorer IDs. Duplicate (run_id, scorer_id) pairs across + entries are collapsed. At most 100 unique pairs total. + ManualScoringDispatchStatus: + type: string + enum: + - dispatched + - already_in_flight + - failed_no_transcript + - failed_to_dispatch description: | - Information about the agent skill used for the run. - Either full_path or bundled_skill_id will be set, but not both. + Outcome of one dispatched (run, scorer) pair: "dispatched" (stamped + with a new or shared judge run), "already_in_flight" (an existing live + judge already holds the pair; it is not queued, cancelled, or + replaced), "failed_no_transcript" (no scoreable transcript existed, so + a failed attempt was stamped instead), or "failed_to_dispatch" (an + operational error occurred after validation passed; retryable). + ManualScoringDispatchResult: + type: object + required: + - run_id + - scorer_id + - status properties: - name: - type: string - description: Human-readable name of the skill - description: + run_id: type: string - description: Description of the skill - full_path: + description: The scored agent run + scorer_id: + type: integer + description: The invoked scorer + status: + $ref: '#/components/schemas/ManualScoringDispatchStatus' + scoring_run_id: type: string - description: Path to the SKILL.md file (for file-based skills) - bundled_skill_id: + nullable: true + description: | + The judge run covering this pair; present for dispatched and + already_in_flight, absent otherwise. Multiple pairs for the same + run can share one scoring_run_id. + error: type: string - description: Unique identifier for bundled skills - ListEnvironmentsResponse: + nullable: true + description: Safe error detail; present only for failed_to_dispatch + ManualScoringDispatchResponse: type: object required: - - environments + - results properties: - environments: + results: type: array items: - $ref: '#/components/schemas/CloudEnvironment' - description: List of accessible cloud environments - CloudEnvironment: + $ref: '#/components/schemas/ManualScoringDispatchResult' + description: One entry per requested pair, in no particular order + RunScoreAttemptStatus: + type: string + enum: + - in_flight + - scored + - failed + description: | + Classification of a run's current attempt against one evaluation. + "scored" takes precedence over in-flight: a live score reads as + scored even while a replacement judge runs, and is_in_flight reports + that overlap independently. + RunScoreTriggerSource: + type: string + enum: + - automatic + - manual + description: Whether the current attempt was requested by the periodic job or a manual dispatch request + RunScoreItem: type: object - description: A cloud environment for running agents required: - - uid - - config - - last_updated - - setup_failed + - scorer_id + - scorer_name + - attempt_status + - is_in_flight + - trigger_source + - attempted_at properties: - uid: + scorer_id: + type: integer + description: The evaluation that attempted this run + scorer_name: type: string - description: Unique identifier for the environment - config: - $ref: '#/components/schemas/CloudEnvironmentConfig' - last_updated: + description: Display name of the evaluation + attempt_status: + $ref: '#/components/schemas/RunScoreAttemptStatus' + is_in_flight: + type: boolean + description: True when a non-terminal judge run currently holds this pair + trigger_source: + $ref: '#/components/schemas/RunScoreTriggerSource' + classification: + type: string + nullable: true + description: The live classification; absent when there is no live score + attempted_at: type: string format: date-time - description: Timestamp when the environment was last updated (RFC3339) - last_task_run_timestamp: + description: When the evaluation last attempted this run + scored_at: 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. - required: - - name - properties: - name: + description: When the live score was recorded; absent when there is no live score + scoring_run_id: type: string - description: Name of the managed secret. - MemoryStoreRef: + nullable: true + description: The Warp run that performed the judging; absent when scoring was never dispatched for this attempt + GetRunScoresResponse: type: object - description: Reference to a memory store to attach to an agent. required: - - uid - - access - - instructions + - run_id + - scores 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: + run_id: type: string - description: Instructions for how the agent should use this memory store. Must not be empty. - MemoryStoreAttachmentResponse: + description: The run these scores belong to + scores: + type: array + items: + $ref: '#/components/schemas/RunScoreItem' + description: One entry per evaluation that has attempted the run, most recent attempt first + ScorerResultReason: type: object - description: Memory store attached to an agent. required: - - uid - - access - - instructions - - owner_type - - owner_uid + - run_id + - status 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: + run_id: type: string - description: Instructions for how the agent should use this memory store. - owner_type: + description: The run this reason belongs to + status: type: string - description: Public owner type. enum: - - user - - service_account - - team - owner_uid: - type: string - description: Public UID of the user, service account, or team that owns the memory store. - description: - type: string - description: Optional description for the memory store. - AgentAutoMemoryCreateConfig: - type: object - description: Auto-memory settings for creating an agent. - properties: - enabled: - type: boolean + - available + - absent + - unavailable description: | - Whether to create and attach a default service-account-owned memory store for this agent. - Defaults to true when omitted. - AgentMemoryCreateConfig: - type: object - description: Memory settings for creating an agent. - properties: - auto_memory: - allOf: - - $ref: '#/components/schemas/AgentAutoMemoryCreateConfig' - description: Agent-owned memory settings. Defaults to enabled when omitted. - attached_stores: - type: array - items: - $ref: '#/components/schemas/MemoryStoreRef' - description: | - Existing team memory stores to attach to the agent. - Duplicate UIDs within a single request are rejected. - AgentMemoryUpdateConfig: - type: object - description: Memory settings for updating an agent. - properties: - attached_stores: - type: array + Availability of the run's judge reason: "available" when the reason + was read, "absent" when the judge recorded none, and "unavailable" + when a recorded reason could not be read back. + reason: + type: string nullable: true - items: - $ref: '#/components/schemas/MemoryStoreRef' description: | - Replacement list of attached team memory stores. Omit to leave unchanged, - pass an empty array to clear, or pass a non-empty array to replace. - AgentAutoMemoryResponse: + The judge's reasoning, truncated beyond 8KB when it was recorded; + absent unless status is "available". + ListScorerResultReasonsResponse: type: object - description: Auto-memory state for an agent. required: - - enabled + - reasons properties: - enabled: - type: boolean - description: Whether this agent has an agent-owned memory store. - store: - $ref: '#/components/schemas/MemoryStoreAttachmentResponse' - AgentMemoryResponse: + reasons: + type: array + items: + $ref: '#/components/schemas/ScorerResultReason' + SelfImprovementConfigResponse: type: object - description: Memory settings for an agent. required: - - auto_memory - - attached_stores + - scorer_id + - status + - created_at + - updated_at properties: - auto_memory: - $ref: '#/components/schemas/AgentAutoMemoryResponse' - attached_stores: - type: array - items: - $ref: '#/components/schemas/MemoryStoreRef' - description: Team memory stores attached to the agent. - AgentCredentialStrategy: - type: string - description: | - Default credential strategy for runs executed by a named agent. - - EXECUTOR: runs authenticate with the named agent's own credentials - (e.g. a GitHub App installation token for the agent's team). - - CREATOR: runs authenticate with the credentials of the principal - that created the run. - Unlike the factory default, an agent may leave this unset. The - strategy applied to a run is resolved in this order: the run's - config.credential_strategy, then the agent's default, then the - factory's default for factory-seeded agents, and finally EXECUTOR. - The inherited strategy is validated at run creation time (the required - credential must be mintable), like an explicit run-level value. - enum: - - CREATOR - - EXECUTOR + scorer_id: + type: integer + description: Identifier of the scorer this self-improvement config belongs to + status: + type: string + enum: + - active + - paused + description: Self-improvement config lifecycle status (active means self-improvement is enabled) + created_at: + type: string + format: date-time + description: When the self-improvement config was created + updated_at: + type: string + format: date-time + description: When the self-improvement config was last updated ReportedRunScore: type: object required: @@ -4030,19 +6121,19 @@ components: type: string nullable: true description: | - Optional default worker host for runs executed by this agent. - Omission, null, or an empty value stores no Agent default, in which - case the workspace default applies. A non-empty value is trimmed - and stored; use "warp" to force Warp-hosted execution over a - self-hosted workspace default. The precedence order for worker - host resolution is: + Optional default worker host for runs executed by this agent; + omission, null, or an empty value stores no Agent default, in + which case the workspace default applies. A non-empty value is + trimmed and stored (use "warp" to force Warp-hosted execution + over a self-hosted workspace default), and is resolved in this + order: 1. The host specified on the run itself 2. The agent's default host 3. The workspace default host UpdateAgentRequest: type: object description: | - Partial update for an agent. Each field is optional: + Partial update for an agent; each field is optional: * Omitted or `null`: leave the field unchanged. * Empty value: clear the field. * Non-empty: replace the field wholesale with the provided value. @@ -4116,20 +6207,20 @@ components: - $ref: '#/components/schemas/InferenceProvidersConfig' nullable: true description: | - Replacement inference provider settings for this agent. - Agent-level config takes precedence over the workspace's - admin-configured defaults. Omit or pass `null` to leave - unchanged. Pass an empty object `{}` to clear. + Replacement inference provider settings for this agent, which + take precedence over the workspace's admin-configured defaults; + omit or pass `null` to leave unchanged, or pass an empty object + `{}` to clear. base_harness: type: string nullable: true deprecated: true description: | - Replacement default harness. Omit or pass `null` to leave unchanged, - or pass an empty string to clear. - Deprecated - use harness instead. Kept for backward compatibility; - when both are sent, harness is authoritative and a conflicting - type is rejected with invalid_request. + Replacement default harness; omit or pass `null` to leave + unchanged, or pass an empty string to clear. Deprecated - use + harness instead, kept only for backward compatibility: when both + are sent, harness is authoritative and a conflicting type is + rejected with invalid_request. harness: allOf: - $ref: '#/components/schemas/Harness' @@ -4203,16 +6294,18 @@ components: environment_id: type: string description: | - Default cloud environment ID for runs executed by this agent. The precedence order for environment resolution is: + Default cloud environment ID for runs executed by this agent; + the precedence order for environment resolution is: 1. The environment specified on the run itself 2. The agent's default environment 3. An empty environment default_runner_uid: type: string description: | - Default runner UID for runs executed by this agent. When set, it overrides the - selected environment's default runner for runs that do not specify their own - `runner_id`. The precedence order for runner resolution is: + Default runner UID for runs executed by this agent; when set, + it overrides the selected environment's default runner for + runs that do not specify their own `runner_id`. The precedence + order for runner resolution is: 1. The runner specified on the run itself 2. The agent's default runner 3. The selected environment's default runner @@ -4220,7 +6313,7 @@ components: 5. System defaults available: type: boolean - description: Whether this agent is within the team's plan limit and can be used for runs + description: Whether the agent is currently enabled. Defaults to true. created_at: type: string format: date-time @@ -4245,7 +6338,8 @@ components: base_model: type: string description: | - Base model for runs executed by this agent. The precedence order for model resolution is: + Base model for runs executed by this agent; the precedence + order for model resolution is: 1. The model specified on the run itself 2. The agent's base model 3. The team's default model @@ -4273,11 +6367,12 @@ components: type: string deprecated: true description: | - Default harness for runs executed by this agent. The precedence order for harness resolution is: + Default harness for runs executed by this agent; the + precedence order for harness resolution is: 1. The harness specified on the run itself 2. The agent's base harness - 3. Oz - Deprecated - use harness instead, which carries the full + 3. Warp + Deprecated: use harness instead, which carries the full {type, model_id, reasoning_level} default. harness: allOf: @@ -4298,6 +6393,8 @@ components: 2. The agent's default strategy 3. The factory's default strategy, for factory-seeded agents 4. EXECUTOR + The resolved strategy is credential-validated at run creation; + an unavailable credential rejects the request before execution. harness_auth_secrets: allOf: - $ref: '#/components/schemas/HarnessAuthSecrets' @@ -4313,8 +6410,8 @@ components: worker_host: type: string description: | - Default worker host for runs executed by this agent, or empty when - unset. The precedence order for worker host resolution is: + Default worker host for runs executed by this agent, or empty + when unset; the precedence order for worker host resolution is: 1. The host specified on the run itself 2. The agent's default host 3. The workspace default host diff --git a/src/content/docs/factories/factory-api.mdx b/src/content/docs/factories/factory-api.mdx index 141f3b200..da3db4122 100644 --- a/src/content/docs/factories/factory-api.mdx +++ b/src/content/docs/factories/factory-api.mdx @@ -14,13 +14,13 @@ Use the factory API to find a factory and start work from a custom integration w Warp Factories is in **Early Access** and available to a limited set of teams. [Request access](https://www.warp.dev/factories/request-access) to use it with your team. ::: -## How it works +## Endpoints * `GET /factory` - list factories your account can access. Add `search` to filter by name or alias, case-insensitive. * `GET /factory/{uid}` - get one factory by UID. * `POST /factory/{uid}/runs` - dispatch a run to the factory's foreman agent. Pass a `prompt`; the server resolves the foreman for you. -A dispatched run is an ordinary [cloud agent run](/platform/): retrieve it, send it follow-ups, or cancel it through the same [Agent API](/reference/api-and-sdk/) you'd use for any run. +The interactive [Agent API reference](/api) documents each endpoint's parameters and schemas. A dispatched run is an ordinary [cloud agent run](/platform/): retrieve it, send it follow-ups, or cancel it through the same [Agent API](/reference/api-and-sdk/) you'd use for any run. ## When to use the factory API vs the Agent API @@ -50,7 +50,7 @@ client = OzAPI(api_key=os.environ.get("WARP_API_KEY")) page = client.factories.list(search="payments") factory = page.factories[0] -# With the pagination scheme wired, iteration auto-pages +# Iteration fetches additional pages automatically for f in client.factories.list(search="payments"): print(f.uid, f.name) ``` diff --git a/src/content/docs/factories/index.mdx b/src/content/docs/factories/index.mdx index 037f81ba3..03dbaf8d3 100644 --- a/src/content/docs/factories/index.mdx +++ b/src/content/docs/factories/index.mdx @@ -37,7 +37,7 @@ Warp Factories is designed for engineering teams with repeatable work that exten * **Coordinated specialist agents** - A team of [factory agents](/factories/factory-agents/) handles each work item. A coordinating foreman routes it through the triage, spec, implement, and review agents, skipping stages that don't apply. You can add custom agents and automations to handle work the defaults don't cover. * **Definitions as code** - [Version-controlled definition files](/factories/factory-as-code/) describe your repositories, agents, automations, runners, skills, and MCP servers, so factory changes get the same review, history, and rollback as code changes. -* **Integrations and the Factory MCP** - Work flows in from [Slack](/factories/integrations/slack/), [GitHub](/factories/integrations/github/), [GitLab](/factories/integrations/gitlab/), [Linear](/factories/integrations/linear/), and [Jira](/factories/integrations/jira/), plus direct runs and schedules. The [Factory MCP](/factories/factory-mcp/) connects coding agents and other MCP clients. +* **Integrations, the factory API, and Factory MCP** - Work flows in from [Slack](/factories/integrations/slack/), [GitHub](/factories/integrations/github/), [GitLab](/factories/integrations/gitlab/), [Linear](/factories/integrations/linear/), and [Jira](/factories/integrations/jira/), plus direct runs and schedules. The [factory API](/factories/factory-api/) dispatches work from your own integrations and scripts, and the [Factory MCP](/factories/factory-mcp/) connects coding agents and other MCP clients. * **Model and harness choice** - Each agent can use a different model and [supported harness](/platform/harnesses/), including the Warp Agent, Claude Code, and Codex. * **Measurement and self-improvement** - The [factory dashboard](/factories/factory-dashboard/) shows work-item status, runs, automations, costs, and benchmarks. [Scorers](/factories/measure-and-improve/) grade completed work, and [Self-improvement](/factories/measure-and-improve/#configure-and-review-self-improvement) turns repeated failures into follow-up work the factory proposes for review. * **Infrastructure control** - Run on Warp-hosted infrastructure, or self-host execution on an eligible Enterprise plan. Teams can also connect supported inference providers, scope secrets, and (if eligible) store transcripts, artifacts, and run attachments in their own S3 or GCS buckets. See [infrastructure and security](/factories/infrastructure-and-security/) for the available controls. diff --git a/src/content/docs/reference/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx b/src/content/docs/reference/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx index 3bdfd4c2f..f4d4af178 100644 --- a/src/content/docs/reference/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx +++ b/src/content/docs/reference/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx @@ -7,22 +7,20 @@ description: >- import VideoEmbed from '@components/VideoEmbed.astro'; import { VARS } from '@data/vars'; -### Turn production errors into draft PRs with Cloud Agents + TypeScript SDK +Turn production errors into draft pull requests: this demo builds a small TypeScript "Sentry monitor" service that listens for specific Sentry alerts, such as a Go nil pointer dereference, and triggers a Warp cloud agent to investigate. The service validates the webhook, extracts the stack trace, and injects it into an agent run inside a [cloud environment](/platform/environments/) so the agent can inspect the repo and propose a fix. The full source is in the [Sentry monitor example repository](https://github.com/warpdotdev/warp-agents-sdk-demo-sentry-monitor). -:::note -Example repository: [**Sentry monitor example repository**](https://github.com/warpdotdev/warp-agents-sdk-demo-sentry-monitor) -::: +## What the demo covers -In this demo, Ben builds a small TypeScript “Sentry monitor” service that listens for specific Sentry alerts (like a Go nil pointer dereference) and triggers a Warp cloud agent to investigate. The server validates the webhook, extracts the stack trace, and injects it into an agent run inside a Warp Environment so the agent can inspect the repo and propose a fix. - -He also covers the task lifecycle basics in the TypeScript SDK (running an agent, polling task state to fetch a session link for debugging), and shows the end result: a draft GitHub pull request created from the Sentry event for a maintainer to review. +* Using the [TypeScript SDK](https://github.com/warpdotdev/oz-sdk-typescript) to trigger agent runs and retrieve run details. +* Handling run lifecycle states (queued → running) to reliably fetch a session link for debugging. +* Running agents inside a cloud environment so they can investigate real code, run tests, and validate fixes. +* Building a lightweight Sentry webhook server that filters, validates, and routes only the right errors to an agent. +* Ending the workflow in a draft GitHub pull request for a maintainer to review, instead of silent autonomous changes. -**What Ben covers** +## Related pages -* Using Warp's TypeScript SDK to trigger agent runs and retrieve run details. -* Handling run lifecycle states (queued → running) to reliably fetch a session link. -* Running agents inside a Warp Environment so they can investigate real code, run tests, and validate fixes. -* Building a lightweight Sentry webhook server that filters, validates, and routes only the right errors to an agent. -* Creating a workflow that results in draft PRs for human review, instead of silent autonomous changes. +* [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) - The API surface and SDKs the demo builds on. +* [API & SDK quickstart](/reference/api-and-sdk/quickstart/) - Create and monitor your first run in about five minutes. +* [Cloud agents quickstart](/platform/quickstart/) - Set up the environment an agent run executes in. diff --git a/src/content/docs/reference/api-and-sdk/index.mdx b/src/content/docs/reference/api-and-sdk/index.mdx index e8929bf10..5cc5898c5 100644 --- a/src/content/docs/reference/api-and-sdk/index.mdx +++ b/src/content/docs/reference/api-and-sdk/index.mdx @@ -9,153 +9,70 @@ description: >- import VideoEmbed from '@components/VideoEmbed.astro'; import { VARS } from '@data/vars'; -The {VARS.API_SDK_NAME} lets you create, monitor, and inspect cloud agent runs programmatically. Use the REST API from any HTTP client, or the official Python and TypeScript SDKs for typed requests, built-in retries, and structured error handling. The SDKs are ideal for CI pipelines, internal tools, and custom integrations. +The {VARS.API_SDK_NAME} lets you create, monitor, and inspect [cloud agent](/platform/) runs from any system that can make HTTP requests — CI pipelines, cron jobs, backend services, and internal tools — without the Warp desktop app. Call the REST API from any HTTP client, or use the official [Python](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript](https://github.com/warpdotdev/oz-sdk-typescript) SDKs for typed requests, built-in retries, and structured error handling. -### API overview +For every endpoint's parameters, schemas, and error responses, see the interactive [Agent API reference](/api). To make your first request, start with the [API & SDK quickstart](/reference/api-and-sdk/quickstart/). -The {VARS.API_SDK_NAME} lets you create and inspect [Cloud Agent](/platform/) runs over HTTP from any system (CI, cron, backend services, internal tools), without requiring the Warp desktop app. +With the API you can: -**With the API you can:** +* **Run agents** - Submit a prompt plus optional configuration: model, environment, MCP servers, and base prompt. +* **Monitor execution** - List runs and track state transitions (queued → in progress → succeeded or failed). +* **Inspect results** - Fetch a run's full details, including the original prompt, creator metadata, session link, and resolved configuration. -* Run an agent by submitting a prompt plus optional config (model, environment, MCP servers, base prompt, etc.) -* Monitor execution by listing runs and tracking state transitions over time (queued → in progress → succeeded/failed) -* Inspect results and provenance by fetching a run's full details, including the original prompt, source/creator metadata, session link, and resolved agent configuration - -:::caution -This page is a high-level overview.\ -\ -For full API endpoint details, refer to the [**Agents API Reference**](/api). For schema definitions, see the SDK repos: [**Python SDK**](https://github.com/warpdotdev/oz-sdk-python) and [**TypeScript SDK**](https://github.com/warpdotdev/oz-sdk-typescript). -::: - -To send work to a [Warp factory](/factories/), use the [factory API](/factories/factory-api/) to discover it and dispatch by UID instead of calling `POST /agent/run` with a foreman's `agent_identity_uid`. Everything on this page - follow-ups, cancellation, status - still applies once a factory run is dispatched. - -### SDK overview - -Warp provides official [Python](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript](https://github.com/warpdotdev/oz-sdk-typescript) SDKs that wrap the {VARS.API_SDK_NAME} with: - -* **Typed requests and responses** (editor autocomplete, fewer schema mistakes) -* **Built-in retries and timeouts** (with per-request overrides) -* [**Consistent error types**](/reference/api-and-sdk/troubleshooting/errors/) that map to API status codes -* **Helpers for raw responses** when you need headers/status or custom parsing - -If you’re building an integration (CI, Slack bots, internal tooling, orchestrators), the SDKs are typically the quickest and safest starting point. +To send work to a [Warp factory](/factories/), use the [factory API](/factories/factory-api/) to discover the factory and dispatch by UID instead of calling `POST /agent/run` with a foreman's `agent_identity_uid`. A dispatched factory run is still an ordinary run, so everything on this page — follow-ups, cancellation, status — applies to it. -**SDK vs raw REST** - -* Use the SDK when you want strong typing, standardized error handling, and easy concurrency patterns. -* Use raw REST when you want minimal dependencies or full control over your HTTP client (the SDKs also support calling undocumented endpoints when needed). +## REST API -:::caution -For the full SDK surface area and latest usage, refer to the GitHub repos: [**Python SDK**](https://github.com/warpdotdev/oz-sdk-python) and [**TypeScript SDK**](https://github.com/warpdotdev/oz-sdk-typescript). -::: - ---- - -## API reference - -### REST API base URL - -All endpoints are served over HTTPS: +All endpoints are served over HTTPS from this base URL, and authenticated with a [Warp API key](/reference/cli/api-keys/) passed as a bearer token: ```http https://app.warp.dev/api/v1 ``` -### Core concepts - -#### **Agent runs** +### Agent runs -An agent run represents a single execution of a cloud agent, created with a prompt and optional configuration. Each run has: +An agent run is a single execution of a cloud agent, created from a prompt and optional configuration. Each run has: -* A unique `run_id` -* A human-readable `title` -* A `prompt` that the agent executes +* A unique `run_id` and a human-readable `title` +* The `prompt` the agent executes * A `state` (for example `QUEUED`, `INPROGRESS`, `SUCCEEDED`, `FAILED`) * Timestamps (`created_at`, `updated_at`) -* Optional session information (`session_id`, `session_link`) -* Optional resolved configuration (`agent_config`) +* Optional session information (`session_id`, `session_link`) and resolved configuration (`agent_config`) -See the [**Agents API Reference**](/api) for details on how runs are created and listed. +### Agent configuration -#### **Agent configuration** +Shape how an agent runs with the `AmbientAgentConfig` object. The most commonly set fields: -You can influence how an agent runs using AmbientAgentConfig, including: - -* `name` — a human-readable label for grouping, filtering, and traceability. When you run an agent from a [skill](/agents/capabilities/skills/), `name` is automatically set to the skill name. You can also set `name` explicitly via the API, SDK, or CLI (`--name`) to categorize runs by intent — for example, grouping all runs of a particular workflow regardless of how they were triggered. Use the `name` query parameter on `GET /agent/runs` to filter runs by config name. -* `model_id` for LLM selection -* `base_prompt` to shape behavior -* `environment_id` to choose a `CloudEnvironment` -* `skill_spec` to use a [skill](/agents/capabilities/skills/) as the base prompt (format: `owner/repo:skill-name` or `owner/repo:path/to/SKILL.md`) -* `mcp_servers` to enable specific tools via MCP - -See the [**Python SDK**](https://github.com/warpdotdev/oz-sdk-python) or [**TypeScript SDK**](https://github.com/warpdotdev/oz-sdk-typescript) for the full configuration schema. - ---- +* `name` - A label for grouping, filtering, and traceability. When you run an agent from a [skill](/agents/capabilities/skills/), `name` is set to the skill name automatically; set it explicitly (via the API, SDK, or `--name` on the CLI) to categorize runs by intent, and filter with the `name` query parameter on `GET /agent/runs`. +* `model_id` - The LLM the run uses. +* `base_prompt` - Standing instructions that shape the agent's behavior. +* `environment_id` - The [cloud environment](/platform/environments/) the run executes in. +* `skill_spec` - A [skill](/agents/capabilities/skills/) to use as the base prompt (format: `owner/repo:skill-name` or `owner/repo:path/to/SKILL.md`). +* `mcp_servers` - MCP servers that give the run specific tools. ### Key endpoints -**The Agents API exposes these primary endpoints:** +* `POST /agent/run` - Create a run from a prompt and optional config and title. Returns `run_id` and the initial state. +* `GET /agent/runs` - List runs, with pagination and filters for state, config name, model, creator, source, and creation time. +* `GET /agent/runs/{runId}` - Fetch one run's full details, including its session link and resolved configuration. +* `POST /agent/runs/{runId}/followups` - Send a follow-up message to steer or continue a run — the same capability the Slack and Linear integrations use. +* `POST /agent/runs/{runId}/cancel` - Cancel a queued or in-progress run. -* `POST /agent/run` - - Create a new agent run with a prompt and optional config and title. Returns run\_id and initial state. -* `GET /agent/runs` - - List runs with pagination and filters for state, config\_name, model\_id, creator, source, and creation time. -* `GET /agent/runs/{runId}` - - Fetch full details for a single run, including session link and resolved configuration. -* `POST /agent/runs/{runId}/followups` - - Send a follow-up message to an existing run to steer or continue it, the same capability the Slack and Linear integrations use. -* `POST /agent/runs/{runId}/cancel` - - Cancel a run that is currently queued or in progress. Returns the ID of the cancelled run. - -All endpoint semantics, query parameters, and [error codes](/reference/api-and-sdk/troubleshooting/errors/) are documented on the [Agents API Reference](/api). - ---- - -#### Models reference - -The API shares a set of reusable models across endpoints. Detailed JSON schemas, types, and enums are available in the SDK repos ([Python](https://github.com/warpdotdev/oz-sdk-python), [TypeScript](https://github.com/warpdotdev/oz-sdk-typescript)). Key models include: - -* `RunAgentRequest` -* `RunAgentResponse` -* `ListRunsResponse` -* `RunItem` -* `PageInfo` -* `RunStatusMessage` -* `RunCreatorInfo` -* `RunState` -* `RunSourceType` -* `RunFollowupRequest` -* `AmbientAgentConfig` -* `MCPServerConfig` -* `Error` - ---- +The [Agent API reference](/api) documents all endpoint semantics, query parameters, and [error codes](/reference/api-and-sdk/troubleshooting/errors/) — including the factory and scorer endpoints and shared models such as `RunAgentRequest`, `RunItem`, `AmbientAgentConfig`, and `Error`. ## SDKs -### Python SDK - -The Python SDK is the recommended way to call the API from Python services and scripts. It provides: - -* Sync + async clients -* Typed request/response models -* Configurable retries/timeouts and structured errors - -See the [**Python SDK GitHub repo**](https://github.com/warpdotdev/oz-sdk-python) for installation, full API reference (api.md), and up-to-date examples. - -### TypeScript SDK +The SDKs wrap the same API with typed request and response models, configurable retries and timeouts, [consistent error types](/reference/api-and-sdk/troubleshooting/errors/) that map to API status codes, and helpers for reading raw responses. Use an SDK when you want strong typing and standardized error handling; use raw REST when you want minimal dependencies or full control over your HTTP client. -The TypeScript SDK is the recommended way to call the API from Node.js services and modern TS/JS runtimes. It provides: +* **[Python SDK](https://github.com/warpdotdev/oz-sdk-python)** - Sync and async clients for Python services and scripts. The repo covers installation, the full API surface (`api.md`), and current examples. +* **[TypeScript SDK](https://github.com/warpdotdev/oz-sdk-typescript)** - Fully typed client for Node.js and other runtimes where `fetch` is available. The repo covers installation, the full API surface (`api.md`), and current examples. -* Fully typed params/responses -* First-class error handling, retries/timeouts -* Support across common runtimes where fetch is available or polyfilled +## Related pages -See the [**TypeScript SDK GitHub repo**](https://github.com/warpdotdev/oz-sdk-typescript) for installation, full API reference (api.md), and up-to-date examples. +* [Agent API reference](/api) - Interactive reference for every endpoint, parameter, and schema. +* [Use the factory API](/factories/factory-api/) - Discover a factory and dispatch work to it by UID. +* [API error reference](/reference/api-and-sdk/troubleshooting/errors/) - Error codes, response format, and resolution steps. +* [API keys](/reference/cli/api-keys/) - Create and manage the keys that authenticate API requests. +* [Demo: Sentry monitoring with SDK](/reference/api-and-sdk/demo-sentry-monitoring-with-sdk/) - A webhook handler that triggers agents from production errors. diff --git a/src/content/docs/reference/api-and-sdk/quickstart.mdx b/src/content/docs/reference/api-and-sdk/quickstart.mdx index 00107985e..ad8a1dfa2 100644 --- a/src/content/docs/reference/api-and-sdk/quickstart.mdx +++ b/src/content/docs/reference/api-and-sdk/quickstart.mdx @@ -1,31 +1,27 @@ --- title: "API & SDK quickstart" description: >- - Create and monitor your first cloud agent run via the {{API_SDK_NAME}} in ~5 - minutes. + Create and monitor your first cloud agent run with the {{API_SDK_NAME}} in + about five minutes. sidebar: label: "Quickstart" --- import VideoEmbed from '@components/VideoEmbed.astro'; import { VARS } from '@data/vars'; -The {VARS.API_SDK_NAME} lets you run and manage cloud agents from anywhere — CI/CD pipelines, backend services, scripts, or custom tooling — without the Warp desktop app. This quickstart walks you through creating your first run and checking its status. +The {VARS.API_SDK_NAME} lets you run and manage cloud agents from anywhere — CI pipelines, backend services, scripts, and custom tooling — without the Warp desktop app. Create your first run and check its status in about five minutes. Watch this short demo of how the REST API can power agent-backed apps like [PowerFixer](https://github.com/warpdotdev/power-fixer-setup), an issue triage bot built by the Warp team: ---- - ## Prerequisites * **A Warp API key** - Create one in the {VARS.WEB_APP} and copy the raw value. Use a personal key if you want runs attributed to you, or an agent key to attribute runs to a [cloud agent](/platform/agents/). See [API Keys](/reference/cli/api-keys/) for the full flow. -* **A cloud environment** - Agents run inside a configured environment that includes repos and other dependencies. If you don't have an environment yet, follow the [Cloud Agents Quickstart](/platform/quickstart/) first. - ---- +* **A cloud environment** - Agents run inside a configured environment that includes repos and other dependencies. If you don't have an environment yet, follow the [Cloud agents quickstart](/platform/quickstart/) first. ## 1. Set your API key -Export your API key so the API can authenticate your requests automatically — all commands in this guide reference the `WARP_API_KEY` environment variable. +Export your API key so the commands in this guide can authenticate; they all read the `WARP_API_KEY` environment variable. ```bash export WARP_API_KEY="wk-..." @@ -55,7 +51,7 @@ Replace `` with your environment ID. Find it with `oz environment list` Prefer typed requests? The official [Python SDK](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript SDK](https://github.com/warpdotdev/oz-sdk-typescript) wrap the same API with typed models, retries, and error handling. ::: -The API returns a `run_id` immediately. The agent starts asynchronously — you can check its status at any time using the run ID. +The API returns a `run_id` immediately. The agent starts asynchronously; check its status at any time using the run ID. ## 3. Check run status @@ -73,7 +69,7 @@ The `state` has the following possible values: * `SUCCEEDED` - The run completed successfully. * `FAILED` - The run encountered an error. Check the `status_message` field in the response for details, then use the [API error reference](/reference/api-and-sdk/troubleshooting/errors/) to interpret the error code. -These are the most common states. See the [full API reference](/reference/api-and-sdk/) for all possible values. +These are the most common states. See the [Agent API reference](/api) for all possible values. To list all recent runs: @@ -84,15 +80,14 @@ curl "https://app.warp.dev/api/v1/agent/runs" \ ## 4. View the results -Once the run reaches `SUCCEEDED`, the response includes a `session_link` — a direct URL to the full run transcript, including commands executed, files changed, and agent output. +Once the run reaches `SUCCEEDED`, the response includes a `session_link`: a direct URL to the full run transcript, including commands executed, files changed, and agent output. You can also view and manage all runs in the {VARS.DASHBOARD}. ---- - ## Next steps -* **Read the full API reference** - [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) documents all endpoint parameters, query filters, and response schemas. -* **Explore the SDKs** - [Python SDK](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript SDK](https://github.com/warpdotdev/oz-sdk-typescript) include typed request/response models, retries, and error handling. -* **See a real-world example** - [Demo: Sentry monitoring with SDK](/reference/api-and-sdk/demo-sentry-monitoring-with-sdk/) shows how to build a webhook handler that triggers agents from production errors. -* **Schedule and automate** - See [Scheduled Agents Quickstart](/platform/triggers/scheduled-agents-quickstart/) to run agents on a cron, or [Integrations Quickstart](/platform/integrations/quickstart/) to trigger agents from Slack or Linear. +You created a cloud agent run over HTTP and tracked it from `QUEUED` to `SUCCEEDED`. From here: + +* **Read the full reference** - The [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) page maps the API surface and SDKs, and the [Agent API reference](/api) documents every endpoint parameter and schema. +* **See a real-world example** - [Demo: Sentry monitoring with SDK](/reference/api-and-sdk/demo-sentry-monitoring-with-sdk/) builds a webhook handler that triggers agents from production errors. +* **Schedule and automate** - Run agents on a cron with the [Scheduled Agents quickstart](/platform/triggers/scheduled-agents-quickstart/), or trigger them from Slack or Linear with the [Integrations quickstart](/platform/integrations/quickstart/). diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/index.mdx b/src/content/docs/reference/api-and-sdk/troubleshooting/errors/index.mdx index af4046131..9a58e8975 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/index.mdx +++ b/src/content/docs/reference/api-and-sdk/troubleshooting/errors/index.mdx @@ -1,5 +1,5 @@ --- -title: Errors Overview +title: Errors overview description: >- Reference for all error codes returned by the {{API_SDK_NAME}}. Each error includes an HTTP status, machine-readable code, and actionable resolution @@ -9,8 +9,6 @@ import { VARS } from '@data/vars'; When the {VARS.API_SDK_NAME} encounters an error, it returns a structured JSON response following [RFC 7807 (Problem Details for HTTP APIs)](https://datatracker.ietf.org/doc/html/rfc7807). Every error response includes a machine-readable error code, a human-readable message, and metadata to help you diagnose and resolve the issue. ---- - ## Response format All error responses share this structure: @@ -43,8 +41,6 @@ Error responses use the `application/problem+json` content type per RFC 7807. Some errors include additional metadata fields (for example, `auth_url`, `provider`, or `inaccessible_repos`). These are documented on each error's page. ---- - ## Error categories Errors are split into two categories based on what caused the failure: @@ -77,15 +73,11 @@ These indicate a Warp-side issue. When a cloud agent task encounters a platform * [`infrastructure_timeout`](/reference/api-and-sdk/troubleshooting/errors/infrastructure-timeout/) — Task terminated after exceeding the maximum allowed runtime * [`agent_process_failed`](/reference/api-and-sdk/troubleshooting/errors/agent-process-failed/) — Agent process exited unexpectedly during task execution ---- - ## Using the `trace_id` When an error response includes a `trace_id`, you can include it when [contacting Warp support](/support-and-community/troubleshooting-and-support/sending-us-feedback/) to help the team locate the specific request in internal logs. This is especially useful for `internal_error` and `resource_unavailable` errors. ---- - -## Related +## Related pages * [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) — API reference for creating and managing agent tasks * [Cloud Agents Overview](/platform/) — How cloud agents work diff --git a/src/content/docs/reference/index.mdx b/src/content/docs/reference/index.mdx index 59996046e..6f5514340 100644 --- a/src/content/docs/reference/index.mdx +++ b/src/content/docs/reference/index.mdx @@ -1,26 +1,38 @@ --- title: Technical reference description: >- - Technical reference documentation for the {{WARP_AGENT_CLI}}, API, and SDK. + Look up the Agent API, the factory API, the Python and TypeScript SDKs, and + the CLIs for running Warp agents from code. --- import { VARS } from '@data/vars'; -Technical reference documentation for the {VARS.WARP_AGENT_CLI}, API, and SDKs. Use these programmatic interfaces to run and manage agents from CI pipelines, scripts, backend services, and custom tooling without requiring the Warp desktop app. +Look up the programmatic interfaces for running and managing agents from CI pipelines, scripts, backend services, and custom tooling, without the Warp desktop app. + +## API & SDK + +The [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) lets you create, monitor, and steer cloud agent runs over HTTP. Official SDKs for [Python](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript](https://github.com/warpdotdev/oz-sdk-typescript) provide typed clients with built-in retries and error handling. + +- [Agent API reference](/api) - Interactive reference for every endpoint, parameter, and schema. +- [API & SDK quickstart](/reference/api-and-sdk/quickstart/) - Create and monitor your first run in about five minutes. +- [API keys](/reference/cli/api-keys/) - Create and manage the keys that authenticate API and CLI requests without human interaction. +- [API error reference](/reference/api-and-sdk/troubleshooting/errors/) - Error codes, response format, and resolution steps. +- [Demo: Sentry monitoring with SDK](/reference/api-and-sdk/demo-sentry-monitoring-with-sdk/) - A webhook handler that triggers agents from production errors. + +To work with a [Warp factory](/factories/) from your own code, use the [factory API](/factories/factory-api/) to discover a factory and dispatch work to it by UID, or connect an MCP-capable coding agent through [Factory MCP](/factories/factory-mcp/). Both are documented with the rest of the Warp Factories docs. ## CLI -The [{VARS.WARP_AGENT_CLI}](/reference/cli/) lets you run and configure agents from any environment — locally, in CI pipelines, or on remote machines. +Two command-line tools run agents, depending on where the work happens: + +- **[{VARS.WARP_CLI}](/agents/cli/)** - Runs the Warp Agent interactively in any terminal, including over SSH and in the Warp app. Documented on the Agents tab. +- **[{VARS.WARP_AGENT_CLI}](/reference/cli/)** - Runs and manages cloud agents from scripts, CI, and automated systems with the `oz` binary. It is being deprecated in favor of the {VARS.WARP_CLI}. -- [API Keys](/reference/cli/api-keys/) - Create and manage API keys to authenticate the {VARS.WARP_AGENT_CLI} without human interaction, ideal for CI pipelines, headless servers, and containers. -- [Agent Profiles](/reference/cli/agent-profiles/) - Use agent profiles to control what the agent can access, how it behaves, and where it can act, including file access, command execution, and MCP server usage. +The {VARS.WARP_AGENT_CLI} pages cover its full surface: + +- [API Keys](/reference/cli/api-keys/) - Authenticate the CLI without human interaction in CI pipelines, headless servers, and containers. +- [Agent Profiles](/reference/cli/agent-profiles/) - Control what the agent can access, how it behaves, and where it can act, including file access, command execution, and MCP server usage. - [MCP Servers](/reference/cli/mcp-servers/) - Pass MCP server configuration to agent runs using the `--mcp` flag, by UUID, inline JSON, or file path. - [Skills](/reference/cli/skills/) - Run agents from reusable instruction sets stored in your repositories using the `--skill` flag. - [Warp Drive Context](/reference/cli/warp-drive/) - Reference saved prompts, notebooks, workflows, and rules from Warp Drive directly in CLI agent commands. - [Integration Setup](/reference/cli/integration-setup/) - Configure environments and connect external tools like Slack and Linear so you can trigger agents from outside the terminal. - [Troubleshooting](/reference/cli/troubleshooting/) - Find solutions to common CLI errors, including authentication issues, agent failures, environment problems, and Docker image issues. - -## API & SDK - -The [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) lets you create and monitor cloud agent runs over HTTP. Official SDKs for [Python](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript](https://github.com/warpdotdev/oz-sdk-typescript) provide typed clients with built-in retries and error handling. - -- [Demo: Sentry monitoring with SDK](/reference/api-and-sdk/demo-sentry-monitoring-with-sdk/) - example integration