---
title: "Add a source to the library"
method: POST
path: "/v1/library"
tags: ["Library"]
---

# Add a source to the library

`POST /v1/library`

Saves an uploaded source to the library so it can be listed and reused later, both here and in the editor's media panels. Create the source via `POST /v1/sources` and upload the bytes first, then pass its `sourceId`. Without this a source is only reachable through the clips that already reference it.

## Request body

- CreateLibraryItemRequest — Save an uploaded source to the library so it can be listed and reused later
  - `name` string — Display name shown in the library. Defaults to the item's type.
  - `scope` 'private' | 'workspace' — Which library the item belongs to: `workspace` items are shared with everyone in the workspace, `private` items are only visible to their creator
  - `sourceId` string, required — Source ID from `POST /v1/sources`, with the bytes already uploaded to its `uploadUrl`
  - `type` 'image' | 'video' | 'sound-effect' — Expected item type. Optional — the type is taken from the source's own kind; supplying a value that disagrees is an error.

## Response `201`

Created

- CreateLibraryItemResponse — The newly created library item
  - `item` LibraryItem, required — A placeable piece of media — either saved to a workspace's library, or an entry in Tella's curated catalog
    - `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)