<!-- Markdown twin of https://pixelvault.dev/docs/guides/organize-media/ -->

# 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`](/docs/transforms/#watermark), 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.

Metadata

curlNode.jsPython

```
# 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 `dedupe` or an `Idempotency-Key` replay returns an existing image, the metadata you sent is ignored (change it with `PATCH`).
-   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-Metadata` header on direct uploads, or the `metadata` JSON field on URL imports. Reference: [images](/docs/api/images/#update_image_metadata), [videos](/docs/api/videos/#update_video), [audio](/docs/api/audio/#update_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](/docs/api/images/#batch_upload) 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/collections`](/docs/api/collections/#list_collections) lists your collections, filtered by `type` and `name`.
-   [`GET /v1/collections/:id`](/docs/api/collections/#get_collection) returns the collection and an `assets` array with every member; `images` remains 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/close`](/docs/api/collections/#close_collection) closes a collection and applies its cleanup policy: a closed `ci_build` collection's members are removed at the next [sweep](/docs/lifecycle/#sweep).

## Next steps

-   [Host CI screenshots](/docs/guides/ci-screenshots/) in one collection per run.
-   [Search by AI description and tags](/docs/guides/ai-descriptions/), which combine with metadata filters.
-   [Pagination](/docs/pagination/) for large result sets.
