Beans

Beans News API

v1 Live

Beans is a publisher-content API for news, blogs, financial and earnings reports, litigation and lawsuits, official statements, research, technical documents, and related coverage context.

Articles are publisher items (news, blogs, reports, statements, research, and other stored types).
Sources are publisher records available on an Article or through the Source routes.
Stories are clusters of articles to track the same news/content across different publishers.
Mentions are engagement on an article in different social media platforms such as shared links, likes, comments etc.

Question	Use
What did publishers report?	Beans
Which sources covered the same story?	Beans Stories and Sources
What external discussion exists around an Article?	Beans Mentions
What happened in structured intelligence terms?	Espresso Events
What does it mean or what is the outlook?	Espresso Signals
What evidence supports the conclusion?	Espresso Evidence

Key features

Article-first retrieval: search publisher material by relevance query, exact Article UUID or URL, type, Source, byline, date, and normalized labels.
Purposeful feeds: use latest for chronology, top-headlines for recent attention-ranked news, and trending for attention-ranked coverage.
Controlled exploration: choose Article, Source, and Story UUIDs from collection data, then request detail or a subresource only when it answers the next question.
Coverage context: inspect related publisher reading, Story membership, and external mentions without treating those concepts as interchangeable.
Content on demand: keep collections compact and request full_content=true (Applies to a subset of articles. Full content is not available for all articles).
Agent-friendly transport: JSON is canonical. Cursor pagination, stable UUIDs, explicit envelopes, and small follow-up calls make the API suitable for tool and agent workflows.

Choose a route by the user question

Initial Question	Start here	Follow only when needed	Provider parallel
Publisher material about a topic, person, place, or organization	`GET /beans/articles/search`	Article detail, related Articles, mentions, Source detail, or Story detail	World News search-news, GNews search, NewsAPI.ai getArticles, NewsAPI.org everything
The most recently published material	`GET /beans/articles/latest`	Continue with the returned cursor or inspect a selected Article	NewsData.io latest, Currents latest-news
The most attention-ranked coverage	`GET /beans/articles/trending`	Inspect available `trend` observations	World News top-news, TheNewsAPI top-news
A current attention-ranked news set	`GET /beans/news/top-headlines`	Article detail or related coverage for selected results	GNews and NewsAPI.org top-headlines
One known Article UUID	`GET /beans/articles/{id}`	Request content, related Articles, mentions, or the linked Story	TheNewsAPI UUID lookup, World News retrieve-news
Related publisher reading for one Article	`GET /beans/articles/{id}/similar`	Inspect a selected related Article	TheNewsAPI similar-by-UUID
External discussion of one Article	`GET /beans/articles/{id}/mentions`	Use the observation data directly	Beans extension
A related-coverage group	`GET /beans/stories`	Story detail, then its member Articles	Beans Story collection
A publisher or domain	`GET /beans/sources`	Source detail or Article search with the selected Source UUID	NewsAPI.org sources, provider source catalogs
An accepted filter value is unknown	`GET /beans/categories`, `/entities`, `/regions`, or `/sentiments`	Reuse the returned `value` in an Article or Story filter	Provider-specific catalogs

A good workflow uses the smallest useful filter set, preserves returned IDs exactly, and stops after enough publisher support has been selected. Do not retrieve detail for every collection item.

Authentication and base URL

Get API Key

All public Beans REST routes except health, and the Beans MCP endpoint, require the same Bearer API key used by other Cafecito products. Paths use the /beans prefix.

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

curl -s "${BASE_URL}/beans/health"

curl -s --get "${BASE_URL}/beans/articles/search" \
  -H "Authorization: Bearer ${API_KEY}" \
  --data-urlencode "limit=5"

Code
Authorization: Bearer YOUR-API-KEY

Unknown or route-inapplicable query parameters return HTTP 400. Clients that previously sent extra keys and expected them to be ignored must stop sending those keys.

The Beans API reference is the source for the complete gateway schemas, parameter validation, and HTTP status codes.

