Getting Started

Beans News API & MCP

v0.8 Live

Beans is a news and blog aggregator. It collects data from 7 000+ sources/publishers every day.

MCP agent workflow

Recommended tool order for AI agents and MCP clients:

listCategories, listEntities, listRegions — discover exact filter values
searchArticles — primary full-corpus search
getLatestArticles, getTrendingArticles, getTopHeadlines — time-ordered feeds
getPublishers — resolve publisher source IDs to display metadata
getArticlePropagation / postArticlePropagation — track how stories spread

Conventions

Pagination defaults: limit=16 (max 128), offset=0. Empty results return HTTP 204 (not an error). Start with fuzzy tags; use exact categories / regions / entities after calling the tag-list tools. Combine q + acc for semantic vector search.

Key features

Vector semantic search — Natural language queries with configurable accuracy thresholds
Comprehensive filtering — By tags (categories, entities, regions), sources, and time ranges
Entity & sentiment enrichment — Automatic extraction of sentiment, named entities, and metadata optimized for analytics and AI pipelines
Trend scoring — Articles ranked by social engagement metrics for relevance and timeliness
Propagation timeline — Track publisher coverage and social mentions for article URLs across the feed

Authentication

Get API Key

Code
Authorization: Bearer YOUR-API-KEY

Base URL

All Beans endpoints live under the /beans path prefix.

Code
BASE_URL="https://api.cafecito.tech"
API_KEY="YOUR-API-KEY"

Core endpoints

Health

Endpoint	Description
`GET /beans/health`	Check API health (liveness probe)

Articles

Endpoint	Description
`GET /beans/articles/top-headlines`	Search or list top headlines from the last 24 hours
`GET /beans/articles/latest`	Search or list newest articles (reverse chronological)
`GET /beans/articles/trending`	Search or list trending articles by engagement score
`GET /beans/articles/search`	Search all articles by topic, tags, or URL (primary MCP tool)
`GET /beans/articles/propagation`	Track how articles spread (GET — CSV `urls` query)
`POST /beans/articles/propagation`	Track how articles spread (POST — JSON `{ "urls": [...] }`)

Publishers

Endpoint	Description
`GET /beans/sources`	Resolve publisher source metadata (site name, description, favicon)

Tags / Metadata

Endpoint	Description
`GET /beans/tags/categories`	List article category topics
`GET /beans/tags/entities`	List named entities
`GET /beans/tags/regions`	List geographic regions

Pagination

All metadata endpoints support offset (default 0) and limit (default 16, max 128).

Query Parameters

Articles

Search requires a filter

GET /beans/articles/search requires at least one of: q, tags, categories, regions, entities, or urls.

Parameter	Type	Description
`q`	string (3–512)	Optional semantic search query (natural language, triggers vector embedding)
`acc`	number (0–1)	Embedding similarity threshold — `0.0` = broad, `1.0` = strict (default `0.75`)
`content_type`	string	Content type filter: `news` or `blog`
`tags`	string[]	Case/whitespace-insensitive filter across categories, regions, entities combined (recommended). E.g., `AI`, `ai`, `#ai` are equivalent. AND combination.
`categories`	string[]	Precise category topic filters — inclusive OR, case/whitespace-sensitive (discover values via `listCategories`)
`regions`	string[]	Precise geographic region filters — inclusive OR, case/whitespace-sensitive (discover values via `listRegions`)
`entities`	string[]	Precise named entity filters — inclusive OR, case/whitespace-sensitive (discover values via `listEntities`)
`sources`	string[]	Publisher/source ID filters — inclusive OR
`urls`	string[]	Search only: Specific article URLs to fetch directly (CSV)
`from`	date (YYYY-MM-DD)	Latest / trending: published since date (defaults to 7 days ago when omitted). Search: published/updated since date. Top-headlines: not accepted (fixed 24h window).
`full_content`	boolean	Include full article text (default `false`) — large payload
`limit`	integer (1–128)	Results per page (default `16`)
`offset`	integer	Pagination offset — number of items to skip (default `0`)

Response: 200 OK → array of article objects. Shape depends on endpoint:

Endpoint	Type	Notable fields
`/articles/latest`	`Bean`	`content_type`, `published_at`, `tags` — no engagement metrics
`/articles/top-headlines`, `/articles/trending`	`BeanTrend`	Above plus `likes`, `comments`, `shares`, `related`, `trend_score`
`/articles/search`	`BeanAggregate`	Above plus publisher fields (`source_site_name`, etc.) and `likes`, `comments`, `shares`, `related` — no `trend_score`

