OpenAPI spec

Goal

Provide a versioned OpenAPI baseline for integration teams, tooling, and future SDK/documentation generation, aligned with the real /api/... routes served by the Beacon app.

Available artifacts

• Source file: openapi/beacon.yaml
• Public static endpoint: /docs/api/openapi.yaml
• API reference landing: /docs/api

Current coverage

• billing
• stripe connect
• webhooks
• fiscal
• platform healthcheck

How to use it today

1. Validate request/response contracts during integration implementation.
2. Generate internal test clients from stable schemas.
3. Diff the spec on each release to detect potential breaking changes.
4. Cross-check the YAML with the MDX reference pages when an operational payload is still evolving.

Evolution rules

• Breaking changes require explicit version strategy at endpoint or field level.
• New fields must remain backward-compatible and documented in changelog.
• Critical operations should keep error semantics explicit and document when deduplication is internal rather than a public header.

Prepared for dedicated API UI

This spec is already organized to support Scalar or Redoc adoption without structural refactor:

• functional tags;
• reusable schemas under components;
• endpoint-level operational summaries.

Relation with LLM tooling

• Every API page has raw markdown available at /docs/raw/....
• llms.txt lists canonical docs URLs and LLM-ready sources.
• This supports controlled indexing without exposing private infrastructure.