Quickstart in JavaScript, Python, and cURL

The following requests make the same Article search. The query asks for publisher material rather than an Espresso Event or Signal. score_threshold is optional with q; sending score_threshold without q returns HTTP 400.

The three requests return the same JSON envelope. Use GET /beans/articles/latest for chronology, GET /beans/news/top-headlines for recent attention-ranked news, and GET /beans/articles/trending for attention-ranked coverage rather than relevance search.

Collections, IDs, and pagination

Every REST collection returns pagination, meta, and data. This is a captured one-Article response from GET /beans/articles/latest?limit=1; values are an example, not a fixed dataset.


Code
{
  "pagination": {
    "limit": 1,
    "num_results": 1,
    "next_cursor": "eyJ2IjoxLCJzIjoiY3JlYXRlZCIsImlkIjoiM2E0NzllM2MtYTg3ZC01OTFlLWJiNmMtNWM4M2MwM2I2YTQwIiwiYyI6IjIwMjYtMDgtMjRUMDI6MDA6NDNaIn0"
  },
  "meta": {
    "as_of": "2026-08-24T20:42:39.633280927Z"
  },
  "data": [
    {
      "id": "3a479e3c-a87d-591e-bb6c-5c83c03b6a40",
      "url": "https://www.middleeastainews.com/p/uae-ai-programme-adds-agentic-ai",
      "content_type": "news",
      "published_at": "2026-08-24T02:00:43Z",
      "author": "Carrington Malin",
      "image_url": null,
      "title": "UAE AI Programme adds Agentic AI focus",
      "summary": "Listen now | Middle East AI News Minute - 24-Aug-26",
      "categories": [
        "artificial_intelligence_and_machine_learning",
        "generative_ai_and_foundation_models"
      ],
      "regions": null,
      "entities": ["carrington_malin"],
      "sentiments": ["disturbed", "anxious"],
      "tags": [
        "artificial_intelligence_and_machine_learning",
        "generative_ai_and_foundation_models",
        "carrington_malin"
      ],
      "story_id": "06860aaa-a43c-585f-9cb3-a6710a93a74a",
      "source": null
    }
  ]
}

Preserve Article, Source, and Story UUIDs exactly. They are opaque identifiers for detail and subresource calls.
pagination.limit is the requested page size. It accepts 1 through 100 and defaults to 20.
pagination.num_results is the number of records in this page. It is not a total count of possible matches.
When pagination.next_cursor is non-null, send the exact token as cursor on the same route with the same filters. Do not decode, modify, sort, or synthesize cursor values.
An empty collection is a successful HTTP 200 response with data: [] and next_cursor: null.
Detail routes return { "data": { ... } }. Missing Article, Source, and Story IDs return HTTP 404.
Do not use offset-style pagination such as offset, page, pageSize, or size; Beans uses cursors.

Detail and error envelopes

Article detail returns the same Article fields plus follow-up links. This captured response shows the link and attention-observation shapes. content is omitted here because it was not requested.


Code
{
  "data": {
    "id": "3a479e3c-a87d-591e-bb6c-5c83c03b6a40",
    "url": "https://www.middleeastainews.com/p/uae-ai-programme-adds-agentic-ai",
    "content_type": "news",
    "published_at": "2026-08-24T02:00:43Z",
    "author": "Carrington Malin",
    "image_url": null,
    "title": "UAE AI Programme adds Agentic AI focus",
    "summary": "Listen now | Middle East AI News Minute - 24-Aug-26",
    "categories": [
      "artificial_intelligence_and_machine_learning",
      "generative_ai_and_foundation_models"
    ],
    "regions": null,
    "entities": ["carrington_malin"],
    "sentiments": ["disturbed", "anxious"],
    "tags": [
      "artificial_intelligence_and_machine_learning",
      "generative_ai_and_foundation_models",
      "carrington_malin"
    ],
    "story_id": "06860aaa-a43c-585f-9cb3-a6710a93a74a",
    "source": null,
    "trend": {
      "likes": 0,
      "comments": 0,
      "mentions": 0,
      "audiences": 0,
      "related": 53,
      "trend_score": 2650
    },
    "links": {
      "similar": "/articles/3a479e3c-a87d-591e-bb6c-5c83c03b6a40/similar",
      "mentions": "/articles/3a479e3c-a87d-591e-bb6c-5c83c03b6a40/mentions",
      "story": "/stories/06860aaa-a43c-585f-9cb3-a6710a93a74a"
    }
  }
}

