OpenAPI spec

Goal

Provide a versioned OpenAPI baseline for integration teams, tooling, and future SDK/documentation generation.

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
• observability

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.

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 and idempotency behavior explicit.

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.