api

---

description: Rules for working in the API service (NestJS backend) globs: apps/api/**/* alwaysApply: false

API Service

Stack: NestJS + Express · MongoDB (via libs/dal) · Redis + Bull · ClickHouse (analytics/traces) · Clerk or Better Auth · @nestjs/swagger

Run: pnpm start:api:dev — port 3000, OpenAPI at http://localhost:3000/openapi

Tests/lint: see testing.mdc

Key directories:

apps/api/src/app/                          # Route controllers and modules
apps/api/src/ee/                           # Enterprise-only features
apps/api/migrations/                       # MongoDB migrations
apps/api/migrations/clickhouse-migrations/ # ClickHouse schema migrations

---

API Service Conventions

Controllers

• Every protected route must use @RequireAuthentication().
• Routes accessible via user API keys or the official SDK must also use @ExternalApiAccessible.
• Routes accessible via Clerk OAuth (DCR) access tokens must also use @OAuthAccessible.
• Controller method names follow: getEntityName, listEntityName, createEntityName, updateEntityName, deleteEntityName.
• List endpoints must support pagination and use @SdkUsePagination.
• Group SDK endpoints with @SdkGroupName using . as the subresource separator (e.g., Subscribers.Notifications).

Use-cases (CQRS)

• Business logic lives in use-case classes, not controllers.
• Use-cases receive a typed command/query and return a typed result via execute(command).
• Never put database queries directly in controllers.

Database

• Always use libs/dal repositories for all queries; see dal-repository.mdc for enforcement rules.

OpenAPI

• Every endpoint must have @ApiOperation, @ApiResponse, and @ApiTags decorators.
• Validate with npm run lint:openapi (run with API started) before submitting a PR.

Migrations

• Place migration scripts in apps/api/migrations/<change-description>/<change-action>.ts.
• Run via npm run migration -- ./migrations/<path>.ts.
• Never rename existing migration scripts — they are referenced in user-facing docs.

Canonical example: @apps/api/src/app/tenant/tenant.controller.ts