Errors use an HTTP status and one error envelope:


Code
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable explanation"
  }
}

Expect HTTP 400 for invalid input, 401 for a missing or invalid public key (gateway), 404 for a selected record that does not exist, 429 when request limits are reached, and 500 when the service is unavailable. Application errors from the product API use { "error": { "code", "message" } }. A successful response does not include a duplicate status field.

Response types and nullable fields

The route matrix below names the response type for every public path. The following tables explain the payload fields a client will parse most often.

Article

Field	Type	Contract
`id`	UUID string	Stable Article identifier for detail, similar, and mention calls.
`url`	string	Publisher Article URL.
`content_type`	string enum	One stored Beans content type.
`published_at`	RFC 3339 timestamp	Publisher publication time.
`title`, `summary`, `author`, `image_url`	string or `null`	Available publisher metadata.
`content`	optional string	Included only when `full_content=true` is requested and Beans has body content. This is not a universal full-text guarantee. Handle a missing value and use `url` for attribution.
`categories`, `regions`, `entities`, `sentiments`, `tags`	string array or `null`	Available normalized labels. Use discovery routes when an accepted filter value is unknown.
`story_id`	optional UUID string	Stable Story identifier when the Article belongs to a Story.
`source`	Source object or `null`	Available publisher metadata for this Article.
`trend`	optional Trend object	Available observed attention values on attention-ranked or enriched responses. It is not a forecast and is not guaranteed on every Article.
`links`	detail only	Service-relative `similar`, `mentions`, and, when available, `story` paths. Prefix a returned path with `/beans` at the public gateway.

Source, discovery label, and Mention

Response item	Fields	Contract
Source	`id`, `url`, `domain`, `name`, optional `description`, `favicon_url`, `rss_feed_url`	Publisher metadata. Preserve `id` and use it with the `sources` Article or Story filter.
Discovery label	`value`, optional `type`	A normalized filter value from categories, entities, regions, or sentiments.
Mention	`url`, `platform`, `forum`, `observed_at`, `engagement`	An external observation for a selected Article, not another publisher Article.
Mention engagement	`likes`, `comments`, `audience`	Nullable observed engagement values. Treat absent or null values as unavailable, not zero.

GET /beans/articles/{id}/mentions returns the normal collection envelope with Mention items. It accepts only the mention-specific filters in the route matrix, not Article text or taxonomy filters.

Story

Field	Type	Contract
`id`	UUID string	Stable Story identifier for `GET /beans/stories/{id}` and `GET /beans/stories/{id}/articles`.
`title`	string	Story title.
`first_published_at`, `last_published_at`	RFC 3339 timestamps	Publication bounds of the Story's available Articles.
`article_count`, `source_count`	integer	Counts of available Story Articles and Sources.
`categories`, `regions`, `entities`, `tags`	string arrays	Normalized Story labels.
`top_articles`	Article-preview array	Compact Article previews with `id`, `url`, `title`, `published_at`, and available `source`. It is not the full member set.
`links.articles`	Story detail only	Service-relative path for the Story's member-Article collection. Prefix it with `/beans` at the public gateway.

Public route contract and request parameters

All request parameters are query parameters unless the table marks id as a path parameter. CSV parameters accept comma-separated values. The table is intentionally route-specific: do not assume that a parameter available on Article search is accepted by every feed or follow-up route.

Health, discovery, Sources, and MCP

