OpenAPI / Swagger Contract

Last updated: 2026-02-17

Bounded Health publishes an OpenAPI 3.1 contract for enterprise integration.

1. Contract endpoint

• GET /api/openapi
• Content type: application/json
• Cache policy: short-lived cache for discoverability

2. What is documented

The spec includes:

• Security schemes:
  • ApiKeyAuth (x-api-key)
  • ClerkBearer (browser/client session token)
  • ScimBearer (SCIM bearer token)
• Enterprise route groups:
  • API key management
  • webhook management
  • exports and cohort upload
  • FHIR resources
  • SSO/SCIM/SAML endpoints
  • version and metadata endpoints

3. Generate SDKs

Example using OpenAPI Generator:

TypeScript Axios SDK:

openapi-generator-cli generate \
  -i https://<host>/api/openapi \
  -g typescript-axios \
  -o ./sdk/Bounded Health-ts

Java SDK:

openapi-generator-cli generate \
  -i https://<host>/api/openapi \
  -g java \
  -o ./sdk/Bounded Health-java

TypeScript package scaffold in-repo:

npm run sdk:ts:build

Contract snapshots:

npm run contracts:export

Snapshot output:

• docs/integration-opportunities/contracts/openapi.enterprise.v1.json
• docs/integration-opportunities/contracts/asyncapi.webhooks.v1.json

4. Client implementation guidance

• Configure API version header globally: x-api-version
• Inject auth per route family:
  • x-api-key for enterprise API routes
  • SCIM bearer token for /api/scim/*
• Implement standardized error handling from documented status codes
• Use /api/asyncapi for webhook consumer contract tooling

5. Contract change policy

• Backward-compatible changes can ship within the same version
• Breaking changes require a new published API version
• Keep generated SDKs pinned to a known /api/openapi snapshot during release cycles