API Reference

The platform exposes two API surfaces:

• Next.js (:3000) — the Director engine, media, and assets (/api/director/*, /api/media, /api/assets)
• Express (:3001) — auth and the kept v1 features (/api/auth, /api/email, /api/svg, /api/settings, /api/brand), proxied through Next.js

Auth is a JWT cookie issued by Express. web/src/middleware.ts validates the session (against Express /api/auth/me) and gates the app pages plus the Director/asset APIs. /api/media is intentionally public so the headless renderer can fetch assets.

---

Director (Next.js)

The AI video engine. See Video Generation.

Method	Path	Purpose
POST	/api/director/start	INTAKE + ANALYZE — accepts a Brief, returns a Storyboard + runId (suspended at the storyboard gate)
POST	/api/director/clarify	AI-driven, product-specific clarify questions (≤ 4 round 1, ≤ 1 round 2; pre-filled, skippable)
POST	/api/director/distill	Multipart: upload source docs (pdf/docx/txt/md/html/csv) → { summary, points[] }
POST	/api/director/:runId/resolve	Storyboard gate decision — approve | edit | reject → ResolvedIR or revised storyboard
POST	/api/director/edit	Chat-driven edit — { doc, sceneId?, instruction } → { ir, changes[] }
POST	/api/director/voiceover	Synthesize narration via Azure TTS — text → MP3 (in storage/voiceover/)
POST	/api/director/export	Submit a ResolvedIR → jobId; GET ?jobId polls progress → MP4 URL

Saved documents

Method	Path	Purpose
GET	/api/director/docs	List saved documents (id, title, savedAt, scenes, seconds, aspect)
POST	/api/director/docs	Save / update a document (full ResolvedIR + title) → docId
GET	/api/director/docs/:id	Fetch one document
DELETE	/api/director/docs/:id	Delete a document

Media & assets (Next.js)

Method	Path	Purpose
GET	/api/media/[...path]	Stream a stored file (Range-aware, traversal-guarded, ?download=1); not auth-gated
GET	/api/assets?kind=audio\|image\|video	List available media (logical paths) for the inspector pickers
POST	/api/assets/upload	Multipart upload → uploads/, returns logical paths

See Library & Media.

---

Auth (Express, proxied)

Method	Path	Purpose
POST	/api/auth/login	Trade an ALLOWED_USERS email for a JWT cookie
GET	/api/auth/me	Current session (used by middleware + AuthGuard)
GET	/api/health	Liveness probe

Email (Express, proxied)

Method	Path	Purpose
POST	/api/email	Start the email pipeline; returns runId
GET	/api/email/:runId/status	Status (also via SSE)
GET	/api/email/:runId	Full EmailRun (brief + copy + layout)
POST	/api/email/:runId/regenerate/:section	Regenerate one section
POST	/api/email/:runId/render-html	Re-render MJML → HTML
POST	/api/email/:runId/send-preview	Send a preview email via ACS

See Email Generator.

SVG (Express, proxied)

Method	Path	Purpose
POST	/api/svg/generate	Generate a branded SVG (banner / square / portrait)

Settings & brand (Express, proxied)

Method	Path	Purpose
GET / PATCH	/api/settings	App settings (API-keys section)
GET / PATCH	/api/brand/guidelines	Legacy BrandGuidelines (consumed by email/SVG, not the video engine)
POST	/api/brand/upload	Upload brand documents for guideline extraction

---

Retired v1 endpoints

The Express server still contains v1 routes that are no longer reachable through the app (the proxy only forwards auth, health, email, svg, settings, brand): e.g. /api/chat/sessions/*, /api/render, /api/runs, /api/video, /api/scenes, and the old per-run /api/assets//api/media. They describe the retired chat-session video pipeline and should not be used. The live video API is the Next.js Director surface above.