OpenAPI bundle
The documentation site ships a static OpenAPI 3.0 JSON file for download and tooling:
- Path in this repo:
docs-site/api-reference/openapi.json (checked into bd-forge-main next to Mintlify content).
- Consumers: Use that file for codegen, contract tests, and schema inspection. In-product interactive explorer (Swagger/Scalar/Redoc) for the public docs site — implementation detail pending verification (tracked separately from the artifact itself).
Relation to apps/web
The apps/web Next.js app exposes a generated spec at runtime:
- Handler:
apps/web/app/api/openapi.json/route.ts → generateOpenAPISpec() from apps/web/lib/api/openapi-spec.ts.
- Title in spec:
BetterData SCM API (see openapi-spec.ts).
Whether production traffic serves docs-site/api-reference/openapi.json and apps/web’s /api/openapi.json as the same document in all environments is an implementation detail pending verification — compare byte-for-byte or info.version after deploy when aligning clients.
SCM workspace API (tenant)
Narrative overview and auth patterns for the tenant API live under API overview and Authentication.
Do not commit secrets or private URLs into OpenAPI servers entries when publishing public docs.
