Videos

The Videos router manages your video library. Videos are the core resource in LynxVizion — each video has a unique job_id and progresses through processing states.

Video statuses: uploaded → queued → processing → completed | failed

---

GET /videos

List all videos for the authenticated user.

Auth: Required

Query Param	Type	Required	Description
project_id	string	No	Filter by project ID
status	string	No	Filter by status (uploaded, queued, processing, completed, failed)

Response: VideoResponse[]

[
  {
    "id": "1",
    "user_id": "550e8400-...",
    "job_id": "a1b2c3d4-...",
    "project_id": null,
    "name": "my-video.mp4",
    "status": "completed",
    "selected_insights": "[\"visualelements\",\"transcription\"]",
    "duration": 120.5,
    "file_size": 52428800,
    "processing_time": 45.2,
    "storage_path": "users/550e8400-.../my-video.mp4",
    "created_at": "2025-01-15T10:00:00",
    "updated_at": "2025-01-15T10:05:00"
  }
]

curl https://api.lynxvizion.com/api/videos \
  -H "Authorization: $LVZ_KEY"

---

GET /videos/{job_id}

Get a single video by job ID.

Auth: Required

Path Param	Type	Required	Description
job_id	string	Yes	The video’s job ID (UUID)

Response: VideoResponse

curl https://api.lynxvizion.com/api/videos/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: $LVZ_KEY"

---

PATCH /videos/{job_id}

Update video metadata.

Auth: Required

Path Param	Type	Required	Description
job_id	string	Yes	The video’s job ID

Body Field	Type	Required	Description
name	string	No	Display name
description	string	No	Description text
project_id	string	No	Assign to a project (or null to unassign)

Response: Updated VideoResponse

curl -X PATCH https://api.lynxvizion.com/api/videos/a1b2c3d4-... \
  -H "Authorization: $LVZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Product Demo v2", "project_id": "5"}'

---

DELETE /videos/{job_id}

Delete a video, its analysis segments, and associated shared reports. Does not delete the source file from storage (use DELETE /storage/files for that).

Auth: Required

Path Param	Type	Required	Description
job_id	string	Yes	The video’s job ID

Response:

{ "ok": true }

curl -X DELETE https://api.lynxvizion.com/api/videos/a1b2c3d4-... \
  -H "Authorization: $LVZ_KEY"

---

POST /videos/register-and-process

Register a video from storage and immediately queue it for processing in one call.

Auth: Required

Body Field	Type	Required	Description
modules	string[]	Yes	Analysis modules to run (e.g. ["visualelements", "transcription"])
storage_path	string	Yes	B2 storage path (must be under users/<your-user-id>/)
file_name	string	No	Display name (defaults to filename from path)
initial_prompt	string	No	Custom prompt to guide analysis

Response:

{
  "job_id": "a1b2c3d4-...",
  "status": "queued",
  "message": "Video queued for processing"
}

curl -X POST https://api.lynxvizion.com/api/videos/register-and-process \
  -H "Authorization: $LVZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "modules": ["visualelements", "transcription", "scenes"],
    "storage_path": "users/550e8400-.../my-video.mp4",
    "file_name": "Product Demo"
  }'

---

POST /videos/{job_id}/process

Start or restart processing for an existing video with specified modules.

Auth: Required

Path Param	Type	Required	Description
job_id	string	Yes	The video’s job ID

Body Field	Type	Required	Description
modules	string[]	Yes	Analysis modules to run
storage_path	string	No	Override storage path
initial_prompt	string	No	Custom prompt

Response:

{
  "job_id": "a1b2c3d4-...",
  "status": "queued",
  "message": "Video queued for processing"
}

curl -X POST https://api.lynxvizion.com/api/videos/a1b2c3d4-.../process \
  -H "Authorization: $LVZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{"modules": ["visualelements", "transcription"]}'

---

POST /videos/{job_id}/reprocess

Reprocess an already-analyzed video. Clears existing segments before reprocessing.

Auth: Required

Path Param	Type	Required	Description
job_id	string	Yes	The video’s job ID

Body Field	Type	Required	Description
modules	string[]	No	Override modules (keeps existing if omitted)
initial_prompt	string	No	Custom prompt

Response:

{
  "job_id": "a1b2c3d4-...",
  "status": "queued",
  "message": "Video queued for reprocessing"
}

curl -X POST https://api.lynxvizion.com/api/videos/a1b2c3d4-.../reprocess \
  -H "Authorization: $LVZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{"modules": ["scenes", "logos"]}'