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

[hongyi-chen]

Regenerates developers/agent-api-openapi.yaml (the file Scalar renders at docs.warp.dev/api) from the canonical spec in warp-server. Opened from the missing_docs drift-watch audit, which flagged three public endpoints present in the canonical spec but missing from the docs copy.

Source: warpdotdev/warp-server @ b84a4127b8c437e29a0d85e6cfeeef3b20cd468a

Drift resolved

Paths present in source but missing from target:

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

Paths present in target but absent from the source subset:

• - /harness-support/transcript

Paths whose operations differ:

• ~ /agent/artifacts/{artifactUid}
• ~ /agent/identities
• ~ /agent/runs

Schemas added (16): AgentAutoMemoryCreateConfig, AgentAutoMemoryResponse, AgentCredentialStrategy, AgentMemoryCreateConfig, AgentMemoryResponse, AgentMemoryUpdateConfig, AgentType, ExternalReferenceArtifact, ExternalReferenceArtifactData, MemoryStoreAttachmentResponse, ReportRunScoresRequest, ReportRunScoresResponse, ReportedRunScore, ReportedRunScoreOutcome, RunByExternalReferenceResponse, RunMetadata.

Schemas modified (21): AIRunTimelineEvent, AIRunTimelineEventType, AgentResponse, AmbientAgentConfig, ArtifactItem, CloudEnvironmentConfig, CreateAgentRequest, CreateScheduledAgentRequest, FileArtifactData, FileArtifactResponseData, Harness, MCPServerConfig, RequestUsage, RunAgentRequest, RunAgentResponse, RunItem, RunSourceType, RunStatusMessage, ScheduledAgentItem, UpdateAgentRequest, UpdateScheduledAgentRequest.

No ! unclassified paths or tags, so the exclusion policy in scripts/sync_openapi.py needed no changes.

Please confirm before merging

The regenerated subset pulls in memory-related schemas (AgentMemoryCreateConfig, AgentAutoMemoryResponse, MemoryStoreAttachmentResponse, and friends). They arrive not because the memory_stores tag was included — it is still excluded — but because public, non-x-internal agent operations reference them, so the $ref walker keeps them reachable.

That mirrors warp-server's own public/internal classification, which this skill treats as the source of truth. Still worth a human check: Agent Memory is a research preview, so if these fields are not meant to be publicly visible on the agent endpoints yet, the fix belongs in warp-server's public_api/openapi.yaml (mark them x-internal: true) rather than in this generated file. Left as a draft for that reason.

Verification

• --mode self-test passes.
• --mode apply validated every $ref in the output before writing.
• npm run build passes; Scalar parses the regenerated YAML.

Related

Companion PRs from the same audit run: #493 (Warp Agent CLI slash commands) and #494 (surface map and snapshot bookkeeping, which lists this run's deferred findings).

Conversation: https://staging.warp.dev/conversation/7e6d979d-88a2-46f0-90e1-6404a7edc72e
Run: https://oz.staging.warp.dev/runs/019fec9e-026d-7b44-bc62-8d6c8e2ccf6b

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 10, 2026 5:26pm