OpenAPI spec

The full API contract is served at /openapi.json. It is the canonical source of truth, the TypeScript, Python, and Go SDKs are generated from it, and the gateway's request validation derives from the same schemas.

Spec version

OpenAPI 3.1. The spec passes openapi-generator-cli validate with the v7.10.0 generator; consumers requiring stricter validation should test against that version.

Endpoints

Fetch the specbash
curl https://bigballsdata.com/openapi.json

For an interactive request explorer, use the gateway's hosted Swagger UI at /v1/docs. Both surfaces describe the same routes.

Two specs, one contract

Two documents exist in the codebase. They describe the same routes; the difference is provenance:

DocumentSourceUse for
/openapi.jsonHand-curated docs/openapi.yamlSDK generation, public contract, drift baseline
/v1/docs/jsonAuto-derived from runtime Fastify schemasInternal debugging, drift detection

Generating an SDK

The official SDKs are pinned to OpenAPI Generator v7.10.0. To generate a client locally:

Pythonbash
openapi-generator-cli generate \
  -i https://bigballsdata.com/openapi.json \
  -g python \
  -o ./bbs-python \
  --additional-properties=packageName=bbs_client,projectName=bbs-client,version=1.0.0
Gobash
openapi-generator-cli generate \
  -i https://bigballsdata.com/openapi.json \
  -g go \
  -o ./bbs-go

Authentication block

The spec declares two equivalent securitySchemes:

yamlyaml
securitySchemes:
  apiKey:
    type: apiKey
    in: header
    name: x-api-key
  bearer:
    type: http
    scheme: bearer
    bearerFormat: bbs_<env>_<32hex>

Either header authenticates. Generated SDKs default to the bearer scheme.

Caching

The spec changes only when route shape changes. Consumers may cache the document aggressively; the gateway also serves a strong ETag for conditional requests.