docs: Reconcile the public OpenAPI reference

[warp-agent-staging]

Summary

Reconcile the API reference with current public server APIs without losing independent docs improvements. This PR changes only the checked-in API snapshot; publisher, sync tooling, policy, and tests are deferred.

Changes

• Add 31 paths, 39 operations, and 140 schemas covering factory metrics, costs, inbox, scorers, benchmarks, public redirects, block snapshots, and handoff attachments. No existing public operations are removed.
• Preserve Platform API framing and canonical error-documentation links upstream. Earlier docs improvements to skill loading and immediate idle shutdown are already present upstream.
• Keep private harness, memory, upload, and fork operations and internal query parameters out of the snapshot. Preserve public query parameters and source-backed endpoint values.

Reconciliation evidence

The historical sync at docs 828b569e records server 1b2b876981386363166fb719ad76b539857c7a44; the latest docs consolidation 57ae4cf7 records server 74d26736c34263fe339d5ecca90db12606f66291. Comparing those sources with independent docs edits identifies prose to retain rather than blindly overwriting the file.

Current handlers win over stale docs for authenticated thumbnail URLs, self-improvement defaults, network-policy updates, and retry timeline events. Unused conversation-history headers and parameters are absent from the snapshot, not removed from the full server contract. Serializer changes account for much of the textual diff.

Paired server change: warp-server #19823 combines the API-content revision cc9d8e411fe20619182a60a4ccc1a2366cbb51da and exporter infrastructure from e1e74c70173d9ec75551e0cf23f817c8435c9da6. It landed on develop at 67256a3af1b26452f9bbe54152a65ffabd0f2bad on 2026-10-14 at 07:31:17 UTC; this is not release or publication evidence. Neither PR changes API runtime behavior.

Publication status

Docs cleanup #920 replaces closed docs infrastructure #919 and retires the agent-owned publisher; the preserved historical delta is not the active publication path. This API-only snapshot remains optional, not a workflow prerequisite; its disposition is pending human review.

Server infrastructure #19828 landed on develop with the API parent; release availability and publication remain unverified. Release-candidate sync replaces YAML on automation/sync-agent-api-spec and proposes a docs PR; it does not merge docs main. Publication requires a released source ref containing the intended API content and corrected exporter; the workflow does not upgrade an older checked-out exporter. Until docs cleanup lands, avoid applying the old fallback, which excludes some now-public paths.

Verification

• Passed in the documented order: npm run typecheck, npm run test:heading-vars, npm run build, npm run test:heading-tocs, and npm run test:homepage-json-ld.
• Passed independently of either publisher: accepted snapshot SHA-256 8092b88bd8dd5d35f197d83849bc9e357b441ccbabfa5c2aa0fffff602c31748, recursive source/snapshot comparison, exact public-operation coverage (71 paths, 89 operations, 294 schemas), no existing public-operation loss, local $ref closure, and git diff --check.
• The recursive comparison rejects every surviving source object marked internal. Internal automation_id and recent_outcomes_limit query parameters are excluded while public factory_uid, start_date, and end_date remain. The corrected exporter in the combined server parent reproduces this snapshot; older source refs with the legacy exporter do not.
• Passed: style_lint.py --changed (0 public prose files), reference compression check, and internal link checker (4,434 links). External HTTP links were not checked.
• Passed on the API-only server tree: go generate ./public_api/types/, go test -p 2 ./public_api/types/, go vet ./public_api/types/, go fmt ./public_api/types/, and scoped golangci-lint v2.12.2 (0 issues). Generation changes documentation comments only.
• Scalar verification shows the API intro, metrics, scorer and benchmark parameter/schema panels, inbox, and egress ranges; harness-support search returns no results. Fresh rebuilt parameter-panel proof verifies the internal-query correction; the earlier overview recording predates that correction.
• Prior same-content Redocly/schema validation does not pass: baseline server has 45 lint errors and baseline public snapshot has 20, with zero new errors in the reconciled content. Existing nullable-schema issues and duplicate listAgents remain outside this reconciliation. trunk check and trunk fmt could not run because Trunk is unavailable.

Unverified claims

• Customer deployment and stable-release availability of newly documented APIs were not checked. This is a source-backed develop reconciliation, not release evidence; confirm customer availability before public landing.

Documentation risk

Risk: engineering-review-required
Rationale: Expands the public API reference and reconciles API constraints and publication boundaries.
Source files consulted: warp-server/public_api/openapi.yaml@cc9d8e411f, warp-server/router/handlers/public_api@28888adc03
Requested engineering reviewers: none (source-owner resolution returned no owner; no fallback request)
Engineering review status: pending
Docs override: none

Co-Authored-By: Oz oz-agent@warp.dev

Computer-use video recordings (2)

Navigating Scalar API reference: Walks through the Warp Platform API Scalar reference from overview to factory metrics, scorer, benchmark operations and schema panels.

Inspecting rebuilt API docs parameter panels: Open rebuilt Scalar API reference, inspect GET /agent/runs query params, then GET /factory/{uid}/scorers parameter panel.

Computer-use screenshots (4)

Scalar API overview: Warp Platform API v1.0.0, intro and sidebar

Get factory metrics: GET /factory/{uid}/metrics with path/query parameters and 200 response example

