# @toolctrl/api

Dedicated Hono API application for `api.<domain>/v1`.

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.