REST API

The HTTP endpoints behind the editor, for scripts and tools that don't speak MCP.

• GET /api/project - current project JSON
• PUT /api/project - replace project JSON (body = full document). Conflict-safe: if the body's revision ≤ the revision currently on disk, the server rejects with 409 and returns {"error":"…","revision":<current>}. Append ?force=1 to overwrite unconditionally. Writes are atomic (tmp file + rename), so a crashed write never corrupts the file.
• GET /api/media - list files in ./media (name, src, size)
• GET /api/library?dir=sfx|elements|svg|fonts - list library assets
• POST /api/upload?name=foo.mp4 - raw body saved into ./media, returns {src}. MP4/MOV/M4V uploads are auto-remuxed with +faststart (needs ffmpeg on PATH). Files copied straight into ./media by external tools skip this - remux big ones yourself (ffmpeg -i in.mp4 -c copy -movflags +faststart out.mp4) or playback stalls.
• POST /api/import-url - body {url:"https://…"} downloads the file into ./media/ and returns {src,name} (same-origin /media/…, like upload). HTTPS only; rejects localhost, private/link-local/CGNAT addresses, and redirects to those. Remote SVG is refused (/media/*.svg is served same-origin as image/svg+xml - a scripted SVG opened as a document would run on the editor origin). Does not write project.json - register the media afterwards (UI and fablecut_import_media do this). Do not put a raw https:// URL (or another origin, including localhost on a different port) in media.src: canvas CORS would taint the compositor and Fast / WebCodecs export cannot JPEG-encode. Import into ./media so src is /media/…, or serve the remote with Access-Control-Allow-Origin.
• POST /api/analyze - body {src:"/media/ref.mp4", threshold?, music?}: analyze a reference video into an edit blueprint (see Remake a reference video); extracts its music into ./media. GET /api/analyze?src=… returns the cached blueprint.
• GET /api/events - SSE: named event change when project.json, ./media or ./library changes; named event profiles when encoding-profiles.json changes (UI refreshes the export-profile list only - no project reload)
• Fast / WebCodecs export (browser compositor → server ffmpeg): GET /api/export/ffmpeg → {available} · GET /api/export/profiles[?detail=1] → {default, profiles, issues} · POST /api/export/begin {fps,name,mode?,profile?,hasAudio?,pixelFormat?,width?,height?} → {id,mode,profile?,label,summary} (fps is required - pass project.fps, no server-side default; mode is "jpeg" (default, Fast) or "annexb" (WebCodecs H.264 elementary stream); jpeg 400 if profile is not a defined id, or if ffmpeg rejects its args in the dry run; optional pixelFormat:"rgba" plus width/height pipes raw canvas frames instead of JPEG) · POST /api/export/frame?id= (JPEG body for jpeg mode; raw RGBA if begin used pixelFormat:"rgba"; Annex-B for annexb - one POST may concatenate frames or AUs. Must be after audio; ffmpeg is spawned on the first frame in both modes) · POST /api/export/audio?id= (WAV body - must be sent before the first frame) · POST /api/export/end?id=[&discard=1] → {src} under /exports/