Route	Response type	Accepted request parameters
`GET /beans/health`	Health object	None. No Bearer header.
`GET /beans/categories`	Label collection envelope	`q`, `limit`, `cursor`
`GET /beans/entities`	Label collection envelope	`q`, `limit`, `cursor`
`GET /beans/regions`	Label collection envelope	`q`, `limit`, `cursor`
`GET /beans/sentiments`	Label collection envelope	`q`, `limit`, `cursor`
`GET /beans/sources`	Source collection envelope	`q`, `ids`, `domains`, `limit`, `cursor`
`GET /beans/sources/{id}`	Source detail envelope	`id` path parameter
`POST /beans/mcp`	MCP tool transport	No REST filter parameters; Bearer required.

Article routes

Route	Response type	Accepted request parameters
`GET /beans/articles/search`	Article collection envelope	`q`, `score_threshold`, `ids`, `urls`, `content_type`, `sources`, `exclude_sources`, `domains`, `exclude_domains`, `authors`, `categories`, `exclude_categories`, `regions`, `entities`, `sentiments`, `tags`, `from`, `to`, `full_content`, `limit`, `cursor`
`GET /beans/articles/latest`	Article collection envelope	`q`, `score_threshold`, `content_type`, `sources`, `exclude_sources`, `domains`, `exclude_domains`, `authors`, `categories`, `exclude_categories`, `regions`, `entities`, `sentiments`, `tags`, `full_content`, `limit`, `cursor`
`GET /beans/news/top-headlines`	Article collection envelope	`q`, `score_threshold`, `sources`, `exclude_sources`, `domains`, `exclude_domains`, `authors`, `categories`, `exclude_categories`, `regions`, `entities`, `sentiments`, `tags`, `full_content`, `limit`, `cursor`
`GET /beans/articles/trending`	Article collection envelope	`q`, `score_threshold`, `content_type`, `sources`, `exclude_sources`, `domains`, `exclude_domains`, `authors`, `categories`, `exclude_categories`, `regions`, `entities`, `sentiments`, `tags`, `full_content`, `limit`, `cursor`
`GET /beans/articles/{id}`	Article detail envelope	`id` path parameter, `full_content`
`GET /beans/articles/{id}/similar`	Article collection envelope	`id` path parameter, `content_type`, `sources`, `exclude_sources`, `domains`, `exclude_domains`, `authors`, `categories`, `exclude_categories`, `regions`, `entities`, `sentiments`, `tags`, `from`, `to`, `full_content`, `limit`, `cursor`
`GET /beans/articles/{id}/mentions`	Mention collection envelope	`id` path parameter, `platforms`, `forums`, `from`, `to`, `limit`, `cursor`

Story routes

Route	Response type	Accepted request parameters
`GET /beans/stories`	Story collection envelope	`q`, `score_threshold`, `content_type`, `sources`, `exclude_sources`, `domains`, `exclude_domains`, `authors`, `categories`, `exclude_categories`, `regions`, `entities`, `sentiments`, `tags`, `min_article_count`, `from`, `to`, `limit`, `cursor`
`GET /beans/stories/{id}`	Story detail envelope	`id` path parameter
`GET /beans/stories/{id}/articles`	Story Article collection envelope	`id` path parameter, `content_type`, `sources`, `exclude_sources`, `domains`, `exclude_domains`, `authors`, `categories`, `exclude_categories`, `regions`, `entities`, `sentiments`, `tags`, `from`, `to`, `full_content`, `limit`, `cursor`

Query and filter rules

Shared request rules

