---
title: "Build with the News API"
description: "Discover feeds, page direct-source news items, and retrieve AI-generated topic recaps"
canonical: https://y2.dev/docs/api/news/
---

# Build with the News API

Discover feeds, page direct-source news items, and retrieve AI-generated topic recaps

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

| Need                               | Operation                 |
| ---------------------------------- | ------------------------- |
| Discover the current topic catalog | `GET /api/v1/news/feeds`  |
| Page individual source items       | `GET /api/v1/news`        |
| Read a synthesized topic recap     | `GET /api/v1/news/recaps` |

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](https://y2.dev/docs/api/x402). 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:

| Field                 | Use                                                     |
| --------------------- | ------------------------------------------------------- |
| `id`                  | Machine-readable value for the `topics` query parameter |
| `name`, `shortLabel`  | Full and compact display labels                         |
| `description`         | Human-readable feed purpose                             |
| `group`, `groupLabel` | Picker grouping metadata                                |
| `color`               | Current UI gradient classes. Do not use as identity     |
| `ingestOntology`      | Whether eligible items can enter Y2's ontology pipeline |

`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:

Prop

Type

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.

Cache initialization

`/news` and `/news/recaps` can return `503 CACHE_NOT_READY` before their respective caches have any data. Retry with backoff. A successful empty or partially populated recap object means the cache exists but not every requested topic has a current recap.

## Combine News with structured intelligence

News items are narrative observations. Use [OSINT v1](https://y2.dev/docs/api/osint) for broader normalized event, country, geospatial, and source-health surfaces. Use [Intel v2](https://y2.dev/docs/api/intel) when you need stable incidents, entities, relationships, FININT, or extracted decision signals.

[List news items](https://y2.dev/docs/api/reference/news/listNews)

[List recaps](https://y2.dev/docs/api/reference/news/listRecaps)

[List feeds](https://y2.dev/docs/api/reference/news/listFeeds)

[News product guide](https://y2.dev/docs/news)

[Integration recipes](https://y2.dev/docs/api/integration-recipes)

[API Workbench](https://y2.dev/docs/api/workbench)

[Authentication](https://y2.dev/docs/api/authentication)
