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

[hongyi-chen]

What changed

Regenerates developers/agent-api-openapi.yaml (the spec behind the Scalar API reference) from warp-server's canonical public_api/openapi.yaml, and fixes the sync-openapi-spec skill's transform to match warp-server's own publish-time filter.

Rework changes (cycle 1)

• Regenerated against the current warp-server source (ef449bc9c680018b855baafc2c5ce8dabe98136d). The previous revision had drifted at /agent/runs and the AgentResponse, AmbientAgentConfig, CreateAgentRequest, Error, RunSourceType, and UpdateAgentRequest schemas.
• Mirrored warp-server's stripFlags policy in the sync script. scripts/sync_openapi.py previously only stripped the x-internal marker, and only from top-level operations. It now recursively strips x-internal, x-enum-varnames, x-go-type, x-go-type-import, x-go-type-skip-optional-pointer, x-oapi-codegen-extra-tags, x-stainless-deprecation-message, and x-stainless-naming from every object in the regenerated spec.
• Confirmed with the API owner that the schemas reachable through the public POST /agent/identities request/response contract are intentionally public as-is; no schema needs to be marked x-internal for this sync.

Rework changes (cycle 2)

• Fixed a leak the cycle-1 stripFlags pass left behind. Removing only the x-internal marker key (not the object it marks) left several internal-only fields published but unmarked: the factory_uid/automation_id query parameters on GET /agent/runs and GET /agent/identities, and the factory_uid/agent_type properties on CreateAgentRequest, UpdateAgentRequest, and AgentResponse.
• Added _prune_internal to sync_openapi.py, which mirrors openapi-format's flagValues semantics from warp-server's public-openapi-filter.yaml: it deletes the entire object marked x-internal: true wherever it appears in the tree (a schema property, a parameter, an operation, a tag, a whole schema) as the very first step of the transform, before any other rule runs. All of the fields listed above are now absent from the regenerated file.
• Added regression coverage for an internal query parameter and an internal schema property (the self-test previously only covered internal operations and tags).

Public operations added (relative to the previously merged copy)

• GET /agent/artifacts/{artifactUid}/download
• GET /agent/run-by-external-reference
• POST /agent/runs/{runId}/scores

Also in the diff: /harness-support/transcript drops out (warp-server now marks it internal), /agent/artifacts/{artifactUid}, /agent/identities, and /agent/runs pick up operation changes, and the reachable schema set is refreshed (including the deprecation of base_harness in favor of harness on agent identities, and a new ORCHESTRATION run source).

Validation

• python3 .agents/skills/sync-openapi-spec/scripts/sync_openapi.py --mode self-test → self-test: OK (covers both the stripFlags regression case and the internal-parameter/internal-property pruning case; verified each fails without its corresponding fix)
• --mode diff --source ../warp-server/public_api/openapi.yaml --target developers/agent-api-openapi.yaml → In sync. No changes needed.
• --mode apply → All $refs resolve in the regenerated spec.; a full-file scan confirms zero remaining x-* extension keys, and factory_uid/automation_id/agent_type no longer appear anywhere in the file
• npm run build passes
• Exercised the rendered Scalar API reference (/api) via computer use against a local dev server: GET /agent/run-by-external-reference and both /agent/runs operations render correctly with their parameters and example bodies; no memory_stores, harness-support, or factory tag/operation appears anywhere in the sidebar or search; the CreateAgentRequest and AgentResponse model pages were inspected property-by-property and no longer include factory_uid, automation_id, or agent_type; no literal x-* extension text is visible anywhere on the page.

Visual proof

Computer-use screenshots (3)

Reviewers

scripts/suggest_reviewers.py found no owner entries for warp-server:public_api/openapi.yaml, router/handlers/public_api/agent_artifacts.go, run_score_reports.go, or agent_webhooks.go, and the requester's GitHub handle could not be resolved automatically, so this still needs manual assignment to the Oz API owners.

Found by

The missing_docs drift-watch audit (three public API endpoints missing from the spec).

Originating thread: https://warpdev.slack.com/archives/C09BVK0PL3Y/p1786727807612589

Conversation: https://staging.warp.dev/conversation/1bda9ae7-44b1-43c5-bb7a-d22ccf8b6c16
Run: https://oz.staging.warp.dev/runs/019ff6ea-bc3c-7336-b1f5-9f1f5b89cd84

This PR was generated with Oz.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview	Aug 14, 2026 7:20pm

[oz-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 /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[oz-for-oss]

Overview

This PR regenerates developers/agent-api-openapi.yaml from the canonical warp-server OpenAPI spec. The attached review diff does not include a patch for the only changed file, so I could not inspect the generated API changes, validate the memory-related public surface called out in the PR description, or perform a meaningful security/spec-alignment review against changed lines.

Concerns

• ⚠️ The annotated diff only says Patch unavailable from GitHub for this file. Please rerun this review with an attached patch or split/provide the generated OpenAPI diff so reviewers can verify the endpoint/schema changes before merge.

Verdict

Found: 0 critical, 1 important, 0 suggestions

Request changes

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

Powered by Oz

[warp-agent-staging]

Review summary

The OpenAPI document parses and the docs build passes, but this branch is not the latest filtered output from warp-server/public_api/openapi.yaml. An API-owner decision is also required for the Agent Memory configuration exposed through the public agent identity contract.

Verdict

Request changes

[warp-agent-staging]

❓ [QUESTION] The sync policy says Agent Memory remains a research preview, yet this schema is reachable from the public agent-identity create/update/request-response contract and will render in the public Scalar reference. Is that public exposure intentional? If not, the API owner needs to mark the relevant contract internal or otherwise remove it from the public source before this sync is regenerated.

[warp-agent-staging]

Confirmed with the API owner: the current public exposure through the POST /agent/identities request/response contract is intentional as-is, so no schema needs to be marked x-internal for this sync. Leaving this thread open for your explicit sign-off.

[warp-agent-staging]

Overview

Cycle-2 re-review confirms that the published OpenAPI spec now matches the canonical server public subset. Internal parameters and schema properties marked x-internal are pruned before extension stripping, generated references resolve, CI and the docs build pass, and the rendered Scalar reference matches the expected public surface.

Verdict

Approved — the prior requested changes are addressed at deba7f2.