All Beans API endpoints for accessing articles, categories, entities, regions, and publisher information
List article categories
Retrieves a paginated list of unique article categories/topics discovered in the database.
query Parameters
limitpage limit (items per page)
offsetpagination offset (number of items to skip)
Headers
AuthorizationThe Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.
List article categories › Responses
list of category strings
List named entities
Retrieves a paginated list of unique named entities (persons, organizations, products, places) extracted from articles.
query Parameters
limitpage limit (items per page)
offsetpagination offset (number of items to skip)
Headers
AuthorizationThe Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.
List named entities › Responses
list of entity strings
List geographic regions
Retrieves a paginated list of unique geographic regions mentioned in articles.
query Parameters
limitpage limit (items per page)
offsetpagination offset (number of items to skip)
Headers
AuthorizationThe Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.
List geographic regions › Responses
list of region strings
Get top headlines
Retrieves top trending headlines from the past 24 hours, ranked by trend score.
query Parameters
qoptional semantic search query (character length 3-512)
accembedding accuracy/similarity threshold (0.0-1.0)
content_typecontent type filter (news, blog, post, etc.)
tagscase/whitespace-insensitive text search across categories, regions, entities (recommended)
categoriesprecise category filters (inclusive OR, case/whitespace-sensitive)
regionsprecise region filters (inclusive OR, case/whitespace-sensitive)
entitiesprecise entity filters (inclusive OR, case/whitespace-sensitive)
sourcespublisher source filters (inclusive OR)
full_contentinclude full article content
limitpage limit
offsetpagination offset
Headers
AuthorizationThe Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.
Get top headlines › Responses
array of top headlines from last 24h, sorted by trend_score
urlURL is the canonical URL of the article or post.
titleTitle is the human-readable headline or title of the content.
summarySummary is a short abstract or teaser used in listings and previews.
contentContent is the full body text when the source content is available.
content_typeContent type such as news, blog, post, comment, job, etc.
authorAuthor is the byline or attributed creator when available from the source.
image_urlImageUrl is the featured image or preview image associated with the content.
sourceSource is the canonical publisher identifier and matches Publisher.Source.
categoriesCategories lists the inferred topics assigned to the content.
regionsRegions lists geographic regions mentioned in or associated with the content.
entitiesEntities lists named entities such as people, places, organizations, or products.
tagsComputed tags merged from categories/regions/entities for display
publish_dateCreated is the original publish timestamp of the article or post.
likesLikes is the aggregate number of likes or upvotes associated with this Bean.
commentsComments is the aggregate number of replies or comments associated with this Bean.
sharesShares is the aggregate number of reposts or share-like actions associated with this Bean.
subscribersSubscribers is the aggregate audience size associated with this Bean's chatter.
trend_scoreTrendScore is the computed ranking score used to order trending results.
sentimentsSentiments lists inferred tones or sentiments expressed in the content.
Get latest articles
Retrieves the most recently published articles, sorted by publish date (newest first).
query Parameters
qoptional semantic search query (character length 3-512)
accembedding accuracy/similarity threshold (0.0-1.0)
content_typecontent type filter (news, blog, post, etc.)
tagscase/whitespace-insensitive text search across categories, regions, entities (recommended)
categoriesprecise category filters (inclusive OR, case/whitespace-sensitive)
regionsprecise region filters (inclusive OR, case/whitespace-sensitive)
entitiesprecise entity filters (inclusive OR, case/whitespace-sensitive)
sourcespublisher source filters (inclusive OR)
frompublished since date (YYYY-MM-DD, defaults to 7 days ago if omitted)
full_contentinclude full article content
limitpage limit
offsetpagination offset
Headers
AuthorizationThe Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.
Get latest articles › Responses
array of latest articles sorted by publish date
urlThe URL of the article.
The content type of the article, e.g., news, blog, oped, job, post.
The publisher ID of the article.
The title of the article.
A summary of the article.
The full content of the article if available.
The URL of the article's featured image.
The author of the article (if available).
The publish date of the article.
Named entities mentioned in the article content.
Geographic regions mentioned in the article content.
Categories/topics of the article content.
Sentiments expressed in the article content.
Get trending articles
Retrieves trending articles ranked by trend score. Trend score is computed from:
query Parameters
qoptional semantic search query (character length 3-512)
accembedding accuracy/similarity threshold (0.0-1.0, higher = stricter)
content_typecontent type filter (news, blog, post, etc.)
tagscase/whitespace-insensitive text search across categories, regions, entities (recommended)
categoriesprecise category filters (inclusive OR, case/whitespace-sensitive)
regionsprecise region filters (inclusive OR, case/whitespace-sensitive)
entitiesprecise entity filters (inclusive OR, case/whitespace-sensitive)
sourcespublisher source filters (inclusive OR)
fromtrending since date (YYYY-MM-DD, defaults to 7 days ago)
full_contentinclude full article content
limitpage limit
offsetpagination offset
Headers
AuthorizationThe Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.
Get trending articles › Responses
array of trending articles sorted by trend_score (descending)
urlURL is the canonical URL of the article or post.
titleTitle is the human-readable headline or title of the content.
summarySummary is a short abstract or teaser used in listings and previews.
contentContent is the full body text when the source content is available.
content_typeContent type such as news, blog, post, comment, job, etc.
authorAuthor is the byline or attributed creator when available from the source.
image_urlImageUrl is the featured image or preview image associated with the content.
sourceSource is the canonical publisher identifier and matches Publisher.Source.
categoriesCategories lists the inferred topics assigned to the content.
regionsRegions lists geographic regions mentioned in or associated with the content.
entitiesEntities lists named entities such as people, places, organizations, or products.
tagsComputed tags merged from categories/regions/entities for display
publish_dateCreated is the original publish timestamp of the article or post.
likesLikes is the aggregate number of likes or upvotes associated with this Bean.
commentsComments is the aggregate number of replies or comments associated with this Bean.
sharesShares is the aggregate number of reposts or share-like actions associated with this Bean.
subscribersSubscribers is the aggregate audience size associated with this Bean's chatter.
trend_scoreTrendScore is the computed ranking score used to order trending results.
sentimentsSentiments lists inferred tones or sentiments expressed in the content.
Search articles
Perform semantic (vector embedding) or tag-based search across all articles in the database.
query Parameters
qsemantic vector search query (character length 3-512, natural language)
accembedding accuracy/similarity threshold (0.0-1.0, higher = stricter match)
content_typecontent type filter (news, blog, post, generated, comment, etc.)
urlsspecific article URLs to fetch directly (CSV)
tagscase/whitespace-insensitive text search across categories, regions, entities (AND combination, recommended)
categoriesprecise category topic filters (inclusive OR, case/whitespace-sensitive)
regionsprecise geographic region filters (inclusive OR, case/whitespace-sensitive)
entitiesprecise named entity filters (inclusive OR, case/whitespace-sensitive)
sourcespublisher/source ID filters (inclusive OR)
frompublished/updated since date (ISO 8601 date format YYYY-MM-DD)
full_contentif true, include full article content (large payload)
limitpage limit (items per page)
offsetpagination offset (number of items to skip)
Headers
AuthorizationThe Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.
Search articles › Responses
array of article aggregates with engagement metrics
urlURL is the canonical URL of the article or post.
titleTitle is the human-readable headline or title of the content.
summarySummary is a short abstract or teaser used in listings and previews.
contentContent is the full body text when the source content is available.
content_typeContent type such as news, blog, post, comment, job, etc.
authorAuthor is the byline or attributed creator when available from the source.
image_urlImageUrl is the featured image or preview image associated with the content.
sourceSource is the canonical publisher identifier and matches Publisher.Source.
source_base_urlBaseURL is the publisher's primary site URL copied onto aggregate results for convenience.
source_descriptionDescription is the publisher description copied onto aggregate results.
source_faviconFavicon is the publisher favicon URL copied onto aggregate results.
source_site_nameSiteName is the human-readable name of the publisher copied onto aggregate results.
categoriesCategories lists the inferred topics assigned to the content.
regionsRegions lists geographic regions mentioned in or associated with the content.
entitiesEntities lists named entities such as people, places, organizations, or products.
tagsComputed tags merged from categories/regions/entities for display
publish_dateCreated is the original publish timestamp of the article or post.
cluster_idClusterId identifies the related-content cluster containing this Bean.
relatedRelated lists URLs of semantically or editorially related Beans.
num_relatedClusterSize is the total number of Beans in the same related-content cluster.
likesLikes is the aggregate number of likes or upvotes associated with this Bean.
commentsComments is the aggregate number of replies or comments associated with this Bean.
sharesShares is the aggregate number of reposts or share-like actions associated with this Bean.
subscribersSubscribers is the aggregate audience size associated with this Bean's chatter.
trend_scoreTrendScore is the computed ranking score used to order trending results.
sentimentsSentiments lists inferred tones or sentiments expressed in the content.
Get sources metadata
Retrieves detailed metadata for one or more sources including site name, description, favicon.
query Parameters
sourcessource IDs to fetch metadata for (comma-separated CSV)
limitpage limit (items per page)
offsetpagination offset (number of items to skip)
Headers
AuthorizationThe Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.
Get sources metadata › Responses
array of publisher metadata objects
sourceSource is the canonical publisher identifier and matches Bean.Source values.
source_base_urlBaseURL is the publisher's primary site URL.
source_descriptionDescription is a short description of the publisher or content source.
source_faviconFavicon is the URL of the publisher favicon or brand icon.
source_site_nameSiteName is the human-readable display name of the publisher.