Metadata

Store your own key-value pairs on a video: lesson IDs, course names, student IDs, project codes, anything. Metadata appears in status, list responses and webhooks, and you can filter listings by it.

Rules

• Up to 20 keys per video.
• Keys: 1–40 characters; letters, digits, _, ., -.
• Values: strings, up to 500 characters each.
• Total: 4 KB maximum for all metadata on one video.

Set on create

Add a metadata object when creating a video (upload or edit):

POST /videos
{
  "fileName": "lesson-1.mp4",
  "sizeBytes": 1048576,
  "metadata": { "lessonId": "123", "courseId": "algebra-1" }
}

Update with PATCH

Change metadata on a finished or in-progress video without re-uploading. Keys set to null are removed; other keys are set:

PATCH /videos/3f1c…
{ "metadata": { "lessonId": "456", "archived": null } }

200 OK
{ "videoId": "3f1c…", "metadata": { "lessonId": "456", "courseId": "algebra-1" } }

Filter listings

Find videos by metadata: GET /videos?metadata.lessonId=123. Each query can include up to 5 filters. Filters are AND'd together. The OpenAPI spec uses metadata.<key> as a placeholder for dynamic filter names.

Inheritance

When you reprocess a video, the new one gets the original's metadata unless you provide new metadata in the reprocess request.