---
title: "List available backgrounds"
method: GET
path: "/v1/backgrounds"
tags: ["Backgrounds"]
---

# List available backgrounds

`GET /v1/backgrounds`

Returns personal uploads, workspace uploads, and Tella's default image and animated backgrounds in named categories. Each item includes a preview URL and a background value that can be passed directly to the clip update endpoint.

## Query parameters

- `scope` 'personal' | 'workspace' | 'default' — Where the background comes from: the authenticated user's uploads, workspace uploads, or Tella's default catalog
- `categoryId` string — Filter by category ID, such as personal, workspace, default:tella, default:macos, or default:animated

## Response `200`

OK

- ListBackgroundsResponse — Background categories visible to the authenticated user
  - `categories` BackgroundCategory[], required
    - `backgrounds` BackgroundItem[], required
      - `background` ClipBackgroundOutput, required — Clip background. Use type = 'solid' with `color`, type = 'image' or 'video' with `sourceId` (from `POST /v1/sources`) or an exact catalog URL from `GET /v1/backgrounds`, or type = 'gradient' with `gradientColor1`, `gradientColor2`, `gradientAngle`.
        - `color` string, nullable — Hex color string. Required when type = 'solid'.
        - `gradientAngle` integer, nullable — Linear gradient angle in degrees. Required when type = 'gradient'.
        - `gradientColor1` string, nullable — Hex color string. Required when type = 'gradient'.
        - `gradientColor2` string, nullable — Hex color string. Required when type = 'gradient'.
        - `imageUrl` string, uri, nullable — Hosted image URL. Present in responses and accepted as input only when copied exactly from `GET /v1/backgrounds`; otherwise pass `sourceId`.
        - `sourceId` string, nullable — Source ID from `POST /v1/sources` (`kind: image` for type = 'image', `kind: video` for type = 'video'). Required for image/video backgrounds unless using an exact URL from `GET /v1/backgrounds`. Input-only.
        - `type` 'solid' | 'gradient' | 'image' | 'video', required — Background variant
        - `videoDurationSeconds` number, nullable — Video background duration in seconds. Read-only: derived from the uploaded source or catalog entry on input.
        - `videoUrl` string, uri, nullable — Hosted video URL. Present in responses and accepted as input only when copied exactly from `GET /v1/backgrounds`; otherwise pass `sourceId`.
      - `name` string, required — Human-readable display name within the category
      - `thumbnailUrl` string, uri, required — Preview image requested at 192x108 when the image host supports resizing
    - `id` string, required — Stable category identifier
    - `name` string, required — Human-readable category name
    - `scope` 'personal' | 'workspace' | 'default', required — Where the background comes from: the authenticated user's uploads, workspace uploads, or Tella's default catalog

## 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)