API Reference Notes

The API reference in this repo is served from:

docs/api-reference/openapi.public.yaml

OpenAPI Source Strategy

• CI and production docs builds use the vendored spec in this repository.
• Local contributors can optionally sync from another source with OPENAPI_SOURCE.

How It Works

1. npm run sync:openapi resolves an OpenAPI source with a CI-safe vendored default.
2. The script writes the resolved source to docs/api-reference/openapi.public.yaml.
3. The sync step generates grouped OpenAPI files under docs/api-reference/grouped/.
4. Scalar registers one route per product area at the site root (for example /payments), product-grouped, and hides empty groups automatically.
5. npm run dev and npm run build run sync first.
6. Production OpenAPI viewer settings prioritize Try Request per operation: the standalone client entrypoint stays hidden (hideClientButton), telemetry and MCP integrations are disabled, and browser sends route through Amos’s first-party proxy.docs.amos.com Worker (configured at sync via DOCS_SCALAR_PROXY_URL) instead of Scalar’s hosted proxy.

Product Grouping Taxonomy

The navigation is organized around product areas mapped to Amos domains:

• Payments
• Platforms and Marketplaces
• Billing and Subscriptions
• Money Movement and Reconciliation
• Risk and Access Control
• Events and Webhooks
• Core Data and Files

Grouping logic lives in scripts/sync-openapi.mjs as the TAG_GROUPS map. Update tag assignments there to tune navigation over time.