---
title: "List and search assets"
method: GET
path: "/api/v1/assets"
tags: ["Asset Management"]
---

# List and search assets

`GET /api/v1/assets`

## Request

- Base URL: `https://api.imagestep.dev`
- URL: `https://api.imagestep.dev/api/v1/assets`
- Auth: API key in header `Authorization`

Paginated list of the caller's assets, newest-created first. Every filter is optional
and they compose: `?tag=cat&mime=image/jpeg&minWidth=2000`.

Each row is an `AssetSummary` — what an asset is called, what it is, how it is labelled and
published, and when it expires. The image facts, `metadata` and `lineage` are only on
GET /api/v1/assets/{id}. To walk a whole library, follow `meta.nextCursor` as `cursor` rather than
counting pages: a cursor page counts nothing. A chain job's intermediate products are left out
unless `includeIntermediate=true`.

USE THIS WHEN:
- Listing a view (all, published) or one collection
- Filtering by tag, MIME type, pixel dimensions, capture date or source operation
- Free-text search over the name and camera make/model

DO NOT USE WHEN:
- Retrieving a single asset by ID → use GET /api/v1/assets/{id}
- Listing the collections that exist → use GET /api/v1/assets/collections

## Query parameters

- `page` integer
- `perPage` integer
- `cursor` string
- `view` 'ALL' | 'PUBLISHED'
- `collection` string
- `tag` string
- `hasCollection` boolean
- `mime` string
- `jobId` string
- `op` string
- `source` 'upload' | 'process' | 'ai-generate' | 'ai-edit' | 'render'
- `minWidth` integer
- `maxWidth` integer
- `minHeight` integer
- `maxHeight` integer
- `takenFrom` string
- `takenTo` string
- `createdFrom` string
- `createdTo` string
- `status` 'PROCESSING' | 'DONE' | 'FAILED'
- `q` string
- `includeIntermediate` boolean

## Response `200`

One page of rows; `meta` carries `hasMore` and `nextCursor`

## Other responses

- `400`: - `invalid_param` on `hasCollection` — sent together with `collection`, which already says the asset is in one - `invalid_param` on `status`, `takenFrom`, `takenTo`, `createdFrom` or `createdTo` — a value it cannot read - `invalid_param` — `source` is not one of its values (this one names no `param`) - `invalid_param` on `cursor` — malformed, taken from another listing, or sent together with `page`
- `429`: Rate limited — `error.code` is `rate_limited` and `retryable` is true. `Retry-After` says how many seconds to wait.

---

[API](https://skmtc.dev/imagestep/apis/imagestep-api.md) · [All operations](https://skmtc.dev/imagestep/apis/imagestep-api/llms.txt) · [OpenAPI document](https://skmtc.dev/imagestep/apis/imagestep-api/revisions/5e8e922a3085?raw)