# API Reference This is a navigational overview of the API surface exposed by `@micprotocol/api` (NestJS). It is intentionally not exhaustive — for request/response shapes, use the live Swagger UI at `http://localhost:4000/api/docs` after starting the API, or read the controllers in [`apps/api/src/`](../apps/api/src/). The API exposes three transports: 1. **REST** — public REST endpoints under `/api/v1/…` plus the guest portal under `/portal/…` and integrations under `/integrations/webhooks/…`. Swagger auto-documents most of it. 2. **tRPC** — typed procedures consumed by `@micprotocol/web`, `@micprotocol/admin`, and `@micprotocol/mobile`. Composed in [`apps/api/src/trpc/`](../apps/api/src/trpc/). 3. **Socket.io WebSockets** — real-time push to clients, namespaced by workspace. Gateway: [`apps/api/src/websocket/events.gateway.ts`](../apps/api/src/websocket/events.gateway.ts). ## Transports ### tRPC The root app router merges per-domain routers; each domain lives in its own folder under `apps/api/src/`. Inputs are validated with Zod schemas shared from `@micprotocol/shared-types` — same package on web, mobile, and admin. Key middleware: | Middleware | File | Purpose | |---|---|---| | Idempotency | `apps/api/src/trpc/trpc-idempotency.middleware.ts` | Dedupes mutations via idempotency keys | | Rate limit | `apps/api/src/trpc/trpc-rate-limit.middleware.ts` | Redis-backed per-IP + per-workspace limits | ### Socket.io events | Event | Direction | Payload | Consumer | |---|---|---|---| | `guest:status_changed` | Server → Client | `{ guestId, oldStatus, newStatus, timestamp }` | Kanban board auto-refresh | | `outreach:email_opened` | Server → Client | `{ messageId, guestId, openedAt }` | Outreach activity feed | | `booking:confirmed` | Server → Client | `{ episodeId, startTime, guestName }` | Dashboard notification banner | | `asset:submitted` | Server → Client | `{ requestId, assetType, guestName }` | Episode production checklist | | `recording:session_ready` | Server → Client | `{ episodeId, meetLink }` | Host pre-recording alert | Namespace scoping is per-workspace (`/ws?workspaceId=…` plus the JWT bearer in `Authorization`). ### mic-realtime (separate Erlang/OTP service) Real-time chat fanout, presence, and live domain events are handled by `mic-realtime` (`:4001`), not the NestJS Socket.io gateway. The API publishes events into mic-realtime via its `/internal/dispatch` HTTP API; clients open a second WebSocket to `MIC_REALTIME_PUBLIC_URL`. See [Self-Hosted Stack → mic-realtime](./self-hosted-stack.md#mic-realtime). ## Health & Monitoring ``` GET /health Basic liveness check (200 OK) GET /health/detailed Full system health (DB, Redis, search, storage) GET /health/ready Kubernetes readiness probe GET /health/live Kubernetes liveness probe GET /tracing/spans Recent execution spans + p95 latency GET /tracing/metrics Aggregate metrics (request count, error rate) GET /integrations/health Reachability of every self-hosted integration ``` Every response carries `X-Trace-Id` (`tr-xxxxxxxx`) and `X-Response-Time` (`ms`) for distributed tracing. ## Module Map Each folder under `apps/api/src/` is a bounded context (domain module). | Module | Folder | What it owns | |---|---|---| | Auth | `auth/` | Clerk JWT verification, webhook handling | | Users | `users/` | User profile + settings | | Workspace | `workspace/` | Workspaces, members, roles (`Owner|Admin|Editor|Viewer`) | | Podcast | `podcast/` | Podcast CRUD, recording + outreach defaults, calendar integration | | Guest | `guest/` | Guest CRM, priority scoring, tags, AI enrichment triggers | | Outreach | `outreach/` | Sequences, templates, message tracking, scheduling | | Scheduling | `scheduling/` | Bookings, availability, calendar sync (Nylas + Cal.com) | | Assets | `assets/` | Asset requests, submissions, AI validation | | Recording | `recording/` | Double-ender sessions, Green Room diagnostics, chunked upload, edge processing | | Content Studio | `content-studio/` | Viral clip detection, scoring, export jobs | | Analytics | `analytics/` | Funnel metrics, time-to-book, snapshot jobs | | Network | `network/` | Verified Guest Network — public profiles, reputation, search, bookings | | Tasks | `tasks/` | Workspace tasks | | Diary | `diary/` | Time-series diary entries | | Chat | `chat/` | Conversations, messages, reactions, media comments (backed by mic-realtime) | | Notifications | `notifications/` | Push channels, preferences | | Billing | `billing/` | Stripe + Paystack + M-Pesa subscriptions and webhooks | | Portal | `portal/` | Signed-token guest portal (booking, upload, episode briefing) | | Integrations | `integrations/` | Self-hosted clients + webhook controllers + health | | LiveKit | `livekit/` | LiveKit token minting, room lifecycle | | Email | `email/` | Resend + React Email templates | | AI | `ai/` | NVIDIA NIM / DeepSeek / Moonshot wrappers | | Queue | `queue/` | BullMQ processors (outreach, content, clip-scoring, etc.) | | Websocket | `websocket/` | Socket.io gateway | | Trpc | `trpc/` | tRPC router composition + middleware | | Prisma | `prisma/` | PrismaClient service wrapper | | Redis | `redis/` | Redis client factory | | Settings | `settings/` | User + workspace settings | | Common | `common/` | Shared utilities (storage, safe-fetch, redis constants) | | Health | `health/` | Health controller | | Types | `types/` | Shared TypeScript types | Sub-READMEs in the source tree: [`apps/api/src/network/README.md`](../apps/api/src/network/README.md), [`apps/api/README.md`](../apps/api/README.md). ## Common REST Endpoints ### Authentication All endpoints require a Bearer token in the `Authorization` header: ``` Authorization: Bearer ``` Dev mode (no Clerk configured) accepts an `x-user-id` header containing a user UUID instead — useful for synthetic agent runs and local dev. **Never enable this in production.** ### Workspaces ``` GET /api/v1/workspaces POST /api/v1/workspaces GET /api/v1/workspaces/:id PUT /api/v1/workspaces/:id DELETE /api/v1/workspaces/:id POST /api/v1/workspaces/:id/members ``` ### Podcasts ``` GET /api/v1/workspaces/:id/podcasts POST /api/v1/workspaces/:id/podcasts GET /api/v1/workspaces/:id/podcasts/:id PUT /api/v1/workspaces/:id/podcasts/:id DELETE /api/v1/workspaces/:id/podcasts/:id GET /api/v1/workspaces/:id/podcasts/:id/stats ``` ### Guests ``` GET /api/v1/podcasts/:id/guests POST /api/v1/podcasts/:id/guests POST /api/v1/podcasts/:id/guests/bulk GET /api/v1/podcasts/:id/guests/top-priority GET /api/v1/podcasts/:id/guests/needs-follow-up GET /api/v1/podcasts/:id/guests/status-counts GET /api/v1/podcasts/:id/guests/:id PUT /api/v1/podcasts/:id/guests/:id PATCH /api/v1/podcasts/:id/guests/:id/status DELETE /api/v1/podcasts/:id/guests/:id POST /api/v1/podcasts/:id/guests/:id/tags ``` ### Outreach ``` GET /api/v1/podcasts/:id/outreach POST /api/v1/podcasts/:id/outreach GET /api/v1/podcasts/:id/outreach/:id POST /api/v1/podcasts/:id/outreach/:id/pause POST /api/v1/podcasts/:id/outreach/:id/resume POST /api/v1/podcasts/:id/outreach/:id/complete GET /api/v1/podcasts/:id/outreach/stats ``` ### Verified Guest Network Full reference in [`apps/api/src/network/README.md`](../apps/api/src/network/README.md). Highlights: ``` GET /network/guests/search GET /network/guests/trending GET /network/guests/:vanityUrl POST /network/views POST /network/profiles GET /network/profiles/me PUT /network/profiles/me GET /network/profiles/:id/views POST /network/bookmarks PUT /network/bookmarks/:id DELETE /network/bookmarks/:id GET /network/bookmarks POST /network/booking-requests PUT /network/booking-requests/:id/respond GET /network/booking-requests/received GET /network/booking-requests/sent GET /network/profiles/:id/reputation POST /network/profiles/:id/reputation/recalculate GET /network/profiles/:id/recommendations GET /network/profiles/:id/network-stats POST /network/reviews ``` The Network module is also exposed via the `network.` tRPC namespace (`trpc.network.search`, `trpc.network.requestBooking`, etc.). See the linked sub-README for tRPC examples. ### Guest portal (signed-token REST) The guest portal uses minimal public REST, authenticated via short-lived signed tokens in the URL — no account creation required. ``` GET /portal/booking/:token Available scheduling slots POST /portal/booking/:token/confirm Confirm a selected slot GET /portal/upload/:token Asset requirements POST /portal/upload/:token/file Initiate chunked file upload PATCH /portal/upload/:token/submit Mark submission complete GET /portal/episode/:token Episode briefing + recording instructions ``` ### Integrations + webhooks Webhooks are mounted under `/integrations/webhooks/` — full reference in [Webhooks](./webhooks.md). Integration health: `GET /integrations/health`. ### Billing Stripe, Paystack, and M-Pesa webhook receivers. Exact paths are configured in the billing module routes — see `apps/api/src/billing/` for source. M-Pesa callback is `POST /billing/webhooks/mpesa` (see `.env.example`). ## Background Job Queues BullMQ workers live in `apps/api/src/queue/` and run under the separate `worker` container in `docker-compose.yml` (`command: npx bullmq-pro`). | Queue | Sample jobs | Notes | |---|---|---| | outreach | `send-email`, `schedule-message` | Tracking pixel + reply parsing | | content | `transcribe`, `generate-clips`, `export` | Whisper transcription + clip export | | clip-scoring | `score-clip` | Spawns Python subprocess (in-worker); uses Redis distributed locks | | notifications | `send-notification` | In-app + push | | analytics | `aggregate-stats` | Snapshot jobs | See [Architecture → Background Job Architecture](./design.md#10-background-job-architecture) for the full queue table with concurrency and retry policies. ## Type Sharing & Codegen - All tRPC procedures are inferred directly by the NestJS router via `createTRPCRouter({ … })`. There is **no codegen step** — the frontend imports the `AppRouter` type and gets end-to-end type safety. - Zod schemas in `packages/shared-types/src/schemas.ts` are imported by both API and clients for input validation. - Enums in `packages/shared-types/src/enums.ts` mirror the Prisma enums in [`apps/api/prisma/schema.prisma`](../apps/api/prisma/schema.prisma) and must be kept in sync manually. ## Discovering Endpoints The fastest way to discover the full surface: ```bash # 1. Start the API pnpm dev # or: docker compose up -d api # 2. Open Swagger open http://localhost:4000/api/docs # 3. Search the source tree for a route grep -rn '@Controller' apps/api/src | less grep -rn '@Post\|@Get\|@Put\|@Delete\|@Patch' apps/api/src | less # 4. List the tRPC routers grep -rn 'createTRPCRouter' apps/api/src | less ``` Swagger covers REST; tRPC procedures are documented by reading the router composition. Webhooks are catalogued in [Webhooks](./webhooks.md).