​
What this API is

The House of Journeys distribution API is a source-agnostic HTTP layer in front of your content CMS. Clients integrate against stable JSON DTOs and OpenAPI — not raw upstream shapes.
  • Auth: OAuth2 client credentials (POST /v1/oauth/token) or API keys (Authorization: Bearer plus your API key).
  • Brand / tenant routing: Product and category routes resolve brand (and optional server defaults) using GET /v1/distribution-channels.
  • Recommendations: Ranked product lists are available under /v1/recommendations/* with the same brand + locale flow and HoJ auth.
  • Contracts: OpenAPI 3.1 lives in the repo at packages/contracts/openapi/hoj-distribution-v1.openapi.json and is served at runtime as GET /v1/openapi.json.

​
Documentation experience

This site is built for Mintlify (or compatible static hosts):

​
Suggested next steps

1

Run the BFF locally

From the monorepo: npm install, configure apps/bff/.env, then npm run dev. Default base URL: http://localhost:8080.
2

Authenticate

See Authentication — use a dev API key or OAuth token, then call /v1/* routes.
3

Try the API Reference tab

Select Local or Staging as the server, paste your bearer token (dev playground may pre-fill a dev key from OpenAPI x-default), and execute requests.

​
Recommendations (DX)

  • CI: Run npm run docs:sync-openapi whenever the canonical OpenAPI file changes, then commit developer-docs/openapi/ so Mintlify stays in sync.
  • SDKs: Generate clients with OpenAPI Generator or Stainless from hoj-distribution-v1.openapi.json.
  • Changelog: Keep CHANGELOG.md in sync with breaking vs additive changes (deprecation policy).
  • Status: Provide a public status page (e.g. Better Stack, Instatus) for api.hofj.com and staging.
  • Rate limits: Document 429 + retryAfterSeconds for integrators (see registry quotas in the main README).