> ## 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. # List library items > 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`. ## OpenAPI ````yaml /openapi.json get /v1/library openapi: 3.0.3 info: description: >- The Tella Public API allows you to programmatically access your videos and playlists, including transcripts, chapters, and thumbnails. ## Authentication All requests require a Bearer token in the Authorization header: ``` Authorization: Bearer tella_pk_xxxxx... ``` API keys can be generated in your Tella workspace settings. ## Rate Limiting The API is rate-limited to 100 requests per minute per user within a workspace. Rate limit information is returned in response headers: - `RateLimit-Policy`: Named quota, request limit, and window in seconds - `RateLimit`: Remaining quota and seconds until reset - `X-RateLimit-Limit`: Maximum requests per window - `X-RateLimit-Remaining`: Remaining requests in current window - `X-RateLimit-Reset`: Unix timestamp in milliseconds when the window resets A `429 Too Many Requests` response also includes `Retry-After` in seconds. title: Tella Public API version: 1.0.0 servers: - description: Production url: https://api.tella.com security: [] tags: - description: Video operations name: Videos - description: Sections of a video name: Clips - description: Playlist operations name: Playlists - description: Sidebar groups for organizing playlists name: Playlist Groups - description: Tags for categorizing and filtering videos name: Tags - description: Personal, workspace, and default video backgrounds name: Backgrounds - description: >- Reusable media saved to a workspace, plus Tella's curated sound effect catalog — the same items the editor's media panels show name: Library - description: Webhook endpoint management name: Webhooks externalDocs: description: API versioning and deprecation policy url: https://www.tella.com/docs/versioning paths: /v1/library: get: tags: - Library summary: List library items description: >- 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`. operationId: listLibraryItems parameters: - description: >- 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) in: query name: scope required: true schema: $ref: '#/components/schemas/LibraryReadScope' - description: >- Only return items of this type. With `scope=default` only `sound-effect` is valid, since the curated catalog holds no other media type. in: query name: type schema: allOf: - $ref: '#/components/schemas/LibraryItemType' description: >- Only return items of this type. With `scope=default` only `sound-effect` is valid, since the curated catalog holds no other media type. - description: >- 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. in: query name: cursor schema: description: >- 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. type: string - description: >- 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. in: query name: limit schema: description: >- 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. example: 24 maximum: 60 minimum: 1 type: integer responses: '200': content: application/json: schema: $ref: '#/components/schemas/ListLibraryResponse' description: OK headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '400': content: application/json: example: docsUrl: https://docs.tella.com/ error: bad_request message: The request was malformed or contained invalid parameters. schema: $ref: '#/components/schemas/ErrorResponse' description: The request was malformed or contained invalid parameters. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '401': content: application/json: example: docsUrl: https://docs.tella.com/ error: unauthorized message: Authentication is required. Provide a valid API key. schema: $ref: '#/components/schemas/ErrorResponse' description: Authentication is required. Provide a valid API key. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '403': content: application/json: example: docsUrl: https://docs.tella.com/ error: forbidden message: You don't have permission to access this resource. schema: $ref: '#/components/schemas/ErrorResponse' description: You don't have permission to access this resource. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '404': content: application/json: example: docsUrl: https://docs.tella.com/ error: not_found message: The requested resource was not found. schema: $ref: '#/components/schemas/ErrorResponse' description: The requested resource was not found. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '429': content: application/json: example: docsUrl: https://docs.tella.com/ error: rate_limited message: You have exceeded the rate limit. Please slow down. schema: $ref: '#/components/schemas/ErrorResponse' description: You have exceeded the rate limit. Please slow down. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Retry-After: $ref: '#/components/headers/RetryAfter' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '500': content: application/json: example: docsUrl: https://docs.tella.com/ error: server_error message: An unexpected error occurred schema: $ref: '#/components/schemas/ErrorResponse' description: An unexpected error occurred headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '501': content: application/json: example: docsUrl: https://docs.tella.com/ error: not_implemented message: The requested operation is not implemented. schema: $ref: '#/components/schemas/ErrorResponse' description: The requested operation is not implemented. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' security: - BearerAuth: [] components: schemas: LibraryReadScope: description: >- 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) enum: - private - workspace - default example: private type: string LibraryItemType: description: The kind of media the item holds enum: - image - video - sound-effect - music - lut example: video type: string ListLibraryResponse: additionalProperties: false description: A page of library items properties: cursor: description: Cursor for the next page. Absent when there are no more items. type: string items: items: $ref: '#/components/schemas/LibraryItem' type: array required: - items type: object ErrorResponse: additionalProperties: false description: Standard error response format properties: docsUrl: description: Link to Tella API documentation example: https://docs.tella.com/ format: uri type: string error: description: Machine-readable error code enum: - bad_request - unauthorized - forbidden - not_found - rate_limited - server_error - not_implemented example: not_found type: string message: description: Human-readable error message example: Resource not found type: string required: - error - message - docsUrl type: object LibraryItem: additionalProperties: false description: >- A placeable piece of media — either saved to a workspace's library, or an entry in Tella's curated catalog properties: category: description: >- Catalog grouping, for `default` items only — the same grouping the editor's sound effects panel shows example: Everyday type: string createdAt: description: >- ISO-8601 creation timestamp. Absent for `default` catalog items, which are served from Tella's catalog rather than stored as rows. type: string dimensions: additionalProperties: false description: Pixel dimensions, for visual media properties: height: maximum: 9007199254740991 minimum: -9007199254740991 type: integer width: maximum: 9007199254740991 minimum: -9007199254740991 type: integer required: - width - height type: object durationMs: description: Duration in milliseconds, for time-based media example: 4200 type: number id: description: Unique library item identifier example: media_abc123def456 type: string name: description: Display name shown in the library example: Intro camera take type: string presetId: description: >- 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. example: cha-ching type: string scope: $ref: '#/components/schemas/LibraryReadScope' sourceId: description: >- 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. example: su_abc123def456 type: string type: $ref: '#/components/schemas/LibraryItemType' updatedAt: description: ISO-8601 update timestamp. Absent for `default` catalog items. type: string url: description: >- 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. type: string required: - id - type - name - scope type: object headers: Deprecation: description: Indicates that an API operation is deprecated, following RFC 9745 example: '@1767225600' schema: type: string RateLimit: description: >- Current quota with remaining requests (`r`) and seconds until reset (`t`) example: '"public-api";r=95;t=42' schema: type: string RateLimitPolicy: description: >- Named quota policy with the request limit (`q`) and window in seconds (`w`) example: '"public-api";q=100;w=60' schema: type: string Sunset: description: >- Indicates when a deprecated API operation will become unavailable, following RFC 8594 example: Tue, 30 Jun 2026 23:59:59 GMT schema: type: string XRateLimitLimit: description: Maximum requests allowed in the current window example: 100 schema: type: integer XRateLimitRemaining: description: Requests remaining in the current window example: 95 schema: type: integer XRateLimitReset: description: Unix timestamp in milliseconds when the window resets example: 1704067200000 schema: format: int64 type: integer RetryAfter: description: Seconds to wait before retrying a rate-limited request example: 45 schema: minimum: 1 type: integer securitySchemes: BearerAuth: description: API key obtained from your Tella account settings scheme: bearer type: http ```` ## Related topics - [Media library API](/docs/media-library-api.md) - [Remove a library item](/docs/api-reference/library/remove-a-library-item.md) - [Model Context Protocol (MCP)](/docs/mcp-server.md) - [Add a source to the library](/docs/api-reference/library/add-a-source-to-the-library.md) - [List available backgrounds](/docs/api-reference/backgrounds/list-available-backgrounds.md)