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

`/v1/search` and `/v1/similar` return the same envelope — a ranked list of results, each carrying the full [rights answer](/guides/rights):

```json theme={null}
{
  "query_id": "q_e6458536ccdc445b",
  "results": [
    {
      "asset_id": "govflickr:8412901414",
      "score": 0.7518,
      "title": null,
      "source": "govflickr",
      "width": 1024,
      "height": 768,
      "file": "https://api.lightdrift.ai/v1/asset/q_e6458536ccdc445b/govflickr:8412901414",
      "thumb": "https://api.lightdrift.ai/v1/asset/q_e6458536ccdc445b/govflickr:8412901414?v=thumb",
      "rights": {
        "...": "see Rights answers"
      }
    }
  ],
  "backend": "voyage",
  "mode": "auto",
  "ranking": "text",
  "latency_ms": 5965
}
```

* `query_id` ties every file fetch back to the query that produced it. Keep it.
* `score` is the reranker's relevance score, higher is better, not a calibrated probability. Similar-image searches use retrieval similarity; skipped reranking can return null. It is also `null` on the rare response that also carries `"degraded": "reranker unavailable; lane-order results"` — results are still valid, just ordered by retrieval rank instead of rerank.
* `file` and `thumb` are **tracked URLs**: a `GET` answers `302` to a signed download link valid for one hour. Follow redirects.

## Filters

Filters constrain retrieval before ranking. Omitted commercial, AI-generation, width and NSFW fields retain their API defaults; see [Search defaults](/guides/search). Pass null where supported to remove a default.

| Filter                     | Type                                  | Meaning                                                                                                                                  |
| -------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `commercial`               | boolean                               | Only assets whose declared license permits commercial use. Defaults to true; null removes this restriction.                              |
| `attribution_required`     | boolean                               | Only assets that do (`true`) or do not (`false`) require attribution.                                                                    |
| `derivatives`              | boolean                               | Only assets whose license permits derivative works.                                                                                      |
| `license_id`               | string\[]                             | Restrict to these licenses, e.g. `["cc0", "cc-by", "pdm"]`.                                                                              |
| `source`                   | string\[]                             | Restrict to these sources, e.g. `["inat", "wikimedia"]`.                                                                                 |
| `min_width` / `min_height` | integer                               | Minimum pixel dimensions of the full-resolution file.                                                                                    |
| `orientation`              | `landscape` \| `portrait` \| `square` | Aspect class.                                                                                                                            |
| `format`                   | string\[]                             | File formats, e.g. `["jpeg", "png"]`.                                                                                                    |
| `year_min` / `year_max`    | integer                               | Capture or creation year, where the source declares one.                                                                                 |
| `monochrome`               | boolean                               | Only (or never) monochrome images.                                                                                                       |
| `colors`                   | string\[]                             | Dominant named colours (`red`, `navy`, `cream`, …). Present only where an image has a clear dominant palette, coverage varies by source. |
| `ai_generated`             | boolean                               | Select or exclude assets the source marks as AI-generated.                                                                               |
| `nsfw_max`                 | number 0–1                            | Maximum permitted NSFW score. Default `0.2`; assets without a score pass.                                                                |

See [Searching the index](/guides/search) for every filter with examples.

Describe mood, style, composition and intended use in the natural-language query. These are semantic requests, not guaranteed hard filters. You can also supply a reference image using `image_base64` or a public HTTPS `image_url`, with optional text to refine the search. See [image search examples](/guides/search#search-with-an-image) for supported formats, limits, and request payloads.