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

Pagination

List endpoints for media and collections use offset pagination with two query parameters, page and per_page, and return the page in data plus a meta object with the total.

curl "https://api.pixelvault.dev/v1/images?page=2&per_page=50" \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"
{
  "data": [
    { "id": "img_abc123", "url": "https://img.pixelvault.dev/proj_xyz789/img_abc123.png" }
  ],
  "meta": { "total": 132, "page": 2, "per_page": 50 }
}

Parameters

ParamDefaultRange
page1Integer, 1 or more
per_page20Integer, 1–100

Out-of-range values are clamped rather than rejected: per_page=500 returns 100 items, page=0 or a non-number falls back to the default. Send integers. Only invalid filters return 400.

Response

meta.total counts every item matching your filters, so the last page is ceil(total / per_page). There is no cursor, has_more, or total_pages field: stop when page * per_page >= total. Results are newest first (created_at descending), except a full-text image search (q), which is best match first. Because pages are offsets, items uploaded while you page can shift later pages by a few rows; dedupe on id if that matters.

Example
// Walk every image in the project, 100 at a time.
async function* allImages() {
  for (let page = 1; ; page++) {
    const res = await fetch(`https://api.pixelvault.dev/v1/images?page=${page}&per_page=100`, {
      headers: { Authorization: `Bearer ${process.env.PIXELVAULT_API_KEY}` },
    });
    if (!res.ok) throw new Error(`List failed: ${res.status}`);
    const { data, meta } = await res.json();
    yield* data;
    if (page * meta.per_page >= meta.total) return;
  }
}

for await (const image of allImages()) console.log(image.url);

Paginated lists

EndpointFilters
GET /v1/imagescollection_id, metadata/meta[key], q (AI description search), tag
GET /v1/videosfolder (400 invalid_folder if malformed), collection_id, metadata/meta[key]
GET /v1/audiofolder, collection_id, metadata/meta[key]
GET /v1/collectionstype, name

Filters combine with AND. Metadata filters are described in Organize media.

Lists that return everything

EndpointReturns
GET /v1/images/tagsThe 40 most used AI tags with counts
GET /v1/keysEvery key in the project (at most 25)
GET /v1/webhooksdata.webhooks plus the plan's endpoint limit and remaining (at most 10 endpoints)
GET /v1/webhooks/:id/deliveriesThe newest deliveries; limit 1–100, default 50, no offset
GET /v1/collections/:idThe collection with all of its members

Next steps