Organize media
Goal: find media again by what it belongs to (a build, a customer, a blog post) instead of keeping your own index of IDs. PixelVault has three tools: folders, custom metadata, and collections.
Folders
A folder is a path segment in the CDN URL and a label on the asset. Set it at upload: the folder form or JSON field for images, X-PixelVault-Folder (direct) or folder (URL import, resumable initiation) for video and audio. Private images ignore the folder because they live under a reserved private prefix. Video and audio lists filter on it (?folder=agents); move a video or audio asset with PATCH. When you watermark with tile, prefix the image path with its folder.
Custom metadata
Attach a JSON object (up to 50 top-level keys, 4 KB) at upload, replace it later with PATCH and {"metadata": {...}} (null clears it), and find assets again with ?metadata={"env":"prod"} or ?meta[env]=prod. All pairs must match. It is returned as metadata on every asset. Don't store secrets in it.
# attach metadata at upload (a JSON string in multipart)
curl -X POST https://api.pixelvault.dev/v1/images \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" \
-F "file=@hero.png" \
-F 'metadata={"env":"prod","post":"launch"}'
# find it again: all pairs must match
curl -G https://api.pixelvault.dev/v1/images \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" \
--data-urlencode "meta[env]=prod" \
--data-urlencode "meta[post]=launch"
# replace it later (null clears it)
curl -X PATCH https://api.pixelvault.dev/v1/images/img_abc123 \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"metadata": {"env": "staging"}}' - Metadata is applied to new images only: when
dedupeor anIdempotency-Keyreplay returns an existing image, the metadata you sent is ignored (change it withPATCH). - It is ignored on keyless uploads, and batch items with invalid metadata fail individually with
invalid_metadata. - Video and audio take it as the
X-PixelVault-Metadataheader on direct uploads, or themetadataJSON field on URL imports. Reference: images, videos, audio.
curl -X POST https://api.pixelvault.dev/v1/videos \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" \
-H "Content-Type: video/mp4" \
-H "X-PixelVault-Filename: run-42.mp4" \
-H "X-PixelVault-Folder: agents" \
-H 'X-PixelVault-Metadata: {"run":"42"}' \
--data-binary @run-42.mp4
curl "https://api.pixelvault.dev/v1/videos?folder=agents&meta[run]=42" \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" Collections
A collection is a typed group of media assets (a CI run, a generation set, an album) with shared metadata and its own lifecycle. The batch endpoint creates or reuses one per (type, name); video and audio join an existing same-visibility collection with collection_id (or X-PixelVault-Collection-Id) at upload or via PATCH.
GET /v1/collections?type=ci_build&name=run-123 # list your collections
GET /v1/collections/:id # a collection and its media assets
GET /v1/images?collection_id=col_… # filter any media list by collection
POST /v1/collections/:id/close # close it and apply its cleanup policy GET /v1/collectionslists your collections, filtered bytypeandname.GET /v1/collections/:idreturns the collection and anassetsarray with every member;imagesremains as the backward-compatible image-only subset.GET /v1/images?collection_id=…,/v1/videos?collection_id=…, or/v1/audio?collection_id=…filter by collection.POST /v1/collections/:id/closecloses a collection and applies its cleanup policy: a closedci_buildcollection's members are removed at the next sweep.
Next steps
- Host CI screenshots in one collection per run.
- Search by AI description and tags, which combine with metadata filters.
- Pagination for large result sets.