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
| Param | Default | Range |
|---|---|---|
page | 1 | Integer, 1 or more |
per_page | 20 | Integer, 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.
// 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
| Endpoint | Filters |
|---|---|
GET /v1/images | collection_id, metadata/meta[key], q (AI description search), tag |
GET /v1/videos | folder (400 invalid_folder if malformed), collection_id, metadata/meta[key] |
GET /v1/audio | folder, collection_id, metadata/meta[key] |
GET /v1/collections | type, name |
Filters combine with AND. Metadata filters are described in Organize media.
Lists that return everything
| Endpoint | Returns |
|---|---|
GET /v1/images/tags | The 40 most used AI tags with counts |
GET /v1/keys | Every key in the project (at most 25) |
GET /v1/webhooks | data.webhooks plus the plan's endpoint limit and remaining (at most 10 endpoints) |
GET /v1/webhooks/:id/deliveries | The newest deliveries; limit 1–100, default 50, no offset |
GET /v1/collections/:id | The collection with all of its members |
Next steps
- Export all media instead of paging through everything to back it up.
- Search images by their AI descriptions.