docs: serve api-catalog by enabling download-spec

[all-hands-bot]

Summary

The docs site advertises a machine-readable API catalog in its Link header:

link: </llms.txt>; rel="llms-txt", ..., </.well-known/api-catalog>; rel="api-catalog", ...

…but https://docs.openhands.dev/.well-known/api-catalog currently returns 404, because no OpenAPI download is configured for the project.

Mintlify publishes the RFC 9727 linkset at /.well-known/api-catalog when download-spec is present in contextual.options. The catalog links each OpenAPI spec declared in docs.json — including the OpenHands Cloud spec (/openapi/openhands-cloud.json) — so agents can discover the Cloud API without crawling the docs.

This change adds "download-spec" to contextual.options so the advertised catalog resolves and points at the Cloud API (and the Agent Server spec).

Validation

• docs.json parses as JSON.
• No other navigation/content changes.

Note

Enabling download-spec also adds a "Download API spec" entry to the page context menu, and (per Mintlify docs) the downloaded spec is unfiltered — i.e. it does not respect authentication groups. This site is public, so no group-restricted endpoints are exposed.

This pull request was created by an AI agent (OpenHands) on behalf of the user.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
all-hands-ai	🟢 Ready	View Preview	Oct 4, 2026, 5:18 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

[enyst]

@OpenHands /codereview and post your feedback with event approved or request changes or comment as you think appropriate.

[openhands-ai]

Uh oh! There was an unexpected error starting the job :(

[enyst]

Reviewed and verified against Mintlify docs plus the live production/preview sites.

What's correct ✅

• The change is minimal and does exactly what it says. Mintlify's docs confirm it: enabling download-spec publishes the RFC 9727 linkset at /.well-known/api-catalog, and without it the path returns 404.
• Production today: https://docs.openhands.dev/.well-known/api-catalog → 404 (matches the problem statement).
• Preview (allhandsai-docs-api-catalog-download-spec.mintlify.site): /.well-known/api-catalog → 200, valid application/linkset+json.
• The security note is accurate: docs.json has no auth/userAuth, and every spec is served publicly (200), so the "unfiltered spec" caveat in the Mintlify docs doesn't apply here.

One discrepancy worth resolving ⚠️

The Summary says the catalog exposes "the OpenHands Cloud spec … and the Agent Server spec" (two specs). The preview catalog actually returns three:

Title	Version	Source file
OpenHands	0.0.1	openapi/openhands-cloud.json (Cloud REST API)
OpenHands Agent Server	0.1.0	openapi/agent-sdk.json
OpenHands	0.53.0	openapi/V0_openapi.json (legacy V0 REST API)

V0_openapi.json is not referenced anywhere in docs.json — only agent-sdk.json and openhands-cloud.json carry "openapi": {"source": ...} navigation entries — and AGENTS.md explicitly marks it "legacy". So enabling download-spec also makes the deprecated V0 REST API (whose servers point at https://app.all-hands.dev) machine-discoverable to agents, and introduces a second spec titled "OpenHands" (v0.53.0) that is easy to confuse with the current Cloud spec (v0.0.1).

Not a blocker for the change itself — please just confirm exposing the legacy V0 spec is intended, or exclude/handle V0_openapi.json so the catalog advertises only the two current specs; and update the summary to mention the third spec if it stays.