Quickstart

Lightdrift is in private beta. If you don’t have an API key yet, sign up at lightdrift.ai/sign-up and create one in the dashboard.Default photo searches now use Voyage embeddings and caption reranking, without waiting for our legacy GPU service to warm up. All search modes use the Voyage index. See Search for modes and retry behavior.

Using an MCP client such as Claude Code, Cursor, or Claude? Skip the key: add https://lightdrift.ai/mcp and sign in when it asks. Per-client commands are on Connect Images MCP.

Get an API key

Make your first search

Pass your key in the X-API-Key header and describe what you need:

curl -X POST https://api.lightdrift.ai/v1/search \
  -H "X-API-Key: $LIGHTDRIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "a spanish shawl nudibranch on a reef", "k": 5}'

import requests

r = requests.post(
    "https://api.lightdrift.ai/v1/search",
    headers={"X-API-Key": LIGHTDRIFT_API_KEY},
    json={"query": "a spanish shawl nudibranch on a reef", "k": 5},
)
for hit in r.json()["results"]:
    print(hit["title"], hit["file"], hit["rights"]["license"])

const r = await fetch("https://api.lightdrift.ai/v1/search", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.LIGHTDRIFT_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "a spanish shawl nudibranch on a reef", k: 5 }),
});
const { results } = await r.json();

Read the rights answer

Every result carries a rights object — license, permission flags, a ready-to-use attribution string, and how the file is delivered:

{
  "license": "cc-by",
  "license_verbatim": "CC BY 4.0",
  "commercial": true,
  "attribution_required": true,
  "attribution": "\"Spanish shawl (Flabellina iodinea)\" by anudibranchmom, inat, CC BY",
  "provenance_url": "https://www.inaturalist.org/photos/41290763",
  "basis": "as-declared by source; verify for critical use"
}

See Rights answers for the full field reference and the posture behind it.

Use the file

file is a tracked URL: a GET returns 302 to a signed download link valid for one hour, so follow redirects. thumb is the same with ?v=thumb for a 512px preview. Both are tied to the query_id they came from.

Connect your coding agent (optional)

Working with Cursor, Claude Code, or another MCP client? Add this docs site as an MCP server so your agent can look up Lightdrift usage itself:

claude mcp add --transport http lightdrift-docs https://docs.lightdrift.ai/mcp

See Connect Docs MCP for setup in other clients and troubleshooting.

Search guide

Filters, similar-image expansion, file delivery, and the patterns that work — with real responses.

Use with agents

Give your agent the whole engine as a tool.

Get started

Learn

Account

Core concepts

Next

Search guide

Use with agents

​Next

Search guide

Use with agents

Next