REST API overview

ChannelForge exposes a REST API under /api/v1/* mounted on Hono. Every authenticated route requires a Clerk session cookie (browser) or a service token (machine-to-machine, lands in Sprint 17).

Conventions

• Errors: { code, message, details?, traceId }. Status from the underlying AppError.
• Validation: @hono/zod-validator against schemas in @channelforge/shared.
• Pagination: cursor-based, never offset in production.
• Workspace scoping: every workspace-scoped route enforces assertWorkspaceMembership(workspaceId, clerkUserId).

Top-level routes

• /health - liveness, cached 5 s at the edge.
• /me - current user + workspaces.
• /workspaces - workspace CRUD + members + invitations.
• /channels - CRUD, OAuth, language routing.
• /projects/* - scripts, audio, visuals, renders, thumbnails, metadata, publish, localize.
• /personas - persona library, bulk-apply, archive.
• /cockpit - aggregated read for the fleet grid.
• /research - ideas, sources, AI-suggest.
• /workflows - CRUD + runs + gate approve / decline + cancel.
• /user-keys - BYOK key vault.
• /billing - state read + Checkout + topup + Customer Portal.
• /voices - ElevenLabs library + voice cloning.

Workflow actions

The action registry lives in @channelforge/workflows/actions. The public catalog is reachable at GET /workflows/actions, which is what the builder UI calls to render parameter fields.

SDKs

• TypeScript SDK with typed routes lands in Sprint 17 alongside the public API formalisation.