Rule	Contract
Authentication	Send `Authorization: Bearer YOUR-API-KEY`.
Page size	`limit` is `1` through `100`; the default is `20`.
Continuation	Send `pagination.next_cursor` unchanged as `cursor` on the same route and filter set.
Date inputs	`from` and `to` use inclusive UTC calendar dates in `YYYY-MM-DD` form.
Text query	`q` is a route-specific natural-language relevance query and accepts up to 512 characters.
Relevance threshold	`score_threshold` is in the `0.0` through `1.0` range. Use it only with `q`. A threshold without `q` returns HTTP `400`. `q` may omit the threshold.
Content projection	`full_content=true` requests available Article content when Beans has it. It does not change which records match and does not guarantee a full publisher copy.
Filter combination	Different filter fields combine with AND. Include values within one category, region, entity, sentiment, Source, or domain field match any listed value. Exclusion filters remove matching records. All supplied `tags` and author terms further narrow results.
Response format	JSON is canonical for REST responses and MCP tool results.

Article and Story filters

Parameter	Matching behavior	Available on
`q`	Natural-language relevance query.	Article search and feeds; Story discovery.
`score_threshold`	Relevance threshold used with `q`. Higher values are stricter.	Article search and feeds; Story discovery.
`ids`, `urls`	Exact Article UUIDs or canonical URLs.	Article search only.
`content_type`	One filterable Article type. `post` is not accepted as a request filter.	Article search, latest, trending, similar, Stories, Story Articles. Not accepted on top-headlines.
`sources`, `exclude_sources`	Include or exclude exact Source UUIDs.	Article and Story collection routes listed in the matrix.
`domains`, `exclude_domains`	Include or exclude exact Source domains.	Article and Story collection routes listed in the matrix.
`authors`	Case-insensitive byline text matching.	Article and Story collection routes listed in the matrix.
`categories`, `exclude_categories`	Normalized category labels.	Article and Story collection routes listed in the matrix.
`regions`, `entities`, `sentiments`	Normalized extracted labels.	Article and Story collection routes listed in the matrix.
`tags`	All supplied normalized category, region, or entity terms must match. It is not a title or body phrase search.	Article and Story collection routes listed in the matrix.
`from`, `to`	Inclusive UTC publication-date bounds.	Article search, similar Articles, Stories, and Story Articles. Mention dates bound `observed_at` instead.
`full_content`	Requests available Article content.	Article search and feeds, Article detail, similar Articles, and Story Articles.
`min_article_count`	Minimum number of Articles in a Story. Default `2`, minimum `2`.	Story discovery only.
`platforms`, `forums`	External observation platform or forum filters.	Article mentions only.

GET /beans/news/top-headlines is a recent attention-ranked news route. It does not accept content_type, ids, urls, from, or to. The current public feed routes also do not accept custom date bounds; use Article search, similar Articles, Stories, or Story Articles when the workflow needs from and to.

Public content types

Request content_type accepts these 14 filterable values:

blog, contract, earnings_report, enforcement_action, financial_report, lawsuit, news, official_statement, podcast, press_release, research_paper, site, technical_documentation, and whitepaper.

post may appear on Article responses. Sending content_type=post returns HTTP 400. Omit content_type to include every stored type, including response-only post. Do not translate provider labels such as pr into Beans aliases.

User need	Beans content types	Starting route
General news and blogs	`news`, `blog`	`GET /beans/articles/search`
Company financial updates	`earnings_report`, `financial_report`	Article search with `content_type`
Legal and regulatory monitoring	`lawsuit`, `enforcement_action`, `contract`	Article search with type and entity filters
Corporate communications	`official_statement`, `press_release`	Article search with type, Source, and date
Research and technical monitoring	`research_paper`, `technical_documentation`, `whitepaper`	Article search with type and topic filters
Audio and publication discovery	`podcast`, `site`	Article search with type and Source filters

Code
# Earnings monitoring (searchArticles). lawsuit monitoring uses the same route with content_type=lawsuit.
curl -s --get "${BASE_URL}/beans/articles/search" \
  -H "Authorization: Bearer ${API_KEY}" \
  --data-urlencode "content_type=earnings_report" \
  --data-urlencode "from=2026-08-01" \
  --data-urlencode "limit=20"

curl -s --get "${BASE_URL}/beans/articles/search" \
  -H "Authorization: Bearer ${API_KEY}" \
  --data-urlencode "content_type=lawsuit" \
  --data-urlencode "entities=openai" \
  --data-urlencode "limit=20"

