Build with the News API

Use the News API to add current narrative context to dashboards, alerts, reports, or intelligence pipelines. The API reads Y2's cached direct-source terminal data; it does not run a new source fetch for each request.

Choose an output

The News base URL is:

https://api.y2.dev/api/v1/news

Authenticate

Send a bearer key with news:read:

curl "https://api.y2.dev/api/v1/news/feeds" \
  --header "Authorization: Bearer $Y2_API_KEY"

All three News operations also support x402 pay-per-request. Without a bearer key, the first request returns 402 Payment Required; retry with the payment header described in that response. Do not send a bearer key and x402 payment together.

Discover feed IDs

Call GET /feeds instead of hard-coding the catalog. The current registry contains 40 topics grouped across crypto, AI and technology, macro and finance, politics and geopolitics, industry, and regional desks.

curl "https://api.y2.dev/api/v1/news/feeds" \
  --header "Authorization: Bearer $Y2_API_KEY"

Each data row contains:

meta.defaultTopics currently contains crypto, geopolitics, macro, equities, ai, and energy. Omitting topics from item or recap requests uses that set.

Page news items

Pass one or more comma-separated feed IDs. The server merges matching caches, removes duplicate source items by their upstream ID, sorts newest first, and returns up to 200 rows.

curl --get "https://api.y2.dev/api/v1/news" \
  --header "Authorization: Bearer $Y2_API_KEY" \
  --data-urlencode "topics=cyber,semiconductors,ai" \
  --data-urlencode "limit=100"

The JSON response has data, meta, and links. Follow links.next until it is null; do not edit the opaque cursor or reuse it with different topic filters.

A canonical news item includes:

Treat source URL, publisher, language, and retrieval metadata as nullable. A source record can be identified even when the provider did not supply every attribution field.

Stream rows as NDJSON

For a warehouse or line-oriented processor, request NDJSON. Each non-empty line is one canonical news item; continuation moves to X-Y2-Next-Cursor because the body contains rows only.

curl --get "https://api.y2.dev/api/v1/news" \
  --header "Authorization: Bearer $Y2_API_KEY" \
  --header "Accept: application/x-ndjson" \
  --data-urlencode "topics=geopolitics,energy" \
  --data-urlencode "limit=200"

You can also send format=ndjson. Preserve the original topics and limit when sending the next cursor.

Retrieve topic recaps

Use recaps when an application needs synthesis rather than individual items. Supported timeframes are 12h, 24h, 3d, and 7d; the default is 12h.

curl --get "https://api.y2.dev/api/v1/news/recaps" \
  --header "Authorization: Bearer $Y2_API_KEY" \
  --data-urlencode "topics=macro,equities,rates_fx" \
  --data-urlencode "timeframe=24h"

data is an object keyed by topic ID. A requested topic can be absent when no valid cached recap exists for that topic and timeframe. Use meta.topics and meta.timeframe to retain request context; do not treat a missing topic as an empty recap.

Combine News with structured intelligence

News items are narrative observations. Use OSINT v1 for broader normalized event, country, geospatial, and source-health surfaces. Use Intel v2 when you need stable incidents, entities, relationships, FININT, or extracted decision signals.