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

# Clair News API

> A news-intelligence data API. Define the entities you care about locally; get every article Clair linked to them, deterministically.

Clair maintains a continuously-collected corpus of world news and lets you pull
the slice that matters to **you**. You describe an entity (a company, a theme, a
country, anything), embed it into a vector on your own machine, and Clair returns
the news that matches, ranked and explainable.

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/docs/quickstart">
    Get a key and pull your first matched news in five minutes.
  </Card>

  <Card title="How it works" icon="diagram-project" href="/docs/how-it-works">
    The stateless-vector model, the two-stage match, and why scores are
    reproducible.
  </Card>

  <Card title="API reference" icon="code" href="/docs/api-reference/introduction">
    `POST /v1/match` and `GET /v1/sources`, with a live request playground.
  </Card>
</CardGroup>

## The model in one paragraph

Clair owns **only news**: text and embeddings. Entities are a **client-side**
concept: an open, pinned embedding model (`bge-m3`) turns your entity's
description into a single 1024-dimensional vector, and only that vector is sent.
Clair matches it against the corpus and returns the articles it links to. Because
the model is open and deterministic, the same entity always produces the same
vector and the same scores; nothing in the loop can drift or hallucinate. The
moat is the **corpus** (un-backfillable historical text), not the vectors.

<Note>
  Your entity text never leaves your machine. Only the 1024-dim vector is sent,
  and it is reproducible from public model weights, so there is nothing secret
  to protect on the client.
</Note>

## Three ways to ask

One endpoint, and the query decides how it reads.

<CardGroup cols={3}>
  <Card title="Ranked" icon="crosshairs">
    Send `text` or a vector to get the top matches by score, with the passage that
    explains each one. A snapshot: best first, no paging.
  </Card>

  <Card title="Complete" icon="clock">
    Add `order=time` to get *everything* at or above your score floor in the
    window, newest first, paged to the end. The monitoring loop.
  </Card>

  <Card title="Bulk" icon="water">
    Send no query at all for the corpus itself, chronologically. Match locally with
    the open `bge-m3` model. For heavy users and archives.
  </Card>
</CardGroup>