Reference
API reference
- Version
1.1.0- Base URL
https://api.earlywave.ai/api/v1- Authentication
Authorization: Bearer ew_live_…- MCP server
https://api.earlywave.ai/mcp- OpenAPI
- api.earlywave.ai/api/v1/openapi.jsonDownload the JSON
Start with the quickstart; errors, the minute window, the monthly quota and paging are explained in Errors, limits and paging.
On this page
- Trends
- List trends
- Get a trend
- List a trend's articles
- Get where a trend is covered
- Monitors
- List your monitors
- Get a monitor's results
- Feeds
- List your subscribed feeds
- Search the feed catalogue
- Get one of your feeds
- List a feed's articles
- Folders
- List your folders
- List a folder's articles
- List all your articles
- Articles
- Search your articles
- Get an article
- Saved
- List your saved items
- Discover
- Search all recent articles
- Top keywords
Read your feeds, articles, folders, saved items and monitors, and the trends EarlyWave detects across every source it reads.
Authentication. Send your key in the Authorization header: Authorization: Bearer ew_live_…. Create keys in EarlyWave › Settings › API & MCP. A key carries scopes: rest for this API, mcp for the MCP server.
Rate limit and monthly quota. Two counters per account, shared by every key, REST and MCP together: a fixed one-minute window and a calendar-month quota (UTC). Pro: 60 requests a minute and 10,000 a month; Max: 300 a minute and 50,000 a month. Every response carries X-RateLimit-* (minute) and X-Quota-* (month) headers; over either limit you get 429 with error.type = "rate_limit" and a Retry-After header — error.code says which counter refused: rate_limit_exceeded for the minute, quota_exceeded for the month (it resets on the 1st).
Errors. Always {"error": {"type", "code", "message"}}. type is one of invalid_request (400), authentication (401), permission (403), not_found (404), rate_limit (429), server (500).
Paging. Lists take limit (1–100, default 20) and offset, and answer has_more.
Same data over MCP. Each operation is also an MCP tool (x-mcp-tool) on https://api.earlywave.ai/mcp.
Trends
Stories detected across every source EarlyWave reads.
GET
/trendsList trends
Stories EarlyWave detects across every source it reads, strongest signal first. Filter by category, stage, the country a story is about, the country of its publishers, reach, or how recently it started.
MCP tool list_trends
Example
curl
curl "https://api.earlywave.ai/api/v1/trends?country=FR&since_hours=24&limit=5" \
-H "Authorization: Bearer $EARLYWAVE_API_KEY"Parameters
| Name | In | Type | Default | Description |
|---|---|---|---|---|
query | In query | stringmax 200 chars | — | Words the trend title contains. |
category | In query | stringmax 300 chars | — | Comma-separated: ai, tech, business, economy, crypto, cyber, geopolitics, politics, energy, climate, health, science, space, society, sports, cinema, people, music, world. |
stage | In query | stringmax 100 chars | — | Comma-separated: emerging, accelerating, breakout. |
country | In query | stringmax 2 chars | — | Country the story is about, ISO alpha-2 (e.g. "FR"). |
publisher_country | In query | stringmax 2 chars | — | Country with at least 2 sources covering it, ISO alpha-2. |
reach | In query | stringmax 100 chars | — | Comma-separated: local, national, international, global. |
since_hours | In query | integer1–720 | — | Only stories that started within this many hours (1–720). |
sort | In query | "signal" | "recent" | "sources" | Default signal | signal (default), recent (last activity) or sources. |
limit | In query | integer1–100 | Default 20 | Results per page (1–100, default 20). |
offset | In query | integer0–5000 | Default 0 | Results to skip, for paging (at most 5000). |
Response
200 application/json · TrendList
| Field | Type | Description |
|---|---|---|
trends | Trend[] | — |
trends[].id | integer | — |
trends[].title | string | — |
trends[].url | string | The trend page on earlywave.ai. |
trends[].status | string | — |
trends[].stage | string | emerging | accelerating | breakout |
trends[].category | string | — |
trends[].reach | string | null | local | national | international | global (null = not computed yet). |
trends[].subject_countries | string[] | Countries the story is about (alpha-2). |
trends[].publisher_countries | string[] | Countries with at least 2 publishing sources (alpha-2). |
trends[].item_count | integer | Articles. |
trends[].source_count | integer | Distinct sources (domains). |
trends[].signal_score | number | — |
trends[].velocity_1h | number | Articles in the last hour. |
trends[].velocity_24h | number | Articles in the last 24 hours. |
trends[].started_at | date-time | Story start: earliest trusted article. |
trends[].earliest_item_at | date-time | null | — |
trends[].first_seen_at | date-time | When EarlyWave grouped the story. |
trends[].last_activity_at | date-time | — |
total | integer | — |
limit | integer | Page size used. |
offset | integer | Results skipped. |
has_more | boolean | True when another page exists (call again with offset + limit). |
Errors
400Invalid parameters.401Missing, unknown or revoked key.403The key lacks therestscope, or the account does not include API access.429Rate limit exceeded (rate_limit_exceeded, the minute window) or monthly quota exceeded (quota_exceeded, resets on the 1st);Retry-Aftersays when.
GET
/trends/{trend_id}Get a trend
A trend with its summary, countries, languages, entities, keywords and its 10 latest articles.
MCP tool get_trend
Example
curl
curl "https://api.earlywave.ai/api/v1/trends/48213" \
-H "Authorization: Bearer $EARLYWAVE_API_KEY"Parameters
| Name | In | Type | Default | Description |
|---|---|---|---|---|
trend_idrequired | In path | integer> 0 | — | Trend ID. |
Response
200 application/json · TrendDetail
| Field | Type | Description |
|---|---|---|
id | integer | — |
title | string | — |
url | string | The trend page on earlywave.ai. |
status | string | — |
stage | string | emerging | accelerating | breakout |
category | string | — |
reach | string | null | local | national | international | global (null = not computed yet). |
subject_countries | string[] | Countries the story is about (alpha-2). |
publisher_countries | string[] | Countries with at least 2 publishing sources (alpha-2). |
item_count | integer | Articles. |
source_count | integer | Distinct sources (domains). |
signal_score | number | — |
velocity_1h | number | Articles in the last hour. |
velocity_24h | number | Articles in the last 24 hours. |
started_at | date-time | Story start: earliest trusted article. |
earliest_item_at | date-time | null | — |
first_seen_at | date-time | When EarlyWave grouped the story. |
last_activity_at | date-time | — |
summary | string | null | — |
regions | string[] | — |
publisher_languages | string[] | — |
top_entities | any | — |
top_keywords | any | — |
sources | object[] | The 10 most recently attached articles; all of them: /trends/{trend_id}/articles. |
sources[].id | integer | — |
sources[].title | string | — |
sources[].url | string | — |
sources[].published | date-time | null | — |
Errors
400Invalid parameters.401Missing, unknown or revoked key.403The key lacks therestscope, or the account does not include API access.404Not found (or not yours).429Rate limit exceeded (rate_limit_exceeded, the minute window) or monthly quota exceeded (quota_exceeded, resets on the 1st);Retry-Aftersays when.
GET
/trends/{trend_id}/articlesList a trend's articles
Every article of a trend with its source (title, site, country), newest or oldest first.
MCP tool get_trend_articles
Example
curl
curl "https://api.earlywave.ai/api/v1/trends/48213/articles?sort=oldest&limit=5" \
-H "Authorization: Bearer $EARLYWAVE_API_KEY"Parameters
| Name | In | Type | Default | Description |
|---|---|---|---|---|
trend_idrequired | In path | integer> 0 | — | Trend ID. |
sort | In query | "latest" | "oldest" | Default latest | latest (default) or oldest first. |
limit | In query | integer1–100 | Default 20 | Results per page (1–100, default 20). |
offset | In query | integer0–5000 | Default 0 | Results to skip, for paging (at most 5000). |
Response
200 application/json · TrendArticleList
| Field | Type | Description |
|---|---|---|
trend_id | integer | — |
articles | TrendArticle[] | — |
articles[].id | integer | — |
articles[].title | string | — |
articles[].url | string | — |
articles[].preview | string | Summary or description, up to 500 characters. |
articles[].image_url | string | null | — |
articles[].author | string | null | — |
articles[].published | date-time | null | — |
articles[].feed_id | integer | — |
articles[].language | string | null | — |
articles[].source | object | — |
total | integer | — |
limit | integer | Page size used. |
offset | integer | Results skipped. |
has_more | boolean | True when another page exists (call again with offset + limit). |
Errors
400Invalid parameters.401Missing, unknown or revoked key.403The key lacks therestscope, or the account does not include API access.404Not found (or not yours).429Rate limit exceeded (rate_limit_exceeded, the minute window) or monthly quota exceeded (quota_exceeded, resets on the 1st);Retry-Aftersays when.
GET
/trends/{trend_id}/coverageGet where a trend is covered
Publisher countries and languages of a trend (sources = distinct sites) and its last 7 days hour by hour.
MCP tool get_trend_coverage
Example
curl
curl "https://api.earlywave.ai/api/v1/trends/48213/coverage" \
-H "Authorization: Bearer $EARLYWAVE_API_KEY"Parameters
| Name | In | Type | Default | Description |
|---|---|---|---|---|
trend_idrequired | In path | integer> 0 | — | Trend ID. |
Response
200 application/json · TrendCoverage
| Field | Type | Description |
|---|---|---|
trend_id | integer | — |
total_articles | integer | — |
total_sources | integer | — |
first_article_at | date-time | null | — |
peak_at | date-time | null | — |
countries | object[] | Every publisher country, most sources first. |
countries[].country | string | Publisher country, alpha-2. |
countries[].sources | integer | — |
countries[].articles | integer | — |
countries[].first_article_at | date-time | — |
countries[].peak_hour | date-time | — |
languages | object[] | — |
languages[].language | string | — |
languages[].sources | integer | — |
languages[].articles | integer | — |
series | object | The last 7 days, hour by hour (168 buckets). |
series.start | date-time | Start of the first hourly bucket. |
series.step_minutes | integer | — |
series.articles | integer[] | — |
series.sources | integer[] | Distinct sources publishing in the hour. |
series.new_sources | integer[] | Sources seen for the first time in the story in the hour. |
Errors
400Invalid parameters.401Missing, unknown or revoked key.403The key lacks therestscope, or the account does not include API access.404Not found (or not yours).429Rate limit exceeded (rate_limit_exceeded, the minute window) or monthly quota exceeded (quota_exceeded, resets on the 1st);Retry-Aftersays when.
Monitors
Your monitors and what they found.
GET
/monitorsList your monitors
Your monitors (archived ones excluded), with their counts and next check.
MCP tool list_monitors
Example
curl
curl "https://api.earlywave.ai/api/v1/monitors" \
-H "Authorization: Bearer $EARLYWAVE_API_KEY"Parameters
No parameters.
Response
200 application/json · MonitorList
| Field | Type | Description |
|---|---|---|
monitors | Monitor[] | — |
monitors[].id | string | — |
monitors[].name | string | — |
monitors[].form | string | — |
monitors[].status | string | — |
monitors[].icon | string | null | — |
monitors[].results_count | integer | — |
monitors[].articles_count | integer | — |
monitors[].last_check_at | date-time | null | — |
monitors[].next_check_at | date-time | null | — |
monitors[].last_result_at | date-time | null | — |
monitors[].created_at | date-time | — |
monitors[].updated_at | date-time | — |
monitors[].conversation_ref | string | null | — |
monitors[].cadence | any | — |
monitors[].delivery_mode | string | — |
monitors[].calm_since | date-time | null | — |
total | integer | — |
Errors
400Invalid parameters.401Missing, unknown or revoked key.403The key lacks therestscope, or the account does not include API access.429Rate limit exceeded (rate_limit_exceeded, the minute window) or monthly quota exceeded (quota_exceeded, resets on the 1st);Retry-Aftersays when.
GET
/monitors/{monitor_id}/resultsGet a monitor's results
What a monitor found over the last days (newest first), with its sources and the current answers to its questions.
MCP tool get_monitor_results
Example
curl
curl "https://api.earlywave.ai/api/v1/monitors/0b7c6a52-4c1e-4e0b-9a51-2f8d3c1e7a90/results?days=7" \
-H "Authorization: Bearer $EARLYWAVE_API_KEY"Parameters
| Name | In | Type | Default | Description |
|---|---|---|---|---|
monitor_idrequired | In path | stringmax 64 chars | — | Monitor ID (from list_monitors / GET /monitors). |
days | In query | integer1–90 | Default 30 | Period in days (1–90, default 30). |
query | In query | stringmax 120 chars | — | Only results containing this text. |
limit | In query | integer1–100 | Default 20 | Results per page (1–100, default 20). |
Response
200 application/json · MonitorResults
| Field | Type | Description |
|---|---|---|
monitor | Monitor | — |
monitor.id | string | — |
monitor.name | string | — |
monitor.form | string | — |
monitor.status | string | — |
monitor.icon | string | null | — |
monitor.results_count | integer | — |
monitor.articles_count | integer | — |
monitor.last_check_at | date-time | null | — |
monitor.next_check_at | date-time | null | — |
monitor.last_result_at | date-time | null | — |
monitor.created_at | date-time | — |
monitor.updated_at | date-time | — |
monitor.conversation_ref | string | null | — |
monitor.cadence | any | — |
monitor.delivery_mode | string | — |
monitor.calm_since | date-time | null | — |
period_days | integer | — |
total | integer | — |
limit | integer | — |
has_more | boolean | — |
results | MonitorResult[] | — |
results[].id | string | — |
results[].kind | string | — |
results[].type | string | null | — |
results[].title | string | — |
results[].summary | string | null | — |
results[].event_date | date-time | null | — |
results[].fields | map | — |
results[].confidence | number | null | — |
results[].cluster_id | integer | null | — |
results[].sources_count | integer | — |
results[].first_seen_at | date-time | — |
results[].updated_at | date-time | — |
results[].hidden_at | date-time | null | — |
results[].feedback | string | null | — |
results[].sources | object[] | — |
answers | object[] | — |
answers[].question | string | — |
answers[].answer | string | null | — |
answers[].changed_at | date-time | null | — |
Errors
400Invalid parameters.401Missing, unknown or revoked key.403The key lacks therestscope, or the account does not include API access.404Not found (or not yours).429Rate limit exceeded (rate_limit_exceeded, the minute window) or monthly quota exceeded (quota_exceeded, resets on the 1st);Retry-Aftersays when.
Feeds
Your subscriptions and the feed catalogue.
GET
/feedsList your subscribed feeds
Lists the RSS feeds the account is subscribed to, optionally filtered by a keyword (title, description, address) or a domain.
MCP tool find_feeds
Example
curl
curl "https://api.earlywave.ai/api/v1/feeds?domain=lemonde.fr" \
-H "Authorization: Bearer $EARLYWAVE_API_KEY"Parameters
| Name | In | Type | Default | Description |
|---|---|---|---|---|
query | In query | stringmax 500 chars | — | Keyword matched against title, description and feed address. |
domain | In query | stringmax 200 chars | — | Domain the feed address contains, e.g. "lemonde.fr". |
limit | In query | integer1–100 | Default 20 | Results per page (1–100, default 20). |
offset | In query | integer0–5000 | Default 0 | Results to skip, for paging (at most 5000). |
Response
200 application/json · FeedList
| Field | Type | Description |
|---|---|---|
feeds | Feed[] | — |
feeds[].id | integer | — |
feeds[].title | string | — |
feeds[].feed_url | string | — |
feeds[].website_url | string | null | — |
feeds[].description | string | — |
feeds[].language | string | null | — |
feeds[].country | string | null | Publisher country, ISO 3166-1 alpha-2. |
feeds[].subscribers | integer | null | — |
feeds[].items_count | integer | null | — |
feeds[].latest_fetch | date-time | null | — |
total | integer | — |
limit | integer | Page size used. |
offset | integer | Results skipped. |
has_more | boolean | True when another page exists (call again with offset + limit). |
Errors
400Invalid parameters.401Missing, unknown or revoked key.403The key lacks therestscope, or the account does not include API access.429Rate limit exceeded (rate_limit_exceeded, the minute window) or monthly quota exceeded (quota_exceeded, resets on the 1st);Retry-Aftersays when.
GET
/feeds/discoverSearch the feed catalogue
Searches every feed EarlyWave reads (not only your subscriptions), most-followed first.
MCP tool discover_feeds
Example
curl
curl "https://api.earlywave.ai/api/v1/feeds/discover?query=climate&country=FR" \
-H "Authorization: Bearer $EARLYWAVE_API_KEY"Parameters
| Name | In | Type | Default | Description |
|---|---|---|---|---|
queryrequired | In query | stringmax 500 chars | — | Keyword (at least 2 characters) matched against the title, the description and the publisher's domain. |
language | In query | stringmax 10 chars | — | Feed language code, e.g. "fr". |
country | In query | stringmax 3 chars | — | Publisher country, ISO alpha-2 ("FR") or alpha-3 ("FRA"). |
limit | In query | integer1–100 | Default 20 | Results per page (1–100, default 20). |
offset | In query | integer0–5000 | Default 0 | Results to skip, for paging (at most 5000). |
Response
200 application/json · FeedDiscoveryList
| Field | Type | Description |
|---|---|---|
query | string | — |
feeds | Feed[] | — |
feeds[].id | integer | — |
feeds[].title | string | — |
feeds[].feed_url | string | — |
feeds[].website_url | string | null | — |
feeds[].description | string | — |
feeds[].language | string | null | — |
feeds[].country | string | null | Publisher country, ISO 3166-1 alpha-2. |
feeds[].subscribers | integer | null | — |
feeds[].items_count | integer | null | — |
feeds[].latest_fetch | date-time | null | — |
limit | integer | Page size used. |
offset | integer | Results skipped. |
has_more | boolean | True when another page exists (call again with offset + limit). |
Errors
400Invalid parameters.401Missing, unknown or revoked key.403The key lacks therestscope, or the account does not include API access.429Rate limit exceeded (rate_limit_exceeded, the minute window) or monthly quota exceeded (quota_exceeded, resets on the 1st);Retry-Aftersays when.
GET
/feeds/{feed_id}Get one of your feeds
Details of a feed you are subscribed to, with its 24-hour and 7-day article counts.
MCP tool get_feed
Example
curl
curl "https://api.earlywave.ai/api/v1/feeds/1207" \
-H "Authorization: Bearer $EARLYWAVE_API_KEY"Parameters
| Name | In | Type | Default | Description |
|---|---|---|---|---|
feed_idrequired | In path | integer> 0 | — | Feed ID. |
Response
200 application/json · FeedDetail
| Field | Type | Description |
|---|---|---|
id | integer | — |
title | string | — |
feed_url | string | — |
website_url | string | null | — |
description | string | — |
language | string | null | — |
country | string | null | Publisher country, ISO 3166-1 alpha-2. |
subscribers | integer | null | — |
items_count | integer | null | — |
latest_fetch | date-time | null | — |
feed_broken | boolean | — |
items_count_24h | integer | null | — |
items_count_7d | integer | null | — |
Errors
400Invalid parameters.401Missing, unknown or revoked key.403The key lacks therestscope, or the account does not include API access.404Not found (or not yours).429Rate limit exceeded (rate_limit_exceeded, the minute window) or monthly quota exceeded (quota_exceeded, resets on the 1st);Retry-Aftersays when.
GET
/feeds/{feed_id}/itemsList a feed's articles
Articles of one of your feeds, newest first.
MCP tool get_feed_items
Example
curl
curl "https://api.earlywave.ai/api/v1/feeds/1207/items" \
-H "Authorization: Bearer $EARLYWAVE_API_KEY"Parameters
| Name | In | Type | Default | Description |
|---|---|---|---|---|
feed_idrequired | In path | integer> 0 | — | Feed ID. |
limit | In query | integer1–100 | Default 20 | Results per page (1–100, default 20). |
offset | In query | integer0–5000 | Default 0 | Results to skip, for paging (at most 5000). |
Response
200 application/json · FeedItemList
| Field | Type | Description |
|---|---|---|
feed_id | integer | — |
items | ArticleSummary[] | — |
items[].id | integer | — |
items[].title | string | — |
items[].url | string | — |
items[].preview | string | Summary or description, up to 500 characters. |
items[].image_url | string | null | — |
items[].author | string | null | — |
items[].published | date-time | null | — |
items[].feed_id | integer | — |
limit | integer | Page size used. |
offset | integer | Results skipped. |
has_more | boolean | True when another page exists (call again with offset + limit). |
Errors
400Invalid parameters.401Missing, unknown or revoked key.403The key lacks therestscope, or the account does not include API access.404Not found (or not yours).429Rate limit exceeded (rate_limit_exceeded, the minute window) or monthly quota exceeded (quota_exceeded, resets on the 1st);Retry-Aftersays when.
Folders
Your feed folders and their articles.
GET
/categoriesList your folders
Your feed folders, with the number of feeds in each.
MCP tool list_categories
Example
curl
curl "https://api.earlywave.ai/api/v1/categories" \
-H "Authorization: Bearer $EARLYWAVE_API_KEY"Parameters
No parameters.
Response
200 application/json · FolderList
| Field | Type | Description |
|---|---|---|
categories | Folder[] | — |
categories[].id | integer | — |
categories[].name | string | — |
categories[].feed_count | integer | — |
categories[].is_frozen | boolean | — |
total | integer | — |
Errors
400Invalid parameters.401Missing, unknown or revoked key.403The key lacks therestscope, or the account does not include API access.429Rate limit exceeded (rate_limit_exceeded, the minute window) or monthly quota exceeded (quota_exceeded, resets on the 1st);Retry-Aftersays when.
GET
/categories/{category_id}/itemsList a folder's articles
Articles from the feeds of one of your folders, newest first.
MCP tool get_category_items
Example
curl
curl "https://api.earlywave.ai/api/v1/categories/12/items" \
-H "Authorization: Bearer $EARLYWAVE_API_KEY"Parameters
| Name | In | Type | Default | Description |
|---|---|---|---|---|
category_idrequired | In path | integer> 0 | — | Folder ID. |
limit | In query | integer1–100 | Default 20 | Results per page (1–100, default 20). |
offset | In query | integer0–5000 | Default 0 | Results to skip, for paging (at most 5000). |
Response
200 application/json · FolderItemList
| Field | Type | Description |
|---|---|---|
category | object | — |
category.id | integer | — |
category.name | string | — |
items | ArticleSummary[] | — |
items[].id | integer | — |
items[].title | string | — |
items[].url | string | — |
items[].preview | string | Summary or description, up to 500 characters. |
items[].image_url | string | null | — |
items[].author | string | null | — |
items[].published | date-time | null | — |
items[].feed_id | integer | — |
total | integer | — |
limit | integer | Page size used. |
offset | integer | Results skipped. |
has_more | boolean | True when another page exists (call again with offset + limit). |
Errors
400Invalid parameters.401Missing, unknown or revoked key.403The key lacks therestscope, or the account does not include API access.404Not found (or not yours).429Rate limit exceeded (rate_limit_exceeded, the minute window) or monthly quota exceeded (quota_exceeded, resets on the 1st);Retry-Aftersays when.
GET
/itemsList all your articles
Articles from all your feeds, newest first.
MCP tool get_all_items
Example
curl
curl "https://api.earlywave.ai/api/v1/items" \
-H "Authorization: Bearer $EARLYWAVE_API_KEY"Parameters
| Name | In | Type | Default | Description |
|---|---|---|---|---|
limit | In query | integer1–100 | Default 20 | Results per page (1–100, default 20). |
offset | In query | integer0–5000 | Default 0 | Results to skip, for paging (at most 5000). |
Response
200 application/json · ItemList
| Field | Type | Description |
|---|---|---|
items | ArticleSummary[] | — |
items[].id | integer | — |
items[].title | string | — |
items[].url | string | — |
items[].preview | string | Summary or description, up to 500 characters. |
items[].image_url | string | null | — |
items[].author | string | null | — |
items[].published | date-time | null | — |
items[].feed_id | integer | — |
total | integer | — |
limit | integer | Page size used. |
offset | integer | Results skipped. |
has_more | boolean | True when another page exists (call again with offset + limit). |
Errors
400Invalid parameters.401Missing, unknown or revoked key.403The key lacks therestscope, or the account does not include API access.429Rate limit exceeded (rate_limit_exceeded, the minute window) or monthly quota exceeded (quota_exceeded, resets on the 1st);Retry-Aftersays when.
Articles
Articles of your feeds.
GET
/articles/searchSearch your articles
Articles of your feeds whose title, description, summary or keywords contain the query, newest first.
MCP tool search_articles
Example
curl
curl "https://api.earlywave.ai/api/v1/articles/search?query=election" \
-H "Authorization: Bearer $EARLYWAVE_API_KEY"Parameters
| Name | In | Type | Default | Description |
|---|---|---|---|---|
queryrequired | In query | stringmax 500 chars | — | Text to search for. |
limit | In query | integer1–100 | Default 20 | Results per page (1–100, default 20). |
offset | In query | integer0–5000 | Default 0 | Results to skip, for paging (at most 5000). |
Response
200 application/json · ArticleSearchList
| Field | Type | Description |
|---|---|---|
query | string | — |
articles | ArticleSummary[] | — |
articles[].id | integer | — |
articles[].title | string | — |
articles[].url | string | — |
articles[].preview | string | Summary or description, up to 500 characters. |
articles[].image_url | string | null | — |
articles[].author | string | null | — |
articles[].published | date-time | null | — |
articles[].feed_id | integer | — |
limit | integer | Page size used. |
offset | integer | Results skipped. |
has_more | boolean | True when another page exists (call again with offset + limit). |
Errors
400Invalid parameters.401Missing, unknown or revoked key.403The key lacks therestscope, or the account does not include API access.429Rate limit exceeded (rate_limit_exceeded, the minute window) or monthly quota exceeded (quota_exceeded, resets on the 1st);Retry-Aftersays when.
GET
/articles/{article_id}Get an article
One article from your feeds, with its text (up to 10,000 characters), summary and keywords.
MCP tool get_article
Example
curl
curl "https://api.earlywave.ai/api/v1/articles/9917305" \
-H "Authorization: Bearer $EARLYWAVE_API_KEY"Parameters
| Name | In | Type | Default | Description |
|---|---|---|---|---|
article_idrequired | In path | integer> 0 | — | Article ID. |
Response
200 application/json · Article
| Field | Type | Description |
|---|---|---|
id | integer | — |
title | string | — |
url | string | — |
preview | string | — |
content | string | Article text, up to 10,000 characters. |
keywords | string | null | — |
image_url | string | null | — |
author | string | null | — |
language | string | null | — |
published | date-time | null | — |
feed_id | integer | — |
Errors
400Invalid parameters.401Missing, unknown or revoked key.403The key lacks therestscope, or the account does not include API access.404Not found (or not yours).429Rate limit exceeded (rate_limit_exceeded, the minute window) or monthly quota exceeded (quota_exceeded, resets on the 1st);Retry-Aftersays when.
Saved
Articles, pages and searches you saved.
GET
/savedList your saved items
Articles, pages and searches you saved, newest first.
MCP tool list_saved
Example
curl
curl "https://api.earlywave.ai/api/v1/saved?type=article" \
-H "Authorization: Bearer $EARLYWAVE_API_KEY"Parameters
| Name | In | Type | Default | Description |
|---|---|---|---|---|
type | In query | "article" | "url" | "search" | — | article, url or search; all when omitted. |
limit | In query | integer1–100 | Default 20 | Results per page (1–100, default 20). |
offset | In query | integer0–5000 | Default 0 | Results to skip, for paging (at most 5000). |
Response
200 application/json · SavedList
| Field | Type | Description |
|---|---|---|
type | string | — |
saved | SavedEntry[] | — |
saved[].type | "article" | "url" | "search" | — |
saved[].id | integer | — |
saved[].source_id | integer | null | — |
saved[].title | string | — |
saved[].url | string | null | — |
saved[].preview | string | — |
saved[].saved_at | date-time | — |
limit | integer | Page size used. |
offset | integer | Results skipped. |
has_more | boolean | True when another page exists (call again with offset + limit). |
Errors
400Invalid parameters.401Missing, unknown or revoked key.403The key lacks therestscope, or the account does not include API access.429Rate limit exceeded (rate_limit_exceeded, the minute window) or monthly quota exceeded (quota_exceeded, resets on the 1st);Retry-Aftersays when.
Discover
Recent articles and keywords across every source.
GET
/discoverSearch all recent articles
Recent articles from every source EarlyWave reads (not only your feeds), by keywords or latest first.
MCP tool discover_items
Example
curl
curl "https://api.earlywave.ai/api/v1/discover?query=chips,export&hours_back=24" \
-H "Authorization: Bearer $EARLYWAVE_API_KEY"Parameters
| Name | In | Type | Default | Description |
|---|---|---|---|---|
query | In query | stringmax 500 chars | — | Comma-separated keywords; latest articles when omitted. |
language | In query | stringmax 10 chars | — | Article language code, e.g. "en". |
hours_back | In query | integer1–168 | Default 24 | Look-back window in hours (1–168, default 24). |
limit | In query | integer1–100 | Default 20 | Results per page (1–100, default 20). |
offset | In query | integer0–5000 | Default 0 | Results to skip, for paging (at most 5000). |
Response
200 application/json · DiscoverItemList
| Field | Type | Description |
|---|---|---|
query | string | null | — |
language | string | null | — |
hours_back | integer | — |
items | DiscoverItem[] | — |
items[].id | integer | — |
items[].title | string | — |
items[].url | string | null | — |
items[].preview | string | — |
items[].image_url | string | null | — |
items[].author | string | null | — |
items[].language | string | null | — |
items[].published | date-time | null | — |
items[].feed | object | null | — |
items[].match_source | string | null | Where the query matched (keywords, title, description); null without a query. |
total | integer | — |
limit | integer | Page size used. |
offset | integer | Results skipped. |
has_more | boolean | True when another page exists (call again with offset + limit). |
Errors
400Invalid parameters.401Missing, unknown or revoked key.403The key lacks therestscope, or the account does not include API access.429Rate limit exceeded (rate_limit_exceeded, the minute window) or monthly quota exceeded (quota_exceeded, resets on the 1st);Retry-Aftersays when.
GET
/discover/keywordsTop keywords
The most frequent keywords, entities, themes or places in recent articles.
MCP tool discover_top_keywords
Example
curl
curl "https://api.earlywave.ai/api/v1/discover/keywords?type=entities" \
-H "Authorization: Bearer $EARLYWAVE_API_KEY"Parameters
| Name | In | Type | Default | Description |
|---|---|---|---|---|
type | In query | "main_keywords" | "entities" | "themes" | "locations" | "all" | Default all | main_keywords, entities, themes, locations or all (default). |
hours_back | In query | integer1–168 | Default 24 | Look-back window in hours (1–168, default 24). |
limit | In query | integer1–100 | Default 20 | Results per page (1–100, default 20). |
Response
200 application/json · KeywordList
| Field | Type | Description |
|---|---|---|
hours_back | integer | — |
type | string | — |
keywords | object[] | — |
keywords[].keyword | string | — |
keywords[].count | integer | — |
keywords[].types | string[] | — |
total | integer | — |
Errors
400Invalid parameters.401Missing, unknown or revoked key.403The key lacks therestscope, or the account does not include API access.429Rate limit exceeded (rate_limit_exceeded, the minute window) or monthly quota exceeded (quota_exceeded, resets on the 1st);Retry-Aftersays when.