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

# Introduction

> Base URL, authentication, and the shape of every response.

## Base URL

```text theme={null}
https://api.lightdrift.ai
```

## Authentication

Pass your API key in the `X-API-Key` header on every request:

```bash theme={null}
curl https://api.lightdrift.ai/v1/search \
  -H "X-API-Key: $LIGHTDRIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "sea otter floating on its back"}'
```

Billing is per query. There are no seats and no minimums.

## The response shape

Every search endpoint returns the same envelope — a ranked list of results, each carrying the full [rights answer](/guides/rights):

```json theme={null}
{
  "query": "sea otter floating on its back",
  "count": 8,
  "latency_ms": 96,
  "results": [
    {
      "asset_id": "inat:41290763",
      "score": 0.83214,
      "title": "Sea Otter, Morro Bay",
      "file": "https://assets.lightdrift.ai/inat/41290763.jpg",
      "license": "cc-by-4.0",
      "rights": { "...": "see Rights answers" },
      "cv": {
        "palette": ["#2b4a5e", "#7fa8b8", "#dce8ec"],
        "luminance": 0.42,
        "neg_space": ["top"],
        "faces": 0,
        "aspect": 1.5
      }
    }
  ]
}
```

## Design-layer filters

Any search can be constrained on how the image *looks*, not just what it shows. Pass a `filters` object:

| Filter                            | Type       | Meaning                                                         |
| --------------------------------- | ---------- | --------------------------------------------------------------- |
| `luminance_min` / `luminance_max` | number 0–1 | Overall brightness.                                             |
| `monochrome`                      | boolean    | Only (or never) monochrome images.                              |
| `faces_min` / `faces_max`         | integer    | Detected face count.                                            |
| `aspect_min` / `aspect_max`       | number     | Width ÷ height.                                                 |
| `neg_space_any`                   | string\[]  | Require clean negative space: `left`, `right`, `top`, `bottom`. |
| `palette_near`                    | string     | Prefer images whose palette sits near this hex color.           |

Or set `parse_design: true` and write the intent in plain language — "dark and moody, room for a headline on the left" — and Lightdrift applies the filters for you, reporting what it inferred in `applied_design`.