Images Videos Audio Pricing Docs View as Markdown (Agent) Get started
Human Agent

API reference

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

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; 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; 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

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: no Authorization header. 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: 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. Honour Retry-After.

Request
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, sign_video_url or 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: no Authorization header. 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: 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. Honour Retry-After.

Request
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

Request
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"
  }
}