## 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](/docs/api/openapi.yaml)
- API reference landing: [/docs/api](/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.

<Note title="Current status">The spec models the most stable public endpoints currently exposed. When a detail is not in YAML yet, treat the matching MDX page as the required complement.</Note>