API

Response format

Illustrative response shapes, not live results. An empty items array can be a successful response.

• items — stories with id, title, summary, topics, publication times, source links and a score. Some fields may be null.
• window, generated_at and offset describe this feed response; has_more indicates another page with the same filters.
• version is the most recent recalculation timestamp, not a request parameter. Ranking can change between pages; compare versions and deduplicate by id.
• Search returns query and items, without has_more or version.

{
  "window": "24h",
  "generated_at": "2026-10-13T10:00:00.000Z",
  "version": 0,
  "offset": 0,
  "has_more": false,
  "items": []
}

{
  "query": "Mars",
  "items": []
}

Errors and empty results

If the upstream request fails or rejects the parameters, the public feed endpoint returns HTTP 200 with degraded: true. Check that flag as well as the HTTP status; keep your last successful data and check the parameters before retrying.

{
  "items": [],
  "degraded": true
}

Search returns HTTP 200 with query and items. On an upstream failure, the response also contains degraded: true and is not cached. An empty items array without that flag is a successful empty result; keep only previous results for the same query and retry reading later.

{
  "query": "Mars",
  "items": [],
  "degraded": true
}

Also handle network failure and responses that are not JSON. Keep the last successful data and retry later; avoid a continuous retry loop.

Use and caching

• Successful responses declare caching: the feed uses 30 seconds in the browser and 60 seconds for shared caches; search uses 60 seconds. Follow the cache headers.
• Read with GET; OPTIONS handles the browser preflight. No key is needed, and cross-origin reading is allowed. Avoid continuous requests and retry loops.
• The texts belong to the outlets. Source links should take the reader to the original publication.