related is always a count of related articles, not a list of URLs.

Propagation

Parameter	Type	Description
`urls`	string[]	Required. Valid article URLs to look up (max 128). GET: comma-separated CSV in one `urls` param; POST: JSON array in request body

Response: 200 OK → array of PropagationResult objects, each with url, coverage (publisher republications), and mentions (social/forum mentions).

Publishers

Parameter	Type	Description
`sources`	string[]	Required. Source IDs to fetch metadata for (CSV, e.g. `techcrunch.com,theverge.com`)
`limit`	integer (1–128)	Items per page (default `16`)
`offset`	integer	Pagination offset (default `0`)

Response: 200 OK → array of Publisher objects.

Tags / Metadata

Parameter	Type	Description
`limit`	integer (1–128)	Items per page (default `16`)
`offset`	integer	Pagination offset (default `0`)

Response: 200 OK → array of strings.

Status codes

200 — Matching data returned
204 — Empty result set (not an error)
400 — Invalid query parameters, missing search filter, or malformed UUID/URL
401 — Missing or invalid API key
429 — Rate limit or concurrency limit exceeded
500 — Database or embedder unavailable

Checkout API reference for more details.

MCP Server

Server URL: https://api.cafecito.tech/beans/mcp (v0.8)

Hosted MCP tools (same names as REST operationIds):

Tool	REST path
`listCategories`	`GET /beans/tags/categories`
`listEntities`	`GET /beans/tags/entities`
`listRegions`	`GET /beans/tags/regions`
`getTopHeadlines`	`GET /beans/articles/top-headlines`
`getLatestArticles`	`GET /beans/articles/latest`
`getTrendingArticles`	`GET /beans/articles/trending`
`searchArticles`	`GET /beans/articles/search`
`getPublishers`	`GET /beans/sources`
`getArticlePropagation`	`GET /beans/articles/propagation`
`postArticlePropagation`	`POST /beans/articles/propagation`

See the MCP Integration guide for client setup patterns.

Examples

Below are real-world examples. Replace YOUR-API-KEY with the key you generated in the developer portal.

1. Health check — verify service is operational

2. Top headlines from the last 24 hours

Get trending headlines ranked by trend score, perfect for building breaking news dashboards.

3. Latest news on market performance & economy

Use the trending endpoint to surface content ranked by social engagement signals and trend score.

5. Semantic search on archive — find articles about AI safety concerns

Search across all articles using natural language and retrieve full content for RAG/summarization.

6. Resolve publisher source metadata

Retrieve site names, descriptions, and favicon URLs for a set of publishers.

7. List article categories with pagination

Retrieve all unique categories/topics in the database.

See how a story spread across publishers and social platforms.

For batch lookups, use POST with a JSON body:

Code
curl -s -X POST "${BASE_URL}/beans/articles/propagation" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://example.com/story-a","https://example.com/story-b"]}'

Multi-URL GET (comma-separated):

Code
curl -s "${BASE_URL}/beans/articles/propagation?urls=https://example.com/story-a,https://example.com/story-b" \
  -H "Authorization: Bearer ${API_KEY}"

Best practices

Discover filters first — call listCategories, listEntities, or listRegions before exact categories / regions / entities filters.
Prefer feeds over search when a time-ordered window is enough — getLatestArticles, getTrendingArticles, and getTopHeadlines are lighter than full-corpus searchArticles.
Start with acc=0.75, then tweak up for precision or down for recall.
Use from parameter on latest/trending to keep feeds fresh — specify YYYY-MM-DD dates (e.g., from=2026-03-10). Do not use from on top-headlines (fixed 24h window).
Use full_content=true sparingly — requests will be slower and payload larger; great for RAG/summarization pipelines.
Paginate with offset + limit for stable ingestion pipelines and monitoring.
Use tags parameter (recommended) for flexible filtering across categories, regions, and entities in one parameter.
Use precise filters (categories, regions, entities) only when you need exact matches (case-sensitive).
Combine search (q) with filters — semantic search + tag filters = powerful precision.

Use cases that aren't boring

AI assistants and RAG workflows that need fresh context
Finance dashboards that actually stay current
Media trend detection — who's talking about what and when
Analyst workflows that want enrichment-ready JSON, not raw HTML

