VidFlow's API is the same set of routes the web app uses. There are two ways to authenticate against it: the browser session cookie the web app rides on, and OAuth 2.1 bearer tokens for headless clients like the MCP server.
Authentication. Every /api/projects/... route enforces requireAuth() and requireProjectOwnership(). requireAuth() checks for a Bearer vfa_... token first; if there's no bearer header it falls back to the NextAuth session cookie. So you have two paths. From a browser, the session cookie is automatic. From outside a browser, run the OAuth 2.1 device flow: POST /api/oauth/device/code to start it, the user approves the code at /device, then POST /api/oauth/device/token polls until it returns an access token (and a refresh token you exchange at /api/oauth/token). Access tokens carry the vfa_ prefix and a scope set, and run under their own oauth-bearer rate-limit tier. Tokens can be revoked at /api/oauth/revoke.
Response shape. Every route returns { success: boolean, data?: ..., error?: { code, message } }. Success codes are 200 for reads, 200 for in-flight writes (async tasks include a task ID for polling). Errors carry both an HTTP status and a structured error object — the code is stable and machine-readable, the message is human-readable and may shift.
Project routes. The core surface lives under /api/projects/[projectId]/.... Top-level routes: GET /api/projects/[id] (full payload — status, counts, derived completed stages), PATCH /api/projects/[id] (update fields — title, selectedTitle, channel, video style), DELETE /api/projects/[id].
Stage routes. Each stage has its own sub-routes. Ideation: /titles, /outlier-videos, /channel-setup. Script: /script/outline, /script/hook, /script/chapters, /script/analyze. Visual Bible: /visual-bible/characters/..., /visual-bible/locations/.../variations/generate. Voiceover: /voiceover/generate, /music/generate. Production: /timeline/shots/plan, /timeline/shots/[id]/generate, /timeline/render. Publish: /publish-context, /publish-suggest, /publish-youtube.
Async generation. Image and video generation are async by default. POST to /timeline/shots/[id]/generate returns a videoTaskId (or wavespeedTaskId for talking-head shots) you can poll. The vendor calls back to /api/{vendor}/callback when done; the shot's row updates as artifacts land. The route also supports asyncVideo: false for synchronous polling if your client can hold the connection open for several minutes.
Credits. Most generation routes charge credits up-front via requireCredits() and refund on failure. The refund logic is conservative — if any usable artifact landed (image, animated still, or video), the image-step credit is kept and only the video-step credit is refunded. Out-of-credit responses come back as 402 with code: 'INSUFFICIENT_CREDITS'.
Rate limits. Three tiers — auth (5/min), api (60/min), generation (10/min). Generation routes also have a separate free-suggest bucket (12/min) for non-billable LLM calls like description suggestions, so a rate-limit hit on Suggest doesn't eat into your generation budget. 429 responses carry a Retry-After header.
Webhooks, vendor-side. /api/kie/callback, /api/wavespeed/callback, and /api/assemblyai/callback accept async vendor results. These are vendor-to-server, not server-to-customer; we don't fire outbound webhooks today.
MCP — drives the whole pipeline. The Model Context Protocol server (in packages/mcp-server) isn't read-only. It exposes a full tool catalog that an MCP client like Claude or Cursor can use to read a project and drive it end to end: create_project, generate_script, generate_visual_bible, plan_shots, generate_all_shots, regenerate_shot, generate_audio, pick_voice, generate_thumbnail, render, publish_youtube, plus read/list tools (list_projects, get_project, list_channels, list_voices, get_run, list_runs). It authenticates with the OAuth device flow above — it's the canonical headless client for the bearer-token path. The long-running generation tools return a runId you poll with get_run.
What's not there yet. A published npm package (the MCP server runs from source today). A typed client SDK. Outbound webhooks. All on the roadmap; none shipped. If you're integrating directly against the routes rather than through MCP, mint an OAuth bearer token via the device flow and call the same routes the web app uses.
This page is a map, not a spec. Routes change as we ship; check the route file in source before committing to a specific shape.