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

# Backgrounds API

Discover hosted ScreenFramed background packs, thumbnails, tags, and ready-to-use capture parameters.

The backgrounds API lists built-in gradient and image backgrounds you can use with `background`, `background_preset`, `background_gradient`, or `background_image_url`.

**List backgrounds**

Returns background assets and ready-to-use ScreenFramed capture parameters.

## List backgrounds

```bash
curl "https://screenframed.com/v1/backgrounds?limit=20&theme=dark" \
  -H "Accept: application/json"
```

## List packs

```bash
curl "https://screenframed.com/v1/backgrounds/packs" \
  -H "Accept: application/json"
```

## Use a hosted background

Copy the returned `screenframed_params.background` value into a capture request:

```json
{
  "url": "https://example.com",
  "background": "fractal-glass-gradients/fractal-glass-34",
  "device": "browser-macos",
  "shadow": "float",
  "aspect_ratio": "16:9"
}
```

## Response shape

```json
{
  "presets": [
    {
      "id": "midnight",
      "name": "Midnight",
      "type": "gradient_preset",
      "background_style": "gradient",
      "background_preset": "midnight"
    }
  ],
  "backgrounds": [
    {
      "id": "fractal-glass-gradients/fractal-glass-34",
      "name": "Fractal Glass 34",
      "group": "backgrounds",
      "pack": "fractal-glass-gradients",
      "theme": "dark",
      "thumbnail_url": "https://...",
      "screenframed_params": {
        "background": "fractal-glass-gradients/fractal-glass-34"
      }
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}
```

Hosted backgrounds are resolved to render-sized image variants during capture, which keeps composition faster than downloading oversized public images.

` GET /v1/backgrounds `

List hosted backgrounds

Returns gradient presets and hosted background assets that can be used in capture requests.

## Servers

- ` https://screenframed.com ` — Production

## Parameters

### ` limit ` (query, optional)

- ` value `: type ` integer `

  - default: ` 100 `

  - minimum: ` 1 `

  - maximum: ` 500 `

### ` offset ` (query, optional)

- ` value `: type ` integer `

  - default: ` 0 `

  - minimum: ` 0 `

### ` group ` (query, optional)

Comma-separated asset groups. Defaults to backgrounds, gradients, and css-backgrounds.

- ` value `: type ` string `

### ` pack ` (query, optional)

Comma-separated pack names.

- ` value `: type ` string `

### ` type ` (query, optional)

Comma-separated asset types.

- ` value `: type ` string `

### ` theme ` (query, optional)

- ` value `: type ` string `

  - enum: ` ["light","dark","mixed"] `

### ` q ` (query, optional)

Search name, pack, and tags.

- ` value `: type ` string `

## Responses

### ` 200 ` — Background list

Content type: ` application/json `

- ` value `: type ` object `

  - Required fields: ` presets `, ` backgrounds `, ` total `, ` limit `, ` offset `

  - ` presets `: type ` array `

    - ` array item `: type ` object `

      - ` id `: type ` string `

      - ` name `: type ` string `

      - ` type `: type ` string `

        - enum: ` ["gradient_preset"] `

      - ` background_style `: type ` string `

        - enum: ` ["gradient"] `

      - ` background_preset `: type ` string `

        - enum: ` ["aurora","sunset","ocean","midnight","arctic","dusk","forest","ember","custom"] `

      - ` css `: type ` string `

      - ` stops `: type ` array `

        - ` array item `: type ` object `

          - ` color `: type ` string `

          - ` position `: type ` string `

  - ` backgrounds `: type ` array `

    - ` array item `: type ` object `

      - ` id `: type ` string `

      - ` name `: type ` string `

      - ` slug `: type ` string `; nullable

      - ` type `: type ` string `; nullable

      - ` subtype `: type ` string `; nullable

      - ` group `: type ` string `; nullable

      - ` pack `: type ` string `; nullable

      - ` theme `: type ` string `; nullable

      - ` format `: type ` string `; nullable

      - ` tags `: type ` array `

        - ` array item `: type ` string `

      - ` background `: type ` string `; nullable

      - ` image_url `: type ` string `; nullable; format ` uri `

      - ` thumbnail_url `: type ` string `; nullable; format ` uri `

      - ` config `: type ` unknown `; nullable

      - ` screenframed_params `: type ` object `; nullable

  - ` total `: type ` integer `

  - ` limit `: type ` integer `

  - ` offset `: type ` integer `

### ` 401 ` — Error response

Content type: ` application/json `

- ` value `: type ` object `

  - Required fields: ` error `

  - ` error `: type ` object `

    - Required fields: ` code `, ` message `

    - ` code `: type ` string `

    - ` message `: type ` string `

    - ` details `: type ` object `

    - ` retry_after `: type ` integer `

### ` 403 ` — Error response

Content type: ` application/json `

- ` value `: type ` object `

  - Required fields: ` error `

  - ` error `: type ` object `

    - Required fields: ` code `, ` message `

    - ` code `: type ` string `

    - ` message `: type ` string `

    - ` details `: type ` object `

    - ` retry_after `: type ` integer `

## Request examples

### cURL

```curl
curl -X GET 'https://screenframed.com/v1/backgrounds' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://screenframed.com/v1/backgrounds', {
  method: 'GET',
  headers: {
      "Authorization": "Bearer YOUR_API_TOKEN"
  }
});

const data = await response.json();
console.log(data);
```

### Python

```python
import requests

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN'
}

response = requests.get('https://screenframed.com/v1/backgrounds', headers=headers)
print(response.json())
```