docs: sync agent-api-openapi.yaml from warp-server

[hongyi-chen]

Summary

Regenerates developers/agent-api-openapi.yaml (the file Scalar renders at docs.warp.dev/api) from the canonical warp-server spec at commit 1b2b8769, using the sanctioned tool:

python3 .agents/skills/sync-openapi-spec/scripts/sync_openapi.py \
  --mode apply --source ../warp-server/public_api/openapi.yaml \
  --target developers/agent-api-openapi.yaml

Surfaced by an exhaustive missing_docs drift-watch run. The standing audit could not see this: it checks route-to-spec presence by parsing literal gin registrations, and the conversation routes are registered through generated handlers (public_api_types.RegisterHandlersWithOptions in agent_conversations.go), so they never enter the audit's route universe at all.

Changes

developers/agent-api-openapi.yaml

Path added (1):

• GET /agent/conversations/{conversation_id}/transcript — returns a 302 to a time-limited transcript download URL. Tagged agent, bearerAuth, and not marked x-internal, so the sync policy classifies it as public. It backs the raw third-party-harness transcript output shipped in v0.2026.09.02.08.27.stable_01 (#15642), and its sibling GET /agent/runs/{runId}/transcript is already published.

Paths with changed operations (11): /agent, /agent/artifacts/{artifactUid}, /agent/connected-self-hosted-workers, /agent/environments, /agent/identities, /agent/run, /agent/runs, /agent/runs/{runId}/cancel, /agent/runs/{runId}/followups, /agent/runs/{runId}/scores, /agent/schedules

Schemas added (4): ChargedUsageDetail, InferenceCostBreakdownUsd, InferenceUsageDetail, TokenCountBreakdown — all reachable from RequestUsage on the released run paths.

Schemas modified (19): AIRunTimelineEvent, AgentCredentialStrategy, AgentResponse, AmbientAgentConfig, CloudEnvironmentConfig, CreateAgentRequest, Error, FileArtifactData, FileArtifactResponseData, Harness, RequestUsage, RunAgentRequest, RunExecutionLocation, RunItem, RunMetadata, RunSourceType, RunStatusMessage, SessionSharingConfig, UpdateAgentRequest

Top-level info also refreshed. No paths or operations were removed.

Public/private safety checks

The --mode diff run reported no ! unclassified tags or paths, so the policy in references/sync-policy.md recognized every item. Verified on the regenerated output:

• Unreleased namespaces present: none — no /factory, /harness-support, or /memory_stores path survives.
• Implementation-only x-* extension keys remaining: none.
• Operations removed relative to main: none.
• --mode apply confirmed All $refs resolve in the regenerated spec.

⚠️ Related: do not merge automation/sync-agent-api-spec as-is

While verifying this change I compared it against the release automation's unmerged branch automation/sync-agent-api-spec (last pushed 2026-09-04, no open PR). That branch would publish 16 endpoints this policy deliberately excludes:

• 15 /factory* endpoints — the Factory REST API has not shipped publicly, and this repo's ledger carries ~12 Gate 0 deferrals for exactly these routes.
• GET /harness-support/transcript — worker-to-server contract, permanently excluded ("customers should not call them directly").

Plus 41 Factory schemas (Factory, FactoryCredentialStrategy, CreateScorerRequest, …).

Root cause: warp-server's publisher filters only on x-internal: true, and those Factory operations are not marked internal — several are even tagged agent upstream. The docs-side policy catches them via EXCLUDED_PATH_PREFIXES = ['/factory'], which is why this PR's output is the safe subset (31 operations) and the automation branch's is not (47).

Suggested follow-up for the server team: mark those Factory and harness-support operations x-internal: true upstream so both publishers agree, per references/sync-policy.md → "Adding a new exclusion". Until then, prefer this manually regenerated subset over the automation branch.

Validation

• sync_openapi.py --mode self-test → self-test: OK
• sync_openapi.py --mode apply → All $refs resolve in the regenerated spec.
• npm ci && npm run build → Complete, 383 pages, Scalar parsed the YAML without error

Notes for reviewers

references/sync-policy.md names warp-server's release automation as the authoritative publisher and this skill as the manual fallback. I reached for the fallback because there is no open sync PR, the published reference is missing an endpoint that shipped in the current stable release, and the automation's staged output is unsafe to merge (above). Close this in favor of the automation if the server team fixes the x-internal markers and re-runs it.

/cc @rachaelrenk @dannyneira — no CODEOWNERS entry resolves for warp-server/public_api/ or router/handlers/public_api/, so this used the documented fallback chain. Real review requests are attached. Note: hongyi-chen (the second-tier fallback) could not be attached — gh pr edit --add-reviewer exited 0 but the reviewer never appeared in the read-back, so the chain advanced.

Unverified claims

None — every path, operation, and schema in this file is mechanically generated from the canonical source spec named below. No prose was hand-written.

Documentation risk

Risk: engineering-review-required
Rationale: Regenerated public API reference: adds a released endpoint and changes API response schema claims.
Source files consulted: warp-server/public_api/openapi.yaml@1b2b8769, warp-server/router/handlers/public_api/agent_conversations.go@1b2b8769
Requested engineering reviewers: rachaelrenk, dannyneira
Engineering review status: pending
Docs override: none

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

[vercel]

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

Project	Deployment	Actions	Updated
docs	Ready	Preview	Sep 7, 2026 5:17pm UTC

[github-actions]

Review summary

The independent agent completed its review for this commit.

Findings

• No blocking findings.

Verdict

Approve

[warp-for-oss]

@hongyi-chen

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

[warp-for-oss]

Overview

This PR refreshes the generated public Warp Agent API OpenAPI spec and adds the conversation transcript endpoint plus updated schemas. The generated subset still publishes Factory-specific components and run-source documentation even though the sync policy says Factory API surfaces are excluded from the public reference.

Concerns

• components.responses.FactoryAccessDenied is added to the public spec as an unpruned Factory-only reusable response.
• RunSourceType now documents Factory benchmark and automation sources in the public Agent API schema.

Verdict

Found: 0 critical, 2 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]

⚠️ [IMPORTANT] This keeps a Factory-only reusable response in the public OpenAPI components even though the sync policy excludes Factory surfaces. Because components.responses are copied verbatim, remove or prune unreferenced/private response components before publishing.

[warp-for-oss]

⚠️ [IMPORTANT] These enum descriptions publish Factory-specific run sources in the public Agent API despite the sync policy excluding Factory surfaces. Mark these values internal upstream or filter them from the docs subset until the Factory API is public.