roboco/docs/backend/api/video-engine-endpoints.md

Video Engine API: Project-Scoped Endpoints

Overview

The RoboCo video engine API is CEO-only and manages three concerns:

1. On-demand video requests: POST /api/video/request opens a video-authoring task scoped to a specific project
2. Re-render (CEO retry): POST /api/video/pipeline/{task_id}/rerender clears render idempotency keys to re-trigger rendering
3. Live preview proxy: GET /api/video/preview/{task_id}/{file_path:path} serves authoring task composition HTML + assets with path-traversal confinement

All endpoints are CEO-only and require the global video engine flag enabled (ROBOCO_VIDEO_ENGINE_ENABLED).

---

Endpoint: POST /api/video/request

Purpose

Open a UX/UI video-authoring task for the CEO's on-demand brief, scoped to a specific project.

Authentication

CEO-only (401 if not CEO).

Request Body (VideoRequestBody)

{
  "occasion": "string",      // Unique identifier; required, min 1 char
  "brief": "string",         // Video brief description; required, min 1 char
  "platforms": ["string"],   // Target platforms: ["x", "tiktok"]; required, min 1
  "project_id": "UUID"       // Project to author against; required (NEW in v2)
}

Breaking Change: project_id is now required. This field scopes the video authoring task and its render pass to the specified project, replacing the hardcoded self_heal_project_slug behavior.

Response (VideoRequestResponse)

{
  "status": "opened|disabled|not_opened",
  "task_id": "UUID|null",
  "detail": "string"
}

Response Codes

Code	Status	Meaning
200	opened	Task created and dispatched to UX/UI developer
200	disabled	Video engine is off (ROBOCO_VIDEO_ENGINE_ENABLED=false)
200	not_opened	Duplicate occasion or open-post cap reached
404	—	project_id unresolvable OR project not opted in (video_engine_enabled=false)
401	—	Not authenticated as CEO

Behavior

1. Project validation: Looks up project_id and checks video_engine_enabled=true. Returns 404 if unresolvable or not opted in.
2. Task creation: Opens a normal ASSIGNED delivery task (source=video) dispatched to an available UX/UI developer (balanced by open-task count).
3. Duplicate check: Returns not_opened if a task for this occasion is already open.
4. Open-post cap: Returns not_opened if open-task count ≥ ROBOCO_VIDEO_MAX_OPEN_POSTS.

Example

curl -X POST http://localhost:3000/api/video/request \
  -H 'X-Agent-Token: <ceo-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "occasion": "v2.0 Launch",
    "brief": "30-second teaser for new dashboard",
    "platforms": ["x", "tiktok"],
    "project_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

---

Endpoint: POST /api/video/pipeline/{task_id}/rerender

Purpose

Clear render idempotency keys (render_status, render_attempts, render_error) on a completed video-authoring task, triggering the render loop to re-pick it up on the next cycle.

Use case: CEO fixes a composition error or wants to retry past a failed terminal state.

Authentication

CEO-only (401 if not CEO).

Path Parameters

Name	Type	Description
task_id	UUID	Video-authoring task ID

Response (VideoPipelineItemResponse)

{
  "task_id": "UUID",
  "title": "string",
  "occasion": "string",
  "status": "string",
  "pr_number": "int|null",
  "composition_id": "string|null",
  "render_status": "string|null",
  "render_attempts": "int",
  "max_attempts": "int",
  "render_error": "string|null"
}

After clearing, render_status, render_attempts, and render_error are null or zero.

Response Codes

Code	Meaning
200	Keys cleared; next render cycle re-picks this task
404	Task not found, not video task, not completed, or no composition_id (nothing to render)
401	Not authenticated as CEO

Behavior

1. Validation: Checks task exists, is a video-authoring task (source=VIDEO_SOURCE), is COMPLETED, and has a composition_id.
2. Clear keys: Removes render_status, render_attempts, render_error from video_draft marker; preserves other fields.
3. Render loop pickup: On next orchestrator cycle, render loop scans for tasks with render_status unset and re-renders.

Example

curl -X POST http://localhost:3000/api/video/pipeline/550e8400-e29b-41d4-a716-446655440000/rerender \
  -H 'X-Agent-Token: <ceo-token>'

---

Endpoint: GET /api/video/preview/{task_id}/{file_path:path}

Purpose

Serve a video-authoring task's composition HTML and sibling assets (kit/, public/, etc.) from the project's merged read-clone. Used by the panel's live preview iframe.

Authentication

CEO-only (401 if not CEO).

Path Parameters

Name	Type	Description
task_id	UUID	Video-authoring task ID
file_path	string	Path relative to workspace root; e.g., motion/compositions/<id>/vertical.html

Response

• Content-Type: Auto-detected from file extension
• Headers:
  • X-Frame-Options: SAMEORIGIN — Allows same-origin iframe embedding
  • Content-Security-Policy: frame-ancestors 'self' — Restricts frame embedding to same origin
• Body: File contents (HTML, CSS, JS, images, etc.)

Response Codes

Code	Meaning
200	File served successfully
404	Task/project not found, file doesn't exist, or file path escapes workspace root
401	Not authenticated as CEO

Behavior

1. Task lookup: Fetches task; validates it's a video task (source=VIDEO_SOURCE) with project_id.
2. Project resolution: Looks up project by project_id.
3. Workspace fetch: Ensures project's read-clone is available (clones if needed).
4. Path resolution:
   • Strips leading / from file_path
   • Resolves against workspace root
   • Validates resolved path is under root and is a regular file
   • Returns 404 on traversal attempt or non-file path
5. Serve: Returns file with iframe-permitting headers.

Path Traversal Confinement

The _resolve_preview_path helper prevents directory-traversal attacks:

candidate = (root / file_path.lstrip("/")).resolve()
if not candidate.is_relative_to(root) or not candidate.is_file():
    return None

Guarantees:

• ../ sequences are resolved before confinement check
• Absolute paths don't escape (resolved relative to root)
• Symlinks are resolved and still held under confinement
• Only regular files served; directories return 404

Example

# Serve composition HTML
curl -H 'X-Agent-Token: <ceo-token>' \
  'http://localhost:3000/api/video/preview/550e8400-e29b-41d4-a716-446655440000/motion/compositions/my-id/vertical.html'

# Serve referenced asset
curl -H 'X-Agent-Token: <ceo-token>' \
  'http://localhost:3000/api/video/preview/550e8400-e29b-41d4-a716-446655440000/kit/public/logo.png'

---

Project-Scoping Architecture

What Changed

Previously, the video engine hardcoded settings.self_heal_project_slug everywhere. Now:

1. On-demand requests (POST /video/request): project_id required in request body
2. Authoring tasks: Each task stores its own project_id
3. Render loop (orchestrator._render_both_cuts): Uses task's project_id to resolve motion/ workspace, not hardcoded setting

Rationale

Each opted-in project can now:

• Author and render videos against its own motion/ directory
• Participate in release and spotlight videos from its own codebase
• Support on-demand briefs scoped to specific projects

Resolution Method

New VideoEngine.resolve_authoring_project(project_id, occasion):

• If project_id provided (on-demand, per-task): Looks up project by ID
• If project_id is None (release/spotlight hooks): Falls back to fixed RoboCo project (self_heal_project_slug)
• Both paths: Check video_engine_enabled and log skip reasons identically

Migration Impact

For on-demand endpoint clients:

• Must now supply project_id in request body
• Requests without project_id fail validation (422)
• Panel's video-request form needs project picker (frontend task, out of scope)

For release/spotlight hooks:

• No change; they continue defaulting to fixed RoboCo project when no project_id provided