OpenAPI spec download

The Minara Agent gateway ships a complete machine-readable description of every endpoint in the OpenAPI 3.1 format. Both equivalent files are served as static assets from this docs site.

Download

• openapi.yaml — human-readable, idiomatic YAML.
• openapi.json — same spec, JSON encoded.

The version field in the spec tracks the agent's package.json version, so a checked-in copy stays comparable across releases.

What's covered

Every route registered in apps/agent/src/gateway/api.ts has a corresponding entry in the spec — including streaming chat (/v1/chat/stream), portfolio and perps surfaces, the personalization rebuilder + memory CRUD, workflow management, and the OAuth flows. CLAUDE.md §8a treats drift between the running gateway and this file as a P1 bug; a coverage test in tests/unit/gateway/route-coverage.test.ts blocks any new endpoint that ships without the matching RouteSpec entry.

How to use it

Swagger UI — open https://editor.swagger.io, File → Import URL, paste the deployed /openapi.yaml URL.

Postman — Import → Link, paste the same URL. Postman recognises servers[].url and pre-fills the host; bearer auth is set up via the bearer security scheme.

openapi-typescript — generate fully-typed client code:

npx openapi-typescript https://your-host/openapi.yaml -o src/api-types.ts

curl smoke test — Authorization: Bearer <GATEWAY_AUTH_TOKEN> if the gateway has auth on:

curl -H "Authorization: Bearer $GATEWAY_AUTH_TOKEN" \
     http://localhost:8080/v1/profile | jq

Local regeneration

The spec is generated at build time from the same ROUTES array that drives the per-route reference pages here. To rebuild after changing apps/agent/src/gateway/api.ts:

npm --prefix docs run generate:openapi
# (or: npm --prefix docs run generate — runs both api + openapi)

The generator writes to docs/public/openapi.{yaml,json}; commit the result alongside your gateway change.