Spaces:

Benaah
/

MicProtocol

Running

App Files Files Community

MicProtocol / docs /api-reference.md

Benaah

Upload folder using huggingface_hub

b17baae verified about 21 hours ago

preview code

Raw History Blame Contribute Delete

11.2 kB

# 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` (`<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|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 <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`](../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](./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).

	# 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` (`<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\|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 <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`](../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](./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).