Discovery and Sources

Discovery routes return accepted filter values rather than requiring a client to guess a taxonomy value:

Route	Returns	Use it for
`GET /beans/categories`	Category labels.	`categories` or `exclude_categories`.
`GET /beans/entities`	Entity labels.	`entities` or `tags`.
`GET /beans/regions`	Region labels.	`regions` or `tags`.
`GET /beans/sentiments`	Sentiment labels.	`sentiments`.

Each discovery route accepts q, limit, and cursor. Use it only when the normalized value is unknown; send a known value directly to the Article or Story route.

Sources are publisher records, not Article results. Resolve a publisher with GET /beans/sources?q=... or domains=..., preserve its UUID, then use that value with sources on Article or Story retrieval.

Code
# Resolve a publisher, then use its returned data[].id as a Source filter.
curl -s --get "${BASE_URL}/beans/sources" \
  -H "Authorization: Bearer ${API_KEY}" \
  --data-urlencode "q=middleeastainews.com" \
  --data-urlencode "domains=middleeastainews.com" \
  --data-urlencode "limit=5"

curl -s --get "${BASE_URL}/beans/articles/search" \
  -H "Authorization: Bearer ${API_KEY}" \
  --data-urlencode "sources=SOURCE_UUID" \
  --data-urlencode "limit=20"

GET /beans/sources/{id} returns one Source detail envelope. Description, favicon, and RSS metadata are optional display fields; an unavailable field is not an error.

Follow-up calls for coverage and context

Inspect a selected Article

Code
curl -s --get "${BASE_URL}/beans/articles/ARTICLE_UUID" \
  -H "Authorization: Bearer ${API_KEY}" \
  --data-urlencode "full_content=true"

Use Article detail after a collection has selected an Article UUID. The response can include available publisher body content plus links to related publisher reading, external mentions, and the Article's Story.

Code
# Related publisher reading. This is not guaranteed Story membership.
curl -s "${BASE_URL}/beans/articles/ARTICLE_UUID/similar?limit=20" \
  -H "Authorization: Bearer ${API_KEY}"

# Observed external platform or forum references to the selected Article.
curl -s "${BASE_URL}/beans/articles/ARTICLE_UUID/mentions?limit=20" \
  -H "Authorization: Bearer ${API_KEY}"

similar returns related publisher reading. mentions returns external observations with available platform, forum, observation time, and engagement fields. Neither route returns a replacement for the selected publisher Article, and related Articles are not guaranteed Story members.

Inspect a Story and its member Articles

Code
# Discover Story UUIDs with Article-style filters and a minimum Article count.
curl -s --get "${BASE_URL}/beans/stories" \
  -H "Authorization: Bearer ${API_KEY}" \
  --data-urlencode "tags=generative_ai_and_foundation_models" \
  --data-urlencode "min_article_count=2" \
  --data-urlencode "limit=20"

curl -s "${BASE_URL}/beans/stories/STORY_UUID" \
  -H "Authorization: Bearer ${API_KEY}"

curl -s --get "${BASE_URL}/beans/stories/STORY_UUID/articles" \
  -H "Authorization: Bearer ${API_KEY}" \
  --data-urlencode "content_type=news" \
  --data-urlencode "limit=20"

The following captured Story detail response shows the full response type. The top_articles field contains previews, while links.articles identifies the pageable member collection.