Last modified on June 29, 2026

API Keys Espresso

Getting Started

Beans News API & MCP

v0.8 Live

Beans is a news and blog aggregator. It collects data from 7 000+ sources/publishers every day.

MCP agent workflow

Recommended tool order for AI agents and MCP clients:

listCategories, listEntities, listRegions — discover exact filter values
searchArticles — primary full-corpus search
getLatestArticles, getTrendingArticles, getTopHeadlines — time-ordered feeds
getPublishers — resolve publisher source IDs to display metadata
getArticlePropagation / postArticlePropagation — track how stories spread

Conventions

Key features

Vector semantic search — Natural language queries with configurable accuracy thresholds
Comprehensive filtering — By tags (categories, entities, regions), sources, and time ranges
Entity & sentiment enrichment — Automatic extraction of sentiment, named entities, and metadata optimized for analytics and AI pipelines
Trend scoring — Articles ranked by social engagement metrics for relevance and timeliness
Propagation timeline — Track publisher coverage and social mentions for article URLs across the feed

Authentication

Get API Key

Code
Authorization: Bearer YOUR-API-KEY

Base URL

All Beans endpoints live under the /beans path prefix.

Code
BASE_URL="https://api.cafecito.tech"
API_KEY="YOUR-API-KEY"

Core endpoints

Health

Endpoint	Description
`GET /beans/health`	Check API health (liveness probe)

Articles

Endpoint	Description
`GET /beans/articles/top-headlines`	Search or list top headlines from the last 24 hours
`GET /beans/articles/latest`	Search or list newest articles (reverse chronological)
`GET /beans/articles/trending`	Search or list trending articles by engagement score
`GET /beans/articles/search`	Search all articles by topic, tags, or URL (primary MCP tool)
`GET /beans/articles/propagation`	Track how articles spread (GET — CSV `urls` query)
`POST /beans/articles/propagation`	Track how articles spread (POST — JSON `{ "urls": [...] }`)

Publishers

Endpoint	Description
`GET /beans/sources`	Resolve publisher source metadata (site name, description, favicon)

Tags / Metadata

Endpoint	Description
`GET /beans/tags/categories`	List article category topics
`GET /beans/tags/entities`	List named entities
`GET /beans/tags/regions`	List geographic regions

Pagination

All metadata endpoints support offset (default 0) and limit (default 16, max 128).

Query Parameters

Articles

Search requires a filter

GET /beans/articles/search requires at least one of: q, tags, categories, regions, entities, or urls.

Parameter	Type	Description
`q`	string (3–512)	Optional semantic search query (natural language, triggers vector embedding)
`acc`	number (0–1)	Embedding similarity threshold — `0.0` = broad, `1.0` = strict (default `0.75`)
`content_type`	string	Content type filter: `news` or `blog`
`tags`	string[]	Case/whitespace-insensitive filter across categories, regions, entities combined (recommended). E.g., `AI`, `ai`, `#ai` are equivalent. AND combination.
`categories`	string[]	Precise category topic filters — inclusive OR, case/whitespace-sensitive (discover values via `listCategories`)
`regions`	string[]	Precise geographic region filters — inclusive OR, case/whitespace-sensitive (discover values via `listRegions`)
`entities`	string[]	Precise named entity filters — inclusive OR, case/whitespace-sensitive (discover values via `listEntities`)
`sources`	string[]	Publisher/source ID filters — inclusive OR
`urls`	string[]	Search only: Specific article URLs to fetch directly (CSV)
`from`	date (YYYY-MM-DD)	Latest / trending: published since date (defaults to 7 days ago when omitted). Search: published/updated since date. Top-headlines: not accepted (fixed 24h window).
`full_content`	boolean	Include full article text (default `false`) — large payload
`limit`	integer (1–128)	Results per page (default `16`)
`offset`	integer	Pagination offset — number of items to skip (default `0`)

Response: 200 OK → array of article objects. Shape depends on endpoint:

Endpoint	Type	Notable fields
`/articles/latest`	`Bean`	`content_type`, `published_at`, `tags` — no engagement metrics
`/articles/top-headlines`, `/articles/trending`	`BeanTrend`	Above plus `likes`, `comments`, `shares`, `related`, `trend_score`
`/articles/search`	`BeanAggregate`	Above plus publisher fields (`source_site_name`, etc.) and `likes`, `comments`, `shares`, `related` — no `trend_score`

