---
title: "List library items"
method: GET
path: "/v1/library"
tags: ["Library"]
---

# List library items

`GET /v1/library`

Returns a page of reusable media saved to the library — images, videos, sound effects, music and LUTs — for one scope. Items added through the API include a `sourceId` you can pass anywhere a source is accepted, including images. Editor-added images, music and LUTs expose a hosted `url` instead. Media still being generated in the editor is omitted. `scope=default` returns Tella's curated sound effect catalog instead of stored media: those items carry a `presetId` to place them with, a `category`, and a publicly fetchable `url` for previewing, and arrive as a single page. Tella's default backgrounds are not part of this catalog — they are placed as a background rather than as a source, and are listed by `GET /v1/backgrounds`.

## Query parameters

- `scope` 'private' | 'workspace' | 'default', required — Which set of media to read: `private` (only visible to their creator), `workspace` (shared with everyone in the workspace), or `default` (Tella's curated sound effect catalog, which holds no other media type)
- `type` 'image' | 'video' | 'sound-effect' | 'music' | 'lut' — The kind of media the item holds
- `cursor` string — Pagination cursor from a previous response. Keep paging while `cursor` is present. `scope=default` is a fixed catalog returned as a single page, so it never sets one.
- `limit` integer — Items per page (1-60, default 24). Treat it as a target rather than an exact count: pages are read from storage before unlistable items are filtered out, and cursors address whole storage pages, so a response may contain somewhat more than `limit`. Returning the extra items is deliberate — trimming them would drop them, because the cursor has already moved past.

## Response `200`

OK

- ListLibraryResponse — A page of library items
  - `cursor` string — Cursor for the next page. Absent when there are no more items.
  - `items` LibraryItem[], required
    - `category` string — Catalog grouping, for `default` items only — the same grouping the editor's sound effects panel shows
    - `createdAt` string — ISO-8601 creation timestamp. Absent for `default` catalog items, which are served from Tella's catalog rather than stored as rows.
    - `dimensions` object — Pixel dimensions, for visual media
      - `height` integer, required
      - `width` integer, required
    - `durationMs` number — Duration in milliseconds, for time-based media
    - `id` string, required — Unique library item identifier
    - `name` string, required — Display name shown in the library
    - `presetId` string — Preset ID, for `default` catalog items only. A preset has no source until it is placed, so pass this to `POST /v1/videos/{id}/clips/{clipId}/sound-effects` instead of `sourceId`; placing it copies the effect into a source owned by your workspace.
    - `scope` 'private' | 'workspace' | 'default', required — Which set of media to read: `private` (only visible to their creator), `workspace` (shared with everyone in the workspace), or `default` (Tella's curated sound effect catalog, which holds no other media type)
    - `sourceId` string — Source ID. Pass it anywhere a `sourceId` is accepted — clips, layouts, overlays, sound effects. Present for every item added through this API, including images. Absent for items added in the editor, which have no source, for music and LUT items, and for `default` catalog items, which use `presetId` instead.
    - `type` 'image' | 'video' | 'sound-effect' | 'music' | 'lut', required — The kind of media the item holds
    - `updatedAt` string — ISO-8601 update timestamp. Absent for `default` catalog items.
    - `url` string — Hosted media URL, for `image`, `music` and `lut` items, and for `default` catalog items, where it is a publicly fetchable preview of the audio. Images expose this alongside `sourceId`; use `sourceId` to place the image on a clip, since overlays and layout media do not accept URLs.

## Other responses

- `400` — The request was malformed or contained invalid parameters.
- `401` — Authentication is required. Provide a valid API key.
- `403` — You don't have permission to access this resource.
- `404` — The requested resource was not found.
- `429` — You have exceeded the rate limit. Please slow down.
- `500` — An unexpected error occurred
- `501` — The requested operation is not implemented.

---

[API](https://skmtc.dev/withchima/apis/tella-public-api.md) · [All operations](https://skmtc.dev/withchima/apis/tella-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/withchima/tella-public-api/revisions/ba2bb13928a5/schema)