Code
{
  "data": {
    "id": "06860aaa-a43c-585f-9cb3-a6710a93a74a",
    "title": "UAE AI Programme adds Agentic AI focus",
    "first_published_at": "2026-06-22T02:00:40Z",
    "last_published_at": "2026-08-24T02:00:43Z",
    "article_count": 12,
    "source_count": 1,
    "categories": [
      "artificial_intelligence_and_machine_learning",
      "generative_ai_and_foundation_models",
      "ai_ethics_and_governance",
      "robotics_and_autonomous_systems",
      "media_and_journalism"
    ],
    "regions": [
      "egypt",
      "middle_east",
      "africa",
      "japan",
      "riyadh",
      "saudi_arabia",
      "united_arab_emirates"
    ],
    "entities": [
      "carrington_malin",
      "anghami",
      "airev",
      "daniel_valle",
      "dubai_university",
      "muhammad_khalid",
      "qatar_university",
      "ai",
      "ai_agents",
      "ai_infrastructure"
    ],
    "tags": [
      "carrington_malin",
      "artificial_intelligence_and_machine_learning",
      "generative_ai_and_foundation_models",
      "anghami",
      "ai_ethics_and_governance",
      "egypt",
      "middle_east",
      "airev",
      "daniel_valle",
      "dubai_university"
    ],
    "top_articles": [
      {
        "id": "3a479e3c-a87d-591e-bb6c-5c83c03b6a40",
        "url": "https://www.middleeastainews.com/p/uae-ai-programme-adds-agentic-ai",
        "title": "UAE AI Programme adds Agentic AI focus",
        "published_at": "2026-08-24T02:00:43Z",
        "source": null
      },
      {
        "id": "ec2e3641-07cd-5a9c-870f-79256e293481",
        "url": "https://www.middleeastainews.com/p/kuwait-backs-ai-to-boost-smart-meter",
        "title": "Kuwait backs AI to boost smart meter efficiency",
        "published_at": "2026-08-22T02:00:35Z",
        "source": null
      },
      {
        "id": "e3a0e8ed-c10c-58ed-a408-61985f6f58f4",
        "url": "https://www.middleeastainews.com/p/dubai-chambers-nasscom-partner-on",
        "title": "Dubai Chambers, Nasscom partner on Agentic AI",
        "published_at": "2026-08-21T02:00:07Z",
        "source": null
      }
    ],
    "links": {
      "articles": "/stories/06860aaa-a43c-585f-9cb3-a6710a93a74a/articles"
    }
  }
}

Story-member Articles use the normal Article collection shape with Story-specific metadata. meta.story_id is the Story UUID used for this member response.


Code
{
  "pagination": {
    "limit": 1,
    "num_results": 1,
    "next_cursor": null
  },
  "meta": {
    "story_id": "06860aaa-a43c-585f-9cb3-a6710a93a74a",
    "as_of": "2026-08-24T20:42:39.633280927Z"
  },
  "data": [
    {
      "id": "3a479e3c-a87d-591e-bb6c-5c83c03b6a40",
      "url": "https://www.middleeastainews.com/p/uae-ai-programme-adds-agentic-ai",
      "content_type": "news",
      "published_at": "2026-08-24T02:00:43Z",
      "title": "UAE AI Programme adds Agentic AI focus",
      "summary": "Listen now | Middle East AI News Minute - 24-Aug-26",
      "story_id": "06860aaa-a43c-585f-9cb3-a6710a93a74a"
    }
  ]
}

Count routes remain unpublished. Use the pagination envelope to process returned records; do not infer a total match count from num_results.

JSON and MCP workflows

JSON is the canonical Beans response format. Keep collection envelopes intact in application code, and pass IDs and cursors through without parsing implementation details from them.

For an MCP workflow, choose a tool from the user question, then move to a detail tool only after selecting an ID:

Use listCategories, listEntities, listRegions, or listSentiments when a filter value is unknown.
Use searchArticles for topic retrieval or getLatestArticles, getTopHeadlines, and getTrendingArticles for feed intent.
Use getArticle for a selected Article UUID, then getSimilarArticles or getArticleMentions only when that context is needed.
Use listStories, getStory, and listStoryArticles for related-coverage workflows.
Use listSources or getSource to resolve publisher metadata and reuse a Source UUID as a filter.

MCP clients connect to https://api.cafecito.tech/beans/mcp with the same API key used for REST. See MCP & AI agents for connection and tool guidance.

Continue learning

Last modified on August 26, 2026

Make Your First API Call Beans News API