related is always a count of related articles, not a list of URLs.

Propagation

Parameter	Type	Description
`urls`	string[]	Required. Valid article URLs to look up (max 128). GET: comma-separated CSV in one `urls` param; POST: JSON array in request body

Response: 200 OK → array of PropagationResult objects, each with url, coverage (publisher republications), and mentions (social/forum mentions).

Publishers

Parameter	Type	Description
`sources`	string[]	Required. Source IDs to fetch metadata for (CSV, e.g. `techcrunch.com,theverge.com`)
`limit`	integer (1–128)	Items per page (default `16`)
`offset`	integer	Pagination offset (default `0`)

Response: 200 OK → array of Publisher objects.

Tags / Metadata

Parameter	Type	Description
`limit`	integer (1–128)	Items per page (default `16`)
`offset`	integer	Pagination offset (default `0`)

Response: 200 OK → array of strings.

Status codes

200 — Matching data returned
204 — Empty result set (not an error)
400 — Invalid query parameters, missing search filter, or malformed UUID/URL
401 — Missing or invalid API key
429 — Rate limit or concurrency limit exceeded
500 — Database or embedder unavailable

Checkout API reference for more details.

MCP Server

Server URL: https://api.cafecito.tech/beans/mcp (v0.8)

Hosted MCP tools (same names as REST operationIds):

Tool	REST path
`listCategories`	`GET /beans/tags/categories`
`listEntities`	`GET /beans/tags/entities`
`listRegions`	`GET /beans/tags/regions`
`getTopHeadlines`	`GET /beans/articles/top-headlines`
`getLatestArticles`	`GET /beans/articles/latest`
`getTrendingArticles`	`GET /beans/articles/trending`
`searchArticles`	`GET /beans/articles/search`
`getPublishers`	`GET /beans/sources`
`getArticlePropagation`	`GET /beans/articles/propagation`
`postArticlePropagation`	`POST /beans/articles/propagation`

See the MCP Integration guide for client setup patterns.

Examples

Below are real-world examples. Replace YOUR-API-KEY with the key you generated in the developer portal.

const API_KEY = process.env.CAFECITO_API_KEY;
const BASE_URL = "https://api.cafecito.tech";

1. Health check — verify service is operational

const res = await fetch(`${BASE_URL}/beans/health`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});

if (!res.ok) throw new Error(`HTTP ${res.status}`);
const status = await res.json();
console.log("Service status:", status);

2. Top headlines from the last 24 hours

Get trending headlines ranked by trend score, perfect for building breaking news dashboards.

const params = new URLSearchParams({
  limit: "10",
});

const res = await fetch(`${BASE_URL}/beans/articles/top-headlines?${params}`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});

if (!res.ok) throw new Error(`HTTP ${res.status}`);
const headlines = await res.json();
headlines?.forEach((h) => console.log(h.title, "→", h.url));

3. Latest news on market performance & economy

const params = new URLSearchParams({
  q: "market performance and economy",
  content_type: "news",
  limit: "10",
});

const res = await fetch(`${BASE_URL}/beans/articles/latest?${params}`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});

if (!res.ok) throw new Error(`HTTP ${res.status}`);
const articles = await res.json();
articles?.forEach((a) => console.log(a.title, "→", a.url));

Use the trending endpoint to surface content ranked by social engagement signals and trend score.

const params = new URLSearchParams();
params.append("tags", "Robotics");
params.append("tags", "saudi arabia");
params.append("content_type", "news");
params.append("limit", "10");

const res = await fetch(`${BASE_URL}/beans/articles/trending?${params}`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});
const articles = await res.json();
articles?.forEach((a) => console.log(a.title, "|", a.regions));

5. Semantic search on archive — find articles about AI safety concerns

Search across all articles using natural language and retrieve full content for RAG/summarization.

const params = new URLSearchParams({
  q: "AI safety risks and concerns",
  acc: "0.8",
  full_content: "true",
  limit: "5",
});

const res = await fetch(`${BASE_URL}/beans/articles/search?${params}`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});

if (!res.ok) throw new Error(`HTTP ${res.status}`);
const results = await res.json();
results?.forEach((a) => {
  console.log(`${a.title} [related: ${a.related}]`);
  console.log(`  → ${a.source} (${a.likes} likes, ${a.shares} shares)`);
  console.log(`  URL: ${a.url}\n`);
});

6. Resolve publisher source metadata

