docs/api-reference.md

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/.

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/.
3. Socket.io WebSockets — real-time push to clients, namespaced by workspace. Gateway: 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.

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 (<n>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
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/README.md.

Common REST Endpoints

Authentication

All endpoints require a Bearer token in the Authorization header:

Authorization: Bearer <clerk_jwt_token>

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. 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/<provider> — full reference in Webhooks.

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 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 and must be kept in sync manually.

Discovering Endpoints

The fastest way to discover the full surface:

# 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.