<!-- Markdown twin of https://pixelvault.dev/docs/api/collections/ -->

[API reference](/docs/api/)

# 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](#object)
-   GET [List collections](#list_collections)
-   GET [Get a collection and its media](#get_collection)
-   POST [Close a collection](#close_collection)

## The Collection object

The collection.

### Properties

The Collection object properties

Property

Type

Description

`id`

string

Collection id (`col_` prefix).

`type`

string

Caller-chosen kind, at most 32 characters. Closing a `ci_build` collection deletes its media.

`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.

One of: `public`, `private`

`metadata`

object nullable

Freeform collection metadata.

`expires_at`

string (date-time) nullable

Set from the batch's `expires_in`; null when its images have no fixed expiry.

`closed_at`

string (date-time) nullable

Set by [`close_collection`](/docs/api/collections/#close_collection); null while open.

`created_at`

string (date-time)

`assets`

array of CollectionAsset

Every member: images, PDFs, videos and audio.

Child properties of `assets`

Properties of assets

Property

Type

Description

`id`

string

`kind`

string

One of: `image`, `document`, `video`, `audio`

`url`

string (uri)

`branded_url`

string (uri)

Same member on the project's active custom domain; omitted when none is ready.

`visibility`

string

One of: `public`, `private`

`mime_type`

string

`size`

integer

`filename`

string

`folder`

string nullable

`metadata`

object nullable

`expires_at`

string (date-time) nullable

`created_at`

string (date-time)

`images`

array of CollectionAsset

Backward-compatible subset of `assets`: images and PDFs only (no videos or audio).

Child properties of `images`

Properties of images

Property

Type

Description

`id`

string

`kind`

string

One of: `image`, `document`, `video`, `audio`

`url`

string (uri)

`branded_url`

string (uri)

Same member on the project's active custom domain; omitted when none is ready.

`visibility`

string

One of: `public`, `private`

`mime_type`

string

`size`

integer

`filename`

string

`folder`

string nullable

`metadata`

object nullable

`expires_at`

string (date-time) nullable

`created_at`

string (date-time)

The Collection object

```
{
  "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`](/docs/api/images/#batch_upload); filter media by collection with `collection_id` on [`list_images`](/docs/api/images/#list_images), [`list_videos`](/docs/api/videos/#list_videos) and [`list_audio`](/docs/api/audio/#list_audio).

### Authentication

API key, sent as `Authorization: Bearer <key>`.

### Query parameters

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.

Default: `1`

min 1

`per_page`

integer

Optional

Collections per page (max 100).

Default: `20`

min 1 · max 100

### Responses

-   200
    
    A page of collections
    
-   401
    
    [`missing_api_key`](/docs/errors/#missing_api_key): no `Authorization` header. [`invalid_api_key`](/docs/errors/#invalid_api_key): the header is not `Bearer pv_live_…`/`pv_test_…`/`pv_pub_…`, or the key is unknown or revoked.
    
-   403
    
    [`publishable_key_forbidden`](/docs/errors/#publishable_key_forbidden): publishable keys (`pv_pub_`) can only upload images; use a secret key. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. Honour `Retry-After`.
    

Request

curlNode.jsPython

```
curl https://api.pixelvault.dev/v1/collections \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"
```

Response 200

```
{
  "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`](/docs/api/images/#sign_image_url), [`sign_video_url`](/docs/api/videos/#sign_video_url) or [`sign_audio_url`](/docs/api/audio/#sign_audio_url).

### Authentication

API key, sent as `Authorization: Bearer <key>`.

### Path parameters

Path parameters

Name

Type

Required

Description

`id`

string

Required

Collection id.

### Responses

-   200
    
    The collection with its members
    
-   401
    
    [`missing_api_key`](/docs/errors/#missing_api_key): no `Authorization` header. [`invalid_api_key`](/docs/errors/#invalid_api_key): the header is not `Bearer pv_live_…`/`pv_test_…`/`pv_pub_…`, or the key is unknown or revoked.
    
-   403
    
    [`publishable_key_forbidden`](/docs/errors/#publishable_key_forbidden): publishable keys (`pv_pub_`) can only upload images; use a secret key. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   404
    
    [`collection_not_found`](/docs/errors/#collection_not_found): no collection with this id in the project.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. Honour `Retry-After`.
    

Request

curlNode.jsPython

```
curl https://api.pixelvault.dev/v1/collections/col_abc123 \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"
```

Response 200

```
{
  "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

Path parameters

Name

Type

Required

Description

`id`

string

Required

Collection id.

### Responses

-   200
    
    The closed collection
    
-   401
    
    [`missing_api_key`](/docs/errors/#missing_api_key): no `Authorization` header. [`invalid_api_key`](/docs/errors/#invalid_api_key): the header is not `Bearer pv_live_…`/`pv_test_…`/`pv_pub_…`, or the key is unknown or revoked.
    
-   403
    
    [`publishable_key_forbidden`](/docs/errors/#publishable_key_forbidden): publishable keys (`pv_pub_`) can only upload images; use a secret key. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   404
    
    [`collection_not_found`](/docs/errors/#collection_not_found): no collection with this id in the project.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. Honour `Retry-After`.
    

Request

curlNode.jsPython

```
curl -X POST https://api.pixelvault.dev/v1/collections/col_abc123/close \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"
```

Response 200

```
{
  "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"
  }
}
```
