Support OpenAPI 3.2 tag hierarchy in the API reference

[vorporeal]

Summary

The API reference uses Scalar 1.57.1, which ignores OpenAPI 3.2 tag.parent and tag.summary fields and renders hierarchical tags as a flat list. This PR upgrades Scalar to 1.74.0 so hierarchies published by the normal release-candidate spec sync render as nested navigation.

The checked-in OpenAPI spec remains unchanged from origin/main. Release automation remains responsible for generated spec updates and reviewable sync PRs.

Changes

• Upgrade the embedded Scalar API reference from 1.57.1 to 1.74.0.
• Preserve summary and parent in the manual sync tool, retain hierarchy ancestors for published operations, and prune unused leaf tags.
• Extend the manual sync self-test to cover OpenAPI 3.2 tag hierarchy metadata.
• Read the OpenAPI version shown beside the YAML and JSON downloads from developers/agent-api-openapi.yaml instead of hardcoding it.

Review guide

Start with the transform and self-test in .agents/skills/sync-openapi-spec/scripts/sync_openapi.py, then review the dynamic version labels in astro.config.mjs and the Scalar version change in src/pages/api.astro.

developers/agent-api-openapi.yaml has no diff. The release-candidate workflow will publish the hierarchy after the corresponding server changes are released.

Validation

• uv run --with pyyaml -- python3 .agents/skills/sync-openapi-spec/scripts/sync_openapi.py --mode self-test
• npm run typecheck
• npm run test:heading-vars
• npm run build
• npm run test:heading-tocs
• npm run test:homepage-json-ld
• git diff --check
• Browser compatibility verification using the pending OpenAPI 3.2 hierarchy from warpdotdev/warp-server#19880: Agents nests Scheduled Agents and Networking; Factories nests Metrics, Scorers, and Benchmarks; the empty Inbox Notifications tag is absent; no console errors were reported.

The screenshots below document that compatibility test. The pending OpenAPI 3.2 spec used for the test is not part of this PR.

Computer-use screenshots (2)

Scalar API reference sidebar with Factories expanded showing nested child groups Metrics, Scorers, Benchmarks (browser zoomed out)

Scalar API reference at 100% zoom with Factories expanded in sidebar showing endpoints and the nested Metrics child group

Unverified claims

None. Scalar behavior and the manual sync transform were verified with the pending OpenAPI 3.2 hierarchy.

Documentation risk

Risk: low
Rationale: Docs rendering and sync tooling only; no API specification content or API behavior changes.
Docs override: none

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	Oct 15, 2026 5:54pm UTC

[warp-for-oss]

@vorporeal

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 updates the OpenAPI sync transform to preserve OpenAPI 3.2 tag hierarchy metadata, updates Scalar, and refreshes the generated API reference. The transform change and Scalar pin look aligned with the stated goal, but the generated reference misclassifies one factory task lookup endpoint under the new Metrics group. No separate approved spec context was present, and the security pass did not find additional issues.

Concerns

• getFactoryTaskByRun is now tagged factory-metrics, which will place a task lookup endpoint under Metrics despite its route, summary, and response schema matching the adjacent factory task lookup endpoints.

Verdict

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

@vorporeal

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 updates the OpenAPI sync tooling to preserve OpenAPI 3.2 tag hierarchy metadata, prunes unused tags while retaining ancestors for referenced operations, updates the self-test coverage, reads the OpenAPI version into the llms.txt optional-link descriptions, and upgrades Scalar for hierarchy rendering. The spec-context attachment contains no approved or repository spec, and the reviewed changes do not introduce security concerns.

Concerns

• No blocking concerns found.

Verdict

Found: 0 critical, 0 important, 0 suggestions

Approve

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

• No findings.

Verdict

Approve