This workspace owns the canonical API host. External integrations should use the /v1 routes documented by OpenAPI; API-owned usage and billing webhook handlers now run in this runtime rather than through web-runtime proxies.

Endpoints

GET /v1/health returns a lightweight JSON health payload.
GET /healthz returns liveness status and GET /readyz returns readiness/dependency status for infrastructure checks.
GET /v1/openapi.json and GET /v1/docs expose the API contract.
GET /v1/session/current-user requires Authorization: Bearer <API_ACCESS_TOKEN> and returns the authenticated service principal.
POST /v1/api-keys/validate validates apiKey from the JSON body, x-api-key header, or bearer token and returns { "active": true, "keyType": "service-token" } for the configured service token.
GET /v1/accounts, GET /v1/accounts/:id, and GET /v1/usage expose service/API-key scoped account and usage metadata.
/v1/entities/*, /v1/relationships/*, /v1/exports/*, and /v1/workspaces/* expose the current tenant-scoped API surface.
POST /v1/billing/stripe/webhooks and POST /v1/events/webhooks/attempts/:id are signed webhook ingress routes.

Use /v1/openapi.json and apps/api/src/route-access-inventory.ts for the detailed route inventory.

Auth and Request IDs

Set API_ACCESS_TOKEN in the API environment to enable the service-token primitives. Missing or invalid credentials return JSON error envelopes with stable error.code, error.message, and error.requestId fields without echoing token values. Requests may provide x-request-id; the API echoes it in the response header and includes it in JSON error bodies for correlation. If no request ID is supplied, the API generates one.

Scripts

pnpm --filter @toolctrl/api dev starts the API with tsx watch.
pnpm --filter @toolctrl/api build compiles src/ to dist/.
pnpm --filter @toolctrl/api start runs the compiled server.
pnpm --filter @toolctrl/api typecheck runs TypeScript without emitting files.

The server listens on API_PORT when set, falls back to PORT, and otherwise defaults to 3001.

Extraction Notes

Keep src/app.ts focused on Hono app composition so tests, adapters and future deployment targets can import the app without starting a listener.
Keep newly extracted API behavior in focused API modules instead of growing src/app.ts with service logic.
Keep shared environment validation in @toolctrl/config and update the catalog when API runtime keys change.