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
- Obtain your endpoint and key through your runtime's secret facility.
- Read the OpenAPI contract and choose an enabled list or search route.
- Start with a small page and preserve its filter and cursor contract.
- Read a returned briefing identifier or slug using the documented detail route.
- Render the briefing with its original source links and applicable publication dates.
- 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}/coverageGET /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.
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[].outletsfor the number of outlets in a country.cluster.sourceCountcounts 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: falsemarks 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.
byGroupshows where the articles come from:clusterfor the cluster and its briefings,linkedfor reporting linked to the story,nearbyClustersandunclusteredfor reporting found by similarity. An outlet counts once in its country even when it appears in several groups.linkedleaves 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.basisislinkswhen the story's period is covered by established links, anddistancewhen the count is computed by similarity instead. Adistanceresponse can take longer.windowgives the period searched around the story, or null when none applies.- When a story has been merged with a duplicate,
cluster.idcan 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 before retrying repeatedly.