Getting Started

Beans API & MCP

v0.1 Live

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

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
Cross-publisher linking — Related articles mapped across the entire feed

Authentication

Code
Authorization: Bearer YOUR-API-KEY

Base URL

All Beans endpoints live under the /beans path prefix.

Core endpoints

Articles

Endpoint	Description
`GET /beans/articles/top-headlines`	Top trending headlines from past 24 hours, ranked by trend score
`GET /beans/articles/latest`	Most recently published articles, sorted by publish date (newest first)
`GET /beans/articles/trending`	Trending articles ranked by trend score (based on social engagement)
`GET /beans/articles/search`	Semantic or tag-based search across all articles in the database

Sources

Endpoint	Description
`GET /beans/sources`	Retrieves detailed metadata for sources (site name, description, favicon)

Tags / Metadata

Endpoint	Description
`GET /beans/tags/categories`	Paginated list of unique article categories/topics
`GET /beans/tags/entities`	Paginated list of named entities (persons, orgs, products, places)
`GET /beans/tags/regions`	Paginated list of geographic regions mentioned in articles

Pagination

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

Query Parameters

Articles

Parameter	Type	Description
`q`	string (3–512)	Optional semantic search query (natural language, triggers vector embedding)
`acc`	number (0–1)	Embedding accuracy/similarity threshold — higher = stricter match (default `0.75`)
`content_type`	string	Content type filter: `news`, `blog`, `post`, `comment`, etc.
`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
`regions`	string[]	Precise geographic region filters — inclusive OR, case/whitespace-sensitive
`entities`	string[]	Precise named entity filters — inclusive OR, case/whitespace-sensitive
`sources`	string[]	Publisher/source ID filters — inclusive OR
`from`	date (YYYY-MM-DD)	Latest/Trending only: Articles published/trending since this date (defaults to 7 days ago)
`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.

Sources

Parameter	Type	Description
`sources`	string[]	Required. Source IDs to fetch metadata for (CSV, case-sensitive)
`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.

Checkout API reference for more details.

MCP Server

Server URL: https://api.cafecito.tech/beans/mcp

Beans endpoints are exposed as hosted MCP tools for AI agent integration. See the MCP Integration guide for more details.

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. Get sources 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.

Best practices

Start with acc=0.75, then tweak up for precision or down for recall.
Use from parameter to keep feeds fresh — specify YYYY-MM-DD dates (e.g., from=2026-03-10).
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 March 16, 2026

API Keys Espresso

Getting Started

Beans API & MCP

v0.1 Live

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

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
Cross-publisher linking — Related articles mapped across the entire feed

Authentication

Get API Key

Code
Authorization: Bearer YOUR-API-KEY

Base URL

All Beans endpoints live under the /beans path prefix.

Core endpoints

Articles

Endpoint	Description
`GET /beans/articles/top-headlines`	Top trending headlines from past 24 hours, ranked by trend score
`GET /beans/articles/latest`	Most recently published articles, sorted by publish date (newest first)
`GET /beans/articles/trending`	Trending articles ranked by trend score (based on social engagement)
`GET /beans/articles/search`	Semantic or tag-based search across all articles in the database

Sources

Endpoint	Description
`GET /beans/sources`	Retrieves detailed metadata for sources (site name, description, favicon)

Tags / Metadata

Endpoint	Description
`GET /beans/tags/categories`	Paginated list of unique article categories/topics
`GET /beans/tags/entities`	Paginated list of named entities (persons, orgs, products, places)
`GET /beans/tags/regions`	Paginated list of geographic regions mentioned in articles

Pagination

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

Query Parameters

Articles

Parameter	Type	Description
`q`	string (3–512)	Optional semantic search query (natural language, triggers vector embedding)
`acc`	number (0–1)	Embedding accuracy/similarity threshold — higher = stricter match (default `0.75`)
`content_type`	string	Content type filter: `news`, `blog`, `post`, `comment`, etc.
`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
`regions`	string[]	Precise geographic region filters — inclusive OR, case/whitespace-sensitive
`entities`	string[]	Precise named entity filters — inclusive OR, case/whitespace-sensitive
`sources`	string[]	Publisher/source ID filters — inclusive OR
`from`	date (YYYY-MM-DD)	Latest/Trending only: Articles published/trending since this date (defaults to 7 days ago)
`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.

Sources

Parameter	Type	Description
`sources`	string[]	Required. Source IDs to fetch metadata for (CSV, case-sensitive)
`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.

Checkout API reference for more details.

MCP Server

Server URL: https://api.cafecito.tech/beans/mcp

Beans endpoints are exposed as hosted MCP tools for AI agent integration. See the MCP Integration guide for more details.

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/beans"; // or read from env

1. Health check — verify service is operational

const res = await fetch(`${BASE_URL.replace('/beans', '')}/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}/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}/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}/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}/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} [trend_score: ${a.trend_score}]`);
  console.log(`  → ${a.source} (${a.likes} likes, ${a.shares} shares)`);
  console.log(`  URL: ${a.url}\n`);
});

6. Get sources 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}/publishers?${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}/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}`));

Best practices

Start with acc=0.75, then tweak up for precision or down for recall.
Use from parameter to keep feeds fresh — specify YYYY-MM-DD dates (e.g., from=2026-03-10).
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 March 16, 2026

API Keys Espresso

Beans API & MCP

Key features

Authentication

Base URL

Core endpoints

Articles

Sources

Tags / Metadata

Pagination

Query Parameters

Articles

Sources

Tags / Metadata

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. Get sources metadata

7. List article categories with pagination

Best practices

Use cases that aren't boring

Related

Beans API & MCP

Key features

Authentication

Base URL

Core endpoints

Articles

Sources

Tags / Metadata

Pagination

Query Parameters

Articles

Sources

Tags / Metadata

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. Get sources metadata

7. List article categories with pagination

Best practices

Use cases that aren't boring

Related