---
title: "List your saved assets"
method: GET
path: "/api/v1/assets"
tags: ["Assets"]
---

# List your saved assets

`GET /api/v1/assets`

## Request

- Base URL: `https://api.popnow.ai`
- URL: `https://api.popnow.ai/api/v1/assets`
- Auth: HTTP bearer

Returns the ready assets of the key's library, one page at a time. Pass
the previous page's `nextCursor` as `cursor` to continue; it is absent on
the last page, and a cursor only works with the `sort` it came from.
Filter with `kind`, `source` (comma-separated), `favorite`, `collectionId`
(one collection of the key's library; collections are created and edited in
the console, and an id outside this library returns 404), `entityId` (the
images of one character) and a case-insensitive name search in `q`.
Order with `sort`: `recent` (default, newest first), `oldest`, `name`
(case-insensitive A to Z) or `size` (largest first).

Every item carries a stable `uri` (`popnow://a/<id>`) and a private
`previewUrl` signed for at most 20 minutes. The `uri` works only in
generation requests made with keys of the same workspace (any media field
of a model input); nothing in this API returns a permanent or publicly
reachable link, so the asset library cannot be used as file hosting.
Responses are `private, no-store`. Listing and reading assets is limited
to 60 requests per minute per account.

The key decides the library: a key created in your personal workspace
reaches your personal library, and a key created in a team workspace
(by any member) reaches that team's shared library. A team key never
reaches anyone's personal library. What a team key may change follows
the current role of the member who created it: owner and admin can save,
rename and delete anything; developer can save and rename or delete only
what they saved; billing and readonly can only read and use assets. If
that member has left the team the key gets 403 with `data.reason`
`asset_workspace_forbidden`.

## Query parameters

- `kind` 'image' | 'video' | 'audio'
- `source` string
- `q` string
- `favorite` boolean
- `collectionId` string
- `entityId` string
- `sort` 'recent' | 'oldest' | 'name' | 'size'
- `cursor` string
- `limit` integer

## Response `200`

One page of assets.

- AssetListEnvelope
  - `code` 200, required
  - `msg` 'success', required
  - `request_id` string, required: Correlation identifier. Include it in support requests.
  - `data` AssetList, required
    - `items` Asset[], required
      - `id` string, required
      - `uri` string, required: Stable reference. Works only in generation requests made with keys of the same workspace; it is never a downloadable link.
      - `name` string, required
      - `kind` 'image' | 'video' | 'audio', required
      - `contentType` string, required
      - `bytes` integer, required
      - `width` integer
      - `height` integer
      - `durationSeconds` number
      - `source` 'task_output' | 'upload' | 'url', required
      - `sourceId` string, required: Your task or upload id; for url, an opaque digest of the address (the address itself is not stored).
      - `createdAt` string, date-time, required
      - `updatedAt` string, date-time, required
      - `previewUrl` string, required: Private preview signed for you for at most 20 minutes; empty when signing fails. Do not store or share it — persist uri instead.
      - `previewUrlExpiresAt` string, date-time
      - `favorite` boolean, required: Favorite mark of the library (shared by everyone in a team).
      - `model` string, required: Public name of the model that generated the asset, for example bytedance/seedream-5.0-pro/text-to-image; empty for uploads and links.
      - `modelName` string, required: Display name of that model; empty when the asset was not generated or the name is unknown.
    - `nextCursor` string: Absent on the last page.

## Other responses

- `400`: Invalid JSON, query, callback URL, model input, or media declaration. Invalid callBackUrl values return code 400 and msg "Invalid callback URL" with request_id. Submitted hosts, IP addresses, and DNS diagnostics are not echoed.
- `401`: Missing, malformed, expired, revoked, or otherwise invalid API key.
- `403`: Account, model, API-key, IP, or region authorization failed.
- `404`: Resource does not exist or is not visible to this account and API key. These cases are intentionally indistinguishable.
- `429`: Account-level request limit exceeded.
- `500`: Internal failure. Details are not exposed; report `request_id` to support.

## Changes

- **2026-10-20** `fede911a6e9b`: 72 warning
  - added the new `agent_project_budget` enum value to the `allOf[subschema #2]/data/reason` response property for the response status `400`
  - added the new `agent_project_budget` enum value to the `allOf[subschema #2]/data/reason` response property for the response status `401`
  - added the new `agent_project_budget` enum value to the `allOf[subschema #2]/data/reason` response property for the response status `403`
  - added the new `agent_project_budget` enum value to the `allOf[subschema #2]/data/reason` response property for the response status `404`
  - …68 more

[Operation history](https://skmtc.dev/popnow/apis/popnow-api/changes/api/v1/assets/get.md)

---

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