Guides

Collections

Collections

Collections are named groups of videos. Every video belongs to exactly one collection. When you search, you can scope the query to a single collection — which is faster and more precise than searching your entire library.

Create a collection

$curl -X POST https://api.pureframe.ai/v1/collections \
>  -H "Authorization: Bearer pf_key_..." \
>  -H "Content-Type: application/json" \
>  -d '{ "name": "Product demos" }'
1{
2  "data": {
3    "id": "col_abc123",
4    "name": "Product demos",
5    "video_count": 0,
6    "created_at": "2025-05-01T12:00:00Z"
7  },
8  "ok": true
9}

Upload a video to a collection

Pass collection_id in the upload form to assign the video on creation.

$curl -X POST https://api.pureframe.ai/v1/upload \
>  -H "Authorization: Bearer pf_key_..." \
>  -F "file=@demo.mp4" \
>  -F "collection_id=col_abc123"

Search within a collection

Pass collection_id as a form field to scope the search.

$curl -X POST https://api.pureframe.ai/v1/search \
>  -H "Authorization: Bearer pf_key_..." \
>  -F "query=pricing objection" \
>  -F "collection_id=col_abc123"

Results will only include videos from that collection.

List videos in a collection

$curl "https://api.pureframe.ai/v1/videos?collection_id=col_abc123" \
>  -H "Authorization: Bearer pf_key_..."

Rename a collection

$curl -X PATCH https://api.pureframe.ai/v1/collections/col_abc123 \
>  -H "Authorization: Bearer pf_key_..." \
>  -H "Content-Type: application/json" \
>  -d '{ "name": "Sales demos" }'

Delete a collection

Deleting a collection permanently deletes all videos and their indexed segments. This cannot be undone.

$curl -X DELETE https://api.pureframe.ai/v1/collections/col_abc123 \
>  -H "Authorization: Bearer pf_key_..."

Collection object

FieldTypeDescription
idstringUnique collection ID, prefixed col_
namestringDisplay name
video_countintegerNumber of videos in the collection
created_atstringISO 8601 timestamp