From 35523de95abc920dcbacfb2dc469253ae875cd31 Mon Sep 17 00:00:00 2001 From: David Stern Date: Thu, 15 Oct 2026 12:48:23 -0400 Subject: [PATCH 1/2] docs: support OpenAPI tag hierarchy Co-Authored-By: Warp --- .../sync-openapi-spec/scripts/sync_openapi.py | 74 +- astro.config.mjs | 4 +- developers/agent-api-openapi.yaml | 8114 +++++++++-------- src/pages/api.astro | 2 +- 4 files changed, 4209 insertions(+), 3985 deletions(-) diff --git a/.agents/skills/sync-openapi-spec/scripts/sync_openapi.py b/.agents/skills/sync-openapi-spec/scripts/sync_openapi.py index deb1170fd..8d637f0a9 100644 --- a/.agents/skills/sync-openapi-spec/scripts/sync_openapi.py +++ b/.agents/skills/sync-openapi-spec/scripts/sync_openapi.py @@ -465,13 +465,11 @@ def transform(source: dict[str, Any]) -> dict[str, Any]: out["info"] = {**out["info"], **DOCS_INFO_OVERRIDES} src_tags = source.get("tags") or [] - out_tags = [ + candidate_tags = [ t for t in src_tags if isinstance(t, dict) and t.get("name") not in EXCLUDED_TAGS ] - if out_tags: - out["tags"] = out_tags src_paths = source.get("paths") or {} kept_paths = { @@ -479,6 +477,34 @@ def transform(source: dict[str, Any]) -> dict[str, Any]: for path, item in src_paths.items() if isinstance(item, dict) and _should_keep_path(path, item) } + + tag_by_name = { + tag["name"]: tag + for tag in candidate_tags + if isinstance(tag.get("name"), str) + } + kept_tag_names = { + tag + for path_item in kept_paths.values() + for tag in _path_tags(path_item) + } + pending_parents = list(kept_tag_names) + while pending_parents: + tag_name = pending_parents.pop() + tag = tag_by_name.get(tag_name) + parent = tag.get("parent") if tag else None + if ( + isinstance(parent, str) + and parent in tag_by_name + and parent not in kept_tag_names + ): + kept_tag_names.add(parent) + pending_parents.append(parent) + out_tags = [ + tag for tag in candidate_tags if tag.get("name") in kept_tag_names + ] + if out_tags: + out["tags"] = out_tags out["paths"] = kept_paths seed_refs: set[str] = set() @@ -584,11 +610,20 @@ 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`, `schedules`, - `factory`, and `networking` tags (kept) and `memory_stores`/`memory`/ - `harness-support` (dropped). Anything else needs human triage. + The skill's policy knows about the public agent and factory tag + hierarchies, plus `memory_stores`/`memory`/`harness-support` (dropped). + Anything else needs human triage. """ - KNOWN_TAGS = {"agent", "schedules", "factory", "networking"} | set(EXCLUDED_TAGS) + KNOWN_TAGS = { + "agent", + "schedules", + "factory", + "factory-notifications", + "factory-metrics", + "factory-scorers", + "factory-benchmarks", + "networking", + } | set(EXCLUDED_TAGS) notes: list[str] = [] for tag in source.get("tags") or []: @@ -618,10 +653,16 @@ def _unknown_classifications(source: dict[str, Any]) -> list[str]: def _self_test() -> int: """Sanity-check the transform on a small synthetic spec.""" sample = { - "openapi": "3.0.0", + "openapi": "3.2.0", "info": {"title": "t", "version": "1"}, "tags": [ - {"name": "agent"}, + {"name": "agent", "summary": "Agents"}, + { + "name": "schedules", + "summary": "Scheduled Agents", + "parent": "agent", + }, + {"name": "unused", "summary": "Unused"}, {"name": "memory_stores", "x-internal": True}, {"name": "harness-support"}, ], @@ -688,6 +729,13 @@ def _self_test() -> int: "responses": {"200": {"description": "ok"}}, } }, + "/schedules": { + "get": { + "tags": ["schedules"], + "operationId": "listSchedules", + "responses": {"200": {"description": "ok"}}, + } + }, }, "components": { "securitySchemes": {"bearerAuth": {"type": "http", "scheme": "bearer"}}, @@ -778,6 +826,7 @@ def _self_test() -> int: assert paths == { "/agent/run", "/agent/runs/{runId}/followups", + "/schedules", }, f"unexpected paths: {paths}" schemas = set(out["components"]["schemas"].keys()) @@ -810,8 +859,11 @@ def _self_test() -> int: assert "BENCHMARK_TRIAL" not in pruned["description"] assert "CUSTOM_WEBHOOK" not in pruned["description"] - tag_names = [t["name"] for t in out.get("tags") or []] - assert tag_names == ["agent"], f"unexpected tags: {tag_names}" + tags = {t["name"]: t for t in out.get("tags") or []} + assert set(tags) == {"agent", "schedules"}, f"unexpected tags: {set(tags)}" + assert tags["agent"]["summary"] == "Agents" + assert tags["schedules"]["summary"] == "Scheduled Agents" + assert tags["schedules"]["parent"] == "agent" assert out["components"].get("securitySchemes"), "securitySchemes should be preserved" assert out["info"]["title"] == "Warp Platform API" diff --git a/astro.config.mjs b/astro.config.mjs index f2a468a8c..b7a68f29b 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -200,12 +200,12 @@ export default defineConfig({ { label: 'Oz Agent API (OpenAPI spec, YAML)', url: 'https://docs.warp.dev/openapi.yaml', - description: 'Machine-readable OpenAPI 3.0 specification for the Oz Agent API.', + description: 'Machine-readable OpenAPI 3.2 specification for the Oz Agent API.', }, { label: 'Oz Agent API (OpenAPI spec, JSON)', url: 'https://docs.warp.dev/openapi.json', - description: 'Machine-readable OpenAPI 3.0 specification (JSON format) for the Oz Agent API.', + description: 'Machine-readable OpenAPI 3.2 specification (JSON format) for the Oz Agent API.', }, ], // Excludes pages that cause a stack overflow in hast-util-to-text diff --git a/developers/agent-api-openapi.yaml b/developers/agent-api-openapi.yaml index 97417a2fc..07bb4462c 100644 --- a/developers/agent-api-openapi.yaml +++ b/developers/agent-api-openapi.yaml @@ -1,32 +1,47 @@ -openapi: 3.0.0 +openapi: 3.2.0 info: title: Warp Platform API version: 1.0.0 description: | API for creating, managing, and querying factory and cloud agent runs. - Send work to factories, start standalone agents, list runs, and retrieve - detailed run information. + These endpoints allow users to send work to factories, start standalone agents, list runs, and retrieve detailed run information. contact: name: Warp Support - url: 'https://docs.warp.dev' + url: https://docs.warp.dev email: support@warp.dev license: name: Proprietary servers: - - url: 'https://app.warp.dev/api/v1' - description: Warp Server +- url: https://app.warp.dev/api/v1 + description: Warp Server tags: - - name: agent - description: Operations for running and managing cloud agents - - name: schedules - description: Operations for creating and managing scheduled agents - - name: factory - description: Operations for creating and managing factories - - name: benchmark - description: 'Operations for managing benchmark suites, tasks, runs, trials, and results' - - name: networking - description: Networking information for Warp-hosted agents +- name: agent + summary: Agents + description: Operations for running and managing cloud agents +- name: schedules + summary: Scheduled Agents + parent: agent + description: Operations for creating and managing scheduled agents +- name: factory + summary: Factories + description: Operations for creating and managing factories +- name: factory-metrics + summary: Metrics + parent: factory + description: Operations for querying factory cost and productivity metrics +- name: factory-scorers + summary: Scorers + parent: factory + description: Operations for creating and managing scorers +- name: factory-benchmarks + summary: Benchmarks + parent: factory + description: Operations for managing benchmark suites, tasks, runs, trials, and results +- name: networking + summary: Networking + parent: agent + description: Networking information for Warp-hosted agents paths: /networking/egress-ranges: get: @@ -36,11 +51,11 @@ paths: Warp-hosted agents. operationId: getEgressRanges tags: - - networking + - networking security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/TeamUidHeaderParam' + - $ref: '#/components/parameters/TeamUidHeaderParam' responses: '200': description: Current Warp-hosted agent egress ranges @@ -71,41 +86,41 @@ paths: case-insensitive substring match on the factory name or alias. operationId: listFactories tags: - - factory + - factory security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/TeamUidHeaderParam' - - name: team_uid - in: query - description: | - Optional team UID to filter factories by ownership. Takes - precedence over the X-Warp-Team-Uid header. - 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 + - $ref: '#/components/parameters/TeamUidHeaderParam' + - name: team_uid + in: query + description: | + Optional team UID to filter factories by ownership. Takes + precedence over the X-Warp-Team-Uid header. + 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 @@ -127,22 +142,22 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - '/factory/{uid}': + /factory/{uid}: get: summary: Get a factory description: Get a factory by its UID. operationId: getFactory tags: - - factory + - factory security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: uid - in: path - description: The public UID of the factory. - required: true - schema: - type: string + - name: uid + in: path + description: The public UID of the factory. + required: true + schema: + type: string responses: '200': description: Factory details @@ -170,199 +185,7 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - /factory-inbox: - get: - summary: List Factory inbox notifications - description: | - List unresolved notifications across factories authorized for the - authenticated principal and active team. The default `mine` scope - preserves the personal Inbox and requires user credentials. The - `team` scope lists notifications assigned to any recipient and - can be used by user or agent credentials. Personal read state - (`is_read`) is included only in `mine` scope and omitted in `team` - scope, including when filtering by recipient. - operationId: listFactoryInbox - tags: - - factory - security: - - bearerAuth: [] - parameters: - - $ref: '#/components/parameters/TeamUidHeaderParam' - - name: scope - in: query - description: | - `mine` returns notifications assigned to the authenticated user - and is the default. `team` returns notifications across live - recipients in the authorized Factory and team scope. - required: false - schema: - $ref: '#/components/schemas/FactoryInboxScope' - - name: factory_uid - in: query - description: 'Exact Factory UID filter, intersected with authorized factories.' - required: false - schema: - type: string - - name: recipient_uid - in: query - description: | - Exact public user UID filter within the authorized Factory and - team scope. In `mine` scope this can only match the authenticated - user. - required: false - schema: - type: string - - name: limit - in: query - description: Maximum number of items to return. Defaults to 50. - required: false - schema: - type: integer - minimum: 1 - maximum: 100 - default: 50 - - name: cursor - in: query - description: Opaque cursor from page_info.next_cursor. - required: false - schema: - type: string - responses: - '200': - description: One page of inbox notifications. - content: - application/json: - schema: - $ref: '#/components/schemas/ListFactoryInboxResponse' - '400': - description: 'Invalid scope, limit, cursor, or principal for the requested scope' - content: - application/problem+json: - schema: - $ref: '#/components/schemas/Error' - '401': - description: Authentication required - content: - application/problem+json: - schema: - $ref: '#/components/schemas/Error' - '403': - $ref: '#/components/responses/FactoryAccessDenied' - '404': - description: Factory task APIs are not available - content: - application/problem+json: - schema: - $ref: '#/components/schemas/Error' - '500': - description: Internal server error - content: - application/problem+json: - schema: - $ref: '#/components/schemas/Error' - /factory-inbox/notifications/read: - post: - summary: Mark inbox notifications as read - description: | - Mark a batch of notifications as read for the authenticated user after - checking access to each factory. The caller must be a recipient of - each existing notification, and the notification must remain active; - otherwise its outcome is unsuccessful. Missing notifications are - successful no-ops. Outcomes are returned in request order. - operationId: markFactoryInboxNotificationsRead - tags: - - factory - security: - - bearerAuth: [] - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/FactoryInboxMutationRequest' - responses: - '200': - description: Per-notification outcomes. - content: - application/json: - schema: - $ref: '#/components/schemas/FactoryInboxMutationResponse' - '400': - description: Invalid notification list - content: - application/problem+json: - schema: - $ref: '#/components/schemas/Error' - '401': - description: Authentication required - content: - application/problem+json: - schema: - $ref: '#/components/schemas/Error' - '403': - description: Caller is not a user - content: - application/problem+json: - schema: - $ref: '#/components/schemas/Error' - '500': - description: Internal server error - content: - application/problem+json: - schema: - $ref: '#/components/schemas/Error' - /factory-inbox/notifications/unread: - post: - summary: Mark inbox notifications as unread - description: | - Mark a batch of notifications as unread for the authenticated user - after checking access to each factory. The caller must be a recipient - of each existing notification, and the notification must remain active; - otherwise its outcome is unsuccessful. Missing notifications are - successful no-ops. Outcomes are returned in request order. - operationId: markFactoryInboxNotificationsUnread - tags: - - factory - security: - - bearerAuth: [] - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/FactoryInboxMutationRequest' - responses: - '200': - description: Per-notification outcomes. - content: - application/json: - schema: - $ref: '#/components/schemas/FactoryInboxMutationResponse' - '400': - description: Invalid notification list - content: - application/problem+json: - schema: - $ref: '#/components/schemas/Error' - '401': - description: Authentication required - content: - application/problem+json: - schema: - $ref: '#/components/schemas/Error' - '403': - description: Caller is not a user - content: - application/problem+json: - schema: - $ref: '#/components/schemas/Error' - '500': - description: Internal server error - content: - application/problem+json: - schema: - $ref: '#/components/schemas/Error' - '/factory/{uid}/tasks': + /factory/{uid}/tasks: post: summary: Create a factory task description: | @@ -373,16 +196,16 @@ paths: factories. operationId: createFactoryTask tags: - - factory + - factory security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: uid - in: path - description: The public UID of the factory. - required: true - schema: - type: string + - name: uid + in: path + description: The public UID of the factory. + required: true + schema: + type: string requestBody: required: true content: @@ -436,123 +259,123 @@ paths: canonical ticket metadata and derived outputs for the returned page. operationId: listFactoryTasks tags: - - factory + - factory security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: uid - in: path - description: The public UID of the factory. - required: true - schema: - type: string - - name: stage - in: query - description: | - Filter by task stage. Can be specified multiple times to match any - of the given stages. - required: false - schema: - type: array - items: - $ref: '#/components/schemas/FactoryTaskStage' - style: form - explode: true - - name: created_by - in: query - description: | - Filter to tasks whose seed run was started by any of these - teammates, each given as their email address. Can be specified - multiple times to match any of the given teammates. - required: false - schema: - type: array - items: - type: string - style: form - explode: true - - name: q - in: query - description: Case-insensitive substring search over the task title. - required: false - schema: - type: string - - name: created_after - in: query - description: Filter to tasks created after this timestamp (RFC3339 format). - required: false - schema: - type: string - format: date-time - - name: created_before - in: query - description: Filter to tasks created before this timestamp (RFC3339 format). - required: false - schema: - type: string - format: date-time - - name: updated_after - in: query - description: Filter to tasks updated after this timestamp (RFC3339 format). - required: false - schema: - type: string - format: date-time - - name: sort_by - in: query - description: Sort field for results. - required: false - schema: - type: string - enum: - - created_at - - updated_at - default: created_at - - name: sort_order - in: query - description: Sort direction. - required: false - schema: - type: string - enum: - - asc - - desc - default: desc - - name: limit - in: query - description: 'Maximum number of tasks to return (default 50, max 100).' - required: false - schema: - type: integer - minimum: 1 - maximum: 100 - - name: cursor - in: query - description: | - Opaque cursor returned by a previous list response. - Valid only for the sort_by/sort_order it was issued under; omit - to restart the listing. - required: false - schema: + - name: uid + in: path + description: The public UID of the factory. + required: true + schema: + type: string + - name: stage + in: query + description: | + Filter by task stage. Can be specified multiple times to match any + of the given stages. + required: false + schema: + type: array + items: + $ref: '#/components/schemas/FactoryTaskStage' + style: form + explode: true + - name: created_by + in: query + description: | + Filter to tasks whose seed run was started by any of these + teammates, each given as their email address. Can be specified + multiple times to match any of the given teammates. + required: false + schema: + type: array + items: type: string - - name: full_list - in: query - description: | - Include canonical ticket_source and ticket_id metadata from each - task's bound run, plus its derived outputs. Defaults to false. - required: false - schema: - type: boolean - default: false - - name: include_current_run - in: query - description: | - Include each task's current top-level run, resolved in one batch - for the returned page. Defaults to false. - required: false - schema: - type: boolean - default: false + style: form + explode: true + - name: q + in: query + description: Case-insensitive substring search over the task title. + required: false + schema: + type: string + - name: created_after + in: query + description: Filter to tasks created after this timestamp (RFC3339 format). + required: false + schema: + type: string + format: date-time + - name: created_before + in: query + description: Filter to tasks created before this timestamp (RFC3339 format). + required: false + schema: + type: string + format: date-time + - name: updated_after + in: query + description: Filter to tasks updated after this timestamp (RFC3339 format). + required: false + schema: + type: string + format: date-time + - name: sort_by + in: query + description: Sort field for results. + required: false + schema: + type: string + enum: + - created_at + - updated_at + default: created_at + - name: sort_order + in: query + description: Sort direction. + required: false + schema: + type: string + enum: + - asc + - desc + default: desc + - name: limit + in: query + description: Maximum number of tasks to return (default 50, max 100). + required: false + schema: + type: integer + minimum: 1 + maximum: 100 + - name: cursor + in: query + description: | + Opaque cursor returned by a previous list response. + Valid only for the sort_by/sort_order it was issued under; omit + to restart the listing. + required: false + schema: + type: string + - name: full_list + in: query + description: | + Include canonical ticket_source and ticket_id metadata from each + task's bound run, plus its derived outputs. Defaults to false. + required: false + schema: + type: boolean + default: false + - name: include_current_run + in: query + description: | + Include each task's current top-level run, resolved in one batch + for the returned page. Defaults to false. + required: false + schema: + type: boolean + default: false responses: '200': description: List of factory tasks @@ -561,7 +384,7 @@ paths: schema: $ref: '#/components/schemas/ListFactoryTasksResponse' '400': - description: 'Invalid filter, sort, limit, cursor, full_list, or include_current_run value' + description: Invalid filter, sort, limit, cursor, full_list, or include_current_run value content: application/problem+json: schema: @@ -586,7 +409,7 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - '/factory/{uid}/runs': + /factory/{uid}/runs: post: summary: Dispatch a run to a factory description: | @@ -596,16 +419,16 @@ paths: be resolved afterwards with GET /factory/{uid}/task-by-run. operationId: createFactoryRun tags: - - factory + - factory security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: uid - in: path - description: The public UID of the factory. - required: true - schema: - type: string + - name: uid + in: path + description: The public UID of the factory. + required: true + schema: + type: string requestBody: required: true content: @@ -651,29 +474,144 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - '/factory/{uid}/tasks/{task_uid}': + /factory/{uid}/branches/{branch_uid}: + get: + summary: Observe a tracked Factory Branch + description: | + Requires Factory view and matching parent Factory/team ownership. + Does not create tracking, request repair, or mutate projections. + Retired tracking remains DELETED until normal permadeletion. + Unverifiable source freshness is UNKNOWN. Requires factory_branches. + operationId: getFactoryBranch + tags: + - factory + security: + - bearerAuth: [] + parameters: + - name: uid + in: path + required: true + schema: + type: string + - name: branch_uid + in: path + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/FactoryBranchStatusResponse' + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/FactoryBranchNotFound' + '500': + $ref: '#/components/responses/FactoryBranchUnavailable' + delete: + summary: Stop tracking a Factory Branch + description: | + Requires Factory view plus source.apply. Retirement blocks future + execution boundaries without deleting the Git head, cancelling + already-loaded work, or deleting production resources. + Repeated authorized deletion, including after purge, returns 204. + Requires factory_branches. + operationId: deleteFactoryBranch + tags: + - factory + security: + - bearerAuth: [] + parameters: + - name: uid + in: path + required: true + schema: + type: string + - name: branch_uid + in: path + required: true + schema: + type: string + responses: + '204': + description: Tracking retired or already absent + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/FactoryAccessDenied' + '404': + $ref: '#/components/responses/FactoryBranchNotFound' + '409': + $ref: '#/components/responses/FactoryBranchConflict' + '500': + $ref: '#/components/responses/FactoryBranchUnavailable' + /factory/{uid}/branches/{branch_uid}/apply: + post: + summary: Apply a Factory Branch sync + description: | + Requires Factory view, source.apply, and complete projection + authorization. Synchronizes to the current registered head with + bounded freshness admission. Duplicate requests converge. + Does not accept a target SHA or repository, create tracking, revive + retired identity, or replace settings on existing runs. + Requires factory_branches. + operationId: applyFactoryBranch + tags: + - factory + security: + - bearerAuth: [] + parameters: + - name: uid + in: path + required: true + schema: + type: string + - name: branch_uid + in: path + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/FactoryBranchStatusResponse' + '400': + description: Invalid source content + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Error' + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/FactoryAccessDenied' + '404': + $ref: '#/components/responses/FactoryBranchNotFound' + '409': + $ref: '#/components/responses/FactoryBranchConflict' + '500': + $ref: '#/components/responses/FactoryBranchUnavailable' + /factory/{uid}/tasks/{task_uid}: get: summary: Get a factory task description: | Get a task with its derived outputs, newest-first. operationId: getFactoryTask tags: - - factory + - factory security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: uid - in: path - description: The public UID of the factory. - required: true - schema: - type: string - - name: task_uid - in: path - description: The public UID of the task. - required: true - schema: - type: string + - name: uid + in: path + description: The public UID of the factory. + required: true + schema: + type: string + - name: task_uid + in: path + description: The public UID of the task. + required: true + schema: + type: string responses: '200': description: Factory task details with derived outputs @@ -709,22 +647,22 @@ paths: transition is allowed, including moving backwards or to completion. operationId: updateFactoryTask tags: - - factory + - factory security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: uid - in: path - description: The public UID of the factory. - required: true - schema: - type: string - - name: task_uid - in: path - description: The public UID of the task. - required: true - schema: - type: string + - name: uid + in: path + description: The public UID of the factory. + required: true + schema: + type: string + - name: task_uid + in: path + description: The public UID of the task. + required: true + schema: + type: string requestBody: required: true content: @@ -772,22 +710,22 @@ paths: Deleting a task never deletes artifacts or the conversation. operationId: deleteFactoryTask tags: - - factory + - factory security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: uid - in: path - description: The public UID of the factory. - required: true - schema: - type: string - - name: task_uid - in: path - description: The public UID of the task. - required: true - schema: - type: string + - name: uid + in: path + description: The public UID of the factory. + required: true + schema: + type: string + - name: task_uid + in: path + description: The public UID of the task. + required: true + schema: + type: string responses: '204': description: Factory task deleted successfully @@ -811,7 +749,7 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - '/factory/{uid}/tasks/{task_uid}/cancel': + /factory/{uid}/tasks/{task_uid}/cancel: post: summary: Stop a factory task description: | @@ -820,22 +758,22 @@ paths: cancelled as well. operationId: cancelFactoryTask tags: - - factory + - factory security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: uid - in: path - description: The public UID of the factory. - required: true - schema: - type: string - - name: task_uid - in: path - description: The public UID of the task. - required: true - schema: - type: string + - name: uid + in: path + description: The public UID of the factory. + required: true + schema: + type: string + - name: task_uid + in: path + description: The public UID of the task. + required: true + schema: + type: string responses: '200': description: | @@ -893,7 +831,7 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - '/factory/{uid}/task-by-conversation': + /factory/{uid}/task-by-conversation: get: summary: Get a factory task by conversation description: | @@ -902,22 +840,22 @@ paths: owned by a different factory is 404. operationId: getFactoryTaskByConversation tags: - - factory + - factory security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: uid - in: path - description: The public UID of the factory. - required: true - schema: - type: string - - name: conversation_id - in: query - description: The agent conversation ID the task is bound to. - required: true - schema: - type: string + - name: uid + in: path + description: The public UID of the factory. + required: true + schema: + type: string + - name: conversation_id + in: query + description: The agent conversation ID the task is bound to. + required: true + schema: + type: string responses: '200': description: Factory task details with derived outputs @@ -940,7 +878,7 @@ paths: '403': $ref: '#/components/responses/FactoryAccessDenied' '404': - description: 'Factory not accessible, or no live task bound to the conversation under this factory' + description: Factory not accessible, or no live task bound to the conversation under this factory content: application/problem+json: schema: @@ -951,7 +889,7 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - '/factory/{uid}/task-by-run': + /factory/{uid}/task-by-run: get: summary: Get a factory task by run description: | @@ -960,22 +898,22 @@ paths: a different factory is 404. operationId: getFactoryTaskByRun tags: - - factory + - factory-metrics security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: uid - in: path - description: The public UID of the factory. - required: true - schema: - type: string - - name: run_id - in: query - description: Any run ID in the task's run tree. - required: true - schema: - type: string + - name: uid + in: path + description: The public UID of the factory. + required: true + schema: + type: string + - name: run_id + in: query + description: Any run ID in the task's run tree. + required: true + schema: + type: string responses: '200': description: Factory task details with derived outputs @@ -998,7 +936,7 @@ paths: '403': $ref: '#/components/responses/FactoryAccessDenied' '404': - description: 'Factory not accessible, the run does not resolve to a live task, or the task belongs to a different factory' + description: Factory not accessible, the run does not resolve to a live task, or the task belongs to a different factory content: application/problem+json: schema: @@ -1009,7 +947,7 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - '/factory/{uid}/metrics': + /factory/{uid}/metrics: get: summary: Get factory metrics description: | @@ -1020,39 +958,39 @@ paths: receive per-period series aligned to period_list. operationId: getFactoryMetrics tags: - - factory + - factory-metrics security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: uid - in: path - description: The public UID of the factory. - required: true - schema: - type: string - - name: start_date - in: query - description: Inclusive RFC3339 range start (UTC). Defaults to end_date minus 30 days. - required: false - schema: - type: string - format: date-time - - name: end_date - in: query - description: Exclusive RFC3339 range end (UTC). Defaults to now. - required: false - schema: - type: string - format: date-time - - name: group_by_period - in: query - description: | - Optional binning granularity; when omitted, the response - contains aggregates only. Binned requests are capped at 365 - periods. - required: false - schema: - $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' + - name: uid + in: path + description: The public UID of the factory. + required: true + schema: + type: string + - name: start_date + in: query + description: Inclusive RFC3339 range start (UTC). Defaults to end_date minus 30 days. + required: false + schema: + type: string + format: date-time + - name: end_date + in: query + description: Exclusive RFC3339 range end (UTC). Defaults to now. + required: false + schema: + type: string + format: date-time + - name: group_by_period + in: query + description: | + Optional binning granularity; when omitted, the response + contains aggregates only. Binned requests are capped at 365 + periods. + required: false + schema: + $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' responses: '200': description: Factory metrics for the requested range @@ -1061,7 +999,7 @@ paths: schema: $ref: '#/components/schemas/FactoryMetricsResponse' '400': - description: 'Invalid date range or group_by_period, or more than 365 periods requested' + description: Invalid date range or group_by_period, or more than 365 periods requested content: application/problem+json: schema: @@ -1088,7 +1026,7 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - '/factory/{uid}/costs/per-pr': + /factory/{uid}/costs/per-pr: get: summary: Get factory cost per PR description: | @@ -1098,39 +1036,39 @@ paths: additionally receive per-period series aligned to period_list. operationId: getFactoryCostPerPR tags: - - factory + - factory-metrics security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: uid - in: path - description: The public UID of the factory. - required: true - schema: - type: string - - name: start_date - in: query - description: Inclusive RFC3339 range start (UTC). Defaults to end_date minus 30 days. - required: false - schema: - type: string - format: date-time - - name: end_date - in: query - description: Exclusive RFC3339 range end (UTC). Defaults to now. - required: false - schema: - type: string - format: date-time - - name: group_by_period - in: query - description: | - Optional binning granularity; when omitted, the response - contains aggregates only. Binned requests are capped at 365 - periods. - required: false - schema: - $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' + - name: uid + in: path + description: The public UID of the factory. + required: true + schema: + type: string + - name: start_date + in: query + description: Inclusive RFC3339 range start (UTC). Defaults to end_date minus 30 days. + required: false + schema: + type: string + format: date-time + - name: end_date + in: query + description: Exclusive RFC3339 range end (UTC). Defaults to now. + required: false + schema: + type: string + format: date-time + - name: group_by_period + in: query + description: | + Optional binning granularity; when omitted, the response + contains aggregates only. Binned requests are capped at 365 + periods. + required: false + schema: + $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' responses: '200': description: Cost per PR for the requested range @@ -1139,7 +1077,7 @@ paths: schema: $ref: '#/components/schemas/FactoryCostPerPRResponse' '400': - description: 'Invalid date range or group_by_period, or more than 365 periods requested' + description: Invalid date range or group_by_period, or more than 365 periods requested content: application/problem+json: schema: @@ -1166,7 +1104,7 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - '/factory/{uid}/costs/breakdown': + /factory/{uid}/costs/breakdown: get: summary: Get factory spend grouped by a dimension description: | @@ -1176,45 +1114,45 @@ paths: additionally receive per-period series aligned to period_list. operationId: getFactoryCostBreakdown tags: - - factory + - factory-metrics security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: uid - in: path - description: The public UID of the factory. - required: true - schema: - type: string - - name: group_by - in: query - description: The dimension to group spend by. - required: true - schema: - $ref: '#/components/schemas/FactoryCostBreakdownGroupBy' - - name: start_date - in: query - description: Inclusive RFC3339 range start (UTC). Defaults to end_date minus 30 days. - required: false - schema: - type: string - format: date-time - - name: end_date - in: query - description: Exclusive RFC3339 range end (UTC). Defaults to now. - required: false - schema: - type: string - format: date-time - - name: group_by_period - in: query - description: | - Optional binning granularity; when omitted, the response - contains aggregates only. Binned requests are capped at 365 - periods. - required: false - schema: - $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' + - name: uid + in: path + description: The public UID of the factory. + required: true + schema: + type: string + - name: group_by + in: query + description: The dimension to group spend by. + required: true + schema: + $ref: '#/components/schemas/FactoryCostBreakdownGroupBy' + - name: start_date + in: query + description: Inclusive RFC3339 range start (UTC). Defaults to end_date minus 30 days. + required: false + schema: + type: string + format: date-time + - name: end_date + in: query + description: Exclusive RFC3339 range end (UTC). Defaults to now. + required: false + schema: + type: string + format: date-time + - name: group_by_period + in: query + description: | + Optional binning granularity; when omitted, the response + contains aggregates only. Binned requests are capped at 365 + periods. + required: false + schema: + $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' responses: '200': description: Grouped spend for the requested range @@ -1223,7 +1161,7 @@ paths: schema: $ref: '#/components/schemas/FactoryCostBreakdownResponse' '400': - description: 'Missing or invalid group_by, invalid date range or group_by_period, or more than 365 periods requested' + description: Missing or invalid group_by, invalid date range or group_by_period, or more than 365 periods requested content: application/problem+json: schema: @@ -1248,7 +1186,7 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - '/factory/{uid}/costs/per-pr/top': + /factory/{uid}/costs/per-pr/top: get: summary: Get the factory's most expensive PRs description: | @@ -1259,38 +1197,38 @@ paths: detail fields. operationId: getFactoryTopPRs tags: - - factory + - factory-metrics security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: uid - in: path - description: The public UID of the factory. - required: true - schema: - type: string - - name: start_date - in: query - description: Inclusive RFC3339 range start (UTC). Defaults to end_date minus 30 days. - required: false - schema: - type: string - format: date-time - - name: end_date - in: query - description: Exclusive RFC3339 range end (UTC). Defaults to now. - required: false - schema: - type: string - format: date-time - - name: limit - in: query - description: Maximum PRs to return. Defaults to 20; at most 50. - required: false - schema: - type: integer - minimum: 1 - maximum: 50 + - name: uid + in: path + description: The public UID of the factory. + required: true + schema: + type: string + - name: start_date + in: query + description: Inclusive RFC3339 range start (UTC). Defaults to end_date minus 30 days. + required: false + schema: + type: string + format: date-time + - name: end_date + in: query + description: Exclusive RFC3339 range end (UTC). Defaults to now. + required: false + schema: + type: string + format: date-time + - name: limit + in: query + description: Maximum PRs to return. Defaults to 20; at most 50. + required: false + schema: + type: integer + minimum: 1 + maximum: 50 responses: '200': description: The factory's most expensive PRs for the requested range @@ -1326,7 +1264,7 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - '/factory/{uid}/pull-requests': + /factory/{uid}/pull-requests: get: summary: List the factory's pull requests description: | @@ -1339,87 +1277,87 @@ paths: cursor to continue. Pass updated_after to sync incrementally. operationId: listFactoryPullRequests tags: - - factory + - factory security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: uid - in: path - description: The public UID of the factory. - required: true - schema: - type: string - - name: limit - in: query - description: Records per page. Defaults to 50; at most 500. - required: false - schema: - type: integer - minimum: 1 - maximum: 500 - - name: cursor - in: query - description: Opaque cursor from a previous page's page_info.next_cursor. - required: false - schema: - type: string - - name: repo - in: query - description: 'Only PRs in this repository, as owner/repo (case-insensitive).' - required: false - schema: - type: string - - name: state - in: query - description: | - Only PRs in these states. Can be specified multiple times to match any of the given states. - required: false - style: form - explode: true - schema: - type: array - items: - $ref: '#/components/schemas/FactoryPullRequestState' - - name: opened_after - in: query - description: Only PRs opened after this RFC3339 time (exclusive). - required: false - schema: - type: string - format: date-time - - name: opened_before - in: query - description: Only PRs opened before this RFC3339 time (exclusive). - required: false - schema: - type: string - format: date-time - - name: merged_after - in: query - description: Only PRs merged after this RFC3339 time (exclusive). - required: false - schema: - type: string - format: date-time - - name: merged_before - in: query - description: Only PRs merged before this RFC3339 time (exclusive). - required: false - schema: - type: string - format: date-time - - name: updated_after - in: query - description: | - Only PRs whose updated_at is after this RFC3339 time - (exclusive). updated_at tracks the PR on the code host; fields - derived from the factory's runs (runs, kickoff_at, - human_interactions.follow_up_message, and the kickoff-based - cycle_time stages) can change without moving it. - required: false - schema: - type: string - format: date-time + - name: uid + in: path + description: The public UID of the factory. + required: true + schema: + type: string + - name: limit + in: query + description: Records per page. Defaults to 50; at most 500. + required: false + schema: + type: integer + minimum: 1 + maximum: 500 + - name: cursor + in: query + description: Opaque cursor from a previous page's page_info.next_cursor. + required: false + schema: + type: string + - name: repo + in: query + description: Only PRs in this repository, as owner/repo (case-insensitive). + required: false + schema: + type: string + - name: state + in: query + description: | + Only PRs in these states. Can be specified multiple times to match any of the given states. + required: false + style: form + explode: true + schema: + type: array + items: + $ref: '#/components/schemas/FactoryPullRequestState' + - name: opened_after + in: query + description: Only PRs opened after this RFC3339 time (exclusive). + required: false + schema: + type: string + format: date-time + - name: opened_before + in: query + description: Only PRs opened before this RFC3339 time (exclusive). + required: false + schema: + type: string + format: date-time + - name: merged_after + in: query + description: Only PRs merged after this RFC3339 time (exclusive). + required: false + schema: + type: string + format: date-time + - name: merged_before + in: query + description: Only PRs merged before this RFC3339 time (exclusive). + required: false + schema: + type: string + format: date-time + - name: updated_after + in: query + description: | + Only PRs whose updated_at is after this RFC3339 time + (exclusive). updated_at tracks the PR on the code host; fields + derived from the factory's runs (runs, kickoff_at, + human_interactions.follow_up_message, and the kickoff-based + cycle_time stages) can change without moving it. + required: false + schema: + type: string + format: date-time responses: '200': description: One page of the factory's pull requests @@ -1428,7 +1366,7 @@ paths: schema: $ref: '#/components/schemas/FactoryPullRequestsResponse' '400': - description: 'Invalid limit, cursor, state, or timestamp filter, or a time window whose *_after bound is not before its *_before bound' + description: Invalid limit, cursor, state, or timestamp filter, or a time window whose *_after bound is not before its *_before bound content: application/problem+json: schema: @@ -1455,7 +1393,7 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - '/factory/{uid}/metrics/run-breakdown': + /factory/{uid}/metrics/run-breakdown: get: summary: Get the factory's run counts grouped by a dimension description: | @@ -1464,45 +1402,45 @@ paths: series aligned to period_list. operationId: getFactoryRunBreakdown tags: - - factory + - factory-metrics security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: uid - in: path - description: The public UID of the factory. - required: true - schema: - type: string - - name: group_by - in: query - description: The dimension to group run counts by. - required: true - schema: - $ref: '#/components/schemas/FactoryRunBreakdownGroupBy' - - name: start_date - in: query - description: Inclusive RFC3339 range start (UTC). Defaults to end_date minus 30 days. - required: false - schema: - type: string - format: date-time - - name: end_date - in: query - description: Exclusive RFC3339 range end (UTC). Defaults to now. - required: false - schema: - type: string - format: date-time - - name: group_by_period - in: query - description: | - Optional binning granularity; when omitted, the response - contains aggregates only. Binned requests are capped at 365 - periods. - required: false - schema: - $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' + - name: uid + in: path + description: The public UID of the factory. + required: true + schema: + type: string + - name: group_by + in: query + description: The dimension to group run counts by. + required: true + schema: + $ref: '#/components/schemas/FactoryRunBreakdownGroupBy' + - name: start_date + in: query + description: Inclusive RFC3339 range start (UTC). Defaults to end_date minus 30 days. + required: false + schema: + type: string + format: date-time + - name: end_date + in: query + description: Exclusive RFC3339 range end (UTC). Defaults to now. + required: false + schema: + type: string + format: date-time + - name: group_by_period + in: query + description: | + Optional binning granularity; when omitted, the response + contains aggregates only. Binned requests are capped at 365 + periods. + required: false + schema: + $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' responses: '200': description: Grouped run counts for the requested range @@ -1511,7 +1449,7 @@ paths: schema: $ref: '#/components/schemas/FactoryRunBreakdownResponse' '400': - description: 'Missing or invalid group_by, invalid date range or group_by_period, or more than 365 periods requested' + description: Missing or invalid group_by, invalid date range or group_by_period, or more than 365 periods requested content: application/problem+json: schema: @@ -1536,7 +1474,7 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - '/factory/{uid}/costs/per-pr/by-size': + /factory/{uid}/costs/per-pr/by-size: get: summary: Get the factory's PR cost distribution grouped by PR size description: | @@ -1546,39 +1484,39 @@ paths: period_list. operationId: getFactoryCostByPRSize tags: - - factory + - factory-metrics security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: uid - in: path - description: The public UID of the factory. - required: true - schema: - type: string - - name: start_date - in: query - description: Inclusive RFC3339 range start (UTC). Defaults to end_date minus 30 days. - required: false - schema: - type: string - format: date-time - - name: end_date - in: query - description: Exclusive RFC3339 range end (UTC). Defaults to now. - required: false - schema: - type: string - format: date-time - - name: group_by_period - in: query - description: | - Optional binning granularity; when omitted, the response - contains aggregates only. Binned requests are capped at 365 - periods. - required: false - schema: - $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' + - name: uid + in: path + description: The public UID of the factory. + required: true + schema: + type: string + - name: start_date + in: query + description: Inclusive RFC3339 range start (UTC). Defaults to end_date minus 30 days. + required: false + schema: + type: string + format: date-time + - name: end_date + in: query + description: Exclusive RFC3339 range end (UTC). Defaults to now. + required: false + schema: + type: string + format: date-time + - name: group_by_period + in: query + description: | + Optional binning granularity; when omitted, the response + contains aggregates only. Binned requests are capped at 365 + periods. + required: false + schema: + $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' responses: '200': description: Cost-by-size distribution for the requested range @@ -1587,7 +1525,7 @@ paths: schema: $ref: '#/components/schemas/FactoryCostByPRSizeResponse' '400': - description: 'Invalid date range or group_by_period, or more than 365 periods requested' + description: Invalid date range or group_by_period, or more than 365 periods requested content: application/problem+json: schema: @@ -1621,50 +1559,50 @@ paths: operationId: listAgents deprecated: true tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/TeamUidHeaderParam' - - name: repo - in: query - description: | - Optional repository specification to list agents from (format: "owner/repo"). - If not provided, lists agents from all accessible environments. - required: false - schema: - type: string - - name: refresh - in: query - description: | - When true, clears the agent list cache before fetching. - Use this to force a refresh of the available agents. - required: false - schema: - type: boolean - default: false - - name: sort_by - in: query - description: | - Sort order for the returned agents. - - "name": Sort alphabetically by name (default) - - "last_run": Sort by most recently used - required: false - schema: - type: string - enum: - - name - - last_run - - name: include_malformed_skills - in: query - description: | - When true, includes skills whose SKILL.md file exists but is - malformed. These variants will have a non-empty `error` field - describing the parse failure. Defaults to false. - required: false - schema: - type: boolean - default: false + - $ref: '#/components/parameters/TeamUidHeaderParam' + - name: repo + in: query + description: | + Optional repository specification to list agents from (format: "owner/repo"). + If not provided, lists agents from all accessible environments. + required: false + schema: + type: string + - name: refresh + in: query + description: | + When true, clears the agent list cache before fetching. + Use this to force a refresh of the available agents. + required: false + schema: + type: boolean + default: false + - name: sort_by + in: query + description: | + Sort order for the returned agents. + - "name": Sort alphabetically by name (default) + - "last_run": Sort by most recently used + required: false + schema: + type: string + enum: + - name + - last_run + - name: include_malformed_skills + in: query + description: | + When true, includes skills whose SKILL.md file exists but is + malformed. These variants will have a non-empty `error` field + describing the parse failure. Defaults to false. + required: false + schema: + type: boolean + default: false responses: '200': description: List of available agents @@ -1686,11 +1624,11 @@ paths: Worker presence is derived from worker websocket heartbeats and may be briefly stale. operationId: listConnectedSelfHostedWorkers tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/TeamUidHeaderParam' + - $ref: '#/components/parameters/TeamUidHeaderParam' responses: '200': description: List of currently connected self-hosted workers @@ -1710,7 +1648,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - '/agent/runs/{runId}/transcript': + /agent/runs/{runId}/transcript: get: summary: Get run transcript description: | @@ -1718,16 +1656,16 @@ paths: Returns a 302 redirect to a time-limited download URL for the transcript. operationId: getRunTranscript tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: runId - in: path - description: The unique identifier of the run - required: true - schema: - type: string + - name: runId + in: path + description: The unique identifier of the run + required: true + schema: + type: string responses: '302': description: Redirect to a download URL for the transcript @@ -1767,7 +1705,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - '/agent/runs/{runId}/harness-usage': + /agent/runs/{runId}/harness-usage: get: summary: Get raw third-party harness usage description: | @@ -1777,15 +1715,15 @@ paths: authorization as transcript reads. operationId: getRunHarnessUsage tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: runId - in: path - required: true - schema: - type: string + - name: runId + in: path + required: true + schema: + type: string responses: '200': description: Raw harness usage or an unavailable result @@ -1826,11 +1764,11 @@ paths: operationId: runAgent deprecated: true tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/TeamUidHeaderParam' + - $ref: '#/components/parameters/TeamUidHeaderParam' requestBody: required: true content: @@ -1859,7 +1797,7 @@ paths: schema: $ref: '#/components/schemas/RunAgentResponse' '400': - description: 'Invalid request (missing prompt, invalid config)' + description: Invalid request (missing prompt, invalid config) content: application/json: schema: @@ -1871,7 +1809,7 @@ paths: schema: $ref: '#/components/schemas/Error' '403': - description: 'No permission to access referenced resources (environment, MCP servers)' + description: No permission to access referenced resources (environment, MCP servers) content: application/json: schema: @@ -1884,11 +1822,11 @@ paths: The agent will be queued for execution and assigned a unique run ID. operationId: createRun tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/TeamUidHeaderParam' + - $ref: '#/components/parameters/TeamUidHeaderParam' requestBody: required: true content: @@ -1903,7 +1841,7 @@ paths: schema: $ref: '#/components/schemas/RunAgentResponse' '400': - description: 'Invalid request (missing prompt, invalid config)' + description: Invalid request (missing prompt, invalid config) content: application/json: schema: @@ -1915,7 +1853,7 @@ paths: schema: $ref: '#/components/schemas/Error' '403': - description: 'No permission to access referenced resources (environment, MCP servers)' + description: No permission to access referenced resources (environment, MCP servers) content: application/json: schema: @@ -1927,234 +1865,234 @@ paths: Results default to `sort_by=updated_at` and `sort_order=desc`. operationId: listRuns tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/TeamUidHeaderParam' - - name: limit - in: query - description: Maximum number of runs to return - required: false - schema: - type: integer - minimum: 1 - maximum: 500 - default: 20 - - name: cursor - in: query - description: Pagination cursor from previous response - required: false - schema: - type: string - - name: sort_by - in: query - description: | - Sort field for results. - - `updated_at`: Sort by last update timestamp (default) - - `created_at`: Sort by creation timestamp - - `title`: Sort alphabetically by run title - - `agent`: Sort alphabetically by skill. Runs without a skill are grouped last. - required: false - schema: - type: string - enum: - - updated_at - - created_at - - title - - agent - default: updated_at - - name: sort_order - in: query - description: Sort direction - required: false - schema: + - $ref: '#/components/parameters/TeamUidHeaderParam' + - name: limit + in: query + description: Maximum number of runs to return + required: false + schema: + type: integer + minimum: 1 + maximum: 500 + default: 20 + - name: cursor + in: query + description: Pagination cursor from previous response + required: false + schema: + type: string + - name: sort_by + in: query + description: | + Sort field for results. + - `updated_at`: Sort by last update timestamp (default) + - `created_at`: Sort by creation timestamp + - `title`: Sort alphabetically by run title + - `agent`: Sort alphabetically by skill. Runs without a skill are grouped last. + required: false + schema: + type: string + enum: + - updated_at + - created_at + - title + - agent + default: updated_at + - name: sort_order + in: query + description: Sort direction + required: false + schema: + type: string + enum: + - asc + - desc + default: desc + - name: state + in: query + description: | + Filter by run state. Can be specified multiple times to match any of the given states. + required: false + schema: + type: array + items: + $ref: '#/components/schemas/RunState' + style: form + explode: true + - name: task_status + in: query + description: | + Filter by high-level task status. Can be specified multiple times to match any value. + `running` matches when the root or any descendant is queued, pending, claimed, or in progress. + `failed`, `blocked`, `cancelled`, and `complete` match the root state only. + required: false + schema: + type: array + items: type: string enum: - - asc - - desc - default: desc - - name: state - in: query - description: | - Filter by run state. Can be specified multiple times to match any of the given states. - required: false - schema: - type: array - items: - $ref: '#/components/schemas/RunState' - style: form - explode: true - - name: task_status - in: query - description: | - Filter by high-level task status. Can be specified multiple times to match any value. - `running` matches when the root or any descendant is queued, pending, claimed, or in progress. - `failed`, `blocked`, `cancelled`, and `complete` match the root state only. - required: false - schema: - type: array - items: - type: string - enum: - - running - - failed - - blocked - - cancelled - - complete - style: form - explode: true - - name: name - in: query - description: Filter by agent config name - required: false - schema: - type: string - - name: model_id - in: query - description: Filter by model ID - required: false - schema: - type: string - - name: creator - in: query - description: Filter by creator UID (user or service account) - required: false - schema: - type: string - - name: executor - in: query - description: | - Filter by the user or agent that executed the run. This will often be the - same as the creator, but not always: users may delegate tasks to agents. - required: false - schema: - type: string - - name: source - in: query - description: | - Filter by run source type. Can be specified multiple times to match any of the given sources. - required: false - schema: - type: array + - running + - failed + - blocked + - cancelled + - complete + style: form + explode: true + - name: name + in: query + description: Filter by agent config name + required: false + schema: + type: string + - name: model_id + in: query + description: Filter by model ID + required: false + schema: + type: string + - name: creator + in: query + description: Filter by creator UID (user or service account) + required: false + schema: + type: string + - name: executor + in: query + description: | + Filter by the user or agent that executed the run. This will often be the + same as the creator, but not always: users may delegate tasks to agents. + required: false + schema: + type: string + - name: source + in: query + description: | + Filter by run source type. Can be specified multiple times to match any of the given sources. + required: false + schema: + type: array + items: + $ref: '#/components/schemas/RunSourceType' + style: form + explode: true + - name: execution_location + in: query + description: Filter by where the run executed + required: false + schema: + $ref: '#/components/schemas/RunExecutionLocation' + - name: created_after + in: query + description: Filter runs created after this timestamp (RFC3339 format) + required: false + schema: + type: string + format: date-time + - name: created_before + in: query + description: Filter runs created before this timestamp (RFC3339 format) + required: false + schema: + type: string + format: date-time + - name: updated_after + in: query + description: Filter runs updated after this timestamp (RFC3339 format) + required: false + schema: + type: string + format: date-time + - name: environment_id + in: query + description: | + Filter runs by environment ID. Passing the literal value + `empty-environment` matches runs with no environment configured, + rather than omitting the parameter, which applies no environment + filter at all. `empty-environment` can never collide with a real + environment ID: every environment ID is exactly 22 characters + drawn from `[A-Za-z0-9]`, while this sentinel contains a hyphen + and is a different length. + required: false + schema: + type: string + - name: skill + in: query + description: | + Filter runs by skill spec (e.g., "owner/repo:path/to/SKILL.md"). + Alias for skill_spec. + required: false + schema: + type: string + - name: skill_spec + in: query + description: Filter runs by skill spec (e.g., "owner/repo:path/to/SKILL.md") + required: false + schema: + type: string + - name: schedule_id + in: query + description: Filter runs by the scheduled agent ID that created them + required: false + schema: + type: string + - name: factory_uid + in: query + description: | + Filter runs by one or more factories. Repeating this parameter + matches runs executed by an agent from any selected factory. A UID + outside the caller's accessible factories matches nothing. + required: false + schema: + oneOf: + - type: string + - type: array items: - $ref: '#/components/schemas/RunSourceType' - style: form - explode: true - - name: execution_location - in: query - description: Filter by where the run executed - required: false - schema: - $ref: '#/components/schemas/RunExecutionLocation' - - name: created_after - in: query - description: Filter runs created after this timestamp (RFC3339 format) - required: false - schema: - type: string - format: date-time - - name: created_before - in: query - description: Filter runs created before this timestamp (RFC3339 format) - required: false - schema: - type: string - format: date-time - - name: updated_after - in: query - description: Filter runs updated after this timestamp (RFC3339 format) - required: false - schema: - type: string - format: date-time - - name: environment_id - in: query - description: | - Filter runs by environment ID. Passing the literal value - `empty-environment` matches runs with no environment configured, - rather than omitting the parameter, which applies no environment - filter at all. `empty-environment` can never collide with a real - environment ID: every environment ID is exactly 22 characters - drawn from `[A-Za-z0-9]`, while this sentinel contains a hyphen - and is a different length. - required: false - schema: - type: string - - name: skill - in: query - description: | - Filter runs by skill spec (e.g., "owner/repo:path/to/SKILL.md"). - Alias for skill_spec. - required: false - schema: - type: string - - name: skill_spec - in: query - description: 'Filter runs by skill spec (e.g., "owner/repo:path/to/SKILL.md")' - required: false - schema: - type: string - - name: schedule_id - in: query - description: Filter runs by the scheduled agent ID that created them - required: false - schema: - type: string - - name: factory_uid - in: query - description: | - Filter runs by one or more factories. Repeating this parameter - matches runs executed by an agent from any selected factory. A UID - outside the caller's accessible factories matches nothing. - required: false - schema: - oneOf: - - type: string - - type: array - items: - type: string - style: form - explode: true - - name: ancestor_run_id - in: query - description: Filter runs by ancestor run ID. The referenced run must exist and be accessible to the caller. - required: false - schema: - type: string - - name: metadata - in: query - description: | - Filter by exact metadata key/value pairs using object notation - (e.g. `metadata[ticket_id]=ACME-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 - maxProperties: 5 - additionalProperties: type: string - style: deepObject - explode: true - - name: artifact_type - in: query - description: Filter runs by artifact type - required: false - schema: - type: string - enum: - - PLAN - - PULL_REQUEST - - SCREENSHOT - - FILE - - EXTERNAL_REFERENCE - - name: q - in: query - description: 'Search by full run ID or run URL, or fuzzy match across run title, prompt, and skill_spec' - required: false - schema: + style: form + explode: true + - name: ancestor_run_id + in: query + description: Filter runs by ancestor run ID. The referenced run must exist and be accessible to the caller. + required: false + schema: + type: string + - name: metadata + in: query + description: | + Filter by exact metadata key/value pairs using object notation + (e.g. `metadata[ticket_id]=ACME-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 + maxProperties: 5 + additionalProperties: type: string + style: deepObject + explode: true + - name: artifact_type + in: query + description: Filter runs by artifact type + required: false + schema: + type: string + enum: + - PLAN + - PULL_REQUEST + - SCREENSHOT + - FILE + - EXTERNAL_REFERENCE + - name: q + in: query + description: Search by full run ID or run URL, or fuzzy match across run title, prompt, and skill_spec + required: false + schema: + type: string responses: '200': description: List of runs @@ -2190,17 +2128,17 @@ paths: exists or when the caller lacks access. operationId: getRunByExternalReferenceURL tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: url - in: query - required: true - description: The canonical URL of the external reference artifact to look up. - schema: - type: string - maxLength: 2048 + - name: url + in: query + required: true + description: The canonical URL of the external reference artifact to look up. + schema: + type: string + maxLength: 2048 responses: '200': description: Run found @@ -2221,7 +2159,7 @@ paths: schema: $ref: '#/components/schemas/Error' '404': - description: 'No run found with the given external reference URL, or caller lacks access' + description: No run found with the given external reference URL, or caller lacks access content: application/json: schema: @@ -2232,7 +2170,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - '/agent/runs/{runId}': + /agent/runs/{runId}: get: summary: Get run details description: | @@ -2240,16 +2178,16 @@ paths: including the full prompt, session link, and resolved configuration. operationId: getRun tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: runId - in: path - description: The unique identifier of the run - required: true - schema: - type: string + - name: runId + in: path + description: The unique identifier of the run + required: true + schema: + type: string responses: '200': description: Run details @@ -2281,23 +2219,23 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - '/agent/runs/{runId}/timeline': + /agent/runs/{runId}/timeline: get: summary: Get run timeline description: | Retrieve chronological setup and lifecycle timeline events for an agent run. operationId: getRunTimeline tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: runId - in: path - description: The unique identifier of the run - required: true - schema: - type: string + - name: runId + in: path + description: The unique identifier of the run + required: true + schema: + type: string responses: '200': description: Run timeline events @@ -2329,7 +2267,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - '/agent/runs/{runId}/conversation': + /agent/runs/{runId}/conversation: get: summary: Get normalized run conversation description: | @@ -2338,16 +2276,16 @@ paths: into structured blocks. operationId: getRunConversation tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: runId - in: path - description: The unique identifier of the run - required: true - schema: - type: string + - name: runId + in: path + description: The unique identifier of the run + required: true + schema: + type: string responses: '200': description: Normalized conversation @@ -2374,7 +2312,7 @@ paths: schema: $ref: '#/components/schemas/Error' '404': - description: 'Run not found, or the run has no conversation' + description: Run not found, or the run has no conversation content: application/json: schema: @@ -2387,7 +2325,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - '/agent/runs/{runId}/cancel': + /agent/runs/{runId}/cancel: post: summary: Cancel a run description: | @@ -2398,16 +2336,16 @@ paths: instead — see the error responses below for each case. operationId: cancelRun tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: runId - in: path - description: The unique identifier of the run to cancel - required: true - schema: - type: string + - name: runId + in: path + description: The unique identifier of the run to cancel + required: true + schema: + type: string responses: '200': description: Run cancelled successfully @@ -2457,7 +2395,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - '/agent/runs/{runId}/followups': + /agent/runs/{runId}/followups: post: summary: Submit a follow-up message for a run description: | @@ -2476,16 +2414,16 @@ paths: unchanged. operationId: submitRunFollowup tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: runId - in: path - description: The unique identifier of the run - required: true - schema: - type: string + - name: runId + in: path + description: The unique identifier of the run + required: true + schema: + type: string requestBody: required: true content: @@ -2542,7 +2480,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - '/agent/runs/{runId}/interrupt': + /agent/runs/{runId}/interrupt: post: summary: Interrupt the turn currently running on a run description: | @@ -2554,16 +2492,16 @@ paths: applies it asynchronously. operationId: interruptRun tags: - - agent + - agent security: - - bearerAuth: [] - parameters: - - name: runId - in: path - description: The unique identifier of the run - required: true - schema: - type: string + - bearerAuth: [] + parameters: + - name: runId + in: path + description: The unique identifier of the run + required: true + schema: + type: string responses: '202': description: Interrupt accepted @@ -2611,61 +2549,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - '/agent/runs/{runId}/handoff/attachments': - get: - summary: List handoff snapshot attachments for a run - description: | - Return fresh presigned download URLs for handoff snapshot files uploaded - by the latest ended execution of this run. An empty list is returned - when no ended execution exists or no snapshot files were uploaded. - - This endpoint is useful for third-party harnesses that want to download - the snapshot files produced by a previous execution before starting a - handoff execution themselves. - operationId: listHandoffSnapshotAttachments - tags: - - agent - security: - - bearerAuth: [] - parameters: - - name: runId - in: path - description: The unique identifier of the run - required: true - schema: - type: string - responses: - '200': - description: Handoff snapshot attachments (possibly empty) - content: - application/json: - schema: - $ref: '#/components/schemas/ListHandoffSnapshotAttachmentsResponse' - '400': - description: Missing run ID - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - '401': - description: Authentication required - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - '403': - description: No permission to view the run - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - '500': - description: Internal server error - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - '/agent/conversations/{conversation_id}/followups': + /agent/conversations/{conversation_id}/followups: post: summary: Submit a follow-up message to the run behind a conversation description: | @@ -2685,17 +2569,17 @@ paths: session runs in the session's current mode. operationId: submitConversationFollowup tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: conversation_id - in: path - description: The UUID of the Warp-native conversation - required: true - schema: - type: string - format: uuid + - name: conversation_id + in: path + description: The UUID of the Warp-native conversation + required: true + schema: + type: string + format: uuid requestBody: required: true content: @@ -2756,7 +2640,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - '/agent/conversations/{conversation_id}/interrupt': + /agent/conversations/{conversation_id}/interrupt: post: summary: Interrupt the turn running on the run behind a conversation description: | @@ -2766,17 +2650,17 @@ paths: be able to view the conversation and the resolved run. operationId: interruptConversation tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: conversation_id - in: path - description: The UUID of the Warp-native conversation - required: true - schema: - type: string - format: uuid + - name: conversation_id + in: path + description: The UUID of the Warp-native conversation + required: true + schema: + type: string + format: uuid responses: '202': description: Interrupt accepted @@ -2822,7 +2706,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - '/agent/conversations/{conversation_id}': + /agent/conversations/{conversation_id}: get: summary: Get normalized conversation description: | @@ -2830,16 +2714,16 @@ paths: normalized task/message format. operationId: getConversation tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: conversation_id - in: path - description: The unique identifier of the conversation - required: true - schema: - type: string + - name: conversation_id + in: path + description: The unique identifier of the conversation + required: true + schema: + type: string responses: '200': description: Normalized conversation @@ -2879,7 +2763,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - '/agent/conversations/{conversation_id}/transcript': + /agent/conversations/{conversation_id}/transcript: get: summary: Get conversation transcript description: | @@ -2888,16 +2772,16 @@ paths: Supported for third-party harness conversations (Claude Code, Codex, Gemini). operationId: getConversationTranscript tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: conversation_id - in: path - description: The unique identifier of the conversation - required: true - schema: - type: string + - name: conversation_id + in: path + description: The unique identifier of the conversation + required: true + schema: + type: string responses: '302': description: Redirect to a download URL for the transcript @@ -2937,7 +2821,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - '/agent/conversations/{conversation_id}/screenshots/{screenshot_uid}/download': + /agent/conversations/{conversation_id}/screenshots/{screenshot_uid}/download: get: summary: Download a stored computer-use screenshot description: | @@ -2949,22 +2833,22 @@ paths: screenshots stored under its source conversation's ID. operationId: downloadConversationScreenshot tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: conversation_id - in: path - description: The unique identifier of the conversation that owns the screenshot - required: true - schema: - type: string - - name: screenshot_uid - in: path - description: The unique identifier of the stored screenshot - required: true - schema: - type: string + - name: conversation_id + in: path + description: The unique identifier of the conversation that owns the screenshot + required: true + schema: + type: string + - name: screenshot_uid + in: path + description: The unique identifier of the stored screenshot + required: true + schema: + type: string responses: '302': description: Redirect to a temporary signed screenshot download URL @@ -3020,11 +2904,11 @@ paths: The agent will be triggered automatically based on the cron expression. operationId: createScheduledAgent tags: - - schedules + - schedules security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/TeamUidHeaderParam' + - $ref: '#/components/parameters/TeamUidHeaderParam' requestBody: required: true content: @@ -3056,7 +2940,7 @@ paths: schema: $ref: '#/components/schemas/ScheduledAgentItem' '400': - description: 'Invalid request (missing required fields, invalid cron expression)' + description: Invalid request (missing required fields, invalid cron expression) content: application/json: schema: @@ -3080,11 +2964,11 @@ paths: Results are sorted alphabetically by name. operationId: listScheduledAgents tags: - - schedules + - schedules security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/TeamUidHeaderParam' + - $ref: '#/components/parameters/TeamUidHeaderParam' responses: '200': description: List of scheduled agents @@ -3104,7 +2988,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - '/agent/schedules/{scheduleId}': + /agent/schedules/{scheduleId}: get: summary: Get scheduled agent details description: | @@ -3112,16 +2996,16 @@ paths: including its configuration, history, and next scheduled run time. operationId: getScheduledAgent tags: - - schedules + - schedules security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: scheduleId - in: path - description: The unique identifier of the scheduled agent - required: true - schema: - type: string + - name: scheduleId + in: path + description: The unique identifier of the scheduled agent + required: true + schema: + type: string responses: '200': description: Scheduled agent details @@ -3160,16 +3044,16 @@ paths: All fields except agent_config are required. operationId: updateScheduledAgent tags: - - schedules + - schedules security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: scheduleId - in: path - description: The unique identifier of the scheduled agent - required: true - schema: - type: string + - name: scheduleId + in: path + description: The unique identifier of the scheduled agent + required: true + schema: + type: string requestBody: required: true content: @@ -3213,16 +3097,16 @@ paths: Delete a scheduled agent. This will stop all future scheduled runs. operationId: deleteScheduledAgent tags: - - schedules + - schedules security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: scheduleId - in: path - description: The unique identifier of the scheduled agent - required: true - schema: - type: string + - name: scheduleId + in: path + description: The unique identifier of the scheduled agent + required: true + schema: + type: string responses: '200': description: Scheduled agent deleted successfully @@ -3254,23 +3138,23 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - '/agent/schedules/{scheduleId}/pause': + /agent/schedules/{scheduleId}/pause: post: summary: Pause a scheduled agent description: | Pause a scheduled agent. The agent will not run until resumed. operationId: pauseScheduledAgent tags: - - schedules + - schedules security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: scheduleId - in: path - description: The unique identifier of the scheduled agent - required: true - schema: - type: string + - name: scheduleId + in: path + description: The unique identifier of the scheduled agent + required: true + schema: + type: string responses: '200': description: Scheduled agent paused successfully @@ -3302,7 +3186,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - '/agent/schedules/{scheduleId}/resume': + /agent/schedules/{scheduleId}/resume: post: summary: Resume a scheduled agent description: | @@ -3310,16 +3194,16 @@ paths: according to its cron schedule. operationId: resumeScheduledAgent tags: - - schedules + - schedules security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: scheduleId - in: path - description: The unique identifier of the scheduled agent - required: true - schema: - type: string + - name: scheduleId + in: path + description: The unique identifier of the scheduled agent + required: true + schema: + type: string responses: '200': description: Scheduled agent resumed successfully @@ -3360,24 +3244,24 @@ paths: or has accessed via link sharing. operationId: listEnvironments tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/TeamUidHeaderParam' - - name: sort_by - in: query - required: false - description: | - Sort order for the returned environments. - - `name`: alphabetical by environment name - - `last_updated`: most recently updated first (default) - schema: - type: string - enum: - - name - - last_updated - default: last_updated + - $ref: '#/components/parameters/TeamUidHeaderParam' + - name: sort_by + in: query + required: false + description: | + Sort order for the returned environments. + - `name`: alphabetical by environment name + - `last_updated`: most recently updated first (default) + schema: + type: string + enum: + - name + - last_updated + default: last_updated responses: '200': description: List of accessible environments @@ -3407,9 +3291,9 @@ paths: currently disabled (and why). operationId: listModels tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] responses: '200': description: List of available models @@ -3429,7 +3313,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - '/agent/artifacts/{artifactUid}': + /agent/artifacts/{artifactUid}: get: summary: Get artifact details description: | @@ -3440,17 +3324,17 @@ paths: authenticated and authorized. operationId: getArtifact tags: - - agent + - agent security: - - bearerAuth: [] - - {} + - bearerAuth: [] + - {} parameters: - - name: artifactUid - in: path - description: The unique identifier (UUID) of the artifact - required: true - schema: - type: string + - name: artifactUid + in: path + description: The unique identifier (UUID) of the artifact + required: true + schema: + type: string responses: '200': description: Artifact details with download information @@ -3482,7 +3366,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - '/agent/artifacts/{artifactUid}/download': + /agent/artifacts/{artifactUid}/download: get: summary: Download an artifact description: | @@ -3491,17 +3375,17 @@ paths: artifacts require the caller to be authenticated and authorized. operationId: downloadArtifact tags: - - agent + - agent security: - - bearerAuth: [] - - {} + - bearerAuth: [] + - {} parameters: - - name: artifactUid - in: path - description: The unique identifier (UUID) of the artifact - required: true - schema: - type: string + - name: artifactUid + in: path + description: The unique identifier (UUID) of the artifact + required: true + schema: + type: string responses: '302': description: Redirect to a temporary signed artifact download URL @@ -3543,14 +3427,14 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - '/factory/{uid}/scorers/{scorer_uid}': + /factory/{uid}/scorers/{scorer_uid}: parameters: - - name: uid - in: path - description: UID of the factory that owns the scorer - required: true - schema: - type: string + - name: uid + in: path + description: UID of the factory that owns the scorer + required: true + schema: + type: string patch: summary: Update a scorer's definition description: | @@ -3564,17 +3448,17 @@ paths: scope in full. operationId: updateScorer tags: - - factory + - factory-scorers security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: scorer_uid - in: path - description: The scorer identifier - required: true - schema: - type: string - description: Scorer UUID or temporary positive decimal integer ID. + - name: scorer_uid + in: path + description: The scorer identifier + required: true + schema: + type: string + description: Scorer UUID or temporary positive decimal integer ID. requestBody: required: true content: @@ -3603,7 +3487,7 @@ paths: '403': $ref: '#/components/responses/FactoryAccessDenied' '404': - description: 'Scorer not found, or the caller cannot manage its factory' + description: Scorer not found, or the caller cannot manage its factory content: application/json: schema: @@ -3628,17 +3512,17 @@ paths: both are gone. operationId: deleteScorer tags: - - factory + - factory-scorers security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: scorer_uid - in: path - description: The scorer identifier - required: true - schema: - type: string - description: Scorer UUID or temporary positive decimal integer ID. + - name: scorer_uid + in: path + description: The scorer identifier + required: true + schema: + type: string + description: Scorer UUID or temporary positive decimal integer ID. responses: '204': description: Scorer deleted @@ -3657,7 +3541,65 @@ paths: '403': $ref: '#/components/responses/FactoryAccessDenied' '404': - description: 'Scorer not found, or the caller cannot manage its factory' + description: Scorer not found, or the caller cannot manage its factory + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '500': + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /agent/conversations/{conversationId}/block-snapshot: + get: + summary: Download a conversation's block snapshot + description: | + Redirect to a signed storage URL for the serialized block snapshot. + Set redirect=false to return the URL as JSON instead. Both modes require + permission to view the conversation. + operationId: getConversationBlockSnapshot + tags: + - agent + security: + - bearerAuth: [] + parameters: + - name: conversationId + in: path + required: true + schema: + type: string + - $ref: '#/components/parameters/PresignedDownloadRedirect' + responses: + '200': + description: Signed download URL when redirect=false + content: + application/json: + schema: + $ref: '#/components/schemas/PresignedDownloadResponse' + '307': + description: Redirect to the signed storage URL (default) + '400': + description: Conversation format does not support block snapshots + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '401': + description: Authentication required + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '403': + description: No permission to view the conversation + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: Conversation or snapshot not found content: application/json: schema: @@ -3676,11 +3618,11 @@ paths: own permissions, configuration, and identity. operationId: createAgent tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/TeamUidHeaderParam' + - $ref: '#/components/parameters/TeamUidHeaderParam' requestBody: required: true content: @@ -3695,7 +3637,7 @@ paths: schema: $ref: '#/components/schemas/AgentResponse' '400': - description: 'Invalid request (empty name, user on multiple teams, or on no team)' + description: Invalid request (empty name, user on multiple teams, or on no team) content: application/json: schema: @@ -3707,7 +3649,7 @@ paths: schema: $ref: '#/components/schemas/Error' '403': - description: 'Only human users can manage agents, or plan limit exceeded' + description: Only human users can manage agents, or plan limit exceeded content: application/json: schema: @@ -3724,19 +3666,19 @@ paths: List all agents on the caller's team. operationId: listAgents tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/TeamUidHeaderParam' - - name: factory_uid - in: query - required: false - description: | - Optional UID of a Factory to filter by. When provided, only agents - linked to that factory are returned. - schema: - type: string + - $ref: '#/components/parameters/TeamUidHeaderParam' + - name: factory_uid + in: query + required: false + description: | + Optional UID of a Factory to filter by. When provided, only agents + linked to that factory are returned. + schema: + type: string responses: '200': description: List of agents @@ -3745,7 +3687,7 @@ paths: schema: $ref: '#/components/schemas/ListAgentIdentitiesResponse' '400': - description: 'User on multiple teams, or on no team' + description: User on multiple teams, or on no team content: application/json: schema: @@ -3768,14 +3710,14 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - '/factory/{uid}/scorers': + /factory/{uid}/scorers: parameters: - - name: uid - in: path - description: UID of the factory that owns the scorer - required: true - schema: - type: string + - name: uid + in: path + description: UID of the factory that owns the scorer + required: true + schema: + type: string post: summary: Create a scorer description: | @@ -3785,9 +3727,9 @@ paths: request; the scorer and its self-improvement config are created atomically. operationId: createScorer tags: - - factory + - factory-scorers security: - - bearerAuth: [] + - bearerAuth: [] requestBody: required: true content: @@ -3838,32 +3780,32 @@ paths: and aggregate scoring stats. operationId: listScorers tags: - - agent + - factory-scorers security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/TeamUidHeaderParam' - - name: start_date - in: query - deprecated: true - description: | - Legacy summary range start (RFC3339 UTC, inclusive). Accepted - and validated for compatibility; does not affect the list - response. Must be provided together with end_date and be - strictly before it. - required: false - schema: - type: string - format: date-time - - name: end_date - in: query - deprecated: true - description: | - Legacy summary range end (RFC3339 UTC, exclusive). See start_date. - required: false - schema: - type: string - format: date-time + - $ref: '#/components/parameters/TeamUidHeaderParam' + - name: start_date + in: query + deprecated: true + description: | + Legacy summary range start (RFC3339 UTC, inclusive). Accepted + and validated for compatibility; does not affect the list + response. Must be provided together with end_date and be + strictly before it. + required: false + schema: + type: string + format: date-time + - name: end_date + in: query + deprecated: true + description: | + Legacy summary range end (RFC3339 UTC, exclusive). See start_date. + required: false + schema: + type: string + format: date-time responses: '200': description: Scorers for the factory @@ -3899,14 +3841,14 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - '/factory/{uid}/scorers/{scorer_uid}/results': + /factory/{uid}/scorers/{scorer_uid}/results: parameters: - - name: uid - in: path - description: UID of the factory that owns the scorer - required: true - schema: - type: string + - name: uid + in: path + description: UID of the factory that owns the scorer + required: true + schema: + type: string get: summary: List results for a scorer description: | @@ -3917,53 +3859,53 @@ paths: Reasons are read from object storage only when include_reasons is true. operationId: listScorerResults tags: - - agent + - factory-scorers security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/TeamUidHeaderParam' - - name: scorer_uid - in: path - description: The scorer identifier - required: true - schema: - type: string - description: Scorer UUID or temporary positive decimal integer ID. - - name: limit - in: query - description: 'Maximum number of results to return (1-100, default 50)' - required: false - schema: - type: integer - minimum: 1 - maximum: 100 - default: 50 - - name: cursor - in: query - description: Opaque cursor returned by a previous list response. - required: false - schema: + - $ref: '#/components/parameters/TeamUidHeaderParam' + - name: scorer_uid + in: path + description: The scorer identifier + required: true + schema: + type: string + description: Scorer UUID or temporary positive decimal integer ID. + - name: limit + in: query + description: Maximum number of results to return (1-100, default 50) + required: false + schema: + type: integer + minimum: 1 + maximum: 100 + default: 50 + - name: cursor + in: query + description: Opaque cursor returned by a previous list response. + required: false + schema: + type: string + - name: include_reasons + in: query + description: Include reason availability and readable judge reasoning. + required: false + schema: + type: boolean + default: false + - name: run_id + in: query + description: | + Exact run filters, repeated once per run. Values are trimmed and + deduplicated; require 1-100 distinct nonblank runs when present. + Cannot be combined with cursor or limit. + required: false + style: form + explode: true + schema: + type: array + items: type: string - - name: include_reasons - in: query - description: Include reason availability and readable judge reasoning. - required: false - schema: - type: boolean - default: false - - name: run_id - in: query - description: | - Exact run filters, repeated once per run. Values are trimmed and - deduplicated; require 1-100 distinct nonblank runs when present. - Cannot be combined with cursor or limit. - required: false - style: form - explode: true - schema: - type: array - items: - type: string responses: '200': description: Recent results for the scorer @@ -3972,7 +3914,7 @@ paths: schema: $ref: '#/components/schemas/ListScorerResultsResponse' '400': - description: 'Invalid scorer ID, limit, cursor, include_reasons, or run_id filters' + description: Invalid scorer ID, limit, cursor, include_reasons, or run_id filters content: application/json: schema: @@ -3997,14 +3939,14 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - '/factory/{uid}/scorers/{scorer_uid}/metrics': + /factory/{uid}/scorers/{scorer_uid}/metrics: parameters: - - name: uid - in: path - description: UID of the factory that owns the scorer - required: true - schema: - type: string + - name: uid + in: path + description: UID of the factory that owns the scorer + required: true + schema: + type: string get: summary: Get scorer metrics over a date range description: | @@ -4015,44 +3957,44 @@ paths: `GET /factory/{uid}/metrics`. operationId: getScorerMetrics tags: - - factory + - factory-scorers security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/TeamUidHeaderParam' - - name: scorer_uid - in: path - description: The scorer identifier - required: true - schema: - type: string - description: Scorer UUID or temporary positive decimal integer ID. - - name: start_date - in: query - description: 'RFC3339 UTC range start, inclusive. Defaults to 30 days before end_date.' - required: false - schema: - type: string - format: date-time - - name: end_date - in: query - description: 'RFC3339 UTC range end, exclusive. Defaults to now.' - required: false - schema: - type: string - format: date-time - - name: group_by_period - in: query - description: Binning granularity for the series. Defaults to day. - required: false - schema: - $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' - - name: include_cost - in: query - description: Include the scorer's judge-run cost for each period. Defaults to false. - required: false - schema: - type: boolean + - $ref: '#/components/parameters/TeamUidHeaderParam' + - name: scorer_uid + in: path + description: The scorer identifier + required: true + schema: + type: string + description: Scorer UUID or temporary positive decimal integer ID. + - name: start_date + in: query + description: RFC3339 UTC range start, inclusive. Defaults to 30 days before end_date. + required: false + schema: + type: string + format: date-time + - name: end_date + in: query + description: RFC3339 UTC range end, exclusive. Defaults to now. + required: false + schema: + type: string + format: date-time + - name: group_by_period + in: query + description: Binning granularity for the series. Defaults to day. + required: false + schema: + $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' + - name: include_cost + in: query + description: Include the scorer's judge-run cost for each period. Defaults to false. + required: false + schema: + type: boolean responses: '200': description: The scorer's pass-rate series and range aggregate @@ -4061,7 +4003,7 @@ paths: schema: $ref: '#/components/schemas/ScorerMetricsResponse' '400': - description: 'Invalid scorer ID, date range, group_by_period, or include_cost' + description: Invalid scorer ID, date range, group_by_period, or include_cost content: application/json: schema: @@ -4084,7 +4026,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - '/factory/{factory_uid}/runs/{run_id}/scorer_dispatch': + /factory/{factory_uid}/runs/{run_id}/scorer_dispatch: post: summary: Manually dispatch scorers for a run description: | @@ -4107,22 +4049,22 @@ paths: individual failures; inspect each result's `status` and `error`. operationId: dispatchRunScorers tags: - - factory + - factory-scorers security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: factory_uid - in: path - required: true - description: The factory containing the run and scorers. - schema: - type: string - - name: run_id - in: path - required: true - schema: - type: string - format: uuid + - name: factory_uid + in: path + required: true + description: The factory containing the run and scorers. + schema: + type: string + - name: run_id + in: path + required: true + schema: + type: string + format: uuid requestBody: required: true content: @@ -4131,8 +4073,8 @@ paths: $ref: '#/components/schemas/RunScorerDispatchRequest' example: scorer_uids: - - 0199b01b-b7c0-7000-8000-000000000007 - - 0199b01b-b7c0-7000-8000-000000000008 + - 0199b01b-b7c0-7000-8000-000000000007 + - 0199b01b-b7c0-7000-8000-000000000008 responses: '202': description: Per-pair dispatch outcomes; scoring completes asynchronously. @@ -4141,7 +4083,7 @@ paths: schema: $ref: '#/components/schemas/ManualScoringDispatchResponse' '400': - description: 'Invalid selection, ineligible run or scorer, or more than 100 scorer UUIDs.' + description: Invalid selection, ineligible run or scorer, or more than 100 scorer UUIDs. content: application/json: schema: @@ -4155,7 +4097,7 @@ paths: '403': $ref: '#/components/responses/FactoryAccessDenied' '404': - description: 'A named run or scorer does not exist, or the caller lacks access' + description: A named run or scorer does not exist, or the caller lacks access content: application/json: schema: @@ -4166,7 +4108,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - '/factory/{factory_uid}/scorers/{scorer_uid}/dispatch': + /factory/{factory_uid}/scorers/{scorer_uid}/dispatch: post: summary: Manually dispatch a scorer for selected runs description: | @@ -4189,22 +4131,22 @@ paths: individual failures; inspect each result's `status` and `error`. operationId: dispatchScorer tags: - - factory + - factory-scorers security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: factory_uid - in: path - required: true - description: The factory containing the scorer and runs. - schema: - type: string - - name: scorer_uid - in: path - required: true - schema: - type: string - format: uuid + - name: factory_uid + in: path + required: true + description: The factory containing the scorer and runs. + schema: + type: string + - name: scorer_uid + in: path + required: true + schema: + type: string + format: uuid requestBody: required: true content: @@ -4213,8 +4155,8 @@ paths: $ref: '#/components/schemas/ScorerDispatchRequest' example: run_ids: - - 0199b01b-b7c0-7000-8000-000000000001 - - 0199b01b-b7c0-7000-8000-000000000002 + - 0199b01b-b7c0-7000-8000-000000000001 + - 0199b01b-b7c0-7000-8000-000000000002 responses: '202': description: Per-pair dispatch outcomes; scoring completes asynchronously. @@ -4223,7 +4165,7 @@ paths: schema: $ref: '#/components/schemas/ManualScoringDispatchResponse' '400': - description: 'Invalid selection, ineligible run or scorer, or more than 100 run UUIDs.' + description: Invalid selection, ineligible run or scorer, or more than 100 run UUIDs. content: application/json: schema: @@ -4237,7 +4179,7 @@ paths: '403': $ref: '#/components/responses/FactoryAccessDenied' '404': - description: 'A named run or scorer does not exist, or the caller lacks access' + description: A named run or scorer does not exist, or the caller lacks access content: application/json: schema: @@ -4248,7 +4190,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - '/factory/runs/{run_id}/scores': + /factory/runs/{run_id}/scores: get: summary: Read a run's current scores description: | @@ -4259,16 +4201,16 @@ paths: the run. operationId: listRunScores tags: - - factory + - factory-scorers security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: run_id - in: path - description: The run identifier - required: true - schema: - type: string + - name: run_id + in: path + description: The run identifier + required: true + schema: + type: string responses: '200': description: The run's current scores @@ -4285,7 +4227,7 @@ paths: '403': $ref: '#/components/responses/FactoryAccessDenied' '404': - description: 'Run not found, or the caller cannot view it' + description: Run not found, or the caller cannot view it content: application/json: schema: @@ -4296,23 +4238,23 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - '/agent/identities/{uid}': + /agent/identities/{uid}: get: summary: Retrieve an agent description: | Retrieve a single agent by its unique identifier. operationId: getAgent tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: uid - in: path - description: The unique identifier of the agent - required: true - schema: - type: string + - name: uid + in: path + description: The unique identifier of the agent + required: true + schema: + type: string responses: '200': description: Agent details @@ -4344,16 +4286,16 @@ paths: Update an existing agent. operationId: updateAgent tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: uid - in: path - description: The unique identifier of the agent - required: true - schema: - type: string + - name: uid + in: path + description: The unique identifier of the agent + required: true + schema: + type: string requestBody: required: true content: @@ -4380,7 +4322,7 @@ paths: schema: $ref: '#/components/schemas/Error' '403': - description: 'Only human users can manage agents, or plan limit exceeded' + description: Only human users can manage agents, or plan limit exceeded content: application/json: schema: @@ -4404,16 +4346,16 @@ paths: agent are deleted atomically. operationId: deleteAgent tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: uid - in: path - description: The unique identifier of the agent - required: true - schema: - type: string + - name: uid + in: path + description: The unique identifier of the agent + required: true + schema: + type: string responses: '204': description: Agent deleted successfully @@ -4447,98 +4389,16 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - '/agent/sessions/{sessionUuid}/redirect': - get: - summary: Get session redirect - description: | - Check whether a shared session should redirect to a conversation - transcript, returning a conversation_id if the agent sandbox has - finished and conversation data is available (or an empty object if - no redirect is needed). Public and unauthenticated, so anonymous - viewers can resolve a shared session link before signing in; access - to the underlying transcript is still gated by conversation - link-sharing. - operationId: getSessionRedirect - tags: - - agent - security: [] - parameters: - - name: sessionUuid - in: path - description: The UUID of the shared session - required: true - schema: - type: string - responses: - '200': - description: | - Redirect information. Contains conversation_id if redirect is needed, - otherwise an empty object. - content: - application/json: - schema: - type: object - properties: - conversation_id: - type: string - description: The conversation ID to redirect to (only present when redirect is needed) - '500': - description: Internal server error - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - '/agent/conversations/{conversationId}/redirect': - get: - summary: Get conversation redirect - description: | - Check whether a conversation should redirect to a live shared - session, returning a session_id if the underlying ambient agent task - still has one (or an empty object if no redirect is needed). Public - and unauthenticated, so anonymous viewers can resolve a shared - conversation link before signing in; access to the underlying live - session is still gated by the session-sharing service ACLs. - operationId: getConversationRedirect - tags: - - agent - security: [] - parameters: - - name: conversationId - in: path - description: The ID of the conversation - required: true - schema: - type: string - responses: - '200': - description: | - Redirect information. Contains session_id if redirect is needed, - otherwise an empty object. - content: - application/json: - schema: - type: object - properties: - session_id: - type: string - description: The shared session UUID to redirect to (only present when redirect is needed) - '500': - description: Internal server error - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - '/factory/{factory_uid}/benchmarks': + /factory/{factory_uid}/benchmarks: post: summary: Create a benchmark suite operationId: createBenchmarkSuite tags: - - factory - - benchmark + - factory-benchmarks security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/BenchmarkFactoryPath' + - $ref: '#/components/parameters/BenchmarkFactoryPath' requestBody: required: true content: @@ -4582,25 +4442,24 @@ paths: summary: List benchmark suites operationId: listBenchmarkSuites tags: - - factory - - benchmark + - factory-benchmarks security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/BenchmarkFactoryPath' - - name: limit - in: query - required: false - schema: - type: integer - minimum: 1 - maximum: 100 - default: 50 - - name: cursor - in: query - required: false - schema: - type: string + - $ref: '#/components/parameters/BenchmarkFactoryPath' + - name: limit + in: query + required: false + schema: + type: integer + minimum: 1 + maximum: 100 + default: 50 + - name: cursor + in: query + required: false + schema: + type: string responses: '200': description: List of suites @@ -4622,18 +4481,17 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - '/factory/{factory_uid}/benchmarks/{suite_uid}': + /factory/{factory_uid}/benchmarks/{suite_uid}: get: summary: Get a benchmark suite with its tasks and configurations operationId: getBenchmarkSuite tags: - - factory - - benchmark + - factory-benchmarks security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/BenchmarkFactoryPath' - - $ref: '#/components/parameters/BenchmarkSuitePath' + - $ref: '#/components/parameters/BenchmarkFactoryPath' + - $ref: '#/components/parameters/BenchmarkSuitePath' responses: '200': description: Suite details @@ -4659,13 +4517,12 @@ paths: summary: Edit a benchmark suite operationId: patchBenchmarkSuite tags: - - factory - - benchmark + - factory-benchmarks security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/BenchmarkFactoryPath' - - $ref: '#/components/parameters/BenchmarkSuitePath' + - $ref: '#/components/parameters/BenchmarkFactoryPath' + - $ref: '#/components/parameters/BenchmarkSuitePath' requestBody: required: true content: @@ -4703,13 +4560,12 @@ paths: summary: Soft-delete a benchmark suite operationId: deleteBenchmarkSuite tags: - - factory - - benchmark + - factory-benchmarks security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/BenchmarkFactoryPath' - - $ref: '#/components/parameters/BenchmarkSuitePath' + - $ref: '#/components/parameters/BenchmarkFactoryPath' + - $ref: '#/components/parameters/BenchmarkSuitePath' responses: '204': description: Suite deleted @@ -4727,7 +4583,7 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - '/factory/{factory_uid}/benchmarks/{suite_uid}/tasks': + /factory/{factory_uid}/benchmarks/{suite_uid}/tasks: post: summary: Create a benchmark suite task description: | @@ -4741,13 +4597,12 @@ paths: is saved as a file and returned from that file. operationId: createBenchmarkSuiteTask tags: - - factory - - benchmark + - factory-benchmarks security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/BenchmarkFactoryPath' - - $ref: '#/components/parameters/BenchmarkSuitePath' + - $ref: '#/components/parameters/BenchmarkFactoryPath' + - $ref: '#/components/parameters/BenchmarkSuitePath' requestBody: required: true content: @@ -4776,35 +4631,34 @@ paths: '403': $ref: '#/components/responses/FactoryAccessDenied' '404': - description: 'Suite not found, or source_run_id is not a run the caller can read' + description: Suite not found, or source_run_id is not a run the caller can read content: application/problem+json: schema: $ref: '#/components/schemas/Error' '409': - description: 'Another task in this suite already has this title with different content, or the Factory is file-managed and cannot be written through' + description: Another task in this suite already has this title with different content, or the Factory is file-managed and cannot be written through content: application/problem+json: schema: $ref: '#/components/schemas/Error' - '/factory/{factory_uid}/benchmarks/{suite_uid}/tasks/{task_uid}': + /factory/{factory_uid}/benchmarks/{suite_uid}/tasks/{task_uid}: get: summary: Get one benchmark suite task operationId: getBenchmarkSuiteTask tags: - - factory - - benchmark + - factory-benchmarks security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/BenchmarkFactoryPath' - - $ref: '#/components/parameters/BenchmarkSuitePath' - - name: task_uid - in: path - required: true - schema: - type: string - format: uuid + - $ref: '#/components/parameters/BenchmarkFactoryPath' + - $ref: '#/components/parameters/BenchmarkSuitePath' + - name: task_uid + in: path + required: true + schema: + type: string + format: uuid responses: '200': description: Task details @@ -4827,7 +4681,7 @@ paths: '403': $ref: '#/components/responses/FactoryAccessDenied' '404': - description: 'Suite not found, task not found, or task_uid belongs to another suite' + description: Suite not found, task not found, or task_uid belongs to another suite content: application/problem+json: schema: @@ -4842,19 +4696,18 @@ paths: starting_repo_refs or tags clears that field. operationId: patchBenchmarkSuiteTask tags: - - factory - - benchmark + - factory-benchmarks security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/BenchmarkFactoryPath' - - $ref: '#/components/parameters/BenchmarkSuitePath' - - name: task_uid - in: path - required: true - schema: - type: string - format: uuid + - $ref: '#/components/parameters/BenchmarkFactoryPath' + - $ref: '#/components/parameters/BenchmarkSuitePath' + - name: task_uid + in: path + required: true + schema: + type: string + format: uuid requestBody: required: true content: @@ -4869,7 +4722,7 @@ paths: schema: $ref: '#/components/schemas/BenchmarkSuiteTask' '400': - description: 'Invalid request, or task_uid is not a valid UUID' + description: Invalid request, or task_uid is not a valid UUID content: application/problem+json: schema: @@ -4883,7 +4736,7 @@ paths: '403': $ref: '#/components/responses/FactoryAccessDenied' '404': - description: 'Suite not found, task not found, or task_uid belongs to another suite' + description: Suite not found, task not found, or task_uid belongs to another suite content: application/problem+json: schema: @@ -4898,19 +4751,18 @@ paths: summary: Delete one benchmark suite task operationId: deleteBenchmarkSuiteTask tags: - - factory - - benchmark + - factory-benchmarks security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/BenchmarkFactoryPath' - - $ref: '#/components/parameters/BenchmarkSuitePath' - - name: task_uid - in: path - required: true - schema: - type: string - format: uuid + - $ref: '#/components/parameters/BenchmarkFactoryPath' + - $ref: '#/components/parameters/BenchmarkSuitePath' + - name: task_uid + in: path + required: true + schema: + type: string + format: uuid responses: '204': description: Task deleted @@ -4929,7 +4781,7 @@ paths: '403': $ref: '#/components/responses/FactoryAccessDenied' '404': - description: 'Suite not found, task not found, or task_uid belongs to another suite' + description: Suite not found, task not found, or task_uid belongs to another suite content: application/problem+json: schema: @@ -4940,7 +4792,7 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - '/factory/{factory_uid}/benchmarks/{suite_uid}/runs': + /factory/{factory_uid}/benchmarks/{suite_uid}/runs: post: summary: Launch a benchmark run from the current suite version description: | @@ -4953,13 +4805,12 @@ paths: These options do not change execution retries within the benchmark run. operationId: launchBenchmarkRun tags: - - factory - - benchmark + - factory-benchmarks security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/BenchmarkFactoryPath' - - $ref: '#/components/parameters/BenchmarkSuitePath' + - $ref: '#/components/parameters/BenchmarkFactoryPath' + - $ref: '#/components/parameters/BenchmarkSuitePath' requestBody: required: true content: @@ -4976,8 +4827,8 @@ paths: value: repetition_count: 1 tasks: - - 7d69fb52-71c5-4e27-914e-8764ee9c5246 - - ad8ff7dc-a7d1-4ed6-9f50-650010bb39aa + - 7d69fb52-71c5-4e27-914e-8764ee9c5246 + - ad8ff7dc-a7d1-4ed6-9f50-650010bb39aa responses: '201': description: Run launched @@ -5016,39 +4867,38 @@ paths: information in `page_info`. Retained runs remain readable after the suite is deleted; an unknown suite returns an empty list. tags: - - factory - - benchmark + - factory-benchmarks security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/BenchmarkRunInclude' - - $ref: '#/components/parameters/BenchmarkFactoryPath' - - $ref: '#/components/parameters/BenchmarkSuitePath' - - name: state - in: query - required: false - schema: - type: array - items: - $ref: '#/components/schemas/BenchmarkRunState' - style: form - explode: true - - name: limit - in: query - required: false - schema: - type: integer - minimum: 1 - maximum: 100 - default: 50 - - name: cursor - in: query - required: false - schema: - type: string + - $ref: '#/components/parameters/BenchmarkRunInclude' + - $ref: '#/components/parameters/BenchmarkFactoryPath' + - $ref: '#/components/parameters/BenchmarkSuitePath' + - name: state + in: query + required: false + schema: + type: array + items: + $ref: '#/components/schemas/BenchmarkRunState' + style: form + explode: true + - name: limit + in: query + required: false + schema: + type: integer + minimum: 1 + maximum: 100 + default: 50 + - name: cursor + in: query + required: false + schema: + type: string responses: '200': - description: 'Runs from the frozen suite identity, including deleted suites; empty for an unknown suite' + description: Runs from the frozen suite identity, including deleted suites; empty for an unknown suite content: application/json: schema: @@ -5067,7 +4917,7 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - '/factory/{factory_uid}/benchmarks/{suite_uid}/runs/{run_uid}': + /factory/{factory_uid}/benchmarks/{suite_uid}/runs/{run_uid}: get: summary: Get benchmark run detail operationId: getBenchmarkRun @@ -5077,15 +4927,14 @@ paths: Use `include` to add these fields or the creator's display name. Retrieve trials separately for individual scores and execution history. tags: - - factory - - benchmark + - factory-benchmarks security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/BenchmarkRunInclude' - - $ref: '#/components/parameters/BenchmarkFactoryPath' - - $ref: '#/components/parameters/BenchmarkSuitePath' - - $ref: '#/components/parameters/BenchmarkRunPath' + - $ref: '#/components/parameters/BenchmarkRunInclude' + - $ref: '#/components/parameters/BenchmarkFactoryPath' + - $ref: '#/components/parameters/BenchmarkSuitePath' + - $ref: '#/components/parameters/BenchmarkRunPath' responses: '200': description: Run detail @@ -5107,19 +4956,18 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - '/factory/{factory_uid}/benchmarks/{suite_uid}/runs/{run_uid}/cancel': + /factory/{factory_uid}/benchmarks/{suite_uid}/runs/{run_uid}/cancel: post: summary: Cancel an in-flight benchmark run operationId: cancelBenchmarkRun tags: - - factory - - benchmark + - factory-benchmarks security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/BenchmarkFactoryPath' - - $ref: '#/components/parameters/BenchmarkSuitePath' - - $ref: '#/components/parameters/BenchmarkRunPath' + - $ref: '#/components/parameters/BenchmarkFactoryPath' + - $ref: '#/components/parameters/BenchmarkSuitePath' + - $ref: '#/components/parameters/BenchmarkRunPath' responses: '200': description: Run cancelled @@ -5147,47 +4995,7 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - '/factory/{factory_uid}/benchmarks/{suite_uid}/runs/{run_uid}/rescore': - post: - summary: Rescore missing results for a completed benchmark run - operationId: rescoreBenchmarkRun - tags: - - factory - - benchmark - security: - - bearerAuth: [] - parameters: - - $ref: '#/components/parameters/BenchmarkFactoryPath' - - $ref: '#/components/parameters/BenchmarkSuitePath' - - $ref: '#/components/parameters/BenchmarkRunPath' - responses: - '202': - description: Missing scores accepted for rescoring - content: - application/json: - schema: - $ref: '#/components/schemas/BenchmarkRunLaunchResponse' - '400': - description: Run is not eligible for rescoring - content: - application/problem+json: - schema: - $ref: '#/components/schemas/Error' - '401': - description: Authentication required - content: - application/problem+json: - schema: - $ref: '#/components/schemas/Error' - '403': - $ref: '#/components/responses/FactoryAccessDenied' - '404': - description: Run not found in this suite or action unavailable - content: - application/problem+json: - schema: - $ref: '#/components/schemas/Error' - '/factory/{factory_uid}/benchmarks/{suite_uid}/runs/{run_uid}/results': + /factory/{factory_uid}/benchmarks/{suite_uid}/runs/{run_uid}/results: get: summary: Get benchmark run results operationId: getBenchmarkRunResults @@ -5200,19 +5008,18 @@ paths: changing the summary or comparison populations. Results cover the whole selected dataset, independently of trial-list pages, and are not paginated. tags: - - factory - - benchmark + - factory-benchmarks security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/BenchmarkResultsInclude' - - $ref: '#/components/parameters/BenchmarkTaskSelection' - - $ref: '#/components/parameters/BenchmarkTagSelection' - - $ref: '#/components/parameters/BenchmarkConfigurationProjection' - - $ref: '#/components/parameters/BenchmarkScorerProjection' - - $ref: '#/components/parameters/BenchmarkFactoryPath' - - $ref: '#/components/parameters/BenchmarkSuitePath' - - $ref: '#/components/parameters/BenchmarkRunPath' + - $ref: '#/components/parameters/BenchmarkResultsInclude' + - $ref: '#/components/parameters/BenchmarkTaskSelection' + - $ref: '#/components/parameters/BenchmarkTagSelection' + - $ref: '#/components/parameters/BenchmarkConfigurationProjection' + - $ref: '#/components/parameters/BenchmarkScorerProjection' + - $ref: '#/components/parameters/BenchmarkFactoryPath' + - $ref: '#/components/parameters/BenchmarkSuitePath' + - $ref: '#/components/parameters/BenchmarkRunPath' responses: '200': description: Results aggregate (JSON) @@ -5234,7 +5041,7 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - '/factory/{factory_uid}/benchmarks/{suite_uid}/runs/{run_uid}/trials': + /factory/{factory_uid}/benchmarks/{suite_uid}/runs/{run_uid}/trials: get: summary: List benchmark trials or find the trial for an agent run operationId: listBenchmarkTrials @@ -5251,49 +5058,48 @@ paths: This lookup accepts `include` and an omitted `limit` or `limit=1`, but no cursor or other filters. Filtering by scorer is not supported. tags: - - factory - - benchmark + - factory-benchmarks security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/BenchmarkFactoryPath' - - $ref: '#/components/parameters/BenchmarkSuitePath' - - $ref: '#/components/parameters/BenchmarkRunPath' - - $ref: '#/components/parameters/BenchmarkTrialInclude' - - $ref: '#/components/parameters/BenchmarkTaskSelection' - - $ref: '#/components/parameters/BenchmarkTagSelection' - - name: configuration_uid - in: query - style: form - explode: true - schema: - type: array - items: - type: string - - name: state - in: query - style: form - explode: true - schema: - type: array - items: - $ref: '#/components/schemas/BenchmarkTrialState' - - name: agent_run_id - in: query - schema: - type: string - - name: limit - in: query - schema: - type: integer - default: 50 - minimum: 1 - maximum: 100 - - name: cursor - in: query - description: Pass the previous response's page_info.next_cursor with the same filters to retrieve the next page. - schema: + - $ref: '#/components/parameters/BenchmarkFactoryPath' + - $ref: '#/components/parameters/BenchmarkSuitePath' + - $ref: '#/components/parameters/BenchmarkRunPath' + - $ref: '#/components/parameters/BenchmarkTrialInclude' + - $ref: '#/components/parameters/BenchmarkTaskSelection' + - $ref: '#/components/parameters/BenchmarkTagSelection' + - name: configuration_uid + in: query + style: form + explode: true + schema: + type: array + items: type: string + - name: state + in: query + style: form + explode: true + schema: + type: array + items: + $ref: '#/components/schemas/BenchmarkTrialState' + - name: agent_run_id + in: query + schema: + type: string + - name: limit + in: query + schema: + type: integer + default: 50 + minimum: 1 + maximum: 100 + - name: cursor + in: query + description: Pass the previous response's page_info.next_cursor with the same filters to retrieve the next page. + schema: + type: string responses: '200': description: Complete requested Trial rows on one page @@ -5302,7 +5108,7 @@ paths: schema: $ref: '#/components/schemas/BenchmarkTrialList' '400': - description: 'Invalid selection, include, or cursor' + description: Invalid selection, include, or cursor content: application/problem+json: schema: @@ -5319,7 +5125,7 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - '/factory/{factory_uid}/benchmarks/{suite_uid}/runs/{run_uid}/trials/{trial_uid}': + /factory/{factory_uid}/benchmarks/{suite_uid}/runs/{run_uid}/trials/{trial_uid}: get: summary: Retrieve an individual benchmark trial within a run operationId: getBenchmarkTrial @@ -5330,20 +5136,19 @@ paths: execution attempts and judge history. Each requested expansion is complete. Selection and pagination parameters are not supported. tags: - - factory - - benchmark + - factory-benchmarks security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/BenchmarkFactoryPath' - - $ref: '#/components/parameters/BenchmarkSuitePath' - - $ref: '#/components/parameters/BenchmarkRunPath' - - $ref: '#/components/parameters/BenchmarkTrialInclude' - - name: trial_uid - in: path - required: true - schema: - type: string + - $ref: '#/components/parameters/BenchmarkFactoryPath' + - $ref: '#/components/parameters/BenchmarkSuitePath' + - $ref: '#/components/parameters/BenchmarkRunPath' + - $ref: '#/components/parameters/BenchmarkTrialInclude' + - name: trial_uid + in: path + required: true + schema: + type: string responses: '200': description: Logical Trial with complete requested expansions @@ -5377,15 +5182,15 @@ paths: with a link to each version's schema bundle. operationId: listFactoryFileSchemaVersions tags: - - factory + - factory security: [] parameters: - - name: If-None-Match - in: header - required: false - description: A previously returned ETag. A match returns 304 with no body. - schema: - type: string + - name: If-None-Match + in: header + required: false + description: A previously returned ETag. A match returns 304 with no body. + schema: + type: string responses: '200': description: The supported schema versions @@ -5403,7 +5208,7 @@ paths: $ref: '#/components/schemas/FactoryFileSchemaRegistry' '304': description: The cached response is still current - '/factory-files/schemas/{schema_version}': + /factory-files/schemas/{schema_version}: get: summary: Get the JSON Schema bundle for one Factory file schema version description: | @@ -5412,21 +5217,21 @@ paths: identities between the documents keep resolving. operationId: getFactoryFileSchemaBundle tags: - - factory + - factory security: [] parameters: - - name: schema_version - in: path - required: true - description: 'A Factory file schema version, for example `v1alpha1`.' - schema: - type: string - - name: If-None-Match - in: header - required: false - description: A previously returned ETag. A match returns 304 with no body. - schema: - type: string + - name: schema_version + in: path + required: true + description: A Factory file schema version, for example `v1alpha1`. + schema: + type: string + - name: If-None-Match + in: header + required: false + description: A previously returned ETag. A match returns 304 with no body. + schema: + type: string responses: '200': description: The schema documents for this version @@ -5450,7 +5255,7 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - '/factory-files/schemas/{schema_version}/{document}': + /factory-files/schemas/{schema_version}/{document}: get: summary: Get one Factory file schema document description: | @@ -5466,24 +5271,24 @@ paths: ``` operationId: getFactoryFileSchemaDocument tags: - - factory - security: [] - parameters: - - name: schema_version - in: path - required: true - schema: - type: string - description: 'Factory file schema version, such as v1alpha1' - - name: document - in: path - required: true - schema: - type: string - description: | - Document file name: common.schema.json, factory.schema.json, - agent.schema.json, automation.schema.json, runner.schema.json, or - scorer.schema.json + - factory + security: [] + parameters: + - name: schema_version + in: path + required: true + schema: + type: string + description: Factory file schema version, such as v1alpha1 + - name: document + in: path + required: true + schema: + type: string + description: | + Document file name: common.schema.json, factory.schema.json, + agent.schema.json, automation.schema.json, runner.schema.json, or + scorer.schema.json responses: '200': description: The requested JSON Schema document @@ -5506,6 +5311,14 @@ components: description: | Authentication via a Warp API key or a supported Warp-issued user token. parameters: + PresignedDownloadRedirect: + name: redirect + in: query + required: false + description: Set to false to return a signed storage URL as JSON rather than redirecting. + schema: + type: boolean + default: true BenchmarkFactoryPath: name: factory_uid in: path @@ -5546,9 +5359,9 @@ components: items: type: string enum: - - details - - summary_results - - creator_display_name + - details + - summary_results + - creator_display_name BenchmarkTrialInclude: name: include in: query @@ -5567,8 +5380,8 @@ components: items: type: string enum: - - results - - details + - results + - details BenchmarkResultsInclude: name: include in: query @@ -5587,10 +5400,10 @@ components: items: type: string enum: - - configuration_metrics - - scorer_configuration_metrics - - task_scorer_configuration_metrics - - agent_metrics + - configuration_metrics + - scorer_configuration_metrics + - task_scorer_configuration_metrics + - agent_metrics BenchmarkTaskSelection: name: task_uid in: query @@ -5655,9 +5468,107 @@ components: service-account callers, which always act as their bound team. schema: type: string + ConversationHistoryConversationId: + name: conversation_id + in: path + description: The UUID of the Warp-native conversation + required: true + schema: + type: string + format: uuid + headers: + ConversationHistoryCacheControl: + description: Prevents storage of canonical conversation history. + schema: + type: string + examples: + - no-store + ConversationHistoryRetryAfter: + description: | + Seconds to wait before re-requesting. Present only when + `X-Warp-Stream-State` is `pending`. + schema: + type: integer + examples: + - 2 + ConversationHistoryStreamState: + description: | + Whether a shared session can produce events for this conversation. + `active`: the newest session-linked execution is live; stream from + `X-Warp-Stream-Session` with `X-Warp-Stream-Cursor`. `pending`: no + session is live yet, but a hosted execution of the run is starting + and has not registered its shared session, or a queued follow-up is + waiting to start one; poll again after `Retry-After`. `ended`: no + execution is linked to a shared session or the newest one has ended, + and nothing is starting. + schema: + type: string + enum: + - active + - pending + - ended + ConversationHistoryStreamSession: + description: | + UUID of the shared session to stream from. Present only when + `X-Warp-Stream-State` is `active`. + schema: + type: string + format: uuid + ConversationHistoryStreamCursor: + description: | + Opaque logical cursor describing where the returned history + ends; pass it verbatim as `?cursor=` on the first connect to + the session-sharing event stream. Present only when + `X-Warp-Stream-State` is `active`. At most 512 bytes. + schema: + type: string + maxLength: 512 + ConversationHistoryRunId: + description: | + The run this conversation is served through: the run whose + execution owns the stream when `X-Warp-Stream-State` is + `active`, else the newest run for the conversation. Absent + when no run references the conversation. The + conversation-keyed steering routes act on this same run. + schema: + type: string responses: - FactoryAccessDenied: - description: Factory access is not enabled for the authenticated principal + FactoryBranchConflict: + description: | + Classified conflict with reason branch_sync_pending, branch_head_moved, + factory_source_changed, branch_deleted, or factory_scope_unavailable. + Pending synchronization, moving heads, and source changes are retryable; + deleted or unavailable identity is not. + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Error' + Unauthorized: + description: Authentication required + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Error' + FactoryBranchNotFound: + description: Hidden Factory, unknown or cross-Factory tracking, or disabled Branch surface + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Error' + FactoryBranchStatusResponse: + description: Current observation of the tracked Branch + headers: + Cache-Control: + schema: + type: string + enum: + - no-store + content: + application/json: + schema: + $ref: '#/components/schemas/FactoryBranchStatus' + FactoryBranchUnavailable: + description: Retryable resource_unavailable for source, synchronization, or database failure content: application/problem+json: schema: @@ -5676,46 +5587,55 @@ components: application/problem+json: schema: $ref: '#/components/schemas/Error' + FactoryAccessDenied: + description: Factory access is not enabled for the authenticated principal + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Error' schemas: EgressRangesResponse: type: object required: - - cidrs + - cidrs properties: cidrs: type: array items: type: string - description: 'Canonical, deduplicated IPv4 and IPv6 network ranges.' + description: Canonical, deduplicated IPv4 and IPv6 network ranges. FactoryFileSchemaRegistry: type: object description: The Factory file schema versions a server can describe. required: - - current_version - - versions + - current_version + - versions properties: current_version: type: string description: The version a new Factory tree should declare. - example: v1alpha1 + examples: + - v1alpha1 versions: type: array - description: 'Every supported version, sorted by schema version.' + description: Every supported version, sorted by schema version. items: $ref: '#/components/schemas/FactoryFileSchemaVersionRef' FactoryFileSchemaVersionRef: type: object required: - - schema_version - - schema_url + - schema_version + - schema_url properties: schema_version: type: string - example: v1alpha1 + examples: + - v1alpha1 schema_url: type: string description: Root-relative path of this version's schema bundle. - example: /api/v1/factory-files/schemas/v1alpha1 + examples: + - /api/v1/factory-files/schemas/v1alpha1 FactoryFileSchemaBundle: type: object description: | @@ -5723,39 +5643,40 @@ components: The envelope is plain JSON; each value in `documents` is a JSON Schema 2020-12 document keyed by its `$id`. required: - - schema_version - - documents + - schema_version + - documents properties: schema_version: type: string - example: v1alpha1 + examples: + - v1alpha1 documents: type: object - description: 'Schema documents keyed by file name, which is also each document''s $id.' + description: Schema documents keyed by file name, which is also each document's $id. additionalProperties: description: A JSON Schema 2020-12 document. Factory: type: object description: Public representation of a factory. required: - - uid - - team_uid - - name - - description - - alias - - avatar_url - - code_forge - - code_forges - - repositories - - default_environment - - default_model - - scoring - - credential_strategy - - integrations - - agent_defaults - - scorer_defaults - - created_at - - updated_at + - uid + - team_uid + - name + - description + - alias + - avatar_url + - code_forge + - code_forges + - repositories + - default_environment + - default_model + - scoring + - credential_strategy + - integrations + - agent_defaults + - scorer_defaults + - created_at + - updated_at properties: uid: type: string @@ -5767,18 +5688,21 @@ components: type: string description: Display name of the factory. description: - type: string - nullable: true + type: + - string + - 'null' description: Optional description of the factory. alias: - type: string - nullable: true + type: + - string + - 'null' description: | Optional display handle for the factory, unique across the team's Warp workspace when set. avatar_url: - type: string - nullable: true + type: + - string + - 'null' description: | Short-lived signed URL for displaying the factory's avatar. The URL may change between reads. @@ -5795,16 +5719,18 @@ components: type: array items: $ref: '#/components/schemas/FactoryRepository' - description: 'Repositories scoped to the factory, independent of its default environment.' + description: Repositories scoped to the factory, independent of its default environment. default_environment: - type: string - nullable: true + type: + - string + - 'null' description: | Public UID of the factory's default environment. File-managed factories may omit this default. default_model: - type: string - nullable: true + type: + - string + - 'null' description: | The default model ID for the factory's runs. File-managed factories may omit this default. Live-managed create and PATCH requests still @@ -5813,26 +5739,27 @@ components: $ref: '#/components/schemas/FactoryScoringConfig' self_improvement: allOf: - - $ref: '#/components/schemas/FactorySelfImprovementConfig' + - $ref: '#/components/schemas/FactorySelfImprovementConfig' readOnly: true - description: 'Self-improvement settings from the Factory YAML. Omitted when none are declared, in which case `self_improvement_defaults` apply.' + description: Self-improvement settings from the Factory YAML. Omitted when none are declared, in which case `self_improvement_defaults` apply. self_improvement_defaults: allOf: - - $ref: '#/components/schemas/FactorySelfImprovementDefaults' + - $ref: '#/components/schemas/FactorySelfImprovementDefaults' readOnly: true description: Server defaults applied to self-improvement settings the Factory does not declare. credential_strategy: allOf: - - $ref: '#/components/schemas/FactoryCredentialStrategy' + - $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 + type: + - array + - 'null' 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 @@ -5844,7 +5771,7 @@ components: $ref: '#/components/schemas/FactoryScorerDefaults' creator: allOf: - - $ref: '#/components/schemas/FactoryCreator' + - $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 @@ -5860,31 +5787,32 @@ components: description: Time the factory was last updated. FactoryCreator: type: object - description: 'The user who created a factory, when resolvable.' + description: The user who created a factory, when resolvable. required: - - uid + - 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.' + type: + - string + - 'null' + 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 + - default_runner_uid + - secrets + - mcp_servers + - worker_host properties: harness: allOf: - - $ref: '#/components/schemas/Harness' + - $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 @@ -5892,7 +5820,7 @@ components: also reported in the factory's default_model. harness_auth_secrets: allOf: - - $ref: '#/components/schemas/HarnessAuthSecrets' + - $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 @@ -5951,11 +5879,11 @@ components: reviewer_type: type: string enum: - - none - - admins - - team - - custom - description: 'Owning-team pool from which one eligible reviewer is randomly selected for self-improvement pull requests and Factory reviews in GitHub-managed or Warp-managed Factories. `admins` requests a team admin or owner. `team` requests any team member. `custom` requests a member listed in `reviewer_emails`. `none` explicitly disables reviewer assignment. Omitted when the Factory declares no pool, in which case `self_improvement_defaults.reviewer_type` applies.' + - none + - admins + - team + - custom + description: Owning-team pool from which one eligible reviewer is randomly selected for self-improvement pull requests and Factory reviews in GitHub-managed or Warp-managed Factories. `admins` requests a team admin or owner. `team` requests any team member. `custom` requests a member listed in `reviewer_emails`. `none` explicitly disables reviewer assignment. Omitted when the Factory declares no pool, in which case `self_improvement_defaults.reviewer_type` applies. failed_run_threshold: type: integer minimum: 1 @@ -5969,20 +5897,20 @@ components: description: 'Owning-team member emails reviewers are chosen from. Only allowed when `reviewer_type` is `custom`: a Factory YAML change that sets emails with any other reviewer type fails validation, including the pull request check.' model: type: string - description: 'The model self-improvement runs use, as a model ID or custom model router key. Falls back to `self_improvement_defaults.model` when not provided.' + description: The model self-improvement runs use, as a model ID or custom model router key. Falls back to `self_improvement_defaults.model` when not provided. FactorySelfImprovementDefaults: type: object required: - - failed_run_threshold - - reviewer_type - - model + - failed_run_threshold + - reviewer_type + - model properties: reviewer_type: type: string enum: - - none - - admins - - team + - none + - admins + - team description: Reviewer pool used when the Factory declares no `reviewer_type`. model: type: string @@ -5995,11 +5923,12 @@ components: FactoryScoringConfig: type: object required: - - default_model + - default_model properties: default_model: - type: string - nullable: true + type: + - string + - 'null' description: | Optional factory override for the model used by managed scorers and scorer-creation prefills. null or absent resolves to the platform @@ -6010,43 +5939,43 @@ components: description: | An integration provider attached to a factory. required: - - type + - type properties: type: $ref: '#/components/schemas/FactoryIntegrationProvider' linear: - allOf: - - $ref: '#/components/schemas/FactoryLinearIntegrationSettings' - nullable: true + oneOf: + - $ref: '#/components/schemas/FactoryLinearIntegrationSettings' + - type: 'null' description: | Linear team IDs from earlier integration selections, when present. Issue discovery follows enabled agent-session automations instead. jira: - allOf: - - $ref: '#/components/schemas/FactoryJiraIntegrationSettings' - nullable: true + oneOf: + - $ref: '#/components/schemas/FactoryJiraIntegrationSettings' + - type: 'null' description: | Jira project keys from earlier integration selections, when present. Issue discovery follows enabled agent-session automations instead. slack: - allOf: - - $ref: '#/components/schemas/FactorySlackIntegrationSettings' - nullable: true + oneOf: + - $ref: '#/components/schemas/FactorySlackIntegrationSettings' + - type: 'null' description: | Persisted Slack settings. Present only when type is slack and the factory has declared at least one Slack setting. Omitted fields keep their default-on behavior. microsoft-teams: - allOf: - - $ref: '#/components/schemas/FactoryTeamsIntegrationSettings' - nullable: true + oneOf: + - $ref: '#/components/schemas/FactoryTeamsIntegrationSettings' + - type: 'null' description: | Persisted Teams reply settings. Valid only when type is microsoft-teams. Omitted settings remain undeclared. FactoryLinearIntegrationSettings: type: object required: - - team_ids + - team_ids properties: team_ids: type: array @@ -6064,11 +5993,11 @@ components: Persisted Slack settings on a factory integration. Omitted fields keep their default-on behavior. allOf: - - $ref: '#/components/schemas/FactoryThreadReplySettings' + - $ref: '#/components/schemas/FactoryThreadReplySettings' FactoryTeamsIntegrationSettings: description: Persisted Teams reply settings on a factory integration. allOf: - - $ref: '#/components/schemas/FactoryThreadReplySettings' + - $ref: '#/components/schemas/FactoryThreadReplySettings' FactoryThreadReplySettings: type: object description: | @@ -6076,8 +6005,9 @@ components: per-Factory reply-setting rollout is enabled. properties: auto_respond_to_thread_replies: - type: boolean - nullable: true + type: + - boolean + - 'null' description: | When true, eligible plain channel thread replies still reach the reply-intent classifier. When false, those replies are ignored @@ -6086,7 +6016,7 @@ components: FactoryJiraIntegrationSettings: type: object required: - - project_keys + - project_keys properties: project_keys: type: array @@ -6106,10 +6036,10 @@ components: 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 - - microsoft-teams - - slack + - jira + - linear + - microsoft-teams + - slack FactoryCodeForge: type: string description: | @@ -6118,17 +6048,17 @@ components: forges. AZURE_DEVOPS identifies Azure Repos. NONE declares a repo-less factory with no native repositories; its environment relies on setup_commands to clone from any host. enum: - - GITHUB - - GITLAB - - AZURE_DEVOPS - - NONE + - GITHUB + - GITLAB + - AZURE_DEVOPS + - NONE FactoryRepositoryCodeForge: type: string description: The concrete source-control provider hosting a repository. enum: - - GITHUB - - GITLAB - - AZURE_DEVOPS + - GITHUB + - GITLAB + - AZURE_DEVOPS FactoryCredentialStrategy: type: string description: | @@ -6140,14 +6070,14 @@ components: - CREATOR: runs authenticate with the credentials of the principal that created the run. enum: - - CREATOR - - EXECUTOR + - CREATOR + - EXECUTOR FactoryRepository: type: object description: A repository scoped to a factory. required: - - owner - - repo + - owner + - repo properties: owner: type: string @@ -6157,7 +6087,7 @@ components: description: Repository name. code_forge: allOf: - - $ref: '#/components/schemas/FactoryRepositoryCodeForge' + - $ref: '#/components/schemas/FactoryRepositoryCodeForge' description: | The concrete forge hosting this repository. Omitted means the factory's primary code_forge. @@ -6165,7 +6095,7 @@ components: type: object additionalProperties: type: string - description: 'Provider-specific repository identity and settings, such as the Azure DevOps organization, project ID, and repository ID.' + description: Provider-specific repository identity and settings, such as the Azure DevOps organization, project ID, and repository ID. FactoryTaskStage: type: string description: | @@ -6176,12 +6106,12 @@ components: the task's current top-level run is cancelled, regardless of that run's agent type. enum: - - TRIAGE - - SPEC - - IMPLEMENT - - REVIEW - - COMPLETE - - CANCELLED + - TRIAGE + - SPEC + - IMPLEMENT + - REVIEW + - COMPLETE + - CANCELLED FactoryTaskCurrentRun: type: object description: | @@ -6189,9 +6119,9 @@ components: conversation at read time. This differs from FactoryTask.run_id, which is a creation-time provenance snapshot and is never updated. required: - - run_id - - state - - is_run_type_cancellable + - run_id + - state + - is_run_type_cancellable properties: run_id: type: string @@ -6209,15 +6139,22 @@ components: A factory task: the unit of work in a factory, bound to the agent conversation that owns it. required: - - uid - - factory_uid - - conversation_id - - run_id - - title - - stage - - created_at - - updated_at + - uid + - factory_uid + - conversation_id + - run_id + - title + - stage + - created_at + - updated_at properties: + config_source: + allOf: + - $ref: '#/components/schemas/FactoryConfigSource' + description: | + Derived from the immutable stored creation run_id, never the + conversation's latest run. Omitted when any required association + has been purged or provenance is otherwise unavailable. uid: type: string description: Public UID of the task. @@ -6236,7 +6173,7 @@ components: resolve it via the conversation. author: allOf: - - $ref: '#/components/schemas/RunCreatorInfo' + - $ref: '#/components/schemas/RunCreatorInfo' description: | Creator of the run captured by run_id. Omitted when the creation run or its creator principal can no longer be resolved. @@ -6254,8 +6191,9 @@ components: Canonical ticket ID from the bound run. Present on list responses only when full_list=true and ticket metadata exists. description: - type: string - nullable: true + type: + - string + - 'null' description: Optional description of the task. stage: $ref: '#/components/schemas/FactoryTaskStage' @@ -6285,203 +6223,18 @@ components: only, not the wider run tree. current_run: allOf: - - $ref: '#/components/schemas/FactoryTaskCurrentRun' + - $ref: '#/components/schemas/FactoryTaskCurrentRun' description: | The task's current top-level run, resolved at read time. Present on single-task reads (by uid, by conversation, and after a stop request), and on list responses when include_current_run=true; omitted when no current root run can be resolved. - FactoryTaskNotificationKind: - type: string - description: The action requested by a Factory notification. - enum: - - question - - answer_question - - spec_review - - pr_review - - blocked - - failed - FactoryInboxScope: - type: string - description: Personal or team-wide Factory Inbox visibility. - enum: - - mine - - team - default: mine - FactoryInboxRecipient: - type: object - description: Minimal public identity for a live notification recipient. - required: - - uid - properties: - uid: - type: string - description: Public Warp user UID. - email: - type: string - format: email - description: 'Recipient email, when available.' - FactoryAttentionQuestion: - type: object - required: - - id - - question - - type - - options - properties: - id: - type: string - question: - type: string - type: - type: string - enum: - - single_select - - multi_select - options: - type: array - items: - type: string - recommended_option_index: - type: integer - FactoryInboxArtifact: - type: object - description: An inbox artifact link with an optional provider PR/MR title. - required: - - url - properties: - url: - type: string - description: Artifact URL. - title: - type: string - description: 'Known provider PR/MR title, when available.' - FactoryInboxItem: - type: object - description: One shared unresolved notification in the Factory Inbox. - required: - - notification_uid - - factory_uid - - factory_task_uid - - title - - stage - - kind - - created_at - - recipients - properties: - notification_uid: - type: string - description: Identifier accepted by the dismiss endpoint. - factory_uid: - type: string - factory_task_uid: - type: string - title: - type: string - description: Notification headline. - stage: - $ref: '#/components/schemas/FactoryTaskStage' - kind: - allOf: - - $ref: '#/components/schemas/FactoryTaskNotificationKind' - is_read: - type: boolean - description: | - Whether the authenticated user has read this notification. - Always present in `mine` scope, including when false. - Omitted in `team` scope, even when filtering by recipient. - description: - type: string - description: 'Notification body, when present.' - questions: - type: array - items: - $ref: '#/components/schemas/FactoryAttentionQuestion' - origin_link: - type: string - description: 'Server-derived link back to the task''s origin, when present.' - url: - type: string - description: Legacy first artifact URL supplied by a review notification. - urls: - type: array - minItems: 1 - maxItems: 20 - items: - type: string - description: Legacy artifact URLs; prefer artifacts for links and titles. - artifacts: - type: array - items: - $ref: '#/components/schemas/FactoryInboxArtifact' - description: Ordered artifact links with optional provider PR/MR titles. - run_id: - type: string - minLength: 1 - description: | - Producing run ID from factory_task_notifications.created_by_run_id. - Present when the producing run is known. - created_at: - type: string - format: date-time - description: Notification declaration time. - recipients: - type: array - items: - $ref: '#/components/schemas/FactoryInboxRecipient' - description: | - Live, undismissed recipients for this shared notification, sorted - deterministically. Slack routing and personal dismissal state are - not exposed. - ListFactoryInboxResponse: - type: object - required: - - items - - page_info - properties: - items: - type: array - items: - $ref: '#/components/schemas/FactoryInboxItem' - page_info: - $ref: '#/components/schemas/PageInfo' - FactoryInboxMutationRequest: - type: object - required: - - notification_uids - properties: - notification_uids: - type: array - minItems: 1 - maxItems: 10000 - uniqueItems: true - items: - type: string - FactoryInboxMutationOutcome: - type: object - required: - - notification_uid - - ok - properties: - notification_uid: - type: string - ok: - type: boolean - FactoryInboxMutationResponse: - type: object - required: - - outcomes - properties: - outcomes: - type: array - items: - $ref: '#/components/schemas/FactoryInboxMutationOutcome' FactoryTaskCreateRequest: type: object description: Request body for creating a factory task. required: - - title - - conversation_id + - title + - conversation_id properties: title: type: string @@ -6492,10 +6245,12 @@ components: UUID of the agent conversation to bind the task to. The conversation's most recent run must be owned by the factory's team, and the conversation must not already be bound to a live - task. + task. Confirmed Branch scope must belong to the requested + Factory. Binding cannot grant execution scope. description: - type: string - nullable: true + type: + - string + - 'null' description: Optional description of the task. stage: $ref: '#/components/schemas/FactoryTaskStage' @@ -6509,22 +6264,23 @@ components: type: string description: Updated title. Must be non-empty when provided. description: - type: string - nullable: true + type: + - string + - 'null' description: Updated description. null or an empty string clears the description. stage: $ref: '#/components/schemas/FactoryTaskStage' ListFactoryTasksResponse: type: object required: - - tasks - - page_info + - tasks + - page_info properties: tasks: type: array items: $ref: '#/components/schemas/FactoryTask' - description: 'One page of the factory''s tasks, in the requested sort order.' + description: One page of the factory's tasks, in the requested sort order. page_info: $ref: '#/components/schemas/PageInfo' FactoryMetricsGroupByPeriod: @@ -6533,9 +6289,9 @@ components: Binning granularity for factory metrics series. Weeks start on Sunday (UTC), consistent with existing Warp analytics. enum: - - day - - week - - month + - day + - week + - month FactoryDollarsBreakdown: type: object description: | @@ -6546,10 +6302,10 @@ components: amount; charges recorded before billed amounts were tracked fall back to an estimated cost. required: - - compute - - platform - - inference - - total + - compute + - platform + - inference + - total properties: compute: type: number @@ -6569,10 +6325,10 @@ components: Per-period dollar series aligned to period_list, zero-filled for periods with no attributed cost. required: - - compute - - platform - - inference - - total + - compute + - platform + - inference + - total properties: compute: type: array @@ -6601,7 +6357,7 @@ components: per-period series when group_by_period was requested. Grouped breakdowns (drill-down) may be added as new fields in the future. required: - - total + - total properties: total: type: integer @@ -6621,7 +6377,7 @@ components: plus a per-period series when group_by_period was requested. The aggregate and periods with no qualifying PRs read zero. required: - - average + - average properties: average: type: number @@ -6637,14 +6393,14 @@ components: format: double FactoryCostPerPRSeries: type: object - description: 'Per-period cost-per-PR series, aligned to period_list.' + description: Per-period cost-per-PR series, aligned to period_list. required: - - pr_count - - dollars - - mean - - compute_mean - - platform_mean - - inference_mean + - pr_count + - dollars + - mean + - compute_mean + - platform_mean + - inference_mean properties: pr_count: type: array @@ -6660,36 +6416,40 @@ components: Mean per-PR attributed cost per period, in US dollars; null for periods with zero PRs. items: - type: number + type: + - number + - 'null' format: double - nullable: true compute_mean: type: array description: | Mean per-PR compute cost per period, in US dollars; null for periods with zero PRs. items: - type: number + type: + - number + - 'null' format: double - nullable: true platform_mean: type: array description: | Mean per-PR platform cost per period, in US dollars; null for periods with zero PRs. items: - type: number + type: + - number + - 'null' format: double - nullable: true inference_mean: type: array description: | Mean per-PR inference cost per period, in US dollars; null for periods with zero PRs. items: - type: number + type: + - number + - 'null' format: double - nullable: true FactoryCostPerPRMetric: type: object description: | @@ -6698,9 +6458,9 @@ components: never double-counted), reported as the arithmetic mean of the per-PR costs. required: - - pr_count - - dollars - - mean + - pr_count + - dollars + - mean properties: pr_count: type: integer @@ -6712,9 +6472,10 @@ components: dollars: $ref: '#/components/schemas/FactoryDollarsBreakdown' mean: - type: number + type: + - number + - 'null' format: double - nullable: true description: | Mean per-PR attributed cost, in US dollars; null when pr_count is 0. @@ -6722,23 +6483,23 @@ components: $ref: '#/components/schemas/FactoryCostPerPRSeries' FactoryCostPerPRResponse: allOf: - - $ref: '#/components/schemas/FactoryMetricsEnvelope' - - type: object - required: - - data - properties: - group_by_period: - $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' - period_list: - type: array - description: | - Period labels every series aligns to (dates like 2026-07-01; - weeks labeled by their Sunday start date). Present only when - group_by_period was requested. - items: - type: string - data: - $ref: '#/components/schemas/FactoryCostPerPRMetric' + - $ref: '#/components/schemas/FactoryMetricsEnvelope' + - type: object + required: + - data + properties: + group_by_period: + $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' + period_list: + type: array + description: | + Period labels every series aligns to (dates like 2026-07-01; + weeks labeled by their Sunday start date). Present only when + group_by_period was requested. + items: + type: string + data: + $ref: '#/components/schemas/FactoryCostPerPRMetric' FactoryCostBreakdownGroupBy: type: string description: | @@ -6746,10 +6507,10 @@ components: roll each run tree's cost to the root run; agent and model keep each run's own cost. enum: - - source - - user - - agent - - model + - source + - user + - agent + - model FactoryCostBreakdownGroup: type: object description: | @@ -6761,9 +6522,9 @@ components: entity behind a User or Agent key has been soft-deleted since incurring the spend; always false for Source/Model and UNKNOWN. required: - - key - - deleted - - dollars + - key + - deleted + - dollars properties: key: type: string @@ -6778,7 +6539,7 @@ components: $ref: '#/components/schemas/FactoryDollarsBreakdown' series: allOf: - - $ref: '#/components/schemas/FactoryDollarsBreakdownSeries' + - $ref: '#/components/schemas/FactoryDollarsBreakdownSeries' description: | One entry per period_list entry, zero-filled. Present only when group_by_period was requested. @@ -6789,8 +6550,8 @@ components: ascending on ties) with UNKNOWN always last. The server never caps or folds groups — every entity with nonzero spend is listed. required: - - total - - groups + - total + - groups properties: total: $ref: '#/components/schemas/FactoryDollarsBreakdown' @@ -6800,36 +6561,36 @@ components: $ref: '#/components/schemas/FactoryCostBreakdownGroup' FactoryCostBreakdownResponse: allOf: - - $ref: '#/components/schemas/FactoryMetricsEnvelope' - - type: object - required: - - group_by - - data - properties: - group_by: - $ref: '#/components/schemas/FactoryCostBreakdownGroupBy' - group_by_period: - $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' - period_list: - type: array - description: | - Period labels every series aligns to (dates like 2026-07-01; - weeks labeled by their Sunday start date). Present only when - group_by_period was requested. - items: - type: string - data: - $ref: '#/components/schemas/FactoryCostBreakdownData' + - $ref: '#/components/schemas/FactoryMetricsEnvelope' + - type: object + required: + - group_by + - data + properties: + group_by: + $ref: '#/components/schemas/FactoryCostBreakdownGroupBy' + group_by_period: + $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' + period_list: + type: array + description: | + Period labels every series aligns to (dates like 2026-07-01; + weeks labeled by their Sunday start date). Present only when + group_by_period was requested. + items: + type: string + data: + $ref: '#/components/schemas/FactoryCostBreakdownData' FactoryMetricsData: type: object required: - - run_count - - pr_count - - merged_pr_count - - autonomy_funnel - - impact - - pr_latency - - average_human_interactions_per_pr + - run_count + - pr_count + - merged_pr_count + - autonomy_funnel + - impact + - pr_latency + - average_human_interactions_per_pr properties: run_count: $ref: '#/components/schemas/FactoryMetricCount' @@ -6837,7 +6598,7 @@ components: $ref: '#/components/schemas/FactoryMetricCount' merged_pr_count: allOf: - - $ref: '#/components/schemas/FactoryMetricCount' + - $ref: '#/components/schemas/FactoryMetricCount' description: | Merged PRs, bucketed by the day the PR was created (merge day when the creation time was never observed) so the series reads @@ -6854,7 +6615,7 @@ components: $ref: '#/components/schemas/FactoryPRLatency' average_human_interactions_per_pr: allOf: - - $ref: '#/components/schemas/FactoryAverageMetric' + - $ref: '#/components/schemas/FactoryAverageMetric' description: | Average qualifying human interactions per factory-attributed PR in the range. The numerator includes live PR interactions with a @@ -6877,11 +6638,11 @@ components: observed (factory_merged_observed); sourced from webhook-collected PR facts, so coverage starts when collection began. required: - - total_merged - - factory_merged - - factory_merged_observed - - merged_without_human_code_change - - repos + - total_merged + - factory_merged + - factory_merged_observed + - merged_without_human_code_change + - repos properties: total_merged: type: integer @@ -6924,10 +6685,10 @@ components: webhook payloads and can be unobserved, so additions/deletions sum only the measured_pr_count PRs where both were recorded. required: - - additions - - deletions - - merged_pr_count - - measured_pr_count + - additions + - deletions + - merged_pr_count + - measured_pr_count properties: additions: type: integer @@ -6954,13 +6715,14 @@ components: PRs where both of the stage's endpoints were observed, plus how many PRs that was. required: - - median_seconds - - measured_pr_count + - median_seconds + - measured_pr_count properties: median_seconds: - type: number + type: + - number + - 'null' format: double - nullable: true description: | p50 stage duration in seconds; null when measured_pr_count is zero. Durations are clamped at zero, so out-of-order provider @@ -6984,11 +6746,11 @@ components: PRs where both endpoints were observed, so stage medians do not sum to kickoff_to_merge's median. required: - - merged_pr_count - - kickoff_to_pr - - pr_to_first_review - - first_review_to_merge - - kickoff_to_merge + - merged_pr_count + - kickoff_to_pr + - pr_to_first_review + - first_review_to_merge + - kickoff_to_merge properties: merged_pr_count: type: integer @@ -6996,28 +6758,28 @@ components: description: PRs produced by this factory's runs and merged in the range. kickoff_to_pr: allOf: - - $ref: '#/components/schemas/FactoryLatencyStage' + - $ref: '#/components/schemas/FactoryLatencyStage' description: Run kickoff to PR creation. pr_to_first_review: allOf: - - $ref: '#/components/schemas/FactoryLatencyStage' + - $ref: '#/components/schemas/FactoryLatencyStage' description: PR creation to the first observed human review. first_review_to_merge: allOf: - - $ref: '#/components/schemas/FactoryLatencyStage' + - $ref: '#/components/schemas/FactoryLatencyStage' description: First observed human review to merge. kickoff_to_merge: allOf: - - $ref: '#/components/schemas/FactoryLatencyStage' - description: 'Run kickoff to merge, measured end to end per PR.' + - $ref: '#/components/schemas/FactoryLatencyStage' + description: Run kickoff to merge, measured end to end per PR. FactoryPullRequestState: type: string description: The pull request's current state. enum: - - open - - draft - - merged - - closed + - open + - draft + - merged + - closed FactoryPullRequestHumanInteractions: type: object description: | @@ -7030,16 +6792,16 @@ components: GitHub comment counts once, as a PR comment or review. total is the sum of every type. required: - - opened - - code_push - - review_approved - - review_changes_requested - - review_commented - - comment - - review_comment - - pr_action - - follow_up_message - - total + - opened + - code_push + - review_approved + - review_changes_requested + - review_commented + - comment + - review_comment + - pr_action + - follow_up_message + - total properties: opened: type: integer @@ -7075,7 +6837,7 @@ components: pr_action: type: integer format: int64 - description: 'Other PR actions by a person, such as closed, reopened, or marked ready.' + description: Other PR actions by a person, such as closed, reopened, or marked ready. follow_up_message: type: integer format: int64 @@ -7088,9 +6850,9 @@ components: type: object description: One of the factory's runs that produced the pull request. required: - - run_id - - root_run_id - - created_at + - run_id + - root_run_id + - created_at properties: run_id: type: string @@ -7108,57 +6870,61 @@ components: Kickoff is when the earliest run that produced the PR was created; first review is the first review by a person. required: - - kickoff_to_pr - - pr_to_first_review - - first_review_to_merge - - kickoff_to_merge + - kickoff_to_pr + - pr_to_first_review + - first_review_to_merge + - kickoff_to_merge properties: kickoff_to_pr: - type: number + type: + - number + - 'null' format: double - nullable: true pr_to_first_review: - type: number + type: + - number + - 'null' format: double - nullable: true first_review_to_merge: - type: number + type: + - number + - 'null' format: double - nullable: true kickoff_to_merge: - type: number + type: + - number + - 'null' format: double - nullable: true FactoryPullRequest: type: object description: | One pull request produced by the factory's runs. Fields the code host has not reported yet (title, size counts, times) are null. required: - - provider - - repo_full_name - - pr_number - - url - - title - - author_login - - factory_uid - - team_uid - - state - - opened_at - - first_human_review_at - - merged_at - - closed_at - - updated_at - - additions - - deletions - - changed_files - - num_commits - - human_interactions - - human_code_change - - history_complete - - runs - - kickoff_at - - cycle_time + - provider + - repo_full_name + - pr_number + - url + - title + - author_login + - factory_uid + - team_uid + - state + - opened_at + - first_human_review_at + - merged_at + - closed_at + - updated_at + - additions + - deletions + - changed_files + - num_commits + - human_interactions + - human_code_change + - history_complete + - runs + - kickoff_at + - cycle_time properties: provider: $ref: '#/components/schemas/FactoryRepositoryCodeForge' @@ -7172,12 +6938,14 @@ components: type: string description: Canonical PR URL. title: - type: string - nullable: true + type: + - string + - 'null' description: The PR title; null until the code host reports it. author_login: - type: string - nullable: true + type: + - string + - 'null' description: The code-host login that opened the PR. factory_uid: type: string @@ -7188,44 +6956,52 @@ components: state: $ref: '#/components/schemas/FactoryPullRequestState' opened_at: - type: string + type: + - string + - 'null' format: date-time - nullable: true description: When the PR was opened; null when Warp did not see it being opened. first_human_review_at: - type: string + type: + - string + - 'null' format: date-time - nullable: true description: The first review by a person; null when none was observed. merged_at: - type: string + type: + - string + - 'null' format: date-time - nullable: true description: When the PR was merged; null while it is not merged. closed_at: - type: string + type: + - string + - 'null' format: date-time - nullable: true - description: 'When the PR was closed, by merging or otherwise; null while it is open or when the code host did not report it.' + description: When the PR was closed, by merging or otherwise; null while it is open or when the code host did not report it. updated_at: type: string format: date-time description: When the PR itself last changed; the updated_after filter compares against it. additions: - type: integer - nullable: true + type: + - integer + - 'null' description: Lines added; null until the code host reports it. deletions: - type: integer - nullable: true + type: + - integer + - 'null' description: Lines deleted; null until the code host reports it. changed_files: - type: integer - nullable: true + type: + - integer + - 'null' description: Files changed; null until the code host reports it. num_commits: - type: integer - nullable: true + type: + - integer + - 'null' description: Commits on the PR; null until the code host reports it. human_interactions: $ref: '#/components/schemas/FactoryPullRequestHumanInteractions' @@ -7243,31 +7019,32 @@ components: missing from the counts. runs: type: array - description: 'The factory''s runs that produced the PR, earliest first.' + description: The factory's runs that produced the PR, earliest first. items: $ref: '#/components/schemas/FactoryPullRequestRun' kickoff_at: - type: string + type: + - string + - 'null' format: date-time - nullable: true description: When the earliest run that produced the PR was created. cycle_time: $ref: '#/components/schemas/FactoryPullRequestCycleTime' FactoryPullRequestsResponse: allOf: - - $ref: '#/components/schemas/FactoryMetricsEnvelope' - - type: object - required: - - data - - page_info - properties: - data: - type: array - description: Newest opened first. - items: - $ref: '#/components/schemas/FactoryPullRequest' - page_info: - $ref: '#/components/schemas/PageInfo' + - $ref: '#/components/schemas/FactoryMetricsEnvelope' + - type: object + required: + - data + - page_info + properties: + data: + type: array + description: Newest opened first. + items: + $ref: '#/components/schemas/FactoryPullRequest' + page_info: + $ref: '#/components/schemas/PageInfo' FactoryTopPR: type: object description: | @@ -7277,9 +7054,9 @@ components: PR has been deleted; the remaining fields are null when the PR predates webhook PR-fact collection. required: - - url - - dollars - - models + - url + - dollars + - models properties: url: type: string @@ -7287,19 +7064,21 @@ components: dollars: $ref: '#/components/schemas/FactoryDollarsBreakdown' creator: - allOf: - - $ref: '#/components/schemas/RunCreatorInfo' - nullable: true + oneOf: + - $ref: '#/components/schemas/RunCreatorInfo' + - type: 'null' description: Who started the run that kicked off the PR. source: - type: string - nullable: true + type: + - string + - 'null' description: | Public source name of the run that kicked off the PR (e.g. GITHUB_WEBHOOK, SLACK, API). New values may appear over time. requested_model_id: - type: string - nullable: true + type: + - string + - 'null' description: | Model the kicking-off run was configured with; null means the server default was used. @@ -7315,121 +7094,140 @@ components: items: $ref: '#/components/schemas/FactoryTopPRModel' provider: - allOf: - - $ref: '#/components/schemas/FactoryRepositoryCodeForge' - nullable: true + oneOf: + - $ref: '#/components/schemas/FactoryRepositoryCodeForge' + - type: 'null' description: The code host the PR lives on. repo_full_name: - type: string - nullable: true + type: + - string + - 'null' description: The repository as owner/repo. pr_number: - type: integer - nullable: true + type: + - integer + - 'null' description: The provider's PR number. title: - type: string - nullable: true + type: + - string + - 'null' description: The PR title; null until the code host reports it. author_login: - type: string - nullable: true + type: + - string + - 'null' description: The code-host login that opened the PR. factory_uid: - type: string - nullable: true + type: + - string + - 'null' description: Public UID of the factory whose runs produced the PR. team_uid: - type: string - nullable: true + type: + - string + - 'null' description: Public UID of the team that owns the factory. state: - allOf: - - $ref: '#/components/schemas/FactoryPullRequestState' - nullable: true + oneOf: + - $ref: '#/components/schemas/FactoryPullRequestState' + - type: 'null' description: The PR's current state. opened_at: - type: string + type: + - string + - 'null' format: date-time - nullable: true description: When the PR was opened; null when Warp did not see it being opened. first_human_review_at: - type: string + type: + - string + - 'null' format: date-time - nullable: true description: The first review by a person; null when none was observed. merged_at: - type: string + type: + - string + - 'null' format: date-time - nullable: true description: When the PR was merged; null while it is not merged. closed_at: - type: string + type: + - string + - 'null' format: date-time - nullable: true - description: 'When the PR was closed, by merging or otherwise; null while it is open or when the code host did not report it.' + description: When the PR was closed, by merging or otherwise; null while it is open or when the code host did not report it. updated_at: - type: string + type: + - string + - 'null' format: date-time - nullable: true description: When the PR itself last changed. additions: - type: integer - nullable: true + type: + - integer + - 'null' description: Lines added; null until the code host reports it. deletions: - type: integer - nullable: true + type: + - integer + - 'null' description: Lines deleted; null until the code host reports it. changed_files: - type: integer - nullable: true + type: + - integer + - 'null' description: Files changed; null until the code host reports it. num_commits: - type: integer - nullable: true + type: + - integer + - 'null' description: Commits on the PR; null until the code host reports it. human_interactions: - allOf: - - $ref: '#/components/schemas/FactoryPullRequestHumanInteractions' - nullable: true - description: 'Actions people took on the PR, counted by type.' + oneOf: + - $ref: '#/components/schemas/FactoryPullRequestHumanInteractions' + - type: 'null' + description: Actions people took on the PR, counted by type. human_code_change: - type: boolean - nullable: true + type: + - boolean + - 'null' description: | Whether a person changed the PR's code: any opened or code_push interaction. False only means autonomous when history_complete is true. history_complete: - type: boolean - nullable: true + type: + - boolean + - 'null' description: | Whether Warp observed the PR from the moment it was opened. When false, interactions before Warp started watching the PR are missing from the counts. runs: - type: array - nullable: true - description: 'The factory''s runs that produced the PR, earliest first.' + type: + - array + - 'null' + description: The factory's runs that produced the PR, earliest first. items: $ref: '#/components/schemas/FactoryPullRequestRun' kickoff_at: - type: string + type: + - string + - 'null' format: date-time - nullable: true description: When the earliest run that produced the PR was created. cycle_time: - allOf: - - $ref: '#/components/schemas/FactoryPullRequestCycleTime' - nullable: true + oneOf: + - $ref: '#/components/schemas/FactoryPullRequestCycleTime' + - type: 'null' description: The PR's pipeline-stage durations in seconds. FactoryTopPRModel: type: object description: One model's share of a top PR's inference cost. required: - - model_id - - inference_dollars + - model_id + - inference_dollars properties: model_id: type: string @@ -7442,16 +7240,16 @@ components: attribution. FactoryTopPRsResponse: allOf: - - $ref: '#/components/schemas/FactoryMetricsEnvelope' - - type: object - required: - - data - properties: - data: - type: array - description: Most expensive first. - items: - $ref: '#/components/schemas/FactoryTopPR' + - $ref: '#/components/schemas/FactoryMetricsEnvelope' + - type: object + required: + - data + properties: + data: + type: array + description: Most expensive first. + items: + $ref: '#/components/schemas/FactoryTopPR' FactoryMetricsEnvelope: type: object description: | @@ -7459,9 +7257,9 @@ components: data, so responses from several factories can be combined or told apart. required: - - as_of - - team_uid - - factory_uid + - as_of + - team_uid + - factory_uid properties: as_of: type: string @@ -7477,23 +7275,23 @@ components: description: Public UID of the factory the response is scoped to. FactoryMetricsResponse: allOf: - - $ref: '#/components/schemas/FactoryMetricsEnvelope' - - type: object - required: - - data - properties: - group_by_period: - $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' - period_list: - type: array - description: | - Period labels every series aligns to (dates like 2026-07-01; - weeks labeled by their Sunday start date). Present only when - group_by_period was requested. - items: - type: string - data: - $ref: '#/components/schemas/FactoryMetricsData' + - $ref: '#/components/schemas/FactoryMetricsEnvelope' + - type: object + required: + - data + properties: + group_by_period: + $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' + period_list: + type: array + description: | + Period labels every series aligns to (dates like 2026-07-01; + weeks labeled by their Sunday start date). Present only when + group_by_period was requested. + items: + type: string + data: + $ref: '#/components/schemas/FactoryMetricsData' FactoryRunBreakdownGroupBy: type: string description: | @@ -7501,12 +7299,12 @@ components: top-level runs only; every other dimension counts subruns individually. enum: - - agent_type - - status - - source - - root_vs_subrun - - model - - harness + - agent_type + - status + - source + - root_vs_subrun + - model + - harness FactoryRunBreakdownGroup: type: object description: | @@ -7518,8 +7316,8 @@ components: names, source aliases) and is absent where the key is already the display form. required: - - key - - total + - key + - total properties: key: type: string @@ -7544,9 +7342,9 @@ components: then OTHER; group totals and series sum to total and its per-period distribution. required: - - total - - root_run_count - - groups + - total + - root_run_count + - groups properties: total: type: integer @@ -7572,36 +7370,36 @@ components: $ref: '#/components/schemas/FactoryRunBreakdownGroup' FactoryRunBreakdownResponse: allOf: - - $ref: '#/components/schemas/FactoryMetricsEnvelope' - - type: object - required: - - group_by - - data - properties: - group_by: - $ref: '#/components/schemas/FactoryRunBreakdownGroupBy' - group_by_period: - $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' - period_list: - type: array - description: | - Period labels every series aligns to (dates like 2026-07-01; - weeks labeled by their Sunday start date). Present only when - group_by_period was requested. - items: - type: string - data: - $ref: '#/components/schemas/FactoryRunBreakdownData' + - $ref: '#/components/schemas/FactoryMetricsEnvelope' + - type: object + required: + - group_by + - data + properties: + group_by: + $ref: '#/components/schemas/FactoryRunBreakdownGroupBy' + group_by_period: + $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' + period_list: + type: array + description: | + Period labels every series aligns to (dates like 2026-07-01; + weeks labeled by their Sunday start date). Present only when + group_by_period was requested. + items: + type: string + data: + $ref: '#/components/schemas/FactoryRunBreakdownData' FactoryPRSizeBucket: type: string description: | A PR's T-shirt size, derived from its webhook-collected line counts (additions + deletions): S < 100, M < 500, L < 1000, XL >= 1000. enum: - - S - - M - - L - - XL + - S + - M + - L + - XL FactoryCostByPRSizeBucket: type: object description: | @@ -7609,9 +7407,9 @@ components: cost_per_pr attribution (even run-tree split, in the US dollars the owning team was billed). required: - - size - - pr_count - - mean + - size + - pr_count + - mean properties: size: $ref: '#/components/schemas/FactoryPRSizeBucket' @@ -7620,9 +7418,10 @@ components: format: int64 description: Sized PRs in this bucket first seen in the range. mean: - type: number + type: + - number + - 'null' format: double - nullable: true description: | Mean per-PR attributed cost in US dollars; null when the bucket has no PRs in the range. @@ -7633,9 +7432,10 @@ components: for periods where the bucket has no PRs. Present only when group_by_period was requested. items: - type: number + type: + - number + - 'null' format: double - nullable: true FactoryCostByPRSizeData: type: object description: | @@ -7645,14 +7445,14 @@ components: difference is the PRs whose line counts were never observed and are excluded from every bucket. required: - - pr_count - - sized_pr_count - - buckets + - pr_count + - sized_pr_count + - buckets properties: pr_count: type: integer format: int64 - description: 'Every PR first seen in the range, sized or not.' + description: Every PR first seen in the range, sized or not. sized_pr_count: type: integer format: int64 @@ -7663,29 +7463,89 @@ components: $ref: '#/components/schemas/FactoryCostByPRSizeBucket' FactoryCostByPRSizeResponse: allOf: - - $ref: '#/components/schemas/FactoryMetricsEnvelope' - - type: object - required: - - data - properties: - group_by_period: - $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' - period_list: - type: array - description: | - Period labels every series aligns to (dates like 2026-07-01; - weeks labeled by their Sunday start date). Present only when - group_by_period was requested. - items: - type: string - data: - $ref: '#/components/schemas/FactoryCostByPRSizeData' + - $ref: '#/components/schemas/FactoryMetricsEnvelope' + - type: object + required: + - data + properties: + group_by_period: + $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' + period_list: + type: array + description: | + Period labels every series aligns to (dates like 2026-07-01; + weeks labeled by their Sunday start date). Present only when + group_by_period was requested. + items: + type: string + data: + $ref: '#/components/schemas/FactoryCostByPRSizeData' + FactorySyncItem: + type: object + description: A single factory sync history/status row. + required: + - id + - factory_uid + - target_sha + - trigger + - status + - created_at + - updated_at + properties: + id: + type: integer + description: Internal sync row ID. + factory_uid: + type: string + description: Public UID of the factory. + target_sha: + type: string + description: Target commit SHA for the sync attempt. + trigger: + type: string + description: What initiated the sync attempt. + enum: + - webhook + - explicit_apply + - anti_entropy + - source_link + status: + $ref: '#/components/schemas/FactorySyncItemStatus' + plan_summary: + type: + - string + - 'null' + description: Optional human-readable plan summary for the sync. + diagnostics: + type: string + description: | + Raw persisted structured diagnostics JSON for the sync attempt + (parse errors, dependency failures, etc.). Empty when the sync + had no diagnostics. This POC field carries the persisted JSON + string verbatim; a future revision may replace it with a + structured schema. + created_at: + type: string + format: date-time + description: Time the sync row was created. + updated_at: + type: string + format: date-time + description: Time the sync row was last updated. + FactorySyncItemStatus: + type: string + description: Outcome of a sync attempt. + enum: + - running + - success + - failed + - noop ListFactoriesResponse: type: object description: Response body for listing factories. required: - - factories - - page_info + - factories + - page_info properties: factories: type: array @@ -7697,8 +7557,18 @@ components: type: object description: Request body for dispatching a run to a factory. required: - - prompt + - prompt properties: + branch: + type: string + nullable: true + description: | + Exact named head in the registered source repository, optionally + prefixed with refs/heads/. Case and slashes are preserved. + Omission, null, or the registered production branch uses + production. Empty strings, revision expressions, tags, forks, + and alternate repository coordinates are not accepted. + Non-production selection is rejected when factory_branches is off. prompt: type: string description: | @@ -7724,12 +7594,15 @@ components: type: object description: Response body for a dispatched factory run. required: - - run_id - - state - - factory_uid - - foreman_agent - - ticket_ref + - run_id + - state + - factory_uid + - foreman_agent + - ticket_ref properties: + config_source: + allOf: + - $ref: '#/components/schemas/FactoryConfigSource' run_id: type: string description: Unique identifier for the dispatched run. @@ -7752,6 +7625,97 @@ components: The canonical : ticket reference the run was stamped with, either the caller-supplied ticket_ref or a minted adhoc reference. + FactoryConfigSource: + type: object + description: | + Branch namespace and registered source-generation identity derived + from the run's execution Agent and required root/Branch associations. + Omitted for production or unavailable provenance; omission does not + establish production scope. No historical configuration revision or + retention guarantee is provided. + required: + - branch + - branch_uid + - source_generation + properties: + branch: + type: string + minLength: 1 + description: Case-sensitive named head, without refs/heads/. + branch_uid: + type: string + minLength: 1 + description: Immutable tracking namespace UID. + source_generation: + type: string + minLength: 1 + description: Fingerprint of the registered source generation. + FactoryBranchState: + type: string + enum: + - UNSYNCED + - SYNCING + - FRESH + - STALE + - FAILED + - UNKNOWN + - DELETED + FactoryBranchStatus: + type: object + description: | + Read-only observation of an existing Branch. UNKNOWN means the + current source could not be verified, never permission to execute. + Lifecycle SHA fields describe current synchronization, not a run's + historical creation revision. + required: + - uid + - factory_uid + - branch + - source_generation + - state + - last_success_sha + - current_head_sha + - last_synced_at + - latest_attempt + - freshness_checked_at + - last_error + properties: + uid: + type: string + factory_uid: + type: string + branch: + type: string + source_generation: + type: string + state: + $ref: '#/components/schemas/FactoryBranchState' + last_success_sha: + type: + - string + - 'null' + current_head_sha: + type: + - string + - 'null' + last_synced_at: + type: + - string + - 'null' + format: date-time + latest_attempt: + oneOf: + - $ref: '#/components/schemas/FactorySyncItem' + - type: 'null' + description: Latest persisted attempt with externally safe diagnostics. + freshness_checked_at: + type: string + format: date-time + last_error: + oneOf: + - $ref: '#/components/schemas/Error' + - type: 'null' + description: Classified, externally safe source-verification failure. ClaudeHarnessUsagePayload: type: object additionalProperties: false @@ -7759,8 +7723,9 @@ components: usage: $ref: '#/components/schemas/ClaudeTokenUsage' attribution: - type: array - nullable: true + type: + - array + - 'null' items: $ref: '#/components/schemas/ClaudeAttributedUsage' toolCalls: @@ -7772,23 +7737,26 @@ components: usage: $ref: '#/components/schemas/CodexTokenUsage' attribution: - type: array - nullable: true + type: + - array + - 'null' items: $ref: '#/components/schemas/CodexAttributedUsage' toolCalls: $ref: '#/components/schemas/HarnessToolCalls' HarnessUsageCounter: - type: integer + type: + - integer + - 'null' format: int64 minimum: 0 maximum: 9223372036854775807 - nullable: true - description: 'A native count. Absent or null means unmeasured, not zero.' + description: A native count. Absent or null means unmeasured, not zero. ClaudeTokenUsage: - type: object + type: + - object + - 'null' additionalProperties: false - nullable: true description: Native cumulative token categories; cache counters are not added to input_tokens. properties: input_tokens: @@ -7802,18 +7770,20 @@ components: cache_creation: $ref: '#/components/schemas/ClaudeCacheCreationUsage' ClaudeCacheCreationUsage: - type: object + type: + - object + - 'null' additionalProperties: false - nullable: true properties: ephemeral_5m_input_tokens: $ref: '#/components/schemas/HarnessUsageCounter' ephemeral_1h_input_tokens: $ref: '#/components/schemas/HarnessUsageCounter' CodexTokenUsage: - type: object + type: + - object + - 'null' additionalProperties: false - nullable: true description: Native checkpoint counters. Cached input and reasoning output may overlap other categories; no derived total is inferred. properties: input_tokens: @@ -7832,49 +7802,58 @@ components: type: object additionalProperties: false required: - - usage + - usage properties: model: - type: string - nullable: true + type: + - string + - 'null' service_tier: - type: string - nullable: true + type: + - string + - 'null' inference_geo: - type: string - nullable: true + type: + - string + - 'null' speed: - type: string - nullable: true + type: + - string + - 'null' usage: $ref: '#/components/schemas/ClaudeTokenUsage' CodexAttributedUsage: type: object additionalProperties: false required: - - usage + - usage properties: model: - type: string - nullable: true + type: + - string + - 'null' service_tier: - type: string - nullable: true + type: + - string + - 'null' inference_geo: - type: string - nullable: true + type: + - string + - 'null' speed: - type: string - nullable: true + type: + - string + - 'null' usage: $ref: '#/components/schemas/CodexTokenUsage' HarnessToolCalls: - type: object + type: + - object + - 'null' additionalProperties: false - nullable: true required: - - total - - byName + - total + - byName description: Native tool invocation counts. Total must equal the sum of byName; tool names are arbitrary map keys. properties: total: @@ -7892,9 +7871,9 @@ components: GetRunHarnessUsageResponse: type: object required: - - run_id - - conversation_id - - available + - run_id + - conversation_id + - available properties: run_id: type: string @@ -7903,15 +7882,16 @@ components: available: type: boolean age_seconds: - type: integer + type: + - integer + - 'null' format: int64 - nullable: true usage: $ref: '#/components/schemas/HarnessUsageEnvelope' HarnessUsageEnvelope: oneOf: - - $ref: '#/components/schemas/ClaudeHarnessUsageEnvelope' - - $ref: '#/components/schemas/CodexHarnessUsageEnvelope' + - $ref: '#/components/schemas/ClaudeHarnessUsageEnvelope' + - $ref: '#/components/schemas/CodexHarnessUsageEnvelope' discriminator: propertyName: harness mapping: @@ -7921,22 +7901,22 @@ components: type: object additionalProperties: false required: - - metricsVersion - - harness - - executionId - - captureSequence - - capturedAt - - snapshot + - metricsVersion + - harness + - executionId + - captureSequence + - capturedAt + - snapshot properties: metricsVersion: type: integer enum: - - 1 - description: 'Server-owned storage format metadata, not the producer''s parser version.' + - 1 + description: Server-owned storage format metadata, not the producer's parser version. harness: type: string enum: - - CLAUDE_CODE + - CLAUDE_CODE executionId: type: integer format: int64 @@ -7950,8 +7930,8 @@ components: type: object additionalProperties: false required: - - coverage - - payload + - coverage + - payload properties: coverage: $ref: '#/components/schemas/RetainedHarnessUsageCoverage' @@ -7961,22 +7941,22 @@ components: type: object additionalProperties: false required: - - metricsVersion - - harness - - executionId - - captureSequence - - capturedAt - - snapshot + - metricsVersion + - harness + - executionId + - captureSequence + - capturedAt + - snapshot properties: metricsVersion: type: integer enum: - - 1 - description: 'Server-owned storage format metadata, not the producer''s parser version.' + - 1 + description: Server-owned storage format metadata, not the producer's parser version. harness: type: string enum: - - CODEX + - CODEX executionId: type: integer format: int64 @@ -7990,8 +7970,8 @@ components: type: object additionalProperties: false required: - - coverage - - payload + - coverage + - payload properties: coverage: $ref: '#/components/schemas/RetainedHarnessUsageCoverage' @@ -8001,21 +7981,21 @@ components: type: object additionalProperties: false required: - - tokenStatus - - toolStatus + - tokenStatus + - toolStatus properties: tokenStatus: type: string enum: - - known - - partial - - unavailable + - known + - partial + - unavailable toolStatus: type: string enum: - - known - - partial - - unavailable + - known + - partial + - unavailable RunAgentRequest: type: object description: | @@ -8114,9 +8094,9 @@ components: RunAgentResponse: type: object required: - - run_id - - task_id - - state + - run_id + - task_id + - state properties: run_id: type: string @@ -8138,17 +8118,17 @@ components: - 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 + - normal + - plan + - orchestrate default: normal ListRunsResponse: type: object required: - - runs - - page_info - - as_of - - team_uid + - runs + - page_info + - as_of + - team_uid properties: runs: type: array @@ -8161,8 +8141,9 @@ components: format: date-time description: Time the runs were read (RFC3339). Data can lag live activity by a few minutes. team_uid: - type: string - nullable: true + type: + - string + - 'null' description: | UID of the team the request was scoped to: the team selected by the `X-Warp-Team-Uid` header, or the API key's team. Null when a user @@ -8171,15 +8152,15 @@ components: RunItem: type: object required: - - run_id - - task_id - - title - - state - - prompt - - created_at - - finished_at - - updated_at - - root_run_id + - run_id + - task_id + - title + - state + - prompt + - created_at + - finished_at + - updated_at + - root_run_id properties: run_id: type: string @@ -8200,7 +8181,7 @@ components: description: The prompt/instruction for the agent submitted_prompt: type: string - description: 'The prompt exactly as it was submitted, without any extra context added by Warp. Includes any follow-up messages sent before the run started, separated by blank lines.' + description: The prompt exactly as it was submitted, without any extra context added by Warp. Includes any follow-up messages sent before the run started, separated by blank lines. created_at: type: string format: date-time @@ -8212,16 +8193,18 @@ components: run_time: type: string format: duration - description: 'Total runtime as an ISO 8601 duration (e.g. "PT2M30S"), computed server-side from run executions.' + description: Total runtime as an ISO 8601 duration (e.g. "PT2M30S"), computed server-side from run executions. started_at: - type: string + type: + - string + - 'null' format: date-time - nullable: true description: Timestamp when the agent started working on the run (RFC3339) finished_at: - type: string + type: + - string + - 'null' format: date-time - nullable: true description: | Timestamp when the run last reached a terminal state (RFC3339). Null while the run is still active, and for terminal runs with no @@ -8243,7 +8226,7 @@ components: trigger_url: type: string format: uri - description: 'URL to the run trigger (e.g. Slack thread, Linear issue, schedule)' + description: URL to the run trigger (e.g. Slack thread, Linear issue, schedule) creator: $ref: '#/components/schemas/RunCreatorInfo' executor: @@ -8290,7 +8273,7 @@ components: type: array items: $ref: '#/components/schemas/ArtifactItem' - description: 'Artifacts created during the run (plans, pull requests, etc.)' + description: Artifacts created during the run (plans, pull requests, etc.) agent_skill: $ref: '#/components/schemas/AgentSkill' scope: @@ -8299,7 +8282,7 @@ components: type: object description: Response body for listing run timeline events. required: - - events + - events properties: events: type: array @@ -8309,10 +8292,10 @@ components: type: object description: A setup or lifecycle event recorded for an agent run. required: - - event_uuid - - run_id - - event_type - - occurred_at + - event_uuid + - run_id + - event_type + - occurred_at properties: event_uuid: type: string @@ -8323,7 +8306,7 @@ components: execution_id: type: integer format: int64 - description: 'Run execution associated with this event, when available.' + description: Run execution associated with this event, when available. event_type: $ref: '#/components/schemas/AIRunTimelineEventType' occurred_at: @@ -8338,23 +8321,23 @@ components: type: string description: Type of timeline event recorded for a run. enum: - - oz_run_created - - oz_run_claimed - - worker_container_ready - - shared_session_started - - agent_started - - oz_run_done - - oz_run_blocked - - oz_run_cancelled - - oz_run_failed - - oz_run_errored - - vm_shutdown - - run_retry_scheduled + - oz_run_created + - oz_run_claimed + - worker_container_ready + - shared_session_started + - agent_started + - oz_run_done + - oz_run_blocked + - oz_run_cancelled + - oz_run_failed + - oz_run_errored + - vm_shutdown + - run_retry_scheduled ConversationResponse: type: object required: - - conversation_id - - steps + - conversation_id + - steps properties: conversation_id: type: string @@ -8367,9 +8350,9 @@ components: ConversationStep: type: object required: - - id - - messages - - steps + - id + - messages + - steps properties: id: type: string @@ -8401,8 +8384,8 @@ components: ConversationMessage: type: object required: - - role - - content + - role + - content properties: message_ids: type: array @@ -8411,7 +8394,7 @@ components: type: string request_id: type: string - description: 'Request identifier shared by transcript messages from the same request, when available' + description: Request identifier shared by transcript messages from the same request, when available role: $ref: '#/components/schemas/ConversationMessageRole' timestamp: @@ -8426,16 +8409,16 @@ components: type: string description: Role of the normalized message enum: - - user - - assistant - - tool - - system + - user + - assistant + - tool + - system ConversationContentBlock: oneOf: - - $ref: '#/components/schemas/TextContentBlock' - - $ref: '#/components/schemas/ActionContentBlock' - - $ref: '#/components/schemas/ActionResultContentBlock' - - $ref: '#/components/schemas/EventContentBlock' + - $ref: '#/components/schemas/TextContentBlock' + - $ref: '#/components/schemas/ActionContentBlock' + - $ref: '#/components/schemas/ActionResultContentBlock' + - $ref: '#/components/schemas/EventContentBlock' discriminator: propertyName: type mapping: @@ -8446,16 +8429,16 @@ components: TextContentBlock: type: object required: - - type - - text + - type + - text properties: type: type: string enum: - - text + - text message_id: type: string - description: 'Underlying transcript message ID that produced this content block, when available' + description: Underlying transcript message ID that produced this content block, when available text: type: string description: Plain text content @@ -8463,38 +8446,38 @@ components: type: string description: High-level category of an action performed during the conversation enum: - - command - - files - - search - - integration - - documents - - computer - - review - - skill + - command + - files + - search + - integration + - documents + - computer + - review + - skill ActionState: type: string description: State of an action result enum: - - running - - completed - - failed - - denied + - running + - completed + - failed + - denied ActionContentBlock: type: object required: - - type - - id - - category - - name - - input + - type + - id + - category + - name + - input properties: type: type: string enum: - - action + - action message_id: type: string - description: 'Underlying transcript message ID that produced this content block, when available' + description: Underlying transcript message ID that produced this content block, when available id: type: string description: Unique identifier for the action @@ -8502,7 +8485,7 @@ components: $ref: '#/components/schemas/ActionCategory' name: type: string - description: 'Public action name, such as run_command or edit_files' + description: Public action name, such as run_command or edit_files input: type: object additionalProperties: true @@ -8510,20 +8493,20 @@ components: ActionResultContentBlock: type: object required: - - type - - action_id - - category - - name - - state - - output + - type + - action_id + - category + - name + - state + - output properties: type: type: string enum: - - action_result + - action_result message_id: type: string - description: 'Underlying transcript message ID that produced this content block, when available' + description: Underlying transcript message ID that produced this content block, when available action_id: type: string description: Identifier of the corresponding action @@ -8541,17 +8524,17 @@ components: EventContentBlock: type: object required: - - type - - name - - data + - type + - name + - data properties: type: type: string enum: - - event + - event message_id: type: string - description: 'Underlying transcript message ID that produced this content block, when available' + 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 @@ -8561,11 +8544,11 @@ components: 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' + - $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: @@ -8577,14 +8560,14 @@ components: ExternalReferenceArtifact: type: object required: - - artifact_type - - created_at - - data + - artifact_type + - created_at + - data properties: artifact_type: type: string enum: - - EXTERNAL_REFERENCE + - EXTERNAL_REFERENCE description: Type of the artifact created_at: type: string @@ -8595,14 +8578,14 @@ components: PlanArtifact: type: object required: - - artifact_type - - created_at - - data + - artifact_type + - created_at + - data properties: artifact_type: type: string enum: - - PLAN + - PLAN description: Type of the artifact created_at: type: string @@ -8613,14 +8596,14 @@ components: PullRequestArtifact: type: object required: - - artifact_type - - created_at - - data + - artifact_type + - created_at + - data properties: artifact_type: type: string enum: - - PULL_REQUEST + - PULL_REQUEST description: Type of the artifact created_at: type: string @@ -8631,14 +8614,14 @@ components: ScreenshotArtifact: type: object required: - - artifact_type - - created_at - - data + - artifact_type + - created_at + - data properties: artifact_type: type: string enum: - - SCREENSHOT + - SCREENSHOT description: Type of the artifact created_at: type: string @@ -8649,14 +8632,14 @@ components: FileArtifact: type: object required: - - artifact_type - - created_at - - data + - artifact_type + - created_at + - data properties: artifact_type: type: string enum: - - FILE + - FILE description: Type of the artifact created_at: type: string @@ -8667,11 +8650,11 @@ components: PlanArtifactData: type: object required: - - document_uid + - document_uid properties: artifact_uid: type: string - description: 'Unique identifier for the plan artifact, usable with the artifact retrieval endpoint' + description: Unique identifier for the plan artifact, usable with the artifact retrieval endpoint document_uid: type: string description: Unique identifier for the plan document @@ -8688,8 +8671,8 @@ components: PullRequestArtifactData: type: object required: - - url - - branch + - url + - branch properties: url: type: string @@ -8700,29 +8683,29 @@ components: description: Branch name for the pull request PullRequestArtifactResponseData: allOf: - - $ref: '#/components/schemas/PullRequestArtifactData' - - type: object - required: - - status - properties: - status: - type: string - description: | - Current state of the pull request as last reported by the code - host's webhooks. `unknown` means Warp has no live provider - record for this pull request (for example, the repository's - code host integration is not connected to the run's team). - enum: - - open - - draft - - merged - - closed - - unknown + - $ref: '#/components/schemas/PullRequestArtifactData' + - type: object + required: + - status + properties: + status: + type: string + description: | + Current state of the pull request as last reported by the code + host's webhooks. `unknown` means Warp has no live provider + record for this pull request (for example, the repository's + code host integration is not connected to the run's team). + enum: + - open + - draft + - merged + - closed + - unknown ScreenshotArtifactData: type: object required: - - artifact_uid - - mime_type + - artifact_uid + - mime_type properties: artifact_uid: type: string @@ -8736,10 +8719,10 @@ components: FileArtifactData: type: object required: - - artifact_uid - - filepath - - filename - - mime_type + - artifact_uid + - filepath + - filename + - mime_type properties: artifact_uid: type: string @@ -8772,25 +8755,21 @@ components: $ref: '#/components/schemas/FileArtifactThumbnail' FileArtifactThumbnail: type: object + description: The companion thumbnail image of a video recording. required: - - download_url - - expires_at + - download_url properties: download_url: type: string format: uri - description: Time-limited signed URL to download the video's thumbnail image - expires_at: - type: string - format: date-time - description: Timestamp when the thumbnail download URL expires (RFC3339) + description: Stable URL of the thumbnail image. Requires authentication. ScheduleInfo: type: object description: Information about the schedule that triggered this run (only present for scheduled runs) required: - - schedule_id - - schedule_name - - cron_schedule + - schedule_id + - schedule_name + - cron_schedule properties: schedule_id: type: string @@ -8804,7 +8783,7 @@ components: PageInfo: type: object required: - - has_next_page + - has_next_page properties: has_next_page: type: boolean @@ -8818,7 +8797,7 @@ components: Status message for a run. For terminal error states, includes structured error code and retryability info from the platform error catalog. required: - - message + - message properties: message: type: string @@ -8912,9 +8891,9 @@ components: description: | Tokens consumed by a single model over a run. required: - - model_id - - total_tokens - - usage_type + - model_id + - total_tokens + - usage_type properties: model_id: type: string @@ -8926,7 +8905,7 @@ components: total_tokens: type: integer format: int64 - description: 'Total tokens this model consumed, across every usage category.' + description: Total tokens this model consumed, across every usage category. usage_type: $ref: '#/components/schemas/ModelUsageType' tokens_by_category: @@ -8945,44 +8924,44 @@ components: - byok: through the caller's own provider API key - custom_endpoint: through a caller-configured model endpoint enum: - - warp - - byok - - custom_endpoint + - warp + - byok + - custom_endpoint InferenceCostBreakdownInCents: type: object description: | Charged cost of LLM inference in US cents, split by token type. Omitted when the data is not available. required: - - input_cost_in_cents - - input_cache_read_cost_in_cents - - input_cache_write_cost_in_cents - - output_cost_in_cents + - input_cost_in_cents + - input_cache_read_cost_in_cents + - input_cache_write_cost_in_cents + - output_cost_in_cents properties: input_cost_in_cents: type: number format: double - description: 'Cost of non-cached input tokens, in US cents.' + description: Cost of non-cached input tokens, in US cents. input_cache_read_cost_in_cents: type: number format: double - description: 'Cost of cache-read input tokens, in US cents.' + description: Cost of cache-read input tokens, in US cents. input_cache_write_cost_in_cents: type: number format: double - description: 'Cost of cache-write input tokens, in US cents.' + description: Cost of cache-write input tokens, in US cents. output_cost_in_cents: type: number format: double - description: 'Cost of output tokens, in US cents.' + description: Cost of output tokens, in US cents. TokenCountBreakdown: type: object description: A per-token-type token count. required: - - input - - output - - input_cache_read - - input_cache_write + - input + - output + - input_cache_read + - input_cache_write properties: input: type: integer @@ -9007,10 +8986,10 @@ components: The counts and cost describe the same usage (e.g. token_count.input tokens cost cost_in_cents.input_cost_in_cents in total). required: - - token_count - - cost_in_cents - - web_search_count - - web_search_cost_in_cents + - token_count + - cost_in_cents + - web_search_count + - web_search_cost_in_cents properties: token_count: $ref: '#/components/schemas/TokenCountBreakdown' @@ -9023,25 +9002,42 @@ components: web_search_cost_in_cents: type: number format: double - description: 'Total cost of those web searches, in US cents.' + description: Total cost of those web searches, in US cents. + web_fetch_page_count: + type: integer + format: int64 + description: | + Recorded web pages requested by native web-fetch calls + web_fetch_cost_in_cents: + type: number + format: double + description: | + Total cost of recorded requested web-fetch pages, in US cents. + web_fetch_cost_in_credits: + type: number + format: double + description: | + Cost of recorded requested web-fetch pages, in the run owner's credits. + Omitted for customer-paid inference, unrecorded costs, or an unavailable credit rate. 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: - - platform_usage_in_cents + - platform_usage_in_cents + - platform_usage_duration_seconds 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.' + 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.' + description: Inference usage charged using a user's own API key, keyed by model ID. custom_endpoint_inference_usage: type: object additionalProperties: @@ -9052,15 +9048,22 @@ components: platform_usage_in_cents: type: number format: double - description: 'Platform usage charged for this category, in US cents.' + description: Platform usage charged for this category, in US cents. + platform_usage_duration_seconds: + type: number + format: double + minimum: 0 + description: | + Cumulative billable agent runtime for this category, in seconds, + across the conversation's turns. Zero when no runtime was recorded. RunCreatorInfo: type: object properties: type: type: string enum: - - user - - service_account + - user + - service_account description: Type of the creator principal uid: type: string @@ -9078,15 +9081,15 @@ components: RunState: type: string enum: - - QUEUED - - PENDING - - CLAIMED - - INPROGRESS - - SUCCEEDED - - FAILED - - BLOCKED - - ERROR - - CANCELLED + - QUEUED + - PENDING + - CLAIMED + - INPROGRESS + - SUCCEEDED + - FAILED + - BLOCKED + - ERROR + - CANCELLED description: | Current state of the run: - QUEUED: Run is waiting to be picked up @@ -9101,29 +9104,29 @@ components: RunSourceType: type: string enum: - - LINEAR - - API - - MCP - - SLACK - - TEAMS - - LOCAL - - SCHEDULED_AGENT - - WEB_APP - - GITHUB_ACTION - - CLOUD_MODE - - CLI - - JIRA - - SELF_IMPROVEMENT - - GITHUB_WEBHOOK - - GITLAB_WEBHOOK - - AZURE_DEVOPS_WEBHOOK - - AUTOFIX - - RUN_SCORER - - ORCHESTRATION - - BENCHMARK_TRIAL - - CREATE_BENCHMARK_TASK - - CUSTOM_WEBHOOK - description: | + - LINEAR + - API + - MCP + - SLACK + - TEAMS + - LOCAL + - SCHEDULED_AGENT + - WEB_APP + - GITHUB_ACTION + - CLOUD_MODE + - CLI + - JIRA + - SELF_IMPROVEMENT + - GITHUB_WEBHOOK + - GITLAB_WEBHOOK + - AZURE_DEVOPS_WEBHOOK + - AUTOFIX + - RUN_SCORER + - ORCHESTRATION + - BENCHMARK_TRIAL + - CREATE_BENCHMARK_TASK + - CUSTOM_WEBHOOK + description: |- Source that created the run: - LINEAR: Created from Linear integration - API: Created via the Warp API @@ -9150,8 +9153,8 @@ components: RunExecutionLocation: type: string enum: - - LOCAL - - REMOTE + - LOCAL + - REMOTE description: | Where the run executed: - LOCAL: Executed in the user's local Warp environment @@ -9258,17 +9261,18 @@ components: description: Memory stores to attach to this run. inference_providers: allOf: - - $ref: '#/components/schemas/InferenceProvidersConfig' + - $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: + oneOf: + - type: string + enum: - CREATOR - EXECUTOR + - type: 'null' description: | Controls which principal's credentials are used when the platform mints tokens (e.g. GitHub or GitLab OAuth tokens) on @@ -9295,8 +9299,8 @@ components: public_access: type: string enum: - - VIEWER - - EDITOR + - VIEWER + - EDITOR description: | Grants anyone-with-link access at the specified level to the run's shared session and backing conversation; link viewers @@ -9315,18 +9319,15 @@ components: empty, since the two describe mutually exclusive default models. properties: type: - type: string - enum: + oneOf: + - 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 + description: Warp's built-in harness (default). + - $ref: '#/components/schemas/ExternalHarness' + description: | + The harness type identifier: `oz` for Warp's built-in harness + (default), or any third-party harness. model_id: type: string description: | @@ -9344,6 +9345,19 @@ components: 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. + ExternalHarness: + type: string + enum: + - claude + - codex + - gemini + - pi + description: | + A third-party harness; every harness other than Warp's built-in `oz`. + - claude: Claude Code + - codex: Codex CLI + - gemini: Gemini CLI + - pi: Pi HarnessAuthSecrets: type: object description: | @@ -9362,6 +9376,14 @@ components: 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". + pi_auth_secret_name: + type: string + description: | + Name of a managed secret for Pi harness authentication. + The secret must exist within the caller's personal or team scope and + must be a credential for the model provider named by the provider + prefix of harness.model_id. + Only applicable when harness type is "pi". MCPServerConfig: type: object description: | @@ -9403,10 +9425,10 @@ components: backward-compatible extension members; additional ones (e.g., `auth_url`, `provider`) may be present depending on the error code. required: - - type - - title - - status - - error + - type + - title + - status + - error properties: type: type: string @@ -9417,7 +9439,7 @@ components: See PlatformErrorCode for the list of possible error codes. title: type: string - description: 'A short, human-readable summary of the problem type (RFC 7807)' + 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) @@ -9443,16 +9465,16 @@ components: description: OpenTelemetry trace ID for debugging and support requests provider: type: string - description: 'External provider that requires authorization, such as `linear`.' + 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' + - $ref: '#/components/schemas/PlanArtifactResponse' + - $ref: '#/components/schemas/ScreenshotArtifactResponse' + - $ref: '#/components/schemas/FileArtifactResponse' discriminator: propertyName: artifact_type mapping: @@ -9463,10 +9485,10 @@ components: type: object description: Response for retrieving a plan artifact. required: - - artifact_uid - - artifact_type - - created_at - - data + - artifact_uid + - artifact_type + - created_at + - data properties: artifact_uid: type: string @@ -9474,7 +9496,7 @@ components: artifact_type: type: string enum: - - PLAN + - PLAN description: Type of the artifact created_at: type: string @@ -9484,12 +9506,12 @@ components: $ref: '#/components/schemas/PlanArtifactResponseData' PlanArtifactResponseData: type: object - description: 'Response data for a plan artifact, including current markdown content.' + description: Response data for a plan artifact, including current markdown content. required: - - document_uid - - notebook_uid - - content - - content_type + - document_uid + - notebook_uid + - content + - content_type properties: document_uid: type: string @@ -9514,10 +9536,10 @@ components: type: object description: Response for retrieving a screenshot artifact. required: - - artifact_uid - - artifact_type - - created_at - - data + - artifact_uid + - artifact_type + - created_at + - data properties: artifact_uid: type: string @@ -9525,7 +9547,7 @@ components: artifact_type: type: string enum: - - SCREENSHOT + - SCREENSHOT description: Type of the artifact created_at: type: string @@ -9542,7 +9564,7 @@ components: run_url: type: string format: uri - description: 'Factory run page for the originating root run, when bound to a live Factory task.' + description: Factory run page for the originating root run, when bound to a live Factory task. pull_request_urls: type: array items: @@ -9551,11 +9573,11 @@ components: description: Distinct pull requests reported by runs in the same tree. ScreenshotArtifactResponseData: type: object - description: 'Response data for a screenshot artifact, including a signed download URL.' + description: Response data for a screenshot artifact, including a signed download URL. required: - - download_url - - expires_at - - content_type + - download_url + - expires_at + - content_type properties: download_url: type: string @@ -9567,7 +9589,7 @@ components: description: Timestamp when the download URL expires (RFC3339) content_type: type: string - description: 'MIME type of the screenshot (e.g., image/png)' + description: MIME type of the screenshot (e.g., image/png) description: type: string description: Optional description of the screenshot @@ -9575,10 +9597,10 @@ components: type: object description: Response for retrieving a file artifact. required: - - artifact_uid - - artifact_type - - created_at - - data + - artifact_uid + - artifact_type + - created_at + - data properties: artifact_uid: type: string @@ -9586,7 +9608,7 @@ components: artifact_type: type: string enum: - - FILE + - FILE description: Type of the artifact created_at: type: string @@ -9598,12 +9620,12 @@ components: $ref: '#/components/schemas/FileArtifactResponseData' FileArtifactResponseData: type: object - description: 'Response data for a file artifact, including a signed download URL.' + description: Response data for a file artifact, including a signed download URL. required: - - download_url - - expires_at - - content_type - - filename + - download_url + - expires_at + - content_type + - filename properties: download_url: type: string @@ -9641,9 +9663,9 @@ components: type: object description: A base64-encoded file attachment to include with the prompt required: - - file_name - - mime_type - - data + - file_name + - mime_type + - data properties: file_name: type: string @@ -9660,13 +9682,13 @@ components: ScheduledAgentItem: type: object required: - - id - - name - - cron_schedule - - enabled - - prompt - - created_at - - updated_at + - id + - name + - cron_schedule + - enabled + - prompt + - created_at + - updated_at properties: id: type: string @@ -9676,7 +9698,7 @@ components: 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)' + 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 @@ -9684,9 +9706,10 @@ components: 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' + type: + - string + - 'null' + description: Error message from the last failed spawn attempt, if any agent_config: $ref: '#/components/schemas/AmbientAgentConfig' agent_uid: @@ -9695,11 +9718,11 @@ components: description: UID of the agent that this schedule runs as metadata: allOf: - - $ref: '#/components/schemas/RunMetadata' + - $ref: '#/components/schemas/RunMetadata' description: Custom metadata stamped onto every run spawned by this schedule environment: allOf: - - $ref: '#/components/schemas/CloudEnvironmentConfig' + - $ref: '#/components/schemas/CloudEnvironmentConfig' description: Resolved environment configuration (if agent_config references an environment_id) created_at: type: string @@ -9722,14 +9745,16 @@ components: description: Scheduler-derived history metadata for a scheduled agent properties: last_ran: - type: string + type: + - string + - 'null' format: date-time - nullable: true description: Timestamp of the last successful run (RFC3339) next_run: - type: string + type: + - string + - 'null' format: date-time - nullable: true description: Timestamp of the next scheduled run (RFC3339) CreateScheduledAgentRequest: type: object @@ -9737,15 +9762,15 @@ components: 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 + - name + - cron_schedule properties: name: type: string description: Human-readable name for the schedule cron_schedule: type: string - description: 'Cron expression defining when the agent runs (e.g., "0 9 * * *" for daily at 9am UTC)' + description: Cron expression defining when the agent runs (e.g., "0 9 * * *" for daily at 9am UTC) prompt: type: string description: | @@ -9776,7 +9801,7 @@ components: Defaults to true for users on a single team. metadata: allOf: - - $ref: '#/components/schemas/RunMetadata' + - $ref: '#/components/schemas/RunMetadata' description: | Custom metadata stamped onto every run spawned by this schedule as the run's explicit metadata layer. @@ -9786,9 +9811,9 @@ components: 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 + - name + - cron_schedule + - enabled properties: name: type: string @@ -9820,7 +9845,7 @@ components: $ref: '#/components/schemas/AmbientAgentConfig' metadata: allOf: - - $ref: '#/components/schemas/RunMetadata' + - $ref: '#/components/schemas/RunMetadata' description: | Custom metadata stamped onto every run spawned by this schedule. Updates follow full-replacement PUT semantics: omitting this field @@ -9828,7 +9853,7 @@ components: ListScheduledAgentsResponse: type: object required: - - schedules + - schedules properties: schedules: type: array @@ -9838,7 +9863,7 @@ components: DeleteScheduledAgentResponse: type: object required: - - success + - success properties: success: type: boolean @@ -9851,12 +9876,13 @@ components: type: string description: Human-readable name for the environment description: - type: string - nullable: true + type: + - string + - 'null' description: Optional description of the environment docker_image: type: string - description: 'Docker image to use (e.g., "ubuntu:latest" or "registry/repo:tag")' + description: Docker image to use (e.g., "ubuntu:latest" or "registry/repo:tag") github_repos: type: array items: @@ -9879,8 +9905,9 @@ components: references are unioned with references from the run config and execution principal. failure_session_retention_minutes: - type: integer - nullable: true + type: + - integer + - 'null' minimum: 1 maximum: 60 description: | @@ -9912,12 +9939,12 @@ components: type: object description: GCP Workload Identity Federation settings required: - - project_number - - workload_identity_federation_pool_id - - workload_identity_federation_provider_id + - 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' + url: https://docs.cloud.google.com/iam/docs/workload-identity-federation properties: project_number: type: string @@ -9936,9 +9963,9 @@ components: 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' + url: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html required: - - role_arn + - role_arn properties: role_arn: type: string @@ -9950,22 +9977,31 @@ components: 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' + 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.' + description: If true, opt out of Bedrock at this layer. role_arn: type: string description: IAM role ARN to assume when calling Bedrock. region: type: string description: AWS region used for STS when assuming the Bedrock inference role. + role_arn_source: + allOf: + - $ref: '#/components/schemas/BedrockSource' + readOnly: true + description: | + Which level supplied `role_arn`. Returned only on a run's + `agent_config`, set when the run is created; absent on agents, on + schedules, and on runs created before this field existed. Ignored + if sent. GitHubRepo: type: object required: - - owner - - repo + - owner + - repo properties: owner: type: string @@ -9976,7 +10012,7 @@ components: ListAgentsResponse: type: object required: - - agents + - agents properties: agents: type: array @@ -9986,7 +10022,7 @@ components: ListConnectedSelfHostedWorkersResponse: type: object required: - - workers + - workers properties: workers: type: array @@ -9996,10 +10032,10 @@ components: ConnectedSelfHostedWorker: type: object required: - - worker_host - - connection_count - - connected_at - - last_seen_at + - worker_host + - connection_count + - connected_at + - last_seen_at properties: worker_host: type: string @@ -10018,8 +10054,8 @@ components: AgentListItem: type: object required: - - name - - variants + - name + - variants properties: name: type: string @@ -10032,11 +10068,11 @@ components: AgentListVariant: type: object required: - - id - - description - - base_prompt - - source - - environments + - id + - description + - base_prompt + - source + - environments properties: id: type: string @@ -10058,9 +10094,10 @@ components: $ref: '#/components/schemas/AgentListEnvironment' description: Environments where this agent variant is available last_run_timestamp: - type: string + type: + - string + - 'null' format: date-time - nullable: true description: Timestamp of the last time this skill was run (RFC3339) error: type: string @@ -10071,9 +10108,9 @@ components: AgentListSource: type: object required: - - owner - - name - - skill_path + - owner + - name + - skill_path properties: owner: type: string @@ -10093,8 +10130,8 @@ components: AgentListEnvironment: type: object required: - - uid - - name + - uid + - name properties: uid: type: string @@ -10106,14 +10143,14 @@ components: type: object description: Ownership scope for a resource (team or personal) required: - - type + - type properties: type: type: string enum: - - User - - Team - description: 'Type of ownership ("User" for personal, "Team" for team-owned)' + - User + - Team + description: Type of ownership ("User" for personal, "Team" for team-owned) uid: type: string description: UID of the owning user or team @@ -10146,24 +10183,32 @@ components: - `agent_stream_failure` — MAA server explicitly reported a terminal response stream failure - `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 - - agent_stream_network_error - - agent_stream_failure - - internal_error + - insufficient_credits + - feature_not_available + - external_authentication_required + - not_authorized + - invalid_request + - resource_not_found + - budget_exceeded + - integration_disabled + - integration_not_configured + - operation_not_supported + - environment_setup_failed + - content_policy_violation + - conflict + - authentication_required + - resource_unavailable + - agent_stream_network_error + - agent_stream_failure + - internal_error + PresignedDownloadResponse: + type: object + required: + - url + properties: + url: + type: string + description: Temporary signed storage URL. Fetch without Warp API headers or credentials. RunFollowupRequest: type: object description: Request body for submitting a follow-up message to an existing run. @@ -10198,7 +10243,7 @@ components: type: object description: A prepared attachment to deliver with a follow-up message. required: - - attachment_id + - attachment_id properties: attachment_id: type: string @@ -10225,20 +10270,21 @@ components: - queue_pending: the message is durably queued and will be delivered once the run can accept it. enum: - - live_session - - queued_prompt - - handoff_execution - - queue_pending + - live_session + - queued_prompt + - handoff_execution + - queue_pending RunFollowupResponse: type: object description: Acknowledgement of an accepted follow-up. required: - - followup_id - - outcome + - followup_id + - outcome properties: followup_id: - type: string - nullable: true + type: + - string + - 'null' description: | Identifier of the durable follow-up record, or null when the outcome did not create one (`queued_prompt`). @@ -10250,13 +10296,14 @@ components: Acknowledgement of a follow-up accepted through a conversation-keyed route: the run-keyed acknowledgement plus the run it was delivered to. required: - - followup_id - - outcome - - run_id + - followup_id + - outcome + - run_id properties: followup_id: - type: string - nullable: true + type: + - string + - 'null' description: | Identifier of the durable follow-up record, or null when the outcome did not create one (`queued_prompt`). @@ -10269,50 +10316,16 @@ components: type: object description: Acknowledgement of an interrupt accepted through a conversation-keyed route. required: - - run_id + - run_id properties: run_id: type: string description: The run whose turn is being interrupted. - HandoffSnapshotAttachmentInfo: - type: object - description: A handoff snapshot attachment exposed for download. - required: - - attachment_id - - filename - - download_url - properties: - attachment_id: - type: string - description: Identifier for the snapshot attachment within the run. - filename: - type: string - description: Original filename of the snapshot attachment. - download_url: - type: string - format: uri - description: Time-limited signed URL to download the snapshot attachment. - mime_type: - type: string - description: 'MIME type of the snapshot attachment, if known.' - ListHandoffSnapshotAttachmentsResponse: - type: object - description: Response body for listing handoff snapshot attachments. - required: - - attachments - properties: - attachments: - type: array - items: - $ref: '#/components/schemas/HandoffSnapshotAttachmentInfo' - description: | - Handoff snapshot attachments exposed by the latest ended execution. - Empty when no ended execution exists or no files were uploaded. ListModelsResponse: type: object required: - - default_model_id - - models + - default_model_id + - models properties: default_model_id: type: string @@ -10325,10 +10338,10 @@ components: ModelInfo: type: object required: - - id - - display_name - - provider - - vision_supported + - id + - display_name + - provider + - vision_supported properties: id: type: string @@ -10337,12 +10350,8 @@ components: type: string description: Human-readable name of the model provider: - type: string - enum: - - OPENAI - - ANTHROPIC - - GOOGLE - - UNKNOWN + allOf: + - $ref: '#/components/schemas/LlmProvider' description: The LLM provider vision_supported: type: boolean @@ -10352,21 +10361,41 @@ components: description: Optional extra descriptor for the model reasoning_level: type: string - description: 'Reasoning level descriptor, if any (e.g. "low", "medium", "high")' + 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' + - PROVIDER_OUTAGE + - OUT_OF_REQUESTS + - ADMIN_DISABLED + - REQUIRES_UPGRADE + description: If set, the model is currently unavailable for the given reason + LlmProvider: + type: string + enum: + - OPENAI + - ANTHROPIC + - GOOGLE + - XAI + - UNKNOWN + description: The LLM provider behind a model. + BedrockSource: + type: string + enum: + - run + - agent + - workspace + description: | + The configuration level that supplied a Bedrock inference role: `run`, + the run's own `config.inference_providers`; `agent`, the agent's + `inference_providers`; `workspace`, the workspace's admin-configured + Bedrock settings. ExternalReferenceArtifactData: type: object description: Data for a generic external reference artifact. required: - - reference_type - - url + - reference_type + - url properties: reference_type: type: string @@ -10391,7 +10420,7 @@ components: type: object description: Response for a run reverse-lookup by external reference URL. required: - - run_id + - run_id properties: run_id: type: string @@ -10417,7 +10446,7 @@ components: ListEnvironmentsResponse: type: object required: - - environments + - environments properties: environments: type: array @@ -10428,10 +10457,10 @@ components: type: object description: A cloud environment for running agents required: - - uid - - config - - last_updated - - setup_failed + - uid + - config + - last_updated + - setup_failed properties: uid: type: string @@ -10443,9 +10472,10 @@ components: format: date-time description: Timestamp when the environment was last updated (RFC3339) last_task_run_timestamp: - type: string + type: + - string + - 'null' format: date-time - nullable: true description: Timestamp of the most recent task run in this environment (RFC3339) last_task_created: $ref: '#/components/schemas/EnvironmentLastTask' @@ -10463,7 +10493,7 @@ components: description: | Reference to a managed secret by name. required: - - name + - name properties: name: type: string @@ -10472,9 +10502,9 @@ components: type: object description: Reference to a memory store to attach to an agent. required: - - uid - - access - - instructions + - uid + - access + - instructions properties: uid: type: string @@ -10482,8 +10512,8 @@ components: access: type: string enum: - - read_write - - read_only + - read_write + - read_only description: Access level for the store. instructions: type: string @@ -10492,11 +10522,11 @@ components: type: object description: Memory store attached to an agent. required: - - uid - - access - - instructions - - owner_type - - owner_uid + - uid + - access + - instructions + - owner_type + - owner_uid properties: uid: type: string @@ -10504,8 +10534,8 @@ components: access: type: string enum: - - read_write - - read_only + - read_write + - read_only description: Access level for the store. instructions: type: string @@ -10514,12 +10544,12 @@ components: type: string description: Public owner type. enum: - - user - - service_account - - team + - user + - service_account + - team owner_uid: type: string - description: 'Public UID of the user, service account, or team that owns the memory store.' + 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. @@ -10538,7 +10568,7 @@ components: properties: auto_memory: allOf: - - $ref: '#/components/schemas/AgentAutoMemoryCreateConfig' + - $ref: '#/components/schemas/AgentAutoMemoryCreateConfig' description: Agent-owned memory settings. Defaults to enabled when omitted. attached_stores: type: array @@ -10552,8 +10582,9 @@ components: description: Memory settings for updating an agent. properties: attached_stores: - type: array - nullable: true + type: + - array + - 'null' items: $ref: '#/components/schemas/MemoryStoreRef' description: | @@ -10563,7 +10594,7 @@ components: type: object description: Auto-memory state for an agent. required: - - enabled + - enabled properties: enabled: type: boolean @@ -10574,8 +10605,8 @@ components: type: object description: Memory settings for an agent. required: - - auto_memory - - attached_stores + - auto_memory + - attached_stores properties: auto_memory: $ref: '#/components/schemas/AgentAutoMemoryResponse' @@ -10595,13 +10626,13 @@ components: - CREATOR: runs authenticate with the credentials of the principal that created the run. enum: - - CREATOR - - EXECUTOR + - CREATOR + - EXECUTOR ScorerClassification: type: object required: - - value - - score + - value + - score properties: value: type: string @@ -10609,8 +10640,9 @@ components: maxLength: 1048576 description: Classification value returned by the scorer description: - type: string - nullable: true + type: + - string + - 'null' maxLength: 1048576 description: | Optional free-text meaning of this classification, surfaced to the @@ -10636,22 +10668,25 @@ components: collections explicitly clear the optional Factory defaults. properties: default_runner_uid: - type: string - nullable: true + type: + - string + - 'null' description: | Runner used by scorer judge runs. Omit or set null to inherit the Factory agent default. secrets: - type: array - nullable: true + type: + - array + - 'null' description: | Managed secrets attached to scorer judge runs. Omit or set null to inherit the Factory agent defaults; an empty array attaches none. items: $ref: '#/components/schemas/SecretRef' mcp_servers: - type: object - nullable: true + type: + - object + - 'null' description: | MCP servers attached to scorer judge runs. Omit or set null to inherit the Factory agent defaults; an empty object attaches none. @@ -10664,12 +10699,12 @@ components: before validation; required text fields must not be blank after trimming, and no text field may exceed 1 MiB (1048576 bytes). required: - - name - - scoring_prompt - - allowed_classifications - - threshold - - scope_mode - - model_id + - name + - scoring_prompt + - allowed_classifications + - threshold + - scope_mode + - model_id properties: factory_uid: type: string @@ -10682,8 +10717,9 @@ components: maxLength: 1048576 description: Display name for the scorer description: - type: string - nullable: true + type: + - string + - 'null' maxLength: 1048576 description: Optional description of the scorer scoring_prompt: @@ -10709,8 +10745,8 @@ components: scope_mode: type: string enum: - - all_agents - - selected_agents + - all_agents + - selected_agents description: Whether the scorer applies to every factory agent or selected agents agent_uids: type: array @@ -10729,9 +10765,10 @@ components: items: $ref: '#/components/schemas/ScorerAgentInput' sampling_rate: - type: number + type: + - number + - 'null' format: double - nullable: true minimum: 0 maximum: 100 description: | @@ -10816,8 +10853,8 @@ components: scope_mode: type: string enum: - - all_agents - - selected_agents + - all_agents + - selected_agents description: | New scope mode. Defaults to the scorer's current mode when only agent_uids or agents is supplied. @@ -10847,14 +10884,9 @@ components: New LLM model dispatched judge runs use to evaluate this scorer's rubric. Must not be blank when provided. agent_config: - type: object - nullable: true anyOf: - - $ref: '#/components/schemas/ScorerAgentConfig' - - type: object - nullable: true - enum: - - null + - $ref: '#/components/schemas/ScorerAgentConfig' + - type: 'null' description: | Partial execution override update. A null object resets every override to inherit the Factory agent defaults. Otherwise, omitted @@ -10871,29 +10903,29 @@ components: 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 + - user + - benchmark_task_correctness ScorerResponse: type: object required: - - scorer_uid - - id - - factory_uid - - name - - description - - scoring_prompt - - allowed_classifications - - threshold - - self_improvement_enabled - - scorer_kind - - scope_mode - - agent_uids - - agents - - sampling_rate - - model_id - - agent_config - - created_at - - updated_at + - scorer_uid + - id + - factory_uid + - name + - description + - scoring_prompt + - allowed_classifications + - threshold + - self_improvement_enabled + - scorer_kind + - scope_mode + - agent_uids + - agents + - sampling_rate + - model_id + - agent_config + - created_at + - updated_at properties: scorer_uid: $ref: '#/components/schemas/ScorerUID' @@ -10922,14 +10954,14 @@ components: threshold: type: number format: double - description: 'Score a run''s classified label must meet or exceed to pass, from 0 to 1' + description: Score a run's classified label must meet or exceed to pass, from 0 to 1 scorer_kind: $ref: '#/components/schemas/ScorerKind' scope_mode: type: string enum: - - all_agents - - selected_agents + - all_agents + - selected_agents description: Whether the scorer applies to every factory agent or selected agents agent_uids: type: array @@ -10965,9 +10997,9 @@ components: ScorerScopeAgent: type: object required: - - uid - - name - - include_descendants + - uid + - name + - include_descendants properties: uid: type: string @@ -10981,7 +11013,7 @@ components: ScorerAgentInput: type: object required: - - uid + - uid properties: uid: type: string @@ -10993,24 +11025,24 @@ components: ScorerListItem: type: object required: - - scorer_uid - - id - - factory_uid - - name - - description - - scoring_prompt - - allowed_classifications - - threshold - - scope_mode - - agents - - scorer_kind - - sampling_rate - - created_at - - updated_at - - result_count - - model_id - - agent_config - - self_improvement_enabled + - scorer_uid + - id + - factory_uid + - name + - description + - scoring_prompt + - allowed_classifications + - threshold + - scope_mode + - agents + - scorer_kind + - sampling_rate + - created_at + - updated_at + - result_count + - model_id + - agent_config + - self_improvement_enabled properties: scorer_uid: $ref: '#/components/schemas/ScorerUID' @@ -11036,12 +11068,12 @@ components: threshold: type: number format: double - description: 'Score a run''s classified label must meet or exceed to pass, from 0 to 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 + - all_agents + - selected_agents description: all_agents (every agent in the scorer's factory) or selected_agents agents: type: array @@ -11070,9 +11102,10 @@ components: type: integer description: Number of live scores recorded for the scorer last_scored_at: - type: string + type: + - string + - 'null' format: date-time - nullable: true description: When the scorer last recorded a score model_id: type: string @@ -11085,7 +11118,7 @@ components: ListScorersResponse: type: object required: - - scorers + - scorers properties: scorers: type: array @@ -11094,8 +11127,8 @@ components: ScorerOutcome: type: string enum: - - pass - - fail + - 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 @@ -11107,9 +11140,9 @@ components: ScorerResultStatus: type: string enum: - - scored - - failed - - in_flight + - scored + - failed + - in_flight description: | Outcome of a scoring attempt: "scored", "failed", or "in_flight" (no live score yet and a judge is currently running). A failed or @@ -11119,87 +11152,89 @@ components: ScorerReasonStatus: type: string enum: - - available - - absent - - unavailable + - available + - absent + - unavailable description: | Available when the judge reason was read, absent when none was recorded, and unavailable when a recorded reason could not be read. ScorerResult: type: object required: - - run_id - - status - - attempted_at - - is_in_flight + - run_id + - status + - attempted_at + - is_in_flight properties: run_id: type: string description: The selected agent run that anchors the scoring attempt conversation_id: - type: string - nullable: true + type: + - string + - 'null' description: Conversation whose transcript was judged conversation_title: - type: string - nullable: true + type: + - string + - 'null' description: Title of the judged conversation status: $ref: '#/components/schemas/ScorerResultStatus' reason_status: allOf: - - $ref: '#/components/schemas/ScorerReasonStatus' + - $ref: '#/components/schemas/ScorerReasonStatus' description: Present only when include_reasons is true. reason: type: string description: Judge reasoning; present only when reason_status is available. classification: - type: string - nullable: true + type: + - string + - 'null' description: The chosen classification; absent when the attempt failed attempted_at: type: string format: date-time description: When the scorer last attempted this run scored_at: - type: string + type: + - string + - 'null' format: date-time - nullable: true description: When the live score was recorded; absent for failed attempts scoring_run_id: - type: string - nullable: true + type: + - string + - 'null' 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' + - $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 + type: + - string + - 'null' 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 + type: + - number + - 'null' 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: - type: string anyOf: - - $ref: '#/components/schemas/ScorerOutcome' - - type: string - nullable: true - enum: - - null - nullable: true + - $ref: '#/components/schemas/ScorerOutcome' + - type: 'null' description: | Pass/fail verdict for this score, derived at read time against the evaluation's current threshold. Absent when the attempt failed. @@ -11212,8 +11247,8 @@ components: ListScorerResultsResponse: type: object required: - - results - - page_info + - results + - page_info properties: results: type: array @@ -11228,14 +11263,14 @@ components: 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 + - 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' @@ -11249,15 +11284,16 @@ components: pass_count: type: integer format: int64 - description: 'Live scores whose derived outcome is pass, over the whole range.' + 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.' + description: Live scores whose derived outcome is fail, over the whole range. pass_rate: - type: number + type: + - number + - 'null' format: double - nullable: true description: | pass_count / (pass_count + fail_count) over the whole range; null when the range has no pass/fail scores. The dashboard headline @@ -11265,13 +11301,13 @@ components: describes the same window as the chart. pass_count_series: type: array - description: 'One entry per period_list entry, zero-filled.' + 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.' + description: One entry per period_list entry, zero-filled. items: type: integer format: int64 @@ -11283,9 +11319,10 @@ components: with no pass/fail scores, so the chart renders a gap there instead of a false 0%. items: - type: number + type: + - number + - 'null' format: double - nullable: true cost_usd_series: type: array description: | @@ -11306,7 +11343,7 @@ components: RunScorerDispatchRequest: type: object required: - - scorer_uids + - scorer_uids properties: scorer_uids: type: array @@ -11318,7 +11355,7 @@ components: ScorerDispatchRequest: type: object required: - - run_ids + - run_ids properties: run_ids: type: array @@ -11331,13 +11368,13 @@ components: ManualScoringDispatchStatus: type: string enum: - - dispatched - - already_in_flight - - failed_no_transcript - - failed_run_tree_not_ready - - failed_run_tree_incomplete - - failed_run_tree_too_large - - failed_to_dispatch + - dispatched + - already_in_flight + - failed_no_transcript + - failed_run_tree_not_ready + - failed_run_tree_incomplete + - failed_run_tree_too_large + - failed_to_dispatch description: | Outcome of one dispatched (run, scorer) pair: "dispatched" (stamped with a new or shared judge run), "already_in_flight" (an existing live @@ -11352,9 +11389,9 @@ components: ManualScoringDispatchResult: type: object required: - - scorer_uid - - run_id - - status + - scorer_uid + - run_id + - status properties: scorer_uid: $ref: '#/components/schemas/ScorerUID' @@ -11365,33 +11402,35 @@ components: status: $ref: '#/components/schemas/ManualScoringDispatchStatus' scoring_run_id: - type: string - nullable: true + type: + - string + - 'null' format: uuid 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 - nullable: true + type: + - string + - 'null' description: Safe error detail; present only for failed_to_dispatch ManualScoringDispatchResponse: type: object required: - - results + - results properties: results: type: array items: $ref: '#/components/schemas/ManualScoringDispatchResult' - description: 'One entry per requested pair, in no particular order' + description: One entry per requested pair, in no particular order RunScoreAttemptStatus: type: string enum: - - in_flight - - scored - - failed + - 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 @@ -11400,19 +11439,19 @@ components: RunScoreTriggerSource: type: string enum: - - automatic - - manual + - automatic + - manual description: Whether the current attempt was requested by an automatic scoring dispatch or a manual dispatch request RunScoreItem: type: object required: - - scorer_uid - - scorer_id - - scorer_name - - attempt_status - - is_in_flight - - trigger_source - - attempted_at + - scorer_uid + - scorer_id + - scorer_name + - attempt_status + - is_in_flight + - trigger_source + - attempted_at properties: scorer_uid: $ref: '#/components/schemas/ScorerUID' @@ -11430,27 +11469,30 @@ components: trigger_source: $ref: '#/components/schemas/RunScoreTriggerSource' classification: - type: string - nullable: true + type: + - string + - 'null' description: The live classification; absent when there is no live score attempted_at: type: string format: date-time description: When the evaluation last attempted this run scored_at: - type: string + type: + - string + - 'null' format: date-time - nullable: true description: When the live score was recorded; absent when there is no live score scoring_run_id: - type: string - nullable: true + type: + - string + - 'null' description: The Warp run that performed the judging; absent when scoring was never dispatched for this attempt GetRunScoresResponse: type: object required: - - run_id - - scores + - run_id + - scores properties: run_id: type: string @@ -11459,33 +11501,37 @@ components: type: array items: $ref: '#/components/schemas/RunScoreItem' - description: 'One entry per evaluation that has attempted the run, most recent attempt first' + description: One entry per evaluation that has attempted the run, most recent attempt first CreateAgentRequest: type: object required: - - name + - name properties: name: type: string description: A name for the agent description: - type: string - nullable: true + type: + - string + - 'null' description: Optional description of the agent prompt: - type: string - nullable: true + type: + - string + - 'null' description: | Optional base prompt for this agent environment_id: - type: string - nullable: true + type: + - string + - 'null' description: | Optional default cloud environment ID for runs executed by this agent. The environment must be owned by the same team as the agent. default_runner_uid: - type: string - nullable: true + type: + - string + - 'null' description: | Optional default runner UID for runs executed by this agent. When set, it overrides the selected environment's default runner for runs that @@ -11509,20 +11555,21 @@ components: Each spec is validated and normalized at attach time using the team's GitHub credentials; inaccessible or malformed specs are rejected. base_model: - type: string - nullable: true + type: + - string + - 'null' description: | Optional base model for runs executed by this agent. inference_providers: allOf: - - $ref: '#/components/schemas/InferenceProvidersConfig' + - $ref: '#/components/schemas/InferenceProvidersConfig' description: | Optional inference provider settings for this agent. Agent-level config takes precedence over the workspace's admin-configured defaults. memory: allOf: - - $ref: '#/components/schemas/AgentMemoryCreateConfig' + - $ref: '#/components/schemas/AgentMemoryCreateConfig' description: Optional memory settings for the agent. mcp_servers: type: object @@ -11532,8 +11579,9 @@ components: Optional map of MCP server configurations by name to attach to runs executed by this agent. Run-level MCP config takes precedence over this agent-level default. base_harness: - type: string - nullable: true + type: + - string + - 'null' deprecated: true description: | Optional default harness for runs executed by this agent. @@ -11542,14 +11590,14 @@ components: type is rejected with invalid_request. harness: allOf: - - $ref: '#/components/schemas/Harness' + - $ref: '#/components/schemas/Harness' description: | Optional default harness for runs executed by this agent. Omission or an empty object stores no harness default. credential_strategy: - allOf: - - $ref: '#/components/schemas/AgentCredentialStrategy' - nullable: true + oneOf: + - $ref: '#/components/schemas/AgentCredentialStrategy' + - type: 'null' description: | Optional default credential strategy for runs executed by this agent. When omitted or null, the agent has no opinion and runs fall @@ -11557,7 +11605,7 @@ components: EXECUTOR. harness_auth_secrets: allOf: - - $ref: '#/components/schemas/HarnessAuthSecrets' + - $ref: '#/components/schemas/HarnessAuthSecrets' description: | Optional per-harness authentication secrets for this agent. Each field names a managed secret for the corresponding harness. @@ -11569,8 +11617,9 @@ components: field to attribute runs to another team member. Defaults to false. Only team admins may set this field. worker_host: - type: string - nullable: true + type: + - string + - 'null' description: | Optional default worker host for runs executed by this agent; omission, null, or an empty value stores no Agent default, in @@ -11590,36 +11639,44 @@ components: * Non-empty: replace the field wholesale with the provided value. `secrets_append` is an exception: it appends secrets idempotently and must be the only supplied field, including fields supplied as `null`. + `network_policy` is also an exception: omission preserves the policy, + null clears it, and an object replaces it wholesale. An object with + no allowed hosts carries deny-all intent. properties: name: type: string description: The new name for the agent description: - type: string - nullable: true + type: + - string + - 'null' description: | Replacement description. Omit or pass `null` to leave unchanged, or use an empty value to clear. prompt: - type: string - nullable: true + type: + - string + - 'null' description: | Replacement prompt. Omit or pass `null` to leave unchanged, or use an empty value to clear. environment_id: - type: string - nullable: true + type: + - string + - 'null' description: | Replacement default cloud environment ID. Omit or pass `null` to leave unchanged, or pass an empty string to clear. default_runner_uid: - type: string - nullable: true + type: + - string + - 'null' description: | Replacement default runner UID. Omit or pass `null` to leave unchanged, or pass an empty string to clear. A non-empty value must reference a runner the editor can View. secrets: - type: array - nullable: true + type: + - array + - 'null' items: $ref: '#/components/schemas/SecretRef' description: | @@ -11628,7 +11685,6 @@ components: Duplicate names are rejected. secrets_append: type: array - nullable: false items: $ref: '#/components/schemas/SecretRef' description: | @@ -11641,23 +11697,25 @@ components: the agent plus secret-attach access on its Factory. Agents managed in external source files return 409. skills: - type: array - nullable: true + type: + - array + - 'null' items: type: string description: | Replacement list of skill specs. Omit to leave unchanged, pass an empty array to clear, or pass a non-empty array to replace. base_model: - type: string - nullable: true + type: + - string + - 'null' description: | Replacement base model. Omit or pass `null` to leave unchanged, or pass an empty string to clear. memory: - allOf: - - $ref: '#/components/schemas/AgentMemoryUpdateConfig' - nullable: true + oneOf: + - $ref: '#/components/schemas/AgentMemoryUpdateConfig' + - type: 'null' description: Replacement memory settings for this agent. mcp_servers: type: object @@ -11669,18 +11727,18 @@ components: to replace. Run-level MCP config takes precedence over this agent-level default. inference_providers: - type: object - allOf: - - $ref: '#/components/schemas/InferenceProvidersConfig' - nullable: true + oneOf: + - $ref: '#/components/schemas/InferenceProvidersConfig' + - type: 'null' description: | 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 + type: + - string + - 'null' deprecated: true description: | Replacement default harness; omit or pass `null` to leave @@ -11689,17 +11747,17 @@ components: are sent, harness is authoritative and a conflicting type is rejected with invalid_request. harness: - allOf: - - $ref: '#/components/schemas/Harness' - nullable: true + oneOf: + - $ref: '#/components/schemas/Harness' + - type: 'null' description: | Replacement default harness for runs executed by this agent. Omit or pass `null` to leave unchanged, pass `{}` to clear the stored default, or pass a populated object to replace it wholesale. credential_strategy: - allOf: - - $ref: '#/components/schemas/AgentCredentialStrategy' - nullable: true + oneOf: + - $ref: '#/components/schemas/AgentCredentialStrategy' + - type: 'null' description: | Replacement default credential strategy. Omit or pass `null` to leave unchanged, or pass an empty string to clear the agent's @@ -11708,22 +11766,24 @@ components: file that declares none keeps the strategy already projected, so a clear is rejected with a 400. harness_auth_secrets: - allOf: - - $ref: '#/components/schemas/HarnessAuthSecrets' - nullable: true + oneOf: + - $ref: '#/components/schemas/HarnessAuthSecrets' + - type: 'null' description: | Replacement per-harness authentication secrets. Omit or pass `null` to leave unchanged, or pass an empty object to clear all secrets. on_behalf_of_enabled: - type: boolean - nullable: true + type: + - boolean + - 'null' description: | Whether runs created with this agent's API key may use the on_behalf_of field to attribute runs to another team member. Omit or pass `null` to leave unchanged. Only team admins may set this field. worker_host: - type: string - nullable: true + type: + - string + - 'null' description: | Replacement default worker host. Omit or pass `null` to leave unchanged, or pass an empty string to clear (the workspace default @@ -11733,15 +11793,15 @@ components: AgentResponse: type: object required: - - uid - - name - - available - - created_at - - updated_at - - secrets - - skills - - memory - - default_runner_uid + - uid + - name + - available + - created_at + - updated_at + - secrets + - skills + - memory + - default_runner_uid properties: uid: type: string @@ -11750,12 +11810,14 @@ components: type: string description: Name of the agent description: - type: string - nullable: true + type: + - string + - 'null' description: Optional description of the agent prompt: - type: string - nullable: true + type: + - string + - 'null' description: | Optional base prompt for this agent environment_id: @@ -11812,14 +11874,14 @@ components: 3. The team's default model inference_providers: allOf: - - $ref: '#/components/schemas/InferenceProvidersConfig' + - $ref: '#/components/schemas/InferenceProvidersConfig' description: | The agent's stored inference provider settings. May be overridden by run-level config; if empty, falls back to the workspace's admin-configured defaults. memory: allOf: - - $ref: '#/components/schemas/AgentMemoryResponse' + - $ref: '#/components/schemas/AgentMemoryResponse' description: | Memory settings for this agent. Always present; attached_stores is empty when no team stores are attached. @@ -11843,7 +11905,7 @@ components: {type, model_id, reasoning_level} default. harness: allOf: - - $ref: '#/components/schemas/Harness' + - $ref: '#/components/schemas/Harness' description: | Default harness for runs executed by this agent. Absent when the agent has no harness default. A stored model_id/reasoning_level @@ -11851,7 +11913,7 @@ components: harness's catalog. credential_strategy: allOf: - - $ref: '#/components/schemas/AgentCredentialStrategy' + - $ref: '#/components/schemas/AgentCredentialStrategy' description: | Default credential strategy for runs executed by this agent. Absent when the agent has no default. The precedence order for @@ -11864,7 +11926,7 @@ components: an unavailable credential rejects the request before execution. harness_auth_secrets: allOf: - - $ref: '#/components/schemas/HarnessAuthSecrets' + - $ref: '#/components/schemas/HarnessAuthSecrets' description: | Per-harness authentication secrets configured on this agent. Each field names a managed secret for the corresponding harness. @@ -11885,7 +11947,7 @@ components: ListAgentIdentitiesResponse: type: object required: - - agents + - agents properties: agents: type: array @@ -11895,11 +11957,11 @@ components: type: object description: Summary of the most recently created task for an environment required: - - id - - title - - state - - created_at - - updated_at + - id + - title + - state + - created_at + - updated_at properties: id: type: string @@ -11918,36 +11980,37 @@ components: format: date-time description: When the task was last updated (RFC3339) started_at: - type: string + type: + - string + - 'null' format: date-time - nullable: true - description: 'When the task started running (RFC3339), null if not yet started' + description: When the task started running (RFC3339), null if not yet started BenchmarkRunState: type: string description: Lifecycle state of a benchmark run. enum: - - pending - - running - - scoring - - completed - - failed - - cancelled + - pending + - running + - scoring + - completed + - failed + - cancelled BenchmarkTrialState: type: string description: Lifecycle state of a benchmark trial. enum: - - pending - - running - - succeeded - - failed - - cancelled + - pending + - running + - succeeded + - failed + - cancelled BenchmarkRepoRef: type: object description: A repository location and optional starting ref for a suite task. required: - - code_forge - - owner - - repo + - code_forge + - owner + - repo properties: code_forge: type: string @@ -11960,10 +12023,10 @@ components: BenchmarkSuiteTask: type: object required: - - uid - - title - - prompt - - success_criteria + - uid + - title + - prompt + - success_criteria properties: uid: type: string @@ -11980,8 +12043,9 @@ components: against, as the authoritative requirements. The task prompt provides context only. source_run_id: - type: string - nullable: true + type: + - string + - 'null' labels: type: object additionalProperties: @@ -11997,9 +12061,9 @@ components: BenchmarkAgentConfigInput: type: object required: - - agent_uid - - harness - - model + - agent_uid + - harness + - model properties: agent_uid: type: string @@ -12011,18 +12075,19 @@ components: model: type: string harness_auth_secret_name: - type: string - nullable: true + type: + - string + - 'null' BenchmarkSuite: type: object required: - - uid - - factory_uid - - name - - agent_uid - - factory_agent_type - - created_at - - updated_at + - uid + - factory_uid + - name + - agent_uid + - factory_agent_type + - created_at + - updated_at properties: uid: type: string @@ -12051,7 +12116,7 @@ components: format: date-time creator: allOf: - - $ref: '#/components/schemas/BenchmarkSuiteCreator' + - $ref: '#/components/schemas/BenchmarkSuiteCreator' description: | The suite's creator, when known. Absent when creator identity is unknown or no longer retained. @@ -12063,47 +12128,48 @@ components: BenchmarkSuiteCreator: type: object required: - - type - - uid + - type + - uid properties: type: type: string enum: - - user - - agent + - user + - agent uid: type: string display_name: type: string BenchmarkSuiteDetail: allOf: - - $ref: '#/components/schemas/BenchmarkSuite' - - type: object - required: - - spawnable_descendant_agent_uids - properties: - tasks: - type: array - items: - $ref: '#/components/schemas/BenchmarkSuiteTask' - spawnable_descendant_agent_uids: - type: array - items: - type: string - description: | - Stable UID-sorted list of live, non-system Factory agents - transitively reachable from this suite's selected root under - the server's effective delegation policy. + - $ref: '#/components/schemas/BenchmarkSuite' + - type: object + required: + - spawnable_descendant_agent_uids + properties: + tasks: + type: array + items: + $ref: '#/components/schemas/BenchmarkSuiteTask' + spawnable_descendant_agent_uids: + type: array + items: + type: string + description: | + Stable UID-sorted list of live, non-system Factory agents + transitively reachable from this suite's selected root under + the server's effective delegation policy. BenchmarkSuiteCreateRequest: type: object required: - - uid - - name - - agent_uid - - factory_agent_type + - uid + - name + - agent_uid + - factory_agent_type properties: uid: type: string + x-stainless-param: suite_uid name: type: string description: @@ -12123,9 +12189,9 @@ components: BenchmarkSuiteTaskInput: type: object required: - - title - - prompt - - success_criteria + - title + - prompt + - success_criteria properties: uid: type: string @@ -12142,8 +12208,9 @@ components: against, as the authoritative requirements. The task prompt provides context only. source_run_id: - type: string - nullable: true + type: + - string + - 'null' labels: type: object additionalProperties: @@ -12159,9 +12226,9 @@ components: BenchmarkSuiteTaskCreateRequest: type: object required: - - title - - prompt - - success_criteria + - title + - prompt + - success_criteria properties: title: type: string @@ -12174,8 +12241,9 @@ components: against, as the authoritative requirements. The task prompt provides context only. source_run_id: - type: string - nullable: true + type: + - string + - 'null' description: | Optional provenance. The caller must be able to read the run. tags: @@ -12196,8 +12264,9 @@ components: success_criteria: type: string source_run_id: - type: string - nullable: true + type: + - string + - 'null' tags: type: array items: @@ -12217,14 +12286,16 @@ components: model: type: string runner_id: - type: string - nullable: true + type: + - string + - 'null' description: | Optional runner UID, constrained to the Factory's existing runner roster. Omitted or empty uses the agent's or environment's default. harness_auth_secret_name: - type: string - nullable: true + type: + - string + - 'null' description: | Optional managed-secret name this configuration's third-party harness authenticates with. Empty or omitted is valid for Oz. For a third-party @@ -12250,8 +12321,9 @@ components: factory_agent_type: type: string tasks: - type: array - nullable: true + type: + - array + - 'null' description: | The array order is not significant: a task's identity comes from its uid (when editing an existing task) or title (when creating one), @@ -12261,7 +12333,7 @@ components: LaunchBenchmarkRunRequest: type: object required: - - repetition_count + - repetition_count properties: configurations: type: array @@ -12282,9 +12354,9 @@ components: type: array items: oneOf: - - $ref: '#/components/schemas/ScorerUID' - - type: integer - minimum: 1 + - $ref: '#/components/schemas/ScorerUID' + - type: integer + minimum: 1 description: | Allowlist of live scorer UUIDs (or temporary positive numeric IDs) for this factory, applied to every trial in the run. Empty or absent means all applicable scorers. IDs must @@ -12295,8 +12367,8 @@ components: uniqueItems: true items: type: string - example: - - 7d69fb52-71c5-4e27-914e-8764ee9c5246 + examples: + - - 7d69fb52-71c5-4e27-914e-8764ee9c5246 - ad8ff7dc-a7d1-4ed6-9f50-650010bb39aa description: | Optional allowlist of immutable UIDs for current tasks in the addressed @@ -12305,8 +12377,8 @@ components: BenchmarkRunLaunchResponse: type: object required: - - uid - - state + - uid + - state properties: uid: type: string @@ -12315,63 +12387,63 @@ components: BenchmarkRunList: type: object required: - - data - - page_info + - data + - page_info properties: data: type: array items: $ref: '#/components/schemas/BenchmarkRun' - description: 'complete requested Run rows on this page, newest first.' + description: complete requested Run rows on this page, newest first. page_info: $ref: '#/components/schemas/BenchmarkPageInfo' description: continuation for this Run list only. BenchmarkTrialList: type: object required: - - data - - page_info + - data + - page_info properties: data: type: array items: $ref: '#/components/schemas/BenchmarkTrial' - description: 'complete requested logical Trial rows on this page, or zero/one targeted match.' + description: complete requested logical Trial rows on this page, or zero/one targeted match. page_info: $ref: '#/components/schemas/BenchmarkPageInfo' description: continuation for the Trial list; targeted lookup always has `has_next_page=false`. BenchmarkPageInfo: type: object required: - - has_next_page + - has_next_page properties: has_next_page: type: boolean description: true when another complete list page exists. next_cursor: type: string - description: 'opaque scoped keyset cursor, present only when `has_next_page=true`, never null.' + description: opaque scoped keyset cursor, present only when `has_next_page=true`, never null. BenchmarkRun: type: object required: - - uid - - factory_uid - - suite_uid - - suite_name - - agent_uid - - agent_name - - state - - created_at - - updated_at - - started_at - - completed_at - - creator - - execution - - scoring + - uid + - factory_uid + - suite_uid + - suite_name + - agent_uid + - agent_name + - state + - created_at + - updated_at + - started_at + - completed_at + - creator + - execution + - scoring properties: uid: type: string - description: 'existing benchmark Run UID, including legacy non-UUID identities.' + description: existing benchmark Run UID, including legacy non-UUID identities. factory_uid: type: string description: authorized owning Factory UID. @@ -12385,17 +12457,20 @@ components: type: string description: suite UID verified against the frozen Run context. suite_name: - type: string - nullable: true + type: + - string + - 'null' description: retained frozen suite name; unknown legacy name is null. agent_uid: - type: string - nullable: true + type: + - string + - 'null' description: tested root agent's frozen UID when retained. agent_name: - type: string - nullable: true - description: 'tested root agent''s frozen name, not today''s catalog name.' + type: + - string + - 'null' + description: tested root agent's frozen name, not today's catalog name. state: $ref: '#/components/schemas/BenchmarkRunState' description: captured benchmark Run lifecycle state. @@ -12406,64 +12481,67 @@ components: updated_at: type: string format: date-time - description: 'stored Run update time, not a complete source-validity watermark.' + description: stored Run update time, not a complete source-validity watermark. started_at: - type: string + type: + - string + - 'null' format: date-time - nullable: true description: stored Run start time; null before start or if not retained. completed_at: - type: string + type: + - string + - 'null' format: date-time - nullable: true description: stored Run terminal time; null while active or if not retained. creator: - allOf: - - $ref: '#/components/schemas/BenchmarkRunCreator' - nullable: true - description: 'safe retained creator identity, or null when it cannot be resolved.' + oneOf: + - $ref: '#/components/schemas/BenchmarkRunCreator' + - type: 'null' + description: safe retained creator identity, or null when it cannot be resolved. execution: $ref: '#/components/schemas/BenchmarkExecutionProgress' - description: 'logical Trial counts, never attempt/descendant counts.' + description: logical Trial counts, never attempt/descendant counts. scoring: $ref: '#/components/schemas/BenchmarkRunScoring' - description: 'existing raw ledger and logical-Trial judging progress, without score values.' + description: existing raw ledger and logical-Trial judging progress, without score values. details: $ref: '#/components/schemas/BenchmarkRunDetails' description: present only for `include=details`; always non-null when requested. summary_results: $ref: '#/components/schemas/BenchmarkResultsSummary' - description: 'present only for `include=summary_results`; whole-run, on-request summary without metric arrays.' + description: present only for `include=summary_results`; whole-run, on-request summary without metric arrays. BenchmarkRunCreator: type: object required: - - type - - uid + - type + - uid properties: type: type: string enum: - - user - - agent + - user + - agent description: resolved creator type; agent includes identities behind API keys. uid: type: string - description: 'creator''s public UID, never its database ID.' + description: creator's public UID, never its database ID. display_name: - type: string - nullable: true - description: 'present only for an authorized creator-display-name include; null if the name is unknown, with no email fallback.' + type: + - string + - 'null' + description: present only for an authorized creator-display-name include; null if the name is unknown, with no email fallback. BenchmarkExecutionProgress: type: object required: - - planned_total - - total - - pending - - running - - succeeded - - failed - - cancelled - - completed + - planned_total + - total + - pending + - running + - succeeded + - failed + - cancelled + - completed properties: planned_total: type: integer @@ -12473,7 +12551,7 @@ components: description: observed stored logical Trial row count. pending: type: integer - description: 'Trials without a currently executing attempt, including queued/claimed attempts.' + description: Trials without a currently executing attempt, including queued/claimed attempts. running: type: integer description: Trials with a currently executing attempt. @@ -12492,23 +12570,24 @@ components: BenchmarkRunScoring: type: object required: - - total - - awaiting_trial - - pending - - judging - - scored - - finished_unscored - - not_scoreable - - received - - expected - - settled - - trials_being_judged - - trials_scoring_finished + - total + - awaiting_trial + - pending + - judging + - scored + - finished_unscored + - not_scoreable + - received + - expected + - settled + - trials_being_judged + - trials_scoring_finished properties: total: - type: integer - nullable: true - description: 'all applicable ledger pairs; null before materialization, zero only for known zero work.' + type: + - integer + - 'null' + description: all applicable ledger pairs; null before materialization, zero only for known zero work. awaiting_trial: type: integer description: raw pairs still waiting for execution to finish. @@ -12520,7 +12599,7 @@ components: description: raw pairs with an active judge. scored: type: integer - description: 'raw pairs marked scored in the durable ledger, even if bound evidence is now absent.' + description: raw pairs marked scored in the durable ledger, even if bound evidence is now absent. finished_unscored: type: integer description: raw pairs settled without a score. @@ -12529,10 +12608,11 @@ components: description: raw pairs skipped because execution failed or was cancelled. received: type: integer - description: 'exactly raw `scored`, not effective retained-score coverage.' + description: exactly raw `scored`, not effective retained-score coverage. expected: - type: integer - nullable: true + type: + - integer + - 'null' description: '`pending + judging + scored + finished_unscored` once materialized; otherwise null.' settled: type: integer @@ -12546,34 +12626,34 @@ components: BenchmarkRunDetails: type: object required: - - configurations - - task_uids - - repetition_count - - scorer_selection - - scorers - - tags + - configurations + - task_uids + - repetition_count + - scorer_selection + - scorers + - tags properties: configurations: type: array items: $ref: '#/components/schemas/BenchmarkRecordedConfiguration' - description: 'complete frozen configurations in launch order, including tooltip settings.' + description: complete frozen configurations in launch order, including tooltip settings. task_uids: type: array items: type: string - description: 'complete selected frozen task identities in launch order, including derived legacy identities.' + description: complete selected frozen task identities in launch order, including derived legacy identities. repetition_count: type: integer description: frozen repetitions per task/configuration. scorer_selection: $ref: '#/components/schemas/BenchmarkScorerSelection' - description: 'recorded launch selection, not the materialized roster.' + description: recorded launch selection, not the materialized roster. scorers: type: array items: $ref: '#/components/schemas/BenchmarkScorer' - description: 'safe descriptors for this Run''s resolved scorers, using the existing authorized resolver.' + description: safe descriptors for this Run's resolved scorers, using the existing authorized resolver. tags: type: array items: @@ -12582,81 +12662,89 @@ components: BenchmarkRecordedConfiguration: type: object required: - - uid - - display_name - - harness - - model - - runner_id - - harness_auth_secret_name - - agent_configs + - uid + - display_name + - harness + - model + - runner_id + - harness_auth_secret_name + - agent_configs properties: uid: type: string - description: 'stable Run-local public configuration identity, without exposing its stored integer ID.' + description: stable Run-local public configuration identity, without exposing its stored integer ID. display_name: type: string description: frozen user-supplied name; the existing empty string means no supplied name. harness: - type: string - nullable: true + type: + - string + - 'null' description: recorded effective root harness; unknown legacy values remain null. model: - type: string - nullable: true + type: + - string + - 'null' description: recorded effective root model; never filled from live defaults. runner_id: - type: string - nullable: true + type: + - string + - 'null' description: recorded root runner identity; no per-agent runner is introduced. harness_auth_secret_name: - type: string - nullable: true - description: 'retained root credential-name reference, including unavailable names.' + type: + - string + - 'null' + description: retained root credential-name reference, including unavailable names. agent_configs: type: array items: $ref: '#/components/schemas/BenchmarkRecordedAgentConfiguration' - description: 'complete retained named-agent settings, including the root when recorded.' + description: complete retained named-agent settings, including the root when recorded. BenchmarkRecordedAgentConfiguration: type: object required: - - agent_uid - - agent_name - - harness - - model - - harness_auth_secret_name + - agent_uid + - agent_name + - harness + - model + - harness_auth_secret_name properties: agent_uid: type: string description: frozen named Factory agent UID. agent_name: - type: string - nullable: true + type: + - string + - 'null' description: retained frozen named-agent label. harness: - type: string - nullable: true + type: + - string + - 'null' description: named agent's recorded effective harness. model: - type: string - nullable: true + type: + - string + - 'null' description: named agent's recorded effective model. harness_auth_secret_name: - type: string - nullable: true + type: + - string + - 'null' description: retained named-agent credential-name reference. BenchmarkScorerSelection: type: object required: - - mode - - scorer_uids + - mode + - scorer_uids properties: mode: type: string enum: - - all_applicable - - selected - description: 'preserved launch selection mode, even if selected scorers later disappear.' + - all_applicable + - selected + description: preserved launch selection mode, even if selected scorers later disappear. scorer_uids: type: array items: @@ -12665,25 +12753,25 @@ components: BenchmarkScorer: type: object required: - - scorer_uid - - name - - kind - - output_type - - output_labels + - scorer_uid + - name + - kind + - output_type + - output_labels properties: scorer_uid: type: string description: canonical scorer UUID supplied by the integrated identity adapter. name: type: string - description: 'existing resolved scorer name, not a promised launch-frozen name.' + description: existing resolved scorer name, not a promised launch-frozen name. kind: $ref: '#/components/schemas/ScorerKind' description: existing resolved scorer kind. output_type: type: string enum: - - classification + - classification description: current benchmark results support classification only. output_labels: type: array @@ -12693,32 +12781,32 @@ components: BenchmarkTagTasks: type: object required: - - tag - - task_uids + - tag + - task_uids properties: tag: type: string - description: 'exact frozen tag value, ordered lexically.' + description: exact frozen tag value, ordered lexically. task_uids: type: array items: type: string - description: 'complete distinct selected frozen task UIDs carrying this tag, in the containing `details.task_uids` order.' + description: complete distinct selected frozen task UIDs carrying this tag, in the containing `details.task_uids` order. BenchmarkTrial: type: object required: - - uid - - run_uid - - task_uid - - task_title - - task_tags - - configuration_uid - - repetition_index - - state - - terminal_reason - - current_agent_run_id - - attempt_count - - scoring + - uid + - run_uid + - task_uid + - task_title + - task_tags + - configuration_uid + - repetition_index + - state + - terminal_reason + - current_agent_run_id + - attempt_count + - scoring properties: uid: type: string @@ -12728,16 +12816,17 @@ components: description: containing benchmark Run UID. task_uid: type: string - description: 'frozen task UID, or stable Run-local public identity for a legacy task.' + description: frozen task UID, or stable Run-local public identity for a legacy task. task_title: - type: string - nullable: true + type: + - string + - 'null' description: frozen task title; unknown legacy title remains null. task_tags: type: array items: type: string - description: 'complete frozen task tags, not live tags.' + description: complete frozen task tags, not live tags. configuration_uid: type: string description: containing Run's stable public configuration identity. @@ -12748,24 +12837,26 @@ components: $ref: '#/components/schemas/BenchmarkTrialState' description: captured logical Trial state after queued/claimed normalization. terminal_reason: - type: string - enum: + oneOf: + - type: string + enum: - timeout - failure - nullable: true + - type: 'null' description: existing failed-Trial distinction; cancellation is already in `state`. current_agent_run_id: - type: string - nullable: true + type: + - string + - 'null' description: current execution attempt ID; null before dispatch. attempt_count: type: integer - description: 'stored dispatch count; zero before dispatch, legacy dispatched fallback one.' + description: stored dispatch count; zero before dispatch, legacy dispatched fallback one. scoring: type: array items: $ref: '#/components/schemas/BenchmarkTrialScoringStatus' - description: 'complete resolved classification-scorer rows with existing ledger status when present, without values/verdicts or scorer projection.' + description: complete resolved classification-scorer rows with existing ledger status when present, without values/verdicts or scorer projection. matched_attempt_number: type: integer description: one-based retained/current execution match on targeted lookup only; omitted elsewhere. @@ -12778,32 +12869,32 @@ components: BenchmarkTrialScoringStatus: type: object required: - - scorer_uid - - state + - scorer_uid + - state properties: scorer_uid: type: string description: resolved canonical scorer UUID. state: - allOf: - - $ref: '#/components/schemas/BenchmarkTrialScoringState' - nullable: true + oneOf: + - $ref: '#/components/schemas/BenchmarkTrialScoringState' + - type: 'null' description: existing effective ledger status after binding/cutoff checks; null when no ledger row exists. BenchmarkTrialResults: type: object required: - - scoring - - metrics - - spend + - scoring + - metrics + - spend properties: scoring: type: array items: $ref: '#/components/schemas/BenchmarkTrialScoringResult' - description: 'complete resolved scorer rows with existing evidence/status, including pending/unscored or absent-work rows.' + description: complete resolved scorer rows with existing evidence/status, including pending/unscored or absent-work rows. metrics: $ref: '#/components/schemas/BenchmarkTrialMetrics' - description: current retained retry-inclusive execution measurements under existing loader semantics. + description: final retained live-tree run counts and retry-inclusive execution costs and durations. spend: $ref: '#/components/schemas/BenchmarkSpend' description: retained execution/judging/combined totals under existing arithmetic. @@ -12811,26 +12902,26 @@ components: type: array items: $ref: '#/components/schemas/BenchmarkTrialAgentMetric' - description: complete existing named-agent breakdown when available; omitted when the existing loader suppresses an empty/incomplete breakdown. + description: available named-agent counts and retry-inclusive costs; count-only rows have null cost_usd. Omitted when no named-agent evidence is available. BenchmarkTrialScoringResult: type: object required: - - scorer_uid - - state - - name - - kind - - score - - label - - outcome - - latest_judge_run_id + - scorer_uid + - state + - name + - kind + - score + - label + - outcome + - latest_judge_run_id properties: scorer_uid: type: string description: resolved canonical scorer UUID. state: - allOf: - - $ref: '#/components/schemas/BenchmarkTrialScoringState' - nullable: true + oneOf: + - $ref: '#/components/schemas/BenchmarkTrialScoringState' + - type: 'null' description: existing effective ledger status after binding/cutoff checks; null when no ledger row exists. name: type: string @@ -12839,38 +12930,55 @@ components: $ref: '#/components/schemas/ScorerKind' description: existing authorized resolver kind. score: - type: number + type: + - number + - 'null' format: double - nullable: true description: exact retained bound classification value at/before cutoff; zero is a real score. label: - type: string - nullable: true + type: + - string + - 'null' description: label from that same bound score; null when no score evidence survives. outcome: - type: string - enum: + oneOf: + - type: string + enum: - pass - fail - nullable: true + - type: 'null' description: existing SQL-derived current-threshold verdict; null when no verdict is supplied. latest_judge_run_id: - type: string - nullable: true + type: + - string + - 'null' description: latest retained judge execution ID by dispatch order; no full judge history is implied. BenchmarkTrialMetrics: type: object - required: - - compute_credits - - platform_credits - - inference_credits - - total_credits - - wall_time_s - - compute_cost_usd - - platform_cost_usd - - inference_cost_usd - - cost_usd - properties: + description: Metrics for a benchmark trial. A run is a persisted platform agent task instance; an execution is one session of that run with a recorded agent start. Resuming a run can add an execution without adding a run. Run/execution counts cover the final trial attempt's root and recursively spawned agents. Scorer runs and all their descendants are excluded. + required: + - agent_runs + - agent_executions + - compute_credits + - platform_credits + - inference_credits + - total_credits + - wall_time_s + - compute_cost_usd + - platform_cost_usd + - inference_cost_usd + - cost_usd + properties: + agent_runs: + type: + - integer + - 'null' + description: Distinct persisted platform agent task instances in the final retained live trial tree, excluding scorer runs and their descendants. Attempted runs count even if they never start or later fail. Superseded trial attempts are excluded. Null when the live tree is unavailable; deleted history is not reconstructed. + agent_executions: + type: + - integer + - 'null' + description: Distinct execution IDs with recorded agent starts in the same final retained live tree as agent_runs, including resumed sessions and starts that later fail. Dispatch or boot retries without an agent start do not count. Null when execution evidence is ambiguous or missing, independently of agent_runs; measured zero is present. compute_credits: type: string description: summed retained execution-attempt compute credits. @@ -12886,7 +12994,7 @@ components: wall_time_s: type: number format: double - description: 'summed retained attempt working durations, excluding teardown; not the span between Trial.details timestamps.' + description: summed retained attempt working durations, excluding teardown; not the span between Trial.details timestamps. compute_cost_usd: type: number format: double @@ -12898,41 +13006,41 @@ components: inference_cost_usd: type: number format: double - description: 'existing inference dollars, including applicable third-party provider estimates.' + description: existing inference dollars, including applicable third-party provider estimates. cost_usd: type: number format: double - description: 'sum of the three dollar components, not guaranteed exact billed cost.' + description: sum of the three dollar components, not guaranteed exact billed cost. provider_cost_estimate: $ref: '#/components/schemas/BenchmarkProviderCostEstimate' - description: 'existing provider estimate/attribution, omitted when unavailable; never an invented zero estimate.' + description: existing provider estimate/attribution, omitted when unavailable; never an invented zero estimate. output_tokens: type: integer - description: 'sum of reported retained output-token counts; omitted when unreported, but reported zero remains present.' + description: sum of reported retained output-token counts; omitted when unreported, but reported zero remains present. tool_calls: type: integer - description: 'sum of reported retained tool-call counts; omitted when unreported, but reported zero remains present.' + description: sum of reported retained tool-call counts; omitted when unreported, but reported zero remains present. BenchmarkSpend: type: object required: - - execution - - judging - - combined + - execution + - judging + - combined properties: execution: $ref: '#/components/schemas/BenchmarkSpendTotal' description: retry-inclusive retained execution totals under existing attribution. judging: $ref: '#/components/schemas/BenchmarkSpendTotal' - description: 'totals for distinct durably linked retained judge runs, including repeated rescores.' + description: totals for distinct durably linked retained judge runs, including repeated rescores. combined: $ref: '#/components/schemas/BenchmarkSpendTotal' description: execution plus judging totals. BenchmarkSpendTotal: type: object required: - - cost_usd - - total_credits + - cost_usd + - total_credits properties: cost_usd: type: number @@ -12943,34 +13051,49 @@ components: description: existing Warp credit total for this spend group. BenchmarkTrialAgentMetric: type: object - required: - - agent_uid - - agent_name - - cost_usd - properties: + description: Named-agent breakdown of trial metrics, with the platform run/execution definitions and scorer-branch exclusions of BenchmarkTrialMetrics. + required: + - agent_runs + - agent_executions + - agent_uid + - agent_name + - cost_usd + properties: + agent_runs: + type: + - integer + - 'null' + description: Distinct persisted platform agent task instances attributed to this agent in the final retained live trial tree, excluding scorer runs and their descendants. Attempts count even if they never start or later fail. Superseded attempts are excluded. Confirmed absence is zero; null means the live tree is unavailable. + agent_executions: + type: + - integer + - 'null' + description: Distinct execution IDs with recorded agent starts attributed to this agent in the same final retained live tree as agent_runs, including resumed sessions and starts that later fail. Dispatch or boot retries without an agent start do not count. Null means this agent's execution evidence is ambiguous or missing, independently of agent_runs; confirmed absence is zero. agent_uid: type: string description: existing named-agent identity; the empty string retains the Unknown-agent fallback. agent_name: type: string - description: 'existing resolved label, including `"Unknown agent"` when identity is unavailable.' + description: existing resolved label, including `"Unknown agent"` when identity is unavailable. cost_usd: - type: number + type: + - number + - 'null' format: double - description: existing exclusive named-agent cost summed across retained retries and non-system descendants. + description: Exclusive named-agent cost summed across retained retries and spawned agents, excluding scorer runs and their descendants; null when only count evidence is available. sandbox_time_s: type: number format: double - description: 'existing summed claim-to-completion seconds, omitted when any contributing duration is unknown; measured zero is present.' + description: existing summed claim-to-completion seconds, omitted when any contributing duration is unknown; measured zero is present. cost_breakdown: $ref: '#/components/schemas/BenchmarkAgentCostBreakdown' - description: 'Retained exclusive costs and public-model attribution, omitted when the existing loader gate or availability suppresses it.' + description: Retained exclusive costs and public-model attribution, omitted when the existing loader gate or availability suppresses it. BenchmarkAgentCostBreakdown: type: object required: - - compute_cost_usd - - platform_cost_usd - - inference_cost_usd + - compute_cost_usd + - platform_cost_usd + - inference_cost_usd properties: compute_cost_usd: type: number @@ -12988,7 +13111,7 @@ components: BenchmarkCategoryCost: type: object required: - - cost_usd + - cost_usd properties: cost_usd: type: number @@ -13001,12 +13124,12 @@ components: BenchmarkProviderCostEstimate: type: object required: - - cost_usd - - incomplete + - cost_usd + - incomplete properties: cost_usd: type: string - description: 'public-rate estimated provider total, not a Warp-billed amount.' + description: public-rate estimated provider total, not a Warp-billed amount. incomplete: type: boolean description: existing signal that estimate inputs/pricing are incomplete. @@ -13018,9 +13141,9 @@ components: BenchmarkProviderCostAttribution: type: object required: - - model - - cost_usd - - incomplete + - model + - cost_usd + - incomplete properties: model: type: string @@ -13035,19 +13158,19 @@ components: type: array items: $ref: '#/components/schemas/BenchmarkProviderTokenCost' - description: 'complete retained priced token buckets, omitted when empty/unavailable.' + description: complete retained priced token buckets, omitted when empty/unavailable. adjustments: type: array items: $ref: '#/components/schemas/BenchmarkProviderCostAdjustment' - description: 'complete retained price multipliers, omitted when empty/unavailable.' + description: complete retained price multipliers, omitted when empty/unavailable. BenchmarkProviderTokenCost: type: object required: - - kind - - tokens - - rate_usd_per_million - - cost_usd + - kind + - tokens + - rate_usd_per_million + - cost_usd properties: kind: type: string @@ -13064,66 +13187,68 @@ components: BenchmarkProviderCostAdjustment: type: object required: - - kind - - multiplier + - kind + - multiplier properties: kind: type: string - description: 'existing adjustment kind, not credential metadata.' + description: existing adjustment kind, not credential metadata. multiplier: type: string description: dimensionless multiplier applied after token subtotals. BenchmarkTrialDetails: type: object required: - - started_at - - completed_at - - attempts - - judge_runs + - started_at + - completed_at + - attempts + - judge_runs properties: started_at: - type: string + type: + - string + - 'null' format: date-time - nullable: true description: earliest retained execution claim across the Trial's attempts. completed_at: - type: string + type: + - string + - 'null' format: date-time - nullable: true description: current attempt's retained terminal time only when the logical Trial is terminal. attempts: type: array items: $ref: '#/components/schemas/BenchmarkExecutionAttempt' - description: 'every retained execution attempt, ordered by one-based attempt number.' + description: every retained execution attempt, ordered by one-based attempt number. judge_runs: type: array items: $ref: '#/components/schemas/BenchmarkRetainedJudgeRun' - description: 'every retained durable judge dispatch across scorers/rescores, ordered by dispatch time and internal row tie-breaker.' + description: every retained durable judge dispatch across scorers/rescores, ordered by dispatch time and internal row tie-breaker. BenchmarkExecutionAttempt: type: object required: - - attempt_number - - agent_run_id - - state + - attempt_number + - agent_run_id + - state properties: attempt_number: type: integer - description: 'one-based position in the original attempt chain, not an array index after retention loss.' + description: one-based position in the original attempt chain, not an array index after retention loss. agent_run_id: type: string description: retained execution attempt ID. state: $ref: '#/components/schemas/BenchmarkExecutionState' - description: 'underlying retained execution state, without logical Trial-state normalization.' + description: underlying retained execution state, without logical Trial-state normalization. BenchmarkRetainedJudgeRun: type: object required: - - scorer_uid - - name - - kind - - agent_run_id + - scorer_uid + - name + - kind + - agent_run_id properties: scorer_uid: type: string @@ -13140,21 +13265,21 @@ components: BenchmarkResultsSummary: type: object required: - - factory_uid - - suite_uid - - run_uid - - state - - as_of - - provisional - - incomplete_reason - - coverage - - compute_credits - - platform_credits - - spend - - elapsed_s - - task_count - - scorer_count - - narrative + - factory_uid + - suite_uid + - run_uid + - state + - as_of + - provisional + - incomplete_reason + - coverage + - compute_credits + - platform_credits + - spend + - elapsed_s + - task_count + - scorer_count + - narrative properties: factory_uid: type: string @@ -13176,12 +13301,13 @@ components: type: boolean description: true for pending/running/scoring Runs whose values can still change. incomplete_reason: - type: string - nullable: true + type: + - string + - 'null' description: existing safe failed/cancelled partial-results explanation; null in other states. coverage: $ref: '#/components/schemas/BenchmarkResultsCoverage' - description: 'count-only execution/scoring evidence coverage, separate from raw progress.' + description: count-only execution/scoring evidence coverage, separate from raw progress. compute_credits: type: string description: existing selected execution compute-credit total from RunMetrics. @@ -13189,30 +13315,32 @@ components: type: string description: existing selected execution platform-credit total from RunMetrics. spend: - allOf: - - $ref: '#/components/schemas/BenchmarkSpend' - nullable: true + oneOf: + - $ref: '#/components/schemas/BenchmarkSpend' + - type: 'null' description: selected-dataset retry/judge totals; null before any selected Trial dispatch. elapsed_s: - type: number + type: + - number + - 'null' format: double - nullable: true - description: 'Run span from start through completion/calculation time, including scoring; null before start or if start is unknown.' + description: Run span from start through completion/calculation time, including scoring; null before start or if start is unknown. task_count: type: integer - description: 'distinct selected frozen tasks, independent of display projections and Trial pages.' + description: distinct selected frozen tasks, independent of display projections and Trial pages. scorer_count: - type: integer - nullable: true - description: 'count of resolved scorer descriptors, as in current history statistics; null before any selected Trial dispatch.' + type: + - integer + - 'null' + description: count of resolved scorer descriptors, as in current history statistics; null before any selected Trial dispatch. narrative: $ref: '#/components/schemas/BenchmarkNarrative' description: independent stored-narrative availability and eligible text. BenchmarkResultsCoverage: type: object required: - - execution - - scoring + - execution + - scoring properties: execution: $ref: '#/components/schemas/BenchmarkExecutionCoverage' @@ -13223,65 +13351,67 @@ components: BenchmarkExecutionCoverage: type: object required: - - planned_trial_count - - materialized_trial_count + - planned_trial_count + - materialized_trial_count properties: planned_trial_count: type: integer - description: 'selected frozen matrix size, equal to `execution.planned_total`.' + description: selected frozen matrix size, equal to `execution.planned_total`. materialized_trial_count: type: integer - description: 'observed selected logical Trial rows, equal to `execution.total`.' + description: observed selected logical Trial rows, equal to `execution.total`. BenchmarkScoringCoverage: type: object required: - - effective_scored_pair_count - - expected_pair_count + - effective_scored_pair_count + - expected_pair_count properties: effective_scored_pair_count: type: integer description: pairs whose exact bound score resolves under retention/access and at/before cutoff. expected_pair_count: - type: integer - nullable: true + type: + - integer + - 'null' description: materialized `pending + judging + scored + finished_unscored`; excludes awaiting-trial/not-scoreable and is null before membership is known. BenchmarkNarrative: type: object required: - - availability - - text + - availability + - text properties: availability: type: string enum: - - pending - - available - - unavailable - description: 'current stored generation/lifecycle gate, not metric completeness.' + - pending + - available + - unavailable + description: current stored generation/lifecycle gate, not metric completeness. text: - type: string - nullable: true + type: + - string + - 'null' description: nonempty retained narrative only when available; null otherwise. BenchmarkResults: type: object required: - - factory_uid - - suite_uid - - run_uid - - state - - as_of - - provisional - - incomplete_reason - - coverage - - compute_credits - - platform_credits - - spend - - elapsed_s - - task_count - - scorer_count - - narrative - - execution - - scoring + - factory_uid + - suite_uid + - run_uid + - state + - as_of + - provisional + - incomplete_reason + - coverage + - compute_credits + - platform_credits + - spend + - elapsed_s + - task_count + - scorer_count + - narrative + - execution + - scoring properties: factory_uid: type: string @@ -13303,12 +13433,13 @@ components: type: boolean description: true for pending/running/scoring Runs whose values can still change. incomplete_reason: - type: string - nullable: true + type: + - string + - 'null' description: existing safe failed/cancelled partial-results explanation; null in other states. coverage: $ref: '#/components/schemas/BenchmarkResultsCoverage' - description: 'count-only execution/scoring evidence coverage, separate from raw progress.' + description: count-only execution/scoring evidence coverage, separate from raw progress. compute_credits: type: string description: existing selected execution compute-credit total from RunMetrics. @@ -13316,22 +13447,24 @@ components: type: string description: existing selected execution platform-credit total from RunMetrics. spend: - allOf: - - $ref: '#/components/schemas/BenchmarkSpend' - nullable: true + oneOf: + - $ref: '#/components/schemas/BenchmarkSpend' + - type: 'null' description: selected-dataset retry/judge totals; null before any selected Trial dispatch. elapsed_s: - type: number + type: + - number + - 'null' format: double - nullable: true - description: 'Run span from start through completion/calculation time, including scoring; null before start or if start is unknown.' + description: Run span from start through completion/calculation time, including scoring; null before start or if start is unknown. task_count: type: integer - description: 'distinct selected frozen tasks, independent of display projections and Trial pages.' + description: distinct selected frozen tasks, independent of display projections and Trial pages. scorer_count: - type: integer - nullable: true - description: 'count of resolved scorer descriptors, as in current history statistics; null before any selected Trial dispatch.' + type: + - integer + - 'null' + description: count of resolved scorer descriptors, as in current history statistics; null before any selected Trial dispatch. narrative: $ref: '#/components/schemas/BenchmarkNarrative' description: independent stored-narrative availability and eligible text. @@ -13364,13 +13497,13 @@ components: BenchmarkConfigurationAggregate: type: object required: - - configuration_uid - - execution - - metrics - - scoring - - retried_trial_count - - retry_count - - overall_mean + - configuration_uid + - execution + - metrics + - scoring + - retried_trial_count + - retry_count + - overall_mean properties: configuration_uid: type: string @@ -13389,25 +13522,41 @@ components: description: logical Trials with more than one execution attempt. retry_count: type: integer - description: 'sum of each logical Trial''s `max(attempt_count-1,0)`.' + description: sum of each logical Trial's `max(attempt_count-1,0)`. overall_mean: - type: number + type: + - number + - 'null' format: double - nullable: true - description: 'unweighted mean of available comparable scorer means, null when none exists.' + description: unweighted mean of available comparable scorer means, null when none exists. BenchmarkConfigurationMetrics: type: object - required: - - compute_credits - - platform_credits - - inference_credits - - total_credits - - cost_usd - - avg_total_credits_per_trial - - avg_total_credits_per_task - - avg_wall_time_s - - avg_cost_usd_per_trial - properties: + description: Configuration totals and averages. Run/execution averages use the platform definitions and scorer-branch exclusions of BenchmarkTrialMetrics. + required: + - avg_agent_runs + - avg_agent_executions + - compute_credits + - platform_credits + - inference_credits + - total_credits + - cost_usd + - avg_total_credits_per_trial + - avg_total_credits_per_task + - avg_wall_time_s + - avg_cost_usd_per_trial + properties: + avg_agent_runs: + type: + - number + - 'null' + format: double + description: Mean observed final retained live-tree run counts over succeeded trials with available run evidence, including active descendants. Superseded attempts and failed or cancelled trials are excluded. + avg_agent_executions: + type: + - number + - 'null' + format: double + description: Mean recorded final-tree starts and resumes over succeeded trials with available execution evidence, including trials with active descendants or queued resumes. Null when no measurements qualify; unknown starts are not zero. compute_credits: type: string description: retry-inclusive execution compute-credit total. @@ -13426,18 +13575,18 @@ components: description: retry-inclusive execution dollar total under existing mixed-cost arithmetic. avg_total_credits_per_trial: type: string - description: 'credits averaged over final successful attempts, with existing decimal rounding.' + description: credits averaged over final successful attempts, with existing decimal rounding. avg_total_credits_per_task: type: string - description: 'final-successful-attempt credits divided by distinct succeeded tasks, with existing rounding.' + description: final-successful-attempt credits divided by distinct succeeded tasks, with existing rounding. avg_wall_time_s: type: number format: double - description: 'final successful attempt working-duration average, not retry-chain duration average.' + description: final successful attempt working-duration average, not retry-chain duration average. avg_cost_usd_per_trial: type: number format: double - description: 'final successful attempt cost average, not retry-chain cost average.' + description: final successful attempt cost average, not retry-chain cost average. avg_output_tokens: type: number format: double @@ -13449,19 +13598,19 @@ components: BenchmarkScorerConfigurationAggregate: type: object required: - - scorer_uid - - configuration_uid - - scored - - pending - - failed - - unscored - - no_result - - outcomes - - labels - - mean - - expected_task_count - - scored_task_count - - comparable + - scorer_uid + - configuration_uid + - scored + - pending + - failed + - unscored + - no_result + - outcomes + - labels + - mean + - expected_task_count + - scored_task_count + - comparable properties: scorer_uid: type: string @@ -13482,8 +13631,9 @@ components: type: integer description: existing finished-unscored or unresolved/post-cutoff scored pair count. no_result: - type: string - nullable: true + type: + - string + - 'null' description: existing safe no-scored-trials explanation. outcomes: $ref: '#/components/schemas/BenchmarkOutcomeCounts' @@ -13492,27 +13642,28 @@ components: type: array items: $ref: '#/components/schemas/BenchmarkLabelCount' - description: 'complete retained classification-label distribution, including known unseen labels at zero.' + description: complete retained classification-label distribution, including known unseen labels at zero. mean: - type: number + type: + - number + - 'null' format: double - nullable: true description: unweighted counted task-cell mean for this scorer/configuration; null when no cell contributes. expected_task_count: type: integer - description: 'existing `applies_to_tasks` selected-dataset ledger task count across configurations, before comparison neutralization.' + description: existing `applies_to_tasks` selected-dataset ledger task count across configurations, before comparison neutralization. scored_task_count: type: integer - description: 'distinct selected tasks with a bound score here, capped at expected_task_count, as in the chart coverage warning.' + description: distinct selected tasks with a bound score here, capped at expected_task_count, as in the chart coverage warning. comparable: type: boolean description: true if some configuration has a scored succeeded Trial for this scorer in the selected dataset. BenchmarkOutcomeCounts: type: object required: - - pass - - fail - - pass_rate + - pass + - fail + - pass_rate properties: pass: type: integer @@ -13521,40 +13672,42 @@ components: type: integer description: retained bound scores whose current-threshold outcome is fail. pass_rate: - type: number + type: + - number + - 'null' format: double - nullable: true description: '`pass/(pass+fail)`, null when that denominator is zero; not a scoring-coverage rate.' BenchmarkLabelCount: type: object required: - - label - - count + - label + - count properties: label: type: string description: retained classification label value. count: type: integer - description: 'bound scores with this label in the aggregate, including real zero counts for known labels.' + description: bound scores with this label in the aggregate, including real zero counts for known labels. BenchmarkTaskScorerConfigurationAggregate: type: object required: - - task_uid - - task_title - - configuration_uid - - scorer_uid - - expected_repetition_count - - scored_repetition_count - - mean - - task_overall_mean + - task_uid + - task_title + - configuration_uid + - scorer_uid + - expected_repetition_count + - scored_repetition_count + - mean + - task_overall_mean properties: task_uid: type: string description: frozen/derived legacy task coordinate. task_title: - type: string - nullable: true + type: + - string + - 'null' description: retained frozen title for row display. configuration_uid: type: string @@ -13564,74 +13717,93 @@ components: description: resolved canonical scorer coordinate. expected_repetition_count: type: integer - description: 'logical Trial repetitions in this cell under existing comparison arithmetic, including execution failures.' + description: logical Trial repetitions in this cell under existing comparison arithmetic, including execution failures. scored_repetition_count: type: integer description: succeeded repetitions with permitted retained bound numeric scores. mean: - type: number + type: + - number + - 'null' format: double - nullable: true - description: 'average of those scored repetitions; null when none contributes, never fabricated zero.' + description: average of those scored repetitions; null when none contributes, never fabricated zero. task_overall_mean: - type: number + type: + - number + - 'null' format: double - nullable: true - description: 'mean of available comparable scorer means for this task/configuration, before scorer display projection.' + description: mean of available comparable scorer means for this task/configuration, before scorer display projection. BenchmarkAgentMetricAggregate: type: object + description: Per-configuration named-agent totals and averages. Run/execution averages use the platform definitions and scorer-branch exclusions of BenchmarkTrialMetrics. required: - - agent_uid - - agent_name - - cost_usd - - configuration_uid + - avg_agent_runs + - avg_agent_executions + - agent_uid + - agent_name + - cost_usd + - configuration_uid properties: + avg_agent_runs: + type: + - number + - 'null' + format: double + description: Mean observed final retained live-tree run counts attributed to this agent over succeeded trials with available run evidence, including active descendants. Confirmed absence contributes zero; superseded attempts and failed or cancelled trials are excluded. + avg_agent_executions: + type: + - number + - 'null' + format: double + description: Mean recorded final-tree starts and resumes attributed to this agent over succeeded trials with available execution evidence for this agent, including trials with active descendants or queued resumes. Confirmed absence contributes zero; unknown starts are not zero. Null when no measurements qualify. agent_uid: type: string description: existing named-agent identity; the empty string retains the Unknown-agent fallback. agent_name: type: string - description: 'existing resolved label, including `"Unknown agent"` when identity is unavailable.' + description: existing resolved label, including `"Unknown agent"` when identity is unavailable. cost_usd: - type: number + type: + - number + - 'null' format: double - description: existing exclusive named-agent cost summed across retained retries and non-system descendants. + description: Exclusive named-agent cost summed across retained retries and spawned agents, excluding scorer runs and their descendants; null when only count evidence is available. sandbox_time_s: type: number format: double - description: 'existing summed claim-to-completion seconds, omitted when any contributing duration is unknown; measured zero is present.' + description: existing summed claim-to-completion seconds, omitted when any contributing duration is unknown; measured zero is present. configuration_uid: type: string description: containing configuration for the existing summed named-agent breakdown. cost_breakdown: $ref: '#/components/schemas/BenchmarkAgentCostBreakdown' - description: 'Retained exclusive costs and public-model attribution, omitted when the existing loader gate or availability suppresses it.' + description: Retained exclusive costs and public-model attribution, omitted when the existing loader gate or availability suppresses it. BenchmarkExecutionState: type: string enum: - - QUEUED - - PENDING - - CLAIMED - - INPROGRESS - - SUCCEEDED - - FAILED - - ERROR - - BLOCKED - - CANCELLED + - QUEUED + - PENDING + - CLAIMED + - INPROGRESS + - SUCCEEDED + - FAILED + - ERROR + - BLOCKED + - CANCELLED BenchmarkTrialScoringState: type: string enum: - - awaiting_trial - - pending - - judging - - scored - - finished_unscored - - not_scoreable + - awaiting_trial + - pending + - judging + - scored + - finished_unscored + - not_scoreable BenchmarkViolation: type: object required: - - code - - message + - code + - message properties: code: type: string @@ -13641,18 +13813,18 @@ components: description: Human-readable explanation BenchmarkLaunchViolationError: allOf: - - $ref: '#/components/schemas/Error' - - type: object - properties: - violations: - type: array - items: - $ref: '#/components/schemas/BenchmarkViolation' + - $ref: '#/components/schemas/Error' + - type: object + properties: + violations: + type: array + items: + $ref: '#/components/schemas/BenchmarkViolation' ListBenchmarkSuitesResponse: type: object required: - - data - - page_info + - data + - page_info properties: data: type: array diff --git a/src/pages/api.astro b/src/pages/api.astro index 4738c273c..1c0905030 100644 --- a/src/pages/api.astro +++ b/src/pages/api.astro @@ -395,7 +395,7 @@ const specBaseUrl = (specObject.servers as Array<{ url?: string }> | undefined)? } })(); - +
Date: Thu, 15 Oct 2026 13:50:47 -0400 Subject: [PATCH 2/2] docs: leave OpenAPI spec updates to releases Restore the generated spec and derive download labels from the checked-in spec version.\n\nCo-Authored-By: Warp --- astro.config.mjs | 10 +- developers/agent-api-openapi.yaml | 8190 ++++++++++++++--------------- 2 files changed, 4017 insertions(+), 4183 deletions(-) diff --git a/astro.config.mjs b/astro.config.mjs index b7a68f29b..a272cbf62 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -1,4 +1,5 @@ // @ts-check +import { readFileSync } from 'node:fs'; import { defineConfig, envField } from 'astro/config'; import remarkGfm from 'remark-gfm'; import mermaid from 'astro-mermaid'; @@ -7,6 +8,7 @@ import sitemap from '@astrojs/sitemap'; import starlight from '@astrojs/starlight'; import starlightLlmsTxt from 'starlight-llms-txt'; import starlightSidebarTopics from 'starlight-sidebar-topics'; +import { parse } from 'yaml'; import pageTitleOverride from './src/plugins/page-title-override.ts'; import remarkHeadingVars from './src/plugins/heading-vars.ts'; import { varsTransformPlugin } from './src/plugins/vars-transform.ts'; @@ -15,6 +17,10 @@ import { sidebarTopics } from './src/sidebar.ts'; import docsMarkdownIntegration from './src/integrations/docs-markdown-integration.js'; import { DOCS_ORIGIN } from './src/lib/site.js'; +const openApiVersion = parse( + readFileSync(new URL('./developers/agent-api-openapi.yaml', import.meta.url), 'utf8'), +).openapi; + // https://astro.build/config export default defineConfig({ site: DOCS_ORIGIN, @@ -200,12 +206,12 @@ export default defineConfig({ { label: 'Oz Agent API (OpenAPI spec, YAML)', url: 'https://docs.warp.dev/openapi.yaml', - description: 'Machine-readable OpenAPI 3.2 specification for the Oz Agent API.', + description: `Machine-readable OpenAPI ${openApiVersion} specification for the Oz Agent API.`, }, { label: 'Oz Agent API (OpenAPI spec, JSON)', url: 'https://docs.warp.dev/openapi.json', - description: 'Machine-readable OpenAPI 3.2 specification (JSON format) for the Oz Agent API.', + description: `Machine-readable OpenAPI ${openApiVersion} specification (JSON format) for the Oz Agent API.`, }, ], // Excludes pages that cause a stack overflow in hast-util-to-text diff --git a/developers/agent-api-openapi.yaml b/developers/agent-api-openapi.yaml index 07bb4462c..97417a2fc 100644 --- a/developers/agent-api-openapi.yaml +++ b/developers/agent-api-openapi.yaml @@ -1,47 +1,32 @@ -openapi: 3.2.0 +openapi: 3.0.0 info: title: Warp Platform API version: 1.0.0 description: | API for creating, managing, and querying factory and cloud agent runs. - These endpoints allow users to send work to factories, start standalone agents, list runs, and retrieve detailed run information. + Send work to factories, start standalone agents, list runs, and retrieve + detailed run information. contact: name: Warp Support - url: https://docs.warp.dev + url: 'https://docs.warp.dev' email: support@warp.dev license: name: Proprietary servers: -- url: https://app.warp.dev/api/v1 - description: Warp Server + - url: 'https://app.warp.dev/api/v1' + description: Warp Server tags: -- name: agent - summary: Agents - description: Operations for running and managing cloud agents -- name: schedules - summary: Scheduled Agents - parent: agent - description: Operations for creating and managing scheduled agents -- name: factory - summary: Factories - description: Operations for creating and managing factories -- name: factory-metrics - summary: Metrics - parent: factory - description: Operations for querying factory cost and productivity metrics -- name: factory-scorers - summary: Scorers - parent: factory - description: Operations for creating and managing scorers -- name: factory-benchmarks - summary: Benchmarks - parent: factory - description: Operations for managing benchmark suites, tasks, runs, trials, and results -- name: networking - summary: Networking - parent: agent - description: Networking information for Warp-hosted agents + - name: agent + description: Operations for running and managing cloud agents + - name: schedules + description: Operations for creating and managing scheduled agents + - name: factory + description: Operations for creating and managing factories + - name: benchmark + description: 'Operations for managing benchmark suites, tasks, runs, trials, and results' + - name: networking + description: Networking information for Warp-hosted agents paths: /networking/egress-ranges: get: @@ -51,11 +36,11 @@ paths: Warp-hosted agents. operationId: getEgressRanges tags: - - networking + - networking security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/TeamUidHeaderParam' + - $ref: '#/components/parameters/TeamUidHeaderParam' responses: '200': description: Current Warp-hosted agent egress ranges @@ -86,41 +71,41 @@ paths: case-insensitive substring match on the factory name or alias. operationId: listFactories tags: - - factory + - factory security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/TeamUidHeaderParam' - - name: team_uid - in: query - description: | - Optional team UID to filter factories by ownership. Takes - precedence over the X-Warp-Team-Uid header. - 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 + - $ref: '#/components/parameters/TeamUidHeaderParam' + - name: team_uid + in: query + description: | + Optional team UID to filter factories by ownership. Takes + precedence over the X-Warp-Team-Uid header. + 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 @@ -142,22 +127,22 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - /factory/{uid}: + '/factory/{uid}': get: summary: Get a factory description: Get a factory by its UID. operationId: getFactory tags: - - factory + - factory security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: uid - in: path - description: The public UID of the factory. - required: true - schema: - type: string + - name: uid + in: path + description: The public UID of the factory. + required: true + schema: + type: string responses: '200': description: Factory details @@ -185,7 +170,199 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - /factory/{uid}/tasks: + /factory-inbox: + get: + summary: List Factory inbox notifications + description: | + List unresolved notifications across factories authorized for the + authenticated principal and active team. The default `mine` scope + preserves the personal Inbox and requires user credentials. The + `team` scope lists notifications assigned to any recipient and + can be used by user or agent credentials. Personal read state + (`is_read`) is included only in `mine` scope and omitted in `team` + scope, including when filtering by recipient. + operationId: listFactoryInbox + tags: + - factory + security: + - bearerAuth: [] + parameters: + - $ref: '#/components/parameters/TeamUidHeaderParam' + - name: scope + in: query + description: | + `mine` returns notifications assigned to the authenticated user + and is the default. `team` returns notifications across live + recipients in the authorized Factory and team scope. + required: false + schema: + $ref: '#/components/schemas/FactoryInboxScope' + - name: factory_uid + in: query + description: 'Exact Factory UID filter, intersected with authorized factories.' + required: false + schema: + type: string + - name: recipient_uid + in: query + description: | + Exact public user UID filter within the authorized Factory and + team scope. In `mine` scope this can only match the authenticated + user. + required: false + schema: + type: string + - name: limit + in: query + description: Maximum number of items to return. Defaults to 50. + required: false + schema: + type: integer + minimum: 1 + maximum: 100 + default: 50 + - name: cursor + in: query + description: Opaque cursor from page_info.next_cursor. + required: false + schema: + type: string + responses: + '200': + description: One page of inbox notifications. + content: + application/json: + schema: + $ref: '#/components/schemas/ListFactoryInboxResponse' + '400': + description: 'Invalid scope, limit, cursor, or principal for the requested scope' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Error' + '401': + description: Authentication required + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Error' + '403': + $ref: '#/components/responses/FactoryAccessDenied' + '404': + description: Factory task APIs are not available + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Error' + '500': + description: Internal server error + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Error' + /factory-inbox/notifications/read: + post: + summary: Mark inbox notifications as read + description: | + Mark a batch of notifications as read for the authenticated user after + checking access to each factory. The caller must be a recipient of + each existing notification, and the notification must remain active; + otherwise its outcome is unsuccessful. Missing notifications are + successful no-ops. Outcomes are returned in request order. + operationId: markFactoryInboxNotificationsRead + tags: + - factory + security: + - bearerAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/FactoryInboxMutationRequest' + responses: + '200': + description: Per-notification outcomes. + content: + application/json: + schema: + $ref: '#/components/schemas/FactoryInboxMutationResponse' + '400': + description: Invalid notification list + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Error' + '401': + description: Authentication required + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Error' + '403': + description: Caller is not a user + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Error' + '500': + description: Internal server error + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Error' + /factory-inbox/notifications/unread: + post: + summary: Mark inbox notifications as unread + description: | + Mark a batch of notifications as unread for the authenticated user + after checking access to each factory. The caller must be a recipient + of each existing notification, and the notification must remain active; + otherwise its outcome is unsuccessful. Missing notifications are + successful no-ops. Outcomes are returned in request order. + operationId: markFactoryInboxNotificationsUnread + tags: + - factory + security: + - bearerAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/FactoryInboxMutationRequest' + responses: + '200': + description: Per-notification outcomes. + content: + application/json: + schema: + $ref: '#/components/schemas/FactoryInboxMutationResponse' + '400': + description: Invalid notification list + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Error' + '401': + description: Authentication required + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Error' + '403': + description: Caller is not a user + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Error' + '500': + description: Internal server error + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Error' + '/factory/{uid}/tasks': post: summary: Create a factory task description: | @@ -196,16 +373,16 @@ paths: factories. operationId: createFactoryTask tags: - - factory + - factory security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: uid - in: path - description: The public UID of the factory. - required: true - schema: - type: string + - name: uid + in: path + description: The public UID of the factory. + required: true + schema: + type: string requestBody: required: true content: @@ -259,123 +436,123 @@ paths: canonical ticket metadata and derived outputs for the returned page. operationId: listFactoryTasks tags: - - factory + - factory security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: uid - in: path - description: The public UID of the factory. - required: true - schema: - type: string - - name: stage - in: query - description: | - Filter by task stage. Can be specified multiple times to match any - of the given stages. - required: false - schema: - type: array - items: - $ref: '#/components/schemas/FactoryTaskStage' - style: form - explode: true - - name: created_by - in: query - description: | - Filter to tasks whose seed run was started by any of these - teammates, each given as their email address. Can be specified - multiple times to match any of the given teammates. - required: false - schema: - type: array - items: + - name: uid + in: path + description: The public UID of the factory. + required: true + schema: type: string - style: form - explode: true - - name: q - in: query - description: Case-insensitive substring search over the task title. - required: false - schema: - type: string - - name: created_after - in: query - description: Filter to tasks created after this timestamp (RFC3339 format). - required: false - schema: - type: string - format: date-time - - name: created_before - in: query - description: Filter to tasks created before this timestamp (RFC3339 format). - required: false - schema: - type: string - format: date-time - - name: updated_after - in: query - description: Filter to tasks updated after this timestamp (RFC3339 format). - required: false - schema: - type: string - format: date-time - - name: sort_by - in: query - description: Sort field for results. - required: false - schema: - type: string - enum: - - created_at - - updated_at - default: created_at - - name: sort_order - in: query - description: Sort direction. - required: false - schema: - type: string - enum: - - asc - - desc - default: desc - - name: limit - in: query - description: Maximum number of tasks to return (default 50, max 100). - required: false - schema: - type: integer - minimum: 1 - maximum: 100 - - name: cursor - in: query - description: | - Opaque cursor returned by a previous list response. - Valid only for the sort_by/sort_order it was issued under; omit - to restart the listing. - required: false - schema: - type: string - - name: full_list - in: query - description: | - Include canonical ticket_source and ticket_id metadata from each - task's bound run, plus its derived outputs. Defaults to false. - required: false - schema: - type: boolean - default: false - - name: include_current_run - in: query - description: | - Include each task's current top-level run, resolved in one batch - for the returned page. Defaults to false. - required: false - schema: - type: boolean - default: false + - name: stage + in: query + description: | + Filter by task stage. Can be specified multiple times to match any + of the given stages. + required: false + schema: + type: array + items: + $ref: '#/components/schemas/FactoryTaskStage' + style: form + explode: true + - name: created_by + in: query + description: | + Filter to tasks whose seed run was started by any of these + teammates, each given as their email address. Can be specified + multiple times to match any of the given teammates. + required: false + schema: + type: array + items: + type: string + style: form + explode: true + - name: q + in: query + description: Case-insensitive substring search over the task title. + required: false + schema: + type: string + - name: created_after + in: query + description: Filter to tasks created after this timestamp (RFC3339 format). + required: false + schema: + type: string + format: date-time + - name: created_before + in: query + description: Filter to tasks created before this timestamp (RFC3339 format). + required: false + schema: + type: string + format: date-time + - name: updated_after + in: query + description: Filter to tasks updated after this timestamp (RFC3339 format). + required: false + schema: + type: string + format: date-time + - name: sort_by + in: query + description: Sort field for results. + required: false + schema: + type: string + enum: + - created_at + - updated_at + default: created_at + - name: sort_order + in: query + description: Sort direction. + required: false + schema: + type: string + enum: + - asc + - desc + default: desc + - name: limit + in: query + description: 'Maximum number of tasks to return (default 50, max 100).' + required: false + schema: + type: integer + minimum: 1 + maximum: 100 + - name: cursor + in: query + description: | + Opaque cursor returned by a previous list response. + Valid only for the sort_by/sort_order it was issued under; omit + to restart the listing. + required: false + schema: + type: string + - name: full_list + in: query + description: | + Include canonical ticket_source and ticket_id metadata from each + task's bound run, plus its derived outputs. Defaults to false. + required: false + schema: + type: boolean + default: false + - name: include_current_run + in: query + description: | + Include each task's current top-level run, resolved in one batch + for the returned page. Defaults to false. + required: false + schema: + type: boolean + default: false responses: '200': description: List of factory tasks @@ -384,7 +561,7 @@ paths: schema: $ref: '#/components/schemas/ListFactoryTasksResponse' '400': - description: Invalid filter, sort, limit, cursor, full_list, or include_current_run value + description: 'Invalid filter, sort, limit, cursor, full_list, or include_current_run value' content: application/problem+json: schema: @@ -409,7 +586,7 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - /factory/{uid}/runs: + '/factory/{uid}/runs': post: summary: Dispatch a run to a factory description: | @@ -419,16 +596,16 @@ paths: be resolved afterwards with GET /factory/{uid}/task-by-run. operationId: createFactoryRun tags: - - factory + - factory security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: uid - in: path - description: The public UID of the factory. - required: true - schema: - type: string + - name: uid + in: path + description: The public UID of the factory. + required: true + schema: + type: string requestBody: required: true content: @@ -474,144 +651,29 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - /factory/{uid}/branches/{branch_uid}: - get: - summary: Observe a tracked Factory Branch - description: | - Requires Factory view and matching parent Factory/team ownership. - Does not create tracking, request repair, or mutate projections. - Retired tracking remains DELETED until normal permadeletion. - Unverifiable source freshness is UNKNOWN. Requires factory_branches. - operationId: getFactoryBranch - tags: - - factory - security: - - bearerAuth: [] - parameters: - - name: uid - in: path - required: true - schema: - type: string - - name: branch_uid - in: path - required: true - schema: - type: string - responses: - '200': - $ref: '#/components/responses/FactoryBranchStatusResponse' - '401': - $ref: '#/components/responses/Unauthorized' - '404': - $ref: '#/components/responses/FactoryBranchNotFound' - '500': - $ref: '#/components/responses/FactoryBranchUnavailable' - delete: - summary: Stop tracking a Factory Branch - description: | - Requires Factory view plus source.apply. Retirement blocks future - execution boundaries without deleting the Git head, cancelling - already-loaded work, or deleting production resources. - Repeated authorized deletion, including after purge, returns 204. - Requires factory_branches. - operationId: deleteFactoryBranch - tags: - - factory - security: - - bearerAuth: [] - parameters: - - name: uid - in: path - required: true - schema: - type: string - - name: branch_uid - in: path - required: true - schema: - type: string - responses: - '204': - description: Tracking retired or already absent - '401': - $ref: '#/components/responses/Unauthorized' - '403': - $ref: '#/components/responses/FactoryAccessDenied' - '404': - $ref: '#/components/responses/FactoryBranchNotFound' - '409': - $ref: '#/components/responses/FactoryBranchConflict' - '500': - $ref: '#/components/responses/FactoryBranchUnavailable' - /factory/{uid}/branches/{branch_uid}/apply: - post: - summary: Apply a Factory Branch sync - description: | - Requires Factory view, source.apply, and complete projection - authorization. Synchronizes to the current registered head with - bounded freshness admission. Duplicate requests converge. - Does not accept a target SHA or repository, create tracking, revive - retired identity, or replace settings on existing runs. - Requires factory_branches. - operationId: applyFactoryBranch - tags: - - factory - security: - - bearerAuth: [] - parameters: - - name: uid - in: path - required: true - schema: - type: string - - name: branch_uid - in: path - required: true - schema: - type: string - responses: - '200': - $ref: '#/components/responses/FactoryBranchStatusResponse' - '400': - description: Invalid source content - content: - application/problem+json: - schema: - $ref: '#/components/schemas/Error' - '401': - $ref: '#/components/responses/Unauthorized' - '403': - $ref: '#/components/responses/FactoryAccessDenied' - '404': - $ref: '#/components/responses/FactoryBranchNotFound' - '409': - $ref: '#/components/responses/FactoryBranchConflict' - '500': - $ref: '#/components/responses/FactoryBranchUnavailable' - /factory/{uid}/tasks/{task_uid}: + '/factory/{uid}/tasks/{task_uid}': get: summary: Get a factory task description: | Get a task with its derived outputs, newest-first. operationId: getFactoryTask tags: - - factory + - factory security: - - bearerAuth: [] - parameters: - - name: uid - in: path - description: The public UID of the factory. - required: true - schema: - type: string - - name: task_uid - in: path - description: The public UID of the task. - required: true - schema: - type: string + - bearerAuth: [] + parameters: + - name: uid + in: path + description: The public UID of the factory. + required: true + schema: + type: string + - name: task_uid + in: path + description: The public UID of the task. + required: true + schema: + type: string responses: '200': description: Factory task details with derived outputs @@ -647,22 +709,22 @@ paths: transition is allowed, including moving backwards or to completion. operationId: updateFactoryTask tags: - - factory + - factory security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: uid - in: path - description: The public UID of the factory. - required: true - schema: - type: string - - name: task_uid - in: path - description: The public UID of the task. - required: true - schema: - type: string + - name: uid + in: path + description: The public UID of the factory. + required: true + schema: + type: string + - name: task_uid + in: path + description: The public UID of the task. + required: true + schema: + type: string requestBody: required: true content: @@ -710,22 +772,22 @@ paths: Deleting a task never deletes artifacts or the conversation. operationId: deleteFactoryTask tags: - - factory + - factory security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: uid - in: path - description: The public UID of the factory. - required: true - schema: - type: string - - name: task_uid - in: path - description: The public UID of the task. - required: true - schema: - type: string + - name: uid + in: path + description: The public UID of the factory. + required: true + schema: + type: string + - name: task_uid + in: path + description: The public UID of the task. + required: true + schema: + type: string responses: '204': description: Factory task deleted successfully @@ -749,7 +811,7 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - /factory/{uid}/tasks/{task_uid}/cancel: + '/factory/{uid}/tasks/{task_uid}/cancel': post: summary: Stop a factory task description: | @@ -758,22 +820,22 @@ paths: cancelled as well. operationId: cancelFactoryTask tags: - - factory + - factory security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: uid - in: path - description: The public UID of the factory. - required: true - schema: - type: string - - name: task_uid - in: path - description: The public UID of the task. - required: true - schema: - type: string + - name: uid + in: path + description: The public UID of the factory. + required: true + schema: + type: string + - name: task_uid + in: path + description: The public UID of the task. + required: true + schema: + type: string responses: '200': description: | @@ -831,7 +893,7 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - /factory/{uid}/task-by-conversation: + '/factory/{uid}/task-by-conversation': get: summary: Get a factory task by conversation description: | @@ -840,22 +902,22 @@ paths: owned by a different factory is 404. operationId: getFactoryTaskByConversation tags: - - factory + - factory security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: uid - in: path - description: The public UID of the factory. - required: true - schema: - type: string - - name: conversation_id - in: query - description: The agent conversation ID the task is bound to. - required: true - schema: - type: string + - name: uid + in: path + description: The public UID of the factory. + required: true + schema: + type: string + - name: conversation_id + in: query + description: The agent conversation ID the task is bound to. + required: true + schema: + type: string responses: '200': description: Factory task details with derived outputs @@ -878,7 +940,7 @@ paths: '403': $ref: '#/components/responses/FactoryAccessDenied' '404': - description: Factory not accessible, or no live task bound to the conversation under this factory + description: 'Factory not accessible, or no live task bound to the conversation under this factory' content: application/problem+json: schema: @@ -889,7 +951,7 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - /factory/{uid}/task-by-run: + '/factory/{uid}/task-by-run': get: summary: Get a factory task by run description: | @@ -898,22 +960,22 @@ paths: a different factory is 404. operationId: getFactoryTaskByRun tags: - - factory-metrics + - factory security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: uid - in: path - description: The public UID of the factory. - required: true - schema: - type: string - - name: run_id - in: query - description: Any run ID in the task's run tree. - required: true - schema: - type: string + - name: uid + in: path + description: The public UID of the factory. + required: true + schema: + type: string + - name: run_id + in: query + description: Any run ID in the task's run tree. + required: true + schema: + type: string responses: '200': description: Factory task details with derived outputs @@ -936,7 +998,7 @@ paths: '403': $ref: '#/components/responses/FactoryAccessDenied' '404': - description: Factory not accessible, the run does not resolve to a live task, or the task belongs to a different factory + description: 'Factory not accessible, the run does not resolve to a live task, or the task belongs to a different factory' content: application/problem+json: schema: @@ -947,7 +1009,7 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - /factory/{uid}/metrics: + '/factory/{uid}/metrics': get: summary: Get factory metrics description: | @@ -958,39 +1020,39 @@ paths: receive per-period series aligned to period_list. operationId: getFactoryMetrics tags: - - factory-metrics + - factory security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: uid - in: path - description: The public UID of the factory. - required: true - schema: - type: string - - name: start_date - in: query - description: Inclusive RFC3339 range start (UTC). Defaults to end_date minus 30 days. - required: false - schema: - type: string - format: date-time - - name: end_date - in: query - description: Exclusive RFC3339 range end (UTC). Defaults to now. - required: false - schema: - type: string - format: date-time - - name: group_by_period - in: query - description: | - Optional binning granularity; when omitted, the response - contains aggregates only. Binned requests are capped at 365 - periods. - required: false - schema: - $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' + - name: uid + in: path + description: The public UID of the factory. + required: true + schema: + type: string + - name: start_date + in: query + description: Inclusive RFC3339 range start (UTC). Defaults to end_date minus 30 days. + required: false + schema: + type: string + format: date-time + - name: end_date + in: query + description: Exclusive RFC3339 range end (UTC). Defaults to now. + required: false + schema: + type: string + format: date-time + - name: group_by_period + in: query + description: | + Optional binning granularity; when omitted, the response + contains aggregates only. Binned requests are capped at 365 + periods. + required: false + schema: + $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' responses: '200': description: Factory metrics for the requested range @@ -999,7 +1061,7 @@ paths: schema: $ref: '#/components/schemas/FactoryMetricsResponse' '400': - description: Invalid date range or group_by_period, or more than 365 periods requested + description: 'Invalid date range or group_by_period, or more than 365 periods requested' content: application/problem+json: schema: @@ -1026,7 +1088,7 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - /factory/{uid}/costs/per-pr: + '/factory/{uid}/costs/per-pr': get: summary: Get factory cost per PR description: | @@ -1036,39 +1098,39 @@ paths: additionally receive per-period series aligned to period_list. operationId: getFactoryCostPerPR tags: - - factory-metrics + - factory security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: uid - in: path - description: The public UID of the factory. - required: true - schema: - type: string - - name: start_date - in: query - description: Inclusive RFC3339 range start (UTC). Defaults to end_date minus 30 days. - required: false - schema: - type: string - format: date-time - - name: end_date - in: query - description: Exclusive RFC3339 range end (UTC). Defaults to now. - required: false - schema: - type: string - format: date-time - - name: group_by_period - in: query - description: | - Optional binning granularity; when omitted, the response - contains aggregates only. Binned requests are capped at 365 - periods. - required: false - schema: - $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' + - name: uid + in: path + description: The public UID of the factory. + required: true + schema: + type: string + - name: start_date + in: query + description: Inclusive RFC3339 range start (UTC). Defaults to end_date minus 30 days. + required: false + schema: + type: string + format: date-time + - name: end_date + in: query + description: Exclusive RFC3339 range end (UTC). Defaults to now. + required: false + schema: + type: string + format: date-time + - name: group_by_period + in: query + description: | + Optional binning granularity; when omitted, the response + contains aggregates only. Binned requests are capped at 365 + periods. + required: false + schema: + $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' responses: '200': description: Cost per PR for the requested range @@ -1077,7 +1139,7 @@ paths: schema: $ref: '#/components/schemas/FactoryCostPerPRResponse' '400': - description: Invalid date range or group_by_period, or more than 365 periods requested + description: 'Invalid date range or group_by_period, or more than 365 periods requested' content: application/problem+json: schema: @@ -1104,7 +1166,7 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - /factory/{uid}/costs/breakdown: + '/factory/{uid}/costs/breakdown': get: summary: Get factory spend grouped by a dimension description: | @@ -1114,45 +1176,45 @@ paths: additionally receive per-period series aligned to period_list. operationId: getFactoryCostBreakdown tags: - - factory-metrics + - factory security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: uid - in: path - description: The public UID of the factory. - required: true - schema: - type: string - - name: group_by - in: query - description: The dimension to group spend by. - required: true - schema: - $ref: '#/components/schemas/FactoryCostBreakdownGroupBy' - - name: start_date - in: query - description: Inclusive RFC3339 range start (UTC). Defaults to end_date minus 30 days. - required: false - schema: - type: string - format: date-time - - name: end_date - in: query - description: Exclusive RFC3339 range end (UTC). Defaults to now. - required: false - schema: - type: string - format: date-time - - name: group_by_period - in: query - description: | - Optional binning granularity; when omitted, the response - contains aggregates only. Binned requests are capped at 365 - periods. - required: false - schema: - $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' + - name: uid + in: path + description: The public UID of the factory. + required: true + schema: + type: string + - name: group_by + in: query + description: The dimension to group spend by. + required: true + schema: + $ref: '#/components/schemas/FactoryCostBreakdownGroupBy' + - name: start_date + in: query + description: Inclusive RFC3339 range start (UTC). Defaults to end_date minus 30 days. + required: false + schema: + type: string + format: date-time + - name: end_date + in: query + description: Exclusive RFC3339 range end (UTC). Defaults to now. + required: false + schema: + type: string + format: date-time + - name: group_by_period + in: query + description: | + Optional binning granularity; when omitted, the response + contains aggregates only. Binned requests are capped at 365 + periods. + required: false + schema: + $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' responses: '200': description: Grouped spend for the requested range @@ -1161,7 +1223,7 @@ paths: schema: $ref: '#/components/schemas/FactoryCostBreakdownResponse' '400': - description: Missing or invalid group_by, invalid date range or group_by_period, or more than 365 periods requested + description: 'Missing or invalid group_by, invalid date range or group_by_period, or more than 365 periods requested' content: application/problem+json: schema: @@ -1186,7 +1248,7 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - /factory/{uid}/costs/per-pr/top: + '/factory/{uid}/costs/per-pr/top': get: summary: Get the factory's most expensive PRs description: | @@ -1197,38 +1259,38 @@ paths: detail fields. operationId: getFactoryTopPRs tags: - - factory-metrics + - factory security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: uid - in: path - description: The public UID of the factory. - required: true - schema: - type: string - - name: start_date - in: query - description: Inclusive RFC3339 range start (UTC). Defaults to end_date minus 30 days. - required: false - schema: - type: string - format: date-time - - name: end_date - in: query - description: Exclusive RFC3339 range end (UTC). Defaults to now. - required: false - schema: - type: string - format: date-time - - name: limit - in: query - description: Maximum PRs to return. Defaults to 20; at most 50. - required: false - schema: - type: integer - minimum: 1 - maximum: 50 + - name: uid + in: path + description: The public UID of the factory. + required: true + schema: + type: string + - name: start_date + in: query + description: Inclusive RFC3339 range start (UTC). Defaults to end_date minus 30 days. + required: false + schema: + type: string + format: date-time + - name: end_date + in: query + description: Exclusive RFC3339 range end (UTC). Defaults to now. + required: false + schema: + type: string + format: date-time + - name: limit + in: query + description: Maximum PRs to return. Defaults to 20; at most 50. + required: false + schema: + type: integer + minimum: 1 + maximum: 50 responses: '200': description: The factory's most expensive PRs for the requested range @@ -1264,7 +1326,7 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - /factory/{uid}/pull-requests: + '/factory/{uid}/pull-requests': get: summary: List the factory's pull requests description: | @@ -1277,87 +1339,87 @@ paths: cursor to continue. Pass updated_after to sync incrementally. operationId: listFactoryPullRequests tags: - - factory + - factory security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: uid - in: path - description: The public UID of the factory. - required: true - schema: - type: string - - name: limit - in: query - description: Records per page. Defaults to 50; at most 500. - required: false - schema: - type: integer - minimum: 1 - maximum: 500 - - name: cursor - in: query - description: Opaque cursor from a previous page's page_info.next_cursor. - required: false - schema: - type: string - - name: repo - in: query - description: Only PRs in this repository, as owner/repo (case-insensitive). - required: false - schema: - type: string - - name: state - in: query - description: | - Only PRs in these states. Can be specified multiple times to match any of the given states. - required: false - style: form - explode: true - schema: - type: array - items: - $ref: '#/components/schemas/FactoryPullRequestState' - - name: opened_after - in: query - description: Only PRs opened after this RFC3339 time (exclusive). - required: false - schema: - type: string - format: date-time - - name: opened_before - in: query - description: Only PRs opened before this RFC3339 time (exclusive). - required: false - schema: - type: string - format: date-time - - name: merged_after - in: query - description: Only PRs merged after this RFC3339 time (exclusive). - required: false - schema: - type: string - format: date-time - - name: merged_before - in: query - description: Only PRs merged before this RFC3339 time (exclusive). - required: false - schema: - type: string - format: date-time - - name: updated_after - in: query - description: | - Only PRs whose updated_at is after this RFC3339 time - (exclusive). updated_at tracks the PR on the code host; fields - derived from the factory's runs (runs, kickoff_at, - human_interactions.follow_up_message, and the kickoff-based - cycle_time stages) can change without moving it. - required: false - schema: - type: string - format: date-time + - name: uid + in: path + description: The public UID of the factory. + required: true + schema: + type: string + - name: limit + in: query + description: Records per page. Defaults to 50; at most 500. + required: false + schema: + type: integer + minimum: 1 + maximum: 500 + - name: cursor + in: query + description: Opaque cursor from a previous page's page_info.next_cursor. + required: false + schema: + type: string + - name: repo + in: query + description: 'Only PRs in this repository, as owner/repo (case-insensitive).' + required: false + schema: + type: string + - name: state + in: query + description: | + Only PRs in these states. Can be specified multiple times to match any of the given states. + required: false + style: form + explode: true + schema: + type: array + items: + $ref: '#/components/schemas/FactoryPullRequestState' + - name: opened_after + in: query + description: Only PRs opened after this RFC3339 time (exclusive). + required: false + schema: + type: string + format: date-time + - name: opened_before + in: query + description: Only PRs opened before this RFC3339 time (exclusive). + required: false + schema: + type: string + format: date-time + - name: merged_after + in: query + description: Only PRs merged after this RFC3339 time (exclusive). + required: false + schema: + type: string + format: date-time + - name: merged_before + in: query + description: Only PRs merged before this RFC3339 time (exclusive). + required: false + schema: + type: string + format: date-time + - name: updated_after + in: query + description: | + Only PRs whose updated_at is after this RFC3339 time + (exclusive). updated_at tracks the PR on the code host; fields + derived from the factory's runs (runs, kickoff_at, + human_interactions.follow_up_message, and the kickoff-based + cycle_time stages) can change without moving it. + required: false + schema: + type: string + format: date-time responses: '200': description: One page of the factory's pull requests @@ -1366,7 +1428,7 @@ paths: schema: $ref: '#/components/schemas/FactoryPullRequestsResponse' '400': - description: Invalid limit, cursor, state, or timestamp filter, or a time window whose *_after bound is not before its *_before bound + description: 'Invalid limit, cursor, state, or timestamp filter, or a time window whose *_after bound is not before its *_before bound' content: application/problem+json: schema: @@ -1393,7 +1455,7 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - /factory/{uid}/metrics/run-breakdown: + '/factory/{uid}/metrics/run-breakdown': get: summary: Get the factory's run counts grouped by a dimension description: | @@ -1402,45 +1464,45 @@ paths: series aligned to period_list. operationId: getFactoryRunBreakdown tags: - - factory-metrics + - factory security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: uid - in: path - description: The public UID of the factory. - required: true - schema: - type: string - - name: group_by - in: query - description: The dimension to group run counts by. - required: true - schema: - $ref: '#/components/schemas/FactoryRunBreakdownGroupBy' - - name: start_date - in: query - description: Inclusive RFC3339 range start (UTC). Defaults to end_date minus 30 days. - required: false - schema: - type: string - format: date-time - - name: end_date - in: query - description: Exclusive RFC3339 range end (UTC). Defaults to now. - required: false - schema: - type: string - format: date-time - - name: group_by_period - in: query - description: | - Optional binning granularity; when omitted, the response - contains aggregates only. Binned requests are capped at 365 - periods. - required: false - schema: - $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' + - name: uid + in: path + description: The public UID of the factory. + required: true + schema: + type: string + - name: group_by + in: query + description: The dimension to group run counts by. + required: true + schema: + $ref: '#/components/schemas/FactoryRunBreakdownGroupBy' + - name: start_date + in: query + description: Inclusive RFC3339 range start (UTC). Defaults to end_date minus 30 days. + required: false + schema: + type: string + format: date-time + - name: end_date + in: query + description: Exclusive RFC3339 range end (UTC). Defaults to now. + required: false + schema: + type: string + format: date-time + - name: group_by_period + in: query + description: | + Optional binning granularity; when omitted, the response + contains aggregates only. Binned requests are capped at 365 + periods. + required: false + schema: + $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' responses: '200': description: Grouped run counts for the requested range @@ -1449,7 +1511,7 @@ paths: schema: $ref: '#/components/schemas/FactoryRunBreakdownResponse' '400': - description: Missing or invalid group_by, invalid date range or group_by_period, or more than 365 periods requested + description: 'Missing or invalid group_by, invalid date range or group_by_period, or more than 365 periods requested' content: application/problem+json: schema: @@ -1474,49 +1536,49 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - /factory/{uid}/costs/per-pr/by-size: + '/factory/{uid}/costs/per-pr/by-size': get: summary: Get the factory's PR cost distribution grouped by PR size description: | - The mean per-PR attributed cost of the factory's PRs first seen in - a UTC date range, grouped by PR size. Pass group_by_period to - additionally receive per-period mean series aligned to - period_list. - operationId: getFactoryCostByPRSize - tags: - - factory-metrics - security: - - bearerAuth: [] - parameters: - - name: uid - in: path - description: The public UID of the factory. - required: true - schema: - type: string - - name: start_date - in: query - description: Inclusive RFC3339 range start (UTC). Defaults to end_date minus 30 days. - required: false - schema: - type: string - format: date-time - - name: end_date - in: query - description: Exclusive RFC3339 range end (UTC). Defaults to now. - required: false - schema: - type: string - format: date-time - - name: group_by_period - in: query - description: | - Optional binning granularity; when omitted, the response - contains aggregates only. Binned requests are capped at 365 - periods. - required: false - schema: - $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' + The mean per-PR attributed cost of the factory's PRs first seen in + a UTC date range, grouped by PR size. Pass group_by_period to + additionally receive per-period mean series aligned to + period_list. + operationId: getFactoryCostByPRSize + tags: + - factory + security: + - bearerAuth: [] + parameters: + - name: uid + in: path + description: The public UID of the factory. + required: true + schema: + type: string + - name: start_date + in: query + description: Inclusive RFC3339 range start (UTC). Defaults to end_date minus 30 days. + required: false + schema: + type: string + format: date-time + - name: end_date + in: query + description: Exclusive RFC3339 range end (UTC). Defaults to now. + required: false + schema: + type: string + format: date-time + - name: group_by_period + in: query + description: | + Optional binning granularity; when omitted, the response + contains aggregates only. Binned requests are capped at 365 + periods. + required: false + schema: + $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' responses: '200': description: Cost-by-size distribution for the requested range @@ -1525,7 +1587,7 @@ paths: schema: $ref: '#/components/schemas/FactoryCostByPRSizeResponse' '400': - description: Invalid date range or group_by_period, or more than 365 periods requested + description: 'Invalid date range or group_by_period, or more than 365 periods requested' content: application/problem+json: schema: @@ -1559,50 +1621,50 @@ paths: operationId: listAgents deprecated: true tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/TeamUidHeaderParam' - - name: repo - in: query - description: | - Optional repository specification to list agents from (format: "owner/repo"). - If not provided, lists agents from all accessible environments. - required: false - schema: - type: string - - name: refresh - in: query - description: | - When true, clears the agent list cache before fetching. - Use this to force a refresh of the available agents. - required: false - schema: - type: boolean - default: false - - name: sort_by - in: query - description: | - Sort order for the returned agents. - - "name": Sort alphabetically by name (default) - - "last_run": Sort by most recently used - required: false - schema: - type: string - enum: - - name - - last_run - - name: include_malformed_skills - in: query - description: | - When true, includes skills whose SKILL.md file exists but is - malformed. These variants will have a non-empty `error` field - describing the parse failure. Defaults to false. - required: false - schema: - type: boolean - default: false + - $ref: '#/components/parameters/TeamUidHeaderParam' + - name: repo + in: query + description: | + Optional repository specification to list agents from (format: "owner/repo"). + If not provided, lists agents from all accessible environments. + required: false + schema: + type: string + - name: refresh + in: query + description: | + When true, clears the agent list cache before fetching. + Use this to force a refresh of the available agents. + required: false + schema: + type: boolean + default: false + - name: sort_by + in: query + description: | + Sort order for the returned agents. + - "name": Sort alphabetically by name (default) + - "last_run": Sort by most recently used + required: false + schema: + type: string + enum: + - name + - last_run + - name: include_malformed_skills + in: query + description: | + When true, includes skills whose SKILL.md file exists but is + malformed. These variants will have a non-empty `error` field + describing the parse failure. Defaults to false. + required: false + schema: + type: boolean + default: false responses: '200': description: List of available agents @@ -1624,11 +1686,11 @@ paths: Worker presence is derived from worker websocket heartbeats and may be briefly stale. operationId: listConnectedSelfHostedWorkers tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/TeamUidHeaderParam' + - $ref: '#/components/parameters/TeamUidHeaderParam' responses: '200': description: List of currently connected self-hosted workers @@ -1648,7 +1710,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /agent/runs/{runId}/transcript: + '/agent/runs/{runId}/transcript': get: summary: Get run transcript description: | @@ -1656,16 +1718,16 @@ paths: Returns a 302 redirect to a time-limited download URL for the transcript. operationId: getRunTranscript tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: runId - in: path - description: The unique identifier of the run - required: true - schema: - type: string + - name: runId + in: path + description: The unique identifier of the run + required: true + schema: + type: string responses: '302': description: Redirect to a download URL for the transcript @@ -1705,7 +1767,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /agent/runs/{runId}/harness-usage: + '/agent/runs/{runId}/harness-usage': get: summary: Get raw third-party harness usage description: | @@ -1715,15 +1777,15 @@ paths: authorization as transcript reads. operationId: getRunHarnessUsage tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: runId - in: path - required: true - schema: - type: string + - name: runId + in: path + required: true + schema: + type: string responses: '200': description: Raw harness usage or an unavailable result @@ -1764,11 +1826,11 @@ paths: operationId: runAgent deprecated: true tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/TeamUidHeaderParam' + - $ref: '#/components/parameters/TeamUidHeaderParam' requestBody: required: true content: @@ -1797,7 +1859,7 @@ paths: schema: $ref: '#/components/schemas/RunAgentResponse' '400': - description: Invalid request (missing prompt, invalid config) + description: 'Invalid request (missing prompt, invalid config)' content: application/json: schema: @@ -1809,7 +1871,7 @@ paths: schema: $ref: '#/components/schemas/Error' '403': - description: No permission to access referenced resources (environment, MCP servers) + description: 'No permission to access referenced resources (environment, MCP servers)' content: application/json: schema: @@ -1822,11 +1884,11 @@ paths: The agent will be queued for execution and assigned a unique run ID. operationId: createRun tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/TeamUidHeaderParam' + - $ref: '#/components/parameters/TeamUidHeaderParam' requestBody: required: true content: @@ -1841,7 +1903,7 @@ paths: schema: $ref: '#/components/schemas/RunAgentResponse' '400': - description: Invalid request (missing prompt, invalid config) + description: 'Invalid request (missing prompt, invalid config)' content: application/json: schema: @@ -1853,7 +1915,7 @@ paths: schema: $ref: '#/components/schemas/Error' '403': - description: No permission to access referenced resources (environment, MCP servers) + description: 'No permission to access referenced resources (environment, MCP servers)' content: application/json: schema: @@ -1865,234 +1927,234 @@ paths: Results default to `sort_by=updated_at` and `sort_order=desc`. operationId: listRuns tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/TeamUidHeaderParam' - - name: limit - in: query - description: Maximum number of runs to return - required: false - schema: - type: integer - minimum: 1 - maximum: 500 - default: 20 - - name: cursor - in: query - description: Pagination cursor from previous response - required: false - schema: - type: string - - name: sort_by - in: query - description: | - Sort field for results. - - `updated_at`: Sort by last update timestamp (default) - - `created_at`: Sort by creation timestamp - - `title`: Sort alphabetically by run title - - `agent`: Sort alphabetically by skill. Runs without a skill are grouped last. - required: false - schema: - type: string - enum: - - updated_at - - created_at - - title - - agent - default: updated_at - - name: sort_order - in: query - description: Sort direction - required: false - schema: - type: string - enum: - - asc - - desc - default: desc - - name: state - in: query - description: | - Filter by run state. Can be specified multiple times to match any of the given states. - required: false - schema: - type: array - items: - $ref: '#/components/schemas/RunState' - style: form - explode: true - - name: task_status - in: query - description: | - Filter by high-level task status. Can be specified multiple times to match any value. - `running` matches when the root or any descendant is queued, pending, claimed, or in progress. - `failed`, `blocked`, `cancelled`, and `complete` match the root state only. - required: false - schema: - type: array - items: + - $ref: '#/components/parameters/TeamUidHeaderParam' + - name: limit + in: query + description: Maximum number of runs to return + required: false + schema: + type: integer + minimum: 1 + maximum: 500 + default: 20 + - name: cursor + in: query + description: Pagination cursor from previous response + required: false + schema: + type: string + - name: sort_by + in: query + description: | + Sort field for results. + - `updated_at`: Sort by last update timestamp (default) + - `created_at`: Sort by creation timestamp + - `title`: Sort alphabetically by run title + - `agent`: Sort alphabetically by skill. Runs without a skill are grouped last. + required: false + schema: type: string enum: - - running - - failed - - blocked - - cancelled - - complete - style: form - explode: true - - name: name - in: query - description: Filter by agent config name - required: false - schema: - type: string - - name: model_id - in: query - description: Filter by model ID - required: false - schema: - type: string - - name: creator - in: query - description: Filter by creator UID (user or service account) - required: false - schema: - type: string - - name: executor - in: query - description: | - Filter by the user or agent that executed the run. This will often be the - same as the creator, but not always: users may delegate tasks to agents. - required: false - schema: - type: string - - name: source - in: query - description: | - Filter by run source type. Can be specified multiple times to match any of the given sources. - required: false - schema: - type: array - items: - $ref: '#/components/schemas/RunSourceType' - style: form - explode: true - - name: execution_location - in: query - description: Filter by where the run executed - required: false - schema: - $ref: '#/components/schemas/RunExecutionLocation' - - name: created_after - in: query - description: Filter runs created after this timestamp (RFC3339 format) - required: false - schema: - type: string - format: date-time - - name: created_before - in: query - description: Filter runs created before this timestamp (RFC3339 format) - required: false - schema: - type: string - format: date-time - - name: updated_after - in: query - description: Filter runs updated after this timestamp (RFC3339 format) - required: false - schema: - type: string - format: date-time - - name: environment_id - in: query - description: | - Filter runs by environment ID. Passing the literal value - `empty-environment` matches runs with no environment configured, - rather than omitting the parameter, which applies no environment - filter at all. `empty-environment` can never collide with a real - environment ID: every environment ID is exactly 22 characters - drawn from `[A-Za-z0-9]`, while this sentinel contains a hyphen - and is a different length. - required: false - schema: - type: string - - name: skill - in: query - description: | - Filter runs by skill spec (e.g., "owner/repo:path/to/SKILL.md"). - Alias for skill_spec. - required: false - schema: - type: string - - name: skill_spec - in: query - description: Filter runs by skill spec (e.g., "owner/repo:path/to/SKILL.md") - required: false - schema: - type: string - - name: schedule_id - in: query - description: Filter runs by the scheduled agent ID that created them - required: false - schema: - type: string - - name: factory_uid - in: query - description: | - Filter runs by one or more factories. Repeating this parameter - matches runs executed by an agent from any selected factory. A UID - outside the caller's accessible factories matches nothing. - required: false - schema: - oneOf: - - type: string - - type: array + - updated_at + - created_at + - title + - agent + default: updated_at + - name: sort_order + in: query + description: Sort direction + required: false + schema: + type: string + enum: + - asc + - desc + default: desc + - name: state + in: query + description: | + Filter by run state. Can be specified multiple times to match any of the given states. + required: false + schema: + type: array + items: + $ref: '#/components/schemas/RunState' + style: form + explode: true + - name: task_status + in: query + description: | + Filter by high-level task status. Can be specified multiple times to match any value. + `running` matches when the root or any descendant is queued, pending, claimed, or in progress. + `failed`, `blocked`, `cancelled`, and `complete` match the root state only. + required: false + schema: + type: array items: type: string - style: form - explode: true - - name: ancestor_run_id - in: query - description: Filter runs by ancestor run ID. The referenced run must exist and be accessible to the caller. - required: false - schema: - type: string - - name: metadata - in: query - description: | - Filter by exact metadata key/value pairs using object notation - (e.g. `metadata[ticket_id]=ACME-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 - maxProperties: 5 - additionalProperties: + enum: + - running + - failed + - blocked + - cancelled + - complete + style: form + explode: true + - name: name + in: query + description: Filter by agent config name + required: false + schema: + type: string + - name: model_id + in: query + description: Filter by model ID + required: false + schema: + type: string + - name: creator + in: query + description: Filter by creator UID (user or service account) + required: false + schema: + type: string + - name: executor + in: query + description: | + Filter by the user or agent that executed the run. This will often be the + same as the creator, but not always: users may delegate tasks to agents. + required: false + schema: + type: string + - name: source + in: query + description: | + Filter by run source type. Can be specified multiple times to match any of the given sources. + required: false + schema: + type: array + items: + $ref: '#/components/schemas/RunSourceType' + style: form + explode: true + - name: execution_location + in: query + description: Filter by where the run executed + required: false + schema: + $ref: '#/components/schemas/RunExecutionLocation' + - name: created_after + in: query + description: Filter runs created after this timestamp (RFC3339 format) + required: false + schema: + type: string + format: date-time + - name: created_before + in: query + description: Filter runs created before this timestamp (RFC3339 format) + required: false + schema: + type: string + format: date-time + - name: updated_after + in: query + description: Filter runs updated after this timestamp (RFC3339 format) + required: false + schema: + type: string + format: date-time + - name: environment_id + in: query + description: | + Filter runs by environment ID. Passing the literal value + `empty-environment` matches runs with no environment configured, + rather than omitting the parameter, which applies no environment + filter at all. `empty-environment` can never collide with a real + environment ID: every environment ID is exactly 22 characters + drawn from `[A-Za-z0-9]`, while this sentinel contains a hyphen + and is a different length. + required: false + schema: + type: string + - name: skill + in: query + description: | + Filter runs by skill spec (e.g., "owner/repo:path/to/SKILL.md"). + Alias for skill_spec. + required: false + schema: + type: string + - name: skill_spec + in: query + description: 'Filter runs by skill spec (e.g., "owner/repo:path/to/SKILL.md")' + required: false + schema: + type: string + - name: schedule_id + in: query + description: Filter runs by the scheduled agent ID that created them + required: false + schema: + type: string + - name: factory_uid + in: query + description: | + Filter runs by one or more factories. Repeating this parameter + matches runs executed by an agent from any selected factory. A UID + outside the caller's accessible factories matches nothing. + required: false + schema: + oneOf: + - type: string + - type: array + items: + type: string + style: form + explode: true + - name: ancestor_run_id + in: query + description: Filter runs by ancestor run ID. The referenced run must exist and be accessible to the caller. + required: false + schema: + type: string + - name: metadata + in: query + description: | + Filter by exact metadata key/value pairs using object notation + (e.g. `metadata[ticket_id]=ACME-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 + maxProperties: 5 + additionalProperties: + type: string + style: deepObject + explode: true + - name: artifact_type + in: query + description: Filter runs by artifact type + required: false + schema: + type: string + enum: + - PLAN + - PULL_REQUEST + - SCREENSHOT + - FILE + - EXTERNAL_REFERENCE + - name: q + in: query + description: 'Search by full run ID or run URL, or fuzzy match across run title, prompt, and skill_spec' + required: false + schema: type: string - style: deepObject - explode: true - - name: artifact_type - in: query - description: Filter runs by artifact type - required: false - schema: - type: string - enum: - - PLAN - - PULL_REQUEST - - SCREENSHOT - - FILE - - EXTERNAL_REFERENCE - - name: q - in: query - description: Search by full run ID or run URL, or fuzzy match across run title, prompt, and skill_spec - required: false - schema: - type: string responses: '200': description: List of runs @@ -2128,17 +2190,17 @@ paths: exists or when the caller lacks access. operationId: getRunByExternalReferenceURL tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: url - in: query - required: true - description: The canonical URL of the external reference artifact to look up. - schema: - type: string - maxLength: 2048 + - name: url + in: query + required: true + description: The canonical URL of the external reference artifact to look up. + schema: + type: string + maxLength: 2048 responses: '200': description: Run found @@ -2159,7 +2221,7 @@ paths: schema: $ref: '#/components/schemas/Error' '404': - description: No run found with the given external reference URL, or caller lacks access + description: 'No run found with the given external reference URL, or caller lacks access' content: application/json: schema: @@ -2170,7 +2232,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /agent/runs/{runId}: + '/agent/runs/{runId}': get: summary: Get run details description: | @@ -2178,16 +2240,16 @@ paths: including the full prompt, session link, and resolved configuration. operationId: getRun tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: runId - in: path - description: The unique identifier of the run - required: true - schema: - type: string + - name: runId + in: path + description: The unique identifier of the run + required: true + schema: + type: string responses: '200': description: Run details @@ -2219,23 +2281,23 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /agent/runs/{runId}/timeline: + '/agent/runs/{runId}/timeline': get: summary: Get run timeline description: | Retrieve chronological setup and lifecycle timeline events for an agent run. operationId: getRunTimeline tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: runId - in: path - description: The unique identifier of the run - required: true - schema: - type: string + - name: runId + in: path + description: The unique identifier of the run + required: true + schema: + type: string responses: '200': description: Run timeline events @@ -2267,7 +2329,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /agent/runs/{runId}/conversation: + '/agent/runs/{runId}/conversation': get: summary: Get normalized run conversation description: | @@ -2276,16 +2338,16 @@ paths: into structured blocks. operationId: getRunConversation tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: runId - in: path - description: The unique identifier of the run - required: true - schema: - type: string + - name: runId + in: path + description: The unique identifier of the run + required: true + schema: + type: string responses: '200': description: Normalized conversation @@ -2312,7 +2374,7 @@ paths: schema: $ref: '#/components/schemas/Error' '404': - description: Run not found, or the run has no conversation + description: 'Run not found, or the run has no conversation' content: application/json: schema: @@ -2325,7 +2387,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /agent/runs/{runId}/cancel: + '/agent/runs/{runId}/cancel': post: summary: Cancel a run description: | @@ -2336,16 +2398,16 @@ paths: instead — see the error responses below for each case. operationId: cancelRun tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: runId - in: path - description: The unique identifier of the run to cancel - required: true - schema: - type: string + - name: runId + in: path + description: The unique identifier of the run to cancel + required: true + schema: + type: string responses: '200': description: Run cancelled successfully @@ -2395,7 +2457,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /agent/runs/{runId}/followups: + '/agent/runs/{runId}/followups': post: summary: Submit a follow-up message for a run description: | @@ -2414,16 +2476,16 @@ paths: unchanged. operationId: submitRunFollowup tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: runId - in: path - description: The unique identifier of the run - required: true - schema: - type: string + - name: runId + in: path + description: The unique identifier of the run + required: true + schema: + type: string requestBody: required: true content: @@ -2480,35 +2542,105 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /agent/runs/{runId}/interrupt: + '/agent/runs/{runId}/interrupt': post: summary: Interrupt the turn currently running on a run description: | - Cancel the request the agent is currently working on without ending - the run or tearing down its sandbox. The run stays in progress and - accepts follow-ups afterwards. Only live runs on the Warp harness - can be interrupted; use `POST /agent/runs/{runId}/cancel` to end a - run outright. A 202 means the platform accepted the cancel; the agent - applies it asynchronously. - operationId: interruptRun + Cancel the request the agent is currently working on without ending + the run or tearing down its sandbox. The run stays in progress and + accepts follow-ups afterwards. Only live runs on the Warp harness + can be interrupted; use `POST /agent/runs/{runId}/cancel` to end a + run outright. A 202 means the platform accepted the cancel; the agent + applies it asynchronously. + operationId: interruptRun + tags: + - agent + security: + - bearerAuth: [] + parameters: + - name: runId + in: path + description: The unique identifier of the run + required: true + schema: + type: string + responses: + '202': + description: Interrupt accepted + content: + application/json: + schema: + type: object + '400': + description: Missing run ID + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '401': + description: Authentication required + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '403': + description: No permission to steer this run + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: Run not found + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '409': + description: | + The run cannot be interrupted right now. `reason` is one of + `no_live_session` (no reachable session, or the session has not + registered a conversation yet), `session_ended`, or + `unsupported_harness` (a non-Oz harness has no turn-level cancel). + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '500': + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '/agent/runs/{runId}/handoff/attachments': + get: + summary: List handoff snapshot attachments for a run + description: | + Return fresh presigned download URLs for handoff snapshot files uploaded + by the latest ended execution of this run. An empty list is returned + when no ended execution exists or no snapshot files were uploaded. + + This endpoint is useful for third-party harnesses that want to download + the snapshot files produced by a previous execution before starting a + handoff execution themselves. + operationId: listHandoffSnapshotAttachments tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: runId - in: path - description: The unique identifier of the run - required: true - schema: - type: string + - name: runId + in: path + description: The unique identifier of the run + required: true + schema: + type: string responses: - '202': - description: Interrupt accepted + '200': + description: Handoff snapshot attachments (possibly empty) content: application/json: schema: - type: object + $ref: '#/components/schemas/ListHandoffSnapshotAttachmentsResponse' '400': description: Missing run ID content: @@ -2522,23 +2654,7 @@ paths: schema: $ref: '#/components/schemas/Error' '403': - description: No permission to steer this run - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - '404': - description: Run not found - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - '409': - description: | - The run cannot be interrupted right now. `reason` is one of - `no_live_session` (no reachable session, or the session has not - registered a conversation yet), `session_ended`, or - `unsupported_harness` (a non-Oz harness has no turn-level cancel). + description: No permission to view the run content: application/json: schema: @@ -2549,7 +2665,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /agent/conversations/{conversation_id}/followups: + '/agent/conversations/{conversation_id}/followups': post: summary: Submit a follow-up message to the run behind a conversation description: | @@ -2569,17 +2685,17 @@ paths: session runs in the session's current mode. operationId: submitConversationFollowup tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: conversation_id - in: path - description: The UUID of the Warp-native conversation - required: true - schema: - type: string - format: uuid + - name: conversation_id + in: path + description: The UUID of the Warp-native conversation + required: true + schema: + type: string + format: uuid requestBody: required: true content: @@ -2640,7 +2756,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /agent/conversations/{conversation_id}/interrupt: + '/agent/conversations/{conversation_id}/interrupt': post: summary: Interrupt the turn running on the run behind a conversation description: | @@ -2650,17 +2766,17 @@ paths: be able to view the conversation and the resolved run. operationId: interruptConversation tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: conversation_id - in: path - description: The UUID of the Warp-native conversation - required: true - schema: - type: string - format: uuid + - name: conversation_id + in: path + description: The UUID of the Warp-native conversation + required: true + schema: + type: string + format: uuid responses: '202': description: Interrupt accepted @@ -2706,7 +2822,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /agent/conversations/{conversation_id}: + '/agent/conversations/{conversation_id}': get: summary: Get normalized conversation description: | @@ -2714,16 +2830,16 @@ paths: normalized task/message format. operationId: getConversation tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: conversation_id - in: path - description: The unique identifier of the conversation - required: true - schema: - type: string + - name: conversation_id + in: path + description: The unique identifier of the conversation + required: true + schema: + type: string responses: '200': description: Normalized conversation @@ -2763,7 +2879,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /agent/conversations/{conversation_id}/transcript: + '/agent/conversations/{conversation_id}/transcript': get: summary: Get conversation transcript description: | @@ -2772,16 +2888,16 @@ paths: Supported for third-party harness conversations (Claude Code, Codex, Gemini). operationId: getConversationTranscript tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: conversation_id - in: path - description: The unique identifier of the conversation - required: true - schema: - type: string + - name: conversation_id + in: path + description: The unique identifier of the conversation + required: true + schema: + type: string responses: '302': description: Redirect to a download URL for the transcript @@ -2821,7 +2937,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /agent/conversations/{conversation_id}/screenshots/{screenshot_uid}/download: + '/agent/conversations/{conversation_id}/screenshots/{screenshot_uid}/download': get: summary: Download a stored computer-use screenshot description: | @@ -2833,22 +2949,22 @@ paths: screenshots stored under its source conversation's ID. operationId: downloadConversationScreenshot tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: conversation_id - in: path - description: The unique identifier of the conversation that owns the screenshot - required: true - schema: - type: string - - name: screenshot_uid - in: path - description: The unique identifier of the stored screenshot - required: true - schema: - type: string + - name: conversation_id + in: path + description: The unique identifier of the conversation that owns the screenshot + required: true + schema: + type: string + - name: screenshot_uid + in: path + description: The unique identifier of the stored screenshot + required: true + schema: + type: string responses: '302': description: Redirect to a temporary signed screenshot download URL @@ -2904,11 +3020,11 @@ paths: The agent will be triggered automatically based on the cron expression. operationId: createScheduledAgent tags: - - schedules + - schedules security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/TeamUidHeaderParam' + - $ref: '#/components/parameters/TeamUidHeaderParam' requestBody: required: true content: @@ -2940,7 +3056,7 @@ paths: schema: $ref: '#/components/schemas/ScheduledAgentItem' '400': - description: Invalid request (missing required fields, invalid cron expression) + description: 'Invalid request (missing required fields, invalid cron expression)' content: application/json: schema: @@ -2964,11 +3080,11 @@ paths: Results are sorted alphabetically by name. operationId: listScheduledAgents tags: - - schedules + - schedules security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/TeamUidHeaderParam' + - $ref: '#/components/parameters/TeamUidHeaderParam' responses: '200': description: List of scheduled agents @@ -2988,7 +3104,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /agent/schedules/{scheduleId}: + '/agent/schedules/{scheduleId}': get: summary: Get scheduled agent details description: | @@ -2996,16 +3112,16 @@ paths: including its configuration, history, and next scheduled run time. operationId: getScheduledAgent tags: - - schedules + - schedules security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: scheduleId - in: path - description: The unique identifier of the scheduled agent - required: true - schema: - type: string + - name: scheduleId + in: path + description: The unique identifier of the scheduled agent + required: true + schema: + type: string responses: '200': description: Scheduled agent details @@ -3044,16 +3160,16 @@ paths: All fields except agent_config are required. operationId: updateScheduledAgent tags: - - schedules + - schedules security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: scheduleId - in: path - description: The unique identifier of the scheduled agent - required: true - schema: - type: string + - name: scheduleId + in: path + description: The unique identifier of the scheduled agent + required: true + schema: + type: string requestBody: required: true content: @@ -3097,16 +3213,16 @@ paths: Delete a scheduled agent. This will stop all future scheduled runs. operationId: deleteScheduledAgent tags: - - schedules + - schedules security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: scheduleId - in: path - description: The unique identifier of the scheduled agent - required: true - schema: - type: string + - name: scheduleId + in: path + description: The unique identifier of the scheduled agent + required: true + schema: + type: string responses: '200': description: Scheduled agent deleted successfully @@ -3138,23 +3254,23 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /agent/schedules/{scheduleId}/pause: + '/agent/schedules/{scheduleId}/pause': post: summary: Pause a scheduled agent description: | Pause a scheduled agent. The agent will not run until resumed. operationId: pauseScheduledAgent tags: - - schedules + - schedules security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: scheduleId - in: path - description: The unique identifier of the scheduled agent - required: true - schema: - type: string + - name: scheduleId + in: path + description: The unique identifier of the scheduled agent + required: true + schema: + type: string responses: '200': description: Scheduled agent paused successfully @@ -3186,7 +3302,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /agent/schedules/{scheduleId}/resume: + '/agent/schedules/{scheduleId}/resume': post: summary: Resume a scheduled agent description: | @@ -3194,16 +3310,16 @@ paths: according to its cron schedule. operationId: resumeScheduledAgent tags: - - schedules + - schedules security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: scheduleId - in: path - description: The unique identifier of the scheduled agent - required: true - schema: - type: string + - name: scheduleId + in: path + description: The unique identifier of the scheduled agent + required: true + schema: + type: string responses: '200': description: Scheduled agent resumed successfully @@ -3244,24 +3360,24 @@ paths: or has accessed via link sharing. operationId: listEnvironments tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/TeamUidHeaderParam' - - name: sort_by - in: query - required: false - description: | - Sort order for the returned environments. - - `name`: alphabetical by environment name - - `last_updated`: most recently updated first (default) - schema: - type: string - enum: - - name - - last_updated - default: last_updated + - $ref: '#/components/parameters/TeamUidHeaderParam' + - name: sort_by + in: query + required: false + description: | + Sort order for the returned environments. + - `name`: alphabetical by environment name + - `last_updated`: most recently updated first (default) + schema: + type: string + enum: + - name + - last_updated + default: last_updated responses: '200': description: List of accessible environments @@ -3291,9 +3407,9 @@ paths: currently disabled (and why). operationId: listModels tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] responses: '200': description: List of available models @@ -3313,7 +3429,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /agent/artifacts/{artifactUid}: + '/agent/artifacts/{artifactUid}': get: summary: Get artifact details description: | @@ -3324,17 +3440,17 @@ paths: authenticated and authorized. operationId: getArtifact tags: - - agent + - agent security: - - bearerAuth: [] - - {} + - bearerAuth: [] + - {} parameters: - - name: artifactUid - in: path - description: The unique identifier (UUID) of the artifact - required: true - schema: - type: string + - name: artifactUid + in: path + description: The unique identifier (UUID) of the artifact + required: true + schema: + type: string responses: '200': description: Artifact details with download information @@ -3366,7 +3482,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /agent/artifacts/{artifactUid}/download: + '/agent/artifacts/{artifactUid}/download': get: summary: Download an artifact description: | @@ -3375,17 +3491,17 @@ paths: artifacts require the caller to be authenticated and authorized. operationId: downloadArtifact tags: - - agent + - agent security: - - bearerAuth: [] - - {} + - bearerAuth: [] + - {} parameters: - - name: artifactUid - in: path - description: The unique identifier (UUID) of the artifact - required: true - schema: - type: string + - name: artifactUid + in: path + description: The unique identifier (UUID) of the artifact + required: true + schema: + type: string responses: '302': description: Redirect to a temporary signed artifact download URL @@ -3427,14 +3543,14 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /factory/{uid}/scorers/{scorer_uid}: + '/factory/{uid}/scorers/{scorer_uid}': parameters: - - name: uid - in: path - description: UID of the factory that owns the scorer - required: true - schema: - type: string + - name: uid + in: path + description: UID of the factory that owns the scorer + required: true + schema: + type: string patch: summary: Update a scorer's definition description: | @@ -3448,17 +3564,17 @@ paths: scope in full. operationId: updateScorer tags: - - factory-scorers + - factory security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: scorer_uid - in: path - description: The scorer identifier - required: true - schema: - type: string - description: Scorer UUID or temporary positive decimal integer ID. + - name: scorer_uid + in: path + description: The scorer identifier + required: true + schema: + type: string + description: Scorer UUID or temporary positive decimal integer ID. requestBody: required: true content: @@ -3487,7 +3603,7 @@ paths: '403': $ref: '#/components/responses/FactoryAccessDenied' '404': - description: Scorer not found, or the caller cannot manage its factory + description: 'Scorer not found, or the caller cannot manage its factory' content: application/json: schema: @@ -3512,17 +3628,17 @@ paths: both are gone. operationId: deleteScorer tags: - - factory-scorers + - factory security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: scorer_uid - in: path - description: The scorer identifier - required: true - schema: - type: string - description: Scorer UUID or temporary positive decimal integer ID. + - name: scorer_uid + in: path + description: The scorer identifier + required: true + schema: + type: string + description: Scorer UUID or temporary positive decimal integer ID. responses: '204': description: Scorer deleted @@ -3541,65 +3657,7 @@ paths: '403': $ref: '#/components/responses/FactoryAccessDenied' '404': - description: Scorer not found, or the caller cannot manage its factory - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - '500': - description: Internal server error - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - /agent/conversations/{conversationId}/block-snapshot: - get: - summary: Download a conversation's block snapshot - description: | - Redirect to a signed storage URL for the serialized block snapshot. - Set redirect=false to return the URL as JSON instead. Both modes require - permission to view the conversation. - operationId: getConversationBlockSnapshot - tags: - - agent - security: - - bearerAuth: [] - parameters: - - name: conversationId - in: path - required: true - schema: - type: string - - $ref: '#/components/parameters/PresignedDownloadRedirect' - responses: - '200': - description: Signed download URL when redirect=false - content: - application/json: - schema: - $ref: '#/components/schemas/PresignedDownloadResponse' - '307': - description: Redirect to the signed storage URL (default) - '400': - description: Conversation format does not support block snapshots - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - '401': - description: Authentication required - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - '403': - description: No permission to view the conversation - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - '404': - description: Conversation or snapshot not found + description: 'Scorer not found, or the caller cannot manage its factory' content: application/json: schema: @@ -3618,11 +3676,11 @@ paths: own permissions, configuration, and identity. operationId: createAgent tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/TeamUidHeaderParam' + - $ref: '#/components/parameters/TeamUidHeaderParam' requestBody: required: true content: @@ -3637,7 +3695,7 @@ paths: schema: $ref: '#/components/schemas/AgentResponse' '400': - description: Invalid request (empty name, user on multiple teams, or on no team) + description: 'Invalid request (empty name, user on multiple teams, or on no team)' content: application/json: schema: @@ -3649,7 +3707,7 @@ paths: schema: $ref: '#/components/schemas/Error' '403': - description: Only human users can manage agents, or plan limit exceeded + description: 'Only human users can manage agents, or plan limit exceeded' content: application/json: schema: @@ -3666,19 +3724,19 @@ paths: List all agents on the caller's team. operationId: listAgents tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/TeamUidHeaderParam' - - name: factory_uid - in: query - required: false - description: | - Optional UID of a Factory to filter by. When provided, only agents - linked to that factory are returned. - schema: - type: string + - $ref: '#/components/parameters/TeamUidHeaderParam' + - name: factory_uid + in: query + required: false + description: | + Optional UID of a Factory to filter by. When provided, only agents + linked to that factory are returned. + schema: + type: string responses: '200': description: List of agents @@ -3687,7 +3745,7 @@ paths: schema: $ref: '#/components/schemas/ListAgentIdentitiesResponse' '400': - description: User on multiple teams, or on no team + description: 'User on multiple teams, or on no team' content: application/json: schema: @@ -3710,14 +3768,14 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /factory/{uid}/scorers: + '/factory/{uid}/scorers': parameters: - - name: uid - in: path - description: UID of the factory that owns the scorer - required: true - schema: - type: string + - name: uid + in: path + description: UID of the factory that owns the scorer + required: true + schema: + type: string post: summary: Create a scorer description: | @@ -3727,9 +3785,9 @@ paths: request; the scorer and its self-improvement config are created atomically. operationId: createScorer tags: - - factory-scorers + - factory security: - - bearerAuth: [] + - bearerAuth: [] requestBody: required: true content: @@ -3780,32 +3838,32 @@ paths: and aggregate scoring stats. operationId: listScorers tags: - - factory-scorers + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/TeamUidHeaderParam' - - name: start_date - in: query - deprecated: true - description: | - Legacy summary range start (RFC3339 UTC, inclusive). Accepted - and validated for compatibility; does not affect the list - response. Must be provided together with end_date and be - strictly before it. - required: false - schema: - type: string - format: date-time - - name: end_date - in: query - deprecated: true - description: | - Legacy summary range end (RFC3339 UTC, exclusive). See start_date. - required: false - schema: - type: string - format: date-time + - $ref: '#/components/parameters/TeamUidHeaderParam' + - name: start_date + in: query + deprecated: true + description: | + Legacy summary range start (RFC3339 UTC, inclusive). Accepted + and validated for compatibility; does not affect the list + response. Must be provided together with end_date and be + strictly before it. + required: false + schema: + type: string + format: date-time + - name: end_date + in: query + deprecated: true + description: | + Legacy summary range end (RFC3339 UTC, exclusive). See start_date. + required: false + schema: + type: string + format: date-time responses: '200': description: Scorers for the factory @@ -3841,14 +3899,14 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /factory/{uid}/scorers/{scorer_uid}/results: + '/factory/{uid}/scorers/{scorer_uid}/results': parameters: - - name: uid - in: path - description: UID of the factory that owns the scorer - required: true - schema: - type: string + - name: uid + in: path + description: UID of the factory that owns the scorer + required: true + schema: + type: string get: summary: List results for a scorer description: | @@ -3859,53 +3917,53 @@ paths: Reasons are read from object storage only when include_reasons is true. operationId: listScorerResults tags: - - factory-scorers + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/TeamUidHeaderParam' - - name: scorer_uid - in: path - description: The scorer identifier - required: true - schema: - type: string - description: Scorer UUID or temporary positive decimal integer ID. - - name: limit - in: query - description: Maximum number of results to return (1-100, default 50) - required: false - schema: - type: integer - minimum: 1 - maximum: 100 - default: 50 - - name: cursor - in: query - description: Opaque cursor returned by a previous list response. - required: false - schema: - type: string - - name: include_reasons - in: query - description: Include reason availability and readable judge reasoning. - required: false - schema: - type: boolean - default: false - - name: run_id - in: query - description: | - Exact run filters, repeated once per run. Values are trimmed and - deduplicated; require 1-100 distinct nonblank runs when present. - Cannot be combined with cursor or limit. - required: false - style: form - explode: true - schema: - type: array - items: + - $ref: '#/components/parameters/TeamUidHeaderParam' + - name: scorer_uid + in: path + description: The scorer identifier + required: true + schema: + type: string + description: Scorer UUID or temporary positive decimal integer ID. + - name: limit + in: query + description: 'Maximum number of results to return (1-100, default 50)' + required: false + schema: + type: integer + minimum: 1 + maximum: 100 + default: 50 + - name: cursor + in: query + description: Opaque cursor returned by a previous list response. + required: false + schema: type: string + - name: include_reasons + in: query + description: Include reason availability and readable judge reasoning. + required: false + schema: + type: boolean + default: false + - name: run_id + in: query + description: | + Exact run filters, repeated once per run. Values are trimmed and + deduplicated; require 1-100 distinct nonblank runs when present. + Cannot be combined with cursor or limit. + required: false + style: form + explode: true + schema: + type: array + items: + type: string responses: '200': description: Recent results for the scorer @@ -3914,7 +3972,7 @@ paths: schema: $ref: '#/components/schemas/ListScorerResultsResponse' '400': - description: Invalid scorer ID, limit, cursor, include_reasons, or run_id filters + description: 'Invalid scorer ID, limit, cursor, include_reasons, or run_id filters' content: application/json: schema: @@ -3939,14 +3997,14 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /factory/{uid}/scorers/{scorer_uid}/metrics: + '/factory/{uid}/scorers/{scorer_uid}/metrics': parameters: - - name: uid - in: path - description: UID of the factory that owns the scorer - required: true - schema: - type: string + - name: uid + in: path + description: UID of the factory that owns the scorer + required: true + schema: + type: string get: summary: Get scorer metrics over a date range description: | @@ -3957,44 +4015,44 @@ paths: `GET /factory/{uid}/metrics`. operationId: getScorerMetrics tags: - - factory-scorers + - factory security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/TeamUidHeaderParam' - - name: scorer_uid - in: path - description: The scorer identifier - required: true - schema: - type: string - description: Scorer UUID or temporary positive decimal integer ID. - - name: start_date - in: query - description: RFC3339 UTC range start, inclusive. Defaults to 30 days before end_date. - required: false - schema: - type: string - format: date-time - - name: end_date - in: query - description: RFC3339 UTC range end, exclusive. Defaults to now. - required: false - schema: - type: string - format: date-time - - name: group_by_period - in: query - description: Binning granularity for the series. Defaults to day. - required: false - schema: - $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' - - name: include_cost - in: query - description: Include the scorer's judge-run cost for each period. Defaults to false. - required: false - schema: - type: boolean + - $ref: '#/components/parameters/TeamUidHeaderParam' + - name: scorer_uid + in: path + description: The scorer identifier + required: true + schema: + type: string + description: Scorer UUID or temporary positive decimal integer ID. + - name: start_date + in: query + description: 'RFC3339 UTC range start, inclusive. Defaults to 30 days before end_date.' + required: false + schema: + type: string + format: date-time + - name: end_date + in: query + description: 'RFC3339 UTC range end, exclusive. Defaults to now.' + required: false + schema: + type: string + format: date-time + - name: group_by_period + in: query + description: Binning granularity for the series. Defaults to day. + required: false + schema: + $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' + - name: include_cost + in: query + description: Include the scorer's judge-run cost for each period. Defaults to false. + required: false + schema: + type: boolean responses: '200': description: The scorer's pass-rate series and range aggregate @@ -4003,7 +4061,7 @@ paths: schema: $ref: '#/components/schemas/ScorerMetricsResponse' '400': - description: Invalid scorer ID, date range, group_by_period, or include_cost + description: 'Invalid scorer ID, date range, group_by_period, or include_cost' content: application/json: schema: @@ -4026,7 +4084,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /factory/{factory_uid}/runs/{run_id}/scorer_dispatch: + '/factory/{factory_uid}/runs/{run_id}/scorer_dispatch': post: summary: Manually dispatch scorers for a run description: | @@ -4049,22 +4107,22 @@ paths: individual failures; inspect each result's `status` and `error`. operationId: dispatchRunScorers tags: - - factory-scorers + - factory security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: factory_uid - in: path - required: true - description: The factory containing the run and scorers. - schema: - type: string - - name: run_id - in: path - required: true - schema: - type: string - format: uuid + - name: factory_uid + in: path + required: true + description: The factory containing the run and scorers. + schema: + type: string + - name: run_id + in: path + required: true + schema: + type: string + format: uuid requestBody: required: true content: @@ -4073,8 +4131,8 @@ paths: $ref: '#/components/schemas/RunScorerDispatchRequest' example: scorer_uids: - - 0199b01b-b7c0-7000-8000-000000000007 - - 0199b01b-b7c0-7000-8000-000000000008 + - 0199b01b-b7c0-7000-8000-000000000007 + - 0199b01b-b7c0-7000-8000-000000000008 responses: '202': description: Per-pair dispatch outcomes; scoring completes asynchronously. @@ -4083,7 +4141,7 @@ paths: schema: $ref: '#/components/schemas/ManualScoringDispatchResponse' '400': - description: Invalid selection, ineligible run or scorer, or more than 100 scorer UUIDs. + description: 'Invalid selection, ineligible run or scorer, or more than 100 scorer UUIDs.' content: application/json: schema: @@ -4097,7 +4155,7 @@ paths: '403': $ref: '#/components/responses/FactoryAccessDenied' '404': - description: A named run or scorer does not exist, or the caller lacks access + description: 'A named run or scorer does not exist, or the caller lacks access' content: application/json: schema: @@ -4108,7 +4166,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /factory/{factory_uid}/scorers/{scorer_uid}/dispatch: + '/factory/{factory_uid}/scorers/{scorer_uid}/dispatch': post: summary: Manually dispatch a scorer for selected runs description: | @@ -4131,22 +4189,22 @@ paths: individual failures; inspect each result's `status` and `error`. operationId: dispatchScorer tags: - - factory-scorers + - factory security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: factory_uid - in: path - required: true - description: The factory containing the scorer and runs. - schema: - type: string - - name: scorer_uid - in: path - required: true - schema: - type: string - format: uuid + - name: factory_uid + in: path + required: true + description: The factory containing the scorer and runs. + schema: + type: string + - name: scorer_uid + in: path + required: true + schema: + type: string + format: uuid requestBody: required: true content: @@ -4155,8 +4213,8 @@ paths: $ref: '#/components/schemas/ScorerDispatchRequest' example: run_ids: - - 0199b01b-b7c0-7000-8000-000000000001 - - 0199b01b-b7c0-7000-8000-000000000002 + - 0199b01b-b7c0-7000-8000-000000000001 + - 0199b01b-b7c0-7000-8000-000000000002 responses: '202': description: Per-pair dispatch outcomes; scoring completes asynchronously. @@ -4165,7 +4223,7 @@ paths: schema: $ref: '#/components/schemas/ManualScoringDispatchResponse' '400': - description: Invalid selection, ineligible run or scorer, or more than 100 run UUIDs. + description: 'Invalid selection, ineligible run or scorer, or more than 100 run UUIDs.' content: application/json: schema: @@ -4179,7 +4237,7 @@ paths: '403': $ref: '#/components/responses/FactoryAccessDenied' '404': - description: A named run or scorer does not exist, or the caller lacks access + description: 'A named run or scorer does not exist, or the caller lacks access' content: application/json: schema: @@ -4190,7 +4248,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /factory/runs/{run_id}/scores: + '/factory/runs/{run_id}/scores': get: summary: Read a run's current scores description: | @@ -4201,16 +4259,16 @@ paths: the run. operationId: listRunScores tags: - - factory-scorers + - factory security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: run_id - in: path - description: The run identifier - required: true - schema: - type: string + - name: run_id + in: path + description: The run identifier + required: true + schema: + type: string responses: '200': description: The run's current scores @@ -4227,7 +4285,7 @@ paths: '403': $ref: '#/components/responses/FactoryAccessDenied' '404': - description: Run not found, or the caller cannot view it + description: 'Run not found, or the caller cannot view it' content: application/json: schema: @@ -4238,23 +4296,23 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /agent/identities/{uid}: + '/agent/identities/{uid}': get: summary: Retrieve an agent description: | Retrieve a single agent by its unique identifier. operationId: getAgent tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: uid - in: path - description: The unique identifier of the agent - required: true - schema: - type: string + - name: uid + in: path + description: The unique identifier of the agent + required: true + schema: + type: string responses: '200': description: Agent details @@ -4286,16 +4344,16 @@ paths: Update an existing agent. operationId: updateAgent tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: uid - in: path - description: The unique identifier of the agent - required: true - schema: - type: string + - name: uid + in: path + description: The unique identifier of the agent + required: true + schema: + type: string requestBody: required: true content: @@ -4322,7 +4380,7 @@ paths: schema: $ref: '#/components/schemas/Error' '403': - description: Only human users can manage agents, or plan limit exceeded + description: 'Only human users can manage agents, or plan limit exceeded' content: application/json: schema: @@ -4346,16 +4404,16 @@ paths: agent are deleted atomically. operationId: deleteAgent tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: uid - in: path - description: The unique identifier of the agent - required: true - schema: - type: string + - name: uid + in: path + description: The unique identifier of the agent + required: true + schema: + type: string responses: '204': description: Agent deleted successfully @@ -4389,16 +4447,98 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /factory/{factory_uid}/benchmarks: + '/agent/sessions/{sessionUuid}/redirect': + get: + summary: Get session redirect + description: | + Check whether a shared session should redirect to a conversation + transcript, returning a conversation_id if the agent sandbox has + finished and conversation data is available (or an empty object if + no redirect is needed). Public and unauthenticated, so anonymous + viewers can resolve a shared session link before signing in; access + to the underlying transcript is still gated by conversation + link-sharing. + operationId: getSessionRedirect + tags: + - agent + security: [] + parameters: + - name: sessionUuid + in: path + description: The UUID of the shared session + required: true + schema: + type: string + responses: + '200': + description: | + Redirect information. Contains conversation_id if redirect is needed, + otherwise an empty object. + content: + application/json: + schema: + type: object + properties: + conversation_id: + type: string + description: The conversation ID to redirect to (only present when redirect is needed) + '500': + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '/agent/conversations/{conversationId}/redirect': + get: + summary: Get conversation redirect + description: | + Check whether a conversation should redirect to a live shared + session, returning a session_id if the underlying ambient agent task + still has one (or an empty object if no redirect is needed). Public + and unauthenticated, so anonymous viewers can resolve a shared + conversation link before signing in; access to the underlying live + session is still gated by the session-sharing service ACLs. + operationId: getConversationRedirect + tags: + - agent + security: [] + parameters: + - name: conversationId + in: path + description: The ID of the conversation + required: true + schema: + type: string + responses: + '200': + description: | + Redirect information. Contains session_id if redirect is needed, + otherwise an empty object. + content: + application/json: + schema: + type: object + properties: + session_id: + type: string + description: The shared session UUID to redirect to (only present when redirect is needed) + '500': + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '/factory/{factory_uid}/benchmarks': post: summary: Create a benchmark suite operationId: createBenchmarkSuite tags: - - factory-benchmarks + - factory + - benchmark security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/BenchmarkFactoryPath' + - $ref: '#/components/parameters/BenchmarkFactoryPath' requestBody: required: true content: @@ -4442,24 +4582,25 @@ paths: summary: List benchmark suites operationId: listBenchmarkSuites tags: - - factory-benchmarks + - factory + - benchmark security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/BenchmarkFactoryPath' - - name: limit - in: query - required: false - schema: - type: integer - minimum: 1 - maximum: 100 - default: 50 - - name: cursor - in: query - required: false - schema: - type: string + - $ref: '#/components/parameters/BenchmarkFactoryPath' + - name: limit + in: query + required: false + schema: + type: integer + minimum: 1 + maximum: 100 + default: 50 + - name: cursor + in: query + required: false + schema: + type: string responses: '200': description: List of suites @@ -4481,17 +4622,18 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - /factory/{factory_uid}/benchmarks/{suite_uid}: + '/factory/{factory_uid}/benchmarks/{suite_uid}': get: summary: Get a benchmark suite with its tasks and configurations operationId: getBenchmarkSuite tags: - - factory-benchmarks + - factory + - benchmark security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/BenchmarkFactoryPath' - - $ref: '#/components/parameters/BenchmarkSuitePath' + - $ref: '#/components/parameters/BenchmarkFactoryPath' + - $ref: '#/components/parameters/BenchmarkSuitePath' responses: '200': description: Suite details @@ -4517,12 +4659,13 @@ paths: summary: Edit a benchmark suite operationId: patchBenchmarkSuite tags: - - factory-benchmarks + - factory + - benchmark security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/BenchmarkFactoryPath' - - $ref: '#/components/parameters/BenchmarkSuitePath' + - $ref: '#/components/parameters/BenchmarkFactoryPath' + - $ref: '#/components/parameters/BenchmarkSuitePath' requestBody: required: true content: @@ -4560,12 +4703,13 @@ paths: summary: Soft-delete a benchmark suite operationId: deleteBenchmarkSuite tags: - - factory-benchmarks + - factory + - benchmark security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/BenchmarkFactoryPath' - - $ref: '#/components/parameters/BenchmarkSuitePath' + - $ref: '#/components/parameters/BenchmarkFactoryPath' + - $ref: '#/components/parameters/BenchmarkSuitePath' responses: '204': description: Suite deleted @@ -4583,7 +4727,7 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - /factory/{factory_uid}/benchmarks/{suite_uid}/tasks: + '/factory/{factory_uid}/benchmarks/{suite_uid}/tasks': post: summary: Create a benchmark suite task description: | @@ -4597,12 +4741,13 @@ paths: is saved as a file and returned from that file. operationId: createBenchmarkSuiteTask tags: - - factory-benchmarks + - factory + - benchmark security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/BenchmarkFactoryPath' - - $ref: '#/components/parameters/BenchmarkSuitePath' + - $ref: '#/components/parameters/BenchmarkFactoryPath' + - $ref: '#/components/parameters/BenchmarkSuitePath' requestBody: required: true content: @@ -4631,34 +4776,35 @@ paths: '403': $ref: '#/components/responses/FactoryAccessDenied' '404': - description: Suite not found, or source_run_id is not a run the caller can read + description: 'Suite not found, or source_run_id is not a run the caller can read' content: application/problem+json: schema: $ref: '#/components/schemas/Error' '409': - description: Another task in this suite already has this title with different content, or the Factory is file-managed and cannot be written through + description: 'Another task in this suite already has this title with different content, or the Factory is file-managed and cannot be written through' content: application/problem+json: schema: $ref: '#/components/schemas/Error' - /factory/{factory_uid}/benchmarks/{suite_uid}/tasks/{task_uid}: + '/factory/{factory_uid}/benchmarks/{suite_uid}/tasks/{task_uid}': get: summary: Get one benchmark suite task operationId: getBenchmarkSuiteTask tags: - - factory-benchmarks + - factory + - benchmark security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/BenchmarkFactoryPath' - - $ref: '#/components/parameters/BenchmarkSuitePath' - - name: task_uid - in: path - required: true - schema: - type: string - format: uuid + - $ref: '#/components/parameters/BenchmarkFactoryPath' + - $ref: '#/components/parameters/BenchmarkSuitePath' + - name: task_uid + in: path + required: true + schema: + type: string + format: uuid responses: '200': description: Task details @@ -4681,7 +4827,7 @@ paths: '403': $ref: '#/components/responses/FactoryAccessDenied' '404': - description: Suite not found, task not found, or task_uid belongs to another suite + description: 'Suite not found, task not found, or task_uid belongs to another suite' content: application/problem+json: schema: @@ -4696,18 +4842,19 @@ paths: starting_repo_refs or tags clears that field. operationId: patchBenchmarkSuiteTask tags: - - factory-benchmarks + - factory + - benchmark security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/BenchmarkFactoryPath' - - $ref: '#/components/parameters/BenchmarkSuitePath' - - name: task_uid - in: path - required: true - schema: - type: string - format: uuid + - $ref: '#/components/parameters/BenchmarkFactoryPath' + - $ref: '#/components/parameters/BenchmarkSuitePath' + - name: task_uid + in: path + required: true + schema: + type: string + format: uuid requestBody: required: true content: @@ -4722,7 +4869,7 @@ paths: schema: $ref: '#/components/schemas/BenchmarkSuiteTask' '400': - description: Invalid request, or task_uid is not a valid UUID + description: 'Invalid request, or task_uid is not a valid UUID' content: application/problem+json: schema: @@ -4736,7 +4883,7 @@ paths: '403': $ref: '#/components/responses/FactoryAccessDenied' '404': - description: Suite not found, task not found, or task_uid belongs to another suite + description: 'Suite not found, task not found, or task_uid belongs to another suite' content: application/problem+json: schema: @@ -4751,18 +4898,19 @@ paths: summary: Delete one benchmark suite task operationId: deleteBenchmarkSuiteTask tags: - - factory-benchmarks + - factory + - benchmark security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/BenchmarkFactoryPath' - - $ref: '#/components/parameters/BenchmarkSuitePath' - - name: task_uid - in: path - required: true - schema: - type: string - format: uuid + - $ref: '#/components/parameters/BenchmarkFactoryPath' + - $ref: '#/components/parameters/BenchmarkSuitePath' + - name: task_uid + in: path + required: true + schema: + type: string + format: uuid responses: '204': description: Task deleted @@ -4781,7 +4929,7 @@ paths: '403': $ref: '#/components/responses/FactoryAccessDenied' '404': - description: Suite not found, task not found, or task_uid belongs to another suite + description: 'Suite not found, task not found, or task_uid belongs to another suite' content: application/problem+json: schema: @@ -4792,7 +4940,7 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - /factory/{factory_uid}/benchmarks/{suite_uid}/runs: + '/factory/{factory_uid}/benchmarks/{suite_uid}/runs': post: summary: Launch a benchmark run from the current suite version description: | @@ -4805,12 +4953,13 @@ paths: These options do not change execution retries within the benchmark run. operationId: launchBenchmarkRun tags: - - factory-benchmarks + - factory + - benchmark security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/BenchmarkFactoryPath' - - $ref: '#/components/parameters/BenchmarkSuitePath' + - $ref: '#/components/parameters/BenchmarkFactoryPath' + - $ref: '#/components/parameters/BenchmarkSuitePath' requestBody: required: true content: @@ -4827,8 +4976,8 @@ paths: value: repetition_count: 1 tasks: - - 7d69fb52-71c5-4e27-914e-8764ee9c5246 - - ad8ff7dc-a7d1-4ed6-9f50-650010bb39aa + - 7d69fb52-71c5-4e27-914e-8764ee9c5246 + - ad8ff7dc-a7d1-4ed6-9f50-650010bb39aa responses: '201': description: Run launched @@ -4867,38 +5016,39 @@ paths: information in `page_info`. Retained runs remain readable after the suite is deleted; an unknown suite returns an empty list. tags: - - factory-benchmarks + - factory + - benchmark security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/BenchmarkRunInclude' - - $ref: '#/components/parameters/BenchmarkFactoryPath' - - $ref: '#/components/parameters/BenchmarkSuitePath' - - name: state - in: query - required: false - schema: - type: array - items: - $ref: '#/components/schemas/BenchmarkRunState' - style: form - explode: true - - name: limit - in: query - required: false - schema: - type: integer - minimum: 1 - maximum: 100 - default: 50 - - name: cursor - in: query - required: false - schema: - type: string + - $ref: '#/components/parameters/BenchmarkRunInclude' + - $ref: '#/components/parameters/BenchmarkFactoryPath' + - $ref: '#/components/parameters/BenchmarkSuitePath' + - name: state + in: query + required: false + schema: + type: array + items: + $ref: '#/components/schemas/BenchmarkRunState' + style: form + explode: true + - name: limit + in: query + required: false + schema: + type: integer + minimum: 1 + maximum: 100 + default: 50 + - name: cursor + in: query + required: false + schema: + type: string responses: '200': - description: Runs from the frozen suite identity, including deleted suites; empty for an unknown suite + description: 'Runs from the frozen suite identity, including deleted suites; empty for an unknown suite' content: application/json: schema: @@ -4917,7 +5067,7 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - /factory/{factory_uid}/benchmarks/{suite_uid}/runs/{run_uid}: + '/factory/{factory_uid}/benchmarks/{suite_uid}/runs/{run_uid}': get: summary: Get benchmark run detail operationId: getBenchmarkRun @@ -4927,14 +5077,15 @@ paths: Use `include` to add these fields or the creator's display name. Retrieve trials separately for individual scores and execution history. tags: - - factory-benchmarks + - factory + - benchmark security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/BenchmarkRunInclude' - - $ref: '#/components/parameters/BenchmarkFactoryPath' - - $ref: '#/components/parameters/BenchmarkSuitePath' - - $ref: '#/components/parameters/BenchmarkRunPath' + - $ref: '#/components/parameters/BenchmarkRunInclude' + - $ref: '#/components/parameters/BenchmarkFactoryPath' + - $ref: '#/components/parameters/BenchmarkSuitePath' + - $ref: '#/components/parameters/BenchmarkRunPath' responses: '200': description: Run detail @@ -4956,18 +5107,19 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - /factory/{factory_uid}/benchmarks/{suite_uid}/runs/{run_uid}/cancel: + '/factory/{factory_uid}/benchmarks/{suite_uid}/runs/{run_uid}/cancel': post: summary: Cancel an in-flight benchmark run operationId: cancelBenchmarkRun tags: - - factory-benchmarks + - factory + - benchmark security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/BenchmarkFactoryPath' - - $ref: '#/components/parameters/BenchmarkSuitePath' - - $ref: '#/components/parameters/BenchmarkRunPath' + - $ref: '#/components/parameters/BenchmarkFactoryPath' + - $ref: '#/components/parameters/BenchmarkSuitePath' + - $ref: '#/components/parameters/BenchmarkRunPath' responses: '200': description: Run cancelled @@ -4995,7 +5147,47 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - /factory/{factory_uid}/benchmarks/{suite_uid}/runs/{run_uid}/results: + '/factory/{factory_uid}/benchmarks/{suite_uid}/runs/{run_uid}/rescore': + post: + summary: Rescore missing results for a completed benchmark run + operationId: rescoreBenchmarkRun + tags: + - factory + - benchmark + security: + - bearerAuth: [] + parameters: + - $ref: '#/components/parameters/BenchmarkFactoryPath' + - $ref: '#/components/parameters/BenchmarkSuitePath' + - $ref: '#/components/parameters/BenchmarkRunPath' + responses: + '202': + description: Missing scores accepted for rescoring + content: + application/json: + schema: + $ref: '#/components/schemas/BenchmarkRunLaunchResponse' + '400': + description: Run is not eligible for rescoring + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Error' + '401': + description: Authentication required + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Error' + '403': + $ref: '#/components/responses/FactoryAccessDenied' + '404': + description: Run not found in this suite or action unavailable + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Error' + '/factory/{factory_uid}/benchmarks/{suite_uid}/runs/{run_uid}/results': get: summary: Get benchmark run results operationId: getBenchmarkRunResults @@ -5008,18 +5200,19 @@ paths: changing the summary or comparison populations. Results cover the whole selected dataset, independently of trial-list pages, and are not paginated. tags: - - factory-benchmarks + - factory + - benchmark security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/BenchmarkResultsInclude' - - $ref: '#/components/parameters/BenchmarkTaskSelection' - - $ref: '#/components/parameters/BenchmarkTagSelection' - - $ref: '#/components/parameters/BenchmarkConfigurationProjection' - - $ref: '#/components/parameters/BenchmarkScorerProjection' - - $ref: '#/components/parameters/BenchmarkFactoryPath' - - $ref: '#/components/parameters/BenchmarkSuitePath' - - $ref: '#/components/parameters/BenchmarkRunPath' + - $ref: '#/components/parameters/BenchmarkResultsInclude' + - $ref: '#/components/parameters/BenchmarkTaskSelection' + - $ref: '#/components/parameters/BenchmarkTagSelection' + - $ref: '#/components/parameters/BenchmarkConfigurationProjection' + - $ref: '#/components/parameters/BenchmarkScorerProjection' + - $ref: '#/components/parameters/BenchmarkFactoryPath' + - $ref: '#/components/parameters/BenchmarkSuitePath' + - $ref: '#/components/parameters/BenchmarkRunPath' responses: '200': description: Results aggregate (JSON) @@ -5041,7 +5234,7 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - /factory/{factory_uid}/benchmarks/{suite_uid}/runs/{run_uid}/trials: + '/factory/{factory_uid}/benchmarks/{suite_uid}/runs/{run_uid}/trials': get: summary: List benchmark trials or find the trial for an agent run operationId: listBenchmarkTrials @@ -5058,48 +5251,49 @@ paths: This lookup accepts `include` and an omitted `limit` or `limit=1`, but no cursor or other filters. Filtering by scorer is not supported. tags: - - factory-benchmarks + - factory + - benchmark security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/BenchmarkFactoryPath' - - $ref: '#/components/parameters/BenchmarkSuitePath' - - $ref: '#/components/parameters/BenchmarkRunPath' - - $ref: '#/components/parameters/BenchmarkTrialInclude' - - $ref: '#/components/parameters/BenchmarkTaskSelection' - - $ref: '#/components/parameters/BenchmarkTagSelection' - - name: configuration_uid - in: query - style: form - explode: true - schema: - type: array - items: + - $ref: '#/components/parameters/BenchmarkFactoryPath' + - $ref: '#/components/parameters/BenchmarkSuitePath' + - $ref: '#/components/parameters/BenchmarkRunPath' + - $ref: '#/components/parameters/BenchmarkTrialInclude' + - $ref: '#/components/parameters/BenchmarkTaskSelection' + - $ref: '#/components/parameters/BenchmarkTagSelection' + - name: configuration_uid + in: query + style: form + explode: true + schema: + type: array + items: + type: string + - name: state + in: query + style: form + explode: true + schema: + type: array + items: + $ref: '#/components/schemas/BenchmarkTrialState' + - name: agent_run_id + in: query + schema: + type: string + - name: limit + in: query + schema: + type: integer + default: 50 + minimum: 1 + maximum: 100 + - name: cursor + in: query + description: Pass the previous response's page_info.next_cursor with the same filters to retrieve the next page. + schema: type: string - - name: state - in: query - style: form - explode: true - schema: - type: array - items: - $ref: '#/components/schemas/BenchmarkTrialState' - - name: agent_run_id - in: query - schema: - type: string - - name: limit - in: query - schema: - type: integer - default: 50 - minimum: 1 - maximum: 100 - - name: cursor - in: query - description: Pass the previous response's page_info.next_cursor with the same filters to retrieve the next page. - schema: - type: string responses: '200': description: Complete requested Trial rows on one page @@ -5108,7 +5302,7 @@ paths: schema: $ref: '#/components/schemas/BenchmarkTrialList' '400': - description: Invalid selection, include, or cursor + description: 'Invalid selection, include, or cursor' content: application/problem+json: schema: @@ -5125,7 +5319,7 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - /factory/{factory_uid}/benchmarks/{suite_uid}/runs/{run_uid}/trials/{trial_uid}: + '/factory/{factory_uid}/benchmarks/{suite_uid}/runs/{run_uid}/trials/{trial_uid}': get: summary: Retrieve an individual benchmark trial within a run operationId: getBenchmarkTrial @@ -5136,19 +5330,20 @@ paths: execution attempts and judge history. Each requested expansion is complete. Selection and pagination parameters are not supported. tags: - - factory-benchmarks + - factory + - benchmark security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - $ref: '#/components/parameters/BenchmarkFactoryPath' - - $ref: '#/components/parameters/BenchmarkSuitePath' - - $ref: '#/components/parameters/BenchmarkRunPath' - - $ref: '#/components/parameters/BenchmarkTrialInclude' - - name: trial_uid - in: path - required: true - schema: - type: string + - $ref: '#/components/parameters/BenchmarkFactoryPath' + - $ref: '#/components/parameters/BenchmarkSuitePath' + - $ref: '#/components/parameters/BenchmarkRunPath' + - $ref: '#/components/parameters/BenchmarkTrialInclude' + - name: trial_uid + in: path + required: true + schema: + type: string responses: '200': description: Logical Trial with complete requested expansions @@ -5182,15 +5377,15 @@ paths: with a link to each version's schema bundle. operationId: listFactoryFileSchemaVersions tags: - - factory + - factory security: [] parameters: - - name: If-None-Match - in: header - required: false - description: A previously returned ETag. A match returns 304 with no body. - schema: - type: string + - name: If-None-Match + in: header + required: false + description: A previously returned ETag. A match returns 304 with no body. + schema: + type: string responses: '200': description: The supported schema versions @@ -5208,7 +5403,7 @@ paths: $ref: '#/components/schemas/FactoryFileSchemaRegistry' '304': description: The cached response is still current - /factory-files/schemas/{schema_version}: + '/factory-files/schemas/{schema_version}': get: summary: Get the JSON Schema bundle for one Factory file schema version description: | @@ -5217,21 +5412,21 @@ paths: identities between the documents keep resolving. operationId: getFactoryFileSchemaBundle tags: - - factory + - factory security: [] parameters: - - name: schema_version - in: path - required: true - description: A Factory file schema version, for example `v1alpha1`. - schema: - type: string - - name: If-None-Match - in: header - required: false - description: A previously returned ETag. A match returns 304 with no body. - schema: - type: string + - name: schema_version + in: path + required: true + description: 'A Factory file schema version, for example `v1alpha1`.' + schema: + type: string + - name: If-None-Match + in: header + required: false + description: A previously returned ETag. A match returns 304 with no body. + schema: + type: string responses: '200': description: The schema documents for this version @@ -5255,7 +5450,7 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/Error' - /factory-files/schemas/{schema_version}/{document}: + '/factory-files/schemas/{schema_version}/{document}': get: summary: Get one Factory file schema document description: | @@ -5268,27 +5463,27 @@ paths: ```yaml # yaml-language-server: $schema=/api/v1/factory-files/schemas/v1alpha1/factory.schema.json - ``` - operationId: getFactoryFileSchemaDocument - tags: - - factory - security: [] - parameters: - - name: schema_version - in: path - required: true - schema: - type: string - description: Factory file schema version, such as v1alpha1 - - name: document - in: path - required: true - schema: - type: string - description: | - Document file name: common.schema.json, factory.schema.json, - agent.schema.json, automation.schema.json, runner.schema.json, or - scorer.schema.json + ``` + operationId: getFactoryFileSchemaDocument + tags: + - factory + security: [] + parameters: + - name: schema_version + in: path + required: true + schema: + type: string + description: 'Factory file schema version, such as v1alpha1' + - name: document + in: path + required: true + schema: + type: string + description: | + Document file name: common.schema.json, factory.schema.json, + agent.schema.json, automation.schema.json, runner.schema.json, or + scorer.schema.json responses: '200': description: The requested JSON Schema document @@ -5311,14 +5506,6 @@ components: description: | Authentication via a Warp API key or a supported Warp-issued user token. parameters: - PresignedDownloadRedirect: - name: redirect - in: query - required: false - description: Set to false to return a signed storage URL as JSON rather than redirecting. - schema: - type: boolean - default: true BenchmarkFactoryPath: name: factory_uid in: path @@ -5359,9 +5546,9 @@ components: items: type: string enum: - - details - - summary_results - - creator_display_name + - details + - summary_results + - creator_display_name BenchmarkTrialInclude: name: include in: query @@ -5380,8 +5567,8 @@ components: items: type: string enum: - - results - - details + - results + - details BenchmarkResultsInclude: name: include in: query @@ -5400,10 +5587,10 @@ components: items: type: string enum: - - configuration_metrics - - scorer_configuration_metrics - - task_scorer_configuration_metrics - - agent_metrics + - configuration_metrics + - scorer_configuration_metrics + - task_scorer_configuration_metrics + - agent_metrics BenchmarkTaskSelection: name: task_uid in: query @@ -5468,107 +5655,9 @@ components: service-account callers, which always act as their bound team. schema: type: string - ConversationHistoryConversationId: - name: conversation_id - in: path - description: The UUID of the Warp-native conversation - required: true - schema: - type: string - format: uuid - headers: - ConversationHistoryCacheControl: - description: Prevents storage of canonical conversation history. - schema: - type: string - examples: - - no-store - ConversationHistoryRetryAfter: - description: | - Seconds to wait before re-requesting. Present only when - `X-Warp-Stream-State` is `pending`. - schema: - type: integer - examples: - - 2 - ConversationHistoryStreamState: - description: | - Whether a shared session can produce events for this conversation. - `active`: the newest session-linked execution is live; stream from - `X-Warp-Stream-Session` with `X-Warp-Stream-Cursor`. `pending`: no - session is live yet, but a hosted execution of the run is starting - and has not registered its shared session, or a queued follow-up is - waiting to start one; poll again after `Retry-After`. `ended`: no - execution is linked to a shared session or the newest one has ended, - and nothing is starting. - schema: - type: string - enum: - - active - - pending - - ended - ConversationHistoryStreamSession: - description: | - UUID of the shared session to stream from. Present only when - `X-Warp-Stream-State` is `active`. - schema: - type: string - format: uuid - ConversationHistoryStreamCursor: - description: | - Opaque logical cursor describing where the returned history - ends; pass it verbatim as `?cursor=` on the first connect to - the session-sharing event stream. Present only when - `X-Warp-Stream-State` is `active`. At most 512 bytes. - schema: - type: string - maxLength: 512 - ConversationHistoryRunId: - description: | - The run this conversation is served through: the run whose - execution owns the stream when `X-Warp-Stream-State` is - `active`, else the newest run for the conversation. Absent - when no run references the conversation. The - conversation-keyed steering routes act on this same run. - schema: - type: string responses: - FactoryBranchConflict: - description: | - Classified conflict with reason branch_sync_pending, branch_head_moved, - factory_source_changed, branch_deleted, or factory_scope_unavailable. - Pending synchronization, moving heads, and source changes are retryable; - deleted or unavailable identity is not. - content: - application/problem+json: - schema: - $ref: '#/components/schemas/Error' - Unauthorized: - description: Authentication required - content: - application/problem+json: - schema: - $ref: '#/components/schemas/Error' - FactoryBranchNotFound: - description: Hidden Factory, unknown or cross-Factory tracking, or disabled Branch surface - content: - application/problem+json: - schema: - $ref: '#/components/schemas/Error' - FactoryBranchStatusResponse: - description: Current observation of the tracked Branch - headers: - Cache-Control: - schema: - type: string - enum: - - no-store - content: - application/json: - schema: - $ref: '#/components/schemas/FactoryBranchStatus' - FactoryBranchUnavailable: - description: Retryable resource_unavailable for source, synchronization, or database failure + FactoryAccessDenied: + description: Factory access is not enabled for the authenticated principal content: application/problem+json: schema: @@ -5587,55 +5676,46 @@ components: application/problem+json: schema: $ref: '#/components/schemas/Error' - FactoryAccessDenied: - description: Factory access is not enabled for the authenticated principal - content: - application/problem+json: - schema: - $ref: '#/components/schemas/Error' schemas: EgressRangesResponse: type: object required: - - cidrs + - cidrs properties: cidrs: type: array items: type: string - description: Canonical, deduplicated IPv4 and IPv6 network ranges. + description: 'Canonical, deduplicated IPv4 and IPv6 network ranges.' FactoryFileSchemaRegistry: type: object description: The Factory file schema versions a server can describe. required: - - current_version - - versions + - current_version + - versions properties: current_version: type: string description: The version a new Factory tree should declare. - examples: - - v1alpha1 + example: v1alpha1 versions: type: array - description: Every supported version, sorted by schema version. + description: 'Every supported version, sorted by schema version.' items: $ref: '#/components/schemas/FactoryFileSchemaVersionRef' FactoryFileSchemaVersionRef: type: object required: - - schema_version - - schema_url + - schema_version + - schema_url properties: schema_version: type: string - examples: - - v1alpha1 + example: v1alpha1 schema_url: type: string description: Root-relative path of this version's schema bundle. - examples: - - /api/v1/factory-files/schemas/v1alpha1 + example: /api/v1/factory-files/schemas/v1alpha1 FactoryFileSchemaBundle: type: object description: | @@ -5643,40 +5723,39 @@ components: The envelope is plain JSON; each value in `documents` is a JSON Schema 2020-12 document keyed by its `$id`. required: - - schema_version - - documents + - schema_version + - documents properties: schema_version: type: string - examples: - - v1alpha1 + example: v1alpha1 documents: type: object - description: Schema documents keyed by file name, which is also each document's $id. + description: 'Schema documents keyed by file name, which is also each document''s $id.' additionalProperties: description: A JSON Schema 2020-12 document. Factory: type: object description: Public representation of a factory. required: - - uid - - team_uid - - name - - description - - alias - - avatar_url - - code_forge - - code_forges - - repositories - - default_environment - - default_model - - scoring - - credential_strategy - - integrations - - agent_defaults - - scorer_defaults - - created_at - - updated_at + - uid + - team_uid + - name + - description + - alias + - avatar_url + - code_forge + - code_forges + - repositories + - default_environment + - default_model + - scoring + - credential_strategy + - integrations + - agent_defaults + - scorer_defaults + - created_at + - updated_at properties: uid: type: string @@ -5688,21 +5767,18 @@ components: type: string description: Display name of the factory. description: - type: - - string - - 'null' + type: string + nullable: true description: Optional description of the factory. alias: - type: - - string - - 'null' + type: string + nullable: true description: | Optional display handle for the factory, unique across the team's Warp workspace when set. avatar_url: - type: - - string - - 'null' + type: string + nullable: true description: | Short-lived signed URL for displaying the factory's avatar. The URL may change between reads. @@ -5719,18 +5795,16 @@ components: type: array items: $ref: '#/components/schemas/FactoryRepository' - description: Repositories scoped to the factory, independent of its default environment. + description: 'Repositories scoped to the factory, independent of its default environment.' default_environment: - type: - - string - - 'null' + type: string + nullable: true description: | Public UID of the factory's default environment. File-managed factories may omit this default. default_model: - type: - - string - - 'null' + 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 @@ -5739,27 +5813,26 @@ components: $ref: '#/components/schemas/FactoryScoringConfig' self_improvement: allOf: - - $ref: '#/components/schemas/FactorySelfImprovementConfig' + - $ref: '#/components/schemas/FactorySelfImprovementConfig' readOnly: true - description: Self-improvement settings from the Factory YAML. Omitted when none are declared, in which case `self_improvement_defaults` apply. + description: 'Self-improvement settings from the Factory YAML. Omitted when none are declared, in which case `self_improvement_defaults` apply.' self_improvement_defaults: allOf: - - $ref: '#/components/schemas/FactorySelfImprovementDefaults' + - $ref: '#/components/schemas/FactorySelfImprovementDefaults' readOnly: true description: Server defaults applied to self-improvement settings the Factory does not declare. credential_strategy: allOf: - - $ref: '#/components/schemas/FactoryCredentialStrategy' + - $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 - - 'null' + 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 @@ -5771,7 +5844,7 @@ components: $ref: '#/components/schemas/FactoryScorerDefaults' creator: allOf: - - $ref: '#/components/schemas/FactoryCreator' + - $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 @@ -5787,32 +5860,31 @@ components: description: Time the factory was last updated. FactoryCreator: type: object - description: The user who created a factory, when resolvable. + description: 'The user who created a factory, when resolvable.' required: - - uid + - uid properties: uid: type: string description: Firebase UID of the user who created the factory. email: - type: - - string - - 'null' - description: Creator's email, when available. + 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 + - default_runner_uid + - secrets + - mcp_servers + - worker_host properties: harness: allOf: - - $ref: '#/components/schemas/Harness' + - $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 @@ -5820,7 +5892,7 @@ components: also reported in the factory's default_model. harness_auth_secrets: allOf: - - $ref: '#/components/schemas/HarnessAuthSecrets' + - $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 @@ -5879,11 +5951,11 @@ components: reviewer_type: type: string enum: - - none - - admins - - team - - custom - description: Owning-team pool from which one eligible reviewer is randomly selected for self-improvement pull requests and Factory reviews in GitHub-managed or Warp-managed Factories. `admins` requests a team admin or owner. `team` requests any team member. `custom` requests a member listed in `reviewer_emails`. `none` explicitly disables reviewer assignment. Omitted when the Factory declares no pool, in which case `self_improvement_defaults.reviewer_type` applies. + - none + - admins + - team + - custom + description: 'Owning-team pool from which one eligible reviewer is randomly selected for self-improvement pull requests and Factory reviews in GitHub-managed or Warp-managed Factories. `admins` requests a team admin or owner. `team` requests any team member. `custom` requests a member listed in `reviewer_emails`. `none` explicitly disables reviewer assignment. Omitted when the Factory declares no pool, in which case `self_improvement_defaults.reviewer_type` applies.' failed_run_threshold: type: integer minimum: 1 @@ -5897,20 +5969,20 @@ components: description: 'Owning-team member emails reviewers are chosen from. Only allowed when `reviewer_type` is `custom`: a Factory YAML change that sets emails with any other reviewer type fails validation, including the pull request check.' model: type: string - description: The model self-improvement runs use, as a model ID or custom model router key. Falls back to `self_improvement_defaults.model` when not provided. + description: 'The model self-improvement runs use, as a model ID or custom model router key. Falls back to `self_improvement_defaults.model` when not provided.' FactorySelfImprovementDefaults: type: object required: - - failed_run_threshold - - reviewer_type - - model + - failed_run_threshold + - reviewer_type + - model properties: reviewer_type: type: string enum: - - none - - admins - - team + - none + - admins + - team description: Reviewer pool used when the Factory declares no `reviewer_type`. model: type: string @@ -5923,12 +5995,11 @@ components: FactoryScoringConfig: type: object required: - - default_model + - default_model properties: default_model: - type: - - string - - 'null' + 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 @@ -5939,43 +6010,43 @@ components: description: | An integration provider attached to a factory. required: - - type + - type properties: type: $ref: '#/components/schemas/FactoryIntegrationProvider' linear: - oneOf: - - $ref: '#/components/schemas/FactoryLinearIntegrationSettings' - - type: 'null' + allOf: + - $ref: '#/components/schemas/FactoryLinearIntegrationSettings' + nullable: true description: | Linear team IDs from earlier integration selections, when present. Issue discovery follows enabled agent-session automations instead. jira: - oneOf: - - $ref: '#/components/schemas/FactoryJiraIntegrationSettings' - - type: 'null' + allOf: + - $ref: '#/components/schemas/FactoryJiraIntegrationSettings' + nullable: true description: | Jira project keys from earlier integration selections, when present. Issue discovery follows enabled agent-session automations instead. slack: - oneOf: - - $ref: '#/components/schemas/FactorySlackIntegrationSettings' - - type: 'null' + allOf: + - $ref: '#/components/schemas/FactorySlackIntegrationSettings' + nullable: true description: | Persisted Slack settings. Present only when type is slack and the factory has declared at least one Slack setting. Omitted fields keep their default-on behavior. microsoft-teams: - oneOf: - - $ref: '#/components/schemas/FactoryTeamsIntegrationSettings' - - type: 'null' + allOf: + - $ref: '#/components/schemas/FactoryTeamsIntegrationSettings' + nullable: true description: | Persisted Teams reply settings. Valid only when type is microsoft-teams. Omitted settings remain undeclared. FactoryLinearIntegrationSettings: type: object required: - - team_ids + - team_ids properties: team_ids: type: array @@ -5993,11 +6064,11 @@ components: Persisted Slack settings on a factory integration. Omitted fields keep their default-on behavior. allOf: - - $ref: '#/components/schemas/FactoryThreadReplySettings' + - $ref: '#/components/schemas/FactoryThreadReplySettings' FactoryTeamsIntegrationSettings: description: Persisted Teams reply settings on a factory integration. allOf: - - $ref: '#/components/schemas/FactoryThreadReplySettings' + - $ref: '#/components/schemas/FactoryThreadReplySettings' FactoryThreadReplySettings: type: object description: | @@ -6005,9 +6076,8 @@ components: per-Factory reply-setting rollout is enabled. properties: auto_respond_to_thread_replies: - type: - - boolean - - 'null' + type: boolean + nullable: true description: | When true, eligible plain channel thread replies still reach the reply-intent classifier. When false, those replies are ignored @@ -6016,7 +6086,7 @@ components: FactoryJiraIntegrationSettings: type: object required: - - project_keys + - project_keys properties: project_keys: type: array @@ -6036,10 +6106,10 @@ components: 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 - - microsoft-teams - - slack + - jira + - linear + - microsoft-teams + - slack FactoryCodeForge: type: string description: | @@ -6048,17 +6118,17 @@ components: forges. AZURE_DEVOPS identifies Azure Repos. NONE declares a repo-less factory with no native repositories; its environment relies on setup_commands to clone from any host. enum: - - GITHUB - - GITLAB - - AZURE_DEVOPS - - NONE + - GITHUB + - GITLAB + - AZURE_DEVOPS + - NONE FactoryRepositoryCodeForge: type: string description: The concrete source-control provider hosting a repository. enum: - - GITHUB - - GITLAB - - AZURE_DEVOPS + - GITHUB + - GITLAB + - AZURE_DEVOPS FactoryCredentialStrategy: type: string description: | @@ -6070,14 +6140,14 @@ components: - CREATOR: runs authenticate with the credentials of the principal that created the run. enum: - - CREATOR - - EXECUTOR + - CREATOR + - EXECUTOR FactoryRepository: type: object description: A repository scoped to a factory. required: - - owner - - repo + - owner + - repo properties: owner: type: string @@ -6087,7 +6157,7 @@ components: description: Repository name. code_forge: allOf: - - $ref: '#/components/schemas/FactoryRepositoryCodeForge' + - $ref: '#/components/schemas/FactoryRepositoryCodeForge' description: | The concrete forge hosting this repository. Omitted means the factory's primary code_forge. @@ -6095,7 +6165,7 @@ components: type: object additionalProperties: type: string - description: Provider-specific repository identity and settings, such as the Azure DevOps organization, project ID, and repository ID. + description: 'Provider-specific repository identity and settings, such as the Azure DevOps organization, project ID, and repository ID.' FactoryTaskStage: type: string description: | @@ -6106,12 +6176,12 @@ components: the task's current top-level run is cancelled, regardless of that run's agent type. enum: - - TRIAGE - - SPEC - - IMPLEMENT - - REVIEW - - COMPLETE - - CANCELLED + - TRIAGE + - SPEC + - IMPLEMENT + - REVIEW + - COMPLETE + - CANCELLED FactoryTaskCurrentRun: type: object description: | @@ -6119,9 +6189,9 @@ components: conversation at read time. This differs from FactoryTask.run_id, which is a creation-time provenance snapshot and is never updated. required: - - run_id - - state - - is_run_type_cancellable + - run_id + - state + - is_run_type_cancellable properties: run_id: type: string @@ -6139,22 +6209,15 @@ components: A factory task: the unit of work in a factory, bound to the agent conversation that owns it. required: - - uid - - factory_uid - - conversation_id - - run_id - - title - - stage - - created_at - - updated_at + - uid + - factory_uid + - conversation_id + - run_id + - title + - stage + - created_at + - updated_at properties: - config_source: - allOf: - - $ref: '#/components/schemas/FactoryConfigSource' - description: | - Derived from the immutable stored creation run_id, never the - conversation's latest run. Omitted when any required association - has been purged or provenance is otherwise unavailable. uid: type: string description: Public UID of the task. @@ -6173,7 +6236,7 @@ components: resolve it via the conversation. author: allOf: - - $ref: '#/components/schemas/RunCreatorInfo' + - $ref: '#/components/schemas/RunCreatorInfo' description: | Creator of the run captured by run_id. Omitted when the creation run or its creator principal can no longer be resolved. @@ -6191,9 +6254,8 @@ components: Canonical ticket ID from the bound run. Present on list responses only when full_list=true and ticket metadata exists. description: - type: - - string - - 'null' + type: string + nullable: true description: Optional description of the task. stage: $ref: '#/components/schemas/FactoryTaskStage' @@ -6223,18 +6285,203 @@ components: only, not the wider run tree. current_run: allOf: - - $ref: '#/components/schemas/FactoryTaskCurrentRun' + - $ref: '#/components/schemas/FactoryTaskCurrentRun' description: | The task's current top-level run, resolved at read time. Present on single-task reads (by uid, by conversation, and after a stop request), and on list responses when include_current_run=true; omitted when no current root run can be resolved. + FactoryTaskNotificationKind: + type: string + description: The action requested by a Factory notification. + enum: + - question + - answer_question + - spec_review + - pr_review + - blocked + - failed + FactoryInboxScope: + type: string + description: Personal or team-wide Factory Inbox visibility. + enum: + - mine + - team + default: mine + FactoryInboxRecipient: + type: object + description: Minimal public identity for a live notification recipient. + required: + - uid + properties: + uid: + type: string + description: Public Warp user UID. + email: + type: string + format: email + description: 'Recipient email, when available.' + FactoryAttentionQuestion: + type: object + required: + - id + - question + - type + - options + properties: + id: + type: string + question: + type: string + type: + type: string + enum: + - single_select + - multi_select + options: + type: array + items: + type: string + recommended_option_index: + type: integer + FactoryInboxArtifact: + type: object + description: An inbox artifact link with an optional provider PR/MR title. + required: + - url + properties: + url: + type: string + description: Artifact URL. + title: + type: string + description: 'Known provider PR/MR title, when available.' + FactoryInboxItem: + type: object + description: One shared unresolved notification in the Factory Inbox. + required: + - notification_uid + - factory_uid + - factory_task_uid + - title + - stage + - kind + - created_at + - recipients + properties: + notification_uid: + type: string + description: Identifier accepted by the dismiss endpoint. + factory_uid: + type: string + factory_task_uid: + type: string + title: + type: string + description: Notification headline. + stage: + $ref: '#/components/schemas/FactoryTaskStage' + kind: + allOf: + - $ref: '#/components/schemas/FactoryTaskNotificationKind' + is_read: + type: boolean + description: | + Whether the authenticated user has read this notification. + Always present in `mine` scope, including when false. + Omitted in `team` scope, even when filtering by recipient. + description: + type: string + description: 'Notification body, when present.' + questions: + type: array + items: + $ref: '#/components/schemas/FactoryAttentionQuestion' + origin_link: + type: string + description: 'Server-derived link back to the task''s origin, when present.' + url: + type: string + description: Legacy first artifact URL supplied by a review notification. + urls: + type: array + minItems: 1 + maxItems: 20 + items: + type: string + description: Legacy artifact URLs; prefer artifacts for links and titles. + artifacts: + type: array + items: + $ref: '#/components/schemas/FactoryInboxArtifact' + description: Ordered artifact links with optional provider PR/MR titles. + run_id: + type: string + minLength: 1 + description: | + Producing run ID from factory_task_notifications.created_by_run_id. + Present when the producing run is known. + created_at: + type: string + format: date-time + description: Notification declaration time. + recipients: + type: array + items: + $ref: '#/components/schemas/FactoryInboxRecipient' + description: | + Live, undismissed recipients for this shared notification, sorted + deterministically. Slack routing and personal dismissal state are + not exposed. + ListFactoryInboxResponse: + type: object + required: + - items + - page_info + properties: + items: + type: array + items: + $ref: '#/components/schemas/FactoryInboxItem' + page_info: + $ref: '#/components/schemas/PageInfo' + FactoryInboxMutationRequest: + type: object + required: + - notification_uids + properties: + notification_uids: + type: array + minItems: 1 + maxItems: 10000 + uniqueItems: true + items: + type: string + FactoryInboxMutationOutcome: + type: object + required: + - notification_uid + - ok + properties: + notification_uid: + type: string + ok: + type: boolean + FactoryInboxMutationResponse: + type: object + required: + - outcomes + properties: + outcomes: + type: array + items: + $ref: '#/components/schemas/FactoryInboxMutationOutcome' FactoryTaskCreateRequest: type: object description: Request body for creating a factory task. required: - - title - - conversation_id + - title + - conversation_id properties: title: type: string @@ -6245,12 +6492,10 @@ components: UUID of the agent conversation to bind the task to. The conversation's most recent run must be owned by the factory's team, and the conversation must not already be bound to a live - task. Confirmed Branch scope must belong to the requested - Factory. Binding cannot grant execution scope. + task. description: - type: - - string - - 'null' + type: string + nullable: true description: Optional description of the task. stage: $ref: '#/components/schemas/FactoryTaskStage' @@ -6264,23 +6509,22 @@ components: type: string description: Updated title. Must be non-empty when provided. description: - type: - - string - - 'null' + type: string + nullable: true description: Updated description. null or an empty string clears the description. stage: $ref: '#/components/schemas/FactoryTaskStage' ListFactoryTasksResponse: type: object required: - - tasks - - page_info + - tasks + - page_info properties: tasks: type: array items: $ref: '#/components/schemas/FactoryTask' - description: One page of the factory's tasks, in the requested sort order. + description: 'One page of the factory''s tasks, in the requested sort order.' page_info: $ref: '#/components/schemas/PageInfo' FactoryMetricsGroupByPeriod: @@ -6289,9 +6533,9 @@ components: Binning granularity for factory metrics series. Weeks start on Sunday (UTC), consistent with existing Warp analytics. enum: - - day - - week - - month + - day + - week + - month FactoryDollarsBreakdown: type: object description: | @@ -6302,10 +6546,10 @@ components: amount; charges recorded before billed amounts were tracked fall back to an estimated cost. required: - - compute - - platform - - inference - - total + - compute + - platform + - inference + - total properties: compute: type: number @@ -6325,10 +6569,10 @@ components: Per-period dollar series aligned to period_list, zero-filled for periods with no attributed cost. required: - - compute - - platform - - inference - - total + - compute + - platform + - inference + - total properties: compute: type: array @@ -6357,7 +6601,7 @@ components: per-period series when group_by_period was requested. Grouped breakdowns (drill-down) may be added as new fields in the future. required: - - total + - total properties: total: type: integer @@ -6377,7 +6621,7 @@ components: plus a per-period series when group_by_period was requested. The aggregate and periods with no qualifying PRs read zero. required: - - average + - average properties: average: type: number @@ -6393,14 +6637,14 @@ components: format: double FactoryCostPerPRSeries: type: object - description: Per-period cost-per-PR series, aligned to period_list. + description: 'Per-period cost-per-PR series, aligned to period_list.' required: - - pr_count - - dollars - - mean - - compute_mean - - platform_mean - - inference_mean + - pr_count + - dollars + - mean + - compute_mean + - platform_mean + - inference_mean properties: pr_count: type: array @@ -6416,40 +6660,36 @@ components: Mean per-PR attributed cost per period, in US dollars; null for periods with zero PRs. items: - type: - - number - - 'null' + type: number format: double + nullable: true compute_mean: type: array description: | Mean per-PR compute cost per period, in US dollars; null for periods with zero PRs. items: - type: - - number - - 'null' + type: number format: double + nullable: true platform_mean: type: array description: | Mean per-PR platform cost per period, in US dollars; null for periods with zero PRs. items: - type: - - number - - 'null' + type: number format: double + nullable: true inference_mean: type: array description: | Mean per-PR inference cost per period, in US dollars; null for periods with zero PRs. items: - type: - - number - - 'null' + type: number format: double + nullable: true FactoryCostPerPRMetric: type: object description: | @@ -6458,9 +6698,9 @@ components: never double-counted), reported as the arithmetic mean of the per-PR costs. required: - - pr_count - - dollars - - mean + - pr_count + - dollars + - mean properties: pr_count: type: integer @@ -6472,10 +6712,9 @@ components: dollars: $ref: '#/components/schemas/FactoryDollarsBreakdown' mean: - type: - - number - - 'null' + type: number format: double + nullable: true description: | Mean per-PR attributed cost, in US dollars; null when pr_count is 0. @@ -6483,23 +6722,23 @@ components: $ref: '#/components/schemas/FactoryCostPerPRSeries' FactoryCostPerPRResponse: allOf: - - $ref: '#/components/schemas/FactoryMetricsEnvelope' - - type: object - required: - - data - properties: - group_by_period: - $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' - period_list: - type: array - description: | - Period labels every series aligns to (dates like 2026-07-01; - weeks labeled by their Sunday start date). Present only when - group_by_period was requested. - items: - type: string - data: - $ref: '#/components/schemas/FactoryCostPerPRMetric' + - $ref: '#/components/schemas/FactoryMetricsEnvelope' + - type: object + required: + - data + properties: + group_by_period: + $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' + period_list: + type: array + description: | + Period labels every series aligns to (dates like 2026-07-01; + weeks labeled by their Sunday start date). Present only when + group_by_period was requested. + items: + type: string + data: + $ref: '#/components/schemas/FactoryCostPerPRMetric' FactoryCostBreakdownGroupBy: type: string description: | @@ -6507,10 +6746,10 @@ components: roll each run tree's cost to the root run; agent and model keep each run's own cost. enum: - - source - - user - - agent - - model + - source + - user + - agent + - model FactoryCostBreakdownGroup: type: object description: | @@ -6522,9 +6761,9 @@ components: entity behind a User or Agent key has been soft-deleted since incurring the spend; always false for Source/Model and UNKNOWN. required: - - key - - deleted - - dollars + - key + - deleted + - dollars properties: key: type: string @@ -6539,7 +6778,7 @@ components: $ref: '#/components/schemas/FactoryDollarsBreakdown' series: allOf: - - $ref: '#/components/schemas/FactoryDollarsBreakdownSeries' + - $ref: '#/components/schemas/FactoryDollarsBreakdownSeries' description: | One entry per period_list entry, zero-filled. Present only when group_by_period was requested. @@ -6550,8 +6789,8 @@ components: ascending on ties) with UNKNOWN always last. The server never caps or folds groups — every entity with nonzero spend is listed. required: - - total - - groups + - total + - groups properties: total: $ref: '#/components/schemas/FactoryDollarsBreakdown' @@ -6561,36 +6800,36 @@ components: $ref: '#/components/schemas/FactoryCostBreakdownGroup' FactoryCostBreakdownResponse: allOf: - - $ref: '#/components/schemas/FactoryMetricsEnvelope' - - type: object - required: - - group_by - - data - properties: - group_by: - $ref: '#/components/schemas/FactoryCostBreakdownGroupBy' - group_by_period: - $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' - period_list: - type: array - description: | - Period labels every series aligns to (dates like 2026-07-01; - weeks labeled by their Sunday start date). Present only when - group_by_period was requested. - items: - type: string - data: - $ref: '#/components/schemas/FactoryCostBreakdownData' + - $ref: '#/components/schemas/FactoryMetricsEnvelope' + - type: object + required: + - group_by + - data + properties: + group_by: + $ref: '#/components/schemas/FactoryCostBreakdownGroupBy' + group_by_period: + $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' + period_list: + type: array + description: | + Period labels every series aligns to (dates like 2026-07-01; + weeks labeled by their Sunday start date). Present only when + group_by_period was requested. + items: + type: string + data: + $ref: '#/components/schemas/FactoryCostBreakdownData' FactoryMetricsData: type: object required: - - run_count - - pr_count - - merged_pr_count - - autonomy_funnel - - impact - - pr_latency - - average_human_interactions_per_pr + - run_count + - pr_count + - merged_pr_count + - autonomy_funnel + - impact + - pr_latency + - average_human_interactions_per_pr properties: run_count: $ref: '#/components/schemas/FactoryMetricCount' @@ -6598,7 +6837,7 @@ components: $ref: '#/components/schemas/FactoryMetricCount' merged_pr_count: allOf: - - $ref: '#/components/schemas/FactoryMetricCount' + - $ref: '#/components/schemas/FactoryMetricCount' description: | Merged PRs, bucketed by the day the PR was created (merge day when the creation time was never observed) so the series reads @@ -6615,7 +6854,7 @@ components: $ref: '#/components/schemas/FactoryPRLatency' average_human_interactions_per_pr: allOf: - - $ref: '#/components/schemas/FactoryAverageMetric' + - $ref: '#/components/schemas/FactoryAverageMetric' description: | Average qualifying human interactions per factory-attributed PR in the range. The numerator includes live PR interactions with a @@ -6638,11 +6877,11 @@ components: observed (factory_merged_observed); sourced from webhook-collected PR facts, so coverage starts when collection began. required: - - total_merged - - factory_merged - - factory_merged_observed - - merged_without_human_code_change - - repos + - total_merged + - factory_merged + - factory_merged_observed + - merged_without_human_code_change + - repos properties: total_merged: type: integer @@ -6685,10 +6924,10 @@ components: webhook payloads and can be unobserved, so additions/deletions sum only the measured_pr_count PRs where both were recorded. required: - - additions - - deletions - - merged_pr_count - - measured_pr_count + - additions + - deletions + - merged_pr_count + - measured_pr_count properties: additions: type: integer @@ -6715,14 +6954,13 @@ components: PRs where both of the stage's endpoints were observed, plus how many PRs that was. required: - - median_seconds - - measured_pr_count + - median_seconds + - measured_pr_count properties: median_seconds: - type: - - number - - 'null' + type: number format: double + nullable: true description: | p50 stage duration in seconds; null when measured_pr_count is zero. Durations are clamped at zero, so out-of-order provider @@ -6746,11 +6984,11 @@ components: PRs where both endpoints were observed, so stage medians do not sum to kickoff_to_merge's median. required: - - merged_pr_count - - kickoff_to_pr - - pr_to_first_review - - first_review_to_merge - - kickoff_to_merge + - merged_pr_count + - kickoff_to_pr + - pr_to_first_review + - first_review_to_merge + - kickoff_to_merge properties: merged_pr_count: type: integer @@ -6758,28 +6996,28 @@ components: description: PRs produced by this factory's runs and merged in the range. kickoff_to_pr: allOf: - - $ref: '#/components/schemas/FactoryLatencyStage' + - $ref: '#/components/schemas/FactoryLatencyStage' description: Run kickoff to PR creation. pr_to_first_review: allOf: - - $ref: '#/components/schemas/FactoryLatencyStage' + - $ref: '#/components/schemas/FactoryLatencyStage' description: PR creation to the first observed human review. first_review_to_merge: allOf: - - $ref: '#/components/schemas/FactoryLatencyStage' + - $ref: '#/components/schemas/FactoryLatencyStage' description: First observed human review to merge. kickoff_to_merge: allOf: - - $ref: '#/components/schemas/FactoryLatencyStage' - description: Run kickoff to merge, measured end to end per PR. + - $ref: '#/components/schemas/FactoryLatencyStage' + description: 'Run kickoff to merge, measured end to end per PR.' FactoryPullRequestState: type: string description: The pull request's current state. enum: - - open - - draft - - merged - - closed + - open + - draft + - merged + - closed FactoryPullRequestHumanInteractions: type: object description: | @@ -6792,16 +7030,16 @@ components: GitHub comment counts once, as a PR comment or review. total is the sum of every type. required: - - opened - - code_push - - review_approved - - review_changes_requested - - review_commented - - comment - - review_comment - - pr_action - - follow_up_message - - total + - opened + - code_push + - review_approved + - review_changes_requested + - review_commented + - comment + - review_comment + - pr_action + - follow_up_message + - total properties: opened: type: integer @@ -6837,7 +7075,7 @@ components: pr_action: type: integer format: int64 - description: Other PR actions by a person, such as closed, reopened, or marked ready. + description: 'Other PR actions by a person, such as closed, reopened, or marked ready.' follow_up_message: type: integer format: int64 @@ -6850,9 +7088,9 @@ components: type: object description: One of the factory's runs that produced the pull request. required: - - run_id - - root_run_id - - created_at + - run_id + - root_run_id + - created_at properties: run_id: type: string @@ -6870,61 +7108,57 @@ components: Kickoff is when the earliest run that produced the PR was created; first review is the first review by a person. required: - - kickoff_to_pr - - pr_to_first_review - - first_review_to_merge - - kickoff_to_merge + - kickoff_to_pr + - pr_to_first_review + - first_review_to_merge + - kickoff_to_merge properties: kickoff_to_pr: - type: - - number - - 'null' + type: number format: double + nullable: true pr_to_first_review: - type: - - number - - 'null' + type: number format: double + nullable: true first_review_to_merge: - type: - - number - - 'null' + type: number format: double + nullable: true kickoff_to_merge: - type: - - number - - 'null' + type: number format: double + nullable: true FactoryPullRequest: type: object description: | One pull request produced by the factory's runs. Fields the code host has not reported yet (title, size counts, times) are null. required: - - provider - - repo_full_name - - pr_number - - url - - title - - author_login - - factory_uid - - team_uid - - state - - opened_at - - first_human_review_at - - merged_at - - closed_at - - updated_at - - additions - - deletions - - changed_files - - num_commits - - human_interactions - - human_code_change - - history_complete - - runs - - kickoff_at - - cycle_time + - provider + - repo_full_name + - pr_number + - url + - title + - author_login + - factory_uid + - team_uid + - state + - opened_at + - first_human_review_at + - merged_at + - closed_at + - updated_at + - additions + - deletions + - changed_files + - num_commits + - human_interactions + - human_code_change + - history_complete + - runs + - kickoff_at + - cycle_time properties: provider: $ref: '#/components/schemas/FactoryRepositoryCodeForge' @@ -6938,14 +7172,12 @@ components: type: string description: Canonical PR URL. title: - type: - - string - - 'null' + type: string + nullable: true description: The PR title; null until the code host reports it. author_login: - type: - - string - - 'null' + type: string + nullable: true description: The code-host login that opened the PR. factory_uid: type: string @@ -6956,52 +7188,44 @@ components: state: $ref: '#/components/schemas/FactoryPullRequestState' opened_at: - type: - - string - - 'null' + type: string format: date-time + nullable: true description: When the PR was opened; null when Warp did not see it being opened. first_human_review_at: - type: - - string - - 'null' + type: string format: date-time + nullable: true description: The first review by a person; null when none was observed. merged_at: - type: - - string - - 'null' + type: string format: date-time + nullable: true description: When the PR was merged; null while it is not merged. closed_at: - type: - - string - - 'null' + type: string format: date-time - description: When the PR was closed, by merging or otherwise; null while it is open or when the code host did not report it. + nullable: true + description: 'When the PR was closed, by merging or otherwise; null while it is open or when the code host did not report it.' updated_at: type: string format: date-time description: When the PR itself last changed; the updated_after filter compares against it. additions: - type: - - integer - - 'null' + type: integer + nullable: true description: Lines added; null until the code host reports it. deletions: - type: - - integer - - 'null' + type: integer + nullable: true description: Lines deleted; null until the code host reports it. changed_files: - type: - - integer - - 'null' + type: integer + nullable: true description: Files changed; null until the code host reports it. num_commits: - type: - - integer - - 'null' + type: integer + nullable: true description: Commits on the PR; null until the code host reports it. human_interactions: $ref: '#/components/schemas/FactoryPullRequestHumanInteractions' @@ -7019,32 +7243,31 @@ components: missing from the counts. runs: type: array - description: The factory's runs that produced the PR, earliest first. + description: 'The factory''s runs that produced the PR, earliest first.' items: $ref: '#/components/schemas/FactoryPullRequestRun' kickoff_at: - type: - - string - - 'null' + type: string format: date-time + nullable: true description: When the earliest run that produced the PR was created. cycle_time: $ref: '#/components/schemas/FactoryPullRequestCycleTime' FactoryPullRequestsResponse: allOf: - - $ref: '#/components/schemas/FactoryMetricsEnvelope' - - type: object - required: - - data - - page_info - properties: - data: - type: array - description: Newest opened first. - items: - $ref: '#/components/schemas/FactoryPullRequest' - page_info: - $ref: '#/components/schemas/PageInfo' + - $ref: '#/components/schemas/FactoryMetricsEnvelope' + - type: object + required: + - data + - page_info + properties: + data: + type: array + description: Newest opened first. + items: + $ref: '#/components/schemas/FactoryPullRequest' + page_info: + $ref: '#/components/schemas/PageInfo' FactoryTopPR: type: object description: | @@ -7054,9 +7277,9 @@ components: PR has been deleted; the remaining fields are null when the PR predates webhook PR-fact collection. required: - - url - - dollars - - models + - url + - dollars + - models properties: url: type: string @@ -7064,21 +7287,19 @@ components: dollars: $ref: '#/components/schemas/FactoryDollarsBreakdown' creator: - oneOf: - - $ref: '#/components/schemas/RunCreatorInfo' - - type: 'null' + allOf: + - $ref: '#/components/schemas/RunCreatorInfo' + nullable: true description: Who started the run that kicked off the PR. source: - type: - - string - - 'null' + type: string + nullable: true description: | Public source name of the run that kicked off the PR (e.g. GITHUB_WEBHOOK, SLACK, API). New values may appear over time. requested_model_id: - type: - - string - - 'null' + type: string + nullable: true description: | Model the kicking-off run was configured with; null means the server default was used. @@ -7094,140 +7315,121 @@ components: items: $ref: '#/components/schemas/FactoryTopPRModel' provider: - oneOf: - - $ref: '#/components/schemas/FactoryRepositoryCodeForge' - - type: 'null' + allOf: + - $ref: '#/components/schemas/FactoryRepositoryCodeForge' + nullable: true description: The code host the PR lives on. repo_full_name: - type: - - string - - 'null' + type: string + nullable: true description: The repository as owner/repo. pr_number: - type: - - integer - - 'null' + type: integer + nullable: true description: The provider's PR number. title: - type: - - string - - 'null' + type: string + nullable: true description: The PR title; null until the code host reports it. author_login: - type: - - string - - 'null' + type: string + nullable: true description: The code-host login that opened the PR. factory_uid: - type: - - string - - 'null' + type: string + nullable: true description: Public UID of the factory whose runs produced the PR. team_uid: - type: - - string - - 'null' + type: string + nullable: true description: Public UID of the team that owns the factory. state: - oneOf: - - $ref: '#/components/schemas/FactoryPullRequestState' - - type: 'null' + allOf: + - $ref: '#/components/schemas/FactoryPullRequestState' + nullable: true description: The PR's current state. opened_at: - type: - - string - - 'null' + type: string format: date-time + nullable: true description: When the PR was opened; null when Warp did not see it being opened. first_human_review_at: - type: - - string - - 'null' + type: string format: date-time + nullable: true description: The first review by a person; null when none was observed. merged_at: - type: - - string - - 'null' + type: string format: date-time + nullable: true description: When the PR was merged; null while it is not merged. closed_at: - type: - - string - - 'null' + type: string format: date-time - description: When the PR was closed, by merging or otherwise; null while it is open or when the code host did not report it. + nullable: true + description: 'When the PR was closed, by merging or otherwise; null while it is open or when the code host did not report it.' updated_at: - type: - - string - - 'null' + type: string format: date-time + nullable: true description: When the PR itself last changed. additions: - type: - - integer - - 'null' + type: integer + nullable: true description: Lines added; null until the code host reports it. deletions: - type: - - integer - - 'null' + type: integer + nullable: true description: Lines deleted; null until the code host reports it. changed_files: - type: - - integer - - 'null' + type: integer + nullable: true description: Files changed; null until the code host reports it. num_commits: - type: - - integer - - 'null' + type: integer + nullable: true description: Commits on the PR; null until the code host reports it. human_interactions: - oneOf: - - $ref: '#/components/schemas/FactoryPullRequestHumanInteractions' - - type: 'null' - description: Actions people took on the PR, counted by type. + allOf: + - $ref: '#/components/schemas/FactoryPullRequestHumanInteractions' + nullable: true + description: 'Actions people took on the PR, counted by type.' human_code_change: - type: - - boolean - - 'null' + type: boolean + nullable: true description: | Whether a person changed the PR's code: any opened or code_push interaction. False only means autonomous when history_complete is true. history_complete: - type: - - boolean - - 'null' + type: boolean + nullable: true description: | Whether Warp observed the PR from the moment it was opened. When false, interactions before Warp started watching the PR are missing from the counts. runs: - type: - - array - - 'null' - description: The factory's runs that produced the PR, earliest first. + type: array + nullable: true + description: 'The factory''s runs that produced the PR, earliest first.' items: $ref: '#/components/schemas/FactoryPullRequestRun' kickoff_at: - type: - - string - - 'null' + type: string format: date-time + nullable: true description: When the earliest run that produced the PR was created. cycle_time: - oneOf: - - $ref: '#/components/schemas/FactoryPullRequestCycleTime' - - type: 'null' + allOf: + - $ref: '#/components/schemas/FactoryPullRequestCycleTime' + nullable: true description: The PR's pipeline-stage durations in seconds. FactoryTopPRModel: type: object description: One model's share of a top PR's inference cost. required: - - model_id - - inference_dollars + - model_id + - inference_dollars properties: model_id: type: string @@ -7240,16 +7442,16 @@ components: attribution. FactoryTopPRsResponse: allOf: - - $ref: '#/components/schemas/FactoryMetricsEnvelope' - - type: object - required: - - data - properties: - data: - type: array - description: Most expensive first. - items: - $ref: '#/components/schemas/FactoryTopPR' + - $ref: '#/components/schemas/FactoryMetricsEnvelope' + - type: object + required: + - data + properties: + data: + type: array + description: Most expensive first. + items: + $ref: '#/components/schemas/FactoryTopPR' FactoryMetricsEnvelope: type: object description: | @@ -7257,9 +7459,9 @@ components: data, so responses from several factories can be combined or told apart. required: - - as_of - - team_uid - - factory_uid + - as_of + - team_uid + - factory_uid properties: as_of: type: string @@ -7275,23 +7477,23 @@ components: description: Public UID of the factory the response is scoped to. FactoryMetricsResponse: allOf: - - $ref: '#/components/schemas/FactoryMetricsEnvelope' - - type: object - required: - - data - properties: - group_by_period: - $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' - period_list: - type: array - description: | - Period labels every series aligns to (dates like 2026-07-01; - weeks labeled by their Sunday start date). Present only when - group_by_period was requested. - items: - type: string - data: - $ref: '#/components/schemas/FactoryMetricsData' + - $ref: '#/components/schemas/FactoryMetricsEnvelope' + - type: object + required: + - data + properties: + group_by_period: + $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' + period_list: + type: array + description: | + Period labels every series aligns to (dates like 2026-07-01; + weeks labeled by their Sunday start date). Present only when + group_by_period was requested. + items: + type: string + data: + $ref: '#/components/schemas/FactoryMetricsData' FactoryRunBreakdownGroupBy: type: string description: | @@ -7299,12 +7501,12 @@ components: top-level runs only; every other dimension counts subruns individually. enum: - - agent_type - - status - - source - - root_vs_subrun - - model - - harness + - agent_type + - status + - source + - root_vs_subrun + - model + - harness FactoryRunBreakdownGroup: type: object description: | @@ -7316,8 +7518,8 @@ components: names, source aliases) and is absent where the key is already the display form. required: - - key - - total + - key + - total properties: key: type: string @@ -7342,9 +7544,9 @@ components: then OTHER; group totals and series sum to total and its per-period distribution. required: - - total - - root_run_count - - groups + - total + - root_run_count + - groups properties: total: type: integer @@ -7370,36 +7572,36 @@ components: $ref: '#/components/schemas/FactoryRunBreakdownGroup' FactoryRunBreakdownResponse: allOf: - - $ref: '#/components/schemas/FactoryMetricsEnvelope' - - type: object - required: - - group_by - - data - properties: - group_by: - $ref: '#/components/schemas/FactoryRunBreakdownGroupBy' - group_by_period: - $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' - period_list: - type: array - description: | - Period labels every series aligns to (dates like 2026-07-01; - weeks labeled by their Sunday start date). Present only when - group_by_period was requested. - items: - type: string - data: - $ref: '#/components/schemas/FactoryRunBreakdownData' + - $ref: '#/components/schemas/FactoryMetricsEnvelope' + - type: object + required: + - group_by + - data + properties: + group_by: + $ref: '#/components/schemas/FactoryRunBreakdownGroupBy' + group_by_period: + $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' + period_list: + type: array + description: | + Period labels every series aligns to (dates like 2026-07-01; + weeks labeled by their Sunday start date). Present only when + group_by_period was requested. + items: + type: string + data: + $ref: '#/components/schemas/FactoryRunBreakdownData' FactoryPRSizeBucket: type: string description: | A PR's T-shirt size, derived from its webhook-collected line counts (additions + deletions): S < 100, M < 500, L < 1000, XL >= 1000. enum: - - S - - M - - L - - XL + - S + - M + - L + - XL FactoryCostByPRSizeBucket: type: object description: | @@ -7407,9 +7609,9 @@ components: cost_per_pr attribution (even run-tree split, in the US dollars the owning team was billed). required: - - size - - pr_count - - mean + - size + - pr_count + - mean properties: size: $ref: '#/components/schemas/FactoryPRSizeBucket' @@ -7418,10 +7620,9 @@ components: format: int64 description: Sized PRs in this bucket first seen in the range. mean: - type: - - number - - 'null' + type: number format: double + nullable: true description: | Mean per-PR attributed cost in US dollars; null when the bucket has no PRs in the range. @@ -7432,10 +7633,9 @@ components: for periods where the bucket has no PRs. Present only when group_by_period was requested. items: - type: - - number - - 'null' + type: number format: double + nullable: true FactoryCostByPRSizeData: type: object description: | @@ -7445,14 +7645,14 @@ components: difference is the PRs whose line counts were never observed and are excluded from every bucket. required: - - pr_count - - sized_pr_count - - buckets + - pr_count + - sized_pr_count + - buckets properties: pr_count: type: integer format: int64 - description: Every PR first seen in the range, sized or not. + description: 'Every PR first seen in the range, sized or not.' sized_pr_count: type: integer format: int64 @@ -7463,89 +7663,29 @@ components: $ref: '#/components/schemas/FactoryCostByPRSizeBucket' FactoryCostByPRSizeResponse: allOf: - - $ref: '#/components/schemas/FactoryMetricsEnvelope' - - type: object - required: - - data - properties: - group_by_period: - $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' - period_list: - type: array - description: | - Period labels every series aligns to (dates like 2026-07-01; - weeks labeled by their Sunday start date). Present only when - group_by_period was requested. - items: - type: string - data: - $ref: '#/components/schemas/FactoryCostByPRSizeData' - FactorySyncItem: - type: object - description: A single factory sync history/status row. - required: - - id - - factory_uid - - target_sha - - trigger - - status - - created_at - - updated_at - properties: - id: - type: integer - description: Internal sync row ID. - factory_uid: - type: string - description: Public UID of the factory. - target_sha: - type: string - description: Target commit SHA for the sync attempt. - trigger: - type: string - description: What initiated the sync attempt. - enum: - - webhook - - explicit_apply - - anti_entropy - - source_link - status: - $ref: '#/components/schemas/FactorySyncItemStatus' - plan_summary: - type: - - string - - 'null' - description: Optional human-readable plan summary for the sync. - diagnostics: - type: string - description: | - Raw persisted structured diagnostics JSON for the sync attempt - (parse errors, dependency failures, etc.). Empty when the sync - had no diagnostics. This POC field carries the persisted JSON - string verbatim; a future revision may replace it with a - structured schema. - created_at: - type: string - format: date-time - description: Time the sync row was created. - updated_at: - type: string - format: date-time - description: Time the sync row was last updated. - FactorySyncItemStatus: - type: string - description: Outcome of a sync attempt. - enum: - - running - - success - - failed - - noop + - $ref: '#/components/schemas/FactoryMetricsEnvelope' + - type: object + required: + - data + properties: + group_by_period: + $ref: '#/components/schemas/FactoryMetricsGroupByPeriod' + period_list: + type: array + description: | + Period labels every series aligns to (dates like 2026-07-01; + weeks labeled by their Sunday start date). Present only when + group_by_period was requested. + items: + type: string + data: + $ref: '#/components/schemas/FactoryCostByPRSizeData' ListFactoriesResponse: type: object description: Response body for listing factories. required: - - factories - - page_info + - factories + - page_info properties: factories: type: array @@ -7557,18 +7697,8 @@ components: type: object description: Request body for dispatching a run to a factory. required: - - prompt + - prompt properties: - branch: - type: string - nullable: true - description: | - Exact named head in the registered source repository, optionally - prefixed with refs/heads/. Case and slashes are preserved. - Omission, null, or the registered production branch uses - production. Empty strings, revision expressions, tags, forks, - and alternate repository coordinates are not accepted. - Non-production selection is rejected when factory_branches is off. prompt: type: string description: | @@ -7594,15 +7724,12 @@ components: type: object description: Response body for a dispatched factory run. required: - - run_id - - state - - factory_uid - - foreman_agent - - ticket_ref + - run_id + - state + - factory_uid + - foreman_agent + - ticket_ref properties: - config_source: - allOf: - - $ref: '#/components/schemas/FactoryConfigSource' run_id: type: string description: Unique identifier for the dispatched run. @@ -7625,97 +7752,6 @@ components: The canonical : ticket reference the run was stamped with, either the caller-supplied ticket_ref or a minted adhoc reference. - FactoryConfigSource: - type: object - description: | - Branch namespace and registered source-generation identity derived - from the run's execution Agent and required root/Branch associations. - Omitted for production or unavailable provenance; omission does not - establish production scope. No historical configuration revision or - retention guarantee is provided. - required: - - branch - - branch_uid - - source_generation - properties: - branch: - type: string - minLength: 1 - description: Case-sensitive named head, without refs/heads/. - branch_uid: - type: string - minLength: 1 - description: Immutable tracking namespace UID. - source_generation: - type: string - minLength: 1 - description: Fingerprint of the registered source generation. - FactoryBranchState: - type: string - enum: - - UNSYNCED - - SYNCING - - FRESH - - STALE - - FAILED - - UNKNOWN - - DELETED - FactoryBranchStatus: - type: object - description: | - Read-only observation of an existing Branch. UNKNOWN means the - current source could not be verified, never permission to execute. - Lifecycle SHA fields describe current synchronization, not a run's - historical creation revision. - required: - - uid - - factory_uid - - branch - - source_generation - - state - - last_success_sha - - current_head_sha - - last_synced_at - - latest_attempt - - freshness_checked_at - - last_error - properties: - uid: - type: string - factory_uid: - type: string - branch: - type: string - source_generation: - type: string - state: - $ref: '#/components/schemas/FactoryBranchState' - last_success_sha: - type: - - string - - 'null' - current_head_sha: - type: - - string - - 'null' - last_synced_at: - type: - - string - - 'null' - format: date-time - latest_attempt: - oneOf: - - $ref: '#/components/schemas/FactorySyncItem' - - type: 'null' - description: Latest persisted attempt with externally safe diagnostics. - freshness_checked_at: - type: string - format: date-time - last_error: - oneOf: - - $ref: '#/components/schemas/Error' - - type: 'null' - description: Classified, externally safe source-verification failure. ClaudeHarnessUsagePayload: type: object additionalProperties: false @@ -7723,9 +7759,8 @@ components: usage: $ref: '#/components/schemas/ClaudeTokenUsage' attribution: - type: - - array - - 'null' + type: array + nullable: true items: $ref: '#/components/schemas/ClaudeAttributedUsage' toolCalls: @@ -7737,26 +7772,23 @@ components: usage: $ref: '#/components/schemas/CodexTokenUsage' attribution: - type: - - array - - 'null' + type: array + nullable: true items: $ref: '#/components/schemas/CodexAttributedUsage' toolCalls: $ref: '#/components/schemas/HarnessToolCalls' HarnessUsageCounter: - type: - - integer - - 'null' + type: integer format: int64 minimum: 0 maximum: 9223372036854775807 - description: A native count. Absent or null means unmeasured, not zero. + nullable: true + description: 'A native count. Absent or null means unmeasured, not zero.' ClaudeTokenUsage: - type: - - object - - 'null' + type: object additionalProperties: false + nullable: true description: Native cumulative token categories; cache counters are not added to input_tokens. properties: input_tokens: @@ -7770,20 +7802,18 @@ components: cache_creation: $ref: '#/components/schemas/ClaudeCacheCreationUsage' ClaudeCacheCreationUsage: - type: - - object - - 'null' + type: object additionalProperties: false + nullable: true properties: ephemeral_5m_input_tokens: $ref: '#/components/schemas/HarnessUsageCounter' ephemeral_1h_input_tokens: $ref: '#/components/schemas/HarnessUsageCounter' CodexTokenUsage: - type: - - object - - 'null' + type: object additionalProperties: false + nullable: true description: Native checkpoint counters. Cached input and reasoning output may overlap other categories; no derived total is inferred. properties: input_tokens: @@ -7802,58 +7832,49 @@ components: type: object additionalProperties: false required: - - usage + - usage properties: model: - type: - - string - - 'null' + type: string + nullable: true service_tier: - type: - - string - - 'null' + type: string + nullable: true inference_geo: - type: - - string - - 'null' + type: string + nullable: true speed: - type: - - string - - 'null' + type: string + nullable: true usage: $ref: '#/components/schemas/ClaudeTokenUsage' CodexAttributedUsage: type: object additionalProperties: false required: - - usage + - usage properties: model: - type: - - string - - 'null' + type: string + nullable: true service_tier: - type: - - string - - 'null' + type: string + nullable: true inference_geo: - type: - - string - - 'null' + type: string + nullable: true speed: - type: - - string - - 'null' + type: string + nullable: true usage: $ref: '#/components/schemas/CodexTokenUsage' HarnessToolCalls: - type: - - object - - 'null' + type: object additionalProperties: false + nullable: true required: - - total - - byName + - total + - byName description: Native tool invocation counts. Total must equal the sum of byName; tool names are arbitrary map keys. properties: total: @@ -7871,9 +7892,9 @@ components: GetRunHarnessUsageResponse: type: object required: - - run_id - - conversation_id - - available + - run_id + - conversation_id + - available properties: run_id: type: string @@ -7882,16 +7903,15 @@ components: available: type: boolean age_seconds: - type: - - integer - - 'null' + type: integer format: int64 + nullable: true usage: $ref: '#/components/schemas/HarnessUsageEnvelope' HarnessUsageEnvelope: oneOf: - - $ref: '#/components/schemas/ClaudeHarnessUsageEnvelope' - - $ref: '#/components/schemas/CodexHarnessUsageEnvelope' + - $ref: '#/components/schemas/ClaudeHarnessUsageEnvelope' + - $ref: '#/components/schemas/CodexHarnessUsageEnvelope' discriminator: propertyName: harness mapping: @@ -7901,22 +7921,22 @@ components: type: object additionalProperties: false required: - - metricsVersion - - harness - - executionId - - captureSequence - - capturedAt - - snapshot + - metricsVersion + - harness + - executionId + - captureSequence + - capturedAt + - snapshot properties: metricsVersion: type: integer enum: - - 1 - description: Server-owned storage format metadata, not the producer's parser version. + - 1 + description: 'Server-owned storage format metadata, not the producer''s parser version.' harness: type: string enum: - - CLAUDE_CODE + - CLAUDE_CODE executionId: type: integer format: int64 @@ -7930,8 +7950,8 @@ components: type: object additionalProperties: false required: - - coverage - - payload + - coverage + - payload properties: coverage: $ref: '#/components/schemas/RetainedHarnessUsageCoverage' @@ -7941,22 +7961,22 @@ components: type: object additionalProperties: false required: - - metricsVersion - - harness - - executionId - - captureSequence - - capturedAt - - snapshot + - metricsVersion + - harness + - executionId + - captureSequence + - capturedAt + - snapshot properties: metricsVersion: type: integer enum: - - 1 - description: Server-owned storage format metadata, not the producer's parser version. + - 1 + description: 'Server-owned storage format metadata, not the producer''s parser version.' harness: type: string enum: - - CODEX + - CODEX executionId: type: integer format: int64 @@ -7970,8 +7990,8 @@ components: type: object additionalProperties: false required: - - coverage - - payload + - coverage + - payload properties: coverage: $ref: '#/components/schemas/RetainedHarnessUsageCoverage' @@ -7981,21 +8001,21 @@ components: type: object additionalProperties: false required: - - tokenStatus - - toolStatus + - tokenStatus + - toolStatus properties: tokenStatus: type: string enum: - - known - - partial - - unavailable + - known + - partial + - unavailable toolStatus: type: string enum: - - known - - partial - - unavailable + - known + - partial + - unavailable RunAgentRequest: type: object description: | @@ -8094,9 +8114,9 @@ components: RunAgentResponse: type: object required: - - run_id - - task_id - - state + - run_id + - task_id + - state properties: run_id: type: string @@ -8118,17 +8138,17 @@ components: - 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 + - normal + - plan + - orchestrate default: normal ListRunsResponse: type: object required: - - runs - - page_info - - as_of - - team_uid + - runs + - page_info + - as_of + - team_uid properties: runs: type: array @@ -8141,9 +8161,8 @@ components: format: date-time description: Time the runs were read (RFC3339). Data can lag live activity by a few minutes. team_uid: - type: - - string - - 'null' + type: string + nullable: true description: | UID of the team the request was scoped to: the team selected by the `X-Warp-Team-Uid` header, or the API key's team. Null when a user @@ -8152,15 +8171,15 @@ components: RunItem: type: object required: - - run_id - - task_id - - title - - state - - prompt - - created_at - - finished_at - - updated_at - - root_run_id + - run_id + - task_id + - title + - state + - prompt + - created_at + - finished_at + - updated_at + - root_run_id properties: run_id: type: string @@ -8181,7 +8200,7 @@ components: description: The prompt/instruction for the agent submitted_prompt: type: string - description: The prompt exactly as it was submitted, without any extra context added by Warp. Includes any follow-up messages sent before the run started, separated by blank lines. + description: 'The prompt exactly as it was submitted, without any extra context added by Warp. Includes any follow-up messages sent before the run started, separated by blank lines.' created_at: type: string format: date-time @@ -8193,18 +8212,16 @@ components: run_time: type: string format: duration - description: Total runtime as an ISO 8601 duration (e.g. "PT2M30S"), computed server-side from run executions. + description: 'Total runtime as an ISO 8601 duration (e.g. "PT2M30S"), computed server-side from run executions.' started_at: - type: - - string - - 'null' + type: string format: date-time + nullable: true description: Timestamp when the agent started working on the run (RFC3339) finished_at: - type: - - string - - 'null' + type: string format: date-time + nullable: true description: | Timestamp when the run last reached a terminal state (RFC3339). Null while the run is still active, and for terminal runs with no @@ -8226,7 +8243,7 @@ components: trigger_url: type: string format: uri - description: URL to the run trigger (e.g. Slack thread, Linear issue, schedule) + description: 'URL to the run trigger (e.g. Slack thread, Linear issue, schedule)' creator: $ref: '#/components/schemas/RunCreatorInfo' executor: @@ -8273,7 +8290,7 @@ components: type: array items: $ref: '#/components/schemas/ArtifactItem' - description: Artifacts created during the run (plans, pull requests, etc.) + description: 'Artifacts created during the run (plans, pull requests, etc.)' agent_skill: $ref: '#/components/schemas/AgentSkill' scope: @@ -8282,7 +8299,7 @@ components: type: object description: Response body for listing run timeline events. required: - - events + - events properties: events: type: array @@ -8292,10 +8309,10 @@ components: type: object description: A setup or lifecycle event recorded for an agent run. required: - - event_uuid - - run_id - - event_type - - occurred_at + - event_uuid + - run_id + - event_type + - occurred_at properties: event_uuid: type: string @@ -8306,7 +8323,7 @@ components: execution_id: type: integer format: int64 - description: Run execution associated with this event, when available. + description: 'Run execution associated with this event, when available.' event_type: $ref: '#/components/schemas/AIRunTimelineEventType' occurred_at: @@ -8321,23 +8338,23 @@ components: type: string description: Type of timeline event recorded for a run. enum: - - oz_run_created - - oz_run_claimed - - worker_container_ready - - shared_session_started - - agent_started - - oz_run_done - - oz_run_blocked - - oz_run_cancelled - - oz_run_failed - - oz_run_errored - - vm_shutdown - - run_retry_scheduled + - oz_run_created + - oz_run_claimed + - worker_container_ready + - shared_session_started + - agent_started + - oz_run_done + - oz_run_blocked + - oz_run_cancelled + - oz_run_failed + - oz_run_errored + - vm_shutdown + - run_retry_scheduled ConversationResponse: type: object required: - - conversation_id - - steps + - conversation_id + - steps properties: conversation_id: type: string @@ -8350,9 +8367,9 @@ components: ConversationStep: type: object required: - - id - - messages - - steps + - id + - messages + - steps properties: id: type: string @@ -8384,8 +8401,8 @@ components: ConversationMessage: type: object required: - - role - - content + - role + - content properties: message_ids: type: array @@ -8394,7 +8411,7 @@ components: type: string request_id: type: string - description: Request identifier shared by transcript messages from the same request, when available + description: 'Request identifier shared by transcript messages from the same request, when available' role: $ref: '#/components/schemas/ConversationMessageRole' timestamp: @@ -8409,16 +8426,16 @@ components: type: string description: Role of the normalized message enum: - - user - - assistant - - tool - - system + - user + - assistant + - tool + - system ConversationContentBlock: oneOf: - - $ref: '#/components/schemas/TextContentBlock' - - $ref: '#/components/schemas/ActionContentBlock' - - $ref: '#/components/schemas/ActionResultContentBlock' - - $ref: '#/components/schemas/EventContentBlock' + - $ref: '#/components/schemas/TextContentBlock' + - $ref: '#/components/schemas/ActionContentBlock' + - $ref: '#/components/schemas/ActionResultContentBlock' + - $ref: '#/components/schemas/EventContentBlock' discriminator: propertyName: type mapping: @@ -8429,16 +8446,16 @@ components: TextContentBlock: type: object required: - - type - - text + - type + - text properties: type: type: string enum: - - text + - text message_id: type: string - description: Underlying transcript message ID that produced this content block, when available + description: 'Underlying transcript message ID that produced this content block, when available' text: type: string description: Plain text content @@ -8446,38 +8463,38 @@ components: type: string description: High-level category of an action performed during the conversation enum: - - command - - files - - search - - integration - - documents - - computer - - review - - skill + - command + - files + - search + - integration + - documents + - computer + - review + - skill ActionState: type: string description: State of an action result enum: - - running - - completed - - failed - - denied + - running + - completed + - failed + - denied ActionContentBlock: type: object required: - - type - - id - - category - - name - - input + - type + - id + - category + - name + - input properties: type: type: string enum: - - action + - action message_id: type: string - description: Underlying transcript message ID that produced this content block, when available + description: 'Underlying transcript message ID that produced this content block, when available' id: type: string description: Unique identifier for the action @@ -8485,7 +8502,7 @@ components: $ref: '#/components/schemas/ActionCategory' name: type: string - description: Public action name, such as run_command or edit_files + description: 'Public action name, such as run_command or edit_files' input: type: object additionalProperties: true @@ -8493,20 +8510,20 @@ components: ActionResultContentBlock: type: object required: - - type - - action_id - - category - - name - - state - - output + - type + - action_id + - category + - name + - state + - output properties: type: type: string enum: - - action_result + - action_result message_id: type: string - description: Underlying transcript message ID that produced this content block, when available + description: 'Underlying transcript message ID that produced this content block, when available' action_id: type: string description: Identifier of the corresponding action @@ -8524,17 +8541,17 @@ components: EventContentBlock: type: object required: - - type - - name - - data + - type + - name + - data properties: type: type: string enum: - - event + - event message_id: type: string - description: Underlying transcript message ID that produced this content block, when available + 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 @@ -8544,11 +8561,11 @@ components: 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' + - $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: @@ -8560,14 +8577,14 @@ components: ExternalReferenceArtifact: type: object required: - - artifact_type - - created_at - - data + - artifact_type + - created_at + - data properties: artifact_type: type: string enum: - - EXTERNAL_REFERENCE + - EXTERNAL_REFERENCE description: Type of the artifact created_at: type: string @@ -8578,14 +8595,14 @@ components: PlanArtifact: type: object required: - - artifact_type - - created_at - - data + - artifact_type + - created_at + - data properties: artifact_type: type: string enum: - - PLAN + - PLAN description: Type of the artifact created_at: type: string @@ -8596,14 +8613,14 @@ components: PullRequestArtifact: type: object required: - - artifact_type - - created_at - - data + - artifact_type + - created_at + - data properties: artifact_type: type: string enum: - - PULL_REQUEST + - PULL_REQUEST description: Type of the artifact created_at: type: string @@ -8614,14 +8631,14 @@ components: ScreenshotArtifact: type: object required: - - artifact_type - - created_at - - data + - artifact_type + - created_at + - data properties: artifact_type: type: string enum: - - SCREENSHOT + - SCREENSHOT description: Type of the artifact created_at: type: string @@ -8632,14 +8649,14 @@ components: FileArtifact: type: object required: - - artifact_type - - created_at - - data + - artifact_type + - created_at + - data properties: artifact_type: type: string enum: - - FILE + - FILE description: Type of the artifact created_at: type: string @@ -8650,11 +8667,11 @@ components: PlanArtifactData: type: object required: - - document_uid + - document_uid properties: artifact_uid: type: string - description: Unique identifier for the plan artifact, usable with the artifact retrieval endpoint + description: 'Unique identifier for the plan artifact, usable with the artifact retrieval endpoint' document_uid: type: string description: Unique identifier for the plan document @@ -8671,8 +8688,8 @@ components: PullRequestArtifactData: type: object required: - - url - - branch + - url + - branch properties: url: type: string @@ -8683,29 +8700,29 @@ components: description: Branch name for the pull request PullRequestArtifactResponseData: allOf: - - $ref: '#/components/schemas/PullRequestArtifactData' - - type: object - required: - - status - properties: - status: - type: string - description: | - Current state of the pull request as last reported by the code - host's webhooks. `unknown` means Warp has no live provider - record for this pull request (for example, the repository's - code host integration is not connected to the run's team). - enum: - - open - - draft - - merged - - closed - - unknown + - $ref: '#/components/schemas/PullRequestArtifactData' + - type: object + required: + - status + properties: + status: + type: string + description: | + Current state of the pull request as last reported by the code + host's webhooks. `unknown` means Warp has no live provider + record for this pull request (for example, the repository's + code host integration is not connected to the run's team). + enum: + - open + - draft + - merged + - closed + - unknown ScreenshotArtifactData: type: object required: - - artifact_uid - - mime_type + - artifact_uid + - mime_type properties: artifact_uid: type: string @@ -8719,10 +8736,10 @@ components: FileArtifactData: type: object required: - - artifact_uid - - filepath - - filename - - mime_type + - artifact_uid + - filepath + - filename + - mime_type properties: artifact_uid: type: string @@ -8755,21 +8772,25 @@ components: $ref: '#/components/schemas/FileArtifactThumbnail' FileArtifactThumbnail: type: object - description: The companion thumbnail image of a video recording. required: - - download_url + - download_url + - expires_at properties: download_url: type: string format: uri - description: Stable URL of the thumbnail image. Requires authentication. + description: Time-limited signed URL to download the video's thumbnail image + expires_at: + type: string + format: date-time + description: Timestamp when the thumbnail download URL expires (RFC3339) ScheduleInfo: type: object description: Information about the schedule that triggered this run (only present for scheduled runs) required: - - schedule_id - - schedule_name - - cron_schedule + - schedule_id + - schedule_name + - cron_schedule properties: schedule_id: type: string @@ -8783,7 +8804,7 @@ components: PageInfo: type: object required: - - has_next_page + - has_next_page properties: has_next_page: type: boolean @@ -8797,7 +8818,7 @@ components: Status message for a run. For terminal error states, includes structured error code and retryability info from the platform error catalog. required: - - message + - message properties: message: type: string @@ -8891,9 +8912,9 @@ components: description: | Tokens consumed by a single model over a run. required: - - model_id - - total_tokens - - usage_type + - model_id + - total_tokens + - usage_type properties: model_id: type: string @@ -8905,7 +8926,7 @@ components: total_tokens: type: integer format: int64 - description: Total tokens this model consumed, across every usage category. + description: 'Total tokens this model consumed, across every usage category.' usage_type: $ref: '#/components/schemas/ModelUsageType' tokens_by_category: @@ -8924,44 +8945,44 @@ components: - byok: through the caller's own provider API key - custom_endpoint: through a caller-configured model endpoint enum: - - warp - - byok - - custom_endpoint + - warp + - byok + - custom_endpoint InferenceCostBreakdownInCents: type: object description: | Charged cost of LLM inference in US cents, split by token type. Omitted when the data is not available. required: - - input_cost_in_cents - - input_cache_read_cost_in_cents - - input_cache_write_cost_in_cents - - output_cost_in_cents + - input_cost_in_cents + - input_cache_read_cost_in_cents + - input_cache_write_cost_in_cents + - output_cost_in_cents properties: input_cost_in_cents: type: number format: double - description: Cost of non-cached input tokens, in US cents. + description: 'Cost of non-cached input tokens, in US cents.' input_cache_read_cost_in_cents: type: number format: double - description: Cost of cache-read input tokens, in US cents. + description: 'Cost of cache-read input tokens, in US cents.' input_cache_write_cost_in_cents: type: number format: double - description: Cost of cache-write input tokens, in US cents. + description: 'Cost of cache-write input tokens, in US cents.' output_cost_in_cents: type: number format: double - description: Cost of output tokens, in US cents. + description: 'Cost of output tokens, in US cents.' TokenCountBreakdown: type: object description: A per-token-type token count. required: - - input - - output - - input_cache_read - - input_cache_write + - input + - output + - input_cache_read + - input_cache_write properties: input: type: integer @@ -8986,10 +9007,10 @@ components: The counts and cost describe the same usage (e.g. token_count.input tokens cost cost_in_cents.input_cost_in_cents in total). required: - - token_count - - cost_in_cents - - web_search_count - - web_search_cost_in_cents + - token_count + - cost_in_cents + - web_search_count + - web_search_cost_in_cents properties: token_count: $ref: '#/components/schemas/TokenCountBreakdown' @@ -9002,42 +9023,25 @@ components: web_search_cost_in_cents: type: number format: double - description: Total cost of those web searches, in US cents. - web_fetch_page_count: - type: integer - format: int64 - description: | - Recorded web pages requested by native web-fetch calls - web_fetch_cost_in_cents: - type: number - format: double - description: | - Total cost of recorded requested web-fetch pages, in US cents. - web_fetch_cost_in_credits: - type: number - format: double - description: | - Cost of recorded requested web-fetch pages, in the run owner's credits. - Omitted for customer-paid inference, unrecorded costs, or an unavailable credit rate. + description: 'Total cost of those web searches, in US cents.' ChargedUsageDetail: type: object description: | Usage charged for a single usage category, broken down by usage type (direct API/BYOK/custom endpoint) and, within each, by model ID. required: - - platform_usage_in_cents - - platform_usage_duration_seconds + - platform_usage_in_cents properties: direct_api_inference_usage: type: object additionalProperties: $ref: '#/components/schemas/InferenceUsageDetail' - description: Inference usage incurred through Warp-provided model access, keyed by model ID. + 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. + description: 'Inference usage charged using a user''s own API key, keyed by model ID.' custom_endpoint_inference_usage: type: object additionalProperties: @@ -9048,22 +9052,15 @@ components: platform_usage_in_cents: type: number format: double - description: Platform usage charged for this category, in US cents. - platform_usage_duration_seconds: - type: number - format: double - minimum: 0 - description: | - Cumulative billable agent runtime for this category, in seconds, - across the conversation's turns. Zero when no runtime was recorded. + description: 'Platform usage charged for this category, in US cents.' RunCreatorInfo: type: object properties: type: type: string enum: - - user - - service_account + - user + - service_account description: Type of the creator principal uid: type: string @@ -9081,15 +9078,15 @@ components: RunState: type: string enum: - - QUEUED - - PENDING - - CLAIMED - - INPROGRESS - - SUCCEEDED - - FAILED - - BLOCKED - - ERROR - - CANCELLED + - QUEUED + - PENDING + - CLAIMED + - INPROGRESS + - SUCCEEDED + - FAILED + - BLOCKED + - ERROR + - CANCELLED description: | Current state of the run: - QUEUED: Run is waiting to be picked up @@ -9104,29 +9101,29 @@ components: RunSourceType: type: string enum: - - LINEAR - - API - - MCP - - SLACK - - TEAMS - - LOCAL - - SCHEDULED_AGENT - - WEB_APP - - GITHUB_ACTION - - CLOUD_MODE - - CLI - - JIRA - - SELF_IMPROVEMENT - - GITHUB_WEBHOOK - - GITLAB_WEBHOOK - - AZURE_DEVOPS_WEBHOOK - - AUTOFIX - - RUN_SCORER - - ORCHESTRATION - - BENCHMARK_TRIAL - - CREATE_BENCHMARK_TASK - - CUSTOM_WEBHOOK - description: |- + - LINEAR + - API + - MCP + - SLACK + - TEAMS + - LOCAL + - SCHEDULED_AGENT + - WEB_APP + - GITHUB_ACTION + - CLOUD_MODE + - CLI + - JIRA + - SELF_IMPROVEMENT + - GITHUB_WEBHOOK + - GITLAB_WEBHOOK + - AZURE_DEVOPS_WEBHOOK + - AUTOFIX + - RUN_SCORER + - ORCHESTRATION + - BENCHMARK_TRIAL + - CREATE_BENCHMARK_TASK + - CUSTOM_WEBHOOK + description: | Source that created the run: - LINEAR: Created from Linear integration - API: Created via the Warp API @@ -9153,8 +9150,8 @@ components: RunExecutionLocation: type: string enum: - - LOCAL - - REMOTE + - LOCAL + - REMOTE description: | Where the run executed: - LOCAL: Executed in the user's local Warp environment @@ -9261,18 +9258,17 @@ components: description: Memory stores to attach to this run. inference_providers: allOf: - - $ref: '#/components/schemas/InferenceProvidersConfig' + - $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: - oneOf: - - type: string - enum: + type: string + nullable: true + enum: - CREATOR - EXECUTOR - - type: 'null' description: | Controls which principal's credentials are used when the platform mints tokens (e.g. GitHub or GitLab OAuth tokens) on @@ -9299,8 +9295,8 @@ components: public_access: type: string enum: - - VIEWER - - EDITOR + - VIEWER + - EDITOR description: | Grants anyone-with-link access at the specified level to the run's shared session and backing conversation; link viewers @@ -9319,15 +9315,18 @@ components: empty, since the two describe mutually exclusive default models. properties: type: - oneOf: - - type: string - enum: + type: string + enum: - oz - description: Warp's built-in harness (default). - - $ref: '#/components/schemas/ExternalHarness' - description: | - The harness type identifier: `oz` for Warp's built-in harness - (default), or any third-party harness. + - 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 description: | @@ -9345,19 +9344,6 @@ components: 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. - ExternalHarness: - type: string - enum: - - claude - - codex - - gemini - - pi - description: | - A third-party harness; every harness other than Warp's built-in `oz`. - - claude: Claude Code - - codex: Codex CLI - - gemini: Gemini CLI - - pi: Pi HarnessAuthSecrets: type: object description: | @@ -9376,14 +9362,6 @@ components: 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". - pi_auth_secret_name: - type: string - description: | - Name of a managed secret for Pi harness authentication. - The secret must exist within the caller's personal or team scope and - must be a credential for the model provider named by the provider - prefix of harness.model_id. - Only applicable when harness type is "pi". MCPServerConfig: type: object description: | @@ -9425,10 +9403,10 @@ components: backward-compatible extension members; additional ones (e.g., `auth_url`, `provider`) may be present depending on the error code. required: - - type - - title - - status - - error + - type + - title + - status + - error properties: type: type: string @@ -9439,7 +9417,7 @@ components: See PlatformErrorCode for the list of possible error codes. title: type: string - description: A short, human-readable summary of the problem type (RFC 7807) + 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) @@ -9465,16 +9443,16 @@ components: description: OpenTelemetry trace ID for debugging and support requests provider: type: string - description: External provider that requires authorization, such as `linear`. + 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' + - $ref: '#/components/schemas/PlanArtifactResponse' + - $ref: '#/components/schemas/ScreenshotArtifactResponse' + - $ref: '#/components/schemas/FileArtifactResponse' discriminator: propertyName: artifact_type mapping: @@ -9485,10 +9463,10 @@ components: type: object description: Response for retrieving a plan artifact. required: - - artifact_uid - - artifact_type - - created_at - - data + - artifact_uid + - artifact_type + - created_at + - data properties: artifact_uid: type: string @@ -9496,7 +9474,7 @@ components: artifact_type: type: string enum: - - PLAN + - PLAN description: Type of the artifact created_at: type: string @@ -9506,12 +9484,12 @@ components: $ref: '#/components/schemas/PlanArtifactResponseData' PlanArtifactResponseData: type: object - description: Response data for a plan artifact, including current markdown content. + description: 'Response data for a plan artifact, including current markdown content.' required: - - document_uid - - notebook_uid - - content - - content_type + - document_uid + - notebook_uid + - content + - content_type properties: document_uid: type: string @@ -9536,10 +9514,10 @@ components: type: object description: Response for retrieving a screenshot artifact. required: - - artifact_uid - - artifact_type - - created_at - - data + - artifact_uid + - artifact_type + - created_at + - data properties: artifact_uid: type: string @@ -9547,7 +9525,7 @@ components: artifact_type: type: string enum: - - SCREENSHOT + - SCREENSHOT description: Type of the artifact created_at: type: string @@ -9564,7 +9542,7 @@ components: run_url: type: string format: uri - description: Factory run page for the originating root run, when bound to a live Factory task. + description: 'Factory run page for the originating root run, when bound to a live Factory task.' pull_request_urls: type: array items: @@ -9573,11 +9551,11 @@ components: description: Distinct pull requests reported by runs in the same tree. ScreenshotArtifactResponseData: type: object - description: Response data for a screenshot artifact, including a signed download URL. + description: 'Response data for a screenshot artifact, including a signed download URL.' required: - - download_url - - expires_at - - content_type + - download_url + - expires_at + - content_type properties: download_url: type: string @@ -9589,7 +9567,7 @@ components: description: Timestamp when the download URL expires (RFC3339) content_type: type: string - description: MIME type of the screenshot (e.g., image/png) + description: 'MIME type of the screenshot (e.g., image/png)' description: type: string description: Optional description of the screenshot @@ -9597,10 +9575,10 @@ components: type: object description: Response for retrieving a file artifact. required: - - artifact_uid - - artifact_type - - created_at - - data + - artifact_uid + - artifact_type + - created_at + - data properties: artifact_uid: type: string @@ -9608,7 +9586,7 @@ components: artifact_type: type: string enum: - - FILE + - FILE description: Type of the artifact created_at: type: string @@ -9620,12 +9598,12 @@ components: $ref: '#/components/schemas/FileArtifactResponseData' FileArtifactResponseData: type: object - description: Response data for a file artifact, including a signed download URL. + description: 'Response data for a file artifact, including a signed download URL.' required: - - download_url - - expires_at - - content_type - - filename + - download_url + - expires_at + - content_type + - filename properties: download_url: type: string @@ -9663,9 +9641,9 @@ components: type: object description: A base64-encoded file attachment to include with the prompt required: - - file_name - - mime_type - - data + - file_name + - mime_type + - data properties: file_name: type: string @@ -9682,13 +9660,13 @@ components: ScheduledAgentItem: type: object required: - - id - - name - - cron_schedule - - enabled - - prompt - - created_at - - updated_at + - id + - name + - cron_schedule + - enabled + - prompt + - created_at + - updated_at properties: id: type: string @@ -9698,7 +9676,7 @@ components: 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) + 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 @@ -9706,10 +9684,9 @@ components: type: string description: The prompt/instruction for the agent to execute last_spawn_error: - type: - - string - - 'null' - description: Error message from the last failed spawn attempt, if any + type: string + nullable: true + description: 'Error message from the last failed spawn attempt, if any' agent_config: $ref: '#/components/schemas/AmbientAgentConfig' agent_uid: @@ -9718,11 +9695,11 @@ components: description: UID of the agent that this schedule runs as metadata: allOf: - - $ref: '#/components/schemas/RunMetadata' + - $ref: '#/components/schemas/RunMetadata' description: Custom metadata stamped onto every run spawned by this schedule environment: allOf: - - $ref: '#/components/schemas/CloudEnvironmentConfig' + - $ref: '#/components/schemas/CloudEnvironmentConfig' description: Resolved environment configuration (if agent_config references an environment_id) created_at: type: string @@ -9745,16 +9722,14 @@ components: description: Scheduler-derived history metadata for a scheduled agent properties: last_ran: - type: - - string - - 'null' + type: string format: date-time + nullable: true description: Timestamp of the last successful run (RFC3339) next_run: - type: - - string - - 'null' + type: string format: date-time + nullable: true description: Timestamp of the next scheduled run (RFC3339) CreateScheduledAgentRequest: type: object @@ -9762,15 +9737,15 @@ components: 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 + - name + - cron_schedule properties: name: type: string description: Human-readable name for the schedule cron_schedule: type: string - description: Cron expression defining when the agent runs (e.g., "0 9 * * *" for daily at 9am UTC) + description: 'Cron expression defining when the agent runs (e.g., "0 9 * * *" for daily at 9am UTC)' prompt: type: string description: | @@ -9801,7 +9776,7 @@ components: Defaults to true for users on a single team. metadata: allOf: - - $ref: '#/components/schemas/RunMetadata' + - $ref: '#/components/schemas/RunMetadata' description: | Custom metadata stamped onto every run spawned by this schedule as the run's explicit metadata layer. @@ -9811,9 +9786,9 @@ components: 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 + - name + - cron_schedule + - enabled properties: name: type: string @@ -9845,7 +9820,7 @@ components: $ref: '#/components/schemas/AmbientAgentConfig' metadata: allOf: - - $ref: '#/components/schemas/RunMetadata' + - $ref: '#/components/schemas/RunMetadata' description: | Custom metadata stamped onto every run spawned by this schedule. Updates follow full-replacement PUT semantics: omitting this field @@ -9853,7 +9828,7 @@ components: ListScheduledAgentsResponse: type: object required: - - schedules + - schedules properties: schedules: type: array @@ -9863,7 +9838,7 @@ components: DeleteScheduledAgentResponse: type: object required: - - success + - success properties: success: type: boolean @@ -9876,13 +9851,12 @@ components: type: string description: Human-readable name for the environment description: - type: - - string - - 'null' + type: string + nullable: true description: Optional description of the environment docker_image: type: string - description: Docker image to use (e.g., "ubuntu:latest" or "registry/repo:tag") + description: 'Docker image to use (e.g., "ubuntu:latest" or "registry/repo:tag")' github_repos: type: array items: @@ -9905,9 +9879,8 @@ components: references are unioned with references from the run config and execution principal. failure_session_retention_minutes: - type: - - integer - - 'null' + type: integer + nullable: true minimum: 1 maximum: 60 description: | @@ -9939,12 +9912,12 @@ components: type: object description: GCP Workload Identity Federation settings required: - - project_number - - workload_identity_federation_pool_id - - workload_identity_federation_provider_id + - 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 + url: 'https://docs.cloud.google.com/iam/docs/workload-identity-federation' properties: project_number: type: string @@ -9963,9 +9936,9 @@ components: 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 + url: 'https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html' required: - - role_arn + - role_arn properties: role_arn: type: string @@ -9977,31 +9950,22 @@ components: 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 + 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. + description: 'If true, opt out of Bedrock at this layer.' role_arn: type: string description: IAM role ARN to assume when calling Bedrock. region: type: string description: AWS region used for STS when assuming the Bedrock inference role. - role_arn_source: - allOf: - - $ref: '#/components/schemas/BedrockSource' - readOnly: true - description: | - Which level supplied `role_arn`. Returned only on a run's - `agent_config`, set when the run is created; absent on agents, on - schedules, and on runs created before this field existed. Ignored - if sent. GitHubRepo: type: object required: - - owner - - repo + - owner + - repo properties: owner: type: string @@ -10012,7 +9976,7 @@ components: ListAgentsResponse: type: object required: - - agents + - agents properties: agents: type: array @@ -10022,7 +9986,7 @@ components: ListConnectedSelfHostedWorkersResponse: type: object required: - - workers + - workers properties: workers: type: array @@ -10032,10 +9996,10 @@ components: ConnectedSelfHostedWorker: type: object required: - - worker_host - - connection_count - - connected_at - - last_seen_at + - worker_host + - connection_count + - connected_at + - last_seen_at properties: worker_host: type: string @@ -10054,8 +10018,8 @@ components: AgentListItem: type: object required: - - name - - variants + - name + - variants properties: name: type: string @@ -10068,11 +10032,11 @@ components: AgentListVariant: type: object required: - - id - - description - - base_prompt - - source - - environments + - id + - description + - base_prompt + - source + - environments properties: id: type: string @@ -10094,10 +10058,9 @@ components: $ref: '#/components/schemas/AgentListEnvironment' description: Environments where this agent variant is available last_run_timestamp: - type: - - string - - 'null' + type: string format: date-time + nullable: true description: Timestamp of the last time this skill was run (RFC3339) error: type: string @@ -10108,9 +10071,9 @@ components: AgentListSource: type: object required: - - owner - - name - - skill_path + - owner + - name + - skill_path properties: owner: type: string @@ -10130,8 +10093,8 @@ components: AgentListEnvironment: type: object required: - - uid - - name + - uid + - name properties: uid: type: string @@ -10143,14 +10106,14 @@ components: type: object description: Ownership scope for a resource (team or personal) required: - - type + - type properties: type: type: string enum: - - User - - Team - description: Type of ownership ("User" for personal, "Team" for team-owned) + - User + - Team + description: 'Type of ownership ("User" for personal, "Team" for team-owned)' uid: type: string description: UID of the owning user or team @@ -10183,32 +10146,24 @@ components: - `agent_stream_failure` — MAA server explicitly reported a terminal response stream failure - `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 - - agent_stream_network_error - - agent_stream_failure - - internal_error - PresignedDownloadResponse: - type: object - required: - - url - properties: - url: - type: string - description: Temporary signed storage URL. Fetch without Warp API headers or credentials. + - insufficient_credits + - feature_not_available + - external_authentication_required + - not_authorized + - invalid_request + - resource_not_found + - budget_exceeded + - integration_disabled + - integration_not_configured + - operation_not_supported + - environment_setup_failed + - content_policy_violation + - conflict + - authentication_required + - resource_unavailable + - agent_stream_network_error + - agent_stream_failure + - internal_error RunFollowupRequest: type: object description: Request body for submitting a follow-up message to an existing run. @@ -10243,7 +10198,7 @@ components: type: object description: A prepared attachment to deliver with a follow-up message. required: - - attachment_id + - attachment_id properties: attachment_id: type: string @@ -10270,21 +10225,20 @@ components: - queue_pending: the message is durably queued and will be delivered once the run can accept it. enum: - - live_session - - queued_prompt - - handoff_execution - - queue_pending + - live_session + - queued_prompt + - handoff_execution + - queue_pending RunFollowupResponse: type: object description: Acknowledgement of an accepted follow-up. required: - - followup_id - - outcome + - followup_id + - outcome properties: followup_id: - type: - - string - - 'null' + type: string + nullable: true description: | Identifier of the durable follow-up record, or null when the outcome did not create one (`queued_prompt`). @@ -10296,14 +10250,13 @@ components: Acknowledgement of a follow-up accepted through a conversation-keyed route: the run-keyed acknowledgement plus the run it was delivered to. required: - - followup_id - - outcome - - run_id + - followup_id + - outcome + - run_id properties: followup_id: - type: - - string - - 'null' + type: string + nullable: true description: | Identifier of the durable follow-up record, or null when the outcome did not create one (`queued_prompt`). @@ -10316,16 +10269,50 @@ components: type: object description: Acknowledgement of an interrupt accepted through a conversation-keyed route. required: - - run_id + - run_id properties: run_id: type: string description: The run whose turn is being interrupted. + HandoffSnapshotAttachmentInfo: + type: object + description: A handoff snapshot attachment exposed for download. + required: + - attachment_id + - filename + - download_url + properties: + attachment_id: + type: string + description: Identifier for the snapshot attachment within the run. + filename: + type: string + description: Original filename of the snapshot attachment. + download_url: + type: string + format: uri + description: Time-limited signed URL to download the snapshot attachment. + mime_type: + type: string + description: 'MIME type of the snapshot attachment, if known.' + ListHandoffSnapshotAttachmentsResponse: + type: object + description: Response body for listing handoff snapshot attachments. + required: + - attachments + properties: + attachments: + type: array + items: + $ref: '#/components/schemas/HandoffSnapshotAttachmentInfo' + description: | + Handoff snapshot attachments exposed by the latest ended execution. + Empty when no ended execution exists or no files were uploaded. ListModelsResponse: type: object required: - - default_model_id - - models + - default_model_id + - models properties: default_model_id: type: string @@ -10338,10 +10325,10 @@ components: ModelInfo: type: object required: - - id - - display_name - - provider - - vision_supported + - id + - display_name + - provider + - vision_supported properties: id: type: string @@ -10350,8 +10337,12 @@ components: type: string description: Human-readable name of the model provider: - allOf: - - $ref: '#/components/schemas/LlmProvider' + type: string + enum: + - OPENAI + - ANTHROPIC + - GOOGLE + - UNKNOWN description: The LLM provider vision_supported: type: boolean @@ -10361,41 +10352,21 @@ components: description: Optional extra descriptor for the model reasoning_level: type: string - description: Reasoning level descriptor, if any (e.g. "low", "medium", "high") + 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 - LlmProvider: - type: string - enum: - - OPENAI - - ANTHROPIC - - GOOGLE - - XAI - - UNKNOWN - description: The LLM provider behind a model. - BedrockSource: - type: string - enum: - - run - - agent - - workspace - description: | - The configuration level that supplied a Bedrock inference role: `run`, - the run's own `config.inference_providers`; `agent`, the agent's - `inference_providers`; `workspace`, the workspace's admin-configured - Bedrock settings. + - PROVIDER_OUTAGE + - OUT_OF_REQUESTS + - ADMIN_DISABLED + - REQUIRES_UPGRADE + description: 'If set, the model is currently unavailable for the given reason' ExternalReferenceArtifactData: type: object description: Data for a generic external reference artifact. required: - - reference_type - - url + - reference_type + - url properties: reference_type: type: string @@ -10420,7 +10391,7 @@ components: type: object description: Response for a run reverse-lookup by external reference URL. required: - - run_id + - run_id properties: run_id: type: string @@ -10446,7 +10417,7 @@ components: ListEnvironmentsResponse: type: object required: - - environments + - environments properties: environments: type: array @@ -10457,10 +10428,10 @@ components: type: object description: A cloud environment for running agents required: - - uid - - config - - last_updated - - setup_failed + - uid + - config + - last_updated + - setup_failed properties: uid: type: string @@ -10472,10 +10443,9 @@ components: format: date-time description: Timestamp when the environment was last updated (RFC3339) last_task_run_timestamp: - type: - - string - - 'null' + 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' @@ -10493,7 +10463,7 @@ components: description: | Reference to a managed secret by name. required: - - name + - name properties: name: type: string @@ -10502,9 +10472,9 @@ components: type: object description: Reference to a memory store to attach to an agent. required: - - uid - - access - - instructions + - uid + - access + - instructions properties: uid: type: string @@ -10512,8 +10482,8 @@ components: access: type: string enum: - - read_write - - read_only + - read_write + - read_only description: Access level for the store. instructions: type: string @@ -10522,11 +10492,11 @@ components: type: object description: Memory store attached to an agent. required: - - uid - - access - - instructions - - owner_type - - owner_uid + - uid + - access + - instructions + - owner_type + - owner_uid properties: uid: type: string @@ -10534,8 +10504,8 @@ components: access: type: string enum: - - read_write - - read_only + - read_write + - read_only description: Access level for the store. instructions: type: string @@ -10544,12 +10514,12 @@ components: type: string description: Public owner type. enum: - - user - - service_account - - team + - user + - service_account + - team owner_uid: type: string - description: Public UID of the user, service account, or team that owns the memory store. + 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. @@ -10568,7 +10538,7 @@ components: properties: auto_memory: allOf: - - $ref: '#/components/schemas/AgentAutoMemoryCreateConfig' + - $ref: '#/components/schemas/AgentAutoMemoryCreateConfig' description: Agent-owned memory settings. Defaults to enabled when omitted. attached_stores: type: array @@ -10582,9 +10552,8 @@ components: description: Memory settings for updating an agent. properties: attached_stores: - type: - - array - - 'null' + type: array + nullable: true items: $ref: '#/components/schemas/MemoryStoreRef' description: | @@ -10594,7 +10563,7 @@ components: type: object description: Auto-memory state for an agent. required: - - enabled + - enabled properties: enabled: type: boolean @@ -10605,8 +10574,8 @@ components: type: object description: Memory settings for an agent. required: - - auto_memory - - attached_stores + - auto_memory + - attached_stores properties: auto_memory: $ref: '#/components/schemas/AgentAutoMemoryResponse' @@ -10626,13 +10595,13 @@ components: - CREATOR: runs authenticate with the credentials of the principal that created the run. enum: - - CREATOR - - EXECUTOR + - CREATOR + - EXECUTOR ScorerClassification: type: object required: - - value - - score + - value + - score properties: value: type: string @@ -10640,9 +10609,8 @@ components: maxLength: 1048576 description: Classification value returned by the scorer description: - type: - - string - - 'null' + type: string + nullable: true maxLength: 1048576 description: | Optional free-text meaning of this classification, surfaced to the @@ -10668,25 +10636,22 @@ components: collections explicitly clear the optional Factory defaults. properties: default_runner_uid: - type: - - string - - 'null' + type: string + nullable: true description: | Runner used by scorer judge runs. Omit or set null to inherit the Factory agent default. secrets: - type: - - array - - 'null' + type: array + nullable: true description: | Managed secrets attached to scorer judge runs. Omit or set null to inherit the Factory agent defaults; an empty array attaches none. items: $ref: '#/components/schemas/SecretRef' mcp_servers: - type: - - object - - 'null' + type: object + nullable: true description: | MCP servers attached to scorer judge runs. Omit or set null to inherit the Factory agent defaults; an empty object attaches none. @@ -10699,12 +10664,12 @@ components: before validation; required text fields must not be blank after trimming, and no text field may exceed 1 MiB (1048576 bytes). required: - - name - - scoring_prompt - - allowed_classifications - - threshold - - scope_mode - - model_id + - name + - scoring_prompt + - allowed_classifications + - threshold + - scope_mode + - model_id properties: factory_uid: type: string @@ -10717,9 +10682,8 @@ components: maxLength: 1048576 description: Display name for the scorer description: - type: - - string - - 'null' + type: string + nullable: true maxLength: 1048576 description: Optional description of the scorer scoring_prompt: @@ -10745,8 +10709,8 @@ components: scope_mode: type: string enum: - - all_agents - - selected_agents + - all_agents + - selected_agents description: Whether the scorer applies to every factory agent or selected agents agent_uids: type: array @@ -10765,10 +10729,9 @@ components: items: $ref: '#/components/schemas/ScorerAgentInput' sampling_rate: - type: - - number - - 'null' + type: number format: double + nullable: true minimum: 0 maximum: 100 description: | @@ -10853,8 +10816,8 @@ components: scope_mode: type: string enum: - - all_agents - - selected_agents + - all_agents + - selected_agents description: | New scope mode. Defaults to the scorer's current mode when only agent_uids or agents is supplied. @@ -10884,9 +10847,14 @@ components: New LLM model dispatched judge runs use to evaluate this scorer's rubric. Must not be blank when provided. agent_config: + type: object + nullable: true anyOf: - - $ref: '#/components/schemas/ScorerAgentConfig' - - type: 'null' + - $ref: '#/components/schemas/ScorerAgentConfig' + - type: object + nullable: true + enum: + - null description: | Partial execution override update. A null object resets every override to inherit the Factory agent defaults. Otherwise, omitted @@ -10903,29 +10871,29 @@ components: 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 + - user + - benchmark_task_correctness ScorerResponse: type: object required: - - scorer_uid - - id - - factory_uid - - name - - description - - scoring_prompt - - allowed_classifications - - threshold - - self_improvement_enabled - - scorer_kind - - scope_mode - - agent_uids - - agents - - sampling_rate - - model_id - - agent_config - - created_at - - updated_at + - scorer_uid + - id + - factory_uid + - name + - description + - scoring_prompt + - allowed_classifications + - threshold + - self_improvement_enabled + - scorer_kind + - scope_mode + - agent_uids + - agents + - sampling_rate + - model_id + - agent_config + - created_at + - updated_at properties: scorer_uid: $ref: '#/components/schemas/ScorerUID' @@ -10954,14 +10922,14 @@ components: threshold: type: number format: double - description: Score a run's classified label must meet or exceed to pass, from 0 to 1 + description: 'Score a run''s classified label must meet or exceed to pass, from 0 to 1' scorer_kind: $ref: '#/components/schemas/ScorerKind' scope_mode: type: string enum: - - all_agents - - selected_agents + - all_agents + - selected_agents description: Whether the scorer applies to every factory agent or selected agents agent_uids: type: array @@ -10997,9 +10965,9 @@ components: ScorerScopeAgent: type: object required: - - uid - - name - - include_descendants + - uid + - name + - include_descendants properties: uid: type: string @@ -11013,7 +10981,7 @@ components: ScorerAgentInput: type: object required: - - uid + - uid properties: uid: type: string @@ -11025,24 +10993,24 @@ components: ScorerListItem: type: object required: - - scorer_uid - - id - - factory_uid - - name - - description - - scoring_prompt - - allowed_classifications - - threshold - - scope_mode - - agents - - scorer_kind - - sampling_rate - - created_at - - updated_at - - result_count - - model_id - - agent_config - - self_improvement_enabled + - scorer_uid + - id + - factory_uid + - name + - description + - scoring_prompt + - allowed_classifications + - threshold + - scope_mode + - agents + - scorer_kind + - sampling_rate + - created_at + - updated_at + - result_count + - model_id + - agent_config + - self_improvement_enabled properties: scorer_uid: $ref: '#/components/schemas/ScorerUID' @@ -11068,12 +11036,12 @@ components: threshold: type: number format: double - description: Score a run's classified label must meet or exceed to pass, from 0 to 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 + - all_agents + - selected_agents description: all_agents (every agent in the scorer's factory) or selected_agents agents: type: array @@ -11102,10 +11070,9 @@ components: type: integer description: Number of live scores recorded for the scorer last_scored_at: - type: - - string - - 'null' + type: string format: date-time + nullable: true description: When the scorer last recorded a score model_id: type: string @@ -11118,7 +11085,7 @@ components: ListScorersResponse: type: object required: - - scorers + - scorers properties: scorers: type: array @@ -11127,8 +11094,8 @@ components: ScorerOutcome: type: string enum: - - pass - - fail + - 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 @@ -11140,9 +11107,9 @@ components: ScorerResultStatus: type: string enum: - - scored - - failed - - in_flight + - scored + - failed + - in_flight description: | Outcome of a scoring attempt: "scored", "failed", or "in_flight" (no live score yet and a judge is currently running). A failed or @@ -11152,89 +11119,87 @@ components: ScorerReasonStatus: type: string enum: - - available - - absent - - unavailable + - available + - absent + - unavailable description: | Available when the judge reason was read, absent when none was recorded, and unavailable when a recorded reason could not be read. ScorerResult: type: object required: - - run_id - - status - - attempted_at - - is_in_flight + - run_id + - status + - attempted_at + - is_in_flight properties: run_id: type: string description: The selected agent run that anchors the scoring attempt conversation_id: - type: - - string - - 'null' + type: string + nullable: true description: Conversation whose transcript was judged conversation_title: - type: - - string - - 'null' + type: string + nullable: true description: Title of the judged conversation status: $ref: '#/components/schemas/ScorerResultStatus' reason_status: allOf: - - $ref: '#/components/schemas/ScorerReasonStatus' + - $ref: '#/components/schemas/ScorerReasonStatus' description: Present only when include_reasons is true. reason: type: string description: Judge reasoning; present only when reason_status is available. classification: - type: - - string - - 'null' + type: string + nullable: true description: The chosen classification; absent when the attempt failed attempted_at: type: string format: date-time description: When the scorer last attempted this run scored_at: - type: - - string - - 'null' + type: string format: date-time + nullable: true description: When the live score was recorded; absent for failed attempts scoring_run_id: - type: - - string - - 'null' + 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' + - $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 - - 'null' + 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 - - 'null' + 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: + type: string anyOf: - - $ref: '#/components/schemas/ScorerOutcome' - - type: 'null' + - $ref: '#/components/schemas/ScorerOutcome' + - type: string + nullable: true + enum: + - null + nullable: true description: | Pass/fail verdict for this score, derived at read time against the evaluation's current threshold. Absent when the attempt failed. @@ -11247,8 +11212,8 @@ components: ListScorerResultsResponse: type: object required: - - results - - page_info + - results + - page_info properties: results: type: array @@ -11263,14 +11228,14 @@ components: 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 + - 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' @@ -11284,16 +11249,15 @@ components: pass_count: type: integer format: int64 - description: Live scores whose derived outcome is pass, over the whole range. + 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. + description: 'Live scores whose derived outcome is fail, over the whole range.' pass_rate: - type: - - number - - 'null' + type: number format: double + nullable: true description: | pass_count / (pass_count + fail_count) over the whole range; null when the range has no pass/fail scores. The dashboard headline @@ -11301,13 +11265,13 @@ components: describes the same window as the chart. pass_count_series: type: array - description: One entry per period_list entry, zero-filled. + 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. + description: 'One entry per period_list entry, zero-filled.' items: type: integer format: int64 @@ -11319,10 +11283,9 @@ components: with no pass/fail scores, so the chart renders a gap there instead of a false 0%. items: - type: - - number - - 'null' + type: number format: double + nullable: true cost_usd_series: type: array description: | @@ -11343,7 +11306,7 @@ components: RunScorerDispatchRequest: type: object required: - - scorer_uids + - scorer_uids properties: scorer_uids: type: array @@ -11355,7 +11318,7 @@ components: ScorerDispatchRequest: type: object required: - - run_ids + - run_ids properties: run_ids: type: array @@ -11368,13 +11331,13 @@ components: ManualScoringDispatchStatus: type: string enum: - - dispatched - - already_in_flight - - failed_no_transcript - - failed_run_tree_not_ready - - failed_run_tree_incomplete - - failed_run_tree_too_large - - failed_to_dispatch + - dispatched + - already_in_flight + - failed_no_transcript + - failed_run_tree_not_ready + - failed_run_tree_incomplete + - failed_run_tree_too_large + - failed_to_dispatch description: | Outcome of one dispatched (run, scorer) pair: "dispatched" (stamped with a new or shared judge run), "already_in_flight" (an existing live @@ -11389,9 +11352,9 @@ components: ManualScoringDispatchResult: type: object required: - - scorer_uid - - run_id - - status + - scorer_uid + - run_id + - status properties: scorer_uid: $ref: '#/components/schemas/ScorerUID' @@ -11402,35 +11365,33 @@ components: status: $ref: '#/components/schemas/ManualScoringDispatchStatus' scoring_run_id: - type: - - string - - 'null' + type: string + nullable: true format: uuid 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 - - 'null' + type: string + nullable: true description: Safe error detail; present only for failed_to_dispatch ManualScoringDispatchResponse: type: object required: - - results + - results properties: results: type: array items: $ref: '#/components/schemas/ManualScoringDispatchResult' - description: One entry per requested pair, in no particular order + description: 'One entry per requested pair, in no particular order' RunScoreAttemptStatus: type: string enum: - - in_flight - - scored - - failed + - 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 @@ -11439,19 +11400,19 @@ components: RunScoreTriggerSource: type: string enum: - - automatic - - manual + - automatic + - manual description: Whether the current attempt was requested by an automatic scoring dispatch or a manual dispatch request RunScoreItem: type: object required: - - scorer_uid - - scorer_id - - scorer_name - - attempt_status - - is_in_flight - - trigger_source - - attempted_at + - scorer_uid + - scorer_id + - scorer_name + - attempt_status + - is_in_flight + - trigger_source + - attempted_at properties: scorer_uid: $ref: '#/components/schemas/ScorerUID' @@ -11469,30 +11430,27 @@ components: trigger_source: $ref: '#/components/schemas/RunScoreTriggerSource' classification: - type: - - string - - 'null' + type: string + nullable: true description: The live classification; absent when there is no live score attempted_at: type: string format: date-time description: When the evaluation last attempted this run scored_at: - type: - - string - - 'null' + type: string format: date-time + nullable: true description: When the live score was recorded; absent when there is no live score scoring_run_id: - type: - - string - - 'null' + type: string + nullable: true description: The Warp run that performed the judging; absent when scoring was never dispatched for this attempt GetRunScoresResponse: type: object required: - - run_id - - scores + - run_id + - scores properties: run_id: type: string @@ -11501,37 +11459,33 @@ components: type: array items: $ref: '#/components/schemas/RunScoreItem' - description: One entry per evaluation that has attempted the run, most recent attempt first + description: 'One entry per evaluation that has attempted the run, most recent attempt first' CreateAgentRequest: type: object required: - - name + - name properties: name: type: string description: A name for the agent description: - type: - - string - - 'null' + type: string + nullable: true description: Optional description of the agent prompt: - type: - - string - - 'null' + type: string + nullable: true description: | Optional base prompt for this agent environment_id: - type: - - string - - 'null' + type: string + nullable: true description: | Optional default cloud environment ID for runs executed by this agent. The environment must be owned by the same team as the agent. default_runner_uid: - type: - - string - - 'null' + type: string + nullable: true description: | Optional default runner UID for runs executed by this agent. When set, it overrides the selected environment's default runner for runs that @@ -11555,21 +11509,20 @@ components: Each spec is validated and normalized at attach time using the team's GitHub credentials; inaccessible or malformed specs are rejected. base_model: - type: - - string - - 'null' + type: string + nullable: true description: | Optional base model for runs executed by this agent. inference_providers: allOf: - - $ref: '#/components/schemas/InferenceProvidersConfig' + - $ref: '#/components/schemas/InferenceProvidersConfig' description: | Optional inference provider settings for this agent. Agent-level config takes precedence over the workspace's admin-configured defaults. memory: allOf: - - $ref: '#/components/schemas/AgentMemoryCreateConfig' + - $ref: '#/components/schemas/AgentMemoryCreateConfig' description: Optional memory settings for the agent. mcp_servers: type: object @@ -11579,9 +11532,8 @@ components: Optional map of MCP server configurations by name to attach to runs executed by this agent. Run-level MCP config takes precedence over this agent-level default. base_harness: - type: - - string - - 'null' + type: string + nullable: true deprecated: true description: | Optional default harness for runs executed by this agent. @@ -11590,14 +11542,14 @@ components: type is rejected with invalid_request. harness: allOf: - - $ref: '#/components/schemas/Harness' + - $ref: '#/components/schemas/Harness' description: | Optional default harness for runs executed by this agent. Omission or an empty object stores no harness default. credential_strategy: - oneOf: - - $ref: '#/components/schemas/AgentCredentialStrategy' - - type: 'null' + allOf: + - $ref: '#/components/schemas/AgentCredentialStrategy' + nullable: true description: | Optional default credential strategy for runs executed by this agent. When omitted or null, the agent has no opinion and runs fall @@ -11605,7 +11557,7 @@ components: EXECUTOR. harness_auth_secrets: allOf: - - $ref: '#/components/schemas/HarnessAuthSecrets' + - $ref: '#/components/schemas/HarnessAuthSecrets' description: | Optional per-harness authentication secrets for this agent. Each field names a managed secret for the corresponding harness. @@ -11617,9 +11569,8 @@ components: field to attribute runs to another team member. Defaults to false. Only team admins may set this field. worker_host: - type: - - string - - 'null' + 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 @@ -11639,44 +11590,36 @@ components: * Non-empty: replace the field wholesale with the provided value. `secrets_append` is an exception: it appends secrets idempotently and must be the only supplied field, including fields supplied as `null`. - `network_policy` is also an exception: omission preserves the policy, - null clears it, and an object replaces it wholesale. An object with - no allowed hosts carries deny-all intent. properties: name: type: string description: The new name for the agent description: - type: - - string - - 'null' + type: string + nullable: true description: | Replacement description. Omit or pass `null` to leave unchanged, or use an empty value to clear. prompt: - type: - - string - - 'null' + type: string + nullable: true description: | Replacement prompt. Omit or pass `null` to leave unchanged, or use an empty value to clear. environment_id: - type: - - string - - 'null' + type: string + nullable: true description: | Replacement default cloud environment ID. Omit or pass `null` to leave unchanged, or pass an empty string to clear. default_runner_uid: - type: - - string - - 'null' + type: string + nullable: true description: | Replacement default runner UID. Omit or pass `null` to leave unchanged, or pass an empty string to clear. A non-empty value must reference a runner the editor can View. secrets: - type: - - array - - 'null' + type: array + nullable: true items: $ref: '#/components/schemas/SecretRef' description: | @@ -11685,6 +11628,7 @@ components: Duplicate names are rejected. secrets_append: type: array + nullable: false items: $ref: '#/components/schemas/SecretRef' description: | @@ -11697,25 +11641,23 @@ components: the agent plus secret-attach access on its Factory. Agents managed in external source files return 409. skills: - type: - - array - - 'null' + type: array + nullable: true items: type: string description: | Replacement list of skill specs. Omit to leave unchanged, pass an empty array to clear, or pass a non-empty array to replace. base_model: - type: - - string - - 'null' + type: string + nullable: true description: | Replacement base model. Omit or pass `null` to leave unchanged, or pass an empty string to clear. memory: - oneOf: - - $ref: '#/components/schemas/AgentMemoryUpdateConfig' - - type: 'null' + allOf: + - $ref: '#/components/schemas/AgentMemoryUpdateConfig' + nullable: true description: Replacement memory settings for this agent. mcp_servers: type: object @@ -11727,18 +11669,18 @@ components: to replace. Run-level MCP config takes precedence over this agent-level default. inference_providers: - oneOf: - - $ref: '#/components/schemas/InferenceProvidersConfig' - - type: 'null' + type: object + allOf: + - $ref: '#/components/schemas/InferenceProvidersConfig' + nullable: true description: | 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 - - 'null' + type: string + nullable: true deprecated: true description: | Replacement default harness; omit or pass `null` to leave @@ -11747,17 +11689,17 @@ components: are sent, harness is authoritative and a conflicting type is rejected with invalid_request. harness: - oneOf: - - $ref: '#/components/schemas/Harness' - - type: 'null' + allOf: + - $ref: '#/components/schemas/Harness' + nullable: true description: | Replacement default harness for runs executed by this agent. Omit or pass `null` to leave unchanged, pass `{}` to clear the stored default, or pass a populated object to replace it wholesale. credential_strategy: - oneOf: - - $ref: '#/components/schemas/AgentCredentialStrategy' - - type: 'null' + allOf: + - $ref: '#/components/schemas/AgentCredentialStrategy' + nullable: true description: | Replacement default credential strategy. Omit or pass `null` to leave unchanged, or pass an empty string to clear the agent's @@ -11766,24 +11708,22 @@ components: file that declares none keeps the strategy already projected, so a clear is rejected with a 400. harness_auth_secrets: - oneOf: - - $ref: '#/components/schemas/HarnessAuthSecrets' - - type: 'null' + allOf: + - $ref: '#/components/schemas/HarnessAuthSecrets' + nullable: true description: | Replacement per-harness authentication secrets. Omit or pass `null` to leave unchanged, or pass an empty object to clear all secrets. on_behalf_of_enabled: - type: - - boolean - - 'null' + type: boolean + nullable: true description: | Whether runs created with this agent's API key may use the on_behalf_of field to attribute runs to another team member. Omit or pass `null` to leave unchanged. Only team admins may set this field. worker_host: - type: - - string - - 'null' + type: string + nullable: true description: | Replacement default worker host. Omit or pass `null` to leave unchanged, or pass an empty string to clear (the workspace default @@ -11793,15 +11733,15 @@ components: AgentResponse: type: object required: - - uid - - name - - available - - created_at - - updated_at - - secrets - - skills - - memory - - default_runner_uid + - uid + - name + - available + - created_at + - updated_at + - secrets + - skills + - memory + - default_runner_uid properties: uid: type: string @@ -11810,14 +11750,12 @@ components: type: string description: Name of the agent description: - type: - - string - - 'null' + type: string + nullable: true description: Optional description of the agent prompt: - type: - - string - - 'null' + type: string + nullable: true description: | Optional base prompt for this agent environment_id: @@ -11874,14 +11812,14 @@ components: 3. The team's default model inference_providers: allOf: - - $ref: '#/components/schemas/InferenceProvidersConfig' + - $ref: '#/components/schemas/InferenceProvidersConfig' description: | The agent's stored inference provider settings. May be overridden by run-level config; if empty, falls back to the workspace's admin-configured defaults. memory: allOf: - - $ref: '#/components/schemas/AgentMemoryResponse' + - $ref: '#/components/schemas/AgentMemoryResponse' description: | Memory settings for this agent. Always present; attached_stores is empty when no team stores are attached. @@ -11905,7 +11843,7 @@ components: {type, model_id, reasoning_level} default. harness: allOf: - - $ref: '#/components/schemas/Harness' + - $ref: '#/components/schemas/Harness' description: | Default harness for runs executed by this agent. Absent when the agent has no harness default. A stored model_id/reasoning_level @@ -11913,7 +11851,7 @@ components: harness's catalog. credential_strategy: allOf: - - $ref: '#/components/schemas/AgentCredentialStrategy' + - $ref: '#/components/schemas/AgentCredentialStrategy' description: | Default credential strategy for runs executed by this agent. Absent when the agent has no default. The precedence order for @@ -11926,7 +11864,7 @@ components: an unavailable credential rejects the request before execution. harness_auth_secrets: allOf: - - $ref: '#/components/schemas/HarnessAuthSecrets' + - $ref: '#/components/schemas/HarnessAuthSecrets' description: | Per-harness authentication secrets configured on this agent. Each field names a managed secret for the corresponding harness. @@ -11947,7 +11885,7 @@ components: ListAgentIdentitiesResponse: type: object required: - - agents + - agents properties: agents: type: array @@ -11957,11 +11895,11 @@ components: type: object description: Summary of the most recently created task for an environment required: - - id - - title - - state - - created_at - - updated_at + - id + - title + - state + - created_at + - updated_at properties: id: type: string @@ -11980,37 +11918,36 @@ components: format: date-time description: When the task was last updated (RFC3339) started_at: - type: - - string - - 'null' + type: string format: date-time - description: When the task started running (RFC3339), null if not yet started + nullable: true + description: 'When the task started running (RFC3339), null if not yet started' BenchmarkRunState: type: string description: Lifecycle state of a benchmark run. enum: - - pending - - running - - scoring - - completed - - failed - - cancelled + - pending + - running + - scoring + - completed + - failed + - cancelled BenchmarkTrialState: type: string description: Lifecycle state of a benchmark trial. enum: - - pending - - running - - succeeded - - failed - - cancelled + - pending + - running + - succeeded + - failed + - cancelled BenchmarkRepoRef: type: object description: A repository location and optional starting ref for a suite task. required: - - code_forge - - owner - - repo + - code_forge + - owner + - repo properties: code_forge: type: string @@ -12023,10 +11960,10 @@ components: BenchmarkSuiteTask: type: object required: - - uid - - title - - prompt - - success_criteria + - uid + - title + - prompt + - success_criteria properties: uid: type: string @@ -12043,9 +11980,8 @@ components: against, as the authoritative requirements. The task prompt provides context only. source_run_id: - type: - - string - - 'null' + type: string + nullable: true labels: type: object additionalProperties: @@ -12061,9 +11997,9 @@ components: BenchmarkAgentConfigInput: type: object required: - - agent_uid - - harness - - model + - agent_uid + - harness + - model properties: agent_uid: type: string @@ -12075,19 +12011,18 @@ components: model: type: string harness_auth_secret_name: - type: - - string - - 'null' + type: string + nullable: true BenchmarkSuite: type: object required: - - uid - - factory_uid - - name - - agent_uid - - factory_agent_type - - created_at - - updated_at + - uid + - factory_uid + - name + - agent_uid + - factory_agent_type + - created_at + - updated_at properties: uid: type: string @@ -12116,7 +12051,7 @@ components: format: date-time creator: allOf: - - $ref: '#/components/schemas/BenchmarkSuiteCreator' + - $ref: '#/components/schemas/BenchmarkSuiteCreator' description: | The suite's creator, when known. Absent when creator identity is unknown or no longer retained. @@ -12128,48 +12063,47 @@ components: BenchmarkSuiteCreator: type: object required: - - type - - uid + - type + - uid properties: type: type: string enum: - - user - - agent + - user + - agent uid: type: string display_name: type: string BenchmarkSuiteDetail: allOf: - - $ref: '#/components/schemas/BenchmarkSuite' - - type: object - required: - - spawnable_descendant_agent_uids - properties: - tasks: - type: array - items: - $ref: '#/components/schemas/BenchmarkSuiteTask' - spawnable_descendant_agent_uids: - type: array - items: - type: string - description: | - Stable UID-sorted list of live, non-system Factory agents - transitively reachable from this suite's selected root under - the server's effective delegation policy. + - $ref: '#/components/schemas/BenchmarkSuite' + - type: object + required: + - spawnable_descendant_agent_uids + properties: + tasks: + type: array + items: + $ref: '#/components/schemas/BenchmarkSuiteTask' + spawnable_descendant_agent_uids: + type: array + items: + type: string + description: | + Stable UID-sorted list of live, non-system Factory agents + transitively reachable from this suite's selected root under + the server's effective delegation policy. BenchmarkSuiteCreateRequest: type: object required: - - uid - - name - - agent_uid - - factory_agent_type + - uid + - name + - agent_uid + - factory_agent_type properties: uid: type: string - x-stainless-param: suite_uid name: type: string description: @@ -12189,9 +12123,9 @@ components: BenchmarkSuiteTaskInput: type: object required: - - title - - prompt - - success_criteria + - title + - prompt + - success_criteria properties: uid: type: string @@ -12208,9 +12142,8 @@ components: against, as the authoritative requirements. The task prompt provides context only. source_run_id: - type: - - string - - 'null' + type: string + nullable: true labels: type: object additionalProperties: @@ -12226,9 +12159,9 @@ components: BenchmarkSuiteTaskCreateRequest: type: object required: - - title - - prompt - - success_criteria + - title + - prompt + - success_criteria properties: title: type: string @@ -12241,9 +12174,8 @@ components: against, as the authoritative requirements. The task prompt provides context only. source_run_id: - type: - - string - - 'null' + type: string + nullable: true description: | Optional provenance. The caller must be able to read the run. tags: @@ -12264,9 +12196,8 @@ components: success_criteria: type: string source_run_id: - type: - - string - - 'null' + type: string + nullable: true tags: type: array items: @@ -12286,16 +12217,14 @@ components: model: type: string runner_id: - type: - - string - - 'null' + type: string + nullable: true description: | Optional runner UID, constrained to the Factory's existing runner roster. Omitted or empty uses the agent's or environment's default. harness_auth_secret_name: - type: - - string - - 'null' + type: string + nullable: true description: | Optional managed-secret name this configuration's third-party harness authenticates with. Empty or omitted is valid for Oz. For a third-party @@ -12321,9 +12250,8 @@ components: factory_agent_type: type: string tasks: - type: - - array - - 'null' + type: array + nullable: true description: | The array order is not significant: a task's identity comes from its uid (when editing an existing task) or title (when creating one), @@ -12333,7 +12261,7 @@ components: LaunchBenchmarkRunRequest: type: object required: - - repetition_count + - repetition_count properties: configurations: type: array @@ -12354,9 +12282,9 @@ components: type: array items: oneOf: - - $ref: '#/components/schemas/ScorerUID' - - type: integer - minimum: 1 + - $ref: '#/components/schemas/ScorerUID' + - type: integer + minimum: 1 description: | Allowlist of live scorer UUIDs (or temporary positive numeric IDs) for this factory, applied to every trial in the run. Empty or absent means all applicable scorers. IDs must @@ -12367,8 +12295,8 @@ components: uniqueItems: true items: type: string - examples: - - - 7d69fb52-71c5-4e27-914e-8764ee9c5246 + example: + - 7d69fb52-71c5-4e27-914e-8764ee9c5246 - ad8ff7dc-a7d1-4ed6-9f50-650010bb39aa description: | Optional allowlist of immutable UIDs for current tasks in the addressed @@ -12377,8 +12305,8 @@ components: BenchmarkRunLaunchResponse: type: object required: - - uid - - state + - uid + - state properties: uid: type: string @@ -12387,63 +12315,63 @@ components: BenchmarkRunList: type: object required: - - data - - page_info + - data + - page_info properties: data: type: array items: $ref: '#/components/schemas/BenchmarkRun' - description: complete requested Run rows on this page, newest first. + description: 'complete requested Run rows on this page, newest first.' page_info: $ref: '#/components/schemas/BenchmarkPageInfo' description: continuation for this Run list only. BenchmarkTrialList: type: object required: - - data - - page_info + - data + - page_info properties: data: type: array items: $ref: '#/components/schemas/BenchmarkTrial' - description: complete requested logical Trial rows on this page, or zero/one targeted match. + description: 'complete requested logical Trial rows on this page, or zero/one targeted match.' page_info: $ref: '#/components/schemas/BenchmarkPageInfo' description: continuation for the Trial list; targeted lookup always has `has_next_page=false`. BenchmarkPageInfo: type: object required: - - has_next_page + - has_next_page properties: has_next_page: type: boolean description: true when another complete list page exists. next_cursor: type: string - description: opaque scoped keyset cursor, present only when `has_next_page=true`, never null. + description: 'opaque scoped keyset cursor, present only when `has_next_page=true`, never null.' BenchmarkRun: type: object required: - - uid - - factory_uid - - suite_uid - - suite_name - - agent_uid - - agent_name - - state - - created_at - - updated_at - - started_at - - completed_at - - creator - - execution - - scoring + - uid + - factory_uid + - suite_uid + - suite_name + - agent_uid + - agent_name + - state + - created_at + - updated_at + - started_at + - completed_at + - creator + - execution + - scoring properties: uid: type: string - description: existing benchmark Run UID, including legacy non-UUID identities. + description: 'existing benchmark Run UID, including legacy non-UUID identities.' factory_uid: type: string description: authorized owning Factory UID. @@ -12457,20 +12385,17 @@ components: type: string description: suite UID verified against the frozen Run context. suite_name: - type: - - string - - 'null' + type: string + nullable: true description: retained frozen suite name; unknown legacy name is null. agent_uid: - type: - - string - - 'null' + type: string + nullable: true description: tested root agent's frozen UID when retained. agent_name: - type: - - string - - 'null' - description: tested root agent's frozen name, not today's catalog name. + type: string + nullable: true + description: 'tested root agent''s frozen name, not today''s catalog name.' state: $ref: '#/components/schemas/BenchmarkRunState' description: captured benchmark Run lifecycle state. @@ -12481,67 +12406,64 @@ components: updated_at: type: string format: date-time - description: stored Run update time, not a complete source-validity watermark. + description: 'stored Run update time, not a complete source-validity watermark.' started_at: - type: - - string - - 'null' + type: string format: date-time + nullable: true description: stored Run start time; null before start or if not retained. completed_at: - type: - - string - - 'null' + type: string format: date-time + nullable: true description: stored Run terminal time; null while active or if not retained. creator: - oneOf: - - $ref: '#/components/schemas/BenchmarkRunCreator' - - type: 'null' - description: safe retained creator identity, or null when it cannot be resolved. + allOf: + - $ref: '#/components/schemas/BenchmarkRunCreator' + nullable: true + description: 'safe retained creator identity, or null when it cannot be resolved.' execution: $ref: '#/components/schemas/BenchmarkExecutionProgress' - description: logical Trial counts, never attempt/descendant counts. + description: 'logical Trial counts, never attempt/descendant counts.' scoring: $ref: '#/components/schemas/BenchmarkRunScoring' - description: existing raw ledger and logical-Trial judging progress, without score values. + description: 'existing raw ledger and logical-Trial judging progress, without score values.' details: $ref: '#/components/schemas/BenchmarkRunDetails' description: present only for `include=details`; always non-null when requested. summary_results: $ref: '#/components/schemas/BenchmarkResultsSummary' - description: present only for `include=summary_results`; whole-run, on-request summary without metric arrays. + description: 'present only for `include=summary_results`; whole-run, on-request summary without metric arrays.' BenchmarkRunCreator: type: object required: - - type - - uid + - type + - uid properties: type: type: string enum: - - user - - agent + - user + - agent description: resolved creator type; agent includes identities behind API keys. uid: type: string - description: creator's public UID, never its database ID. + description: 'creator''s public UID, never its database ID.' display_name: - type: - - string - - 'null' - description: present only for an authorized creator-display-name include; null if the name is unknown, with no email fallback. + type: string + nullable: true + description: 'present only for an authorized creator-display-name include; null if the name is unknown, with no email fallback.' BenchmarkExecutionProgress: type: object required: - - planned_total - - total - - pending - - running - - succeeded - - failed - - cancelled - - completed + - planned_total + - total + - pending + - running + - succeeded + - failed + - cancelled + - completed properties: planned_total: type: integer @@ -12551,7 +12473,7 @@ components: description: observed stored logical Trial row count. pending: type: integer - description: Trials without a currently executing attempt, including queued/claimed attempts. + description: 'Trials without a currently executing attempt, including queued/claimed attempts.' running: type: integer description: Trials with a currently executing attempt. @@ -12570,24 +12492,23 @@ components: BenchmarkRunScoring: type: object required: - - total - - awaiting_trial - - pending - - judging - - scored - - finished_unscored - - not_scoreable - - received - - expected - - settled - - trials_being_judged - - trials_scoring_finished + - total + - awaiting_trial + - pending + - judging + - scored + - finished_unscored + - not_scoreable + - received + - expected + - settled + - trials_being_judged + - trials_scoring_finished properties: total: - type: - - integer - - 'null' - description: all applicable ledger pairs; null before materialization, zero only for known zero work. + type: integer + nullable: true + description: 'all applicable ledger pairs; null before materialization, zero only for known zero work.' awaiting_trial: type: integer description: raw pairs still waiting for execution to finish. @@ -12599,7 +12520,7 @@ components: description: raw pairs with an active judge. scored: type: integer - description: raw pairs marked scored in the durable ledger, even if bound evidence is now absent. + description: 'raw pairs marked scored in the durable ledger, even if bound evidence is now absent.' finished_unscored: type: integer description: raw pairs settled without a score. @@ -12608,11 +12529,10 @@ components: description: raw pairs skipped because execution failed or was cancelled. received: type: integer - description: exactly raw `scored`, not effective retained-score coverage. + description: 'exactly raw `scored`, not effective retained-score coverage.' expected: - type: - - integer - - 'null' + type: integer + nullable: true description: '`pending + judging + scored + finished_unscored` once materialized; otherwise null.' settled: type: integer @@ -12626,34 +12546,34 @@ components: BenchmarkRunDetails: type: object required: - - configurations - - task_uids - - repetition_count - - scorer_selection - - scorers - - tags + - configurations + - task_uids + - repetition_count + - scorer_selection + - scorers + - tags properties: configurations: type: array items: $ref: '#/components/schemas/BenchmarkRecordedConfiguration' - description: complete frozen configurations in launch order, including tooltip settings. + description: 'complete frozen configurations in launch order, including tooltip settings.' task_uids: type: array items: type: string - description: complete selected frozen task identities in launch order, including derived legacy identities. + description: 'complete selected frozen task identities in launch order, including derived legacy identities.' repetition_count: type: integer description: frozen repetitions per task/configuration. scorer_selection: $ref: '#/components/schemas/BenchmarkScorerSelection' - description: recorded launch selection, not the materialized roster. + description: 'recorded launch selection, not the materialized roster.' scorers: type: array items: $ref: '#/components/schemas/BenchmarkScorer' - description: safe descriptors for this Run's resolved scorers, using the existing authorized resolver. + description: 'safe descriptors for this Run''s resolved scorers, using the existing authorized resolver.' tags: type: array items: @@ -12662,89 +12582,81 @@ components: BenchmarkRecordedConfiguration: type: object required: - - uid - - display_name - - harness - - model - - runner_id - - harness_auth_secret_name - - agent_configs + - uid + - display_name + - harness + - model + - runner_id + - harness_auth_secret_name + - agent_configs properties: uid: type: string - description: stable Run-local public configuration identity, without exposing its stored integer ID. + description: 'stable Run-local public configuration identity, without exposing its stored integer ID.' display_name: type: string description: frozen user-supplied name; the existing empty string means no supplied name. harness: - type: - - string - - 'null' + type: string + nullable: true description: recorded effective root harness; unknown legacy values remain null. model: - type: - - string - - 'null' + type: string + nullable: true description: recorded effective root model; never filled from live defaults. runner_id: - type: - - string - - 'null' + type: string + nullable: true description: recorded root runner identity; no per-agent runner is introduced. harness_auth_secret_name: - type: - - string - - 'null' - description: retained root credential-name reference, including unavailable names. + type: string + nullable: true + description: 'retained root credential-name reference, including unavailable names.' agent_configs: type: array items: $ref: '#/components/schemas/BenchmarkRecordedAgentConfiguration' - description: complete retained named-agent settings, including the root when recorded. + description: 'complete retained named-agent settings, including the root when recorded.' BenchmarkRecordedAgentConfiguration: type: object required: - - agent_uid - - agent_name - - harness - - model - - harness_auth_secret_name + - agent_uid + - agent_name + - harness + - model + - harness_auth_secret_name properties: agent_uid: type: string description: frozen named Factory agent UID. agent_name: - type: - - string - - 'null' + type: string + nullable: true description: retained frozen named-agent label. harness: - type: - - string - - 'null' + type: string + nullable: true description: named agent's recorded effective harness. model: - type: - - string - - 'null' + type: string + nullable: true description: named agent's recorded effective model. harness_auth_secret_name: - type: - - string - - 'null' + type: string + nullable: true description: retained named-agent credential-name reference. BenchmarkScorerSelection: type: object required: - - mode - - scorer_uids + - mode + - scorer_uids properties: mode: type: string enum: - - all_applicable - - selected - description: preserved launch selection mode, even if selected scorers later disappear. + - all_applicable + - selected + description: 'preserved launch selection mode, even if selected scorers later disappear.' scorer_uids: type: array items: @@ -12753,25 +12665,25 @@ components: BenchmarkScorer: type: object required: - - scorer_uid - - name - - kind - - output_type - - output_labels + - scorer_uid + - name + - kind + - output_type + - output_labels properties: scorer_uid: type: string description: canonical scorer UUID supplied by the integrated identity adapter. name: type: string - description: existing resolved scorer name, not a promised launch-frozen name. + description: 'existing resolved scorer name, not a promised launch-frozen name.' kind: $ref: '#/components/schemas/ScorerKind' description: existing resolved scorer kind. output_type: type: string enum: - - classification + - classification description: current benchmark results support classification only. output_labels: type: array @@ -12781,32 +12693,32 @@ components: BenchmarkTagTasks: type: object required: - - tag - - task_uids + - tag + - task_uids properties: tag: type: string - description: exact frozen tag value, ordered lexically. + description: 'exact frozen tag value, ordered lexically.' task_uids: type: array items: type: string - description: complete distinct selected frozen task UIDs carrying this tag, in the containing `details.task_uids` order. + description: 'complete distinct selected frozen task UIDs carrying this tag, in the containing `details.task_uids` order.' BenchmarkTrial: type: object required: - - uid - - run_uid - - task_uid - - task_title - - task_tags - - configuration_uid - - repetition_index - - state - - terminal_reason - - current_agent_run_id - - attempt_count - - scoring + - uid + - run_uid + - task_uid + - task_title + - task_tags + - configuration_uid + - repetition_index + - state + - terminal_reason + - current_agent_run_id + - attempt_count + - scoring properties: uid: type: string @@ -12816,17 +12728,16 @@ components: description: containing benchmark Run UID. task_uid: type: string - description: frozen task UID, or stable Run-local public identity for a legacy task. + description: 'frozen task UID, or stable Run-local public identity for a legacy task.' task_title: - type: - - string - - 'null' + type: string + nullable: true description: frozen task title; unknown legacy title remains null. task_tags: type: array items: type: string - description: complete frozen task tags, not live tags. + description: 'complete frozen task tags, not live tags.' configuration_uid: type: string description: containing Run's stable public configuration identity. @@ -12837,26 +12748,24 @@ components: $ref: '#/components/schemas/BenchmarkTrialState' description: captured logical Trial state after queued/claimed normalization. terminal_reason: - oneOf: - - type: string - enum: + type: string + enum: - timeout - failure - - type: 'null' + nullable: true description: existing failed-Trial distinction; cancellation is already in `state`. current_agent_run_id: - type: - - string - - 'null' + type: string + nullable: true description: current execution attempt ID; null before dispatch. attempt_count: type: integer - description: stored dispatch count; zero before dispatch, legacy dispatched fallback one. + description: 'stored dispatch count; zero before dispatch, legacy dispatched fallback one.' scoring: type: array items: $ref: '#/components/schemas/BenchmarkTrialScoringStatus' - description: complete resolved classification-scorer rows with existing ledger status when present, without values/verdicts or scorer projection. + description: 'complete resolved classification-scorer rows with existing ledger status when present, without values/verdicts or scorer projection.' matched_attempt_number: type: integer description: one-based retained/current execution match on targeted lookup only; omitted elsewhere. @@ -12869,32 +12778,32 @@ components: BenchmarkTrialScoringStatus: type: object required: - - scorer_uid - - state + - scorer_uid + - state properties: scorer_uid: type: string description: resolved canonical scorer UUID. state: - oneOf: - - $ref: '#/components/schemas/BenchmarkTrialScoringState' - - type: 'null' + allOf: + - $ref: '#/components/schemas/BenchmarkTrialScoringState' + nullable: true description: existing effective ledger status after binding/cutoff checks; null when no ledger row exists. BenchmarkTrialResults: type: object required: - - scoring - - metrics - - spend + - scoring + - metrics + - spend properties: scoring: type: array items: $ref: '#/components/schemas/BenchmarkTrialScoringResult' - description: complete resolved scorer rows with existing evidence/status, including pending/unscored or absent-work rows. + description: 'complete resolved scorer rows with existing evidence/status, including pending/unscored or absent-work rows.' metrics: $ref: '#/components/schemas/BenchmarkTrialMetrics' - description: final retained live-tree run counts and retry-inclusive execution costs and durations. + description: current retained retry-inclusive execution measurements under existing loader semantics. spend: $ref: '#/components/schemas/BenchmarkSpend' description: retained execution/judging/combined totals under existing arithmetic. @@ -12902,26 +12811,26 @@ components: type: array items: $ref: '#/components/schemas/BenchmarkTrialAgentMetric' - description: available named-agent counts and retry-inclusive costs; count-only rows have null cost_usd. Omitted when no named-agent evidence is available. + description: complete existing named-agent breakdown when available; omitted when the existing loader suppresses an empty/incomplete breakdown. BenchmarkTrialScoringResult: type: object required: - - scorer_uid - - state - - name - - kind - - score - - label - - outcome - - latest_judge_run_id + - scorer_uid + - state + - name + - kind + - score + - label + - outcome + - latest_judge_run_id properties: scorer_uid: type: string description: resolved canonical scorer UUID. state: - oneOf: - - $ref: '#/components/schemas/BenchmarkTrialScoringState' - - type: 'null' + allOf: + - $ref: '#/components/schemas/BenchmarkTrialScoringState' + nullable: true description: existing effective ledger status after binding/cutoff checks; null when no ledger row exists. name: type: string @@ -12930,55 +12839,38 @@ components: $ref: '#/components/schemas/ScorerKind' description: existing authorized resolver kind. score: - type: - - number - - 'null' + type: number format: double + nullable: true description: exact retained bound classification value at/before cutoff; zero is a real score. label: - type: - - string - - 'null' + type: string + nullable: true description: label from that same bound score; null when no score evidence survives. outcome: - oneOf: - - type: string - enum: + type: string + enum: - pass - fail - - type: 'null' + nullable: true description: existing SQL-derived current-threshold verdict; null when no verdict is supplied. latest_judge_run_id: - type: - - string - - 'null' + type: string + nullable: true description: latest retained judge execution ID by dispatch order; no full judge history is implied. BenchmarkTrialMetrics: type: object - description: Metrics for a benchmark trial. A run is a persisted platform agent task instance; an execution is one session of that run with a recorded agent start. Resuming a run can add an execution without adding a run. Run/execution counts cover the final trial attempt's root and recursively spawned agents. Scorer runs and all their descendants are excluded. - required: - - agent_runs - - agent_executions - - compute_credits - - platform_credits - - inference_credits - - total_credits - - wall_time_s - - compute_cost_usd - - platform_cost_usd - - inference_cost_usd - - cost_usd - properties: - agent_runs: - type: - - integer - - 'null' - description: Distinct persisted platform agent task instances in the final retained live trial tree, excluding scorer runs and their descendants. Attempted runs count even if they never start or later fail. Superseded trial attempts are excluded. Null when the live tree is unavailable; deleted history is not reconstructed. - agent_executions: - type: - - integer - - 'null' - description: Distinct execution IDs with recorded agent starts in the same final retained live tree as agent_runs, including resumed sessions and starts that later fail. Dispatch or boot retries without an agent start do not count. Null when execution evidence is ambiguous or missing, independently of agent_runs; measured zero is present. + required: + - compute_credits + - platform_credits + - inference_credits + - total_credits + - wall_time_s + - compute_cost_usd + - platform_cost_usd + - inference_cost_usd + - cost_usd + properties: compute_credits: type: string description: summed retained execution-attempt compute credits. @@ -12994,7 +12886,7 @@ components: wall_time_s: type: number format: double - description: summed retained attempt working durations, excluding teardown; not the span between Trial.details timestamps. + description: 'summed retained attempt working durations, excluding teardown; not the span between Trial.details timestamps.' compute_cost_usd: type: number format: double @@ -13006,41 +12898,41 @@ components: inference_cost_usd: type: number format: double - description: existing inference dollars, including applicable third-party provider estimates. + description: 'existing inference dollars, including applicable third-party provider estimates.' cost_usd: type: number format: double - description: sum of the three dollar components, not guaranteed exact billed cost. + description: 'sum of the three dollar components, not guaranteed exact billed cost.' provider_cost_estimate: $ref: '#/components/schemas/BenchmarkProviderCostEstimate' - description: existing provider estimate/attribution, omitted when unavailable; never an invented zero estimate. + description: 'existing provider estimate/attribution, omitted when unavailable; never an invented zero estimate.' output_tokens: type: integer - description: sum of reported retained output-token counts; omitted when unreported, but reported zero remains present. + description: 'sum of reported retained output-token counts; omitted when unreported, but reported zero remains present.' tool_calls: type: integer - description: sum of reported retained tool-call counts; omitted when unreported, but reported zero remains present. + description: 'sum of reported retained tool-call counts; omitted when unreported, but reported zero remains present.' BenchmarkSpend: type: object required: - - execution - - judging - - combined + - execution + - judging + - combined properties: execution: $ref: '#/components/schemas/BenchmarkSpendTotal' description: retry-inclusive retained execution totals under existing attribution. judging: $ref: '#/components/schemas/BenchmarkSpendTotal' - description: totals for distinct durably linked retained judge runs, including repeated rescores. + description: 'totals for distinct durably linked retained judge runs, including repeated rescores.' combined: $ref: '#/components/schemas/BenchmarkSpendTotal' description: execution plus judging totals. BenchmarkSpendTotal: type: object required: - - cost_usd - - total_credits + - cost_usd + - total_credits properties: cost_usd: type: number @@ -13051,49 +12943,34 @@ components: description: existing Warp credit total for this spend group. BenchmarkTrialAgentMetric: type: object - description: Named-agent breakdown of trial metrics, with the platform run/execution definitions and scorer-branch exclusions of BenchmarkTrialMetrics. - required: - - agent_runs - - agent_executions - - agent_uid - - agent_name - - cost_usd - properties: - agent_runs: - type: - - integer - - 'null' - description: Distinct persisted platform agent task instances attributed to this agent in the final retained live trial tree, excluding scorer runs and their descendants. Attempts count even if they never start or later fail. Superseded attempts are excluded. Confirmed absence is zero; null means the live tree is unavailable. - agent_executions: - type: - - integer - - 'null' - description: Distinct execution IDs with recorded agent starts attributed to this agent in the same final retained live tree as agent_runs, including resumed sessions and starts that later fail. Dispatch or boot retries without an agent start do not count. Null means this agent's execution evidence is ambiguous or missing, independently of agent_runs; confirmed absence is zero. + required: + - agent_uid + - agent_name + - cost_usd + properties: agent_uid: type: string description: existing named-agent identity; the empty string retains the Unknown-agent fallback. agent_name: type: string - description: existing resolved label, including `"Unknown agent"` when identity is unavailable. + description: 'existing resolved label, including `"Unknown agent"` when identity is unavailable.' cost_usd: - type: - - number - - 'null' + type: number format: double - description: Exclusive named-agent cost summed across retained retries and spawned agents, excluding scorer runs and their descendants; null when only count evidence is available. + description: existing exclusive named-agent cost summed across retained retries and non-system descendants. sandbox_time_s: type: number format: double - description: existing summed claim-to-completion seconds, omitted when any contributing duration is unknown; measured zero is present. + description: 'existing summed claim-to-completion seconds, omitted when any contributing duration is unknown; measured zero is present.' cost_breakdown: $ref: '#/components/schemas/BenchmarkAgentCostBreakdown' - description: Retained exclusive costs and public-model attribution, omitted when the existing loader gate or availability suppresses it. + description: 'Retained exclusive costs and public-model attribution, omitted when the existing loader gate or availability suppresses it.' BenchmarkAgentCostBreakdown: type: object required: - - compute_cost_usd - - platform_cost_usd - - inference_cost_usd + - compute_cost_usd + - platform_cost_usd + - inference_cost_usd properties: compute_cost_usd: type: number @@ -13111,7 +12988,7 @@ components: BenchmarkCategoryCost: type: object required: - - cost_usd + - cost_usd properties: cost_usd: type: number @@ -13124,12 +13001,12 @@ components: BenchmarkProviderCostEstimate: type: object required: - - cost_usd - - incomplete + - cost_usd + - incomplete properties: cost_usd: type: string - description: public-rate estimated provider total, not a Warp-billed amount. + description: 'public-rate estimated provider total, not a Warp-billed amount.' incomplete: type: boolean description: existing signal that estimate inputs/pricing are incomplete. @@ -13141,9 +13018,9 @@ components: BenchmarkProviderCostAttribution: type: object required: - - model - - cost_usd - - incomplete + - model + - cost_usd + - incomplete properties: model: type: string @@ -13158,19 +13035,19 @@ components: type: array items: $ref: '#/components/schemas/BenchmarkProviderTokenCost' - description: complete retained priced token buckets, omitted when empty/unavailable. + description: 'complete retained priced token buckets, omitted when empty/unavailable.' adjustments: type: array items: $ref: '#/components/schemas/BenchmarkProviderCostAdjustment' - description: complete retained price multipliers, omitted when empty/unavailable. + description: 'complete retained price multipliers, omitted when empty/unavailable.' BenchmarkProviderTokenCost: type: object required: - - kind - - tokens - - rate_usd_per_million - - cost_usd + - kind + - tokens + - rate_usd_per_million + - cost_usd properties: kind: type: string @@ -13187,68 +13064,66 @@ components: BenchmarkProviderCostAdjustment: type: object required: - - kind - - multiplier + - kind + - multiplier properties: kind: type: string - description: existing adjustment kind, not credential metadata. + description: 'existing adjustment kind, not credential metadata.' multiplier: type: string description: dimensionless multiplier applied after token subtotals. BenchmarkTrialDetails: type: object required: - - started_at - - completed_at - - attempts - - judge_runs + - started_at + - completed_at + - attempts + - judge_runs properties: started_at: - type: - - string - - 'null' + type: string format: date-time + nullable: true description: earliest retained execution claim across the Trial's attempts. completed_at: - type: - - string - - 'null' + type: string format: date-time + nullable: true description: current attempt's retained terminal time only when the logical Trial is terminal. attempts: type: array items: $ref: '#/components/schemas/BenchmarkExecutionAttempt' - description: every retained execution attempt, ordered by one-based attempt number. + description: 'every retained execution attempt, ordered by one-based attempt number.' judge_runs: type: array items: $ref: '#/components/schemas/BenchmarkRetainedJudgeRun' - description: every retained durable judge dispatch across scorers/rescores, ordered by dispatch time and internal row tie-breaker. + description: 'every retained durable judge dispatch across scorers/rescores, ordered by dispatch time and internal row tie-breaker.' BenchmarkExecutionAttempt: type: object required: - - attempt_number - - agent_run_id - - state + - attempt_number + - agent_run_id + - state properties: attempt_number: type: integer - description: one-based position in the original attempt chain, not an array index after retention loss. + description: 'one-based position in the original attempt chain, not an array index after retention loss.' agent_run_id: type: string description: retained execution attempt ID. state: $ref: '#/components/schemas/BenchmarkExecutionState' - description: underlying retained execution state, without logical Trial-state normalization. + description: 'underlying retained execution state, without logical Trial-state normalization.' BenchmarkRetainedJudgeRun: type: object required: - - scorer_uid - - name - - kind - - agent_run_id + - scorer_uid + - name + - kind + - agent_run_id properties: scorer_uid: type: string @@ -13265,21 +13140,21 @@ components: BenchmarkResultsSummary: type: object required: - - factory_uid - - suite_uid - - run_uid - - state - - as_of - - provisional - - incomplete_reason - - coverage - - compute_credits - - platform_credits - - spend - - elapsed_s - - task_count - - scorer_count - - narrative + - factory_uid + - suite_uid + - run_uid + - state + - as_of + - provisional + - incomplete_reason + - coverage + - compute_credits + - platform_credits + - spend + - elapsed_s + - task_count + - scorer_count + - narrative properties: factory_uid: type: string @@ -13301,13 +13176,12 @@ components: type: boolean description: true for pending/running/scoring Runs whose values can still change. incomplete_reason: - type: - - string - - 'null' + type: string + nullable: true description: existing safe failed/cancelled partial-results explanation; null in other states. coverage: $ref: '#/components/schemas/BenchmarkResultsCoverage' - description: count-only execution/scoring evidence coverage, separate from raw progress. + description: 'count-only execution/scoring evidence coverage, separate from raw progress.' compute_credits: type: string description: existing selected execution compute-credit total from RunMetrics. @@ -13315,32 +13189,30 @@ components: type: string description: existing selected execution platform-credit total from RunMetrics. spend: - oneOf: - - $ref: '#/components/schemas/BenchmarkSpend' - - type: 'null' + allOf: + - $ref: '#/components/schemas/BenchmarkSpend' + nullable: true description: selected-dataset retry/judge totals; null before any selected Trial dispatch. elapsed_s: - type: - - number - - 'null' + type: number format: double - description: Run span from start through completion/calculation time, including scoring; null before start or if start is unknown. + nullable: true + description: 'Run span from start through completion/calculation time, including scoring; null before start or if start is unknown.' task_count: type: integer - description: distinct selected frozen tasks, independent of display projections and Trial pages. + description: 'distinct selected frozen tasks, independent of display projections and Trial pages.' scorer_count: - type: - - integer - - 'null' - description: count of resolved scorer descriptors, as in current history statistics; null before any selected Trial dispatch. + type: integer + nullable: true + description: 'count of resolved scorer descriptors, as in current history statistics; null before any selected Trial dispatch.' narrative: $ref: '#/components/schemas/BenchmarkNarrative' description: independent stored-narrative availability and eligible text. BenchmarkResultsCoverage: type: object required: - - execution - - scoring + - execution + - scoring properties: execution: $ref: '#/components/schemas/BenchmarkExecutionCoverage' @@ -13351,67 +13223,65 @@ components: BenchmarkExecutionCoverage: type: object required: - - planned_trial_count - - materialized_trial_count + - planned_trial_count + - materialized_trial_count properties: planned_trial_count: type: integer - description: selected frozen matrix size, equal to `execution.planned_total`. + description: 'selected frozen matrix size, equal to `execution.planned_total`.' materialized_trial_count: type: integer - description: observed selected logical Trial rows, equal to `execution.total`. + description: 'observed selected logical Trial rows, equal to `execution.total`.' BenchmarkScoringCoverage: type: object required: - - effective_scored_pair_count - - expected_pair_count + - effective_scored_pair_count + - expected_pair_count properties: effective_scored_pair_count: type: integer description: pairs whose exact bound score resolves under retention/access and at/before cutoff. expected_pair_count: - type: - - integer - - 'null' + type: integer + nullable: true description: materialized `pending + judging + scored + finished_unscored`; excludes awaiting-trial/not-scoreable and is null before membership is known. BenchmarkNarrative: type: object required: - - availability - - text + - availability + - text properties: availability: type: string enum: - - pending - - available - - unavailable - description: current stored generation/lifecycle gate, not metric completeness. + - pending + - available + - unavailable + description: 'current stored generation/lifecycle gate, not metric completeness.' text: - type: - - string - - 'null' + type: string + nullable: true description: nonempty retained narrative only when available; null otherwise. BenchmarkResults: type: object required: - - factory_uid - - suite_uid - - run_uid - - state - - as_of - - provisional - - incomplete_reason - - coverage - - compute_credits - - platform_credits - - spend - - elapsed_s - - task_count - - scorer_count - - narrative - - execution - - scoring + - factory_uid + - suite_uid + - run_uid + - state + - as_of + - provisional + - incomplete_reason + - coverage + - compute_credits + - platform_credits + - spend + - elapsed_s + - task_count + - scorer_count + - narrative + - execution + - scoring properties: factory_uid: type: string @@ -13433,13 +13303,12 @@ components: type: boolean description: true for pending/running/scoring Runs whose values can still change. incomplete_reason: - type: - - string - - 'null' + type: string + nullable: true description: existing safe failed/cancelled partial-results explanation; null in other states. coverage: $ref: '#/components/schemas/BenchmarkResultsCoverage' - description: count-only execution/scoring evidence coverage, separate from raw progress. + description: 'count-only execution/scoring evidence coverage, separate from raw progress.' compute_credits: type: string description: existing selected execution compute-credit total from RunMetrics. @@ -13447,24 +13316,22 @@ components: type: string description: existing selected execution platform-credit total from RunMetrics. spend: - oneOf: - - $ref: '#/components/schemas/BenchmarkSpend' - - type: 'null' + allOf: + - $ref: '#/components/schemas/BenchmarkSpend' + nullable: true description: selected-dataset retry/judge totals; null before any selected Trial dispatch. elapsed_s: - type: - - number - - 'null' + type: number format: double - description: Run span from start through completion/calculation time, including scoring; null before start or if start is unknown. + nullable: true + description: 'Run span from start through completion/calculation time, including scoring; null before start or if start is unknown.' task_count: type: integer - description: distinct selected frozen tasks, independent of display projections and Trial pages. + description: 'distinct selected frozen tasks, independent of display projections and Trial pages.' scorer_count: - type: - - integer - - 'null' - description: count of resolved scorer descriptors, as in current history statistics; null before any selected Trial dispatch. + type: integer + nullable: true + description: 'count of resolved scorer descriptors, as in current history statistics; null before any selected Trial dispatch.' narrative: $ref: '#/components/schemas/BenchmarkNarrative' description: independent stored-narrative availability and eligible text. @@ -13497,13 +13364,13 @@ components: BenchmarkConfigurationAggregate: type: object required: - - configuration_uid - - execution - - metrics - - scoring - - retried_trial_count - - retry_count - - overall_mean + - configuration_uid + - execution + - metrics + - scoring + - retried_trial_count + - retry_count + - overall_mean properties: configuration_uid: type: string @@ -13522,41 +13389,25 @@ components: description: logical Trials with more than one execution attempt. retry_count: type: integer - description: sum of each logical Trial's `max(attempt_count-1,0)`. + description: 'sum of each logical Trial''s `max(attempt_count-1,0)`.' overall_mean: - type: - - number - - 'null' + type: number format: double - description: unweighted mean of available comparable scorer means, null when none exists. + nullable: true + description: 'unweighted mean of available comparable scorer means, null when none exists.' BenchmarkConfigurationMetrics: type: object - description: Configuration totals and averages. Run/execution averages use the platform definitions and scorer-branch exclusions of BenchmarkTrialMetrics. - required: - - avg_agent_runs - - avg_agent_executions - - compute_credits - - platform_credits - - inference_credits - - total_credits - - cost_usd - - avg_total_credits_per_trial - - avg_total_credits_per_task - - avg_wall_time_s - - avg_cost_usd_per_trial - properties: - avg_agent_runs: - type: - - number - - 'null' - format: double - description: Mean observed final retained live-tree run counts over succeeded trials with available run evidence, including active descendants. Superseded attempts and failed or cancelled trials are excluded. - avg_agent_executions: - type: - - number - - 'null' - format: double - description: Mean recorded final-tree starts and resumes over succeeded trials with available execution evidence, including trials with active descendants or queued resumes. Null when no measurements qualify; unknown starts are not zero. + required: + - compute_credits + - platform_credits + - inference_credits + - total_credits + - cost_usd + - avg_total_credits_per_trial + - avg_total_credits_per_task + - avg_wall_time_s + - avg_cost_usd_per_trial + properties: compute_credits: type: string description: retry-inclusive execution compute-credit total. @@ -13575,18 +13426,18 @@ components: description: retry-inclusive execution dollar total under existing mixed-cost arithmetic. avg_total_credits_per_trial: type: string - description: credits averaged over final successful attempts, with existing decimal rounding. + description: 'credits averaged over final successful attempts, with existing decimal rounding.' avg_total_credits_per_task: type: string - description: final-successful-attempt credits divided by distinct succeeded tasks, with existing rounding. + description: 'final-successful-attempt credits divided by distinct succeeded tasks, with existing rounding.' avg_wall_time_s: type: number format: double - description: final successful attempt working-duration average, not retry-chain duration average. + description: 'final successful attempt working-duration average, not retry-chain duration average.' avg_cost_usd_per_trial: type: number format: double - description: final successful attempt cost average, not retry-chain cost average. + description: 'final successful attempt cost average, not retry-chain cost average.' avg_output_tokens: type: number format: double @@ -13598,19 +13449,19 @@ components: BenchmarkScorerConfigurationAggregate: type: object required: - - scorer_uid - - configuration_uid - - scored - - pending - - failed - - unscored - - no_result - - outcomes - - labels - - mean - - expected_task_count - - scored_task_count - - comparable + - scorer_uid + - configuration_uid + - scored + - pending + - failed + - unscored + - no_result + - outcomes + - labels + - mean + - expected_task_count + - scored_task_count + - comparable properties: scorer_uid: type: string @@ -13631,9 +13482,8 @@ components: type: integer description: existing finished-unscored or unresolved/post-cutoff scored pair count. no_result: - type: - - string - - 'null' + type: string + nullable: true description: existing safe no-scored-trials explanation. outcomes: $ref: '#/components/schemas/BenchmarkOutcomeCounts' @@ -13642,28 +13492,27 @@ components: type: array items: $ref: '#/components/schemas/BenchmarkLabelCount' - description: complete retained classification-label distribution, including known unseen labels at zero. + description: 'complete retained classification-label distribution, including known unseen labels at zero.' mean: - type: - - number - - 'null' + type: number format: double + nullable: true description: unweighted counted task-cell mean for this scorer/configuration; null when no cell contributes. expected_task_count: type: integer - description: existing `applies_to_tasks` selected-dataset ledger task count across configurations, before comparison neutralization. + description: 'existing `applies_to_tasks` selected-dataset ledger task count across configurations, before comparison neutralization.' scored_task_count: type: integer - description: distinct selected tasks with a bound score here, capped at expected_task_count, as in the chart coverage warning. + description: 'distinct selected tasks with a bound score here, capped at expected_task_count, as in the chart coverage warning.' comparable: type: boolean description: true if some configuration has a scored succeeded Trial for this scorer in the selected dataset. BenchmarkOutcomeCounts: type: object required: - - pass - - fail - - pass_rate + - pass + - fail + - pass_rate properties: pass: type: integer @@ -13672,42 +13521,40 @@ components: type: integer description: retained bound scores whose current-threshold outcome is fail. pass_rate: - type: - - number - - 'null' + type: number format: double + nullable: true description: '`pass/(pass+fail)`, null when that denominator is zero; not a scoring-coverage rate.' BenchmarkLabelCount: type: object required: - - label - - count + - label + - count properties: label: type: string description: retained classification label value. count: type: integer - description: bound scores with this label in the aggregate, including real zero counts for known labels. + description: 'bound scores with this label in the aggregate, including real zero counts for known labels.' BenchmarkTaskScorerConfigurationAggregate: type: object required: - - task_uid - - task_title - - configuration_uid - - scorer_uid - - expected_repetition_count - - scored_repetition_count - - mean - - task_overall_mean + - task_uid + - task_title + - configuration_uid + - scorer_uid + - expected_repetition_count + - scored_repetition_count + - mean + - task_overall_mean properties: task_uid: type: string description: frozen/derived legacy task coordinate. task_title: - type: - - string - - 'null' + type: string + nullable: true description: retained frozen title for row display. configuration_uid: type: string @@ -13717,93 +13564,74 @@ components: description: resolved canonical scorer coordinate. expected_repetition_count: type: integer - description: logical Trial repetitions in this cell under existing comparison arithmetic, including execution failures. + description: 'logical Trial repetitions in this cell under existing comparison arithmetic, including execution failures.' scored_repetition_count: type: integer description: succeeded repetitions with permitted retained bound numeric scores. mean: - type: - - number - - 'null' + type: number format: double - description: average of those scored repetitions; null when none contributes, never fabricated zero. + nullable: true + description: 'average of those scored repetitions; null when none contributes, never fabricated zero.' task_overall_mean: - type: - - number - - 'null' + type: number format: double - description: mean of available comparable scorer means for this task/configuration, before scorer display projection. + nullable: true + description: 'mean of available comparable scorer means for this task/configuration, before scorer display projection.' BenchmarkAgentMetricAggregate: type: object - description: Per-configuration named-agent totals and averages. Run/execution averages use the platform definitions and scorer-branch exclusions of BenchmarkTrialMetrics. required: - - avg_agent_runs - - avg_agent_executions - - agent_uid - - agent_name - - cost_usd - - configuration_uid + - agent_uid + - agent_name + - cost_usd + - configuration_uid properties: - avg_agent_runs: - type: - - number - - 'null' - format: double - description: Mean observed final retained live-tree run counts attributed to this agent over succeeded trials with available run evidence, including active descendants. Confirmed absence contributes zero; superseded attempts and failed or cancelled trials are excluded. - avg_agent_executions: - type: - - number - - 'null' - format: double - description: Mean recorded final-tree starts and resumes attributed to this agent over succeeded trials with available execution evidence for this agent, including trials with active descendants or queued resumes. Confirmed absence contributes zero; unknown starts are not zero. Null when no measurements qualify. agent_uid: type: string description: existing named-agent identity; the empty string retains the Unknown-agent fallback. agent_name: type: string - description: existing resolved label, including `"Unknown agent"` when identity is unavailable. + description: 'existing resolved label, including `"Unknown agent"` when identity is unavailable.' cost_usd: - type: - - number - - 'null' + type: number format: double - description: Exclusive named-agent cost summed across retained retries and spawned agents, excluding scorer runs and their descendants; null when only count evidence is available. + description: existing exclusive named-agent cost summed across retained retries and non-system descendants. sandbox_time_s: type: number format: double - description: existing summed claim-to-completion seconds, omitted when any contributing duration is unknown; measured zero is present. + description: 'existing summed claim-to-completion seconds, omitted when any contributing duration is unknown; measured zero is present.' configuration_uid: type: string description: containing configuration for the existing summed named-agent breakdown. cost_breakdown: $ref: '#/components/schemas/BenchmarkAgentCostBreakdown' - description: Retained exclusive costs and public-model attribution, omitted when the existing loader gate or availability suppresses it. + description: 'Retained exclusive costs and public-model attribution, omitted when the existing loader gate or availability suppresses it.' BenchmarkExecutionState: type: string enum: - - QUEUED - - PENDING - - CLAIMED - - INPROGRESS - - SUCCEEDED - - FAILED - - ERROR - - BLOCKED - - CANCELLED + - QUEUED + - PENDING + - CLAIMED + - INPROGRESS + - SUCCEEDED + - FAILED + - ERROR + - BLOCKED + - CANCELLED BenchmarkTrialScoringState: type: string enum: - - awaiting_trial - - pending - - judging - - scored - - finished_unscored - - not_scoreable + - awaiting_trial + - pending + - judging + - scored + - finished_unscored + - not_scoreable BenchmarkViolation: type: object required: - - code - - message + - code + - message properties: code: type: string @@ -13813,18 +13641,18 @@ components: description: Human-readable explanation BenchmarkLaunchViolationError: allOf: - - $ref: '#/components/schemas/Error' - - type: object - properties: - violations: - type: array - items: - $ref: '#/components/schemas/BenchmarkViolation' + - $ref: '#/components/schemas/Error' + - type: object + properties: + violations: + type: array + items: + $ref: '#/components/schemas/BenchmarkViolation' ListBenchmarkSuitesResponse: type: object required: - - data - - page_info + - data + - page_info properties: data: type: array