> ## Documentation Index
> Fetch the complete documentation index at: https://www.tella.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Library

> Save reusable media to the workspace library and browse Tella's curated sound effects and music.

The library is where reusable media lives — images, videos, sound effects, music and LUTs. It is the same set the editor's **Media library** and **Sound effects** panels show.

<Tip>
  Saving a source to the library is what makes it findable later. A source you never add is only reachable through the clips that reference it, so deleting the video takes the last handle on it with it.
</Tip>

## list\_library

List placeable media for one scope. Media still being generated is omitted.

<ParamField path="scope" type="enum<string>" required>
  Which library to read: `private` (only you), `workspace` (shared with the workspace), or `default` (Tella's curated catalog).
</ParamField>

<ParamField path="type" type="enum<string>">
  Only return `image`, `video`, `sound-effect`, `music`, or `lut` items.
</ParamField>

<ParamField path="cursor" type="string">
  Cursor from a previous response — keep paging while `cursor` is present.
</ParamField>

<ParamField path="limit" type="integer">
  Items per page (1-60, default 24). A target rather than an exact count: a page is read before unlistable items are filtered out, so a response may hold somewhat more. Page until `cursor` is absent rather than counting items.
</ParamField>

What comes back depends on where the item came from:

* **Added through the API or generated with AI** — includes a `sourceId` you can pass straight to `add_overlay`, `add_layout`, `add_sound_effect` or `upload_clip` (images included), alongside the hosted `url`. A `workspace` item's `sourceId` works for every member of the workspace, not just whoever uploaded it.
* **Uploaded in the editor** — has no source and exposes only a `url`, so it can't be placed through the API.

<Accordion title="The default catalog">
  `scope: "default"` returns Tella's curated sound effects and background music — the same tracks the editor's panels show.

  * Presets have no source, so items carry a `presetId` instead of a `sourceId`: `sound-effect` items go to `add_sound_effect`, `music` items to `set_background_music`.
  * Each item also has a `category` for grouping and a publicly fetchable `url` for auditioning the audio.
  * Filter with `type: "sound-effect"` or `type: "music"`; omitting `type` returns both. Any other `type` is an error.
  * The catalog is fixed, so it comes back as a single page and never sets a `cursor`.
  * Tella's default backgrounds are not here — they are placed as a background rather than a source, so use `list_backgrounds`.
</Accordion>

## add\_library\_item

Save an uploaded source to the library. Call `create_source` first, `PUT` the bytes to the returned `uploadUrl`, then pass the `sourceId` here.

<ParamField path="sourceId" type="string" required>
  Source ID from `create_source`, already uploaded
</ParamField>

<ParamField path="name" type="string">
  Display name shown in the library — defaults to the item's type
</ParamField>

<ParamField path="scope" type="enum<string>">
  `private` (default) or `workspace` to share it with everyone in the workspace — `workspace` requires an owner or member role
</ParamField>

<ParamField path="type" type="enum<string>">
  Expected item type — the type is taken from the source's own kind, and supplying a value that disagrees is an error
</ParamField>

## remove\_library\_item

Remove an item from the library. This removes the library entry only — clips already using the underlying source keep working.

<ParamField path="id" type="string" required>
  Library item ID from `list_library`
</ParamField>

<ParamField path="scope" type="enum<string>" required>
  The library the item lives in — `private` or `workspace`
</ParamField>


## Related topics

- [Media library API](/docs/media-library-api.md)
- [Remove a library item](/docs/api-reference/library/remove-a-library-item.md)
- [Add a source to the library](/docs/api-reference/library/add-a-source-to-the-library.md)
- [List library items](/docs/api-reference/library/list-library-items.md)
- [Set your preferences](/docs/help/account/preferences.md)