# Feed API integration

Connect your website to published content using the current API contract.

The Feed serves the content of the workspace identified by your key. Obtain the endpoint and credential privately from your authorised operator; this documentation site does not accept keys.

## Discover the contract

Open `/v1/openapi.json` on your assigned Feed endpoint. It defines the available routes, parameters and response schemas. Use that version of the contract as the integration reference.

The Feed covers published briefings, front-page and category views, search, related coverage, coverage by country, statistics, RSS and JSON Feed. Audio, social, source and cluster access depend on enabled features.

## Choose the right key

- A **secret key** belongs on your server and travels only in the Authorization Bearer header. It is refused in a URL or a browser-origin request.
- A **publishable key** is intended for permitted browser origins. Its allowed origins and enabled capabilities still apply.
- An **MCP key** is a separate credential for the MCP interface; do not substitute a Feed key for it.

Prefer a server-side integration when you do not need direct browser access. Never place a secret key in browser code, page HTML, analytics, a URL or a support message.

## Implement a reading journey

1. Obtain your endpoint and key through your runtime's secret facility.
2. Read the OpenAPI contract and choose an enabled list or search route.
3. Start with a small page and preserve its filter and cursor contract.
4. Read a returned briefing identifier or slug using the documented detail route.
5. Render the briefing with its original source links and applicable publication dates.
6. Handle access changes and withdrawn content on subsequent requests.

## Count coverage by country

When the clusters feature is enabled, two routes report how many outlets in each country wrote about a story:

- `GET /v1/clusters/{id}/coverage`
- `GET /v1/briefings/{slug}/coverage`

Both accept `lang` for the briefing language. The optional `maxDistance` accepts values from 0.05 to 0.30 and defaults to 0.22; a value outside that range returns 400 `invalid_parameter`. Keep the default unless you have tested another value against your own stories.

```sh
curl -H "Authorization: Bearer $REFRACTO_FEED_KEY" \
  "https://<your-feed-endpoint>/v1/clusters/<cluster-id>/coverage?lang=en"
```

Read the response this way:

- Use `countries[].outlets` for the number of outlets in a country. `cluster.sourceCount` counts only the sources inside the cluster and leaves out related reporting, so it understates national coverage of a large story.
- `countries[].sources[]` lists each outlet with its article count. `inCluster: false` marks an outlet that reported the story but sits outside the cluster.
- An outlet is one website in a country. When Refracto reads several section feeds of the same newspaper, such as its main feed and its economy section, they count as one outlet under the newspaper's name and their articles add up.
- `byGroup` shows where the articles come from: `cluster` for the cluster and its briefings, `linked` for reporting linked to the story, `nearbyClusters` and `unclustered` for reporting found by similarity. An outlet counts once in its country even when it appears in several groups.
- `linked` leaves out recurring digests, such as a daily front-page review an outlet publishes under the same title every day, and counts a piece once when the outlet published it at two addresses.
- `basis` is `links` when the story's period is covered by established links, and `distance` when the count is computed by similarity instead. A `distance` response can take longer.
- `window` gives the period searched around the story, or null when none applies.
- When a story has been merged with a duplicate, `cluster.id` can be the surviving story rather than the identifier you requested, and the counts include both.

The response contains counts and outlet identities, never article text. Like all coverage, it reflects reporting available to Refracto: the outlets it reads and, for each outlet, the feeds it reads, not every publisher or every page in a country. Show a zero as no coverage found, not as proof that no outlet reported the story.

## Media and errors

Media routes check access again and may redirect to an authorised short-lived file URL. Do not forward the private Feed key to that destination.

Treat 401 and 403 as access problems, 404 as unavailable content and 429 as a request-budget refusal. Honour Retry-After when supplied. See [troubleshooting](/docs/troubleshooting) before retrying repeatedly.