Retrieve site names, descriptions, and favicon URLs for a set of publishers.

const params = new URLSearchParams();
params.append("sources", "barchart");
params.append("sources", "reuters");
params.append("sources", "techcrunch");

const res = await fetch(`${BASE_URL}/beans/sources?${params}`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});

if (!res.ok) throw new Error(`HTTP ${res.status}`);
const publishers = await res.json();
publishers?.forEach((p) => {
  console.log(`${p.source_site_name}`);
  console.log(`  ID: ${p.source}`);
  console.log(`  URL: ${p.source_base_url}`);
  console.log(`  Description: ${p.source_description}\n`);
});

7. List article categories with pagination

Retrieve all unique categories/topics in the database.

const params = new URLSearchParams({
  limit: "50",
  offset: "0",
});

const res = await fetch(`${BASE_URL}/beans/tags/categories?${params}`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});

if (!res.ok) throw new Error(`HTTP ${res.status}`);
const categories = await res.json();
console.log("Article categories:");
categories?.forEach((cat) => console.log(`  - ${cat}`));

See how a story spread across publishers and social platforms.

const params = new URLSearchParams();
params.append("urls", "https://example.com/breaking-story");

const res = await fetch(`${BASE_URL}/beans/articles/propagation?${params}`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});

if (!res.ok) throw new Error(`HTTP ${res.status}`);
const results = await res.json();
results?.forEach((r) => {
  console.log(r.url, "→", r.coverage?.length, "coverage,", r.mentions?.length, "mentions");
});

For batch lookups, use POST with a JSON body:

Code
curl -s -X POST "${BASE_URL}/beans/articles/propagation" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://example.com/story-a","https://example.com/story-b"]}'

Multi-URL GET (comma-separated):

Code
curl -s "${BASE_URL}/beans/articles/propagation?urls=https://example.com/story-a,https://example.com/story-b" \
  -H "Authorization: Bearer ${API_KEY}"

Best practices

Discover filters first — call listCategories, listEntities, or listRegions before exact categories / regions / entities filters.
Prefer feeds over search when a time-ordered window is enough — getLatestArticles, getTrendingArticles, and getTopHeadlines are lighter than full-corpus searchArticles.
Start with acc=0.75, then tweak up for precision or down for recall.
Use from parameter on latest/trending to keep feeds fresh — specify YYYY-MM-DD dates (e.g., from=2026-03-10). Do not use from on top-headlines (fixed 24h window).
Use full_content=true sparingly — requests will be slower and payload larger; great for RAG/summarization pipelines.
Paginate with offset + limit for stable ingestion pipelines and monitoring.
Use tags parameter (recommended) for flexible filtering across categories, regions, and entities in one parameter.
Use precise filters (categories, regions, entities) only when you need exact matches (case-sensitive).
Combine search (q) with filters — semantic search + tag filters = powerful precision.

Use cases that aren't boring

AI assistants and RAG workflows that need fresh context
Finance dashboards that actually stay current
Media trend detection — who's talking about what and when
Analyst workflows that want enrichment-ready JSON, not raw HTML

Last modified on June 29, 2026

API Keys Espresso

Beans News API & MCP

MCP agent workflow

Key features

Authentication

Base URL

Core endpoints

Health

Articles

Publishers

Tags / Metadata

Query Parameters

Articles

Propagation

Publishers

Tags / Metadata

Status codes

MCP Server

Examples

1. Health check — verify service is operational

2. Top headlines from the last 24 hours

3. Latest news on market performance & economy

4. Trending news on Robotics in Saudi Arabia

5. Semantic search on archive — find articles about AI safety concerns

6. Resolve publisher source metadata

7. List article categories with pagination

8. Article propagation — track coverage and social mentions

Best practices

Use cases that aren't boring

Related

Beans News API & MCP

MCP agent workflow

Key features

Authentication

Base URL

Core endpoints

Health

Articles

Publishers

Tags / Metadata

Query Parameters

Articles

Propagation

Publishers

Tags / Metadata

Status codes

MCP Server

Examples

1. Health check — verify service is operational

2. Top headlines from the last 24 hours

3. Latest news on market performance & economy

4. Trending news on Robotics in Saudi Arabia

5. Semantic search on archive — find articles about AI safety concerns

6. Resolve publisher source metadata

7. List article categories with pagination

8. Article propagation — track coverage and social mentions

Best practices

Use cases that aren't boring

Related