# EarlyWave API

EarlyWave reads news from tens of thousands of sources and groups the articles into stories, called trends. The API gives you read access to those trends and to your own data: monitors, feeds, folders, articles and saved items.

There are two ways in, over the same 18 read-only operations:

- **REST** — `https://api.earlywave.ai/api/v1`, JSON over HTTPS, one `GET` per operation.
- **MCP** — `https://api.earlywave.ai/mcp`, the same operations as tools for Claude, Cursor, VS Code and any other MCP client.

Both use the same keys and the same two counters (a minute window and a monthly quota by plan: 10,000 requests a month on Pro, 50,000 on Max) and return the same data.

## Start here

1. [Quickstart](https://www.earlywave.ai/developers/docs/quickstart) — a key, a first request and an MCP client in five minutes.
2. [Authentication](https://www.earlywave.ai/developers/docs/authentication) — keys, scopes and access.
3. [Errors, limits and paging](https://www.earlywave.ai/developers/docs/errors-and-limits) — what every response has in common.
4. [MCP server](https://www.earlywave.ai/developers/docs/mcp) — client setup and the list of tools.
5. [API reference](https://www.earlywave.ai/developers/reference) — every operation, parameter and field.

## What you can read

| Area | REST | MCP tool | Returns |
|---|---|---|---|
| Trends | [`GET /trends`](https://www.earlywave.ai/developers/reference#listTrends) | `list_trends` | List trends |
| Trends | [`GET /trends/{trend_id}`](https://www.earlywave.ai/developers/reference#getTrend) | `get_trend` | Get a trend |
| Trends | [`GET /trends/{trend_id}/articles`](https://www.earlywave.ai/developers/reference#listTrendArticles) | `get_trend_articles` | List a trend's articles |
| Trends | [`GET /trends/{trend_id}/coverage`](https://www.earlywave.ai/developers/reference#getTrendCoverage) | `get_trend_coverage` | Get where a trend is covered |
| Monitors | [`GET /monitors`](https://www.earlywave.ai/developers/reference#listMonitors) | `list_monitors` | List your monitors |
| Monitors | [`GET /monitors/{monitor_id}/results`](https://www.earlywave.ai/developers/reference#getMonitorResults) | `get_monitor_results` | Get a monitor's results |
| Feeds | [`GET /feeds`](https://www.earlywave.ai/developers/reference#listFeeds) | `find_feeds` | List your subscribed feeds |
| Feeds | [`GET /feeds/discover`](https://www.earlywave.ai/developers/reference#discoverFeeds) | `discover_feeds` | Search the feed catalogue |
| Feeds | [`GET /feeds/{feed_id}`](https://www.earlywave.ai/developers/reference#getFeed) | `get_feed` | Get one of your feeds |
| Feeds | [`GET /feeds/{feed_id}/items`](https://www.earlywave.ai/developers/reference#listFeedItems) | `get_feed_items` | List a feed's articles |
| Folders | [`GET /categories`](https://www.earlywave.ai/developers/reference#listFolders) | `list_categories` | List your folders |
| Folders | [`GET /categories/{category_id}/items`](https://www.earlywave.ai/developers/reference#listFolderItems) | `get_category_items` | List a folder's articles |
| Folders | [`GET /items`](https://www.earlywave.ai/developers/reference#listItems) | `get_all_items` | List all your articles |
| Articles | [`GET /articles/search`](https://www.earlywave.ai/developers/reference#searchArticles) | `search_articles` | Search your articles |
| Articles | [`GET /articles/{article_id}`](https://www.earlywave.ai/developers/reference#getArticle) | `get_article` | Get an article |
| Saved | [`GET /saved`](https://www.earlywave.ai/developers/reference#listSaved) | `list_saved` | List your saved items |
| Discover | [`GET /discover`](https://www.earlywave.ai/developers/reference#discoverItems) | `discover_items` | Search all recent articles |
| Discover | [`GET /discover/keywords`](https://www.earlywave.ai/developers/reference#discoverKeywords) | `discover_top_keywords` | Top keywords |

Trends are EarlyWave's catalogue: every key sees the same trends, whatever its account follows. Everything else — monitors, feeds, folders, articles, saved items — belongs to the account that owns the key.

## Access

The REST API and the MCP server are included with Pro (10,000 requests a month) and Max (50,000). See [plans](https://www.earlywave.ai/pricing). Create keys in EarlyWave under **Settings › API & MCP** ([open it](https://www.earlywave.ai/settings/developers)).

## Conventions

- JSON in, JSON out. Field and parameter names are `snake_case`, the same on REST and MCP.
- Timestamps are ISO 8601 in UTC, for example `2026-10-19T08:55:31.000Z`.
- Countries are ISO 3166-1 alpha-2 codes (`FR`, `US`). Languages are short codes such as `fr` or `en`.
- Every list takes `limit` (1–100, default 20) and `offset`, and answers `has_more`.
- Every error is `{"error": {"type", "code", "message"}}` with a stable `type`.
- The API is read-only. Monitors, feeds and folders are created in the app or with Ask EarlyWave.

## Machine-readable

- OpenAPI 3.1: [`https://api.earlywave.ai/api/v1/openapi.json`](https://api.earlywave.ai/api/v1/openapi.json) — the contract. Each operation carries its MCP tool name in `x-mcp-tool`.
- [`/llms.txt`](https://www.earlywave.ai/llms.txt) and [`/llms-full.txt`](https://www.earlywave.ai/llms-full.txt) — these docs for coding agents.
- Every docs page is also served as Markdown: add `.md` to its address, for example [`/developers/docs/quickstart.md`](https://www.earlywave.ai/developers/docs/quickstart.md).

---
Source: https://www.earlywave.ai/developers/docs · All docs: https://www.earlywave.ai/llms.txt