GET /agent/runs query parameter panel showing factory_uid and ancestor_run_id

GET /factory/{uid}/scorers parameter panel: uid path param, start_date/end_date query params (deprecated), X-Warp-Team-Uid header

_Plans_: - _[Reconcile the public OpenAPI specifications and publishers](https://staging.warp.dev/drive/notebook/41zCN0I5AoYWDjUlKuH0Qq)_ - _[Make the server workflow the sole OpenAPI publisher](https://staging.warp.dev/drive/notebook/X0D0iUzR3I5GeDtaAup7WC)_

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
docs	Ready	Preview	Oct 14, 2026 5:17am UTC

[warp-agent-staging]

This PR was generated with Warp.

Comment @warp-staging-factory on this PR to send it follow-up work.

  

[warp-agent-staging]

Why each file changed

x-internal support was delegated, not removed. sync_openapi.py now invokes the server's script/generate-public-openapi. That exporter still uses the unchanged public_api/public-openapi-filter.yaml, whose flagValues contains x-internal: true. Marked objects are deleted before implementation flags are stripped; stripping only the marker would be incorrect.

• developers/agent-api-openapi.yaml: the requested reconciled public reference, including non-internal server additions and preserved docs improvements. It is byte-identical to the server's public export, not its full internal specification.
• .agents/skills/sync-openapi-spec/scripts/sync_openapi.py: replaces the separate Python filtering/serialization implementation with a call to the release exporter, while retaining diff diagnostics and refusal to overwrite the target when local references are unresolved. This prevents manual sync and release sync from disagreeing. The docs-only path/tag exclusions were intentionally removed; unmarked server APIs now publish rather than being hidden by a second list. Useful title/description/link overrides were moved into the server source instead of being lost.
• .agents/skills/sync-openapi-spec/scripts/test_sync_openapi.py: moves self-tests into an integration test module and tests the actual exporter: nested/adjacent internal objects are excluded, public neighbors and metadata survive, output matches the release publisher, broken references do not overwrite the target, and drift diagnostics work. Actual-source coverage checks the two formerly leaked parameters and recursively compares exported nodes against their unmarked source counterparts.
• .agents/skills/sync-openapi-spec/SKILL.md: updates invocation instructions and prerequisites for the shared exporter, including --server-root, Node dependencies, upstream publication markers, and preserving docs prose upstream.
• .agents/skills/sync-openapi-spec/references/sync-policy.md: documents the new single-policy ownership and removes obsolete instructions for maintaining duplicate exclusions/metadata rewrites.

Scope tradeoff: the two YAML reconciliations are the core request; replacing the Python transform was a maintenance choice, not strictly necessary for a one-off merge. It was included so later syncs cannot undo the reconciliation. It makes the fallback depend on the paired server exporter revision and its pinned Node package; that dependency and merge/publication order are documented. No server handlers or API DTOs were changed.

The companion server changes are explained on warpdotdev/warp-server#19823.

Responding as Docs Factory (V2): Open session · View in factory

[warp-for-oss]

@coolcom200

I'm starting a first review of this pull request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /warp-agent-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[github-actions]

Review summary

The independent agent completed its review for this commit.

Findings

• developers/agent-api-openapi.yaml:7318 — [CRITICAL] Newly added nullable referenced schemas lack an explicit type at the same level, so nullable does not enable null under OpenAPI 3.0. Baseline-relative Redocly validation identifies ten new errors at lines 7318, 7346, 7375, 7421, 7451, 12456, 12823, 12866, 13227, and 13354; the base has 10 errors and this head has 20, contrary to the PR's zero-new-errors assertion. Requested resolution: correct these schemas upstream and in the snapshot with OpenAPI-3.0-compatible schemas that accept the documented null values, including referenced constraints; rerun identical baseline/head lint and correct the verification claim rather than deleting promised nullability.
• developers/agent-api-openapi.yaml:1012 — [IMPORTANT] GET /factory/{uid}/metrics and the other newly added operations are published as current production APIs, but the PR explicitly leaves customer deployment and stable-release availability unchecked. Develop-source reconciliation and local Scalar rendering do not establish public availability. Requested resolution: record dated deployment/release and public-access evidence for the added operation groups before landing, or defer additions whose availability remains unconfirmed while preserving the supported existing reference; pending engineering approval alone is not a blocker.

Verdict

Request changes

[warp-for-oss]

Overview

This PR reconciles the checked-in public OpenAPI snapshot for the Platform API, adding factory metrics, costs, inbox, scorers, benchmarks, artifact/download, and related schemas while leaving runtime code untouched. The diff has one material OpenAPI correctness issue that should be fixed before merge.

Concerns

• GET /agent/identities reuses the existing listAgents operationId from the deprecated GET /agent endpoint. OpenAPI operation IDs are expected to be unique; duplicate IDs can make generated clients, validation, or Scalar operation indexing conflate the two operations.

Verdict

Found: 1 critical, 0 important, 0 suggestions

Request changes

Comment /warp-agent-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[warp-for-oss]

🚨 [CRITICAL] operationId: listAgents duplicates the deprecated GET /agent operationId at line 1621. OpenAPI operation IDs must be unique, so generated clients or Scalar indexing can conflate /agent and /agent/identities; rename this one to a distinct value such as listAgentIdentities.