Client API Contract

Status: active source of truth for browser-facing HTTP payloads.

Source Of Truth

Artifact	Purpose
doc/openapi/client-api.openapi.yaml	Canonical client-facing backend HTTP contract.
doc/openapi/client-api-reference.md	Clean VitePress redirect page for the generated reference.
shared/src/generated/client-api.d.ts	Generated TypeScript schemas and operation types.
doc/public/openapi/client-api-reference/index.html	Generated Redoc API reference for VitePress builds.
doc/public/openapi/client-api.openapi.yaml	Published copy of the OpenAPI YAML for docs users.
frontend/src/lib/api/client-api-types.ts	Frontend type aliases and graph-specific adapters.
frontend/src/lib/api/routes.ts	Frontend BFF route helpers for /api/backend/*.

Run this from the repo root in CI or before review:

pnpm run openapi:verify

Run generation only when intentionally updating the generated TypeScript file:

pnpm run openapi:generate

Build scripts should not silently regenerate tracked contract files. openapi:verify validates the spec and uses openapi-typescript --check to fail when shared/src/generated/client-api.d.ts is stale.

The docs build can generate static documentation artifacts because they are ignored build output:

pnpm run openapi:docs

The generated full-screen reference is available at Client API Reference.

Boundary

The OpenAPI spec covers routes the active frontend can call through the frontend Backend-for-Frontend proxy.

Browser code calls:

/api/backend/*

The Next.js proxy forwards those requests to:

/api/v1/*

Auth routes under frontend/src/app/api/auth/* are frontend-owned wrappers around the backend SIWE/session routes.

The spec does not define backend in-process module contracts. Those types should live beside the backend module that owns the state and rules.

Client Surfaces

The generated reference is grouped by product-facing client surfaces. Route paths may still contain backend module names while the monolith is small; the tags describe how frontend code should think about the API.

Surface	Backend routes	Frontend purpose
Auth	/api/v1/auth/*, /api/v1/me	SIWE challenge/verify, session refresh/logout, current user.
Clones	/api/v1/clone/clones*	Clone list/detail/update and entitlement summary.
Workflow	Clone strategy, backtest, decision-run, and latest-data routes	Strategy drafts/versions, backtest jobs, decision history, and workflow data previews.
Auditions	/api/v1/economy/audition-fee/*, /api/v1/lifecycle/auditions*	Quote/confirm audition deposits and submit/read audition progress.
Contest	/api/v1/lifecycle/arena*, /api/v1/lifecycle/promotion-queue	Arena and Promotion Queue reads.
Profiles	/api/v1/clone/*/public-profile, /api/v1/public/clones/*	Owner profile editing and public profile/report reads.
Discovery Data	/api/v1/assets, /api/v1/polymarket/*, /api/v1/defillama/*, /api/v1/ingestion/*	Strategy builder asset/data-source search and health surfaces.

Backend Rules

• Backend route adapters in backend/src/api/server.ts and backend/src/api/routes/* may import generated OpenAPI operation/schema types.
• Backend modules in backend/src/modules/* must not import OpenAPI types; their contracts stay module-local.
• backend/test/client-api-contract.test.ts checks the frontend BFF allowlist against the non-auth OpenAPI route surface.

Frontend Rules

• Import generated-derived payload types from frontend/src/lib/api/client-api-types.ts.
• Build product API URLs with frontend/src/lib/api/routes.ts.
• Do not import from frontend/src/lib/shared; the copied shared-contract directory has been removed.
• Do not call backend module-only functions from browser code. Browser code should go through the BFF proxy.
• If a frontend workflow needs a graph-specific type, adapt the generated type locally instead of widening the OpenAPI schema beyond the HTTP contract.