Collections
A collection is a typed group of media (a CI run, a generation set, an album) with shared metadata and its own lifecycle. Batch uploads create or reuse one; images, videos and audio can be filtered by collection_id.
The Collection object
The collection.
Properties
| Property | Type | Description | |||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
id | string | Collection id ( | |||||||||||||||||||||||||||||||||||||||
type | string | Caller-chosen kind, at most 32 characters. Closing a | |||||||||||||||||||||||||||||||||||||||
name | string nullable | Caller-chosen name within (project, type), e.g. the CI run id. Batch uploads with the same type and name reuse the collection. | |||||||||||||||||||||||||||||||||||||||
visibility | string | Members must share this visibility. | |||||||||||||||||||||||||||||||||||||||
metadata | object nullable | Freeform collection metadata. | |||||||||||||||||||||||||||||||||||||||
expires_at | string (date-time) nullable | Set from the batch's | |||||||||||||||||||||||||||||||||||||||
closed_at | string (date-time) nullable | Set by | |||||||||||||||||||||||||||||||||||||||
created_at | string (date-time) | ||||||||||||||||||||||||||||||||||||||||
assets | array of CollectionAsset | Every member: images, PDFs, videos and audio. | |||||||||||||||||||||||||||||||||||||||
Child properties of | |||||||||||||||||||||||||||||||||||||||||
| Property | Type | Description |
|---|---|---|
id | string | |
kind | string | |
url | string (uri) | |
branded_url | string (uri) | Same member on the project's active custom domain; omitted when none is ready. |
visibility | string | |
mime_type | string | |
size | integer | |
filename | string | |
folder | string nullable | |
metadata | object nullable | |
expires_at | string (date-time) nullable | |
created_at | string (date-time) |
imagesBackward-compatible subset of assets: images and PDFs only (no videos or audio).
Child properties of images
| Property | Type | Description |
|---|---|---|
id | string | |
kind | string | |
url | string (uri) | |
branded_url | string (uri) | Same member on the project's active custom domain; omitted when none is ready. |
visibility | string | |
mime_type | string | |
size | integer | |
filename | string | |
folder | string nullable | |
metadata | object nullable | |
expires_at | string (date-time) nullable | |
created_at | string (date-time) |
{
"id": "col_abc123",
"type": "ci_build",
"name": "gh-run-1234567890",
"visibility": "private",
"metadata": {
"commit": "9f8e7d6",
"pr_number": 128,
"branch": "feature/login"
},
"expires_at": "2026-12-16T12:00:00.000Z",
"closed_at": null,
"created_at": "2026-11-16T12:00:00.000Z",
"assets": [
{
"id": "img_abc123",
"kind": "image",
"url": "https://img.pixelvault.dev/proj_xyz789/cp/col_abc123/img_abc123.png",
"branded_url": "https://media.example.com/cp/col_abc123/img_abc123.png",
"visibility": "private",
"mime_type": "image/png",
"size": 48231,
"filename": "login-diff.png",
"folder": "cp/col_abc123",
"metadata": {
"testName": "login page"
},
"expires_at": "2026-12-16T12:00:00.000Z",
"created_at": "2026-11-16T12:00:00.000Z"
}
],
"images": [
{
"id": "img_abc123",
"kind": "image",
"url": "https://img.pixelvault.dev/proj_xyz789/cp/col_abc123/img_abc123.png",
"branded_url": "https://media.example.com/cp/col_abc123/img_abc123.png",
"visibility": "private",
"mime_type": "image/png",
"size": 48231,
"filename": "login-diff.png",
"folder": "cp/col_abc123",
"metadata": {
"testName": "login page"
},
"expires_at": "2026-12-16T12:00:00.000Z",
"created_at": "2026-11-16T12:00:00.000Z"
}
]
}List collections
GET /v1/collections
List the project's collections, newest first, optionally filtered by exact type and/or name (the CI run id, generation id, and so on). Collections are created by batch_upload; filter media by collection with collection_id on list_images, list_videos and list_audio.
Authentication
API key, sent as Authorization: Bearer <key>.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
type | string | Optional | Exact collection type. |
name | string | Optional | Exact collection name. |
page | integer | Optional | Page number, from 1. |
per_page | integer | Optional | Collections per page (max 100). |
Responses
- 200
A page of collections
- 401
missing_api_key: noAuthorizationheader.invalid_api_key: the header is notBearer pv_live_…/pv_test_…/pv_pub_…, or the key is unknown or revoked. - 403
publishable_key_forbidden: publishable keys (pv_pub_) can only upload images; use a secret key.account_suspended: the account is suspended. - 429
rate_limit_exceeded: more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. HonourRetry-After.
curl https://api.pixelvault.dev/v1/collections \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" {
"data": [
{
"id": "col_abc123",
"type": "ci_build",
"name": "gh-run-1234567890",
"visibility": "private",
"metadata": {
"commit": "9f8e7d6",
"pr_number": 128,
"branch": "feature/login"
},
"expires_at": "2026-12-16T12:00:00.000Z",
"closed_at": null,
"created_at": "2026-11-16T12:00:00.000Z"
}
],
"meta": {
"total": 42,
"page": 1,
"per_page": 20
}
} Get a collection and its media
GET /v1/collections/{id}
A collection and every member, newest first: assets lists all media (use each member's kind); images remains as the backward-compatible subset of images and PDFs, without videos or audio. Member URLs are unsigned identifiers: for private members, mint links with sign_image_url, sign_video_url or sign_audio_url.
Authentication
API key, sent as Authorization: Bearer <key>.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | Collection id. |
Responses
- 200
The collection with its members
- 401
missing_api_key: noAuthorizationheader.invalid_api_key: the header is notBearer pv_live_…/pv_test_…/pv_pub_…, or the key is unknown or revoked. - 403
publishable_key_forbidden: publishable keys (pv_pub_) can only upload images; use a secret key.account_suspended: the account is suspended. - 404
collection_not_found: no collection with this id in the project. - 429
rate_limit_exceeded: more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. HonourRetry-After.
curl https://api.pixelvault.dev/v1/collections/col_abc123 \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" {
"data": {
"id": "col_abc123",
"type": "ci_build",
"name": "gh-run-1234567890",
"visibility": "private",
"metadata": {
"commit": "9f8e7d6",
"pr_number": 128,
"branch": "feature/login"
},
"expires_at": "2026-12-16T12:00:00.000Z",
"closed_at": null,
"created_at": "2026-11-16T12:00:00.000Z",
"assets": [
{
"id": "img_abc123",
"kind": "image",
"url": "https://img.pixelvault.dev/proj_xyz789/cp/col_abc123/img_abc123.png",
"branded_url": "https://media.example.com/cp/col_abc123/img_abc123.png",
"visibility": "private",
"mime_type": "image/png",
"size": 48231,
"filename": "login-diff.png",
"folder": "cp/col_abc123",
"metadata": {
"testName": "login page"
},
"expires_at": "2026-12-16T12:00:00.000Z",
"created_at": "2026-11-16T12:00:00.000Z"
}
],
"images": [
{
"id": "img_abc123",
"kind": "image",
"url": "https://img.pixelvault.dev/proj_xyz789/cp/col_abc123/img_abc123.png",
"branded_url": "https://media.example.com/cp/col_abc123/img_abc123.png",
"visibility": "private",
"mime_type": "image/png",
"size": 48231,
"filename": "login-diff.png",
"folder": "cp/col_abc123",
"metadata": {
"testName": "login page"
},
"expires_at": "2026-12-16T12:00:00.000Z",
"created_at": "2026-11-16T12:00:00.000Z"
}
]
}
} Close a collection
POST /v1/collections/{id}/close
Marks a collection closed (sets closed_at), for example when its pull request merges. For ci_build collections, every member is expired now and deleted by the hourly cleanup sweep (which can lag by about two hours) instead of waiting for its TTL; the empty collection is removed afterwards. For other types (albums, generation sets) closing is only a marker and members are kept.
Authentication
API key, sent as Authorization: Bearer <key>.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | Collection id. |
Responses
- 200
The closed collection
- 401
missing_api_key: noAuthorizationheader.invalid_api_key: the header is notBearer pv_live_…/pv_test_…/pv_pub_…, or the key is unknown or revoked. - 403
publishable_key_forbidden: publishable keys (pv_pub_) can only upload images; use a secret key.account_suspended: the account is suspended. - 404
collection_not_found: no collection with this id in the project. - 429
rate_limit_exceeded: more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. HonourRetry-After.
curl -X POST https://api.pixelvault.dev/v1/collections/col_abc123/close \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" {
"data": {
"id": "col_abc123",
"type": "ci_build",
"name": "gh-run-1234567890",
"visibility": "private",
"metadata": {
"commit": "9f8e7d6",
"pr_number": 128,
"branch": "feature/login"
},
"expires_at": "2026-12-16T12:00:00.000Z",
"closed_at": "2026-11-18T09:00:00.000Z",
"created_at": "2026-11-16T12:00:00.000Z"
}
}