openapi: 3.1.0
info:
title: APITube News API
version: 1.0.0
summary: Search and filter news articles from thousands of sources worldwide.
description: 'APITube News API provides programmatic access to a comprehensive, real-time news database
aggregated from thousands of sources worldwide. Use it to search, filter, and retrieve news articles
with advanced query capabilities.
## Key Endpoints
- **Everything** (`/v1/news/everything`) — full-text search across all indexed articles with filters
by title, date range, language, country, source, sentiment, category, topic, industry, and named entities
(people, organizations, locations, brands, etc.).
- **Top Headlines** (`/v1/news/top-headlines`) — breaking and trending news from high-authority sources
ranked by OPR score.
- **Story** (`/v1/news/story/{articleId}`) — retrieve related articles for a given story.
- **Article** (`/v1/news/article`) — fetch one or more articles by ID.
- **Dictionaries** — list available categories, topics, industries, and entities.
- **Trends** — discover trending topics and entities over time.
- **Stream** (`/v1/news/stream`) — real-time Server-Sent Events (SSE) stream of new articles.
- **Webhooks** — subscribe to push notifications for new articles matching your filters.
## Export Formats
JSON (default), CSV, TSV, XML, RSS, XLSX, Parquet, JSONL, and NDJSON.
## Authentication
All requests require an API key passed via the `X-API-Key` header or the `api_key` query parameter.'
contact:
name: APITube Support
url: https://apitube.io
email: support@apitube.io
termsOfService: https://apitube.io/terms/terms-of-service
components:
securitySchemes:
ApiKeyHeader:
type: apiKey
in: header
name: X-API-Key
description: API key passed via X-API-Key header
ApiKeyQuery:
type: apiKey
in: query
name: api_key
description: API key passed as query parameter
schemas: {}
paths:
/ping:
get:
summary: Ping (Health Check)
tags:
- System
description: Returns "pong" if the server is running.
responses:
'200':
description: Server is healthy
content:
application/json:
schema:
description: Server is healthy
type: string
example: pong
/v1/balance:
get:
summary: Get API key balance
tags:
- Account
description: Returns the current balance and plan information for the provided API key.
responses:
'200':
description: API key balance information
content:
application/json:
schema:
description: API key balance information
type: object
properties:
api_key:
type: string
description: The API key
points:
type: integer
description: Remaining points
plan:
type: string
description: Subscription plan name
example:
api_key: ak_live_abc123...
points: 48500
plan: professional
'400':
description: API key is required
content:
application/json:
schema:
description: API key is required
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
'401':
description: Invalid API key
content:
application/json:
schema:
description: Invalid API key
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
/v1/news/everything:
post:
summary: Search all news articles
tags:
- News
description: Search and filter news articles from thousands of sources worldwide. Supports advanced
filtering by title, date, language, source, category, topic, industry, entity, sentiment, readability,
media, location, and more. Results can be exported in multiple formats (CSV, TSV, XML, RSS, XLSX,
Parquet, JSONL).
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
prompt:
type: string
minLength: 3
maxLength: 500
description: 'Plain-language description of the news you want, e.g. "Elon Musk, Tesla,
news for the last 10 days". It is translated into the regular filters below before
the search runs, and the resulting parameters are returned in meta.prompt. Explicit
parameters always win over the prompt. Costs 2 extra points when the wording has not
been parsed before (repeats are served from cache). Available on Basic and above —
on Free and Starter the request fails with 403 ER0706. Errors: ER0706 (plan), ER0800
(length), ER0801 (translation service unavailable), ER0802 (nothing usable in the
prompt).'
page:
type: integer
minimum: 1
default: 1
description: Page number for pagination
per_page:
type: integer
minimum: 1
maximum: 250
default: 100
description: Number of results per page (max 250; the Free plan is capped at 10 and
Starter at 50)
sort.by:
type: string
enum:
- published_at
- relevance
- engagement
- quality
- controversy
- trust
- id
- new
- created_at
- source.rank.opr
- sentiment.overall.score
- sentiment.title.score
- sentiment.body.score
- read_time
- sentences_count
- paragraphs_count
- characters_count
- media.images.count
- media.videos.count
- media.images.width.min
- media.images.width.max
- media.images.height.min
- media.images.height.max
- media_richness
- shares.facebook.min
- shares.facebook.max
- shares.twitter.min
- shares.twitter.max
- shares.reddit.min
- shares.reddit.max
default: published_at
description: Field to sort results by
sort.order:
type: string
enum:
- asc
- desc
default: desc
description: Sort order
article.id:
type: string
description: Comma-separated article IDs (max 5)
example: '12345'
title:
type: string
minLength: 2
maxLength: 100
description: 'Search in article titles. Supports phrase search with proximity: "climate
change"~2. Title search is limited to a 31-day published_at window: without published_at.start
/ published_at.end the last 31 days are searched, a wider explicit range returns ER0110.'
ignore.title:
type: string
minLength: 2
maxLength: 100
description: Exclude articles containing this text in the title
title_starts_with:
type: string
minLength: 2
maxLength: 100
description: Filter articles whose title starts with the given text. Same 31-day window
limit as title
title_ends_with:
type: string
minLength: 2
maxLength: 100
description: Filter articles whose title ends with the given text. Same 31-day window
limit as title
title_pattern:
type: string
minLength: 2
maxLength: 200
description: Filter articles whose title matches the given pattern. Same 31-day window
limit as title
published_at:
type: string
description: 'Exact date (creates 24-hour range). Format: YYYY-MM-DD or ISO 8601'
example: '2025-01-15'
published_at.start:
type: string
description: 'Start of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title
search the range may not exceed 31 days (ER0110)'
example: '2025-01-01'
published_at.end:
type: string
description: 'End of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title
search the range may not exceed 31 days (ER0110)'
example: '2025-01-31'
language.code:
type: string
description: Comma-separated ISO 639-1 language codes (max 3)
example: en
ignore.language.code:
type: string
description: Exclude articles in these languages (comma-separated, max 3)
example: zh,ar
source.country.code:
type: string
description: Filter by source country ISO 3166-1 alpha-2 codes (comma-separated, max
3)
example: us
ignore.source.country.code:
type: string
description: Exclude sources from these countries (comma-separated, max 3)
example: us
source.rank.opr.min:
type: integer
minimum: 0
description: Minimum Open PageRank score
source.rank.opr.max:
type: integer
minimum: 0
description: Maximum Open PageRank score
source.id:
type: string
description: Comma-separated source IDs (max 3)
example: '100'
ignore.source.id:
type: string
description: Exclude these source IDs (comma-separated, max 3)
source.domain:
type: string
description: Comma-separated source domains (max 3)
example: nytimes.com
ignore.source.domain:
type: string
description: Exclude these source domains (comma-separated, max 3)
source.bias:
type: string
description: 'Filter by media bias (comma-separated). Values: left, center, right'
example: left
ignore.source.bias:
type: string
description: 'Exclude sources with this media bias (comma-separated). Values: left,
center, right'
example: right
is_premium_source:
type: integer
enum:
- 0
- 1
description: Filter by premium source status
is_verified_source:
type: integer
enum:
- 0
- 1
description: Filter by verified source status
category.id:
type: string
description: Comma-separated category IDs (max 3)
example: iab-1
ignore.category.id:
type: string
description: Exclude these categories (comma-separated, max 3)
topic.id:
type: string
description: Comma-separated topic IDs (max 3)
example: technology
ignore.topic.id:
type: string
description: Exclude these topics (comma-separated, max 3)
industry.id:
type: string
description: Comma-separated industry IDs (max 3)
example: '1'
ignore.industry.id:
type: string
description: Exclude these industries (comma-separated, max 3)
entity.id:
type: string
description: Comma-separated entity IDs (max 3)
example: '12345'
ignore.entity.id:
type: string
description: Exclude these entity IDs (comma-separated, max 3)
entity.sentiment.polarity:
type: string
enum:
- positive
- negative
- neutral
description: Filter by sentiment polarity toward the entity (combine with entity.id
or *.name; standalone = any entity)
entity.sentiment.score.min:
type: number
minimum: -1
maximum: 1
description: Minimum sentiment score toward the entity
entity.sentiment.score.max:
type: number
minimum: -1
maximum: 1
description: Maximum sentiment score toward the entity
person.name:
type: string
maxLength: 120
description: Filter by person name (comma-separated, max 3)
example: Elon Musk
ignore.person.name:
type: string
maxLength: 120
description: Exclude articles mentioning these persons (comma-separated, max 3)
organization.name:
type: string
maxLength: 120
description: Filter by organization name (comma-separated, max 3)
example: Google
ignore.organization.name:
type: string
maxLength: 120
description: Exclude articles mentioning these organizations (comma-separated, max 3)
location.name:
type: string
maxLength: 120
description: Filter by location name (comma-separated, max 3)
example: New York
ignore.location.name:
type: string
maxLength: 120
description: Exclude articles mentioning these locations (comma-separated, max 3)
brand.name:
type: string
maxLength: 120
description: Filter by brand name (comma-separated, max 3)
ignore.brand.name:
type: string
maxLength: 120
description: Exclude articles mentioning these brands (comma-separated, max 3)
disaster.name:
type: string
maxLength: 120
description: Filter by natural disaster name (comma-separated, max 3)
ignore.disaster.name:
type: string
maxLength: 120
description: Exclude articles mentioning these disasters (comma-separated, max 3)
disease.name:
type: string
maxLength: 120
description: Filter by disease name (comma-separated, max 3)
ignore.disease.name:
type: string
maxLength: 120
description: Exclude articles mentioning these diseases (comma-separated, max 3)
event.name:
type: string
maxLength: 120
description: Filter by event name (comma-separated, max 3)
ignore.event.name:
type: string
maxLength: 120
description: Exclude articles mentioning these events (comma-separated, max 3)
sport.name:
type: string
maxLength: 120
description: Filter by sport name (comma-separated, max 3)
ignore.sport.name:
type: string
maxLength: 120
description: Exclude articles mentioning these sports (comma-separated, max 3)
event.type:
type: string
description: 'Comma-separated event types (max 5). Values: merger-acquisition, ipo,
layoffs, bankruptcy, product-launch, funding-round, earnings, partnership, executive-change,
lawsuit, data-breach, recall, expansion, closure, stock-movement, contract-award,
spin-off, regulatory-action, election, protest, crime, terrorism, accident, policy-change,
scandal, death, award-ceremony, conflict, diplomacy, health-crisis, migration, human-rights,
earthquake, hurricane, flood, wildfire, tornado, tsunami, volcanic-eruption, drought,
climate-event, pollution, wildlife-event, avalanche'
example: ipo
event.category:
type: string
enum:
- business
- society
- environment
description: Filter by event category
ignore.event.type:
type: string
description: Exclude these event types (comma-separated, max 5)
sentiment.overall.score:
type: number
minimum: -1
maximum: 1
description: Exact overall sentiment score
sentiment.overall.score.min:
type: number
minimum: -1
maximum: 1
description: Minimum overall sentiment score
sentiment.overall.score.max:
type: number
minimum: -1
maximum: 1
description: Maximum overall sentiment score
sentiment.overall.polarity:
type: string
enum:
- positive
- negative
- neutral
description: Overall sentiment polarity
sentiment.title.score:
type: number
minimum: -1
maximum: 1
description: Exact title sentiment score
sentiment.title.score.min:
type: number
minimum: -1
maximum: 1
description: Minimum title sentiment score
sentiment.title.score.max:
type: number
minimum: -1
maximum: 1
description: Maximum title sentiment score
sentiment.title.polarity:
type: string
enum:
- positive
- negative
- neutral
description: Title sentiment polarity
sentiment.body.score:
type: number
minimum: -1
maximum: 1
description: Exact body sentiment score
sentiment.body.score.min:
type: number
minimum: -1
maximum: 1
description: Minimum body sentiment score
sentiment.body.score.max:
type: number
minimum: -1
maximum: 1
description: Maximum body sentiment score
sentiment.body.polarity:
type: string
enum:
- positive
- negative
- neutral
description: Body sentiment polarity
sentiment.mixed:
type: integer
enum:
- 0
- 1
description: Filter for mixed sentiment (title polarity != body polarity)
sentiment.consistent:
type: integer
enum:
- 0
- 1
description: Filter for consistent sentiment (title polarity == body polarity)
is_clickbait:
type: integer
enum:
- 0
- 1
description: Filter by clickbait detection
sentiment_gap.min:
type: number
minimum: 0
maximum: 2
description: Minimum sentiment gap between title and body
sentiment_gap.max:
type: number
minimum: 0
maximum: 2
description: Maximum sentiment gap between title and body
media.images.count:
type: integer
minimum: 0
description: Exact number of images
media.images.count.min:
type: integer
minimum: 0
description: Minimum number of images
media.images.count.max:
type: integer
minimum: 0
description: Maximum number of images
media.images.width.min:
type: integer
minimum: 0
description: Minimum image width in pixels
media.images.width.max:
type: integer
minimum: 0
description: Maximum image width in pixels
media.images.height.min:
type: integer
minimum: 0
description: Minimum image height in pixels
media.images.height.max:
type: integer
minimum: 0
description: Maximum image height in pixels
media.videos.count:
type: integer
minimum: 0
description: Exact number of videos
media.videos.count.min:
type: integer
minimum: 0
description: Minimum number of videos
media.videos.count.max:
type: integer
minimum: 0
description: Maximum number of videos
has_image:
type: integer
enum:
- 0
- 1
description: Filter articles with/without images
has_video:
type: integer
enum:
- 0
- 1
description: Filter articles with/without videos
has_hq_images:
type: integer
enum:
- 0
- 1
description: Filter articles with high-quality images (>= 1200px width)
is_media_rich:
type: integer
enum:
- 0
- 1
description: Filter articles with both images and videos
is_landscape_media:
type: integer
enum:
- 0
- 1
description: Filter articles with landscape-oriented media
is_portrait_media:
type: integer
enum:
- 0
- 1
description: Filter articles with portrait-oriented media
has_multiple_images:
type: integer
enum:
- 0
- 1
description: Filter articles with 2+ images
has_fullhd_images:
type: integer
enum:
- 0
- 1
description: Filter articles with Full HD images (>= 1920px width)
has_4k_images:
type: integer
enum:
- 0
- 1
description: Filter articles with 4K images (>= 3840px width)
has_mobile_optimized_images:
type: integer
enum:
- 0
- 1
description: Filter articles with mobile-optimized images (320-800px width)
is_instagram_ready:
type: integer
enum:
- 0
- 1
description: Filter articles with Instagram-ready images (>= 1080px + aspect ratio)
is_twitter_card_ready:
type: integer
enum:
- 0
- 1
description: Filter articles with Twitter Card-ready images (>= 800px + landscape)
has_consistent_image_sizes:
type: integer
enum:
- 0
- 1
description: Filter articles with consistent image dimensions
has_thumbnail:
type: integer
enum:
- 0
- 1
description: Filter articles with thumbnail images (<= 300px width)
has_social_share_image:
type: integer
enum:
- 0
- 1
description: Filter articles with social share images (>= 1200x630px)
has_mixed_media:
type: integer
enum:
- 0
- 1
description: Filter articles with both image and video media types
readability.fk_grade:
type: number
minimum: 0
maximum: 30
description: Exact Flesch-Kincaid grade level
readability.fk_grade.min:
type: number
minimum: 0
maximum: 30
description: Minimum Flesch-Kincaid grade level
readability.fk_grade.max:
type: number
minimum: 0
maximum: 30
description: Maximum Flesch-Kincaid grade level
readability.ease:
type: number
minimum: 0
maximum: 100
description: Exact Flesch Reading Ease score
readability.ease.min:
type: number
minimum: 0
maximum: 100
description: Minimum Flesch Reading Ease score
readability.ease.max:
type: number
minimum: 0
maximum: 100
description: Maximum Flesch Reading Ease score
readability.ari:
type: number
minimum: 0
maximum: 30
description: Exact Automated Readability Index
readability.ari.min:
type: number
minimum: 0
maximum: 30
description: Minimum Automated Readability Index
readability.ari.max:
type: number
minimum: 0
maximum: 30
description: Maximum Automated Readability Index
readability.difficulty:
type: string
enum:
- beginner
- intermediate
- advanced
- expert
description: Difficulty level
readability.audience:
type: string
enum:
- children
- general
- professional
- academic
description: Target audience
readability.age:
type: integer
minimum: 6
maximum: 22
description: Exact reading age
readability.age.min:
type: integer
minimum: 6
maximum: 22
description: Minimum reading age
readability.age.max:
type: integer
minimum: 6
maximum: 22
description: Maximum reading age
is_easy_read:
type: integer
enum:
- 0
- 1
description: Filter for easy-to-read articles (Flesch Reading Ease >= 60)
is_difficult_read:
type: integer
enum:
- 0
- 1
description: Filter for difficult-to-read articles (Flesch Reading Ease < 40)
read_time:
type: integer
minimum: 0
maximum: 1000
description: Exact read time in minutes
read_time.min:
type: integer
minimum: 0
maximum: 1000
description: Minimum read time in minutes
read_time.max:
type: integer
minimum: 0
maximum: 1000
description: Maximum read time in minutes
is_long_read:
type: integer
enum:
- 0
- 1
description: Filter for long reads (>= 5 minutes)
is_short_read:
type: integer
enum:
- 0
- 1
description: Filter for short reads (< 3 minutes)
is_quick_read:
type: integer
enum:
- 0
- 1
description: Filter for quick reads (<= 2 minutes)
is_medium_read:
type: integer
enum:
- 0
- 1
description: Filter for medium-length reads (3-7 minutes)
is_deep_dive:
type: integer
enum:
- 0
- 1
description: Filter for deep dives (>= 10 minutes)
location.bbox:
type: string
description: 'Bounding box: minLat,maxLat,minLng,maxLng'
example: 40.0,41.0,-74.5,-73.5
has_location_geo:
type: integer
enum:
- 0
- 1
description: Filter articles with/without geo-location data
location.lat:
type: number
minimum: -90
maximum: 90
description: Latitude for radius search
location.lng:
type: number
minimum: -180
maximum: 180
description: Longitude for radius search
location.radius:
type: number
exclusiveMinimum: 0
maximum: 20000
description: Search radius in kilometers (requires location.lat and location.lng)
location.radius.min:
type: number
minimum: 0
maximum: 20000
description: Minimum distance from point in km
is_duplicate:
type: integer
enum:
- 0
- 1
description: Filter duplicate/unique articles
is_paywall:
type: integer
enum:
- 0
- 1
description: Filter paywalled articles
is_breaking:
type: integer
enum:
- 0
- 1
description: Filter breaking news articles
is_high_quality:
type: integer
enum:
- 0
- 1
description: Filter high-quality articles (not duplicate, rank >= 5, has images, has
author)
author.id:
type: string
description: Comma-separated author IDs (max 3)
ignore.author.id:
type: string
description: Exclude these author IDs (comma-separated, max 3)
author.name:
type: string
maxLength: 100
description: Filter by author name (comma-separated, max 3)
ignore.author.name:
type: string
maxLength: 100
description: Exclude articles by these authors (comma-separated, max 3)
has_author:
type: integer
enum:
- 0
- 1
description: Filter articles with/without author
facet:
type: string
enum:
- '0'
- '1'
description: Enable faceting
facet.field:
type: string
description: 'Comma-separated facet fields (max 5). Values: source.id, source.country.id,
source.bias, language.id, author.id, category.id, topic.id, industry.id, entity.id,
sentiment.overall.polarity, sentiment.title.polarity, sentiment.body.polarity, sentiment.strength,
is_duplicate, is_free, is_important, media.images.count, media.videos.count, read_time,
content.length, published.year, published.month, published.day_of_week, published.hour,
published.weekday, published.time_of_day'
example: source.id,category.id
facet.limit:
type: integer
minimum: 1
maximum: 100
default: 10
description: Maximum number of facet values per field (max 100)
facet.mincount:
type: integer
minimum: 1
default: 1
description: Minimum count for a facet value to be included
facet.range:
type: string
enum:
- '0'
- '1'
description: Enable range faceting
facet.range.field:
type: string
description: 'Field for range faceting. Values: published_at, sentiment.overall.score,
sentiment.title.score, sentiment.body.score, read_time, source.rank.opr, media.images.count,
media.videos.count'
facet.range.start:
type: string
description: Start value for range faceting (required with facet.range)
facet.range.end:
type: string
description: End value for range faceting (required with facet.range)
facet.range.gap:
type: string
default: +1DAY
description: Gap value for range faceting
hl:
type: string
enum:
- '0'
- '1'
description: Enable highlighting
hl.fl:
type: string
default: title,description
description: 'Comma-separated fields to highlight (max 5). Values: title, description,
body'
example: title,description
hl.fragsize:
type: integer
minimum: 50
maximum: 500
default: 150
description: Size of highlighted fragment in characters (50-500)
hl.snippets:
type: integer
minimum: 1
maximum: 10
default: 3
description: Number of highlighted snippets per field (max 10)
hl.tag.pre:
type: string
description: Opening tag for highlighted text
default:
hl.tag.post:
type: string
description: Closing tag for highlighted text
default:
export:
type: string
enum:
- json
- csv
- tsv
- xml
- rss
- xlsx
- parquet
- jsonl
- ndjson
description: Export format
fl:
type: string
description: Comma-separated list of fields to include in the response
example: id,title,published_at,source.domain
debug:
type: string
enum:
- '0'
- '1'
description: Include user_input in response for debugging
api_key:
type: string
description: API key (alternative to X-API-Key header)
responses:
'200':
description: Successful response with articles
content:
application/json:
schema:
description: Successful response with articles
type: object
properties:
status:
type: string
enum:
- ok
description: Response status
limit:
type: integer
description: Results per page
path:
type: string
description: Current request URL
page:
type: integer
description: Current page number
has_next_pages:
type: boolean
description: Whether more pages are available
next_page:
type: string
description: URL for the next page (empty if no next page)
has_previous_page:
type: boolean
description: Whether a previous page exists
previous_page:
type: string
description: URL for the previous page (empty if no previous page)
export:
type: object
description: Export format URLs
properties:
json:
type: string
xlsx:
type: string
csv:
type: string
tsv:
type: string
xml:
type: string
rss:
type: string
parquet:
type: string
jsonl:
type: string
request_id:
type: string
description: Unique request identifier
results:
type: array
items:
type: object
properties:
id:
type: integer
description: Unique article ID
href:
type:
- string
- 'null'
description: Original article URL
published_at:
type:
- string
- 'null'
format: date-time
description: Publication date in ISO 8601
title:
type:
- string
- 'null'
description: Article title
description:
type:
- string
- 'null'
description: Article description (plain text)
body:
type:
- string
- 'null'
description: Article body (plain text)
body_html:
type:
- string
- 'null'
description: Article body (HTML)
language:
type: string
description: ISO 639-1 language code
translations:
type: object
description: Machine translations of the article title and description. Always
present; fields stay null for English articles and for languages without a
translation model
properties:
en:
type: object
properties:
title:
type:
- string
- 'null'
description: Title translated to English
description:
type:
- string
- 'null'
description: Description translated to English (plain text)
author:
type: object
properties:
id:
type:
- integer
- 'null'
description: Author ID
name:
type: string
description: Author name
image:
type: string
description: Main article image URL
categories:
type: array
items:
type: object
properties:
id:
type: integer
description: Category ID
name:
type: string
description: Category name
score:
type: number
description: Relevance score
taxonomy:
type: string
description: Taxonomy identifier
links:
type: object
properties:
self:
type: string
description: Link to category endpoint
topics:
type: array
items:
type: object
properties:
id:
type: string
description: Topic ID
name:
type: string
description: Topic name
score:
type: number
description: Relevance score
links:
type: object
properties:
self:
type: string
description: Link to topic endpoint
industries:
type: array
items:
type: object
properties:
id:
type: integer
description: Industry ID
name:
type: string
description: Industry name
links:
type: object
properties:
self:
type: string
description: Link to industry endpoint
entities:
type: array
items:
type: object
properties:
id:
type: integer
description: Entity ID
name:
type: string
description: Entity name
type:
type: string
enum:
- person
- location
- organization
- brand
- product
- natural-disaster
- disease
- event
- sport
- unknown
description: Entity type
frequency:
type: integer
description: Number of mentions in the article
sentiment:
type: object
description: Sentiment toward this entity (aggregated across its mentions)
properties:
score:
type: number
description: Entity sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Entity sentiment polarity
mentions:
type: object
description: Per-mention polarity breakdown
properties:
positive:
type: integer
neutral:
type: integer
negative:
type: integer
title:
type: object
properties:
pos:
type: array
items:
type: object
properties:
start:
type: integer
description: Start character offset
end:
type: integer
description: End character offset
description: Mention positions in title
body:
type: object
properties:
pos:
type: array
items:
type: object
properties:
start:
type: integer
description: Start character offset
end:
type: integer
description: End character offset
description: Mention positions in body
links:
type: object
properties:
self:
type: string
description: Link to entity endpoint
wikipedia:
type: string
description: Wikipedia URL
wikidata:
type: string
description: Wikidata URL
metadata:
type: object
description: Additional entity metadata (varies by entity type)
additionalProperties: true
locations_mentioned:
type: array
items:
type: object
properties:
name:
type: string
description: Location name
country:
type: string
description: Country code
lat:
type:
- number
- 'null'
description: Latitude
lng:
type:
- number
- 'null'
description: Longitude
type:
type: string
description: Location type
source:
type: object
properties:
id:
type:
- integer
- 'null'
description: Source ID
domain:
type: string
description: Source domain
home_page_url:
type: string
description: Source home page URL
type:
type: string
description: Source type
bias:
type: string
description: Media bias (left, center, right)
rankings:
type: object
properties:
opr:
type: integer
description: Open PageRank score
location:
type: object
properties:
country_name:
type: string
description: Source country name
country_code:
type: string
description: Source country ISO code
favicon:
type: string
description: Source favicon URL
sentiment:
type: object
properties:
overall:
type: object
properties:
score:
type: number
description: Sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Sentiment polarity
title:
type: object
properties:
score:
type: number
description: Sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Sentiment polarity
body:
type: object
properties:
score:
type: number
description: Sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Sentiment polarity
summary:
type: array
items:
type: object
properties:
sentence:
type: string
description: Summary sentence
sentiment:
type: object
properties:
score:
type: number
description: Sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Sentiment polarity
readability:
type: object
properties:
flesch_kincaid_grade:
type: number
description: Flesch-Kincaid grade level
flesch_reading_ease:
type: number
description: Flesch Reading Ease score (0-100)
automated_readability_index:
type: number
description: Automated Readability Index
difficulty_level:
type: string
enum:
- beginner
- intermediate
- advanced
- expert
- unknown
description: Difficulty level
target_audience:
type: string
enum:
- children
- general
- professional
- academic
- unknown
description: Target audience
reading_age:
type: number
description: Estimated reading age
avg_words_per_sentence:
type: number
description: Average words per sentence
avg_syllables_per_word:
type: number
description: Average syllables per word
keywords:
type: array
items:
type: string
description: Article keywords
links:
type: array
items:
type: object
properties:
url:
type: string
description: Link URL
type:
type: string
description: Link type
media:
type: array
items:
type: object
properties:
url:
type: string
description: Media URL
type:
type: string
description: Media type (image, video, etc.)
shares:
type: object
properties:
total:
type: integer
description: Total social shares
facebook:
type: integer
description: Facebook shares
twitter:
type: integer
description: Twitter/X shares
reddit:
type: integer
description: Reddit shares
story:
type: object
properties:
id:
type: integer
description: Story ID
uri:
type: string
description: Story endpoint URI
is_duplicate:
type: boolean
description: Whether this is a duplicate article
is_free:
type: boolean
description: Whether the article is freely accessible
is_breaking:
type: boolean
description: Whether this is breaking news
read_time:
type: integer
description: Estimated read time in minutes
sentences_count:
type: integer
description: Number of sentences
paragraphs_count:
type: integer
description: Number of paragraphs
words_count:
type: integer
description: Number of words
characters_count:
type: integer
description: Number of characters
description: Array of articles
facets:
type: object
description: Facet results (present when facet.field is specified)
additionalProperties: true
highlighting:
type: object
description: Highlighting results (present when hl=1)
additionalProperties: true
headlines:
type: array
description: Headlines (present in some responses)
items:
type: object
additionalProperties: true
meta:
type: object
description: 'Additional metadata. Present only when there is something to report
about how the request was handled: `prompt` (the request used the prompt parameter)
and/or `warnings` (the query was silently narrowed, e.g. ER0366 clamping a title
search to the last 31 days).'
properties:
prompt:
type: object
description: How the `prompt` parameter was translated into filters. Returned
by every JSON response to a request that used it (the SSE stream has no JSON
envelope, so it carries none).
properties:
text:
type: string
description: The prompt as it was parsed, trimmed
applied:
type: object
description: Parameters the prompt was translated into — the request that
actually ran
additionalProperties:
type: string
ignored:
type: array
description: Values understood but not used
items:
type: object
properties:
field:
type: string
description: Parameter that was not applied
value:
type: string
description: Value the prompt produced for it
reason:
type: string
enum:
- not_found
- explicit_param
- unsupported_on_endpoint
- invalid_date
- title_too_long
- title_window_clamped
description: Why the value was not applied
cached:
type: boolean
description: true when this wording had been parsed before, so no parse fee
was charged
warnings:
type: array
description: Non-fatal notices — the request still returned HTTP 200
items:
type: object
properties:
code:
type: string
description: Warning code, e.g. ER0366
message:
type: string
description: Human-readable explanation
links:
type: object
additionalProperties: true
additionalProperties: true
user_input:
type: object
description: Debug info — original request parameters (present when debug=1)
additionalProperties: true
required:
- status
- limit
- path
- page
- has_next_pages
- has_previous_page
- request_id
- results
example:
status: ok
limit: 50
path: /v1/news/everything
page: 1
has_next_pages: true
next_page: /v1/news/everything?page=2
has_previous_page: false
previous_page: ''
export:
json: /v1/news/everything?export=json
csv: /v1/news/everything?export=csv
rss: /v1/news/everything?export=rss
request_id: req_abc123def456
results:
- id: 84029371
href: https://example.com/article/spacex-launch
published_at: '2026-03-23T14:30:00Z'
title: SpaceX Successfully Launches New Starship Prototype
description: SpaceX completed another successful test flight of its Starship rocket...
language: en
author:
id: 1024
name: Jane Smith
image: https://example.com/images/starship.jpg
categories:
- id: 201
name: Science & Technology
score: 0.95
taxonomy: iptc_mediatopics
topics:
- id: space-exploration
name: Space Exploration
score: 0.92
industries:
- id: 88
name: Aerospace & Defense
entities:
- id: 5012
name: SpaceX
type: organization
frequency: 8
links:
wikipedia: https://en.wikipedia.org/wiki/SpaceX
- id: 3401
name: Elon Musk
type: person
frequency: 3
links:
wikipedia: https://en.wikipedia.org/wiki/Elon_Musk
source:
id: 7823
domain: reuters.com
home_page_url: https://www.reuters.com
type: news_agency
location:
country_name: United States
country_code: us
rankings:
opr: 8
sentiment:
overall:
score: 0.65
polarity: positive
title:
score: 0.72
polarity: positive
body:
score: 0.61
polarity: positive
readability:
flesch_kincaid_grade: 10.2
flesch_reading_ease: 52.3
difficulty_level: intermediate
target_audience: general
keywords:
- spacex
- starship
- rocket
- launch
is_duplicate: false
is_breaking: true
read_time: 4
words_count: 847
'401':
description: Authentication error
content:
application/json:
schema:
description: Authentication error
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
description: Rate limit exceeded
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
/v1/news/raw:
post:
summary: Get raw articles (before parsing & enrichment)
tags:
- News
description: Returns raw articles straight from the discovery stage, before HTML parsing and NLP
enrichment. This is a fast-churning staging feed (rows are continuously consumed by the pipeline
and expire within ~1 day). Enrichment fields (language, categories, topics, entities, sentiment,
etc.) are not available at this stage. Supports pagination, source filtering, a published date
range, and basic sorting.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
page:
type: integer
description: Page number (default 1).
example: 1
per_page:
type: integer
description: Results per page (default 100, max 250; the Free plan is capped at 10 and
Starter at 50).
example: 100
source.id:
type: string
description: Comma-separated source (sitemap) IDs (max 3).
example: '123'
ignore.source.id:
type: string
description: Comma-separated source IDs to exclude (max 3).
example: '789'
published_at:
type: string
description: Single day filter (creates a 24h range). ISO 8601 / YYYY-MM-DD / relative.
example: '2026-05-27'
published_at.start:
type: string
description: Start of the publication date range.
example: '2026-05-26'
published_at.end:
type: string
description: End of the publication date range.
example: '2026-05-27'
sort.by:
type: string
enum:
- id
- published_at
- created_at
description: Sort field (default id).
example: id
sort.order:
type: string
enum:
- asc
- desc
description: Sort direction (default desc).
example: desc
prompt:
type: string
minLength: 3
maxLength: 500
description: 'Plain-language description of the news you want. Only PARTIALLY applied
here: this endpoint understands published_at.start, published_at.end, sort.order and
per_page, so anything else the prompt produced is reported in meta.prompt.ignored
with reason "unsupported_on_endpoint". The 2-point translation fee still applies on
a cache miss. Available on Basic and above — on Free and Starter the request fails
with 403 ER0706.'
responses:
'200':
description: Successful response with raw articles
content:
application/json:
schema:
description: Successful response with raw articles
type: object
properties:
status:
type: string
enum:
- ok
description: Response status
limit:
type: integer
description: Results per page
path:
type: string
description: Current request URL
page:
type: integer
description: Current page number
has_next_pages:
type: boolean
description: Whether more pages are available
next_page:
type: string
description: URL for the next page (empty if none)
has_previous_page:
type: boolean
description: Whether a previous page exists
previous_page:
type: string
description: URL for the previous page (empty if none)
request_id:
type: string
description: Unique request identifier
results:
type: array
items:
type: object
properties:
id:
type: integer
description: Raw article ID
title:
type:
- string
- 'null'
description: Article title from RSS
href:
type:
- string
- 'null'
description: Article URL
created_at:
type:
- string
- 'null'
description: Publication date from RSS (may be null)
description:
type:
- string
- 'null'
description: Short description from RSS
body:
type: string
description: Article body with HTML stripped (plain text)
body_html:
type: string
description: Article body as received from RSS (HTML)
author:
type:
- string
- 'null'
description: Author from RSS
keywords:
type:
- array
- 'null'
items:
type: string
description: Raw RSS keywords/categories
source:
type: object
description: Source (publisher) details, resolved from the sitemap repository
properties:
id:
type:
- integer
- 'null'
description: Source (sitemap) ID
domain:
type: string
description: Source domain
home_page_url:
type: string
description: Source home page URL
type:
type: string
description: Source resource type
bias:
type: string
description: Political bias (left/center/right)
rankings:
type: object
properties:
opr:
type:
- number
- 'null'
description: Open PageRank
location:
type: object
properties:
country_name:
type: string
country_code:
type: string
favicon:
type: string
description: Favicon URL
description: Array of raw (unenriched) articles
'401':
description: Authentication error
content:
application/json:
schema:
description: Authentication error
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
description: Rate limit exceeded
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
/v1/fact-check:
post:
summary: Fact-check an article or a claim
tags:
- Fact Check
description: Verifies factual claims against APITube’s live news corpus (retrieval-augmented). Accepts
an article `id` (loaded from the corpus), raw article `text`, or a single `claim`. Returns per-claim
verdicts on an 8-level scale with calibrated confidence, an explanation, and the supporting/refuting
evidence articles.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
id:
type: integer
description: APITube article id to fact-check. The article is loaded from the corpus
and its claims are extracted and verified. Takes priority over `text` and `claim`.
example: 123456789
text:
type: string
description: Raw article text (title + body), 100–10000 characters. Claims are extracted
automatically.
minLength: 100
maxLength: 10000
claim:
type: string
description: A single factual statement to verify directly (5–500 characters).
minLength: 5
maxLength: 500
example: OpenAI released GPT-5 in 2024
max_claims:
type: integer
description: Maximum number of claims to extract and verify (capped server-side).
example: 5
evidence_per_claim:
type: integer
description: Maximum number of evidence articles to retrieve per claim (capped server-side).
example: 5
responses:
'200':
description: Fact-check result
content:
application/json:
schema:
description: Fact-check result
type: object
properties:
status:
type: string
enum:
- ok
request_id:
type:
- string
- 'null'
input:
type: object
properties:
type:
type: string
enum:
- id
- text
- claim
language:
type: string
summary:
type: object
properties:
overall_verdict:
type: string
enum:
- 'true'
- mostly_true
- mixed
- misleading
- mostly_false
- 'false'
- unverified
- outdated
overall_confidence:
type: number
claims_total:
type: integer
claims_checked:
type: integer
verdict_breakdown:
type: object
additionalProperties:
type: integer
claims:
type: array
items:
type: object
properties:
claim:
type: string
normalized_claim:
type: string
checkworthy:
type: boolean
verdict:
type: string
enum:
- 'true'
- mostly_true
- mixed
- misleading
- mostly_false
- 'false'
- unverified
- outdated
confidence:
type: number
description: Calibrated confidence in the verdict (0..1)
as_of:
type: string
description: Date the verdict is valid as of (YYYY-MM-DD)
explanation:
type: string
evidence:
type: array
items:
type: object
properties:
article_id:
type: integer
description: APITube article id of the evidence
title:
type: string
url:
type: string
source:
type: string
description: Source domain
source_authority:
type: integer
description: Source authority/OPR rank (higher = more authoritative)
published_at:
type:
- string
- 'null'
format: date-time
snippet:
type: string
stance:
type: string
enum:
- supports
- refutes
- neutral
relevance:
type: number
description: Relevance of the evidence to the claim (0..1)
'400':
description: Invalid request (no input, or out-of-range text/claim/id)
content:
application/json:
schema:
description: Invalid request (no input, or out-of-range text/claim/id)
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
'401':
description: Authentication error
content:
application/json:
schema:
description: Authentication error
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
'402':
description: No points / balance on the account
content:
application/json:
schema:
description: No points / balance on the account
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
'403':
description: Not available on the free plan, or API key lacks the fact_check scope
content:
application/json:
schema:
description: Not available on the free plan, or API key lacks the fact_check scope
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
'404':
description: Article with the provided id was not found
content:
application/json:
schema:
description: Article with the provided id was not found
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
description: Rate limit exceeded
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
'502':
description: Fact-check upstream temporarily unavailable
content:
application/json:
schema:
description: Fact-check upstream temporarily unavailable
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
/v1/news/top-headlines:
post:
summary: Get top headlines
tags:
- News
description: Returns top headlines — breaking and important news from high-authority sources (OPR
rank >= 5). Supports the same filtering, faceting, highlighting, and export options as /v1/news/everything.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
prompt:
type: string
minLength: 3
maxLength: 500
description: 'Plain-language description of the news you want, e.g. "Elon Musk, Tesla,
news for the last 10 days". It is translated into the regular filters below before
the search runs, and the resulting parameters are returned in meta.prompt. Explicit
parameters always win over the prompt. Costs 2 extra points when the wording has not
been parsed before (repeats are served from cache). Available on Basic and above —
on Free and Starter the request fails with 403 ER0706. Errors: ER0706 (plan), ER0800
(length), ER0801 (translation service unavailable), ER0802 (nothing usable in the
prompt).'
page:
type: integer
minimum: 1
default: 1
description: Page number for pagination
per_page:
type: integer
minimum: 1
maximum: 250
default: 100
description: Number of results per page (max 250; the Free plan is capped at 10 and
Starter at 50)
sort.by:
type: string
enum:
- published_at
- relevance
- engagement
- quality
- controversy
- trust
- id
- new
- created_at
- source.rank.opr
- sentiment.overall.score
- sentiment.title.score
- sentiment.body.score
- read_time
- sentences_count
- paragraphs_count
- characters_count
- media.images.count
- media.videos.count
- media.images.width.min
- media.images.width.max
- media.images.height.min
- media.images.height.max
- media_richness
- shares.facebook.min
- shares.facebook.max
- shares.twitter.min
- shares.twitter.max
- shares.reddit.min
- shares.reddit.max
default: published_at
description: Field to sort results by
sort.order:
type: string
enum:
- asc
- desc
default: desc
description: Sort order
article.id:
type: string
description: Comma-separated article IDs (max 5)
example: '12345'
title:
type: string
minLength: 2
maxLength: 100
description: 'Search in article titles. Supports phrase search with proximity: "climate
change"~2. Title search is limited to a 31-day published_at window: without published_at.start
/ published_at.end the last 31 days are searched, a wider explicit range returns ER0110.'
ignore.title:
type: string
minLength: 2
maxLength: 100
description: Exclude articles containing this text in the title
title_starts_with:
type: string
minLength: 2
maxLength: 100
description: Filter articles whose title starts with the given text. Same 31-day window
limit as title
title_ends_with:
type: string
minLength: 2
maxLength: 100
description: Filter articles whose title ends with the given text. Same 31-day window
limit as title
title_pattern:
type: string
minLength: 2
maxLength: 200
description: Filter articles whose title matches the given pattern. Same 31-day window
limit as title
published_at:
type: string
description: 'Exact date (creates 24-hour range). Format: YYYY-MM-DD or ISO 8601'
example: '2025-01-15'
published_at.start:
type: string
description: 'Start of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title
search the range may not exceed 31 days (ER0110)'
example: '2025-01-01'
published_at.end:
type: string
description: 'End of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title
search the range may not exceed 31 days (ER0110)'
example: '2025-01-31'
language.code:
type: string
description: Comma-separated ISO 639-1 language codes (max 3)
example: en
ignore.language.code:
type: string
description: Exclude articles in these languages (comma-separated, max 3)
example: zh,ar
source.country.code:
type: string
description: Filter by source country ISO 3166-1 alpha-2 codes (comma-separated, max
3)
example: us
ignore.source.country.code:
type: string
description: Exclude sources from these countries (comma-separated, max 3)
example: us
source.rank.opr.min:
type: integer
minimum: 0
description: Minimum Open PageRank score
source.rank.opr.max:
type: integer
minimum: 0
description: Maximum Open PageRank score
source.id:
type: string
description: Comma-separated source IDs (max 3)
example: '100'
ignore.source.id:
type: string
description: Exclude these source IDs (comma-separated, max 3)
source.domain:
type: string
description: Comma-separated source domains (max 3)
example: nytimes.com
ignore.source.domain:
type: string
description: Exclude these source domains (comma-separated, max 3)
source.bias:
type: string
description: 'Filter by media bias (comma-separated). Values: left, center, right'
example: left
ignore.source.bias:
type: string
description: 'Exclude sources with this media bias (comma-separated). Values: left,
center, right'
example: right
is_premium_source:
type: integer
enum:
- 0
- 1
description: Filter by premium source status
is_verified_source:
type: integer
enum:
- 0
- 1
description: Filter by verified source status
category.id:
type: string
description: Comma-separated category IDs (max 3)
example: iab-1
ignore.category.id:
type: string
description: Exclude these categories (comma-separated, max 3)
topic.id:
type: string
description: Comma-separated topic IDs (max 3)
example: technology
ignore.topic.id:
type: string
description: Exclude these topics (comma-separated, max 3)
industry.id:
type: string
description: Comma-separated industry IDs (max 3)
example: '1'
ignore.industry.id:
type: string
description: Exclude these industries (comma-separated, max 3)
entity.id:
type: string
description: Comma-separated entity IDs (max 3)
example: '12345'
ignore.entity.id:
type: string
description: Exclude these entity IDs (comma-separated, max 3)
entity.sentiment.polarity:
type: string
enum:
- positive
- negative
- neutral
description: Filter by sentiment polarity toward the entity (combine with entity.id
or *.name; standalone = any entity)
entity.sentiment.score.min:
type: number
minimum: -1
maximum: 1
description: Minimum sentiment score toward the entity
entity.sentiment.score.max:
type: number
minimum: -1
maximum: 1
description: Maximum sentiment score toward the entity
person.name:
type: string
maxLength: 120
description: Filter by person name (comma-separated, max 3)
example: Elon Musk
ignore.person.name:
type: string
maxLength: 120
description: Exclude articles mentioning these persons (comma-separated, max 3)
organization.name:
type: string
maxLength: 120
description: Filter by organization name (comma-separated, max 3)
example: Google
ignore.organization.name:
type: string
maxLength: 120
description: Exclude articles mentioning these organizations (comma-separated, max 3)
location.name:
type: string
maxLength: 120
description: Filter by location name (comma-separated, max 3)
example: New York
ignore.location.name:
type: string
maxLength: 120
description: Exclude articles mentioning these locations (comma-separated, max 3)
brand.name:
type: string
maxLength: 120
description: Filter by brand name (comma-separated, max 3)
ignore.brand.name:
type: string
maxLength: 120
description: Exclude articles mentioning these brands (comma-separated, max 3)
disaster.name:
type: string
maxLength: 120
description: Filter by natural disaster name (comma-separated, max 3)
ignore.disaster.name:
type: string
maxLength: 120
description: Exclude articles mentioning these disasters (comma-separated, max 3)
disease.name:
type: string
maxLength: 120
description: Filter by disease name (comma-separated, max 3)
ignore.disease.name:
type: string
maxLength: 120
description: Exclude articles mentioning these diseases (comma-separated, max 3)
event.name:
type: string
maxLength: 120
description: Filter by event name (comma-separated, max 3)
ignore.event.name:
type: string
maxLength: 120
description: Exclude articles mentioning these events (comma-separated, max 3)
sport.name:
type: string
maxLength: 120
description: Filter by sport name (comma-separated, max 3)
ignore.sport.name:
type: string
maxLength: 120
description: Exclude articles mentioning these sports (comma-separated, max 3)
event.type:
type: string
description: 'Comma-separated event types (max 5). Values: merger-acquisition, ipo,
layoffs, bankruptcy, product-launch, funding-round, earnings, partnership, executive-change,
lawsuit, data-breach, recall, expansion, closure, stock-movement, contract-award,
spin-off, regulatory-action, election, protest, crime, terrorism, accident, policy-change,
scandal, death, award-ceremony, conflict, diplomacy, health-crisis, migration, human-rights,
earthquake, hurricane, flood, wildfire, tornado, tsunami, volcanic-eruption, drought,
climate-event, pollution, wildlife-event, avalanche'
example: ipo
event.category:
type: string
enum:
- business
- society
- environment
description: Filter by event category
ignore.event.type:
type: string
description: Exclude these event types (comma-separated, max 5)
sentiment.overall.score:
type: number
minimum: -1
maximum: 1
description: Exact overall sentiment score
sentiment.overall.score.min:
type: number
minimum: -1
maximum: 1
description: Minimum overall sentiment score
sentiment.overall.score.max:
type: number
minimum: -1
maximum: 1
description: Maximum overall sentiment score
sentiment.overall.polarity:
type: string
enum:
- positive
- negative
- neutral
description: Overall sentiment polarity
sentiment.title.score:
type: number
minimum: -1
maximum: 1
description: Exact title sentiment score
sentiment.title.score.min:
type: number
minimum: -1
maximum: 1
description: Minimum title sentiment score
sentiment.title.score.max:
type: number
minimum: -1
maximum: 1
description: Maximum title sentiment score
sentiment.title.polarity:
type: string
enum:
- positive
- negative
- neutral
description: Title sentiment polarity
sentiment.body.score:
type: number
minimum: -1
maximum: 1
description: Exact body sentiment score
sentiment.body.score.min:
type: number
minimum: -1
maximum: 1
description: Minimum body sentiment score
sentiment.body.score.max:
type: number
minimum: -1
maximum: 1
description: Maximum body sentiment score
sentiment.body.polarity:
type: string
enum:
- positive
- negative
- neutral
description: Body sentiment polarity
sentiment.mixed:
type: integer
enum:
- 0
- 1
description: Filter for mixed sentiment (title polarity != body polarity)
sentiment.consistent:
type: integer
enum:
- 0
- 1
description: Filter for consistent sentiment (title polarity == body polarity)
is_clickbait:
type: integer
enum:
- 0
- 1
description: Filter by clickbait detection
sentiment_gap.min:
type: number
minimum: 0
maximum: 2
description: Minimum sentiment gap between title and body
sentiment_gap.max:
type: number
minimum: 0
maximum: 2
description: Maximum sentiment gap between title and body
media.images.count:
type: integer
minimum: 0
description: Exact number of images
media.images.count.min:
type: integer
minimum: 0
description: Minimum number of images
media.images.count.max:
type: integer
minimum: 0
description: Maximum number of images
media.images.width.min:
type: integer
minimum: 0
description: Minimum image width in pixels
media.images.width.max:
type: integer
minimum: 0
description: Maximum image width in pixels
media.images.height.min:
type: integer
minimum: 0
description: Minimum image height in pixels
media.images.height.max:
type: integer
minimum: 0
description: Maximum image height in pixels
media.videos.count:
type: integer
minimum: 0
description: Exact number of videos
media.videos.count.min:
type: integer
minimum: 0
description: Minimum number of videos
media.videos.count.max:
type: integer
minimum: 0
description: Maximum number of videos
has_image:
type: integer
enum:
- 0
- 1
description: Filter articles with/without images
has_video:
type: integer
enum:
- 0
- 1
description: Filter articles with/without videos
has_hq_images:
type: integer
enum:
- 0
- 1
description: Filter articles with high-quality images (>= 1200px width)
is_media_rich:
type: integer
enum:
- 0
- 1
description: Filter articles with both images and videos
is_landscape_media:
type: integer
enum:
- 0
- 1
description: Filter articles with landscape-oriented media
is_portrait_media:
type: integer
enum:
- 0
- 1
description: Filter articles with portrait-oriented media
has_multiple_images:
type: integer
enum:
- 0
- 1
description: Filter articles with 2+ images
has_fullhd_images:
type: integer
enum:
- 0
- 1
description: Filter articles with Full HD images (>= 1920px width)
has_4k_images:
type: integer
enum:
- 0
- 1
description: Filter articles with 4K images (>= 3840px width)
has_mobile_optimized_images:
type: integer
enum:
- 0
- 1
description: Filter articles with mobile-optimized images (320-800px width)
is_instagram_ready:
type: integer
enum:
- 0
- 1
description: Filter articles with Instagram-ready images (>= 1080px + aspect ratio)
is_twitter_card_ready:
type: integer
enum:
- 0
- 1
description: Filter articles with Twitter Card-ready images (>= 800px + landscape)
has_consistent_image_sizes:
type: integer
enum:
- 0
- 1
description: Filter articles with consistent image dimensions
has_thumbnail:
type: integer
enum:
- 0
- 1
description: Filter articles with thumbnail images (<= 300px width)
has_social_share_image:
type: integer
enum:
- 0
- 1
description: Filter articles with social share images (>= 1200x630px)
has_mixed_media:
type: integer
enum:
- 0
- 1
description: Filter articles with both image and video media types
readability.fk_grade:
type: number
minimum: 0
maximum: 30
description: Exact Flesch-Kincaid grade level
readability.fk_grade.min:
type: number
minimum: 0
maximum: 30
description: Minimum Flesch-Kincaid grade level
readability.fk_grade.max:
type: number
minimum: 0
maximum: 30
description: Maximum Flesch-Kincaid grade level
readability.ease:
type: number
minimum: 0
maximum: 100
description: Exact Flesch Reading Ease score
readability.ease.min:
type: number
minimum: 0
maximum: 100
description: Minimum Flesch Reading Ease score
readability.ease.max:
type: number
minimum: 0
maximum: 100
description: Maximum Flesch Reading Ease score
readability.ari:
type: number
minimum: 0
maximum: 30
description: Exact Automated Readability Index
readability.ari.min:
type: number
minimum: 0
maximum: 30
description: Minimum Automated Readability Index
readability.ari.max:
type: number
minimum: 0
maximum: 30
description: Maximum Automated Readability Index
readability.difficulty:
type: string
enum:
- beginner
- intermediate
- advanced
- expert
description: Difficulty level
readability.audience:
type: string
enum:
- children
- general
- professional
- academic
description: Target audience
readability.age:
type: integer
minimum: 6
maximum: 22
description: Exact reading age
readability.age.min:
type: integer
minimum: 6
maximum: 22
description: Minimum reading age
readability.age.max:
type: integer
minimum: 6
maximum: 22
description: Maximum reading age
is_easy_read:
type: integer
enum:
- 0
- 1
description: Filter for easy-to-read articles (Flesch Reading Ease >= 60)
is_difficult_read:
type: integer
enum:
- 0
- 1
description: Filter for difficult-to-read articles (Flesch Reading Ease < 40)
read_time:
type: integer
minimum: 0
maximum: 1000
description: Exact read time in minutes
read_time.min:
type: integer
minimum: 0
maximum: 1000
description: Minimum read time in minutes
read_time.max:
type: integer
minimum: 0
maximum: 1000
description: Maximum read time in minutes
is_long_read:
type: integer
enum:
- 0
- 1
description: Filter for long reads (>= 5 minutes)
is_short_read:
type: integer
enum:
- 0
- 1
description: Filter for short reads (< 3 minutes)
is_quick_read:
type: integer
enum:
- 0
- 1
description: Filter for quick reads (<= 2 minutes)
is_medium_read:
type: integer
enum:
- 0
- 1
description: Filter for medium-length reads (3-7 minutes)
is_deep_dive:
type: integer
enum:
- 0
- 1
description: Filter for deep dives (>= 10 minutes)
location.bbox:
type: string
description: 'Bounding box: minLat,maxLat,minLng,maxLng'
example: 40.0,41.0,-74.5,-73.5
has_location_geo:
type: integer
enum:
- 0
- 1
description: Filter articles with/without geo-location data
location.lat:
type: number
minimum: -90
maximum: 90
description: Latitude for radius search
location.lng:
type: number
minimum: -180
maximum: 180
description: Longitude for radius search
location.radius:
type: number
exclusiveMinimum: 0
maximum: 20000
description: Search radius in kilometers (requires location.lat and location.lng)
location.radius.min:
type: number
minimum: 0
maximum: 20000
description: Minimum distance from point in km
is_duplicate:
type: integer
enum:
- 0
- 1
description: Filter duplicate/unique articles
is_paywall:
type: integer
enum:
- 0
- 1
description: Filter paywalled articles
is_breaking:
type: integer
enum:
- 0
- 1
description: Filter breaking news articles
is_high_quality:
type: integer
enum:
- 0
- 1
description: Filter high-quality articles (not duplicate, rank >= 5, has images, has
author)
author.id:
type: string
description: Comma-separated author IDs (max 3)
ignore.author.id:
type: string
description: Exclude these author IDs (comma-separated, max 3)
author.name:
type: string
maxLength: 100
description: Filter by author name (comma-separated, max 3)
ignore.author.name:
type: string
maxLength: 100
description: Exclude articles by these authors (comma-separated, max 3)
has_author:
type: integer
enum:
- 0
- 1
description: Filter articles with/without author
facet:
type: string
enum:
- '0'
- '1'
description: Enable faceting
facet.field:
type: string
description: 'Comma-separated facet fields (max 5). Values: source.id, source.country.id,
source.bias, language.id, author.id, category.id, topic.id, industry.id, entity.id,
sentiment.overall.polarity, sentiment.title.polarity, sentiment.body.polarity, sentiment.strength,
is_duplicate, is_free, is_important, media.images.count, media.videos.count, read_time,
content.length, published.year, published.month, published.day_of_week, published.hour,
published.weekday, published.time_of_day'
example: source.id,category.id
facet.limit:
type: integer
minimum: 1
maximum: 100
default: 10
description: Maximum number of facet values per field (max 100)
facet.mincount:
type: integer
minimum: 1
default: 1
description: Minimum count for a facet value to be included
facet.range:
type: string
enum:
- '0'
- '1'
description: Enable range faceting
facet.range.field:
type: string
description: 'Field for range faceting. Values: published_at, sentiment.overall.score,
sentiment.title.score, sentiment.body.score, read_time, source.rank.opr, media.images.count,
media.videos.count'
facet.range.start:
type: string
description: Start value for range faceting (required with facet.range)
facet.range.end:
type: string
description: End value for range faceting (required with facet.range)
facet.range.gap:
type: string
default: +1DAY
description: Gap value for range faceting
hl:
type: string
enum:
- '0'
- '1'
description: Enable highlighting
hl.fl:
type: string
default: title,description
description: 'Comma-separated fields to highlight (max 5). Values: title, description,
body'
example: title,description
hl.fragsize:
type: integer
minimum: 50
maximum: 500
default: 150
description: Size of highlighted fragment in characters (50-500)
hl.snippets:
type: integer
minimum: 1
maximum: 10
default: 3
description: Number of highlighted snippets per field (max 10)
hl.tag.pre:
type: string
description: Opening tag for highlighted text
default:
hl.tag.post:
type: string
description: Closing tag for highlighted text
default:
export:
type: string
enum:
- json
- csv
- tsv
- xml
- rss
- xlsx
- parquet
- jsonl
- ndjson
description: Export format
fl:
type: string
description: Comma-separated list of fields to include in the response
example: id,title,published_at,source.domain
debug:
type: string
enum:
- '0'
- '1'
description: Include user_input in response for debugging
api_key:
type: string
description: API key (alternative to X-API-Key header)
responses:
'200':
description: Successful response with top headlines
content:
application/json:
schema:
description: Successful response with top headlines
type: object
properties:
status:
type: string
enum:
- ok
description: Response status
limit:
type: integer
description: Results per page
path:
type: string
description: Current request URL
page:
type: integer
description: Current page number
has_next_pages:
type: boolean
description: Whether more pages are available
next_page:
type: string
description: URL for the next page (empty if no next page)
has_previous_page:
type: boolean
description: Whether a previous page exists
previous_page:
type: string
description: URL for the previous page (empty if no previous page)
export:
type: object
description: Export format URLs
properties:
json:
type: string
xlsx:
type: string
csv:
type: string
tsv:
type: string
xml:
type: string
rss:
type: string
parquet:
type: string
jsonl:
type: string
request_id:
type: string
description: Unique request identifier
results:
type: array
items:
type: object
properties:
id:
type: integer
description: Unique article ID
href:
type:
- string
- 'null'
description: Original article URL
published_at:
type:
- string
- 'null'
format: date-time
description: Publication date in ISO 8601
title:
type:
- string
- 'null'
description: Article title
description:
type:
- string
- 'null'
description: Article description (plain text)
body:
type:
- string
- 'null'
description: Article body (plain text)
body_html:
type:
- string
- 'null'
description: Article body (HTML)
language:
type: string
description: ISO 639-1 language code
translations:
type: object
description: Machine translations of the article title and description. Always
present; fields stay null for English articles and for languages without a
translation model
properties:
en:
type: object
properties:
title:
type:
- string
- 'null'
description: Title translated to English
description:
type:
- string
- 'null'
description: Description translated to English (plain text)
author:
type: object
properties:
id:
type:
- integer
- 'null'
description: Author ID
name:
type: string
description: Author name
image:
type: string
description: Main article image URL
categories:
type: array
items:
type: object
properties:
id:
type: integer
description: Category ID
name:
type: string
description: Category name
score:
type: number
description: Relevance score
taxonomy:
type: string
description: Taxonomy identifier
links:
type: object
properties:
self:
type: string
description: Link to category endpoint
topics:
type: array
items:
type: object
properties:
id:
type: string
description: Topic ID
name:
type: string
description: Topic name
score:
type: number
description: Relevance score
links:
type: object
properties:
self:
type: string
description: Link to topic endpoint
industries:
type: array
items:
type: object
properties:
id:
type: integer
description: Industry ID
name:
type: string
description: Industry name
links:
type: object
properties:
self:
type: string
description: Link to industry endpoint
entities:
type: array
items:
type: object
properties:
id:
type: integer
description: Entity ID
name:
type: string
description: Entity name
type:
type: string
enum:
- person
- location
- organization
- brand
- product
- natural-disaster
- disease
- event
- sport
- unknown
description: Entity type
frequency:
type: integer
description: Number of mentions in the article
sentiment:
type: object
description: Sentiment toward this entity (aggregated across its mentions)
properties:
score:
type: number
description: Entity sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Entity sentiment polarity
mentions:
type: object
description: Per-mention polarity breakdown
properties:
positive:
type: integer
neutral:
type: integer
negative:
type: integer
title:
type: object
properties:
pos:
type: array
items:
type: object
properties:
start:
type: integer
description: Start character offset
end:
type: integer
description: End character offset
description: Mention positions in title
body:
type: object
properties:
pos:
type: array
items:
type: object
properties:
start:
type: integer
description: Start character offset
end:
type: integer
description: End character offset
description: Mention positions in body
links:
type: object
properties:
self:
type: string
description: Link to entity endpoint
wikipedia:
type: string
description: Wikipedia URL
wikidata:
type: string
description: Wikidata URL
metadata:
type: object
description: Additional entity metadata (varies by entity type)
additionalProperties: true
locations_mentioned:
type: array
items:
type: object
properties:
name:
type: string
description: Location name
country:
type: string
description: Country code
lat:
type:
- number
- 'null'
description: Latitude
lng:
type:
- number
- 'null'
description: Longitude
type:
type: string
description: Location type
source:
type: object
properties:
id:
type:
- integer
- 'null'
description: Source ID
domain:
type: string
description: Source domain
home_page_url:
type: string
description: Source home page URL
type:
type: string
description: Source type
bias:
type: string
description: Media bias (left, center, right)
rankings:
type: object
properties:
opr:
type: integer
description: Open PageRank score
location:
type: object
properties:
country_name:
type: string
description: Source country name
country_code:
type: string
description: Source country ISO code
favicon:
type: string
description: Source favicon URL
sentiment:
type: object
properties:
overall:
type: object
properties:
score:
type: number
description: Sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Sentiment polarity
title:
type: object
properties:
score:
type: number
description: Sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Sentiment polarity
body:
type: object
properties:
score:
type: number
description: Sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Sentiment polarity
summary:
type: array
items:
type: object
properties:
sentence:
type: string
description: Summary sentence
sentiment:
type: object
properties:
score:
type: number
description: Sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Sentiment polarity
readability:
type: object
properties:
flesch_kincaid_grade:
type: number
description: Flesch-Kincaid grade level
flesch_reading_ease:
type: number
description: Flesch Reading Ease score (0-100)
automated_readability_index:
type: number
description: Automated Readability Index
difficulty_level:
type: string
enum:
- beginner
- intermediate
- advanced
- expert
- unknown
description: Difficulty level
target_audience:
type: string
enum:
- children
- general
- professional
- academic
- unknown
description: Target audience
reading_age:
type: number
description: Estimated reading age
avg_words_per_sentence:
type: number
description: Average words per sentence
avg_syllables_per_word:
type: number
description: Average syllables per word
keywords:
type: array
items:
type: string
description: Article keywords
links:
type: array
items:
type: object
properties:
url:
type: string
description: Link URL
type:
type: string
description: Link type
media:
type: array
items:
type: object
properties:
url:
type: string
description: Media URL
type:
type: string
description: Media type (image, video, etc.)
shares:
type: object
properties:
total:
type: integer
description: Total social shares
facebook:
type: integer
description: Facebook shares
twitter:
type: integer
description: Twitter/X shares
reddit:
type: integer
description: Reddit shares
story:
type: object
properties:
id:
type: integer
description: Story ID
uri:
type: string
description: Story endpoint URI
is_duplicate:
type: boolean
description: Whether this is a duplicate article
is_free:
type: boolean
description: Whether the article is freely accessible
is_breaking:
type: boolean
description: Whether this is breaking news
read_time:
type: integer
description: Estimated read time in minutes
sentences_count:
type: integer
description: Number of sentences
paragraphs_count:
type: integer
description: Number of paragraphs
words_count:
type: integer
description: Number of words
characters_count:
type: integer
description: Number of characters
description: Array of articles
facets:
type: object
description: Facet results (present when facet.field is specified)
additionalProperties: true
highlighting:
type: object
description: Highlighting results (present when hl=1)
additionalProperties: true
headlines:
type: array
description: Headlines (present in some responses)
items:
type: object
additionalProperties: true
meta:
type: object
description: 'Additional metadata. Present only when there is something to report
about how the request was handled: `prompt` (the request used the prompt parameter)
and/or `warnings` (the query was silently narrowed, e.g. ER0366 clamping a title
search to the last 31 days).'
properties:
prompt:
type: object
description: How the `prompt` parameter was translated into filters. Returned
by every JSON response to a request that used it (the SSE stream has no JSON
envelope, so it carries none).
properties:
text:
type: string
description: The prompt as it was parsed, trimmed
applied:
type: object
description: Parameters the prompt was translated into — the request that
actually ran
additionalProperties:
type: string
ignored:
type: array
description: Values understood but not used
items:
type: object
properties:
field:
type: string
description: Parameter that was not applied
value:
type: string
description: Value the prompt produced for it
reason:
type: string
enum:
- not_found
- explicit_param
- unsupported_on_endpoint
- invalid_date
- title_too_long
- title_window_clamped
description: Why the value was not applied
cached:
type: boolean
description: true when this wording had been parsed before, so no parse fee
was charged
warnings:
type: array
description: Non-fatal notices — the request still returned HTTP 200
items:
type: object
properties:
code:
type: string
description: Warning code, e.g. ER0366
message:
type: string
description: Human-readable explanation
links:
type: object
additionalProperties: true
additionalProperties: true
user_input:
type: object
description: Debug info — original request parameters (present when debug=1)
additionalProperties: true
required:
- status
- limit
- path
- page
- has_next_pages
- has_previous_page
- request_id
- results
example:
status: ok
limit: 50
path: /v1/news/everything
page: 1
has_next_pages: true
next_page: /v1/news/everything?page=2
has_previous_page: false
previous_page: ''
export:
json: /v1/news/everything?export=json
csv: /v1/news/everything?export=csv
rss: /v1/news/everything?export=rss
request_id: req_abc123def456
results:
- id: 84029371
href: https://example.com/article/spacex-launch
published_at: '2026-03-23T14:30:00Z'
title: SpaceX Successfully Launches New Starship Prototype
description: SpaceX completed another successful test flight of its Starship rocket...
language: en
author:
id: 1024
name: Jane Smith
image: https://example.com/images/starship.jpg
categories:
- id: 201
name: Science & Technology
score: 0.95
taxonomy: iptc_mediatopics
topics:
- id: space-exploration
name: Space Exploration
score: 0.92
industries:
- id: 88
name: Aerospace & Defense
entities:
- id: 5012
name: SpaceX
type: organization
frequency: 8
links:
wikipedia: https://en.wikipedia.org/wiki/SpaceX
- id: 3401
name: Elon Musk
type: person
frequency: 3
links:
wikipedia: https://en.wikipedia.org/wiki/Elon_Musk
source:
id: 7823
domain: reuters.com
home_page_url: https://www.reuters.com
type: news_agency
location:
country_name: United States
country_code: us
rankings:
opr: 8
sentiment:
overall:
score: 0.65
polarity: positive
title:
score: 0.72
polarity: positive
body:
score: 0.61
polarity: positive
readability:
flesch_kincaid_grade: 10.2
flesch_reading_ease: 52.3
difficulty_level: intermediate
target_audience: general
keywords:
- spacex
- starship
- rocket
- launch
is_duplicate: false
is_breaking: true
read_time: 4
words_count: 847
'401':
description: Authentication error
content:
application/json:
schema:
description: Authentication error
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
description: Rate limit exceeded
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
/v1/news/local:
post:
summary: Local news around a point
tags:
- News
description: Returns news articles whose mentioned locations fall within `radius` km of `lat`/`lng`,
sorted by proximity. Each article is enriched with `distance_km` and `nearest_location`. Supports
the same filters as `/v1/news/everything`. Optionally returns a `local_insights` dashboard (mood,
hotspots, extracted events, top entities, media-bias split, top sources, timeline) via the `insights`
parameter. Costs 1 point + 1 per requested insight block.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
lat:
type: number
minimum: -90
maximum: 90
description: Latitude of the search center (required unless `place` is given)
lng:
type: number
minimum: -180
maximum: 180
description: Longitude of the search center (required unless `place` is given)
place:
type: string
description: Place name to geocode into the search center instead of lat/lng (e.g. `Berlin`).
Resolved heuristically against the entity graph; ambiguous names are matched to the
best candidate — add `country` or pass `lat`/`lng` for precision. Explicit lat/lng
take precedence over `place`.
example: Berlin
country:
type: string
description: ISO 3166-1 alpha-2 code to disambiguate `place` (e.g. `de`)
example: de
radius:
type: number
exclusiveMinimum: 0
maximum: 20000
default: 50
description: Search radius in kilometers (default 50, max 20000)
sort:
type: string
enum:
- distance
- published_at
- relevance
default: distance
description: 'Sort order: nearest first (`distance`), newest first (`published_at`),
or `relevance` (blends proximity + source authority + recency + breaking; adds `relevance_score`
to each article)'
ranking:
type: string
enum:
- balanced
- proximity
- authority
- fresh
default: balanced
description: 'Relevance weighting preset (only when sort=relevance): balanced, proximity
(closer wins), authority (bigger sources win), fresh (recency wins). Override individual
weights with w.* params.'
w.distance:
type: number
minimum: 0
description: Relevance weight for proximity (overrides preset)
w.opr:
type: number
minimum: 0
description: Relevance weight for source authority (overrides preset)
w.recency:
type: number
minimum: 0
description: Relevance weight for recency (overrides preset)
w.important:
type: number
minimum: 0
description: Relevance weight for breaking/importance (overrides preset)
insights:
type: string
description: 'Comma-separated local intelligence blocks to compute over the radius.
Values: mood, hotspots, events, entities, bias, sources, timeline, top_categories,
top_topics, breaking, velocity, movers. `velocity`/`movers` use rolling time windows
and are most accurate without an explicit published_at filter. Each block costs 1
additional point.'
example: top_categories,breaking,movers
prompt:
type: string
minLength: 3
maxLength: 500
description: 'Plain-language description of the news you want, e.g. "Elon Musk, Tesla,
news for the last 10 days". It is translated into the regular filters below before
the search runs, and the resulting parameters are returned in meta.prompt. Explicit
parameters always win over the prompt. Costs 2 extra points when the wording has not
been parsed before (repeats are served from cache). Available on Basic and above —
on Free and Starter the request fails with 403 ER0706. Errors: ER0706 (plan), ER0800
(length), ER0801 (translation service unavailable), ER0802 (nothing usable in the
prompt).'
page:
type: integer
minimum: 1
default: 1
description: Page number for pagination
per_page:
type: integer
minimum: 1
maximum: 250
default: 100
description: Number of results per page (max 250; the Free plan is capped at 10 and
Starter at 50)
sort.by:
type: string
enum:
- published_at
- relevance
- engagement
- quality
- controversy
- trust
- id
- new
- created_at
- source.rank.opr
- sentiment.overall.score
- sentiment.title.score
- sentiment.body.score
- read_time
- sentences_count
- paragraphs_count
- characters_count
- media.images.count
- media.videos.count
- media.images.width.min
- media.images.width.max
- media.images.height.min
- media.images.height.max
- media_richness
- shares.facebook.min
- shares.facebook.max
- shares.twitter.min
- shares.twitter.max
- shares.reddit.min
- shares.reddit.max
default: published_at
description: Field to sort results by
sort.order:
type: string
enum:
- asc
- desc
default: desc
description: Sort order
article.id:
type: string
description: Comma-separated article IDs (max 5)
example: '12345'
title:
type: string
minLength: 2
maxLength: 100
description: 'Search in article titles. Supports phrase search with proximity: "climate
change"~2. Title search is limited to a 31-day published_at window: without published_at.start
/ published_at.end the last 31 days are searched, a wider explicit range returns ER0110.'
ignore.title:
type: string
minLength: 2
maxLength: 100
description: Exclude articles containing this text in the title
title_starts_with:
type: string
minLength: 2
maxLength: 100
description: Filter articles whose title starts with the given text. Same 31-day window
limit as title
title_ends_with:
type: string
minLength: 2
maxLength: 100
description: Filter articles whose title ends with the given text. Same 31-day window
limit as title
title_pattern:
type: string
minLength: 2
maxLength: 200
description: Filter articles whose title matches the given pattern. Same 31-day window
limit as title
published_at:
type: string
description: 'Exact date (creates 24-hour range). Format: YYYY-MM-DD or ISO 8601'
example: '2025-01-15'
published_at.start:
type: string
description: 'Start of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title
search the range may not exceed 31 days (ER0110)'
example: '2025-01-01'
published_at.end:
type: string
description: 'End of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title
search the range may not exceed 31 days (ER0110)'
example: '2025-01-31'
language.code:
type: string
description: Comma-separated ISO 639-1 language codes (max 3)
example: en
ignore.language.code:
type: string
description: Exclude articles in these languages (comma-separated, max 3)
example: zh,ar
source.country.code:
type: string
description: Filter by source country ISO 3166-1 alpha-2 codes (comma-separated, max
3)
example: us
ignore.source.country.code:
type: string
description: Exclude sources from these countries (comma-separated, max 3)
example: us
source.rank.opr.min:
type: integer
minimum: 0
description: Minimum Open PageRank score
source.rank.opr.max:
type: integer
minimum: 0
description: Maximum Open PageRank score
source.id:
type: string
description: Comma-separated source IDs (max 3)
example: '100'
ignore.source.id:
type: string
description: Exclude these source IDs (comma-separated, max 3)
source.domain:
type: string
description: Comma-separated source domains (max 3)
example: nytimes.com
ignore.source.domain:
type: string
description: Exclude these source domains (comma-separated, max 3)
source.bias:
type: string
description: 'Filter by media bias (comma-separated). Values: left, center, right'
example: left
ignore.source.bias:
type: string
description: 'Exclude sources with this media bias (comma-separated). Values: left,
center, right'
example: right
is_premium_source:
type: integer
enum:
- 0
- 1
description: Filter by premium source status
is_verified_source:
type: integer
enum:
- 0
- 1
description: Filter by verified source status
category.id:
type: string
description: Comma-separated category IDs (max 3)
example: iab-1
ignore.category.id:
type: string
description: Exclude these categories (comma-separated, max 3)
topic.id:
type: string
description: Comma-separated topic IDs (max 3)
example: technology
ignore.topic.id:
type: string
description: Exclude these topics (comma-separated, max 3)
industry.id:
type: string
description: Comma-separated industry IDs (max 3)
example: '1'
ignore.industry.id:
type: string
description: Exclude these industries (comma-separated, max 3)
entity.id:
type: string
description: Comma-separated entity IDs (max 3)
example: '12345'
ignore.entity.id:
type: string
description: Exclude these entity IDs (comma-separated, max 3)
entity.sentiment.polarity:
type: string
enum:
- positive
- negative
- neutral
description: Filter by sentiment polarity toward the entity (combine with entity.id
or *.name; standalone = any entity)
entity.sentiment.score.min:
type: number
minimum: -1
maximum: 1
description: Minimum sentiment score toward the entity
entity.sentiment.score.max:
type: number
minimum: -1
maximum: 1
description: Maximum sentiment score toward the entity
person.name:
type: string
maxLength: 120
description: Filter by person name (comma-separated, max 3)
example: Elon Musk
ignore.person.name:
type: string
maxLength: 120
description: Exclude articles mentioning these persons (comma-separated, max 3)
organization.name:
type: string
maxLength: 120
description: Filter by organization name (comma-separated, max 3)
example: Google
ignore.organization.name:
type: string
maxLength: 120
description: Exclude articles mentioning these organizations (comma-separated, max 3)
location.name:
type: string
maxLength: 120
description: Filter by location name (comma-separated, max 3)
example: New York
ignore.location.name:
type: string
maxLength: 120
description: Exclude articles mentioning these locations (comma-separated, max 3)
brand.name:
type: string
maxLength: 120
description: Filter by brand name (comma-separated, max 3)
ignore.brand.name:
type: string
maxLength: 120
description: Exclude articles mentioning these brands (comma-separated, max 3)
disaster.name:
type: string
maxLength: 120
description: Filter by natural disaster name (comma-separated, max 3)
ignore.disaster.name:
type: string
maxLength: 120
description: Exclude articles mentioning these disasters (comma-separated, max 3)
disease.name:
type: string
maxLength: 120
description: Filter by disease name (comma-separated, max 3)
ignore.disease.name:
type: string
maxLength: 120
description: Exclude articles mentioning these diseases (comma-separated, max 3)
event.name:
type: string
maxLength: 120
description: Filter by event name (comma-separated, max 3)
ignore.event.name:
type: string
maxLength: 120
description: Exclude articles mentioning these events (comma-separated, max 3)
sport.name:
type: string
maxLength: 120
description: Filter by sport name (comma-separated, max 3)
ignore.sport.name:
type: string
maxLength: 120
description: Exclude articles mentioning these sports (comma-separated, max 3)
event.type:
type: string
description: 'Comma-separated event types (max 5). Values: merger-acquisition, ipo,
layoffs, bankruptcy, product-launch, funding-round, earnings, partnership, executive-change,
lawsuit, data-breach, recall, expansion, closure, stock-movement, contract-award,
spin-off, regulatory-action, election, protest, crime, terrorism, accident, policy-change,
scandal, death, award-ceremony, conflict, diplomacy, health-crisis, migration, human-rights,
earthquake, hurricane, flood, wildfire, tornado, tsunami, volcanic-eruption, drought,
climate-event, pollution, wildlife-event, avalanche'
example: ipo
event.category:
type: string
enum:
- business
- society
- environment
description: Filter by event category
ignore.event.type:
type: string
description: Exclude these event types (comma-separated, max 5)
sentiment.overall.score:
type: number
minimum: -1
maximum: 1
description: Exact overall sentiment score
sentiment.overall.score.min:
type: number
minimum: -1
maximum: 1
description: Minimum overall sentiment score
sentiment.overall.score.max:
type: number
minimum: -1
maximum: 1
description: Maximum overall sentiment score
sentiment.overall.polarity:
type: string
enum:
- positive
- negative
- neutral
description: Overall sentiment polarity
sentiment.title.score:
type: number
minimum: -1
maximum: 1
description: Exact title sentiment score
sentiment.title.score.min:
type: number
minimum: -1
maximum: 1
description: Minimum title sentiment score
sentiment.title.score.max:
type: number
minimum: -1
maximum: 1
description: Maximum title sentiment score
sentiment.title.polarity:
type: string
enum:
- positive
- negative
- neutral
description: Title sentiment polarity
sentiment.body.score:
type: number
minimum: -1
maximum: 1
description: Exact body sentiment score
sentiment.body.score.min:
type: number
minimum: -1
maximum: 1
description: Minimum body sentiment score
sentiment.body.score.max:
type: number
minimum: -1
maximum: 1
description: Maximum body sentiment score
sentiment.body.polarity:
type: string
enum:
- positive
- negative
- neutral
description: Body sentiment polarity
sentiment.mixed:
type: integer
enum:
- 0
- 1
description: Filter for mixed sentiment (title polarity != body polarity)
sentiment.consistent:
type: integer
enum:
- 0
- 1
description: Filter for consistent sentiment (title polarity == body polarity)
is_clickbait:
type: integer
enum:
- 0
- 1
description: Filter by clickbait detection
sentiment_gap.min:
type: number
minimum: 0
maximum: 2
description: Minimum sentiment gap between title and body
sentiment_gap.max:
type: number
minimum: 0
maximum: 2
description: Maximum sentiment gap between title and body
media.images.count:
type: integer
minimum: 0
description: Exact number of images
media.images.count.min:
type: integer
minimum: 0
description: Minimum number of images
media.images.count.max:
type: integer
minimum: 0
description: Maximum number of images
media.images.width.min:
type: integer
minimum: 0
description: Minimum image width in pixels
media.images.width.max:
type: integer
minimum: 0
description: Maximum image width in pixels
media.images.height.min:
type: integer
minimum: 0
description: Minimum image height in pixels
media.images.height.max:
type: integer
minimum: 0
description: Maximum image height in pixels
media.videos.count:
type: integer
minimum: 0
description: Exact number of videos
media.videos.count.min:
type: integer
minimum: 0
description: Minimum number of videos
media.videos.count.max:
type: integer
minimum: 0
description: Maximum number of videos
has_image:
type: integer
enum:
- 0
- 1
description: Filter articles with/without images
has_video:
type: integer
enum:
- 0
- 1
description: Filter articles with/without videos
has_hq_images:
type: integer
enum:
- 0
- 1
description: Filter articles with high-quality images (>= 1200px width)
is_media_rich:
type: integer
enum:
- 0
- 1
description: Filter articles with both images and videos
is_landscape_media:
type: integer
enum:
- 0
- 1
description: Filter articles with landscape-oriented media
is_portrait_media:
type: integer
enum:
- 0
- 1
description: Filter articles with portrait-oriented media
has_multiple_images:
type: integer
enum:
- 0
- 1
description: Filter articles with 2+ images
has_fullhd_images:
type: integer
enum:
- 0
- 1
description: Filter articles with Full HD images (>= 1920px width)
has_4k_images:
type: integer
enum:
- 0
- 1
description: Filter articles with 4K images (>= 3840px width)
has_mobile_optimized_images:
type: integer
enum:
- 0
- 1
description: Filter articles with mobile-optimized images (320-800px width)
is_instagram_ready:
type: integer
enum:
- 0
- 1
description: Filter articles with Instagram-ready images (>= 1080px + aspect ratio)
is_twitter_card_ready:
type: integer
enum:
- 0
- 1
description: Filter articles with Twitter Card-ready images (>= 800px + landscape)
has_consistent_image_sizes:
type: integer
enum:
- 0
- 1
description: Filter articles with consistent image dimensions
has_thumbnail:
type: integer
enum:
- 0
- 1
description: Filter articles with thumbnail images (<= 300px width)
has_social_share_image:
type: integer
enum:
- 0
- 1
description: Filter articles with social share images (>= 1200x630px)
has_mixed_media:
type: integer
enum:
- 0
- 1
description: Filter articles with both image and video media types
readability.fk_grade:
type: number
minimum: 0
maximum: 30
description: Exact Flesch-Kincaid grade level
readability.fk_grade.min:
type: number
minimum: 0
maximum: 30
description: Minimum Flesch-Kincaid grade level
readability.fk_grade.max:
type: number
minimum: 0
maximum: 30
description: Maximum Flesch-Kincaid grade level
readability.ease:
type: number
minimum: 0
maximum: 100
description: Exact Flesch Reading Ease score
readability.ease.min:
type: number
minimum: 0
maximum: 100
description: Minimum Flesch Reading Ease score
readability.ease.max:
type: number
minimum: 0
maximum: 100
description: Maximum Flesch Reading Ease score
readability.ari:
type: number
minimum: 0
maximum: 30
description: Exact Automated Readability Index
readability.ari.min:
type: number
minimum: 0
maximum: 30
description: Minimum Automated Readability Index
readability.ari.max:
type: number
minimum: 0
maximum: 30
description: Maximum Automated Readability Index
readability.difficulty:
type: string
enum:
- beginner
- intermediate
- advanced
- expert
description: Difficulty level
readability.audience:
type: string
enum:
- children
- general
- professional
- academic
description: Target audience
readability.age:
type: integer
minimum: 6
maximum: 22
description: Exact reading age
readability.age.min:
type: integer
minimum: 6
maximum: 22
description: Minimum reading age
readability.age.max:
type: integer
minimum: 6
maximum: 22
description: Maximum reading age
is_easy_read:
type: integer
enum:
- 0
- 1
description: Filter for easy-to-read articles (Flesch Reading Ease >= 60)
is_difficult_read:
type: integer
enum:
- 0
- 1
description: Filter for difficult-to-read articles (Flesch Reading Ease < 40)
read_time:
type: integer
minimum: 0
maximum: 1000
description: Exact read time in minutes
read_time.min:
type: integer
minimum: 0
maximum: 1000
description: Minimum read time in minutes
read_time.max:
type: integer
minimum: 0
maximum: 1000
description: Maximum read time in minutes
is_long_read:
type: integer
enum:
- 0
- 1
description: Filter for long reads (>= 5 minutes)
is_short_read:
type: integer
enum:
- 0
- 1
description: Filter for short reads (< 3 minutes)
is_quick_read:
type: integer
enum:
- 0
- 1
description: Filter for quick reads (<= 2 minutes)
is_medium_read:
type: integer
enum:
- 0
- 1
description: Filter for medium-length reads (3-7 minutes)
is_deep_dive:
type: integer
enum:
- 0
- 1
description: Filter for deep dives (>= 10 minutes)
location.bbox:
type: string
description: 'Bounding box: minLat,maxLat,minLng,maxLng'
example: 40.0,41.0,-74.5,-73.5
has_location_geo:
type: integer
enum:
- 0
- 1
description: Filter articles with/without geo-location data
location.lat:
type: number
minimum: -90
maximum: 90
description: Latitude for radius search
location.lng:
type: number
minimum: -180
maximum: 180
description: Longitude for radius search
location.radius:
type: number
exclusiveMinimum: 0
maximum: 20000
description: Search radius in kilometers (requires location.lat and location.lng)
location.radius.min:
type: number
minimum: 0
maximum: 20000
description: Minimum distance from point in km
is_duplicate:
type: integer
enum:
- 0
- 1
description: Filter duplicate/unique articles
is_paywall:
type: integer
enum:
- 0
- 1
description: Filter paywalled articles
is_breaking:
type: integer
enum:
- 0
- 1
description: Filter breaking news articles
is_high_quality:
type: integer
enum:
- 0
- 1
description: Filter high-quality articles (not duplicate, rank >= 5, has images, has
author)
author.id:
type: string
description: Comma-separated author IDs (max 3)
ignore.author.id:
type: string
description: Exclude these author IDs (comma-separated, max 3)
author.name:
type: string
maxLength: 100
description: Filter by author name (comma-separated, max 3)
ignore.author.name:
type: string
maxLength: 100
description: Exclude articles by these authors (comma-separated, max 3)
has_author:
type: integer
enum:
- 0
- 1
description: Filter articles with/without author
facet:
type: string
enum:
- '0'
- '1'
description: Enable faceting
facet.field:
type: string
description: 'Comma-separated facet fields (max 5). Values: source.id, source.country.id,
source.bias, language.id, author.id, category.id, topic.id, industry.id, entity.id,
sentiment.overall.polarity, sentiment.title.polarity, sentiment.body.polarity, sentiment.strength,
is_duplicate, is_free, is_important, media.images.count, media.videos.count, read_time,
content.length, published.year, published.month, published.day_of_week, published.hour,
published.weekday, published.time_of_day'
example: source.id,category.id
facet.limit:
type: integer
minimum: 1
maximum: 100
default: 10
description: Maximum number of facet values per field (max 100)
facet.mincount:
type: integer
minimum: 1
default: 1
description: Minimum count for a facet value to be included
facet.range:
type: string
enum:
- '0'
- '1'
description: Enable range faceting
facet.range.field:
type: string
description: 'Field for range faceting. Values: published_at, sentiment.overall.score,
sentiment.title.score, sentiment.body.score, read_time, source.rank.opr, media.images.count,
media.videos.count'
facet.range.start:
type: string
description: Start value for range faceting (required with facet.range)
facet.range.end:
type: string
description: End value for range faceting (required with facet.range)
facet.range.gap:
type: string
default: +1DAY
description: Gap value for range faceting
hl:
type: string
enum:
- '0'
- '1'
description: Enable highlighting
hl.fl:
type: string
default: title,description
description: 'Comma-separated fields to highlight (max 5). Values: title, description,
body'
example: title,description
hl.fragsize:
type: integer
minimum: 50
maximum: 500
default: 150
description: Size of highlighted fragment in characters (50-500)
hl.snippets:
type: integer
minimum: 1
maximum: 10
default: 3
description: Number of highlighted snippets per field (max 10)
hl.tag.pre:
type: string
description: Opening tag for highlighted text
default:
hl.tag.post:
type: string
description: Closing tag for highlighted text
default:
export:
type: string
enum:
- json
- csv
- tsv
- xml
- rss
- xlsx
- parquet
- jsonl
- ndjson
description: Export format
fl:
type: string
description: Comma-separated list of fields to include in the response
example: id,title,published_at,source.domain
debug:
type: string
enum:
- '0'
- '1'
description: Include user_input in response for debugging
api_key:
type: string
description: API key (alternative to X-API-Key header)
responses:
'200':
description: Articles near the point with optional local insights
content:
application/json:
schema:
description: Articles near the point with optional local insights
type: object
properties:
status:
type: string
enum:
- ok
query:
type: object
properties:
lat:
type: number
lng:
type: number
radius_km:
type: number
place:
type: string
description: Resolved place name (only when `place` was used)
resolved_entity_id:
type:
- integer
- 'null'
description: Entity id the place was geocoded to
results:
type: array
items:
type: object
properties:
id:
type: integer
title:
type:
- string
- 'null'
published_at:
type:
- string
- 'null'
distance_km:
type:
- number
- 'null'
description: Distance to the nearest location, km
relevance_score:
type:
- number
- 'null'
description: Composite relevance (only when sort=relevance)
nearest_location:
type:
- object
- 'null'
properties:
entity_id:
type:
- integer
- 'null'
name:
type: string
lat:
type:
- number
- 'null'
lng:
type:
- number
- 'null'
country:
type: string
local_insights:
type: object
description: Present only when `insights` is requested
properties:
mood:
type: object
properties:
avg_sentiment:
type:
- number
- 'null'
distribution:
type: object
properties:
positive:
type: integer
neutral:
type: integer
negative:
type: integer
hotspots:
type: array
items:
type: object
properties:
lat:
type: number
lng:
type: number
count:
type: integer
top_events:
type: array
items:
type: object
properties:
type:
type: string
category:
type:
- string
- 'null'
count:
type: integer
avg_sentiment:
type:
- number
- 'null'
top_entities:
type: array
items:
type: object
properties:
id:
type:
- integer
- 'null'
name:
type:
- string
- 'null'
type_id:
type:
- integer
- 'null'
count:
type: integer
bias_split:
type: object
additionalProperties:
type: object
properties:
count:
type: integer
avg_sentiment:
type:
- number
- 'null'
top_sources:
type: array
items:
type: object
properties:
id:
type: integer
domain:
type:
- string
- 'null'
bias:
type:
- string
- 'null'
opr:
type:
- integer
- 'null'
count:
type: integer
timeline:
type: object
additionalProperties:
type: integer
top_categories:
type: array
items:
type: object
properties:
id: {}
name:
type:
- string
- 'null'
count:
type: integer
top_topics:
type: array
items:
type: object
properties:
id: {}
name:
type:
- string
- 'null'
count:
type: integer
breaking:
type: object
properties:
count:
type: integer
share:
type: number
description: Percentage of breaking articles
velocity:
type: object
properties:
articles_per_hour:
type:
- number
- 'null'
window_hours:
type: integer
movers:
type: array
description: Entities/topics accelerating vs their 14-day baseline
items:
type: object
properties:
type:
type: string
enum:
- entity
- topic
id: {}
name:
type:
- string
- 'null'
count_now:
type: integer
count_baseline:
type: integer
growth_pct:
type:
- number
- 'null'
total:
type: integer
description: Exact number of matching articles in radius
ranking_weights:
type: object
description: Effective relevance weights (only when sort=relevance)
properties:
distance:
type: number
opr:
type: number
recency:
type: number
important:
type: number
request_id:
type:
- string
- 'null'
example:
status: ok
query:
lat: 52.52
lng: 13.4
radius_km: 50
results:
- id: 88412091
title: Berlin transit strike enters second day
published_at: '2026-05-22T07:10:00.000Z'
distance_km: 1.83
nearest_location:
entity_id: 1234
name: Berlin Mitte
lat: 52.52
lng: 13.4
country: de
local_insights:
mood:
avg_sentiment: -0.21
distribution:
positive: 41
neutral: 88
negative: 132
top_events:
- type: protest
category: society
count: 23
avg_sentiment: -0.38
top_entities:
- id: 567
name: Kai Wegner
type_id: 1
count: 19
bias_split:
left:
count: 88
avg_sentiment: -0.18
center:
count: 154
avg_sentiment: -0.2
right:
count: 19
avg_sentiment: -0.41
request_id: req_abc123def456
'400':
description: Invalid request (missing/invalid lat, lng, radius or insights)
content:
application/json:
schema:
description: Invalid request (missing/invalid lat, lng, radius or insights)
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
'401':
description: Authentication error
content:
application/json:
schema:
description: Authentication error
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
description: Rate limit exceeded
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
/v1/news/event-types:
get:
summary: List valid event types
tags:
- Reference
description: Returns every valid value for the `event.type` and `event.category` filters. Use `event_types[].code`
in the `event.type` / `ignore.event.type` filters and `categories[]` in the `event.category` filter.
responses:
'200':
description: Valid event types and the categories they belong to
content:
application/json:
schema:
description: Valid event types and the categories they belong to
type: object
properties:
status:
type: string
description: ok
categories:
type: array
items:
type: string
description: Valid values for the event.category filter
event_types:
type: array
items:
type: object
properties:
code:
type: string
description: Valid value for the event.type filter
category:
type: string
description: Category this event type belongs to
example:
status: ok
categories:
- business
- society
- environment
event_types:
- code: ipo
category: business
- code: layoffs
category: business
- code: election
category: society
- code: earthquake
category: environment
'401':
description: Authentication error
content:
application/json:
schema:
description: Authentication error
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
/v1/news/story/{articleId}:
post:
summary: Get related articles for a story
tags:
- News
description: Returns articles related to a given article ID. Finds similar articles based on title
similarity. Supports the same filtering, faceting, highlighting, and export options as /v1/news/everything.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
page:
type: integer
minimum: 1
default: 1
description: Page number for pagination
per_page:
type: integer
minimum: 1
maximum: 250
default: 100
description: Number of results per page (max 250; the Free plan is capped at 10 and
Starter at 50)
sort.by:
type: string
enum:
- published_at
- relevance
- engagement
- quality
- controversy
- trust
- id
- new
- created_at
- source.rank.opr
- sentiment.overall.score
- sentiment.title.score
- sentiment.body.score
- read_time
- sentences_count
- paragraphs_count
- characters_count
- media.images.count
- media.videos.count
- media.images.width.min
- media.images.width.max
- media.images.height.min
- media.images.height.max
- media_richness
- shares.facebook.min
- shares.facebook.max
- shares.twitter.min
- shares.twitter.max
- shares.reddit.min
- shares.reddit.max
default: published_at
description: Field to sort results by
sort.order:
type: string
enum:
- asc
- desc
default: desc
description: Sort order
article.id:
type: string
description: Comma-separated article IDs (max 5)
example: '12345'
title:
type: string
minLength: 2
maxLength: 100
description: 'Search in article titles. Supports phrase search with proximity: "climate
change"~2. Title search is limited to a 31-day published_at window: without published_at.start
/ published_at.end the last 31 days are searched, a wider explicit range returns ER0110.'
ignore.title:
type: string
minLength: 2
maxLength: 100
description: Exclude articles containing this text in the title
title_starts_with:
type: string
minLength: 2
maxLength: 100
description: Filter articles whose title starts with the given text. Same 31-day window
limit as title
title_ends_with:
type: string
minLength: 2
maxLength: 100
description: Filter articles whose title ends with the given text. Same 31-day window
limit as title
title_pattern:
type: string
minLength: 2
maxLength: 200
description: Filter articles whose title matches the given pattern. Same 31-day window
limit as title
published_at:
type: string
description: 'Exact date (creates 24-hour range). Format: YYYY-MM-DD or ISO 8601'
example: '2025-01-15'
published_at.start:
type: string
description: 'Start of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title
search the range may not exceed 31 days (ER0110)'
example: '2025-01-01'
published_at.end:
type: string
description: 'End of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title
search the range may not exceed 31 days (ER0110)'
example: '2025-01-31'
language.code:
type: string
description: Comma-separated ISO 639-1 language codes (max 3)
example: en
ignore.language.code:
type: string
description: Exclude articles in these languages (comma-separated, max 3)
example: zh,ar
source.country.code:
type: string
description: Filter by source country ISO 3166-1 alpha-2 codes (comma-separated, max
3)
example: us
ignore.source.country.code:
type: string
description: Exclude sources from these countries (comma-separated, max 3)
example: us
source.rank.opr.min:
type: integer
minimum: 0
description: Minimum Open PageRank score
source.rank.opr.max:
type: integer
minimum: 0
description: Maximum Open PageRank score
source.id:
type: string
description: Comma-separated source IDs (max 3)
example: '100'
ignore.source.id:
type: string
description: Exclude these source IDs (comma-separated, max 3)
source.domain:
type: string
description: Comma-separated source domains (max 3)
example: nytimes.com
ignore.source.domain:
type: string
description: Exclude these source domains (comma-separated, max 3)
source.bias:
type: string
description: 'Filter by media bias (comma-separated). Values: left, center, right'
example: left
ignore.source.bias:
type: string
description: 'Exclude sources with this media bias (comma-separated). Values: left,
center, right'
example: right
is_premium_source:
type: integer
enum:
- 0
- 1
description: Filter by premium source status
is_verified_source:
type: integer
enum:
- 0
- 1
description: Filter by verified source status
category.id:
type: string
description: Comma-separated category IDs (max 3)
example: iab-1
ignore.category.id:
type: string
description: Exclude these categories (comma-separated, max 3)
topic.id:
type: string
description: Comma-separated topic IDs (max 3)
example: technology
ignore.topic.id:
type: string
description: Exclude these topics (comma-separated, max 3)
industry.id:
type: string
description: Comma-separated industry IDs (max 3)
example: '1'
ignore.industry.id:
type: string
description: Exclude these industries (comma-separated, max 3)
entity.id:
type: string
description: Comma-separated entity IDs (max 3)
example: '12345'
ignore.entity.id:
type: string
description: Exclude these entity IDs (comma-separated, max 3)
entity.sentiment.polarity:
type: string
enum:
- positive
- negative
- neutral
description: Filter by sentiment polarity toward the entity (combine with entity.id
or *.name; standalone = any entity)
entity.sentiment.score.min:
type: number
minimum: -1
maximum: 1
description: Minimum sentiment score toward the entity
entity.sentiment.score.max:
type: number
minimum: -1
maximum: 1
description: Maximum sentiment score toward the entity
person.name:
type: string
maxLength: 120
description: Filter by person name (comma-separated, max 3)
example: Elon Musk
ignore.person.name:
type: string
maxLength: 120
description: Exclude articles mentioning these persons (comma-separated, max 3)
organization.name:
type: string
maxLength: 120
description: Filter by organization name (comma-separated, max 3)
example: Google
ignore.organization.name:
type: string
maxLength: 120
description: Exclude articles mentioning these organizations (comma-separated, max 3)
location.name:
type: string
maxLength: 120
description: Filter by location name (comma-separated, max 3)
example: New York
ignore.location.name:
type: string
maxLength: 120
description: Exclude articles mentioning these locations (comma-separated, max 3)
brand.name:
type: string
maxLength: 120
description: Filter by brand name (comma-separated, max 3)
ignore.brand.name:
type: string
maxLength: 120
description: Exclude articles mentioning these brands (comma-separated, max 3)
disaster.name:
type: string
maxLength: 120
description: Filter by natural disaster name (comma-separated, max 3)
ignore.disaster.name:
type: string
maxLength: 120
description: Exclude articles mentioning these disasters (comma-separated, max 3)
disease.name:
type: string
maxLength: 120
description: Filter by disease name (comma-separated, max 3)
ignore.disease.name:
type: string
maxLength: 120
description: Exclude articles mentioning these diseases (comma-separated, max 3)
event.name:
type: string
maxLength: 120
description: Filter by event name (comma-separated, max 3)
ignore.event.name:
type: string
maxLength: 120
description: Exclude articles mentioning these events (comma-separated, max 3)
sport.name:
type: string
maxLength: 120
description: Filter by sport name (comma-separated, max 3)
ignore.sport.name:
type: string
maxLength: 120
description: Exclude articles mentioning these sports (comma-separated, max 3)
event.type:
type: string
description: 'Comma-separated event types (max 5). Values: merger-acquisition, ipo,
layoffs, bankruptcy, product-launch, funding-round, earnings, partnership, executive-change,
lawsuit, data-breach, recall, expansion, closure, stock-movement, contract-award,
spin-off, regulatory-action, election, protest, crime, terrorism, accident, policy-change,
scandal, death, award-ceremony, conflict, diplomacy, health-crisis, migration, human-rights,
earthquake, hurricane, flood, wildfire, tornado, tsunami, volcanic-eruption, drought,
climate-event, pollution, wildlife-event, avalanche'
example: ipo
event.category:
type: string
enum:
- business
- society
- environment
description: Filter by event category
ignore.event.type:
type: string
description: Exclude these event types (comma-separated, max 5)
sentiment.overall.score:
type: number
minimum: -1
maximum: 1
description: Exact overall sentiment score
sentiment.overall.score.min:
type: number
minimum: -1
maximum: 1
description: Minimum overall sentiment score
sentiment.overall.score.max:
type: number
minimum: -1
maximum: 1
description: Maximum overall sentiment score
sentiment.overall.polarity:
type: string
enum:
- positive
- negative
- neutral
description: Overall sentiment polarity
sentiment.title.score:
type: number
minimum: -1
maximum: 1
description: Exact title sentiment score
sentiment.title.score.min:
type: number
minimum: -1
maximum: 1
description: Minimum title sentiment score
sentiment.title.score.max:
type: number
minimum: -1
maximum: 1
description: Maximum title sentiment score
sentiment.title.polarity:
type: string
enum:
- positive
- negative
- neutral
description: Title sentiment polarity
sentiment.body.score:
type: number
minimum: -1
maximum: 1
description: Exact body sentiment score
sentiment.body.score.min:
type: number
minimum: -1
maximum: 1
description: Minimum body sentiment score
sentiment.body.score.max:
type: number
minimum: -1
maximum: 1
description: Maximum body sentiment score
sentiment.body.polarity:
type: string
enum:
- positive
- negative
- neutral
description: Body sentiment polarity
sentiment.mixed:
type: integer
enum:
- 0
- 1
description: Filter for mixed sentiment (title polarity != body polarity)
sentiment.consistent:
type: integer
enum:
- 0
- 1
description: Filter for consistent sentiment (title polarity == body polarity)
is_clickbait:
type: integer
enum:
- 0
- 1
description: Filter by clickbait detection
sentiment_gap.min:
type: number
minimum: 0
maximum: 2
description: Minimum sentiment gap between title and body
sentiment_gap.max:
type: number
minimum: 0
maximum: 2
description: Maximum sentiment gap between title and body
media.images.count:
type: integer
minimum: 0
description: Exact number of images
media.images.count.min:
type: integer
minimum: 0
description: Minimum number of images
media.images.count.max:
type: integer
minimum: 0
description: Maximum number of images
media.images.width.min:
type: integer
minimum: 0
description: Minimum image width in pixels
media.images.width.max:
type: integer
minimum: 0
description: Maximum image width in pixels
media.images.height.min:
type: integer
minimum: 0
description: Minimum image height in pixels
media.images.height.max:
type: integer
minimum: 0
description: Maximum image height in pixels
media.videos.count:
type: integer
minimum: 0
description: Exact number of videos
media.videos.count.min:
type: integer
minimum: 0
description: Minimum number of videos
media.videos.count.max:
type: integer
minimum: 0
description: Maximum number of videos
has_image:
type: integer
enum:
- 0
- 1
description: Filter articles with/without images
has_video:
type: integer
enum:
- 0
- 1
description: Filter articles with/without videos
has_hq_images:
type: integer
enum:
- 0
- 1
description: Filter articles with high-quality images (>= 1200px width)
is_media_rich:
type: integer
enum:
- 0
- 1
description: Filter articles with both images and videos
is_landscape_media:
type: integer
enum:
- 0
- 1
description: Filter articles with landscape-oriented media
is_portrait_media:
type: integer
enum:
- 0
- 1
description: Filter articles with portrait-oriented media
has_multiple_images:
type: integer
enum:
- 0
- 1
description: Filter articles with 2+ images
has_fullhd_images:
type: integer
enum:
- 0
- 1
description: Filter articles with Full HD images (>= 1920px width)
has_4k_images:
type: integer
enum:
- 0
- 1
description: Filter articles with 4K images (>= 3840px width)
has_mobile_optimized_images:
type: integer
enum:
- 0
- 1
description: Filter articles with mobile-optimized images (320-800px width)
is_instagram_ready:
type: integer
enum:
- 0
- 1
description: Filter articles with Instagram-ready images (>= 1080px + aspect ratio)
is_twitter_card_ready:
type: integer
enum:
- 0
- 1
description: Filter articles with Twitter Card-ready images (>= 800px + landscape)
has_consistent_image_sizes:
type: integer
enum:
- 0
- 1
description: Filter articles with consistent image dimensions
has_thumbnail:
type: integer
enum:
- 0
- 1
description: Filter articles with thumbnail images (<= 300px width)
has_social_share_image:
type: integer
enum:
- 0
- 1
description: Filter articles with social share images (>= 1200x630px)
has_mixed_media:
type: integer
enum:
- 0
- 1
description: Filter articles with both image and video media types
readability.fk_grade:
type: number
minimum: 0
maximum: 30
description: Exact Flesch-Kincaid grade level
readability.fk_grade.min:
type: number
minimum: 0
maximum: 30
description: Minimum Flesch-Kincaid grade level
readability.fk_grade.max:
type: number
minimum: 0
maximum: 30
description: Maximum Flesch-Kincaid grade level
readability.ease:
type: number
minimum: 0
maximum: 100
description: Exact Flesch Reading Ease score
readability.ease.min:
type: number
minimum: 0
maximum: 100
description: Minimum Flesch Reading Ease score
readability.ease.max:
type: number
minimum: 0
maximum: 100
description: Maximum Flesch Reading Ease score
readability.ari:
type: number
minimum: 0
maximum: 30
description: Exact Automated Readability Index
readability.ari.min:
type: number
minimum: 0
maximum: 30
description: Minimum Automated Readability Index
readability.ari.max:
type: number
minimum: 0
maximum: 30
description: Maximum Automated Readability Index
readability.difficulty:
type: string
enum:
- beginner
- intermediate
- advanced
- expert
description: Difficulty level
readability.audience:
type: string
enum:
- children
- general
- professional
- academic
description: Target audience
readability.age:
type: integer
minimum: 6
maximum: 22
description: Exact reading age
readability.age.min:
type: integer
minimum: 6
maximum: 22
description: Minimum reading age
readability.age.max:
type: integer
minimum: 6
maximum: 22
description: Maximum reading age
is_easy_read:
type: integer
enum:
- 0
- 1
description: Filter for easy-to-read articles (Flesch Reading Ease >= 60)
is_difficult_read:
type: integer
enum:
- 0
- 1
description: Filter for difficult-to-read articles (Flesch Reading Ease < 40)
read_time:
type: integer
minimum: 0
maximum: 1000
description: Exact read time in minutes
read_time.min:
type: integer
minimum: 0
maximum: 1000
description: Minimum read time in minutes
read_time.max:
type: integer
minimum: 0
maximum: 1000
description: Maximum read time in minutes
is_long_read:
type: integer
enum:
- 0
- 1
description: Filter for long reads (>= 5 minutes)
is_short_read:
type: integer
enum:
- 0
- 1
description: Filter for short reads (< 3 minutes)
is_quick_read:
type: integer
enum:
- 0
- 1
description: Filter for quick reads (<= 2 minutes)
is_medium_read:
type: integer
enum:
- 0
- 1
description: Filter for medium-length reads (3-7 minutes)
is_deep_dive:
type: integer
enum:
- 0
- 1
description: Filter for deep dives (>= 10 minutes)
location.bbox:
type: string
description: 'Bounding box: minLat,maxLat,minLng,maxLng'
example: 40.0,41.0,-74.5,-73.5
has_location_geo:
type: integer
enum:
- 0
- 1
description: Filter articles with/without geo-location data
location.lat:
type: number
minimum: -90
maximum: 90
description: Latitude for radius search
location.lng:
type: number
minimum: -180
maximum: 180
description: Longitude for radius search
location.radius:
type: number
exclusiveMinimum: 0
maximum: 20000
description: Search radius in kilometers (requires location.lat and location.lng)
location.radius.min:
type: number
minimum: 0
maximum: 20000
description: Minimum distance from point in km
is_duplicate:
type: integer
enum:
- 0
- 1
description: Filter duplicate/unique articles
is_paywall:
type: integer
enum:
- 0
- 1
description: Filter paywalled articles
is_breaking:
type: integer
enum:
- 0
- 1
description: Filter breaking news articles
is_high_quality:
type: integer
enum:
- 0
- 1
description: Filter high-quality articles (not duplicate, rank >= 5, has images, has
author)
author.id:
type: string
description: Comma-separated author IDs (max 3)
ignore.author.id:
type: string
description: Exclude these author IDs (comma-separated, max 3)
author.name:
type: string
maxLength: 100
description: Filter by author name (comma-separated, max 3)
ignore.author.name:
type: string
maxLength: 100
description: Exclude articles by these authors (comma-separated, max 3)
has_author:
type: integer
enum:
- 0
- 1
description: Filter articles with/without author
facet:
type: string
enum:
- '0'
- '1'
description: Enable faceting
facet.field:
type: string
description: 'Comma-separated facet fields (max 5). Values: source.id, source.country.id,
source.bias, language.id, author.id, category.id, topic.id, industry.id, entity.id,
sentiment.overall.polarity, sentiment.title.polarity, sentiment.body.polarity, sentiment.strength,
is_duplicate, is_free, is_important, media.images.count, media.videos.count, read_time,
content.length, published.year, published.month, published.day_of_week, published.hour,
published.weekday, published.time_of_day'
example: source.id,category.id
facet.limit:
type: integer
minimum: 1
maximum: 100
default: 10
description: Maximum number of facet values per field (max 100)
facet.mincount:
type: integer
minimum: 1
default: 1
description: Minimum count for a facet value to be included
facet.range:
type: string
enum:
- '0'
- '1'
description: Enable range faceting
facet.range.field:
type: string
description: 'Field for range faceting. Values: published_at, sentiment.overall.score,
sentiment.title.score, sentiment.body.score, read_time, source.rank.opr, media.images.count,
media.videos.count'
facet.range.start:
type: string
description: Start value for range faceting (required with facet.range)
facet.range.end:
type: string
description: End value for range faceting (required with facet.range)
facet.range.gap:
type: string
default: +1DAY
description: Gap value for range faceting
hl:
type: string
enum:
- '0'
- '1'
description: Enable highlighting
hl.fl:
type: string
default: title,description
description: 'Comma-separated fields to highlight (max 5). Values: title, description,
body'
example: title,description
hl.fragsize:
type: integer
minimum: 50
maximum: 500
default: 150
description: Size of highlighted fragment in characters (50-500)
hl.snippets:
type: integer
minimum: 1
maximum: 10
default: 3
description: Number of highlighted snippets per field (max 10)
hl.tag.pre:
type: string
description: Opening tag for highlighted text
default:
hl.tag.post:
type: string
description: Closing tag for highlighted text
default:
export:
type: string
enum:
- json
- csv
- tsv
- xml
- rss
- xlsx
- parquet
- jsonl
- ndjson
description: Export format
fl:
type: string
description: Comma-separated list of fields to include in the response
example: id,title,published_at,source.domain
debug:
type: string
enum:
- '0'
- '1'
description: Include user_input in response for debugging
api_key:
type: string
description: API key (alternative to X-API-Key header)
parameters:
- schema:
type: string
in: path
name: articleId
required: true
description: Source article ID to find related stories for
responses:
'200':
description: Successful response with related articles
content:
application/json:
schema:
description: Successful response with related articles
type: object
properties:
status:
type: string
enum:
- ok
description: Response status
limit:
type: integer
description: Results per page
path:
type: string
description: Current request URL
page:
type: integer
description: Current page number
has_next_pages:
type: boolean
description: Whether more pages are available
next_page:
type: string
description: URL for the next page (empty if no next page)
has_previous_page:
type: boolean
description: Whether a previous page exists
previous_page:
type: string
description: URL for the previous page (empty if no previous page)
export:
type: object
description: Export format URLs
properties:
json:
type: string
xlsx:
type: string
csv:
type: string
tsv:
type: string
xml:
type: string
rss:
type: string
parquet:
type: string
jsonl:
type: string
request_id:
type: string
description: Unique request identifier
results:
type: array
items:
type: object
properties:
id:
type: integer
description: Unique article ID
href:
type:
- string
- 'null'
description: Original article URL
published_at:
type:
- string
- 'null'
format: date-time
description: Publication date in ISO 8601
title:
type:
- string
- 'null'
description: Article title
description:
type:
- string
- 'null'
description: Article description (plain text)
body:
type:
- string
- 'null'
description: Article body (plain text)
body_html:
type:
- string
- 'null'
description: Article body (HTML)
language:
type: string
description: ISO 639-1 language code
translations:
type: object
description: Machine translations of the article title and description. Always
present; fields stay null for English articles and for languages without a
translation model
properties:
en:
type: object
properties:
title:
type:
- string
- 'null'
description: Title translated to English
description:
type:
- string
- 'null'
description: Description translated to English (plain text)
author:
type: object
properties:
id:
type:
- integer
- 'null'
description: Author ID
name:
type: string
description: Author name
image:
type: string
description: Main article image URL
categories:
type: array
items:
type: object
properties:
id:
type: integer
description: Category ID
name:
type: string
description: Category name
score:
type: number
description: Relevance score
taxonomy:
type: string
description: Taxonomy identifier
links:
type: object
properties:
self:
type: string
description: Link to category endpoint
topics:
type: array
items:
type: object
properties:
id:
type: string
description: Topic ID
name:
type: string
description: Topic name
score:
type: number
description: Relevance score
links:
type: object
properties:
self:
type: string
description: Link to topic endpoint
industries:
type: array
items:
type: object
properties:
id:
type: integer
description: Industry ID
name:
type: string
description: Industry name
links:
type: object
properties:
self:
type: string
description: Link to industry endpoint
entities:
type: array
items:
type: object
properties:
id:
type: integer
description: Entity ID
name:
type: string
description: Entity name
type:
type: string
enum:
- person
- location
- organization
- brand
- product
- natural-disaster
- disease
- event
- sport
- unknown
description: Entity type
frequency:
type: integer
description: Number of mentions in the article
sentiment:
type: object
description: Sentiment toward this entity (aggregated across its mentions)
properties:
score:
type: number
description: Entity sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Entity sentiment polarity
mentions:
type: object
description: Per-mention polarity breakdown
properties:
positive:
type: integer
neutral:
type: integer
negative:
type: integer
title:
type: object
properties:
pos:
type: array
items:
type: object
properties:
start:
type: integer
description: Start character offset
end:
type: integer
description: End character offset
description: Mention positions in title
body:
type: object
properties:
pos:
type: array
items:
type: object
properties:
start:
type: integer
description: Start character offset
end:
type: integer
description: End character offset
description: Mention positions in body
links:
type: object
properties:
self:
type: string
description: Link to entity endpoint
wikipedia:
type: string
description: Wikipedia URL
wikidata:
type: string
description: Wikidata URL
metadata:
type: object
description: Additional entity metadata (varies by entity type)
additionalProperties: true
locations_mentioned:
type: array
items:
type: object
properties:
name:
type: string
description: Location name
country:
type: string
description: Country code
lat:
type:
- number
- 'null'
description: Latitude
lng:
type:
- number
- 'null'
description: Longitude
type:
type: string
description: Location type
source:
type: object
properties:
id:
type:
- integer
- 'null'
description: Source ID
domain:
type: string
description: Source domain
home_page_url:
type: string
description: Source home page URL
type:
type: string
description: Source type
bias:
type: string
description: Media bias (left, center, right)
rankings:
type: object
properties:
opr:
type: integer
description: Open PageRank score
location:
type: object
properties:
country_name:
type: string
description: Source country name
country_code:
type: string
description: Source country ISO code
favicon:
type: string
description: Source favicon URL
sentiment:
type: object
properties:
overall:
type: object
properties:
score:
type: number
description: Sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Sentiment polarity
title:
type: object
properties:
score:
type: number
description: Sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Sentiment polarity
body:
type: object
properties:
score:
type: number
description: Sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Sentiment polarity
summary:
type: array
items:
type: object
properties:
sentence:
type: string
description: Summary sentence
sentiment:
type: object
properties:
score:
type: number
description: Sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Sentiment polarity
readability:
type: object
properties:
flesch_kincaid_grade:
type: number
description: Flesch-Kincaid grade level
flesch_reading_ease:
type: number
description: Flesch Reading Ease score (0-100)
automated_readability_index:
type: number
description: Automated Readability Index
difficulty_level:
type: string
enum:
- beginner
- intermediate
- advanced
- expert
- unknown
description: Difficulty level
target_audience:
type: string
enum:
- children
- general
- professional
- academic
- unknown
description: Target audience
reading_age:
type: number
description: Estimated reading age
avg_words_per_sentence:
type: number
description: Average words per sentence
avg_syllables_per_word:
type: number
description: Average syllables per word
keywords:
type: array
items:
type: string
description: Article keywords
links:
type: array
items:
type: object
properties:
url:
type: string
description: Link URL
type:
type: string
description: Link type
media:
type: array
items:
type: object
properties:
url:
type: string
description: Media URL
type:
type: string
description: Media type (image, video, etc.)
shares:
type: object
properties:
total:
type: integer
description: Total social shares
facebook:
type: integer
description: Facebook shares
twitter:
type: integer
description: Twitter/X shares
reddit:
type: integer
description: Reddit shares
story:
type: object
properties:
id:
type: integer
description: Story ID
uri:
type: string
description: Story endpoint URI
is_duplicate:
type: boolean
description: Whether this is a duplicate article
is_free:
type: boolean
description: Whether the article is freely accessible
is_breaking:
type: boolean
description: Whether this is breaking news
read_time:
type: integer
description: Estimated read time in minutes
sentences_count:
type: integer
description: Number of sentences
paragraphs_count:
type: integer
description: Number of paragraphs
words_count:
type: integer
description: Number of words
characters_count:
type: integer
description: Number of characters
description: Array of articles
facets:
type: object
description: Facet results (present when facet.field is specified)
additionalProperties: true
highlighting:
type: object
description: Highlighting results (present when hl=1)
additionalProperties: true
headlines:
type: array
description: Headlines (present in some responses)
items:
type: object
additionalProperties: true
meta:
type: object
description: 'Additional metadata. Present only when there is something to report
about how the request was handled: `prompt` (the request used the prompt parameter)
and/or `warnings` (the query was silently narrowed, e.g. ER0366 clamping a title
search to the last 31 days).'
properties:
prompt:
type: object
description: How the `prompt` parameter was translated into filters. Returned
by every JSON response to a request that used it (the SSE stream has no JSON
envelope, so it carries none).
properties:
text:
type: string
description: The prompt as it was parsed, trimmed
applied:
type: object
description: Parameters the prompt was translated into — the request that
actually ran
additionalProperties:
type: string
ignored:
type: array
description: Values understood but not used
items:
type: object
properties:
field:
type: string
description: Parameter that was not applied
value:
type: string
description: Value the prompt produced for it
reason:
type: string
enum:
- not_found
- explicit_param
- unsupported_on_endpoint
- invalid_date
- title_too_long
- title_window_clamped
description: Why the value was not applied
cached:
type: boolean
description: true when this wording had been parsed before, so no parse fee
was charged
warnings:
type: array
description: Non-fatal notices — the request still returned HTTP 200
items:
type: object
properties:
code:
type: string
description: Warning code, e.g. ER0366
message:
type: string
description: Human-readable explanation
links:
type: object
additionalProperties: true
additionalProperties: true
user_input:
type: object
description: Debug info — original request parameters (present when debug=1)
additionalProperties: true
required:
- status
- limit
- path
- page
- has_next_pages
- has_previous_page
- request_id
- results
example:
status: ok
limit: 50
path: /v1/news/everything
page: 1
has_next_pages: true
next_page: /v1/news/everything?page=2
has_previous_page: false
previous_page: ''
export:
json: /v1/news/everything?export=json
csv: /v1/news/everything?export=csv
rss: /v1/news/everything?export=rss
request_id: req_abc123def456
results:
- id: 84029371
href: https://example.com/article/spacex-launch
published_at: '2026-03-23T14:30:00Z'
title: SpaceX Successfully Launches New Starship Prototype
description: SpaceX completed another successful test flight of its Starship rocket...
language: en
author:
id: 1024
name: Jane Smith
image: https://example.com/images/starship.jpg
categories:
- id: 201
name: Science & Technology
score: 0.95
taxonomy: iptc_mediatopics
topics:
- id: space-exploration
name: Space Exploration
score: 0.92
industries:
- id: 88
name: Aerospace & Defense
entities:
- id: 5012
name: SpaceX
type: organization
frequency: 8
links:
wikipedia: https://en.wikipedia.org/wiki/SpaceX
- id: 3401
name: Elon Musk
type: person
frequency: 3
links:
wikipedia: https://en.wikipedia.org/wiki/Elon_Musk
source:
id: 7823
domain: reuters.com
home_page_url: https://www.reuters.com
type: news_agency
location:
country_name: United States
country_code: us
rankings:
opr: 8
sentiment:
overall:
score: 0.65
polarity: positive
title:
score: 0.72
polarity: positive
body:
score: 0.61
polarity: positive
readability:
flesch_kincaid_grade: 10.2
flesch_reading_ease: 52.3
difficulty_level: intermediate
target_audience: general
keywords:
- spacex
- starship
- rocket
- launch
is_duplicate: false
is_breaking: true
read_time: 4
words_count: 847
'400':
description: Article ID is required
content:
application/json:
schema:
description: Article ID is required
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
'401':
description: Authentication error
content:
application/json:
schema:
description: Authentication error
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
description: Rate limit exceeded
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
/v1/news/article:
post:
summary: Get articles by ID
tags:
- News
description: Returns one or more articles by their IDs (comma-separated, max 100). Supports filtering,
faceting, field selection, and export.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: Comma-separated article IDs (max 100). Required.
example: '12345'
page:
type: integer
minimum: 1
default: 1
description: Page number for pagination
per_page:
type: integer
minimum: 1
maximum: 250
default: 100
description: Number of results per page (max 250; the Free plan is capped at 10 and
Starter at 50)
sort.by:
type: string
enum:
- published_at
- relevance
- engagement
- quality
- controversy
- trust
- id
- new
- created_at
- source.rank.opr
- sentiment.overall.score
- sentiment.title.score
- sentiment.body.score
- read_time
- sentences_count
- paragraphs_count
- characters_count
- media.images.count
- media.videos.count
- media.images.width.min
- media.images.width.max
- media.images.height.min
- media.images.height.max
- media_richness
- shares.facebook.min
- shares.facebook.max
- shares.twitter.min
- shares.twitter.max
- shares.reddit.min
- shares.reddit.max
default: published_at
description: Field to sort results by
sort.order:
type: string
enum:
- asc
- desc
default: desc
description: Sort order
article.id:
type: string
description: Comma-separated article IDs (max 5)
example: '12345'
title:
type: string
minLength: 2
maxLength: 100
description: 'Search in article titles. Supports phrase search with proximity: "climate
change"~2. Title search is limited to a 31-day published_at window: without published_at.start
/ published_at.end the last 31 days are searched, a wider explicit range returns ER0110.'
ignore.title:
type: string
minLength: 2
maxLength: 100
description: Exclude articles containing this text in the title
title_starts_with:
type: string
minLength: 2
maxLength: 100
description: Filter articles whose title starts with the given text. Same 31-day window
limit as title
title_ends_with:
type: string
minLength: 2
maxLength: 100
description: Filter articles whose title ends with the given text. Same 31-day window
limit as title
title_pattern:
type: string
minLength: 2
maxLength: 200
description: Filter articles whose title matches the given pattern. Same 31-day window
limit as title
published_at:
type: string
description: 'Exact date (creates 24-hour range). Format: YYYY-MM-DD or ISO 8601'
example: '2025-01-15'
published_at.start:
type: string
description: 'Start of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title
search the range may not exceed 31 days (ER0110)'
example: '2025-01-01'
published_at.end:
type: string
description: 'End of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title
search the range may not exceed 31 days (ER0110)'
example: '2025-01-31'
language.code:
type: string
description: Comma-separated ISO 639-1 language codes (max 3)
example: en
ignore.language.code:
type: string
description: Exclude articles in these languages (comma-separated, max 3)
example: zh,ar
source.country.code:
type: string
description: Filter by source country ISO 3166-1 alpha-2 codes (comma-separated, max
3)
example: us
ignore.source.country.code:
type: string
description: Exclude sources from these countries (comma-separated, max 3)
example: us
source.rank.opr.min:
type: integer
minimum: 0
description: Minimum Open PageRank score
source.rank.opr.max:
type: integer
minimum: 0
description: Maximum Open PageRank score
source.id:
type: string
description: Comma-separated source IDs (max 3)
example: '100'
ignore.source.id:
type: string
description: Exclude these source IDs (comma-separated, max 3)
source.domain:
type: string
description: Comma-separated source domains (max 3)
example: nytimes.com
ignore.source.domain:
type: string
description: Exclude these source domains (comma-separated, max 3)
source.bias:
type: string
description: 'Filter by media bias (comma-separated). Values: left, center, right'
example: left
ignore.source.bias:
type: string
description: 'Exclude sources with this media bias (comma-separated). Values: left,
center, right'
example: right
is_premium_source:
type: integer
enum:
- 0
- 1
description: Filter by premium source status
is_verified_source:
type: integer
enum:
- 0
- 1
description: Filter by verified source status
category.id:
type: string
description: Comma-separated category IDs (max 3)
example: iab-1
ignore.category.id:
type: string
description: Exclude these categories (comma-separated, max 3)
topic.id:
type: string
description: Comma-separated topic IDs (max 3)
example: technology
ignore.topic.id:
type: string
description: Exclude these topics (comma-separated, max 3)
industry.id:
type: string
description: Comma-separated industry IDs (max 3)
example: '1'
ignore.industry.id:
type: string
description: Exclude these industries (comma-separated, max 3)
entity.id:
type: string
description: Comma-separated entity IDs (max 3)
example: '12345'
ignore.entity.id:
type: string
description: Exclude these entity IDs (comma-separated, max 3)
entity.sentiment.polarity:
type: string
enum:
- positive
- negative
- neutral
description: Filter by sentiment polarity toward the entity (combine with entity.id
or *.name; standalone = any entity)
entity.sentiment.score.min:
type: number
minimum: -1
maximum: 1
description: Minimum sentiment score toward the entity
entity.sentiment.score.max:
type: number
minimum: -1
maximum: 1
description: Maximum sentiment score toward the entity
person.name:
type: string
maxLength: 120
description: Filter by person name (comma-separated, max 3)
example: Elon Musk
ignore.person.name:
type: string
maxLength: 120
description: Exclude articles mentioning these persons (comma-separated, max 3)
organization.name:
type: string
maxLength: 120
description: Filter by organization name (comma-separated, max 3)
example: Google
ignore.organization.name:
type: string
maxLength: 120
description: Exclude articles mentioning these organizations (comma-separated, max 3)
location.name:
type: string
maxLength: 120
description: Filter by location name (comma-separated, max 3)
example: New York
ignore.location.name:
type: string
maxLength: 120
description: Exclude articles mentioning these locations (comma-separated, max 3)
brand.name:
type: string
maxLength: 120
description: Filter by brand name (comma-separated, max 3)
ignore.brand.name:
type: string
maxLength: 120
description: Exclude articles mentioning these brands (comma-separated, max 3)
disaster.name:
type: string
maxLength: 120
description: Filter by natural disaster name (comma-separated, max 3)
ignore.disaster.name:
type: string
maxLength: 120
description: Exclude articles mentioning these disasters (comma-separated, max 3)
disease.name:
type: string
maxLength: 120
description: Filter by disease name (comma-separated, max 3)
ignore.disease.name:
type: string
maxLength: 120
description: Exclude articles mentioning these diseases (comma-separated, max 3)
event.name:
type: string
maxLength: 120
description: Filter by event name (comma-separated, max 3)
ignore.event.name:
type: string
maxLength: 120
description: Exclude articles mentioning these events (comma-separated, max 3)
sport.name:
type: string
maxLength: 120
description: Filter by sport name (comma-separated, max 3)
ignore.sport.name:
type: string
maxLength: 120
description: Exclude articles mentioning these sports (comma-separated, max 3)
event.type:
type: string
description: 'Comma-separated event types (max 5). Values: merger-acquisition, ipo,
layoffs, bankruptcy, product-launch, funding-round, earnings, partnership, executive-change,
lawsuit, data-breach, recall, expansion, closure, stock-movement, contract-award,
spin-off, regulatory-action, election, protest, crime, terrorism, accident, policy-change,
scandal, death, award-ceremony, conflict, diplomacy, health-crisis, migration, human-rights,
earthquake, hurricane, flood, wildfire, tornado, tsunami, volcanic-eruption, drought,
climate-event, pollution, wildlife-event, avalanche'
example: ipo
event.category:
type: string
enum:
- business
- society
- environment
description: Filter by event category
ignore.event.type:
type: string
description: Exclude these event types (comma-separated, max 5)
sentiment.overall.score:
type: number
minimum: -1
maximum: 1
description: Exact overall sentiment score
sentiment.overall.score.min:
type: number
minimum: -1
maximum: 1
description: Minimum overall sentiment score
sentiment.overall.score.max:
type: number
minimum: -1
maximum: 1
description: Maximum overall sentiment score
sentiment.overall.polarity:
type: string
enum:
- positive
- negative
- neutral
description: Overall sentiment polarity
sentiment.title.score:
type: number
minimum: -1
maximum: 1
description: Exact title sentiment score
sentiment.title.score.min:
type: number
minimum: -1
maximum: 1
description: Minimum title sentiment score
sentiment.title.score.max:
type: number
minimum: -1
maximum: 1
description: Maximum title sentiment score
sentiment.title.polarity:
type: string
enum:
- positive
- negative
- neutral
description: Title sentiment polarity
sentiment.body.score:
type: number
minimum: -1
maximum: 1
description: Exact body sentiment score
sentiment.body.score.min:
type: number
minimum: -1
maximum: 1
description: Minimum body sentiment score
sentiment.body.score.max:
type: number
minimum: -1
maximum: 1
description: Maximum body sentiment score
sentiment.body.polarity:
type: string
enum:
- positive
- negative
- neutral
description: Body sentiment polarity
sentiment.mixed:
type: integer
enum:
- 0
- 1
description: Filter for mixed sentiment (title polarity != body polarity)
sentiment.consistent:
type: integer
enum:
- 0
- 1
description: Filter for consistent sentiment (title polarity == body polarity)
is_clickbait:
type: integer
enum:
- 0
- 1
description: Filter by clickbait detection
sentiment_gap.min:
type: number
minimum: 0
maximum: 2
description: Minimum sentiment gap between title and body
sentiment_gap.max:
type: number
minimum: 0
maximum: 2
description: Maximum sentiment gap between title and body
media.images.count:
type: integer
minimum: 0
description: Exact number of images
media.images.count.min:
type: integer
minimum: 0
description: Minimum number of images
media.images.count.max:
type: integer
minimum: 0
description: Maximum number of images
media.images.width.min:
type: integer
minimum: 0
description: Minimum image width in pixels
media.images.width.max:
type: integer
minimum: 0
description: Maximum image width in pixels
media.images.height.min:
type: integer
minimum: 0
description: Minimum image height in pixels
media.images.height.max:
type: integer
minimum: 0
description: Maximum image height in pixels
media.videos.count:
type: integer
minimum: 0
description: Exact number of videos
media.videos.count.min:
type: integer
minimum: 0
description: Minimum number of videos
media.videos.count.max:
type: integer
minimum: 0
description: Maximum number of videos
has_image:
type: integer
enum:
- 0
- 1
description: Filter articles with/without images
has_video:
type: integer
enum:
- 0
- 1
description: Filter articles with/without videos
has_hq_images:
type: integer
enum:
- 0
- 1
description: Filter articles with high-quality images (>= 1200px width)
is_media_rich:
type: integer
enum:
- 0
- 1
description: Filter articles with both images and videos
is_landscape_media:
type: integer
enum:
- 0
- 1
description: Filter articles with landscape-oriented media
is_portrait_media:
type: integer
enum:
- 0
- 1
description: Filter articles with portrait-oriented media
has_multiple_images:
type: integer
enum:
- 0
- 1
description: Filter articles with 2+ images
has_fullhd_images:
type: integer
enum:
- 0
- 1
description: Filter articles with Full HD images (>= 1920px width)
has_4k_images:
type: integer
enum:
- 0
- 1
description: Filter articles with 4K images (>= 3840px width)
has_mobile_optimized_images:
type: integer
enum:
- 0
- 1
description: Filter articles with mobile-optimized images (320-800px width)
is_instagram_ready:
type: integer
enum:
- 0
- 1
description: Filter articles with Instagram-ready images (>= 1080px + aspect ratio)
is_twitter_card_ready:
type: integer
enum:
- 0
- 1
description: Filter articles with Twitter Card-ready images (>= 800px + landscape)
has_consistent_image_sizes:
type: integer
enum:
- 0
- 1
description: Filter articles with consistent image dimensions
has_thumbnail:
type: integer
enum:
- 0
- 1
description: Filter articles with thumbnail images (<= 300px width)
has_social_share_image:
type: integer
enum:
- 0
- 1
description: Filter articles with social share images (>= 1200x630px)
has_mixed_media:
type: integer
enum:
- 0
- 1
description: Filter articles with both image and video media types
readability.fk_grade:
type: number
minimum: 0
maximum: 30
description: Exact Flesch-Kincaid grade level
readability.fk_grade.min:
type: number
minimum: 0
maximum: 30
description: Minimum Flesch-Kincaid grade level
readability.fk_grade.max:
type: number
minimum: 0
maximum: 30
description: Maximum Flesch-Kincaid grade level
readability.ease:
type: number
minimum: 0
maximum: 100
description: Exact Flesch Reading Ease score
readability.ease.min:
type: number
minimum: 0
maximum: 100
description: Minimum Flesch Reading Ease score
readability.ease.max:
type: number
minimum: 0
maximum: 100
description: Maximum Flesch Reading Ease score
readability.ari:
type: number
minimum: 0
maximum: 30
description: Exact Automated Readability Index
readability.ari.min:
type: number
minimum: 0
maximum: 30
description: Minimum Automated Readability Index
readability.ari.max:
type: number
minimum: 0
maximum: 30
description: Maximum Automated Readability Index
readability.difficulty:
type: string
enum:
- beginner
- intermediate
- advanced
- expert
description: Difficulty level
readability.audience:
type: string
enum:
- children
- general
- professional
- academic
description: Target audience
readability.age:
type: integer
minimum: 6
maximum: 22
description: Exact reading age
readability.age.min:
type: integer
minimum: 6
maximum: 22
description: Minimum reading age
readability.age.max:
type: integer
minimum: 6
maximum: 22
description: Maximum reading age
is_easy_read:
type: integer
enum:
- 0
- 1
description: Filter for easy-to-read articles (Flesch Reading Ease >= 60)
is_difficult_read:
type: integer
enum:
- 0
- 1
description: Filter for difficult-to-read articles (Flesch Reading Ease < 40)
read_time:
type: integer
minimum: 0
maximum: 1000
description: Exact read time in minutes
read_time.min:
type: integer
minimum: 0
maximum: 1000
description: Minimum read time in minutes
read_time.max:
type: integer
minimum: 0
maximum: 1000
description: Maximum read time in minutes
is_long_read:
type: integer
enum:
- 0
- 1
description: Filter for long reads (>= 5 minutes)
is_short_read:
type: integer
enum:
- 0
- 1
description: Filter for short reads (< 3 minutes)
is_quick_read:
type: integer
enum:
- 0
- 1
description: Filter for quick reads (<= 2 minutes)
is_medium_read:
type: integer
enum:
- 0
- 1
description: Filter for medium-length reads (3-7 minutes)
is_deep_dive:
type: integer
enum:
- 0
- 1
description: Filter for deep dives (>= 10 minutes)
location.bbox:
type: string
description: 'Bounding box: minLat,maxLat,minLng,maxLng'
example: 40.0,41.0,-74.5,-73.5
has_location_geo:
type: integer
enum:
- 0
- 1
description: Filter articles with/without geo-location data
location.lat:
type: number
minimum: -90
maximum: 90
description: Latitude for radius search
location.lng:
type: number
minimum: -180
maximum: 180
description: Longitude for radius search
location.radius:
type: number
exclusiveMinimum: 0
maximum: 20000
description: Search radius in kilometers (requires location.lat and location.lng)
location.radius.min:
type: number
minimum: 0
maximum: 20000
description: Minimum distance from point in km
is_duplicate:
type: integer
enum:
- 0
- 1
description: Filter duplicate/unique articles
is_paywall:
type: integer
enum:
- 0
- 1
description: Filter paywalled articles
is_breaking:
type: integer
enum:
- 0
- 1
description: Filter breaking news articles
is_high_quality:
type: integer
enum:
- 0
- 1
description: Filter high-quality articles (not duplicate, rank >= 5, has images, has
author)
author.id:
type: string
description: Comma-separated author IDs (max 3)
ignore.author.id:
type: string
description: Exclude these author IDs (comma-separated, max 3)
author.name:
type: string
maxLength: 100
description: Filter by author name (comma-separated, max 3)
ignore.author.name:
type: string
maxLength: 100
description: Exclude articles by these authors (comma-separated, max 3)
has_author:
type: integer
enum:
- 0
- 1
description: Filter articles with/without author
facet:
type: string
enum:
- '0'
- '1'
description: Enable faceting
facet.field:
type: string
description: 'Comma-separated facet fields (max 5). Values: source.id, source.country.id,
source.bias, language.id, author.id, category.id, topic.id, industry.id, entity.id,
sentiment.overall.polarity, sentiment.title.polarity, sentiment.body.polarity, sentiment.strength,
is_duplicate, is_free, is_important, media.images.count, media.videos.count, read_time,
content.length, published.year, published.month, published.day_of_week, published.hour,
published.weekday, published.time_of_day'
example: source.id,category.id
facet.limit:
type: integer
minimum: 1
maximum: 100
default: 10
description: Maximum number of facet values per field (max 100)
facet.mincount:
type: integer
minimum: 1
default: 1
description: Minimum count for a facet value to be included
facet.range:
type: string
enum:
- '0'
- '1'
description: Enable range faceting
facet.range.field:
type: string
description: 'Field for range faceting. Values: published_at, sentiment.overall.score,
sentiment.title.score, sentiment.body.score, read_time, source.rank.opr, media.images.count,
media.videos.count'
facet.range.start:
type: string
description: Start value for range faceting (required with facet.range)
facet.range.end:
type: string
description: End value for range faceting (required with facet.range)
facet.range.gap:
type: string
default: +1DAY
description: Gap value for range faceting
hl:
type: string
enum:
- '0'
- '1'
description: Enable highlighting
hl.fl:
type: string
default: title,description
description: 'Comma-separated fields to highlight (max 5). Values: title, description,
body'
example: title,description
hl.fragsize:
type: integer
minimum: 50
maximum: 500
default: 150
description: Size of highlighted fragment in characters (50-500)
hl.snippets:
type: integer
minimum: 1
maximum: 10
default: 3
description: Number of highlighted snippets per field (max 10)
hl.tag.pre:
type: string
description: Opening tag for highlighted text
default:
hl.tag.post:
type: string
description: Closing tag for highlighted text
default:
export:
type: string
enum:
- json
- csv
- tsv
- xml
- rss
- xlsx
- parquet
- jsonl
- ndjson
description: Export format
fl:
type: string
description: Comma-separated list of fields to include in the response
example: id,title,published_at,source.domain
debug:
type: string
enum:
- '0'
- '1'
description: Include user_input in response for debugging
api_key:
type: string
description: API key (alternative to X-API-Key header)
responses:
'200':
description: Successful response with articles
content:
application/json:
schema:
description: Successful response with articles
type: object
properties:
status:
type: string
enum:
- ok
description: Response status
limit:
type: integer
description: Results per page
path:
type: string
description: Current request URL
page:
type: integer
description: Current page number
has_next_pages:
type: boolean
description: Whether more pages are available
next_page:
type: string
description: URL for the next page (empty if no next page)
has_previous_page:
type: boolean
description: Whether a previous page exists
previous_page:
type: string
description: URL for the previous page (empty if no previous page)
export:
type: object
description: Export format URLs
properties:
json:
type: string
xlsx:
type: string
csv:
type: string
tsv:
type: string
xml:
type: string
rss:
type: string
parquet:
type: string
jsonl:
type: string
request_id:
type: string
description: Unique request identifier
results:
type: array
items:
type: object
properties:
id:
type: integer
description: Unique article ID
href:
type:
- string
- 'null'
description: Original article URL
published_at:
type:
- string
- 'null'
format: date-time
description: Publication date in ISO 8601
title:
type:
- string
- 'null'
description: Article title
description:
type:
- string
- 'null'
description: Article description (plain text)
body:
type:
- string
- 'null'
description: Article body (plain text)
body_html:
type:
- string
- 'null'
description: Article body (HTML)
language:
type: string
description: ISO 639-1 language code
translations:
type: object
description: Machine translations of the article title and description. Always
present; fields stay null for English articles and for languages without a
translation model
properties:
en:
type: object
properties:
title:
type:
- string
- 'null'
description: Title translated to English
description:
type:
- string
- 'null'
description: Description translated to English (plain text)
author:
type: object
properties:
id:
type:
- integer
- 'null'
description: Author ID
name:
type: string
description: Author name
image:
type: string
description: Main article image URL
categories:
type: array
items:
type: object
properties:
id:
type: integer
description: Category ID
name:
type: string
description: Category name
score:
type: number
description: Relevance score
taxonomy:
type: string
description: Taxonomy identifier
links:
type: object
properties:
self:
type: string
description: Link to category endpoint
topics:
type: array
items:
type: object
properties:
id:
type: string
description: Topic ID
name:
type: string
description: Topic name
score:
type: number
description: Relevance score
links:
type: object
properties:
self:
type: string
description: Link to topic endpoint
industries:
type: array
items:
type: object
properties:
id:
type: integer
description: Industry ID
name:
type: string
description: Industry name
links:
type: object
properties:
self:
type: string
description: Link to industry endpoint
entities:
type: array
items:
type: object
properties:
id:
type: integer
description: Entity ID
name:
type: string
description: Entity name
type:
type: string
enum:
- person
- location
- organization
- brand
- product
- natural-disaster
- disease
- event
- sport
- unknown
description: Entity type
frequency:
type: integer
description: Number of mentions in the article
sentiment:
type: object
description: Sentiment toward this entity (aggregated across its mentions)
properties:
score:
type: number
description: Entity sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Entity sentiment polarity
mentions:
type: object
description: Per-mention polarity breakdown
properties:
positive:
type: integer
neutral:
type: integer
negative:
type: integer
title:
type: object
properties:
pos:
type: array
items:
type: object
properties:
start:
type: integer
description: Start character offset
end:
type: integer
description: End character offset
description: Mention positions in title
body:
type: object
properties:
pos:
type: array
items:
type: object
properties:
start:
type: integer
description: Start character offset
end:
type: integer
description: End character offset
description: Mention positions in body
links:
type: object
properties:
self:
type: string
description: Link to entity endpoint
wikipedia:
type: string
description: Wikipedia URL
wikidata:
type: string
description: Wikidata URL
metadata:
type: object
description: Additional entity metadata (varies by entity type)
additionalProperties: true
locations_mentioned:
type: array
items:
type: object
properties:
name:
type: string
description: Location name
country:
type: string
description: Country code
lat:
type:
- number
- 'null'
description: Latitude
lng:
type:
- number
- 'null'
description: Longitude
type:
type: string
description: Location type
source:
type: object
properties:
id:
type:
- integer
- 'null'
description: Source ID
domain:
type: string
description: Source domain
home_page_url:
type: string
description: Source home page URL
type:
type: string
description: Source type
bias:
type: string
description: Media bias (left, center, right)
rankings:
type: object
properties:
opr:
type: integer
description: Open PageRank score
location:
type: object
properties:
country_name:
type: string
description: Source country name
country_code:
type: string
description: Source country ISO code
favicon:
type: string
description: Source favicon URL
sentiment:
type: object
properties:
overall:
type: object
properties:
score:
type: number
description: Sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Sentiment polarity
title:
type: object
properties:
score:
type: number
description: Sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Sentiment polarity
body:
type: object
properties:
score:
type: number
description: Sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Sentiment polarity
summary:
type: array
items:
type: object
properties:
sentence:
type: string
description: Summary sentence
sentiment:
type: object
properties:
score:
type: number
description: Sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Sentiment polarity
readability:
type: object
properties:
flesch_kincaid_grade:
type: number
description: Flesch-Kincaid grade level
flesch_reading_ease:
type: number
description: Flesch Reading Ease score (0-100)
automated_readability_index:
type: number
description: Automated Readability Index
difficulty_level:
type: string
enum:
- beginner
- intermediate
- advanced
- expert
- unknown
description: Difficulty level
target_audience:
type: string
enum:
- children
- general
- professional
- academic
- unknown
description: Target audience
reading_age:
type: number
description: Estimated reading age
avg_words_per_sentence:
type: number
description: Average words per sentence
avg_syllables_per_word:
type: number
description: Average syllables per word
keywords:
type: array
items:
type: string
description: Article keywords
links:
type: array
items:
type: object
properties:
url:
type: string
description: Link URL
type:
type: string
description: Link type
media:
type: array
items:
type: object
properties:
url:
type: string
description: Media URL
type:
type: string
description: Media type (image, video, etc.)
shares:
type: object
properties:
total:
type: integer
description: Total social shares
facebook:
type: integer
description: Facebook shares
twitter:
type: integer
description: Twitter/X shares
reddit:
type: integer
description: Reddit shares
story:
type: object
properties:
id:
type: integer
description: Story ID
uri:
type: string
description: Story endpoint URI
is_duplicate:
type: boolean
description: Whether this is a duplicate article
is_free:
type: boolean
description: Whether the article is freely accessible
is_breaking:
type: boolean
description: Whether this is breaking news
read_time:
type: integer
description: Estimated read time in minutes
sentences_count:
type: integer
description: Number of sentences
paragraphs_count:
type: integer
description: Number of paragraphs
words_count:
type: integer
description: Number of words
characters_count:
type: integer
description: Number of characters
description: Array of articles
facets:
type: object
description: Facet results (present when facet.field is specified)
additionalProperties: true
highlighting:
type: object
description: Highlighting results (present when hl=1)
additionalProperties: true
headlines:
type: array
description: Headlines (present in some responses)
items:
type: object
additionalProperties: true
meta:
type: object
description: 'Additional metadata. Present only when there is something to report
about how the request was handled: `prompt` (the request used the prompt parameter)
and/or `warnings` (the query was silently narrowed, e.g. ER0366 clamping a title
search to the last 31 days).'
properties:
prompt:
type: object
description: How the `prompt` parameter was translated into filters. Returned
by every JSON response to a request that used it (the SSE stream has no JSON
envelope, so it carries none).
properties:
text:
type: string
description: The prompt as it was parsed, trimmed
applied:
type: object
description: Parameters the prompt was translated into — the request that
actually ran
additionalProperties:
type: string
ignored:
type: array
description: Values understood but not used
items:
type: object
properties:
field:
type: string
description: Parameter that was not applied
value:
type: string
description: Value the prompt produced for it
reason:
type: string
enum:
- not_found
- explicit_param
- unsupported_on_endpoint
- invalid_date
- title_too_long
- title_window_clamped
description: Why the value was not applied
cached:
type: boolean
description: true when this wording had been parsed before, so no parse fee
was charged
warnings:
type: array
description: Non-fatal notices — the request still returned HTTP 200
items:
type: object
properties:
code:
type: string
description: Warning code, e.g. ER0366
message:
type: string
description: Human-readable explanation
links:
type: object
additionalProperties: true
additionalProperties: true
user_input:
type: object
description: Debug info — original request parameters (present when debug=1)
additionalProperties: true
required:
- status
- limit
- path
- page
- has_next_pages
- has_previous_page
- request_id
- results
example:
status: ok
limit: 50
path: /v1/news/everything
page: 1
has_next_pages: true
next_page: /v1/news/everything?page=2
has_previous_page: false
previous_page: ''
export:
json: /v1/news/everything?export=json
csv: /v1/news/everything?export=csv
rss: /v1/news/everything?export=rss
request_id: req_abc123def456
results:
- id: 84029371
href: https://example.com/article/spacex-launch
published_at: '2026-03-23T14:30:00Z'
title: SpaceX Successfully Launches New Starship Prototype
description: SpaceX completed another successful test flight of its Starship rocket...
language: en
author:
id: 1024
name: Jane Smith
image: https://example.com/images/starship.jpg
categories:
- id: 201
name: Science & Technology
score: 0.95
taxonomy: iptc_mediatopics
topics:
- id: space-exploration
name: Space Exploration
score: 0.92
industries:
- id: 88
name: Aerospace & Defense
entities:
- id: 5012
name: SpaceX
type: organization
frequency: 8
links:
wikipedia: https://en.wikipedia.org/wiki/SpaceX
- id: 3401
name: Elon Musk
type: person
frequency: 3
links:
wikipedia: https://en.wikipedia.org/wiki/Elon_Musk
source:
id: 7823
domain: reuters.com
home_page_url: https://www.reuters.com
type: news_agency
location:
country_name: United States
country_code: us
rankings:
opr: 8
sentiment:
overall:
score: 0.65
polarity: positive
title:
score: 0.72
polarity: positive
body:
score: 0.61
polarity: positive
readability:
flesch_kincaid_grade: 10.2
flesch_reading_ease: 52.3
difficulty_level: intermediate
target_audience: general
keywords:
- spacex
- starship
- rocket
- launch
is_duplicate: false
is_breaking: true
read_time: 4
words_count: 847
'400':
description: Article ID is required
content:
application/json:
schema:
description: Article ID is required
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
'401':
description: Authentication error
content:
application/json:
schema:
description: Authentication error
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
description: Rate limit exceeded
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
/v1/news/category/{taxonomy}/{categoryId}:
post:
summary: Get articles by category
tags:
- News
description: Returns articles for a specific category within a taxonomy. Supports the same filtering,
faceting, highlighting, and export options as /v1/news/everything.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
prompt:
type: string
minLength: 3
maxLength: 500
description: 'Plain-language description of the news you want, e.g. "Elon Musk, Tesla,
news for the last 10 days". It is translated into the regular filters below before
the search runs, and the resulting parameters are returned in meta.prompt. Explicit
parameters always win over the prompt. Costs 2 extra points when the wording has not
been parsed before (repeats are served from cache). Available on Basic and above —
on Free and Starter the request fails with 403 ER0706. Errors: ER0706 (plan), ER0800
(length), ER0801 (translation service unavailable), ER0802 (nothing usable in the
prompt).'
page:
type: integer
minimum: 1
default: 1
description: Page number for pagination
per_page:
type: integer
minimum: 1
maximum: 250
default: 100
description: Number of results per page (max 250; the Free plan is capped at 10 and
Starter at 50)
sort.by:
type: string
enum:
- published_at
- relevance
- engagement
- quality
- controversy
- trust
- id
- new
- created_at
- source.rank.opr
- sentiment.overall.score
- sentiment.title.score
- sentiment.body.score
- read_time
- sentences_count
- paragraphs_count
- characters_count
- media.images.count
- media.videos.count
- media.images.width.min
- media.images.width.max
- media.images.height.min
- media.images.height.max
- media_richness
- shares.facebook.min
- shares.facebook.max
- shares.twitter.min
- shares.twitter.max
- shares.reddit.min
- shares.reddit.max
default: published_at
description: Field to sort results by
sort.order:
type: string
enum:
- asc
- desc
default: desc
description: Sort order
article.id:
type: string
description: Comma-separated article IDs (max 5)
example: '12345'
title:
type: string
minLength: 2
maxLength: 100
description: 'Search in article titles. Supports phrase search with proximity: "climate
change"~2. Title search is limited to a 31-day published_at window: without published_at.start
/ published_at.end the last 31 days are searched, a wider explicit range returns ER0110.'
ignore.title:
type: string
minLength: 2
maxLength: 100
description: Exclude articles containing this text in the title
title_starts_with:
type: string
minLength: 2
maxLength: 100
description: Filter articles whose title starts with the given text. Same 31-day window
limit as title
title_ends_with:
type: string
minLength: 2
maxLength: 100
description: Filter articles whose title ends with the given text. Same 31-day window
limit as title
title_pattern:
type: string
minLength: 2
maxLength: 200
description: Filter articles whose title matches the given pattern. Same 31-day window
limit as title
published_at:
type: string
description: 'Exact date (creates 24-hour range). Format: YYYY-MM-DD or ISO 8601'
example: '2025-01-15'
published_at.start:
type: string
description: 'Start of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title
search the range may not exceed 31 days (ER0110)'
example: '2025-01-01'
published_at.end:
type: string
description: 'End of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title
search the range may not exceed 31 days (ER0110)'
example: '2025-01-31'
language.code:
type: string
description: Comma-separated ISO 639-1 language codes (max 3)
example: en
ignore.language.code:
type: string
description: Exclude articles in these languages (comma-separated, max 3)
example: zh,ar
source.country.code:
type: string
description: Filter by source country ISO 3166-1 alpha-2 codes (comma-separated, max
3)
example: us
ignore.source.country.code:
type: string
description: Exclude sources from these countries (comma-separated, max 3)
example: us
source.rank.opr.min:
type: integer
minimum: 0
description: Minimum Open PageRank score
source.rank.opr.max:
type: integer
minimum: 0
description: Maximum Open PageRank score
source.id:
type: string
description: Comma-separated source IDs (max 3)
example: '100'
ignore.source.id:
type: string
description: Exclude these source IDs (comma-separated, max 3)
source.domain:
type: string
description: Comma-separated source domains (max 3)
example: nytimes.com
ignore.source.domain:
type: string
description: Exclude these source domains (comma-separated, max 3)
source.bias:
type: string
description: 'Filter by media bias (comma-separated). Values: left, center, right'
example: left
ignore.source.bias:
type: string
description: 'Exclude sources with this media bias (comma-separated). Values: left,
center, right'
example: right
is_premium_source:
type: integer
enum:
- 0
- 1
description: Filter by premium source status
is_verified_source:
type: integer
enum:
- 0
- 1
description: Filter by verified source status
category.id:
type: string
description: Comma-separated category IDs (max 3)
example: iab-1
ignore.category.id:
type: string
description: Exclude these categories (comma-separated, max 3)
topic.id:
type: string
description: Comma-separated topic IDs (max 3)
example: technology
ignore.topic.id:
type: string
description: Exclude these topics (comma-separated, max 3)
industry.id:
type: string
description: Comma-separated industry IDs (max 3)
example: '1'
ignore.industry.id:
type: string
description: Exclude these industries (comma-separated, max 3)
entity.id:
type: string
description: Comma-separated entity IDs (max 3)
example: '12345'
ignore.entity.id:
type: string
description: Exclude these entity IDs (comma-separated, max 3)
entity.sentiment.polarity:
type: string
enum:
- positive
- negative
- neutral
description: Filter by sentiment polarity toward the entity (combine with entity.id
or *.name; standalone = any entity)
entity.sentiment.score.min:
type: number
minimum: -1
maximum: 1
description: Minimum sentiment score toward the entity
entity.sentiment.score.max:
type: number
minimum: -1
maximum: 1
description: Maximum sentiment score toward the entity
person.name:
type: string
maxLength: 120
description: Filter by person name (comma-separated, max 3)
example: Elon Musk
ignore.person.name:
type: string
maxLength: 120
description: Exclude articles mentioning these persons (comma-separated, max 3)
organization.name:
type: string
maxLength: 120
description: Filter by organization name (comma-separated, max 3)
example: Google
ignore.organization.name:
type: string
maxLength: 120
description: Exclude articles mentioning these organizations (comma-separated, max 3)
location.name:
type: string
maxLength: 120
description: Filter by location name (comma-separated, max 3)
example: New York
ignore.location.name:
type: string
maxLength: 120
description: Exclude articles mentioning these locations (comma-separated, max 3)
brand.name:
type: string
maxLength: 120
description: Filter by brand name (comma-separated, max 3)
ignore.brand.name:
type: string
maxLength: 120
description: Exclude articles mentioning these brands (comma-separated, max 3)
disaster.name:
type: string
maxLength: 120
description: Filter by natural disaster name (comma-separated, max 3)
ignore.disaster.name:
type: string
maxLength: 120
description: Exclude articles mentioning these disasters (comma-separated, max 3)
disease.name:
type: string
maxLength: 120
description: Filter by disease name (comma-separated, max 3)
ignore.disease.name:
type: string
maxLength: 120
description: Exclude articles mentioning these diseases (comma-separated, max 3)
event.name:
type: string
maxLength: 120
description: Filter by event name (comma-separated, max 3)
ignore.event.name:
type: string
maxLength: 120
description: Exclude articles mentioning these events (comma-separated, max 3)
sport.name:
type: string
maxLength: 120
description: Filter by sport name (comma-separated, max 3)
ignore.sport.name:
type: string
maxLength: 120
description: Exclude articles mentioning these sports (comma-separated, max 3)
event.type:
type: string
description: 'Comma-separated event types (max 5). Values: merger-acquisition, ipo,
layoffs, bankruptcy, product-launch, funding-round, earnings, partnership, executive-change,
lawsuit, data-breach, recall, expansion, closure, stock-movement, contract-award,
spin-off, regulatory-action, election, protest, crime, terrorism, accident, policy-change,
scandal, death, award-ceremony, conflict, diplomacy, health-crisis, migration, human-rights,
earthquake, hurricane, flood, wildfire, tornado, tsunami, volcanic-eruption, drought,
climate-event, pollution, wildlife-event, avalanche'
example: ipo
event.category:
type: string
enum:
- business
- society
- environment
description: Filter by event category
ignore.event.type:
type: string
description: Exclude these event types (comma-separated, max 5)
sentiment.overall.score:
type: number
minimum: -1
maximum: 1
description: Exact overall sentiment score
sentiment.overall.score.min:
type: number
minimum: -1
maximum: 1
description: Minimum overall sentiment score
sentiment.overall.score.max:
type: number
minimum: -1
maximum: 1
description: Maximum overall sentiment score
sentiment.overall.polarity:
type: string
enum:
- positive
- negative
- neutral
description: Overall sentiment polarity
sentiment.title.score:
type: number
minimum: -1
maximum: 1
description: Exact title sentiment score
sentiment.title.score.min:
type: number
minimum: -1
maximum: 1
description: Minimum title sentiment score
sentiment.title.score.max:
type: number
minimum: -1
maximum: 1
description: Maximum title sentiment score
sentiment.title.polarity:
type: string
enum:
- positive
- negative
- neutral
description: Title sentiment polarity
sentiment.body.score:
type: number
minimum: -1
maximum: 1
description: Exact body sentiment score
sentiment.body.score.min:
type: number
minimum: -1
maximum: 1
description: Minimum body sentiment score
sentiment.body.score.max:
type: number
minimum: -1
maximum: 1
description: Maximum body sentiment score
sentiment.body.polarity:
type: string
enum:
- positive
- negative
- neutral
description: Body sentiment polarity
sentiment.mixed:
type: integer
enum:
- 0
- 1
description: Filter for mixed sentiment (title polarity != body polarity)
sentiment.consistent:
type: integer
enum:
- 0
- 1
description: Filter for consistent sentiment (title polarity == body polarity)
is_clickbait:
type: integer
enum:
- 0
- 1
description: Filter by clickbait detection
sentiment_gap.min:
type: number
minimum: 0
maximum: 2
description: Minimum sentiment gap between title and body
sentiment_gap.max:
type: number
minimum: 0
maximum: 2
description: Maximum sentiment gap between title and body
media.images.count:
type: integer
minimum: 0
description: Exact number of images
media.images.count.min:
type: integer
minimum: 0
description: Minimum number of images
media.images.count.max:
type: integer
minimum: 0
description: Maximum number of images
media.images.width.min:
type: integer
minimum: 0
description: Minimum image width in pixels
media.images.width.max:
type: integer
minimum: 0
description: Maximum image width in pixels
media.images.height.min:
type: integer
minimum: 0
description: Minimum image height in pixels
media.images.height.max:
type: integer
minimum: 0
description: Maximum image height in pixels
media.videos.count:
type: integer
minimum: 0
description: Exact number of videos
media.videos.count.min:
type: integer
minimum: 0
description: Minimum number of videos
media.videos.count.max:
type: integer
minimum: 0
description: Maximum number of videos
has_image:
type: integer
enum:
- 0
- 1
description: Filter articles with/without images
has_video:
type: integer
enum:
- 0
- 1
description: Filter articles with/without videos
has_hq_images:
type: integer
enum:
- 0
- 1
description: Filter articles with high-quality images (>= 1200px width)
is_media_rich:
type: integer
enum:
- 0
- 1
description: Filter articles with both images and videos
is_landscape_media:
type: integer
enum:
- 0
- 1
description: Filter articles with landscape-oriented media
is_portrait_media:
type: integer
enum:
- 0
- 1
description: Filter articles with portrait-oriented media
has_multiple_images:
type: integer
enum:
- 0
- 1
description: Filter articles with 2+ images
has_fullhd_images:
type: integer
enum:
- 0
- 1
description: Filter articles with Full HD images (>= 1920px width)
has_4k_images:
type: integer
enum:
- 0
- 1
description: Filter articles with 4K images (>= 3840px width)
has_mobile_optimized_images:
type: integer
enum:
- 0
- 1
description: Filter articles with mobile-optimized images (320-800px width)
is_instagram_ready:
type: integer
enum:
- 0
- 1
description: Filter articles with Instagram-ready images (>= 1080px + aspect ratio)
is_twitter_card_ready:
type: integer
enum:
- 0
- 1
description: Filter articles with Twitter Card-ready images (>= 800px + landscape)
has_consistent_image_sizes:
type: integer
enum:
- 0
- 1
description: Filter articles with consistent image dimensions
has_thumbnail:
type: integer
enum:
- 0
- 1
description: Filter articles with thumbnail images (<= 300px width)
has_social_share_image:
type: integer
enum:
- 0
- 1
description: Filter articles with social share images (>= 1200x630px)
has_mixed_media:
type: integer
enum:
- 0
- 1
description: Filter articles with both image and video media types
readability.fk_grade:
type: number
minimum: 0
maximum: 30
description: Exact Flesch-Kincaid grade level
readability.fk_grade.min:
type: number
minimum: 0
maximum: 30
description: Minimum Flesch-Kincaid grade level
readability.fk_grade.max:
type: number
minimum: 0
maximum: 30
description: Maximum Flesch-Kincaid grade level
readability.ease:
type: number
minimum: 0
maximum: 100
description: Exact Flesch Reading Ease score
readability.ease.min:
type: number
minimum: 0
maximum: 100
description: Minimum Flesch Reading Ease score
readability.ease.max:
type: number
minimum: 0
maximum: 100
description: Maximum Flesch Reading Ease score
readability.ari:
type: number
minimum: 0
maximum: 30
description: Exact Automated Readability Index
readability.ari.min:
type: number
minimum: 0
maximum: 30
description: Minimum Automated Readability Index
readability.ari.max:
type: number
minimum: 0
maximum: 30
description: Maximum Automated Readability Index
readability.difficulty:
type: string
enum:
- beginner
- intermediate
- advanced
- expert
description: Difficulty level
readability.audience:
type: string
enum:
- children
- general
- professional
- academic
description: Target audience
readability.age:
type: integer
minimum: 6
maximum: 22
description: Exact reading age
readability.age.min:
type: integer
minimum: 6
maximum: 22
description: Minimum reading age
readability.age.max:
type: integer
minimum: 6
maximum: 22
description: Maximum reading age
is_easy_read:
type: integer
enum:
- 0
- 1
description: Filter for easy-to-read articles (Flesch Reading Ease >= 60)
is_difficult_read:
type: integer
enum:
- 0
- 1
description: Filter for difficult-to-read articles (Flesch Reading Ease < 40)
read_time:
type: integer
minimum: 0
maximum: 1000
description: Exact read time in minutes
read_time.min:
type: integer
minimum: 0
maximum: 1000
description: Minimum read time in minutes
read_time.max:
type: integer
minimum: 0
maximum: 1000
description: Maximum read time in minutes
is_long_read:
type: integer
enum:
- 0
- 1
description: Filter for long reads (>= 5 minutes)
is_short_read:
type: integer
enum:
- 0
- 1
description: Filter for short reads (< 3 minutes)
is_quick_read:
type: integer
enum:
- 0
- 1
description: Filter for quick reads (<= 2 minutes)
is_medium_read:
type: integer
enum:
- 0
- 1
description: Filter for medium-length reads (3-7 minutes)
is_deep_dive:
type: integer
enum:
- 0
- 1
description: Filter for deep dives (>= 10 minutes)
location.bbox:
type: string
description: 'Bounding box: minLat,maxLat,minLng,maxLng'
example: 40.0,41.0,-74.5,-73.5
has_location_geo:
type: integer
enum:
- 0
- 1
description: Filter articles with/without geo-location data
location.lat:
type: number
minimum: -90
maximum: 90
description: Latitude for radius search
location.lng:
type: number
minimum: -180
maximum: 180
description: Longitude for radius search
location.radius:
type: number
exclusiveMinimum: 0
maximum: 20000
description: Search radius in kilometers (requires location.lat and location.lng)
location.radius.min:
type: number
minimum: 0
maximum: 20000
description: Minimum distance from point in km
is_duplicate:
type: integer
enum:
- 0
- 1
description: Filter duplicate/unique articles
is_paywall:
type: integer
enum:
- 0
- 1
description: Filter paywalled articles
is_breaking:
type: integer
enum:
- 0
- 1
description: Filter breaking news articles
is_high_quality:
type: integer
enum:
- 0
- 1
description: Filter high-quality articles (not duplicate, rank >= 5, has images, has
author)
author.id:
type: string
description: Comma-separated author IDs (max 3)
ignore.author.id:
type: string
description: Exclude these author IDs (comma-separated, max 3)
author.name:
type: string
maxLength: 100
description: Filter by author name (comma-separated, max 3)
ignore.author.name:
type: string
maxLength: 100
description: Exclude articles by these authors (comma-separated, max 3)
has_author:
type: integer
enum:
- 0
- 1
description: Filter articles with/without author
facet:
type: string
enum:
- '0'
- '1'
description: Enable faceting
facet.field:
type: string
description: 'Comma-separated facet fields (max 5). Values: source.id, source.country.id,
source.bias, language.id, author.id, category.id, topic.id, industry.id, entity.id,
sentiment.overall.polarity, sentiment.title.polarity, sentiment.body.polarity, sentiment.strength,
is_duplicate, is_free, is_important, media.images.count, media.videos.count, read_time,
content.length, published.year, published.month, published.day_of_week, published.hour,
published.weekday, published.time_of_day'
example: source.id,category.id
facet.limit:
type: integer
minimum: 1
maximum: 100
default: 10
description: Maximum number of facet values per field (max 100)
facet.mincount:
type: integer
minimum: 1
default: 1
description: Minimum count for a facet value to be included
facet.range:
type: string
enum:
- '0'
- '1'
description: Enable range faceting
facet.range.field:
type: string
description: 'Field for range faceting. Values: published_at, sentiment.overall.score,
sentiment.title.score, sentiment.body.score, read_time, source.rank.opr, media.images.count,
media.videos.count'
facet.range.start:
type: string
description: Start value for range faceting (required with facet.range)
facet.range.end:
type: string
description: End value for range faceting (required with facet.range)
facet.range.gap:
type: string
default: +1DAY
description: Gap value for range faceting
hl:
type: string
enum:
- '0'
- '1'
description: Enable highlighting
hl.fl:
type: string
default: title,description
description: 'Comma-separated fields to highlight (max 5). Values: title, description,
body'
example: title,description
hl.fragsize:
type: integer
minimum: 50
maximum: 500
default: 150
description: Size of highlighted fragment in characters (50-500)
hl.snippets:
type: integer
minimum: 1
maximum: 10
default: 3
description: Number of highlighted snippets per field (max 10)
hl.tag.pre:
type: string
description: Opening tag for highlighted text
default:
hl.tag.post:
type: string
description: Closing tag for highlighted text
default:
export:
type: string
enum:
- json
- csv
- tsv
- xml
- rss
- xlsx
- parquet
- jsonl
- ndjson
description: Export format
fl:
type: string
description: Comma-separated list of fields to include in the response
example: id,title,published_at,source.domain
debug:
type: string
enum:
- '0'
- '1'
description: Include user_input in response for debugging
api_key:
type: string
description: API key (alternative to X-API-Key header)
parameters:
- schema:
type: string
in: path
name: taxonomy
required: true
description: Category taxonomy (e.g. iptc_mediatopics)
- schema:
type: string
in: path
name: categoryId
required: true
description: Category ID
responses:
'200':
description: Successful response with articles
content:
application/json:
schema:
description: Successful response with articles
type: object
properties:
status:
type: string
enum:
- ok
description: Response status
limit:
type: integer
description: Results per page
path:
type: string
description: Current request URL
page:
type: integer
description: Current page number
has_next_pages:
type: boolean
description: Whether more pages are available
next_page:
type: string
description: URL for the next page (empty if no next page)
has_previous_page:
type: boolean
description: Whether a previous page exists
previous_page:
type: string
description: URL for the previous page (empty if no previous page)
export:
type: object
description: Export format URLs
properties:
json:
type: string
xlsx:
type: string
csv:
type: string
tsv:
type: string
xml:
type: string
rss:
type: string
parquet:
type: string
jsonl:
type: string
request_id:
type: string
description: Unique request identifier
results:
type: array
items:
type: object
properties:
id:
type: integer
description: Unique article ID
href:
type:
- string
- 'null'
description: Original article URL
published_at:
type:
- string
- 'null'
format: date-time
description: Publication date in ISO 8601
title:
type:
- string
- 'null'
description: Article title
description:
type:
- string
- 'null'
description: Article description (plain text)
body:
type:
- string
- 'null'
description: Article body (plain text)
body_html:
type:
- string
- 'null'
description: Article body (HTML)
language:
type: string
description: ISO 639-1 language code
translations:
type: object
description: Machine translations of the article title and description. Always
present; fields stay null for English articles and for languages without a
translation model
properties:
en:
type: object
properties:
title:
type:
- string
- 'null'
description: Title translated to English
description:
type:
- string
- 'null'
description: Description translated to English (plain text)
author:
type: object
properties:
id:
type:
- integer
- 'null'
description: Author ID
name:
type: string
description: Author name
image:
type: string
description: Main article image URL
categories:
type: array
items:
type: object
properties:
id:
type: integer
description: Category ID
name:
type: string
description: Category name
score:
type: number
description: Relevance score
taxonomy:
type: string
description: Taxonomy identifier
links:
type: object
properties:
self:
type: string
description: Link to category endpoint
topics:
type: array
items:
type: object
properties:
id:
type: string
description: Topic ID
name:
type: string
description: Topic name
score:
type: number
description: Relevance score
links:
type: object
properties:
self:
type: string
description: Link to topic endpoint
industries:
type: array
items:
type: object
properties:
id:
type: integer
description: Industry ID
name:
type: string
description: Industry name
links:
type: object
properties:
self:
type: string
description: Link to industry endpoint
entities:
type: array
items:
type: object
properties:
id:
type: integer
description: Entity ID
name:
type: string
description: Entity name
type:
type: string
enum:
- person
- location
- organization
- brand
- product
- natural-disaster
- disease
- event
- sport
- unknown
description: Entity type
frequency:
type: integer
description: Number of mentions in the article
sentiment:
type: object
description: Sentiment toward this entity (aggregated across its mentions)
properties:
score:
type: number
description: Entity sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Entity sentiment polarity
mentions:
type: object
description: Per-mention polarity breakdown
properties:
positive:
type: integer
neutral:
type: integer
negative:
type: integer
title:
type: object
properties:
pos:
type: array
items:
type: object
properties:
start:
type: integer
description: Start character offset
end:
type: integer
description: End character offset
description: Mention positions in title
body:
type: object
properties:
pos:
type: array
items:
type: object
properties:
start:
type: integer
description: Start character offset
end:
type: integer
description: End character offset
description: Mention positions in body
links:
type: object
properties:
self:
type: string
description: Link to entity endpoint
wikipedia:
type: string
description: Wikipedia URL
wikidata:
type: string
description: Wikidata URL
metadata:
type: object
description: Additional entity metadata (varies by entity type)
additionalProperties: true
locations_mentioned:
type: array
items:
type: object
properties:
name:
type: string
description: Location name
country:
type: string
description: Country code
lat:
type:
- number
- 'null'
description: Latitude
lng:
type:
- number
- 'null'
description: Longitude
type:
type: string
description: Location type
source:
type: object
properties:
id:
type:
- integer
- 'null'
description: Source ID
domain:
type: string
description: Source domain
home_page_url:
type: string
description: Source home page URL
type:
type: string
description: Source type
bias:
type: string
description: Media bias (left, center, right)
rankings:
type: object
properties:
opr:
type: integer
description: Open PageRank score
location:
type: object
properties:
country_name:
type: string
description: Source country name
country_code:
type: string
description: Source country ISO code
favicon:
type: string
description: Source favicon URL
sentiment:
type: object
properties:
overall:
type: object
properties:
score:
type: number
description: Sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Sentiment polarity
title:
type: object
properties:
score:
type: number
description: Sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Sentiment polarity
body:
type: object
properties:
score:
type: number
description: Sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Sentiment polarity
summary:
type: array
items:
type: object
properties:
sentence:
type: string
description: Summary sentence
sentiment:
type: object
properties:
score:
type: number
description: Sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Sentiment polarity
readability:
type: object
properties:
flesch_kincaid_grade:
type: number
description: Flesch-Kincaid grade level
flesch_reading_ease:
type: number
description: Flesch Reading Ease score (0-100)
automated_readability_index:
type: number
description: Automated Readability Index
difficulty_level:
type: string
enum:
- beginner
- intermediate
- advanced
- expert
- unknown
description: Difficulty level
target_audience:
type: string
enum:
- children
- general
- professional
- academic
- unknown
description: Target audience
reading_age:
type: number
description: Estimated reading age
avg_words_per_sentence:
type: number
description: Average words per sentence
avg_syllables_per_word:
type: number
description: Average syllables per word
keywords:
type: array
items:
type: string
description: Article keywords
links:
type: array
items:
type: object
properties:
url:
type: string
description: Link URL
type:
type: string
description: Link type
media:
type: array
items:
type: object
properties:
url:
type: string
description: Media URL
type:
type: string
description: Media type (image, video, etc.)
shares:
type: object
properties:
total:
type: integer
description: Total social shares
facebook:
type: integer
description: Facebook shares
twitter:
type: integer
description: Twitter/X shares
reddit:
type: integer
description: Reddit shares
story:
type: object
properties:
id:
type: integer
description: Story ID
uri:
type: string
description: Story endpoint URI
is_duplicate:
type: boolean
description: Whether this is a duplicate article
is_free:
type: boolean
description: Whether the article is freely accessible
is_breaking:
type: boolean
description: Whether this is breaking news
read_time:
type: integer
description: Estimated read time in minutes
sentences_count:
type: integer
description: Number of sentences
paragraphs_count:
type: integer
description: Number of paragraphs
words_count:
type: integer
description: Number of words
characters_count:
type: integer
description: Number of characters
description: Array of articles
facets:
type: object
description: Facet results (present when facet.field is specified)
additionalProperties: true
highlighting:
type: object
description: Highlighting results (present when hl=1)
additionalProperties: true
headlines:
type: array
description: Headlines (present in some responses)
items:
type: object
additionalProperties: true
meta:
type: object
description: 'Additional metadata. Present only when there is something to report
about how the request was handled: `prompt` (the request used the prompt parameter)
and/or `warnings` (the query was silently narrowed, e.g. ER0366 clamping a title
search to the last 31 days).'
properties:
prompt:
type: object
description: How the `prompt` parameter was translated into filters. Returned
by every JSON response to a request that used it (the SSE stream has no JSON
envelope, so it carries none).
properties:
text:
type: string
description: The prompt as it was parsed, trimmed
applied:
type: object
description: Parameters the prompt was translated into — the request that
actually ran
additionalProperties:
type: string
ignored:
type: array
description: Values understood but not used
items:
type: object
properties:
field:
type: string
description: Parameter that was not applied
value:
type: string
description: Value the prompt produced for it
reason:
type: string
enum:
- not_found
- explicit_param
- unsupported_on_endpoint
- invalid_date
- title_too_long
- title_window_clamped
description: Why the value was not applied
cached:
type: boolean
description: true when this wording had been parsed before, so no parse fee
was charged
warnings:
type: array
description: Non-fatal notices — the request still returned HTTP 200
items:
type: object
properties:
code:
type: string
description: Warning code, e.g. ER0366
message:
type: string
description: Human-readable explanation
links:
type: object
additionalProperties: true
additionalProperties: true
user_input:
type: object
description: Debug info — original request parameters (present when debug=1)
additionalProperties: true
required:
- status
- limit
- path
- page
- has_next_pages
- has_previous_page
- request_id
- results
example:
status: ok
limit: 50
path: /v1/news/everything
page: 1
has_next_pages: true
next_page: /v1/news/everything?page=2
has_previous_page: false
previous_page: ''
export:
json: /v1/news/everything?export=json
csv: /v1/news/everything?export=csv
rss: /v1/news/everything?export=rss
request_id: req_abc123def456
results:
- id: 84029371
href: https://example.com/article/spacex-launch
published_at: '2026-03-23T14:30:00Z'
title: SpaceX Successfully Launches New Starship Prototype
description: SpaceX completed another successful test flight of its Starship rocket...
language: en
author:
id: 1024
name: Jane Smith
image: https://example.com/images/starship.jpg
categories:
- id: 201
name: Science & Technology
score: 0.95
taxonomy: iptc_mediatopics
topics:
- id: space-exploration
name: Space Exploration
score: 0.92
industries:
- id: 88
name: Aerospace & Defense
entities:
- id: 5012
name: SpaceX
type: organization
frequency: 8
links:
wikipedia: https://en.wikipedia.org/wiki/SpaceX
- id: 3401
name: Elon Musk
type: person
frequency: 3
links:
wikipedia: https://en.wikipedia.org/wiki/Elon_Musk
source:
id: 7823
domain: reuters.com
home_page_url: https://www.reuters.com
type: news_agency
location:
country_name: United States
country_code: us
rankings:
opr: 8
sentiment:
overall:
score: 0.65
polarity: positive
title:
score: 0.72
polarity: positive
body:
score: 0.61
polarity: positive
readability:
flesch_kincaid_grade: 10.2
flesch_reading_ease: 52.3
difficulty_level: intermediate
target_audience: general
keywords:
- spacex
- starship
- rocket
- launch
is_duplicate: false
is_breaking: true
read_time: 4
words_count: 847
'401':
description: Authentication error
content:
application/json:
schema:
description: Authentication error
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
'404':
description: Category not found
content:
application/json:
schema:
description: Category not found
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
description: Rate limit exceeded
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
/v1/news/topic/{topicId}:
post:
summary: Get articles by topic
tags:
- News
description: Returns articles for a specific topic. Supports the same filtering, faceting, highlighting,
and export options as /v1/news/everything.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
prompt:
type: string
minLength: 3
maxLength: 500
description: 'Plain-language description of the news you want, e.g. "Elon Musk, Tesla,
news for the last 10 days". It is translated into the regular filters below before
the search runs, and the resulting parameters are returned in meta.prompt. Explicit
parameters always win over the prompt. Costs 2 extra points when the wording has not
been parsed before (repeats are served from cache). Available on Basic and above —
on Free and Starter the request fails with 403 ER0706. Errors: ER0706 (plan), ER0800
(length), ER0801 (translation service unavailable), ER0802 (nothing usable in the
prompt).'
page:
type: integer
minimum: 1
default: 1
description: Page number for pagination
per_page:
type: integer
minimum: 1
maximum: 250
default: 100
description: Number of results per page (max 250; the Free plan is capped at 10 and
Starter at 50)
sort.by:
type: string
enum:
- published_at
- relevance
- engagement
- quality
- controversy
- trust
- id
- new
- created_at
- source.rank.opr
- sentiment.overall.score
- sentiment.title.score
- sentiment.body.score
- read_time
- sentences_count
- paragraphs_count
- characters_count
- media.images.count
- media.videos.count
- media.images.width.min
- media.images.width.max
- media.images.height.min
- media.images.height.max
- media_richness
- shares.facebook.min
- shares.facebook.max
- shares.twitter.min
- shares.twitter.max
- shares.reddit.min
- shares.reddit.max
default: published_at
description: Field to sort results by
sort.order:
type: string
enum:
- asc
- desc
default: desc
description: Sort order
article.id:
type: string
description: Comma-separated article IDs (max 5)
example: '12345'
title:
type: string
minLength: 2
maxLength: 100
description: 'Search in article titles. Supports phrase search with proximity: "climate
change"~2. Title search is limited to a 31-day published_at window: without published_at.start
/ published_at.end the last 31 days are searched, a wider explicit range returns ER0110.'
ignore.title:
type: string
minLength: 2
maxLength: 100
description: Exclude articles containing this text in the title
title_starts_with:
type: string
minLength: 2
maxLength: 100
description: Filter articles whose title starts with the given text. Same 31-day window
limit as title
title_ends_with:
type: string
minLength: 2
maxLength: 100
description: Filter articles whose title ends with the given text. Same 31-day window
limit as title
title_pattern:
type: string
minLength: 2
maxLength: 200
description: Filter articles whose title matches the given pattern. Same 31-day window
limit as title
published_at:
type: string
description: 'Exact date (creates 24-hour range). Format: YYYY-MM-DD or ISO 8601'
example: '2025-01-15'
published_at.start:
type: string
description: 'Start of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title
search the range may not exceed 31 days (ER0110)'
example: '2025-01-01'
published_at.end:
type: string
description: 'End of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title
search the range may not exceed 31 days (ER0110)'
example: '2025-01-31'
language.code:
type: string
description: Comma-separated ISO 639-1 language codes (max 3)
example: en
ignore.language.code:
type: string
description: Exclude articles in these languages (comma-separated, max 3)
example: zh,ar
source.country.code:
type: string
description: Filter by source country ISO 3166-1 alpha-2 codes (comma-separated, max
3)
example: us
ignore.source.country.code:
type: string
description: Exclude sources from these countries (comma-separated, max 3)
example: us
source.rank.opr.min:
type: integer
minimum: 0
description: Minimum Open PageRank score
source.rank.opr.max:
type: integer
minimum: 0
description: Maximum Open PageRank score
source.id:
type: string
description: Comma-separated source IDs (max 3)
example: '100'
ignore.source.id:
type: string
description: Exclude these source IDs (comma-separated, max 3)
source.domain:
type: string
description: Comma-separated source domains (max 3)
example: nytimes.com
ignore.source.domain:
type: string
description: Exclude these source domains (comma-separated, max 3)
source.bias:
type: string
description: 'Filter by media bias (comma-separated). Values: left, center, right'
example: left
ignore.source.bias:
type: string
description: 'Exclude sources with this media bias (comma-separated). Values: left,
center, right'
example: right
is_premium_source:
type: integer
enum:
- 0
- 1
description: Filter by premium source status
is_verified_source:
type: integer
enum:
- 0
- 1
description: Filter by verified source status
category.id:
type: string
description: Comma-separated category IDs (max 3)
example: iab-1
ignore.category.id:
type: string
description: Exclude these categories (comma-separated, max 3)
topic.id:
type: string
description: Comma-separated topic IDs (max 3)
example: technology
ignore.topic.id:
type: string
description: Exclude these topics (comma-separated, max 3)
industry.id:
type: string
description: Comma-separated industry IDs (max 3)
example: '1'
ignore.industry.id:
type: string
description: Exclude these industries (comma-separated, max 3)
entity.id:
type: string
description: Comma-separated entity IDs (max 3)
example: '12345'
ignore.entity.id:
type: string
description: Exclude these entity IDs (comma-separated, max 3)
entity.sentiment.polarity:
type: string
enum:
- positive
- negative
- neutral
description: Filter by sentiment polarity toward the entity (combine with entity.id
or *.name; standalone = any entity)
entity.sentiment.score.min:
type: number
minimum: -1
maximum: 1
description: Minimum sentiment score toward the entity
entity.sentiment.score.max:
type: number
minimum: -1
maximum: 1
description: Maximum sentiment score toward the entity
person.name:
type: string
maxLength: 120
description: Filter by person name (comma-separated, max 3)
example: Elon Musk
ignore.person.name:
type: string
maxLength: 120
description: Exclude articles mentioning these persons (comma-separated, max 3)
organization.name:
type: string
maxLength: 120
description: Filter by organization name (comma-separated, max 3)
example: Google
ignore.organization.name:
type: string
maxLength: 120
description: Exclude articles mentioning these organizations (comma-separated, max 3)
location.name:
type: string
maxLength: 120
description: Filter by location name (comma-separated, max 3)
example: New York
ignore.location.name:
type: string
maxLength: 120
description: Exclude articles mentioning these locations (comma-separated, max 3)
brand.name:
type: string
maxLength: 120
description: Filter by brand name (comma-separated, max 3)
ignore.brand.name:
type: string
maxLength: 120
description: Exclude articles mentioning these brands (comma-separated, max 3)
disaster.name:
type: string
maxLength: 120
description: Filter by natural disaster name (comma-separated, max 3)
ignore.disaster.name:
type: string
maxLength: 120
description: Exclude articles mentioning these disasters (comma-separated, max 3)
disease.name:
type: string
maxLength: 120
description: Filter by disease name (comma-separated, max 3)
ignore.disease.name:
type: string
maxLength: 120
description: Exclude articles mentioning these diseases (comma-separated, max 3)
event.name:
type: string
maxLength: 120
description: Filter by event name (comma-separated, max 3)
ignore.event.name:
type: string
maxLength: 120
description: Exclude articles mentioning these events (comma-separated, max 3)
sport.name:
type: string
maxLength: 120
description: Filter by sport name (comma-separated, max 3)
ignore.sport.name:
type: string
maxLength: 120
description: Exclude articles mentioning these sports (comma-separated, max 3)
event.type:
type: string
description: 'Comma-separated event types (max 5). Values: merger-acquisition, ipo,
layoffs, bankruptcy, product-launch, funding-round, earnings, partnership, executive-change,
lawsuit, data-breach, recall, expansion, closure, stock-movement, contract-award,
spin-off, regulatory-action, election, protest, crime, terrorism, accident, policy-change,
scandal, death, award-ceremony, conflict, diplomacy, health-crisis, migration, human-rights,
earthquake, hurricane, flood, wildfire, tornado, tsunami, volcanic-eruption, drought,
climate-event, pollution, wildlife-event, avalanche'
example: ipo
event.category:
type: string
enum:
- business
- society
- environment
description: Filter by event category
ignore.event.type:
type: string
description: Exclude these event types (comma-separated, max 5)
sentiment.overall.score:
type: number
minimum: -1
maximum: 1
description: Exact overall sentiment score
sentiment.overall.score.min:
type: number
minimum: -1
maximum: 1
description: Minimum overall sentiment score
sentiment.overall.score.max:
type: number
minimum: -1
maximum: 1
description: Maximum overall sentiment score
sentiment.overall.polarity:
type: string
enum:
- positive
- negative
- neutral
description: Overall sentiment polarity
sentiment.title.score:
type: number
minimum: -1
maximum: 1
description: Exact title sentiment score
sentiment.title.score.min:
type: number
minimum: -1
maximum: 1
description: Minimum title sentiment score
sentiment.title.score.max:
type: number
minimum: -1
maximum: 1
description: Maximum title sentiment score
sentiment.title.polarity:
type: string
enum:
- positive
- negative
- neutral
description: Title sentiment polarity
sentiment.body.score:
type: number
minimum: -1
maximum: 1
description: Exact body sentiment score
sentiment.body.score.min:
type: number
minimum: -1
maximum: 1
description: Minimum body sentiment score
sentiment.body.score.max:
type: number
minimum: -1
maximum: 1
description: Maximum body sentiment score
sentiment.body.polarity:
type: string
enum:
- positive
- negative
- neutral
description: Body sentiment polarity
sentiment.mixed:
type: integer
enum:
- 0
- 1
description: Filter for mixed sentiment (title polarity != body polarity)
sentiment.consistent:
type: integer
enum:
- 0
- 1
description: Filter for consistent sentiment (title polarity == body polarity)
is_clickbait:
type: integer
enum:
- 0
- 1
description: Filter by clickbait detection
sentiment_gap.min:
type: number
minimum: 0
maximum: 2
description: Minimum sentiment gap between title and body
sentiment_gap.max:
type: number
minimum: 0
maximum: 2
description: Maximum sentiment gap between title and body
media.images.count:
type: integer
minimum: 0
description: Exact number of images
media.images.count.min:
type: integer
minimum: 0
description: Minimum number of images
media.images.count.max:
type: integer
minimum: 0
description: Maximum number of images
media.images.width.min:
type: integer
minimum: 0
description: Minimum image width in pixels
media.images.width.max:
type: integer
minimum: 0
description: Maximum image width in pixels
media.images.height.min:
type: integer
minimum: 0
description: Minimum image height in pixels
media.images.height.max:
type: integer
minimum: 0
description: Maximum image height in pixels
media.videos.count:
type: integer
minimum: 0
description: Exact number of videos
media.videos.count.min:
type: integer
minimum: 0
description: Minimum number of videos
media.videos.count.max:
type: integer
minimum: 0
description: Maximum number of videos
has_image:
type: integer
enum:
- 0
- 1
description: Filter articles with/without images
has_video:
type: integer
enum:
- 0
- 1
description: Filter articles with/without videos
has_hq_images:
type: integer
enum:
- 0
- 1
description: Filter articles with high-quality images (>= 1200px width)
is_media_rich:
type: integer
enum:
- 0
- 1
description: Filter articles with both images and videos
is_landscape_media:
type: integer
enum:
- 0
- 1
description: Filter articles with landscape-oriented media
is_portrait_media:
type: integer
enum:
- 0
- 1
description: Filter articles with portrait-oriented media
has_multiple_images:
type: integer
enum:
- 0
- 1
description: Filter articles with 2+ images
has_fullhd_images:
type: integer
enum:
- 0
- 1
description: Filter articles with Full HD images (>= 1920px width)
has_4k_images:
type: integer
enum:
- 0
- 1
description: Filter articles with 4K images (>= 3840px width)
has_mobile_optimized_images:
type: integer
enum:
- 0
- 1
description: Filter articles with mobile-optimized images (320-800px width)
is_instagram_ready:
type: integer
enum:
- 0
- 1
description: Filter articles with Instagram-ready images (>= 1080px + aspect ratio)
is_twitter_card_ready:
type: integer
enum:
- 0
- 1
description: Filter articles with Twitter Card-ready images (>= 800px + landscape)
has_consistent_image_sizes:
type: integer
enum:
- 0
- 1
description: Filter articles with consistent image dimensions
has_thumbnail:
type: integer
enum:
- 0
- 1
description: Filter articles with thumbnail images (<= 300px width)
has_social_share_image:
type: integer
enum:
- 0
- 1
description: Filter articles with social share images (>= 1200x630px)
has_mixed_media:
type: integer
enum:
- 0
- 1
description: Filter articles with both image and video media types
readability.fk_grade:
type: number
minimum: 0
maximum: 30
description: Exact Flesch-Kincaid grade level
readability.fk_grade.min:
type: number
minimum: 0
maximum: 30
description: Minimum Flesch-Kincaid grade level
readability.fk_grade.max:
type: number
minimum: 0
maximum: 30
description: Maximum Flesch-Kincaid grade level
readability.ease:
type: number
minimum: 0
maximum: 100
description: Exact Flesch Reading Ease score
readability.ease.min:
type: number
minimum: 0
maximum: 100
description: Minimum Flesch Reading Ease score
readability.ease.max:
type: number
minimum: 0
maximum: 100
description: Maximum Flesch Reading Ease score
readability.ari:
type: number
minimum: 0
maximum: 30
description: Exact Automated Readability Index
readability.ari.min:
type: number
minimum: 0
maximum: 30
description: Minimum Automated Readability Index
readability.ari.max:
type: number
minimum: 0
maximum: 30
description: Maximum Automated Readability Index
readability.difficulty:
type: string
enum:
- beginner
- intermediate
- advanced
- expert
description: Difficulty level
readability.audience:
type: string
enum:
- children
- general
- professional
- academic
description: Target audience
readability.age:
type: integer
minimum: 6
maximum: 22
description: Exact reading age
readability.age.min:
type: integer
minimum: 6
maximum: 22
description: Minimum reading age
readability.age.max:
type: integer
minimum: 6
maximum: 22
description: Maximum reading age
is_easy_read:
type: integer
enum:
- 0
- 1
description: Filter for easy-to-read articles (Flesch Reading Ease >= 60)
is_difficult_read:
type: integer
enum:
- 0
- 1
description: Filter for difficult-to-read articles (Flesch Reading Ease < 40)
read_time:
type: integer
minimum: 0
maximum: 1000
description: Exact read time in minutes
read_time.min:
type: integer
minimum: 0
maximum: 1000
description: Minimum read time in minutes
read_time.max:
type: integer
minimum: 0
maximum: 1000
description: Maximum read time in minutes
is_long_read:
type: integer
enum:
- 0
- 1
description: Filter for long reads (>= 5 minutes)
is_short_read:
type: integer
enum:
- 0
- 1
description: Filter for short reads (< 3 minutes)
is_quick_read:
type: integer
enum:
- 0
- 1
description: Filter for quick reads (<= 2 minutes)
is_medium_read:
type: integer
enum:
- 0
- 1
description: Filter for medium-length reads (3-7 minutes)
is_deep_dive:
type: integer
enum:
- 0
- 1
description: Filter for deep dives (>= 10 minutes)
location.bbox:
type: string
description: 'Bounding box: minLat,maxLat,minLng,maxLng'
example: 40.0,41.0,-74.5,-73.5
has_location_geo:
type: integer
enum:
- 0
- 1
description: Filter articles with/without geo-location data
location.lat:
type: number
minimum: -90
maximum: 90
description: Latitude for radius search
location.lng:
type: number
minimum: -180
maximum: 180
description: Longitude for radius search
location.radius:
type: number
exclusiveMinimum: 0
maximum: 20000
description: Search radius in kilometers (requires location.lat and location.lng)
location.radius.min:
type: number
minimum: 0
maximum: 20000
description: Minimum distance from point in km
is_duplicate:
type: integer
enum:
- 0
- 1
description: Filter duplicate/unique articles
is_paywall:
type: integer
enum:
- 0
- 1
description: Filter paywalled articles
is_breaking:
type: integer
enum:
- 0
- 1
description: Filter breaking news articles
is_high_quality:
type: integer
enum:
- 0
- 1
description: Filter high-quality articles (not duplicate, rank >= 5, has images, has
author)
author.id:
type: string
description: Comma-separated author IDs (max 3)
ignore.author.id:
type: string
description: Exclude these author IDs (comma-separated, max 3)
author.name:
type: string
maxLength: 100
description: Filter by author name (comma-separated, max 3)
ignore.author.name:
type: string
maxLength: 100
description: Exclude articles by these authors (comma-separated, max 3)
has_author:
type: integer
enum:
- 0
- 1
description: Filter articles with/without author
facet:
type: string
enum:
- '0'
- '1'
description: Enable faceting
facet.field:
type: string
description: 'Comma-separated facet fields (max 5). Values: source.id, source.country.id,
source.bias, language.id, author.id, category.id, topic.id, industry.id, entity.id,
sentiment.overall.polarity, sentiment.title.polarity, sentiment.body.polarity, sentiment.strength,
is_duplicate, is_free, is_important, media.images.count, media.videos.count, read_time,
content.length, published.year, published.month, published.day_of_week, published.hour,
published.weekday, published.time_of_day'
example: source.id,category.id
facet.limit:
type: integer
minimum: 1
maximum: 100
default: 10
description: Maximum number of facet values per field (max 100)
facet.mincount:
type: integer
minimum: 1
default: 1
description: Minimum count for a facet value to be included
facet.range:
type: string
enum:
- '0'
- '1'
description: Enable range faceting
facet.range.field:
type: string
description: 'Field for range faceting. Values: published_at, sentiment.overall.score,
sentiment.title.score, sentiment.body.score, read_time, source.rank.opr, media.images.count,
media.videos.count'
facet.range.start:
type: string
description: Start value for range faceting (required with facet.range)
facet.range.end:
type: string
description: End value for range faceting (required with facet.range)
facet.range.gap:
type: string
default: +1DAY
description: Gap value for range faceting
hl:
type: string
enum:
- '0'
- '1'
description: Enable highlighting
hl.fl:
type: string
default: title,description
description: 'Comma-separated fields to highlight (max 5). Values: title, description,
body'
example: title,description
hl.fragsize:
type: integer
minimum: 50
maximum: 500
default: 150
description: Size of highlighted fragment in characters (50-500)
hl.snippets:
type: integer
minimum: 1
maximum: 10
default: 3
description: Number of highlighted snippets per field (max 10)
hl.tag.pre:
type: string
description: Opening tag for highlighted text
default:
hl.tag.post:
type: string
description: Closing tag for highlighted text
default:
export:
type: string
enum:
- json
- csv
- tsv
- xml
- rss
- xlsx
- parquet
- jsonl
- ndjson
description: Export format
fl:
type: string
description: Comma-separated list of fields to include in the response
example: id,title,published_at,source.domain
debug:
type: string
enum:
- '0'
- '1'
description: Include user_input in response for debugging
api_key:
type: string
description: API key (alternative to X-API-Key header)
parameters:
- schema:
type: string
in: path
name: topicId
required: true
description: Topic ID
responses:
'200':
description: Successful response with articles
content:
application/json:
schema:
description: Successful response with articles
type: object
properties:
status:
type: string
enum:
- ok
description: Response status
limit:
type: integer
description: Results per page
path:
type: string
description: Current request URL
page:
type: integer
description: Current page number
has_next_pages:
type: boolean
description: Whether more pages are available
next_page:
type: string
description: URL for the next page (empty if no next page)
has_previous_page:
type: boolean
description: Whether a previous page exists
previous_page:
type: string
description: URL for the previous page (empty if no previous page)
export:
type: object
description: Export format URLs
properties:
json:
type: string
xlsx:
type: string
csv:
type: string
tsv:
type: string
xml:
type: string
rss:
type: string
parquet:
type: string
jsonl:
type: string
request_id:
type: string
description: Unique request identifier
results:
type: array
items:
type: object
properties:
id:
type: integer
description: Unique article ID
href:
type:
- string
- 'null'
description: Original article URL
published_at:
type:
- string
- 'null'
format: date-time
description: Publication date in ISO 8601
title:
type:
- string
- 'null'
description: Article title
description:
type:
- string
- 'null'
description: Article description (plain text)
body:
type:
- string
- 'null'
description: Article body (plain text)
body_html:
type:
- string
- 'null'
description: Article body (HTML)
language:
type: string
description: ISO 639-1 language code
translations:
type: object
description: Machine translations of the article title and description. Always
present; fields stay null for English articles and for languages without a
translation model
properties:
en:
type: object
properties:
title:
type:
- string
- 'null'
description: Title translated to English
description:
type:
- string
- 'null'
description: Description translated to English (plain text)
author:
type: object
properties:
id:
type:
- integer
- 'null'
description: Author ID
name:
type: string
description: Author name
image:
type: string
description: Main article image URL
categories:
type: array
items:
type: object
properties:
id:
type: integer
description: Category ID
name:
type: string
description: Category name
score:
type: number
description: Relevance score
taxonomy:
type: string
description: Taxonomy identifier
links:
type: object
properties:
self:
type: string
description: Link to category endpoint
topics:
type: array
items:
type: object
properties:
id:
type: string
description: Topic ID
name:
type: string
description: Topic name
score:
type: number
description: Relevance score
links:
type: object
properties:
self:
type: string
description: Link to topic endpoint
industries:
type: array
items:
type: object
properties:
id:
type: integer
description: Industry ID
name:
type: string
description: Industry name
links:
type: object
properties:
self:
type: string
description: Link to industry endpoint
entities:
type: array
items:
type: object
properties:
id:
type: integer
description: Entity ID
name:
type: string
description: Entity name
type:
type: string
enum:
- person
- location
- organization
- brand
- product
- natural-disaster
- disease
- event
- sport
- unknown
description: Entity type
frequency:
type: integer
description: Number of mentions in the article
sentiment:
type: object
description: Sentiment toward this entity (aggregated across its mentions)
properties:
score:
type: number
description: Entity sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Entity sentiment polarity
mentions:
type: object
description: Per-mention polarity breakdown
properties:
positive:
type: integer
neutral:
type: integer
negative:
type: integer
title:
type: object
properties:
pos:
type: array
items:
type: object
properties:
start:
type: integer
description: Start character offset
end:
type: integer
description: End character offset
description: Mention positions in title
body:
type: object
properties:
pos:
type: array
items:
type: object
properties:
start:
type: integer
description: Start character offset
end:
type: integer
description: End character offset
description: Mention positions in body
links:
type: object
properties:
self:
type: string
description: Link to entity endpoint
wikipedia:
type: string
description: Wikipedia URL
wikidata:
type: string
description: Wikidata URL
metadata:
type: object
description: Additional entity metadata (varies by entity type)
additionalProperties: true
locations_mentioned:
type: array
items:
type: object
properties:
name:
type: string
description: Location name
country:
type: string
description: Country code
lat:
type:
- number
- 'null'
description: Latitude
lng:
type:
- number
- 'null'
description: Longitude
type:
type: string
description: Location type
source:
type: object
properties:
id:
type:
- integer
- 'null'
description: Source ID
domain:
type: string
description: Source domain
home_page_url:
type: string
description: Source home page URL
type:
type: string
description: Source type
bias:
type: string
description: Media bias (left, center, right)
rankings:
type: object
properties:
opr:
type: integer
description: Open PageRank score
location:
type: object
properties:
country_name:
type: string
description: Source country name
country_code:
type: string
description: Source country ISO code
favicon:
type: string
description: Source favicon URL
sentiment:
type: object
properties:
overall:
type: object
properties:
score:
type: number
description: Sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Sentiment polarity
title:
type: object
properties:
score:
type: number
description: Sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Sentiment polarity
body:
type: object
properties:
score:
type: number
description: Sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Sentiment polarity
summary:
type: array
items:
type: object
properties:
sentence:
type: string
description: Summary sentence
sentiment:
type: object
properties:
score:
type: number
description: Sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Sentiment polarity
readability:
type: object
properties:
flesch_kincaid_grade:
type: number
description: Flesch-Kincaid grade level
flesch_reading_ease:
type: number
description: Flesch Reading Ease score (0-100)
automated_readability_index:
type: number
description: Automated Readability Index
difficulty_level:
type: string
enum:
- beginner
- intermediate
- advanced
- expert
- unknown
description: Difficulty level
target_audience:
type: string
enum:
- children
- general
- professional
- academic
- unknown
description: Target audience
reading_age:
type: number
description: Estimated reading age
avg_words_per_sentence:
type: number
description: Average words per sentence
avg_syllables_per_word:
type: number
description: Average syllables per word
keywords:
type: array
items:
type: string
description: Article keywords
links:
type: array
items:
type: object
properties:
url:
type: string
description: Link URL
type:
type: string
description: Link type
media:
type: array
items:
type: object
properties:
url:
type: string
description: Media URL
type:
type: string
description: Media type (image, video, etc.)
shares:
type: object
properties:
total:
type: integer
description: Total social shares
facebook:
type: integer
description: Facebook shares
twitter:
type: integer
description: Twitter/X shares
reddit:
type: integer
description: Reddit shares
story:
type: object
properties:
id:
type: integer
description: Story ID
uri:
type: string
description: Story endpoint URI
is_duplicate:
type: boolean
description: Whether this is a duplicate article
is_free:
type: boolean
description: Whether the article is freely accessible
is_breaking:
type: boolean
description: Whether this is breaking news
read_time:
type: integer
description: Estimated read time in minutes
sentences_count:
type: integer
description: Number of sentences
paragraphs_count:
type: integer
description: Number of paragraphs
words_count:
type: integer
description: Number of words
characters_count:
type: integer
description: Number of characters
description: Array of articles
facets:
type: object
description: Facet results (present when facet.field is specified)
additionalProperties: true
highlighting:
type: object
description: Highlighting results (present when hl=1)
additionalProperties: true
headlines:
type: array
description: Headlines (present in some responses)
items:
type: object
additionalProperties: true
meta:
type: object
description: 'Additional metadata. Present only when there is something to report
about how the request was handled: `prompt` (the request used the prompt parameter)
and/or `warnings` (the query was silently narrowed, e.g. ER0366 clamping a title
search to the last 31 days).'
properties:
prompt:
type: object
description: How the `prompt` parameter was translated into filters. Returned
by every JSON response to a request that used it (the SSE stream has no JSON
envelope, so it carries none).
properties:
text:
type: string
description: The prompt as it was parsed, trimmed
applied:
type: object
description: Parameters the prompt was translated into — the request that
actually ran
additionalProperties:
type: string
ignored:
type: array
description: Values understood but not used
items:
type: object
properties:
field:
type: string
description: Parameter that was not applied
value:
type: string
description: Value the prompt produced for it
reason:
type: string
enum:
- not_found
- explicit_param
- unsupported_on_endpoint
- invalid_date
- title_too_long
- title_window_clamped
description: Why the value was not applied
cached:
type: boolean
description: true when this wording had been parsed before, so no parse fee
was charged
warnings:
type: array
description: Non-fatal notices — the request still returned HTTP 200
items:
type: object
properties:
code:
type: string
description: Warning code, e.g. ER0366
message:
type: string
description: Human-readable explanation
links:
type: object
additionalProperties: true
additionalProperties: true
user_input:
type: object
description: Debug info — original request parameters (present when debug=1)
additionalProperties: true
required:
- status
- limit
- path
- page
- has_next_pages
- has_previous_page
- request_id
- results
example:
status: ok
limit: 50
path: /v1/news/everything
page: 1
has_next_pages: true
next_page: /v1/news/everything?page=2
has_previous_page: false
previous_page: ''
export:
json: /v1/news/everything?export=json
csv: /v1/news/everything?export=csv
rss: /v1/news/everything?export=rss
request_id: req_abc123def456
results:
- id: 84029371
href: https://example.com/article/spacex-launch
published_at: '2026-03-23T14:30:00Z'
title: SpaceX Successfully Launches New Starship Prototype
description: SpaceX completed another successful test flight of its Starship rocket...
language: en
author:
id: 1024
name: Jane Smith
image: https://example.com/images/starship.jpg
categories:
- id: 201
name: Science & Technology
score: 0.95
taxonomy: iptc_mediatopics
topics:
- id: space-exploration
name: Space Exploration
score: 0.92
industries:
- id: 88
name: Aerospace & Defense
entities:
- id: 5012
name: SpaceX
type: organization
frequency: 8
links:
wikipedia: https://en.wikipedia.org/wiki/SpaceX
- id: 3401
name: Elon Musk
type: person
frequency: 3
links:
wikipedia: https://en.wikipedia.org/wiki/Elon_Musk
source:
id: 7823
domain: reuters.com
home_page_url: https://www.reuters.com
type: news_agency
location:
country_name: United States
country_code: us
rankings:
opr: 8
sentiment:
overall:
score: 0.65
polarity: positive
title:
score: 0.72
polarity: positive
body:
score: 0.61
polarity: positive
readability:
flesch_kincaid_grade: 10.2
flesch_reading_ease: 52.3
difficulty_level: intermediate
target_audience: general
keywords:
- spacex
- starship
- rocket
- launch
is_duplicate: false
is_breaking: true
read_time: 4
words_count: 847
'401':
description: Authentication error
content:
application/json:
schema:
description: Authentication error
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
'404':
description: Topic not found
content:
application/json:
schema:
description: Topic not found
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
description: Rate limit exceeded
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
/v1/news/industry/{industryId}:
post:
summary: Get articles by industry
tags:
- News
description: Returns articles for a specific industry. Supports the same filtering, faceting, highlighting,
and export options as /v1/news/everything.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
prompt:
type: string
minLength: 3
maxLength: 500
description: 'Plain-language description of the news you want, e.g. "Elon Musk, Tesla,
news for the last 10 days". It is translated into the regular filters below before
the search runs, and the resulting parameters are returned in meta.prompt. Explicit
parameters always win over the prompt. Costs 2 extra points when the wording has not
been parsed before (repeats are served from cache). Available on Basic and above —
on Free and Starter the request fails with 403 ER0706. Errors: ER0706 (plan), ER0800
(length), ER0801 (translation service unavailable), ER0802 (nothing usable in the
prompt).'
page:
type: integer
minimum: 1
default: 1
description: Page number for pagination
per_page:
type: integer
minimum: 1
maximum: 250
default: 100
description: Number of results per page (max 250; the Free plan is capped at 10 and
Starter at 50)
sort.by:
type: string
enum:
- published_at
- relevance
- engagement
- quality
- controversy
- trust
- id
- new
- created_at
- source.rank.opr
- sentiment.overall.score
- sentiment.title.score
- sentiment.body.score
- read_time
- sentences_count
- paragraphs_count
- characters_count
- media.images.count
- media.videos.count
- media.images.width.min
- media.images.width.max
- media.images.height.min
- media.images.height.max
- media_richness
- shares.facebook.min
- shares.facebook.max
- shares.twitter.min
- shares.twitter.max
- shares.reddit.min
- shares.reddit.max
default: published_at
description: Field to sort results by
sort.order:
type: string
enum:
- asc
- desc
default: desc
description: Sort order
article.id:
type: string
description: Comma-separated article IDs (max 5)
example: '12345'
title:
type: string
minLength: 2
maxLength: 100
description: 'Search in article titles. Supports phrase search with proximity: "climate
change"~2. Title search is limited to a 31-day published_at window: without published_at.start
/ published_at.end the last 31 days are searched, a wider explicit range returns ER0110.'
ignore.title:
type: string
minLength: 2
maxLength: 100
description: Exclude articles containing this text in the title
title_starts_with:
type: string
minLength: 2
maxLength: 100
description: Filter articles whose title starts with the given text. Same 31-day window
limit as title
title_ends_with:
type: string
minLength: 2
maxLength: 100
description: Filter articles whose title ends with the given text. Same 31-day window
limit as title
title_pattern:
type: string
minLength: 2
maxLength: 200
description: Filter articles whose title matches the given pattern. Same 31-day window
limit as title
published_at:
type: string
description: 'Exact date (creates 24-hour range). Format: YYYY-MM-DD or ISO 8601'
example: '2025-01-15'
published_at.start:
type: string
description: 'Start of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title
search the range may not exceed 31 days (ER0110)'
example: '2025-01-01'
published_at.end:
type: string
description: 'End of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title
search the range may not exceed 31 days (ER0110)'
example: '2025-01-31'
language.code:
type: string
description: Comma-separated ISO 639-1 language codes (max 3)
example: en
ignore.language.code:
type: string
description: Exclude articles in these languages (comma-separated, max 3)
example: zh,ar
source.country.code:
type: string
description: Filter by source country ISO 3166-1 alpha-2 codes (comma-separated, max
3)
example: us
ignore.source.country.code:
type: string
description: Exclude sources from these countries (comma-separated, max 3)
example: us
source.rank.opr.min:
type: integer
minimum: 0
description: Minimum Open PageRank score
source.rank.opr.max:
type: integer
minimum: 0
description: Maximum Open PageRank score
source.id:
type: string
description: Comma-separated source IDs (max 3)
example: '100'
ignore.source.id:
type: string
description: Exclude these source IDs (comma-separated, max 3)
source.domain:
type: string
description: Comma-separated source domains (max 3)
example: nytimes.com
ignore.source.domain:
type: string
description: Exclude these source domains (comma-separated, max 3)
source.bias:
type: string
description: 'Filter by media bias (comma-separated). Values: left, center, right'
example: left
ignore.source.bias:
type: string
description: 'Exclude sources with this media bias (comma-separated). Values: left,
center, right'
example: right
is_premium_source:
type: integer
enum:
- 0
- 1
description: Filter by premium source status
is_verified_source:
type: integer
enum:
- 0
- 1
description: Filter by verified source status
category.id:
type: string
description: Comma-separated category IDs (max 3)
example: iab-1
ignore.category.id:
type: string
description: Exclude these categories (comma-separated, max 3)
topic.id:
type: string
description: Comma-separated topic IDs (max 3)
example: technology
ignore.topic.id:
type: string
description: Exclude these topics (comma-separated, max 3)
industry.id:
type: string
description: Comma-separated industry IDs (max 3)
example: '1'
ignore.industry.id:
type: string
description: Exclude these industries (comma-separated, max 3)
entity.id:
type: string
description: Comma-separated entity IDs (max 3)
example: '12345'
ignore.entity.id:
type: string
description: Exclude these entity IDs (comma-separated, max 3)
entity.sentiment.polarity:
type: string
enum:
- positive
- negative
- neutral
description: Filter by sentiment polarity toward the entity (combine with entity.id
or *.name; standalone = any entity)
entity.sentiment.score.min:
type: number
minimum: -1
maximum: 1
description: Minimum sentiment score toward the entity
entity.sentiment.score.max:
type: number
minimum: -1
maximum: 1
description: Maximum sentiment score toward the entity
person.name:
type: string
maxLength: 120
description: Filter by person name (comma-separated, max 3)
example: Elon Musk
ignore.person.name:
type: string
maxLength: 120
description: Exclude articles mentioning these persons (comma-separated, max 3)
organization.name:
type: string
maxLength: 120
description: Filter by organization name (comma-separated, max 3)
example: Google
ignore.organization.name:
type: string
maxLength: 120
description: Exclude articles mentioning these organizations (comma-separated, max 3)
location.name:
type: string
maxLength: 120
description: Filter by location name (comma-separated, max 3)
example: New York
ignore.location.name:
type: string
maxLength: 120
description: Exclude articles mentioning these locations (comma-separated, max 3)
brand.name:
type: string
maxLength: 120
description: Filter by brand name (comma-separated, max 3)
ignore.brand.name:
type: string
maxLength: 120
description: Exclude articles mentioning these brands (comma-separated, max 3)
disaster.name:
type: string
maxLength: 120
description: Filter by natural disaster name (comma-separated, max 3)
ignore.disaster.name:
type: string
maxLength: 120
description: Exclude articles mentioning these disasters (comma-separated, max 3)
disease.name:
type: string
maxLength: 120
description: Filter by disease name (comma-separated, max 3)
ignore.disease.name:
type: string
maxLength: 120
description: Exclude articles mentioning these diseases (comma-separated, max 3)
event.name:
type: string
maxLength: 120
description: Filter by event name (comma-separated, max 3)
ignore.event.name:
type: string
maxLength: 120
description: Exclude articles mentioning these events (comma-separated, max 3)
sport.name:
type: string
maxLength: 120
description: Filter by sport name (comma-separated, max 3)
ignore.sport.name:
type: string
maxLength: 120
description: Exclude articles mentioning these sports (comma-separated, max 3)
event.type:
type: string
description: 'Comma-separated event types (max 5). Values: merger-acquisition, ipo,
layoffs, bankruptcy, product-launch, funding-round, earnings, partnership, executive-change,
lawsuit, data-breach, recall, expansion, closure, stock-movement, contract-award,
spin-off, regulatory-action, election, protest, crime, terrorism, accident, policy-change,
scandal, death, award-ceremony, conflict, diplomacy, health-crisis, migration, human-rights,
earthquake, hurricane, flood, wildfire, tornado, tsunami, volcanic-eruption, drought,
climate-event, pollution, wildlife-event, avalanche'
example: ipo
event.category:
type: string
enum:
- business
- society
- environment
description: Filter by event category
ignore.event.type:
type: string
description: Exclude these event types (comma-separated, max 5)
sentiment.overall.score:
type: number
minimum: -1
maximum: 1
description: Exact overall sentiment score
sentiment.overall.score.min:
type: number
minimum: -1
maximum: 1
description: Minimum overall sentiment score
sentiment.overall.score.max:
type: number
minimum: -1
maximum: 1
description: Maximum overall sentiment score
sentiment.overall.polarity:
type: string
enum:
- positive
- negative
- neutral
description: Overall sentiment polarity
sentiment.title.score:
type: number
minimum: -1
maximum: 1
description: Exact title sentiment score
sentiment.title.score.min:
type: number
minimum: -1
maximum: 1
description: Minimum title sentiment score
sentiment.title.score.max:
type: number
minimum: -1
maximum: 1
description: Maximum title sentiment score
sentiment.title.polarity:
type: string
enum:
- positive
- negative
- neutral
description: Title sentiment polarity
sentiment.body.score:
type: number
minimum: -1
maximum: 1
description: Exact body sentiment score
sentiment.body.score.min:
type: number
minimum: -1
maximum: 1
description: Minimum body sentiment score
sentiment.body.score.max:
type: number
minimum: -1
maximum: 1
description: Maximum body sentiment score
sentiment.body.polarity:
type: string
enum:
- positive
- negative
- neutral
description: Body sentiment polarity
sentiment.mixed:
type: integer
enum:
- 0
- 1
description: Filter for mixed sentiment (title polarity != body polarity)
sentiment.consistent:
type: integer
enum:
- 0
- 1
description: Filter for consistent sentiment (title polarity == body polarity)
is_clickbait:
type: integer
enum:
- 0
- 1
description: Filter by clickbait detection
sentiment_gap.min:
type: number
minimum: 0
maximum: 2
description: Minimum sentiment gap between title and body
sentiment_gap.max:
type: number
minimum: 0
maximum: 2
description: Maximum sentiment gap between title and body
media.images.count:
type: integer
minimum: 0
description: Exact number of images
media.images.count.min:
type: integer
minimum: 0
description: Minimum number of images
media.images.count.max:
type: integer
minimum: 0
description: Maximum number of images
media.images.width.min:
type: integer
minimum: 0
description: Minimum image width in pixels
media.images.width.max:
type: integer
minimum: 0
description: Maximum image width in pixels
media.images.height.min:
type: integer
minimum: 0
description: Minimum image height in pixels
media.images.height.max:
type: integer
minimum: 0
description: Maximum image height in pixels
media.videos.count:
type: integer
minimum: 0
description: Exact number of videos
media.videos.count.min:
type: integer
minimum: 0
description: Minimum number of videos
media.videos.count.max:
type: integer
minimum: 0
description: Maximum number of videos
has_image:
type: integer
enum:
- 0
- 1
description: Filter articles with/without images
has_video:
type: integer
enum:
- 0
- 1
description: Filter articles with/without videos
has_hq_images:
type: integer
enum:
- 0
- 1
description: Filter articles with high-quality images (>= 1200px width)
is_media_rich:
type: integer
enum:
- 0
- 1
description: Filter articles with both images and videos
is_landscape_media:
type: integer
enum:
- 0
- 1
description: Filter articles with landscape-oriented media
is_portrait_media:
type: integer
enum:
- 0
- 1
description: Filter articles with portrait-oriented media
has_multiple_images:
type: integer
enum:
- 0
- 1
description: Filter articles with 2+ images
has_fullhd_images:
type: integer
enum:
- 0
- 1
description: Filter articles with Full HD images (>= 1920px width)
has_4k_images:
type: integer
enum:
- 0
- 1
description: Filter articles with 4K images (>= 3840px width)
has_mobile_optimized_images:
type: integer
enum:
- 0
- 1
description: Filter articles with mobile-optimized images (320-800px width)
is_instagram_ready:
type: integer
enum:
- 0
- 1
description: Filter articles with Instagram-ready images (>= 1080px + aspect ratio)
is_twitter_card_ready:
type: integer
enum:
- 0
- 1
description: Filter articles with Twitter Card-ready images (>= 800px + landscape)
has_consistent_image_sizes:
type: integer
enum:
- 0
- 1
description: Filter articles with consistent image dimensions
has_thumbnail:
type: integer
enum:
- 0
- 1
description: Filter articles with thumbnail images (<= 300px width)
has_social_share_image:
type: integer
enum:
- 0
- 1
description: Filter articles with social share images (>= 1200x630px)
has_mixed_media:
type: integer
enum:
- 0
- 1
description: Filter articles with both image and video media types
readability.fk_grade:
type: number
minimum: 0
maximum: 30
description: Exact Flesch-Kincaid grade level
readability.fk_grade.min:
type: number
minimum: 0
maximum: 30
description: Minimum Flesch-Kincaid grade level
readability.fk_grade.max:
type: number
minimum: 0
maximum: 30
description: Maximum Flesch-Kincaid grade level
readability.ease:
type: number
minimum: 0
maximum: 100
description: Exact Flesch Reading Ease score
readability.ease.min:
type: number
minimum: 0
maximum: 100
description: Minimum Flesch Reading Ease score
readability.ease.max:
type: number
minimum: 0
maximum: 100
description: Maximum Flesch Reading Ease score
readability.ari:
type: number
minimum: 0
maximum: 30
description: Exact Automated Readability Index
readability.ari.min:
type: number
minimum: 0
maximum: 30
description: Minimum Automated Readability Index
readability.ari.max:
type: number
minimum: 0
maximum: 30
description: Maximum Automated Readability Index
readability.difficulty:
type: string
enum:
- beginner
- intermediate
- advanced
- expert
description: Difficulty level
readability.audience:
type: string
enum:
- children
- general
- professional
- academic
description: Target audience
readability.age:
type: integer
minimum: 6
maximum: 22
description: Exact reading age
readability.age.min:
type: integer
minimum: 6
maximum: 22
description: Minimum reading age
readability.age.max:
type: integer
minimum: 6
maximum: 22
description: Maximum reading age
is_easy_read:
type: integer
enum:
- 0
- 1
description: Filter for easy-to-read articles (Flesch Reading Ease >= 60)
is_difficult_read:
type: integer
enum:
- 0
- 1
description: Filter for difficult-to-read articles (Flesch Reading Ease < 40)
read_time:
type: integer
minimum: 0
maximum: 1000
description: Exact read time in minutes
read_time.min:
type: integer
minimum: 0
maximum: 1000
description: Minimum read time in minutes
read_time.max:
type: integer
minimum: 0
maximum: 1000
description: Maximum read time in minutes
is_long_read:
type: integer
enum:
- 0
- 1
description: Filter for long reads (>= 5 minutes)
is_short_read:
type: integer
enum:
- 0
- 1
description: Filter for short reads (< 3 minutes)
is_quick_read:
type: integer
enum:
- 0
- 1
description: Filter for quick reads (<= 2 minutes)
is_medium_read:
type: integer
enum:
- 0
- 1
description: Filter for medium-length reads (3-7 minutes)
is_deep_dive:
type: integer
enum:
- 0
- 1
description: Filter for deep dives (>= 10 minutes)
location.bbox:
type: string
description: 'Bounding box: minLat,maxLat,minLng,maxLng'
example: 40.0,41.0,-74.5,-73.5
has_location_geo:
type: integer
enum:
- 0
- 1
description: Filter articles with/without geo-location data
location.lat:
type: number
minimum: -90
maximum: 90
description: Latitude for radius search
location.lng:
type: number
minimum: -180
maximum: 180
description: Longitude for radius search
location.radius:
type: number
exclusiveMinimum: 0
maximum: 20000
description: Search radius in kilometers (requires location.lat and location.lng)
location.radius.min:
type: number
minimum: 0
maximum: 20000
description: Minimum distance from point in km
is_duplicate:
type: integer
enum:
- 0
- 1
description: Filter duplicate/unique articles
is_paywall:
type: integer
enum:
- 0
- 1
description: Filter paywalled articles
is_breaking:
type: integer
enum:
- 0
- 1
description: Filter breaking news articles
is_high_quality:
type: integer
enum:
- 0
- 1
description: Filter high-quality articles (not duplicate, rank >= 5, has images, has
author)
author.id:
type: string
description: Comma-separated author IDs (max 3)
ignore.author.id:
type: string
description: Exclude these author IDs (comma-separated, max 3)
author.name:
type: string
maxLength: 100
description: Filter by author name (comma-separated, max 3)
ignore.author.name:
type: string
maxLength: 100
description: Exclude articles by these authors (comma-separated, max 3)
has_author:
type: integer
enum:
- 0
- 1
description: Filter articles with/without author
facet:
type: string
enum:
- '0'
- '1'
description: Enable faceting
facet.field:
type: string
description: 'Comma-separated facet fields (max 5). Values: source.id, source.country.id,
source.bias, language.id, author.id, category.id, topic.id, industry.id, entity.id,
sentiment.overall.polarity, sentiment.title.polarity, sentiment.body.polarity, sentiment.strength,
is_duplicate, is_free, is_important, media.images.count, media.videos.count, read_time,
content.length, published.year, published.month, published.day_of_week, published.hour,
published.weekday, published.time_of_day'
example: source.id,category.id
facet.limit:
type: integer
minimum: 1
maximum: 100
default: 10
description: Maximum number of facet values per field (max 100)
facet.mincount:
type: integer
minimum: 1
default: 1
description: Minimum count for a facet value to be included
facet.range:
type: string
enum:
- '0'
- '1'
description: Enable range faceting
facet.range.field:
type: string
description: 'Field for range faceting. Values: published_at, sentiment.overall.score,
sentiment.title.score, sentiment.body.score, read_time, source.rank.opr, media.images.count,
media.videos.count'
facet.range.start:
type: string
description: Start value for range faceting (required with facet.range)
facet.range.end:
type: string
description: End value for range faceting (required with facet.range)
facet.range.gap:
type: string
default: +1DAY
description: Gap value for range faceting
hl:
type: string
enum:
- '0'
- '1'
description: Enable highlighting
hl.fl:
type: string
default: title,description
description: 'Comma-separated fields to highlight (max 5). Values: title, description,
body'
example: title,description
hl.fragsize:
type: integer
minimum: 50
maximum: 500
default: 150
description: Size of highlighted fragment in characters (50-500)
hl.snippets:
type: integer
minimum: 1
maximum: 10
default: 3
description: Number of highlighted snippets per field (max 10)
hl.tag.pre:
type: string
description: Opening tag for highlighted text
default:
hl.tag.post:
type: string
description: Closing tag for highlighted text
default:
export:
type: string
enum:
- json
- csv
- tsv
- xml
- rss
- xlsx
- parquet
- jsonl
- ndjson
description: Export format
fl:
type: string
description: Comma-separated list of fields to include in the response
example: id,title,published_at,source.domain
debug:
type: string
enum:
- '0'
- '1'
description: Include user_input in response for debugging
api_key:
type: string
description: API key (alternative to X-API-Key header)
parameters:
- schema:
type: string
in: path
name: industryId
required: true
description: Industry ID
responses:
'200':
description: Successful response with articles
content:
application/json:
schema:
description: Successful response with articles
type: object
properties:
status:
type: string
enum:
- ok
description: Response status
limit:
type: integer
description: Results per page
path:
type: string
description: Current request URL
page:
type: integer
description: Current page number
has_next_pages:
type: boolean
description: Whether more pages are available
next_page:
type: string
description: URL for the next page (empty if no next page)
has_previous_page:
type: boolean
description: Whether a previous page exists
previous_page:
type: string
description: URL for the previous page (empty if no previous page)
export:
type: object
description: Export format URLs
properties:
json:
type: string
xlsx:
type: string
csv:
type: string
tsv:
type: string
xml:
type: string
rss:
type: string
parquet:
type: string
jsonl:
type: string
request_id:
type: string
description: Unique request identifier
results:
type: array
items:
type: object
properties:
id:
type: integer
description: Unique article ID
href:
type:
- string
- 'null'
description: Original article URL
published_at:
type:
- string
- 'null'
format: date-time
description: Publication date in ISO 8601
title:
type:
- string
- 'null'
description: Article title
description:
type:
- string
- 'null'
description: Article description (plain text)
body:
type:
- string
- 'null'
description: Article body (plain text)
body_html:
type:
- string
- 'null'
description: Article body (HTML)
language:
type: string
description: ISO 639-1 language code
translations:
type: object
description: Machine translations of the article title and description. Always
present; fields stay null for English articles and for languages without a
translation model
properties:
en:
type: object
properties:
title:
type:
- string
- 'null'
description: Title translated to English
description:
type:
- string
- 'null'
description: Description translated to English (plain text)
author:
type: object
properties:
id:
type:
- integer
- 'null'
description: Author ID
name:
type: string
description: Author name
image:
type: string
description: Main article image URL
categories:
type: array
items:
type: object
properties:
id:
type: integer
description: Category ID
name:
type: string
description: Category name
score:
type: number
description: Relevance score
taxonomy:
type: string
description: Taxonomy identifier
links:
type: object
properties:
self:
type: string
description: Link to category endpoint
topics:
type: array
items:
type: object
properties:
id:
type: string
description: Topic ID
name:
type: string
description: Topic name
score:
type: number
description: Relevance score
links:
type: object
properties:
self:
type: string
description: Link to topic endpoint
industries:
type: array
items:
type: object
properties:
id:
type: integer
description: Industry ID
name:
type: string
description: Industry name
links:
type: object
properties:
self:
type: string
description: Link to industry endpoint
entities:
type: array
items:
type: object
properties:
id:
type: integer
description: Entity ID
name:
type: string
description: Entity name
type:
type: string
enum:
- person
- location
- organization
- brand
- product
- natural-disaster
- disease
- event
- sport
- unknown
description: Entity type
frequency:
type: integer
description: Number of mentions in the article
sentiment:
type: object
description: Sentiment toward this entity (aggregated across its mentions)
properties:
score:
type: number
description: Entity sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Entity sentiment polarity
mentions:
type: object
description: Per-mention polarity breakdown
properties:
positive:
type: integer
neutral:
type: integer
negative:
type: integer
title:
type: object
properties:
pos:
type: array
items:
type: object
properties:
start:
type: integer
description: Start character offset
end:
type: integer
description: End character offset
description: Mention positions in title
body:
type: object
properties:
pos:
type: array
items:
type: object
properties:
start:
type: integer
description: Start character offset
end:
type: integer
description: End character offset
description: Mention positions in body
links:
type: object
properties:
self:
type: string
description: Link to entity endpoint
wikipedia:
type: string
description: Wikipedia URL
wikidata:
type: string
description: Wikidata URL
metadata:
type: object
description: Additional entity metadata (varies by entity type)
additionalProperties: true
locations_mentioned:
type: array
items:
type: object
properties:
name:
type: string
description: Location name
country:
type: string
description: Country code
lat:
type:
- number
- 'null'
description: Latitude
lng:
type:
- number
- 'null'
description: Longitude
type:
type: string
description: Location type
source:
type: object
properties:
id:
type:
- integer
- 'null'
description: Source ID
domain:
type: string
description: Source domain
home_page_url:
type: string
description: Source home page URL
type:
type: string
description: Source type
bias:
type: string
description: Media bias (left, center, right)
rankings:
type: object
properties:
opr:
type: integer
description: Open PageRank score
location:
type: object
properties:
country_name:
type: string
description: Source country name
country_code:
type: string
description: Source country ISO code
favicon:
type: string
description: Source favicon URL
sentiment:
type: object
properties:
overall:
type: object
properties:
score:
type: number
description: Sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Sentiment polarity
title:
type: object
properties:
score:
type: number
description: Sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Sentiment polarity
body:
type: object
properties:
score:
type: number
description: Sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Sentiment polarity
summary:
type: array
items:
type: object
properties:
sentence:
type: string
description: Summary sentence
sentiment:
type: object
properties:
score:
type: number
description: Sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Sentiment polarity
readability:
type: object
properties:
flesch_kincaid_grade:
type: number
description: Flesch-Kincaid grade level
flesch_reading_ease:
type: number
description: Flesch Reading Ease score (0-100)
automated_readability_index:
type: number
description: Automated Readability Index
difficulty_level:
type: string
enum:
- beginner
- intermediate
- advanced
- expert
- unknown
description: Difficulty level
target_audience:
type: string
enum:
- children
- general
- professional
- academic
- unknown
description: Target audience
reading_age:
type: number
description: Estimated reading age
avg_words_per_sentence:
type: number
description: Average words per sentence
avg_syllables_per_word:
type: number
description: Average syllables per word
keywords:
type: array
items:
type: string
description: Article keywords
links:
type: array
items:
type: object
properties:
url:
type: string
description: Link URL
type:
type: string
description: Link type
media:
type: array
items:
type: object
properties:
url:
type: string
description: Media URL
type:
type: string
description: Media type (image, video, etc.)
shares:
type: object
properties:
total:
type: integer
description: Total social shares
facebook:
type: integer
description: Facebook shares
twitter:
type: integer
description: Twitter/X shares
reddit:
type: integer
description: Reddit shares
story:
type: object
properties:
id:
type: integer
description: Story ID
uri:
type: string
description: Story endpoint URI
is_duplicate:
type: boolean
description: Whether this is a duplicate article
is_free:
type: boolean
description: Whether the article is freely accessible
is_breaking:
type: boolean
description: Whether this is breaking news
read_time:
type: integer
description: Estimated read time in minutes
sentences_count:
type: integer
description: Number of sentences
paragraphs_count:
type: integer
description: Number of paragraphs
words_count:
type: integer
description: Number of words
characters_count:
type: integer
description: Number of characters
description: Array of articles
facets:
type: object
description: Facet results (present when facet.field is specified)
additionalProperties: true
highlighting:
type: object
description: Highlighting results (present when hl=1)
additionalProperties: true
headlines:
type: array
description: Headlines (present in some responses)
items:
type: object
additionalProperties: true
meta:
type: object
description: 'Additional metadata. Present only when there is something to report
about how the request was handled: `prompt` (the request used the prompt parameter)
and/or `warnings` (the query was silently narrowed, e.g. ER0366 clamping a title
search to the last 31 days).'
properties:
prompt:
type: object
description: How the `prompt` parameter was translated into filters. Returned
by every JSON response to a request that used it (the SSE stream has no JSON
envelope, so it carries none).
properties:
text:
type: string
description: The prompt as it was parsed, trimmed
applied:
type: object
description: Parameters the prompt was translated into — the request that
actually ran
additionalProperties:
type: string
ignored:
type: array
description: Values understood but not used
items:
type: object
properties:
field:
type: string
description: Parameter that was not applied
value:
type: string
description: Value the prompt produced for it
reason:
type: string
enum:
- not_found
- explicit_param
- unsupported_on_endpoint
- invalid_date
- title_too_long
- title_window_clamped
description: Why the value was not applied
cached:
type: boolean
description: true when this wording had been parsed before, so no parse fee
was charged
warnings:
type: array
description: Non-fatal notices — the request still returned HTTP 200
items:
type: object
properties:
code:
type: string
description: Warning code, e.g. ER0366
message:
type: string
description: Human-readable explanation
links:
type: object
additionalProperties: true
additionalProperties: true
user_input:
type: object
description: Debug info — original request parameters (present when debug=1)
additionalProperties: true
required:
- status
- limit
- path
- page
- has_next_pages
- has_previous_page
- request_id
- results
example:
status: ok
limit: 50
path: /v1/news/everything
page: 1
has_next_pages: true
next_page: /v1/news/everything?page=2
has_previous_page: false
previous_page: ''
export:
json: /v1/news/everything?export=json
csv: /v1/news/everything?export=csv
rss: /v1/news/everything?export=rss
request_id: req_abc123def456
results:
- id: 84029371
href: https://example.com/article/spacex-launch
published_at: '2026-03-23T14:30:00Z'
title: SpaceX Successfully Launches New Starship Prototype
description: SpaceX completed another successful test flight of its Starship rocket...
language: en
author:
id: 1024
name: Jane Smith
image: https://example.com/images/starship.jpg
categories:
- id: 201
name: Science & Technology
score: 0.95
taxonomy: iptc_mediatopics
topics:
- id: space-exploration
name: Space Exploration
score: 0.92
industries:
- id: 88
name: Aerospace & Defense
entities:
- id: 5012
name: SpaceX
type: organization
frequency: 8
links:
wikipedia: https://en.wikipedia.org/wiki/SpaceX
- id: 3401
name: Elon Musk
type: person
frequency: 3
links:
wikipedia: https://en.wikipedia.org/wiki/Elon_Musk
source:
id: 7823
domain: reuters.com
home_page_url: https://www.reuters.com
type: news_agency
location:
country_name: United States
country_code: us
rankings:
opr: 8
sentiment:
overall:
score: 0.65
polarity: positive
title:
score: 0.72
polarity: positive
body:
score: 0.61
polarity: positive
readability:
flesch_kincaid_grade: 10.2
flesch_reading_ease: 52.3
difficulty_level: intermediate
target_audience: general
keywords:
- spacex
- starship
- rocket
- launch
is_duplicate: false
is_breaking: true
read_time: 4
words_count: 847
'401':
description: Authentication error
content:
application/json:
schema:
description: Authentication error
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
'404':
description: Industry not found
content:
application/json:
schema:
description: Industry not found
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
description: Rate limit exceeded
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
/v1/news/entity/{entityId}:
post:
summary: Get articles by entity
tags:
- News
description: Returns articles mentioning a specific entity (person, organization, location, brand,
etc.). Supports the same filtering, faceting, highlighting, and export options as /v1/news/everything.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
prompt:
type: string
minLength: 3
maxLength: 500
description: 'Plain-language description of the news you want, e.g. "Elon Musk, Tesla,
news for the last 10 days". It is translated into the regular filters below before
the search runs, and the resulting parameters are returned in meta.prompt. Explicit
parameters always win over the prompt. Costs 2 extra points when the wording has not
been parsed before (repeats are served from cache). Available on Basic and above —
on Free and Starter the request fails with 403 ER0706. Errors: ER0706 (plan), ER0800
(length), ER0801 (translation service unavailable), ER0802 (nothing usable in the
prompt).'
page:
type: integer
minimum: 1
default: 1
description: Page number for pagination
per_page:
type: integer
minimum: 1
maximum: 250
default: 100
description: Number of results per page (max 250; the Free plan is capped at 10 and
Starter at 50)
sort.by:
type: string
enum:
- published_at
- relevance
- engagement
- quality
- controversy
- trust
- id
- new
- created_at
- source.rank.opr
- sentiment.overall.score
- sentiment.title.score
- sentiment.body.score
- read_time
- sentences_count
- paragraphs_count
- characters_count
- media.images.count
- media.videos.count
- media.images.width.min
- media.images.width.max
- media.images.height.min
- media.images.height.max
- media_richness
- shares.facebook.min
- shares.facebook.max
- shares.twitter.min
- shares.twitter.max
- shares.reddit.min
- shares.reddit.max
default: published_at
description: Field to sort results by
sort.order:
type: string
enum:
- asc
- desc
default: desc
description: Sort order
article.id:
type: string
description: Comma-separated article IDs (max 5)
example: '12345'
title:
type: string
minLength: 2
maxLength: 100
description: 'Search in article titles. Supports phrase search with proximity: "climate
change"~2. Title search is limited to a 31-day published_at window: without published_at.start
/ published_at.end the last 31 days are searched, a wider explicit range returns ER0110.'
ignore.title:
type: string
minLength: 2
maxLength: 100
description: Exclude articles containing this text in the title
title_starts_with:
type: string
minLength: 2
maxLength: 100
description: Filter articles whose title starts with the given text. Same 31-day window
limit as title
title_ends_with:
type: string
minLength: 2
maxLength: 100
description: Filter articles whose title ends with the given text. Same 31-day window
limit as title
title_pattern:
type: string
minLength: 2
maxLength: 200
description: Filter articles whose title matches the given pattern. Same 31-day window
limit as title
published_at:
type: string
description: 'Exact date (creates 24-hour range). Format: YYYY-MM-DD or ISO 8601'
example: '2025-01-15'
published_at.start:
type: string
description: 'Start of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title
search the range may not exceed 31 days (ER0110)'
example: '2025-01-01'
published_at.end:
type: string
description: 'End of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title
search the range may not exceed 31 days (ER0110)'
example: '2025-01-31'
language.code:
type: string
description: Comma-separated ISO 639-1 language codes (max 3)
example: en
ignore.language.code:
type: string
description: Exclude articles in these languages (comma-separated, max 3)
example: zh,ar
source.country.code:
type: string
description: Filter by source country ISO 3166-1 alpha-2 codes (comma-separated, max
3)
example: us
ignore.source.country.code:
type: string
description: Exclude sources from these countries (comma-separated, max 3)
example: us
source.rank.opr.min:
type: integer
minimum: 0
description: Minimum Open PageRank score
source.rank.opr.max:
type: integer
minimum: 0
description: Maximum Open PageRank score
source.id:
type: string
description: Comma-separated source IDs (max 3)
example: '100'
ignore.source.id:
type: string
description: Exclude these source IDs (comma-separated, max 3)
source.domain:
type: string
description: Comma-separated source domains (max 3)
example: nytimes.com
ignore.source.domain:
type: string
description: Exclude these source domains (comma-separated, max 3)
source.bias:
type: string
description: 'Filter by media bias (comma-separated). Values: left, center, right'
example: left
ignore.source.bias:
type: string
description: 'Exclude sources with this media bias (comma-separated). Values: left,
center, right'
example: right
is_premium_source:
type: integer
enum:
- 0
- 1
description: Filter by premium source status
is_verified_source:
type: integer
enum:
- 0
- 1
description: Filter by verified source status
category.id:
type: string
description: Comma-separated category IDs (max 3)
example: iab-1
ignore.category.id:
type: string
description: Exclude these categories (comma-separated, max 3)
topic.id:
type: string
description: Comma-separated topic IDs (max 3)
example: technology
ignore.topic.id:
type: string
description: Exclude these topics (comma-separated, max 3)
industry.id:
type: string
description: Comma-separated industry IDs (max 3)
example: '1'
ignore.industry.id:
type: string
description: Exclude these industries (comma-separated, max 3)
entity.id:
type: string
description: Comma-separated entity IDs (max 3)
example: '12345'
ignore.entity.id:
type: string
description: Exclude these entity IDs (comma-separated, max 3)
entity.sentiment.polarity:
type: string
enum:
- positive
- negative
- neutral
description: Filter by sentiment polarity toward the entity (combine with entity.id
or *.name; standalone = any entity)
entity.sentiment.score.min:
type: number
minimum: -1
maximum: 1
description: Minimum sentiment score toward the entity
entity.sentiment.score.max:
type: number
minimum: -1
maximum: 1
description: Maximum sentiment score toward the entity
person.name:
type: string
maxLength: 120
description: Filter by person name (comma-separated, max 3)
example: Elon Musk
ignore.person.name:
type: string
maxLength: 120
description: Exclude articles mentioning these persons (comma-separated, max 3)
organization.name:
type: string
maxLength: 120
description: Filter by organization name (comma-separated, max 3)
example: Google
ignore.organization.name:
type: string
maxLength: 120
description: Exclude articles mentioning these organizations (comma-separated, max 3)
location.name:
type: string
maxLength: 120
description: Filter by location name (comma-separated, max 3)
example: New York
ignore.location.name:
type: string
maxLength: 120
description: Exclude articles mentioning these locations (comma-separated, max 3)
brand.name:
type: string
maxLength: 120
description: Filter by brand name (comma-separated, max 3)
ignore.brand.name:
type: string
maxLength: 120
description: Exclude articles mentioning these brands (comma-separated, max 3)
disaster.name:
type: string
maxLength: 120
description: Filter by natural disaster name (comma-separated, max 3)
ignore.disaster.name:
type: string
maxLength: 120
description: Exclude articles mentioning these disasters (comma-separated, max 3)
disease.name:
type: string
maxLength: 120
description: Filter by disease name (comma-separated, max 3)
ignore.disease.name:
type: string
maxLength: 120
description: Exclude articles mentioning these diseases (comma-separated, max 3)
event.name:
type: string
maxLength: 120
description: Filter by event name (comma-separated, max 3)
ignore.event.name:
type: string
maxLength: 120
description: Exclude articles mentioning these events (comma-separated, max 3)
sport.name:
type: string
maxLength: 120
description: Filter by sport name (comma-separated, max 3)
ignore.sport.name:
type: string
maxLength: 120
description: Exclude articles mentioning these sports (comma-separated, max 3)
event.type:
type: string
description: 'Comma-separated event types (max 5). Values: merger-acquisition, ipo,
layoffs, bankruptcy, product-launch, funding-round, earnings, partnership, executive-change,
lawsuit, data-breach, recall, expansion, closure, stock-movement, contract-award,
spin-off, regulatory-action, election, protest, crime, terrorism, accident, policy-change,
scandal, death, award-ceremony, conflict, diplomacy, health-crisis, migration, human-rights,
earthquake, hurricane, flood, wildfire, tornado, tsunami, volcanic-eruption, drought,
climate-event, pollution, wildlife-event, avalanche'
example: ipo
event.category:
type: string
enum:
- business
- society
- environment
description: Filter by event category
ignore.event.type:
type: string
description: Exclude these event types (comma-separated, max 5)
sentiment.overall.score:
type: number
minimum: -1
maximum: 1
description: Exact overall sentiment score
sentiment.overall.score.min:
type: number
minimum: -1
maximum: 1
description: Minimum overall sentiment score
sentiment.overall.score.max:
type: number
minimum: -1
maximum: 1
description: Maximum overall sentiment score
sentiment.overall.polarity:
type: string
enum:
- positive
- negative
- neutral
description: Overall sentiment polarity
sentiment.title.score:
type: number
minimum: -1
maximum: 1
description: Exact title sentiment score
sentiment.title.score.min:
type: number
minimum: -1
maximum: 1
description: Minimum title sentiment score
sentiment.title.score.max:
type: number
minimum: -1
maximum: 1
description: Maximum title sentiment score
sentiment.title.polarity:
type: string
enum:
- positive
- negative
- neutral
description: Title sentiment polarity
sentiment.body.score:
type: number
minimum: -1
maximum: 1
description: Exact body sentiment score
sentiment.body.score.min:
type: number
minimum: -1
maximum: 1
description: Minimum body sentiment score
sentiment.body.score.max:
type: number
minimum: -1
maximum: 1
description: Maximum body sentiment score
sentiment.body.polarity:
type: string
enum:
- positive
- negative
- neutral
description: Body sentiment polarity
sentiment.mixed:
type: integer
enum:
- 0
- 1
description: Filter for mixed sentiment (title polarity != body polarity)
sentiment.consistent:
type: integer
enum:
- 0
- 1
description: Filter for consistent sentiment (title polarity == body polarity)
is_clickbait:
type: integer
enum:
- 0
- 1
description: Filter by clickbait detection
sentiment_gap.min:
type: number
minimum: 0
maximum: 2
description: Minimum sentiment gap between title and body
sentiment_gap.max:
type: number
minimum: 0
maximum: 2
description: Maximum sentiment gap between title and body
media.images.count:
type: integer
minimum: 0
description: Exact number of images
media.images.count.min:
type: integer
minimum: 0
description: Minimum number of images
media.images.count.max:
type: integer
minimum: 0
description: Maximum number of images
media.images.width.min:
type: integer
minimum: 0
description: Minimum image width in pixels
media.images.width.max:
type: integer
minimum: 0
description: Maximum image width in pixels
media.images.height.min:
type: integer
minimum: 0
description: Minimum image height in pixels
media.images.height.max:
type: integer
minimum: 0
description: Maximum image height in pixels
media.videos.count:
type: integer
minimum: 0
description: Exact number of videos
media.videos.count.min:
type: integer
minimum: 0
description: Minimum number of videos
media.videos.count.max:
type: integer
minimum: 0
description: Maximum number of videos
has_image:
type: integer
enum:
- 0
- 1
description: Filter articles with/without images
has_video:
type: integer
enum:
- 0
- 1
description: Filter articles with/without videos
has_hq_images:
type: integer
enum:
- 0
- 1
description: Filter articles with high-quality images (>= 1200px width)
is_media_rich:
type: integer
enum:
- 0
- 1
description: Filter articles with both images and videos
is_landscape_media:
type: integer
enum:
- 0
- 1
description: Filter articles with landscape-oriented media
is_portrait_media:
type: integer
enum:
- 0
- 1
description: Filter articles with portrait-oriented media
has_multiple_images:
type: integer
enum:
- 0
- 1
description: Filter articles with 2+ images
has_fullhd_images:
type: integer
enum:
- 0
- 1
description: Filter articles with Full HD images (>= 1920px width)
has_4k_images:
type: integer
enum:
- 0
- 1
description: Filter articles with 4K images (>= 3840px width)
has_mobile_optimized_images:
type: integer
enum:
- 0
- 1
description: Filter articles with mobile-optimized images (320-800px width)
is_instagram_ready:
type: integer
enum:
- 0
- 1
description: Filter articles with Instagram-ready images (>= 1080px + aspect ratio)
is_twitter_card_ready:
type: integer
enum:
- 0
- 1
description: Filter articles with Twitter Card-ready images (>= 800px + landscape)
has_consistent_image_sizes:
type: integer
enum:
- 0
- 1
description: Filter articles with consistent image dimensions
has_thumbnail:
type: integer
enum:
- 0
- 1
description: Filter articles with thumbnail images (<= 300px width)
has_social_share_image:
type: integer
enum:
- 0
- 1
description: Filter articles with social share images (>= 1200x630px)
has_mixed_media:
type: integer
enum:
- 0
- 1
description: Filter articles with both image and video media types
readability.fk_grade:
type: number
minimum: 0
maximum: 30
description: Exact Flesch-Kincaid grade level
readability.fk_grade.min:
type: number
minimum: 0
maximum: 30
description: Minimum Flesch-Kincaid grade level
readability.fk_grade.max:
type: number
minimum: 0
maximum: 30
description: Maximum Flesch-Kincaid grade level
readability.ease:
type: number
minimum: 0
maximum: 100
description: Exact Flesch Reading Ease score
readability.ease.min:
type: number
minimum: 0
maximum: 100
description: Minimum Flesch Reading Ease score
readability.ease.max:
type: number
minimum: 0
maximum: 100
description: Maximum Flesch Reading Ease score
readability.ari:
type: number
minimum: 0
maximum: 30
description: Exact Automated Readability Index
readability.ari.min:
type: number
minimum: 0
maximum: 30
description: Minimum Automated Readability Index
readability.ari.max:
type: number
minimum: 0
maximum: 30
description: Maximum Automated Readability Index
readability.difficulty:
type: string
enum:
- beginner
- intermediate
- advanced
- expert
description: Difficulty level
readability.audience:
type: string
enum:
- children
- general
- professional
- academic
description: Target audience
readability.age:
type: integer
minimum: 6
maximum: 22
description: Exact reading age
readability.age.min:
type: integer
minimum: 6
maximum: 22
description: Minimum reading age
readability.age.max:
type: integer
minimum: 6
maximum: 22
description: Maximum reading age
is_easy_read:
type: integer
enum:
- 0
- 1
description: Filter for easy-to-read articles (Flesch Reading Ease >= 60)
is_difficult_read:
type: integer
enum:
- 0
- 1
description: Filter for difficult-to-read articles (Flesch Reading Ease < 40)
read_time:
type: integer
minimum: 0
maximum: 1000
description: Exact read time in minutes
read_time.min:
type: integer
minimum: 0
maximum: 1000
description: Minimum read time in minutes
read_time.max:
type: integer
minimum: 0
maximum: 1000
description: Maximum read time in minutes
is_long_read:
type: integer
enum:
- 0
- 1
description: Filter for long reads (>= 5 minutes)
is_short_read:
type: integer
enum:
- 0
- 1
description: Filter for short reads (< 3 minutes)
is_quick_read:
type: integer
enum:
- 0
- 1
description: Filter for quick reads (<= 2 minutes)
is_medium_read:
type: integer
enum:
- 0
- 1
description: Filter for medium-length reads (3-7 minutes)
is_deep_dive:
type: integer
enum:
- 0
- 1
description: Filter for deep dives (>= 10 minutes)
location.bbox:
type: string
description: 'Bounding box: minLat,maxLat,minLng,maxLng'
example: 40.0,41.0,-74.5,-73.5
has_location_geo:
type: integer
enum:
- 0
- 1
description: Filter articles with/without geo-location data
location.lat:
type: number
minimum: -90
maximum: 90
description: Latitude for radius search
location.lng:
type: number
minimum: -180
maximum: 180
description: Longitude for radius search
location.radius:
type: number
exclusiveMinimum: 0
maximum: 20000
description: Search radius in kilometers (requires location.lat and location.lng)
location.radius.min:
type: number
minimum: 0
maximum: 20000
description: Minimum distance from point in km
is_duplicate:
type: integer
enum:
- 0
- 1
description: Filter duplicate/unique articles
is_paywall:
type: integer
enum:
- 0
- 1
description: Filter paywalled articles
is_breaking:
type: integer
enum:
- 0
- 1
description: Filter breaking news articles
is_high_quality:
type: integer
enum:
- 0
- 1
description: Filter high-quality articles (not duplicate, rank >= 5, has images, has
author)
author.id:
type: string
description: Comma-separated author IDs (max 3)
ignore.author.id:
type: string
description: Exclude these author IDs (comma-separated, max 3)
author.name:
type: string
maxLength: 100
description: Filter by author name (comma-separated, max 3)
ignore.author.name:
type: string
maxLength: 100
description: Exclude articles by these authors (comma-separated, max 3)
has_author:
type: integer
enum:
- 0
- 1
description: Filter articles with/without author
facet:
type: string
enum:
- '0'
- '1'
description: Enable faceting
facet.field:
type: string
description: 'Comma-separated facet fields (max 5). Values: source.id, source.country.id,
source.bias, language.id, author.id, category.id, topic.id, industry.id, entity.id,
sentiment.overall.polarity, sentiment.title.polarity, sentiment.body.polarity, sentiment.strength,
is_duplicate, is_free, is_important, media.images.count, media.videos.count, read_time,
content.length, published.year, published.month, published.day_of_week, published.hour,
published.weekday, published.time_of_day'
example: source.id,category.id
facet.limit:
type: integer
minimum: 1
maximum: 100
default: 10
description: Maximum number of facet values per field (max 100)
facet.mincount:
type: integer
minimum: 1
default: 1
description: Minimum count for a facet value to be included
facet.range:
type: string
enum:
- '0'
- '1'
description: Enable range faceting
facet.range.field:
type: string
description: 'Field for range faceting. Values: published_at, sentiment.overall.score,
sentiment.title.score, sentiment.body.score, read_time, source.rank.opr, media.images.count,
media.videos.count'
facet.range.start:
type: string
description: Start value for range faceting (required with facet.range)
facet.range.end:
type: string
description: End value for range faceting (required with facet.range)
facet.range.gap:
type: string
default: +1DAY
description: Gap value for range faceting
hl:
type: string
enum:
- '0'
- '1'
description: Enable highlighting
hl.fl:
type: string
default: title,description
description: 'Comma-separated fields to highlight (max 5). Values: title, description,
body'
example: title,description
hl.fragsize:
type: integer
minimum: 50
maximum: 500
default: 150
description: Size of highlighted fragment in characters (50-500)
hl.snippets:
type: integer
minimum: 1
maximum: 10
default: 3
description: Number of highlighted snippets per field (max 10)
hl.tag.pre:
type: string
description: Opening tag for highlighted text
default:
hl.tag.post:
type: string
description: Closing tag for highlighted text
default:
export:
type: string
enum:
- json
- csv
- tsv
- xml
- rss
- xlsx
- parquet
- jsonl
- ndjson
description: Export format
fl:
type: string
description: Comma-separated list of fields to include in the response
example: id,title,published_at,source.domain
debug:
type: string
enum:
- '0'
- '1'
description: Include user_input in response for debugging
api_key:
type: string
description: API key (alternative to X-API-Key header)
parameters:
- schema:
type: string
in: path
name: entityId
required: true
description: Entity ID
responses:
'200':
description: Successful response with articles
content:
application/json:
schema:
description: Successful response with articles
type: object
properties:
status:
type: string
enum:
- ok
description: Response status
limit:
type: integer
description: Results per page
path:
type: string
description: Current request URL
page:
type: integer
description: Current page number
has_next_pages:
type: boolean
description: Whether more pages are available
next_page:
type: string
description: URL for the next page (empty if no next page)
has_previous_page:
type: boolean
description: Whether a previous page exists
previous_page:
type: string
description: URL for the previous page (empty if no previous page)
export:
type: object
description: Export format URLs
properties:
json:
type: string
xlsx:
type: string
csv:
type: string
tsv:
type: string
xml:
type: string
rss:
type: string
parquet:
type: string
jsonl:
type: string
request_id:
type: string
description: Unique request identifier
results:
type: array
items:
type: object
properties:
id:
type: integer
description: Unique article ID
href:
type:
- string
- 'null'
description: Original article URL
published_at:
type:
- string
- 'null'
format: date-time
description: Publication date in ISO 8601
title:
type:
- string
- 'null'
description: Article title
description:
type:
- string
- 'null'
description: Article description (plain text)
body:
type:
- string
- 'null'
description: Article body (plain text)
body_html:
type:
- string
- 'null'
description: Article body (HTML)
language:
type: string
description: ISO 639-1 language code
translations:
type: object
description: Machine translations of the article title and description. Always
present; fields stay null for English articles and for languages without a
translation model
properties:
en:
type: object
properties:
title:
type:
- string
- 'null'
description: Title translated to English
description:
type:
- string
- 'null'
description: Description translated to English (plain text)
author:
type: object
properties:
id:
type:
- integer
- 'null'
description: Author ID
name:
type: string
description: Author name
image:
type: string
description: Main article image URL
categories:
type: array
items:
type: object
properties:
id:
type: integer
description: Category ID
name:
type: string
description: Category name
score:
type: number
description: Relevance score
taxonomy:
type: string
description: Taxonomy identifier
links:
type: object
properties:
self:
type: string
description: Link to category endpoint
topics:
type: array
items:
type: object
properties:
id:
type: string
description: Topic ID
name:
type: string
description: Topic name
score:
type: number
description: Relevance score
links:
type: object
properties:
self:
type: string
description: Link to topic endpoint
industries:
type: array
items:
type: object
properties:
id:
type: integer
description: Industry ID
name:
type: string
description: Industry name
links:
type: object
properties:
self:
type: string
description: Link to industry endpoint
entities:
type: array
items:
type: object
properties:
id:
type: integer
description: Entity ID
name:
type: string
description: Entity name
type:
type: string
enum:
- person
- location
- organization
- brand
- product
- natural-disaster
- disease
- event
- sport
- unknown
description: Entity type
frequency:
type: integer
description: Number of mentions in the article
sentiment:
type: object
description: Sentiment toward this entity (aggregated across its mentions)
properties:
score:
type: number
description: Entity sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Entity sentiment polarity
mentions:
type: object
description: Per-mention polarity breakdown
properties:
positive:
type: integer
neutral:
type: integer
negative:
type: integer
title:
type: object
properties:
pos:
type: array
items:
type: object
properties:
start:
type: integer
description: Start character offset
end:
type: integer
description: End character offset
description: Mention positions in title
body:
type: object
properties:
pos:
type: array
items:
type: object
properties:
start:
type: integer
description: Start character offset
end:
type: integer
description: End character offset
description: Mention positions in body
links:
type: object
properties:
self:
type: string
description: Link to entity endpoint
wikipedia:
type: string
description: Wikipedia URL
wikidata:
type: string
description: Wikidata URL
metadata:
type: object
description: Additional entity metadata (varies by entity type)
additionalProperties: true
locations_mentioned:
type: array
items:
type: object
properties:
name:
type: string
description: Location name
country:
type: string
description: Country code
lat:
type:
- number
- 'null'
description: Latitude
lng:
type:
- number
- 'null'
description: Longitude
type:
type: string
description: Location type
source:
type: object
properties:
id:
type:
- integer
- 'null'
description: Source ID
domain:
type: string
description: Source domain
home_page_url:
type: string
description: Source home page URL
type:
type: string
description: Source type
bias:
type: string
description: Media bias (left, center, right)
rankings:
type: object
properties:
opr:
type: integer
description: Open PageRank score
location:
type: object
properties:
country_name:
type: string
description: Source country name
country_code:
type: string
description: Source country ISO code
favicon:
type: string
description: Source favicon URL
sentiment:
type: object
properties:
overall:
type: object
properties:
score:
type: number
description: Sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Sentiment polarity
title:
type: object
properties:
score:
type: number
description: Sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Sentiment polarity
body:
type: object
properties:
score:
type: number
description: Sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Sentiment polarity
summary:
type: array
items:
type: object
properties:
sentence:
type: string
description: Summary sentence
sentiment:
type: object
properties:
score:
type: number
description: Sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Sentiment polarity
readability:
type: object
properties:
flesch_kincaid_grade:
type: number
description: Flesch-Kincaid grade level
flesch_reading_ease:
type: number
description: Flesch Reading Ease score (0-100)
automated_readability_index:
type: number
description: Automated Readability Index
difficulty_level:
type: string
enum:
- beginner
- intermediate
- advanced
- expert
- unknown
description: Difficulty level
target_audience:
type: string
enum:
- children
- general
- professional
- academic
- unknown
description: Target audience
reading_age:
type: number
description: Estimated reading age
avg_words_per_sentence:
type: number
description: Average words per sentence
avg_syllables_per_word:
type: number
description: Average syllables per word
keywords:
type: array
items:
type: string
description: Article keywords
links:
type: array
items:
type: object
properties:
url:
type: string
description: Link URL
type:
type: string
description: Link type
media:
type: array
items:
type: object
properties:
url:
type: string
description: Media URL
type:
type: string
description: Media type (image, video, etc.)
shares:
type: object
properties:
total:
type: integer
description: Total social shares
facebook:
type: integer
description: Facebook shares
twitter:
type: integer
description: Twitter/X shares
reddit:
type: integer
description: Reddit shares
story:
type: object
properties:
id:
type: integer
description: Story ID
uri:
type: string
description: Story endpoint URI
is_duplicate:
type: boolean
description: Whether this is a duplicate article
is_free:
type: boolean
description: Whether the article is freely accessible
is_breaking:
type: boolean
description: Whether this is breaking news
read_time:
type: integer
description: Estimated read time in minutes
sentences_count:
type: integer
description: Number of sentences
paragraphs_count:
type: integer
description: Number of paragraphs
words_count:
type: integer
description: Number of words
characters_count:
type: integer
description: Number of characters
description: Array of articles
facets:
type: object
description: Facet results (present when facet.field is specified)
additionalProperties: true
highlighting:
type: object
description: Highlighting results (present when hl=1)
additionalProperties: true
headlines:
type: array
description: Headlines (present in some responses)
items:
type: object
additionalProperties: true
meta:
type: object
description: 'Additional metadata. Present only when there is something to report
about how the request was handled: `prompt` (the request used the prompt parameter)
and/or `warnings` (the query was silently narrowed, e.g. ER0366 clamping a title
search to the last 31 days).'
properties:
prompt:
type: object
description: How the `prompt` parameter was translated into filters. Returned
by every JSON response to a request that used it (the SSE stream has no JSON
envelope, so it carries none).
properties:
text:
type: string
description: The prompt as it was parsed, trimmed
applied:
type: object
description: Parameters the prompt was translated into — the request that
actually ran
additionalProperties:
type: string
ignored:
type: array
description: Values understood but not used
items:
type: object
properties:
field:
type: string
description: Parameter that was not applied
value:
type: string
description: Value the prompt produced for it
reason:
type: string
enum:
- not_found
- explicit_param
- unsupported_on_endpoint
- invalid_date
- title_too_long
- title_window_clamped
description: Why the value was not applied
cached:
type: boolean
description: true when this wording had been parsed before, so no parse fee
was charged
warnings:
type: array
description: Non-fatal notices — the request still returned HTTP 200
items:
type: object
properties:
code:
type: string
description: Warning code, e.g. ER0366
message:
type: string
description: Human-readable explanation
links:
type: object
additionalProperties: true
additionalProperties: true
user_input:
type: object
description: Debug info — original request parameters (present when debug=1)
additionalProperties: true
required:
- status
- limit
- path
- page
- has_next_pages
- has_previous_page
- request_id
- results
example:
status: ok
limit: 50
path: /v1/news/everything
page: 1
has_next_pages: true
next_page: /v1/news/everything?page=2
has_previous_page: false
previous_page: ''
export:
json: /v1/news/everything?export=json
csv: /v1/news/everything?export=csv
rss: /v1/news/everything?export=rss
request_id: req_abc123def456
results:
- id: 84029371
href: https://example.com/article/spacex-launch
published_at: '2026-03-23T14:30:00Z'
title: SpaceX Successfully Launches New Starship Prototype
description: SpaceX completed another successful test flight of its Starship rocket...
language: en
author:
id: 1024
name: Jane Smith
image: https://example.com/images/starship.jpg
categories:
- id: 201
name: Science & Technology
score: 0.95
taxonomy: iptc_mediatopics
topics:
- id: space-exploration
name: Space Exploration
score: 0.92
industries:
- id: 88
name: Aerospace & Defense
entities:
- id: 5012
name: SpaceX
type: organization
frequency: 8
links:
wikipedia: https://en.wikipedia.org/wiki/SpaceX
- id: 3401
name: Elon Musk
type: person
frequency: 3
links:
wikipedia: https://en.wikipedia.org/wiki/Elon_Musk
source:
id: 7823
domain: reuters.com
home_page_url: https://www.reuters.com
type: news_agency
location:
country_name: United States
country_code: us
rankings:
opr: 8
sentiment:
overall:
score: 0.65
polarity: positive
title:
score: 0.72
polarity: positive
body:
score: 0.61
polarity: positive
readability:
flesch_kincaid_grade: 10.2
flesch_reading_ease: 52.3
difficulty_level: intermediate
target_audience: general
keywords:
- spacex
- starship
- rocket
- launch
is_duplicate: false
is_breaking: true
read_time: 4
words_count: 847
'401':
description: Authentication error
content:
application/json:
schema:
description: Authentication error
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
'404':
description: Entity not found
content:
application/json:
schema:
description: Entity not found
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
description: Rate limit exceeded
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
/v1/news/trends:
post:
summary: Get trending topics and entities
tags:
- News
description: 'Returns trending aggregations across news articles. Analyze trends by source, category,
topic, industry, or entity. Supports time bucketing, comparison windows, growth rate analysis,
and percentile filtering. Maximum date range: 30 days.'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
field:
type: string
description: Comma-separated fields to aggregate (max 5). Required.
enum:
- source.id
- category.id
- topic.id
- industry.id
- entity.id
per_page:
type: integer
minimum: 1
maximum: 100
default: 10
description: Number of results per field
offset:
type: integer
minimum: 0
default: 0
description: Offset for pagination
mincount:
type: integer
minimum: 1
maximum: 10000
default: 1
description: Minimum article count for a value to be included
sort:
type: string
enum:
- count
- value
- growth_rate
- change
- trending_score
default: count
description: Sort field (change and trending_score require compare=1)
order:
type: string
enum:
- asc
- desc
default: desc
description: Sort order
time_bucket:
type: string
enum:
- hour
- day
- week
- month
description: Time bucket for time-series breakdown
trending:
type: string
enum:
- '0'
- '1'
description: Enable trending analysis with growth rate calculation
trending_days:
type: integer
minimum: 7
maximum: 30
default: 14
description: Number of days for trending analysis window
compare:
type: string
enum:
- '0'
- '1'
description: Enable period comparison
compare_window:
type: string
description: 'Comparison window (required when compare=1). Examples: 24HOURS, 7DAYS,
1WEEK, 1w, 2m'
percentile:
type: integer
minimum: 1
maximum: 100
description: Filter results above this percentile
prompt:
type: string
minLength: 3
maxLength: 500
description: 'Plain-language description of the news you want, e.g. "Elon Musk, Tesla,
news for the last 10 days". It is translated into the regular filters below before
the search runs, and the resulting parameters are returned in meta.prompt. Explicit
parameters always win over the prompt. Costs 2 extra points when the wording has not
been parsed before (repeats are served from cache). Available on Basic and above —
on Free and Starter the request fails with 403 ER0706. Errors: ER0706 (plan), ER0800
(length), ER0801 (translation service unavailable), ER0802 (nothing usable in the
prompt).'
published_at:
type: string
description: 'Exact date (creates 24-hour range). Format: YYYY-MM-DD or ISO 8601'
example: '2025-01-15'
published_at.start:
type: string
description: 'Start of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title
search the range may not exceed 31 days (ER0110)'
example: '2025-01-01'
published_at.end:
type: string
description: 'End of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title
search the range may not exceed 31 days (ER0110)'
example: '2025-01-31'
language.code:
type: string
description: Comma-separated ISO 639-1 language codes (max 3)
example: en
ignore.language.code:
type: string
description: Exclude articles in these languages (comma-separated, max 3)
example: zh,ar
source.country.code:
type: string
description: Filter by source country ISO 3166-1 alpha-2 codes (comma-separated, max
3)
example: us
ignore.source.country.code:
type: string
description: Exclude sources from these countries (comma-separated, max 3)
example: us
source.rank.opr.min:
type: integer
minimum: 0
description: Minimum Open PageRank score
source.rank.opr.max:
type: integer
minimum: 0
description: Maximum Open PageRank score
source.id:
type: string
description: Comma-separated source IDs (max 3)
example: '100'
ignore.source.id:
type: string
description: Exclude these source IDs (comma-separated, max 3)
source.domain:
type: string
description: Comma-separated source domains (max 3)
example: nytimes.com
ignore.source.domain:
type: string
description: Exclude these source domains (comma-separated, max 3)
source.bias:
type: string
description: 'Filter by media bias (comma-separated). Values: left, center, right'
example: left
ignore.source.bias:
type: string
description: 'Exclude sources with this media bias (comma-separated). Values: left,
center, right'
example: right
category.id:
type: string
description: Comma-separated category IDs (max 3)
example: iab-1
ignore.category.id:
type: string
description: Exclude these categories (comma-separated, max 3)
topic.id:
type: string
description: Comma-separated topic IDs (max 3)
example: technology
ignore.topic.id:
type: string
description: Exclude these topics (comma-separated, max 3)
industry.id:
type: string
description: Comma-separated industry IDs (max 3)
example: '1'
ignore.industry.id:
type: string
description: Exclude these industries (comma-separated, max 3)
entity.id:
type: string
description: Comma-separated entity IDs (max 3)
example: '12345'
ignore.entity.id:
type: string
description: Exclude these entity IDs (comma-separated, max 3)
entity.sentiment.polarity:
type: string
enum:
- positive
- negative
- neutral
description: Filter by sentiment polarity toward the entity (combine with entity.id
or *.name; standalone = any entity)
entity.sentiment.score.min:
type: number
minimum: -1
maximum: 1
description: Minimum sentiment score toward the entity
entity.sentiment.score.max:
type: number
minimum: -1
maximum: 1
description: Maximum sentiment score toward the entity
is_duplicate:
type: integer
enum:
- 0
- 1
description: Filter duplicate/unique articles
is_breaking:
type: integer
enum:
- 0
- 1
description: Filter breaking news articles
api_key:
type: string
description: API key (alternative to X-API-Key header)
responses:
'200':
description: Successful response with trend data
content:
application/json:
schema:
description: Successful response with trend data
type: object
properties:
status:
type: string
enum:
- ok
field:
type: string
description: Aggregated field (single-field request)
fields:
type: array
items:
type: string
description: Aggregated fields (multi-field request)
per_page:
type: integer
description: Results per field
offset:
type: integer
description: Pagination offset
total_count:
type: integer
description: Distinct values count (single-field request)
total_articles:
type: integer
description: Total matching articles (single-field request)
sort:
type: string
description: Sort field used
order:
type: string
enum:
- asc
- desc
description: Sort order used
mincount:
type: integer
description: Minimum article count threshold used
percentile:
type: integer
description: Percentile filter (present when percentile is set)
time_bucket:
type: string
description: Time bucket (present when time_bucket is set)
compare_window:
type: string
description: Comparison window (present when compare=1)
trending_days:
type: integer
description: Trending window in days (present when trending=1)
cached:
type: boolean
description: Whether the result was served from cache
trends:
description: For a single field — an array of trend items. For multiple fields — an
object keyed by field name, each holding { trends, total_count, total_articles }.
oneOf:
- type: array
items:
type: object
properties:
value:
description: Aggregated value. A plain string when no enrichment is available,
or an enriched object (id, name, type, ...) for entities/categories/topics/sources.
oneOf:
- type: string
- type: object
additionalProperties: true
count:
type: integer
description: Article count for this value
percentage:
type: number
description: Share of total matching articles (%)
growth_rate:
type:
- number
- 'null'
description: Articles per hour over the value lifetime
trending_score:
type: number
description: Trending score (present when trending=1)
trending_history:
type: object
description: Per-bucket history (present when trending=1)
additionalProperties: true
previous_count:
type: integer
description: Count in the comparison window (present when compare=1)
change_absolute:
type: integer
description: Absolute change vs comparison window (present when compare=1)
change_percent:
type: number
description: Percentage change vs comparison window (present when compare=1)
buckets:
type: object
description: Counts per time bucket (present when time_bucket is set)
additionalProperties: true
total:
type: integer
description: Total across buckets (present when time_bucket is set)
- type: object
additionalProperties:
type: object
properties:
trends:
type: array
items:
type: object
additionalProperties: true
total_count:
type: integer
total_articles:
type: integer
request_id:
type: string
example:
status: ok
field: entity.id
per_page: 10
offset: 0
total_count: 1240
total_articles: 58213
sort: count
order: desc
mincount: 1
trends:
- value:
id: 5012
name: SpaceX
type: organization
count: 342
percentage: 0.59
growth_rate: 2.15
- value:
id: 3401
name: Elon Musk
type: person
count: 218
percentage: 0.37
growth_rate: 1.45
request_id: req_abc123def456
'401':
description: Authentication error
content:
application/json:
schema:
description: Authentication error
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
description: Rate limit exceeded
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
/v1/news/count:
post:
summary: Count matching articles
tags:
- News
description: Returns only the number of articles matching the given filters, without loading any
article content. Accepts the same filters as `/v1/news/everything`, but runs a single `count(*)`
in ClickHouse — much cheaper and faster when you only need the total (dashboards, sample size
estimation, progress bars).
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
prompt:
type: string
minLength: 3
maxLength: 500
description: 'Plain-language description of the news you want, e.g. "Elon Musk, Tesla,
news for the last 10 days". It is translated into the regular filters below before
the search runs, and the resulting parameters are returned in meta.prompt. Explicit
parameters always win over the prompt. Costs 2 extra points when the wording has not
been parsed before (repeats are served from cache). Available on Basic and above —
on Free and Starter the request fails with 403 ER0706. Errors: ER0706 (plan), ER0800
(length), ER0801 (translation service unavailable), ER0802 (nothing usable in the
prompt).'
page:
type: integer
minimum: 1
default: 1
description: Page number for pagination
per_page:
type: integer
minimum: 1
maximum: 250
default: 100
description: Number of results per page (max 250; the Free plan is capped at 10 and
Starter at 50)
sort.by:
type: string
enum:
- published_at
- relevance
- engagement
- quality
- controversy
- trust
- id
- new
- created_at
- source.rank.opr
- sentiment.overall.score
- sentiment.title.score
- sentiment.body.score
- read_time
- sentences_count
- paragraphs_count
- characters_count
- media.images.count
- media.videos.count
- media.images.width.min
- media.images.width.max
- media.images.height.min
- media.images.height.max
- media_richness
- shares.facebook.min
- shares.facebook.max
- shares.twitter.min
- shares.twitter.max
- shares.reddit.min
- shares.reddit.max
default: published_at
description: Field to sort results by
sort.order:
type: string
enum:
- asc
- desc
default: desc
description: Sort order
article.id:
type: string
description: Comma-separated article IDs (max 5)
example: '12345'
title:
type: string
minLength: 2
maxLength: 100
description: 'Search in article titles. Supports phrase search with proximity: "climate
change"~2. Title search is limited to a 31-day published_at window: without published_at.start
/ published_at.end the last 31 days are searched, a wider explicit range returns ER0110.'
ignore.title:
type: string
minLength: 2
maxLength: 100
description: Exclude articles containing this text in the title
title_starts_with:
type: string
minLength: 2
maxLength: 100
description: Filter articles whose title starts with the given text. Same 31-day window
limit as title
title_ends_with:
type: string
minLength: 2
maxLength: 100
description: Filter articles whose title ends with the given text. Same 31-day window
limit as title
title_pattern:
type: string
minLength: 2
maxLength: 200
description: Filter articles whose title matches the given pattern. Same 31-day window
limit as title
published_at:
type: string
description: 'Exact date (creates 24-hour range). Format: YYYY-MM-DD or ISO 8601'
example: '2025-01-15'
published_at.start:
type: string
description: 'Start of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title
search the range may not exceed 31 days (ER0110)'
example: '2025-01-01'
published_at.end:
type: string
description: 'End of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title
search the range may not exceed 31 days (ER0110)'
example: '2025-01-31'
language.code:
type: string
description: Comma-separated ISO 639-1 language codes (max 3)
example: en
ignore.language.code:
type: string
description: Exclude articles in these languages (comma-separated, max 3)
example: zh,ar
source.country.code:
type: string
description: Filter by source country ISO 3166-1 alpha-2 codes (comma-separated, max
3)
example: us
ignore.source.country.code:
type: string
description: Exclude sources from these countries (comma-separated, max 3)
example: us
source.rank.opr.min:
type: integer
minimum: 0
description: Minimum Open PageRank score
source.rank.opr.max:
type: integer
minimum: 0
description: Maximum Open PageRank score
source.id:
type: string
description: Comma-separated source IDs (max 3)
example: '100'
ignore.source.id:
type: string
description: Exclude these source IDs (comma-separated, max 3)
source.domain:
type: string
description: Comma-separated source domains (max 3)
example: nytimes.com
ignore.source.domain:
type: string
description: Exclude these source domains (comma-separated, max 3)
source.bias:
type: string
description: 'Filter by media bias (comma-separated). Values: left, center, right'
example: left
ignore.source.bias:
type: string
description: 'Exclude sources with this media bias (comma-separated). Values: left,
center, right'
example: right
is_premium_source:
type: integer
enum:
- 0
- 1
description: Filter by premium source status
is_verified_source:
type: integer
enum:
- 0
- 1
description: Filter by verified source status
category.id:
type: string
description: Comma-separated category IDs (max 3)
example: iab-1
ignore.category.id:
type: string
description: Exclude these categories (comma-separated, max 3)
topic.id:
type: string
description: Comma-separated topic IDs (max 3)
example: technology
ignore.topic.id:
type: string
description: Exclude these topics (comma-separated, max 3)
industry.id:
type: string
description: Comma-separated industry IDs (max 3)
example: '1'
ignore.industry.id:
type: string
description: Exclude these industries (comma-separated, max 3)
entity.id:
type: string
description: Comma-separated entity IDs (max 3)
example: '12345'
ignore.entity.id:
type: string
description: Exclude these entity IDs (comma-separated, max 3)
entity.sentiment.polarity:
type: string
enum:
- positive
- negative
- neutral
description: Filter by sentiment polarity toward the entity (combine with entity.id
or *.name; standalone = any entity)
entity.sentiment.score.min:
type: number
minimum: -1
maximum: 1
description: Minimum sentiment score toward the entity
entity.sentiment.score.max:
type: number
minimum: -1
maximum: 1
description: Maximum sentiment score toward the entity
person.name:
type: string
maxLength: 120
description: Filter by person name (comma-separated, max 3)
example: Elon Musk
ignore.person.name:
type: string
maxLength: 120
description: Exclude articles mentioning these persons (comma-separated, max 3)
organization.name:
type: string
maxLength: 120
description: Filter by organization name (comma-separated, max 3)
example: Google
ignore.organization.name:
type: string
maxLength: 120
description: Exclude articles mentioning these organizations (comma-separated, max 3)
location.name:
type: string
maxLength: 120
description: Filter by location name (comma-separated, max 3)
example: New York
ignore.location.name:
type: string
maxLength: 120
description: Exclude articles mentioning these locations (comma-separated, max 3)
brand.name:
type: string
maxLength: 120
description: Filter by brand name (comma-separated, max 3)
ignore.brand.name:
type: string
maxLength: 120
description: Exclude articles mentioning these brands (comma-separated, max 3)
disaster.name:
type: string
maxLength: 120
description: Filter by natural disaster name (comma-separated, max 3)
ignore.disaster.name:
type: string
maxLength: 120
description: Exclude articles mentioning these disasters (comma-separated, max 3)
disease.name:
type: string
maxLength: 120
description: Filter by disease name (comma-separated, max 3)
ignore.disease.name:
type: string
maxLength: 120
description: Exclude articles mentioning these diseases (comma-separated, max 3)
event.name:
type: string
maxLength: 120
description: Filter by event name (comma-separated, max 3)
ignore.event.name:
type: string
maxLength: 120
description: Exclude articles mentioning these events (comma-separated, max 3)
sport.name:
type: string
maxLength: 120
description: Filter by sport name (comma-separated, max 3)
ignore.sport.name:
type: string
maxLength: 120
description: Exclude articles mentioning these sports (comma-separated, max 3)
event.type:
type: string
description: 'Comma-separated event types (max 5). Values: merger-acquisition, ipo,
layoffs, bankruptcy, product-launch, funding-round, earnings, partnership, executive-change,
lawsuit, data-breach, recall, expansion, closure, stock-movement, contract-award,
spin-off, regulatory-action, election, protest, crime, terrorism, accident, policy-change,
scandal, death, award-ceremony, conflict, diplomacy, health-crisis, migration, human-rights,
earthquake, hurricane, flood, wildfire, tornado, tsunami, volcanic-eruption, drought,
climate-event, pollution, wildlife-event, avalanche'
example: ipo
event.category:
type: string
enum:
- business
- society
- environment
description: Filter by event category
ignore.event.type:
type: string
description: Exclude these event types (comma-separated, max 5)
sentiment.overall.score:
type: number
minimum: -1
maximum: 1
description: Exact overall sentiment score
sentiment.overall.score.min:
type: number
minimum: -1
maximum: 1
description: Minimum overall sentiment score
sentiment.overall.score.max:
type: number
minimum: -1
maximum: 1
description: Maximum overall sentiment score
sentiment.overall.polarity:
type: string
enum:
- positive
- negative
- neutral
description: Overall sentiment polarity
sentiment.title.score:
type: number
minimum: -1
maximum: 1
description: Exact title sentiment score
sentiment.title.score.min:
type: number
minimum: -1
maximum: 1
description: Minimum title sentiment score
sentiment.title.score.max:
type: number
minimum: -1
maximum: 1
description: Maximum title sentiment score
sentiment.title.polarity:
type: string
enum:
- positive
- negative
- neutral
description: Title sentiment polarity
sentiment.body.score:
type: number
minimum: -1
maximum: 1
description: Exact body sentiment score
sentiment.body.score.min:
type: number
minimum: -1
maximum: 1
description: Minimum body sentiment score
sentiment.body.score.max:
type: number
minimum: -1
maximum: 1
description: Maximum body sentiment score
sentiment.body.polarity:
type: string
enum:
- positive
- negative
- neutral
description: Body sentiment polarity
sentiment.mixed:
type: integer
enum:
- 0
- 1
description: Filter for mixed sentiment (title polarity != body polarity)
sentiment.consistent:
type: integer
enum:
- 0
- 1
description: Filter for consistent sentiment (title polarity == body polarity)
is_clickbait:
type: integer
enum:
- 0
- 1
description: Filter by clickbait detection
sentiment_gap.min:
type: number
minimum: 0
maximum: 2
description: Minimum sentiment gap between title and body
sentiment_gap.max:
type: number
minimum: 0
maximum: 2
description: Maximum sentiment gap between title and body
media.images.count:
type: integer
minimum: 0
description: Exact number of images
media.images.count.min:
type: integer
minimum: 0
description: Minimum number of images
media.images.count.max:
type: integer
minimum: 0
description: Maximum number of images
media.images.width.min:
type: integer
minimum: 0
description: Minimum image width in pixels
media.images.width.max:
type: integer
minimum: 0
description: Maximum image width in pixels
media.images.height.min:
type: integer
minimum: 0
description: Minimum image height in pixels
media.images.height.max:
type: integer
minimum: 0
description: Maximum image height in pixels
media.videos.count:
type: integer
minimum: 0
description: Exact number of videos
media.videos.count.min:
type: integer
minimum: 0
description: Minimum number of videos
media.videos.count.max:
type: integer
minimum: 0
description: Maximum number of videos
has_image:
type: integer
enum:
- 0
- 1
description: Filter articles with/without images
has_video:
type: integer
enum:
- 0
- 1
description: Filter articles with/without videos
has_hq_images:
type: integer
enum:
- 0
- 1
description: Filter articles with high-quality images (>= 1200px width)
is_media_rich:
type: integer
enum:
- 0
- 1
description: Filter articles with both images and videos
is_landscape_media:
type: integer
enum:
- 0
- 1
description: Filter articles with landscape-oriented media
is_portrait_media:
type: integer
enum:
- 0
- 1
description: Filter articles with portrait-oriented media
has_multiple_images:
type: integer
enum:
- 0
- 1
description: Filter articles with 2+ images
has_fullhd_images:
type: integer
enum:
- 0
- 1
description: Filter articles with Full HD images (>= 1920px width)
has_4k_images:
type: integer
enum:
- 0
- 1
description: Filter articles with 4K images (>= 3840px width)
has_mobile_optimized_images:
type: integer
enum:
- 0
- 1
description: Filter articles with mobile-optimized images (320-800px width)
is_instagram_ready:
type: integer
enum:
- 0
- 1
description: Filter articles with Instagram-ready images (>= 1080px + aspect ratio)
is_twitter_card_ready:
type: integer
enum:
- 0
- 1
description: Filter articles with Twitter Card-ready images (>= 800px + landscape)
has_consistent_image_sizes:
type: integer
enum:
- 0
- 1
description: Filter articles with consistent image dimensions
has_thumbnail:
type: integer
enum:
- 0
- 1
description: Filter articles with thumbnail images (<= 300px width)
has_social_share_image:
type: integer
enum:
- 0
- 1
description: Filter articles with social share images (>= 1200x630px)
has_mixed_media:
type: integer
enum:
- 0
- 1
description: Filter articles with both image and video media types
readability.fk_grade:
type: number
minimum: 0
maximum: 30
description: Exact Flesch-Kincaid grade level
readability.fk_grade.min:
type: number
minimum: 0
maximum: 30
description: Minimum Flesch-Kincaid grade level
readability.fk_grade.max:
type: number
minimum: 0
maximum: 30
description: Maximum Flesch-Kincaid grade level
readability.ease:
type: number
minimum: 0
maximum: 100
description: Exact Flesch Reading Ease score
readability.ease.min:
type: number
minimum: 0
maximum: 100
description: Minimum Flesch Reading Ease score
readability.ease.max:
type: number
minimum: 0
maximum: 100
description: Maximum Flesch Reading Ease score
readability.ari:
type: number
minimum: 0
maximum: 30
description: Exact Automated Readability Index
readability.ari.min:
type: number
minimum: 0
maximum: 30
description: Minimum Automated Readability Index
readability.ari.max:
type: number
minimum: 0
maximum: 30
description: Maximum Automated Readability Index
readability.difficulty:
type: string
enum:
- beginner
- intermediate
- advanced
- expert
description: Difficulty level
readability.audience:
type: string
enum:
- children
- general
- professional
- academic
description: Target audience
readability.age:
type: integer
minimum: 6
maximum: 22
description: Exact reading age
readability.age.min:
type: integer
minimum: 6
maximum: 22
description: Minimum reading age
readability.age.max:
type: integer
minimum: 6
maximum: 22
description: Maximum reading age
is_easy_read:
type: integer
enum:
- 0
- 1
description: Filter for easy-to-read articles (Flesch Reading Ease >= 60)
is_difficult_read:
type: integer
enum:
- 0
- 1
description: Filter for difficult-to-read articles (Flesch Reading Ease < 40)
read_time:
type: integer
minimum: 0
maximum: 1000
description: Exact read time in minutes
read_time.min:
type: integer
minimum: 0
maximum: 1000
description: Minimum read time in minutes
read_time.max:
type: integer
minimum: 0
maximum: 1000
description: Maximum read time in minutes
is_long_read:
type: integer
enum:
- 0
- 1
description: Filter for long reads (>= 5 minutes)
is_short_read:
type: integer
enum:
- 0
- 1
description: Filter for short reads (< 3 minutes)
is_quick_read:
type: integer
enum:
- 0
- 1
description: Filter for quick reads (<= 2 minutes)
is_medium_read:
type: integer
enum:
- 0
- 1
description: Filter for medium-length reads (3-7 minutes)
is_deep_dive:
type: integer
enum:
- 0
- 1
description: Filter for deep dives (>= 10 minutes)
location.bbox:
type: string
description: 'Bounding box: minLat,maxLat,minLng,maxLng'
example: 40.0,41.0,-74.5,-73.5
has_location_geo:
type: integer
enum:
- 0
- 1
description: Filter articles with/without geo-location data
location.lat:
type: number
minimum: -90
maximum: 90
description: Latitude for radius search
location.lng:
type: number
minimum: -180
maximum: 180
description: Longitude for radius search
location.radius:
type: number
exclusiveMinimum: 0
maximum: 20000
description: Search radius in kilometers (requires location.lat and location.lng)
location.radius.min:
type: number
minimum: 0
maximum: 20000
description: Minimum distance from point in km
is_duplicate:
type: integer
enum:
- 0
- 1
description: Filter duplicate/unique articles
is_paywall:
type: integer
enum:
- 0
- 1
description: Filter paywalled articles
is_breaking:
type: integer
enum:
- 0
- 1
description: Filter breaking news articles
is_high_quality:
type: integer
enum:
- 0
- 1
description: Filter high-quality articles (not duplicate, rank >= 5, has images, has
author)
author.id:
type: string
description: Comma-separated author IDs (max 3)
ignore.author.id:
type: string
description: Exclude these author IDs (comma-separated, max 3)
author.name:
type: string
maxLength: 100
description: Filter by author name (comma-separated, max 3)
ignore.author.name:
type: string
maxLength: 100
description: Exclude articles by these authors (comma-separated, max 3)
has_author:
type: integer
enum:
- 0
- 1
description: Filter articles with/without author
facet:
type: string
enum:
- '0'
- '1'
description: Enable faceting
facet.field:
type: string
description: 'Comma-separated facet fields (max 5). Values: source.id, source.country.id,
source.bias, language.id, author.id, category.id, topic.id, industry.id, entity.id,
sentiment.overall.polarity, sentiment.title.polarity, sentiment.body.polarity, sentiment.strength,
is_duplicate, is_free, is_important, media.images.count, media.videos.count, read_time,
content.length, published.year, published.month, published.day_of_week, published.hour,
published.weekday, published.time_of_day'
example: source.id,category.id
facet.limit:
type: integer
minimum: 1
maximum: 100
default: 10
description: Maximum number of facet values per field (max 100)
facet.mincount:
type: integer
minimum: 1
default: 1
description: Minimum count for a facet value to be included
facet.range:
type: string
enum:
- '0'
- '1'
description: Enable range faceting
facet.range.field:
type: string
description: 'Field for range faceting. Values: published_at, sentiment.overall.score,
sentiment.title.score, sentiment.body.score, read_time, source.rank.opr, media.images.count,
media.videos.count'
facet.range.start:
type: string
description: Start value for range faceting (required with facet.range)
facet.range.end:
type: string
description: End value for range faceting (required with facet.range)
facet.range.gap:
type: string
default: +1DAY
description: Gap value for range faceting
hl:
type: string
enum:
- '0'
- '1'
description: Enable highlighting
hl.fl:
type: string
default: title,description
description: 'Comma-separated fields to highlight (max 5). Values: title, description,
body'
example: title,description
hl.fragsize:
type: integer
minimum: 50
maximum: 500
default: 150
description: Size of highlighted fragment in characters (50-500)
hl.snippets:
type: integer
minimum: 1
maximum: 10
default: 3
description: Number of highlighted snippets per field (max 10)
hl.tag.pre:
type: string
description: Opening tag for highlighted text
default:
hl.tag.post:
type: string
description: Closing tag for highlighted text
default:
export:
type: string
enum:
- json
- csv
- tsv
- xml
- rss
- xlsx
- parquet
- jsonl
- ndjson
description: Export format
fl:
type: string
description: Comma-separated list of fields to include in the response
example: id,title,published_at,source.domain
debug:
type: string
enum:
- '0'
- '1'
description: Include user_input in response for debugging
api_key:
type: string
description: API key (alternative to X-API-Key header)
responses:
'200':
description: Successful response with matching article count
content:
application/json:
schema:
description: Successful response with matching article count
type: object
properties:
status:
type: string
enum:
- ok
count:
type: integer
description: Number of articles matching the filters
request_id:
type: string
example:
status: ok
count: 12345
request_id: req_abc123def456
'401':
description: Authentication error
content:
application/json:
schema:
description: Authentication error
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
description: Rate limit exceeded
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
/v1/suggest/entities:
get:
summary: Autocomplete entities
tags:
- Suggest
description: Returns entity suggestions matching a given prefix. Useful for building autocomplete/typeahead
UI.
parameters:
- schema:
type: string
in: query
name: prefix
required: true
description: Search prefix for entity name. Required.
responses:
'200':
description: Array of matching entities
content:
application/json:
schema:
description: Array of matching entities
type: array
items:
type: object
properties:
id:
type: integer
description: Entity ID
name:
type: string
description: Entity name
type:
type: string
enum:
- person
- location
- organization
- brand
- product
- natural-disaster
- disease
- event
- sport
- unknown
description: Entity type
links:
type: object
properties:
self:
type: string
description: Link to entity endpoint
wikipedia:
type: string
description: Wikipedia URL
wikidata:
type: string
description: Wikidata URL
metadata:
type: object
description: Additional entity metadata
additionalProperties: true
example:
- id: 5012
name: SpaceX
type: organization
links:
self: /v1/news/entity/5012
wikipedia: https://en.wikipedia.org/wiki/SpaceX
wikidata: https://www.wikidata.org/wiki/Q193701
metadata: {}
- id: 9284
name: Spotify
type: brand
links:
self: /v1/news/entity/9284
wikipedia: https://en.wikipedia.org/wiki/Spotify
wikidata: https://www.wikidata.org/wiki/Q689141
metadata: {}
'400':
description: Missing prefix parameter
content:
application/json:
schema:
description: Missing prefix parameter
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
'401':
description: Authentication error
content:
application/json:
schema:
description: Authentication error
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
/v1/suggest/categories:
get:
summary: Autocomplete categories
tags:
- Suggest
description: Returns category suggestions matching a given prefix. The returned `id` can be used
directly in the `category.id` filter. Useful for building autocomplete/typeahead UI.
parameters:
- schema:
type: string
in: query
name: prefix
required: true
description: Search prefix for category name. Required.
responses:
'200':
description: Array of matching categories
content:
application/json:
schema:
description: Array of matching categories
type: array
items:
type: object
properties:
id:
type: integer
description: Category ID (use in category.id filter)
name:
type: string
description: Category name
taxonomy:
type: string
description: Category taxonomy
links:
type: object
properties:
self:
type: string
description: Link to category endpoint
example:
- id: 11100000
name: sport
taxonomy: iptc_mediatopics
links:
self: /v1/news/category/iptc_mediatopics/11100000
'400':
description: Missing prefix parameter
content:
application/json:
schema:
description: Missing prefix parameter
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
'401':
description: Authentication error
content:
application/json:
schema:
description: Authentication error
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
/v1/suggest/topics:
get:
summary: Autocomplete topics
tags:
- Suggest
description: Returns topic suggestions matching a given prefix. The returned `id` can be used directly
in the `topic.id` filter. Useful for building autocomplete/typeahead UI.
parameters:
- schema:
type: string
in: query
name: prefix
required: true
description: Search prefix for topic name. Required.
responses:
'200':
description: Array of matching topics
content:
application/json:
schema:
description: Array of matching topics
type: array
items:
type: object
properties:
id:
type: string
description: Topic ID (use in topic.id filter)
name:
type: string
description: Topic name
links:
type: object
properties:
self:
type: string
description: Link to topic endpoint
example:
- id: elections
name: Elections
links:
self: /v1/news/topic/elections
'400':
description: Missing prefix parameter
content:
application/json:
schema:
description: Missing prefix parameter
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
'401':
description: Authentication error
content:
application/json:
schema:
description: Authentication error
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
/v1/suggest/industries:
get:
summary: Autocomplete industries
tags:
- Suggest
description: Returns industry suggestions matching a given prefix. The returned `id` can be used
directly in the `industry.id` filter. Useful for building autocomplete/typeahead UI.
parameters:
- schema:
type: string
in: query
name: prefix
required: true
description: Search prefix for industry name. Required.
responses:
'200':
description: Array of matching industries
content:
application/json:
schema:
description: Array of matching industries
type: array
items:
type: object
properties:
id:
type: integer
description: Industry ID (use in industry.id filter)
name:
type: string
description: Industry name
links:
type: object
properties:
self:
type: string
description: Link to industry endpoint
example:
- id: 312
name: Technology
links:
self: /v1/news/industry/312
'400':
description: Missing prefix parameter
content:
application/json:
schema:
description: Missing prefix parameter
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
'401':
description: Authentication error
content:
application/json:
schema:
description: Authentication error
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
/v1/people:
get:
summary: List & search people
tags:
- Reference
description: Directory of known persons (public figures, politicians, executives) with Wikidata-enriched
profiles. Filter by name or Wikidata ID. Pivot to coverage via the `links.articles` URL.
parameters:
- schema:
type: string
in: query
name: name
required: false
description: Filter by person name (substring match).
- schema:
type: string
in: query
name: wikidata_id
required: false
description: Filter by Wikidata ID (e.g. Q317521 or 317521).
- schema:
type: integer
in: query
name: page
required: false
description: Page number (default 1).
- schema:
type: integer
in: query
name: per_page
required: false
description: Results per page (default 100, max 250; the Free plan is capped at 10 and Starter
at 50).
responses:
'200':
description: Paginated list of people
content:
application/json:
schema:
description: Paginated list of people
type: object
properties:
status:
type: string
enum:
- ok
limit:
type: integer
description: Results per page
page:
type: integer
description: Current page number
has_next_pages:
type: boolean
description: Whether more pages are available
results:
type: array
items:
type: object
properties:
id:
type: integer
description: Person (entity) ID
name:
type: string
description: Person name
type:
type: string
description: Entity type (person)
links:
type: object
properties:
self:
type: string
description: Link to this reference profile
articles:
type: string
description: Link to articles mentioning this entity
wikipedia:
type: string
description: Wikipedia URL (empty if unknown)
wikidata:
type: string
description: Wikidata URL (empty if unknown)
profile:
type:
- object
- 'null'
description: Wikidata-enriched metadata (varies by entity)
additionalProperties: true
'401':
description: Authentication error
content:
application/json:
schema:
description: Authentication error
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
/v1/people/{id}:
get:
summary: Get a person profile
tags:
- Reference
description: Returns a single person profile with Wikidata-enriched metadata and links to coverage.
parameters:
- schema:
type: string
in: query
name: coverage
required: false
description: Set to "false" to skip the coverage block (article counts, timeline, top sources/topics).
- schema:
type: integer
in: path
name: id
required: true
description: Person (entity) ID.
responses:
'200':
description: A single person profile
content:
application/json:
schema:
description: A single person profile
type: object
properties:
id:
type: integer
description: Person (entity) ID
name:
type: string
description: Person name
type:
type: string
description: Entity type (person)
links:
type: object
properties:
self:
type: string
description: Link to this reference profile
articles:
type: string
description: Link to articles mentioning this entity
wikipedia:
type: string
description: Wikipedia URL (empty if unknown)
wikidata:
type: string
description: Wikidata URL (empty if unknown)
profile:
type:
- object
- 'null'
description: Wikidata-enriched metadata (varies by entity)
additionalProperties: true
coverage:
type:
- object
- 'null'
description: Aggregated coverage stats (omitted when coverage=false, null on error)
properties:
article_count:
type: integer
description: Total articles in coverage scope
first_seen:
type:
- string
- 'null'
description: Date of the earliest article (YYYY-MM-DD)
last_seen:
type:
- string
- 'null'
description: Date of the latest article (YYYY-MM-DD)
sentiment:
type: object
properties:
positive:
type: integer
neutral:
type: integer
negative:
type: integer
momentum:
type: object
properties:
last_30_days:
type: integer
previous_30_days:
type: integer
change_pct:
type:
- integer
- 'null'
description: Percent change vs previous 30 days
timeline:
type: array
items:
type: object
properties:
period:
type: string
description: Month bucket (YYYY-MM-DD)
count:
type: integer
top_sources:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
domain:
type: string
count:
type: integer
top_topics:
type: array
items:
type: object
properties:
id:
type:
- integer
- string
description: Item ID
name:
type: string
count:
type: integer
top_countries:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
code:
type: string
count:
type: integer
top_languages:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
code:
type: string
count:
type: integer
related_entities:
type: array
items:
type: object
properties:
id:
type:
- integer
- string
description: Item ID
name:
type: string
count:
type: integer
recent_articles:
type: array
description: Up to 5 most recent articles (full article objects)
items:
type: object
properties:
id:
type: integer
description: Unique article ID
href:
type:
- string
- 'null'
description: Original article URL
published_at:
type:
- string
- 'null'
format: date-time
description: Publication date in ISO 8601
title:
type:
- string
- 'null'
description: Article title
description:
type:
- string
- 'null'
description: Article description (plain text)
body:
type:
- string
- 'null'
description: Article body (plain text)
body_html:
type:
- string
- 'null'
description: Article body (HTML)
language:
type: string
description: ISO 639-1 language code
translations:
type: object
description: Machine translations of the article title and description. Always
present; fields stay null for English articles and for languages without a
translation model
properties:
en:
type: object
properties:
title:
type:
- string
- 'null'
description: Title translated to English
description:
type:
- string
- 'null'
description: Description translated to English (plain text)
author:
type: object
properties:
id:
type:
- integer
- 'null'
description: Author ID
name:
type: string
description: Author name
image:
type: string
description: Main article image URL
categories:
type: array
items:
type: object
properties:
id:
type: integer
description: Category ID
name:
type: string
description: Category name
score:
type: number
description: Relevance score
taxonomy:
type: string
description: Taxonomy identifier
links:
type: object
properties:
self:
type: string
description: Link to category endpoint
topics:
type: array
items:
type: object
properties:
id:
type: string
description: Topic ID
name:
type: string
description: Topic name
score:
type: number
description: Relevance score
links:
type: object
properties:
self:
type: string
description: Link to topic endpoint
industries:
type: array
items:
type: object
properties:
id:
type: integer
description: Industry ID
name:
type: string
description: Industry name
links:
type: object
properties:
self:
type: string
description: Link to industry endpoint
entities:
type: array
items:
type: object
properties:
id:
type: integer
description: Entity ID
name:
type: string
description: Entity name
type:
type: string
enum:
- person
- location
- organization
- brand
- product
- natural-disaster
- disease
- event
- sport
- unknown
description: Entity type
frequency:
type: integer
description: Number of mentions in the article
sentiment:
type: object
description: Sentiment toward this entity (aggregated across its mentions)
properties:
score:
type: number
description: Entity sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Entity sentiment polarity
mentions:
type: object
description: Per-mention polarity breakdown
properties:
positive:
type: integer
neutral:
type: integer
negative:
type: integer
title:
type: object
properties:
pos:
type: array
items:
type: object
properties:
start:
type: integer
description: Start character offset
end:
type: integer
description: End character offset
description: Mention positions in title
body:
type: object
properties:
pos:
type: array
items:
type: object
properties:
start:
type: integer
description: Start character offset
end:
type: integer
description: End character offset
description: Mention positions in body
links:
type: object
properties:
self:
type: string
description: Link to entity endpoint
wikipedia:
type: string
description: Wikipedia URL
wikidata:
type: string
description: Wikidata URL
metadata:
type: object
description: Additional entity metadata (varies by entity type)
additionalProperties: true
locations_mentioned:
type: array
items:
type: object
properties:
name:
type: string
description: Location name
country:
type: string
description: Country code
lat:
type:
- number
- 'null'
description: Latitude
lng:
type:
- number
- 'null'
description: Longitude
type:
type: string
description: Location type
source:
type: object
properties:
id:
type:
- integer
- 'null'
description: Source ID
domain:
type: string
description: Source domain
home_page_url:
type: string
description: Source home page URL
type:
type: string
description: Source type
bias:
type: string
description: Media bias (left, center, right)
rankings:
type: object
properties:
opr:
type: integer
description: Open PageRank score
location:
type: object
properties:
country_name:
type: string
description: Source country name
country_code:
type: string
description: Source country ISO code
favicon:
type: string
description: Source favicon URL
sentiment:
type: object
properties:
overall:
type: object
properties:
score:
type: number
description: Sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Sentiment polarity
title:
type: object
properties:
score:
type: number
description: Sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Sentiment polarity
body:
type: object
properties:
score:
type: number
description: Sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Sentiment polarity
summary:
type: array
items:
type: object
properties:
sentence:
type: string
description: Summary sentence
sentiment:
type: object
properties:
score:
type: number
description: Sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Sentiment polarity
readability:
type: object
properties:
flesch_kincaid_grade:
type: number
description: Flesch-Kincaid grade level
flesch_reading_ease:
type: number
description: Flesch Reading Ease score (0-100)
automated_readability_index:
type: number
description: Automated Readability Index
difficulty_level:
type: string
enum:
- beginner
- intermediate
- advanced
- expert
- unknown
description: Difficulty level
target_audience:
type: string
enum:
- children
- general
- professional
- academic
- unknown
description: Target audience
reading_age:
type: number
description: Estimated reading age
avg_words_per_sentence:
type: number
description: Average words per sentence
avg_syllables_per_word:
type: number
description: Average syllables per word
keywords:
type: array
items:
type: string
description: Article keywords
links:
type: array
items:
type: object
properties:
url:
type: string
description: Link URL
type:
type: string
description: Link type
media:
type: array
items:
type: object
properties:
url:
type: string
description: Media URL
type:
type: string
description: Media type (image, video, etc.)
shares:
type: object
properties:
total:
type: integer
description: Total social shares
facebook:
type: integer
description: Facebook shares
twitter:
type: integer
description: Twitter/X shares
reddit:
type: integer
description: Reddit shares
story:
type: object
properties:
id:
type: integer
description: Story ID
uri:
type: string
description: Story endpoint URI
is_duplicate:
type: boolean
description: Whether this is a duplicate article
is_free:
type: boolean
description: Whether the article is freely accessible
is_breaking:
type: boolean
description: Whether this is breaking news
read_time:
type: integer
description: Estimated read time in minutes
sentences_count:
type: integer
description: Number of sentences
paragraphs_count:
type: integer
description: Number of paragraphs
words_count:
type: integer
description: Number of words
characters_count:
type: integer
description: Number of characters
'401':
description: Authentication error
content:
application/json:
schema:
description: Authentication error
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
'402':
description: No points left on account
content:
application/json:
schema:
description: No points left on account
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
'404':
description: Person not found
content:
application/json:
schema:
description: Person not found
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
/v1/companies:
get:
summary: List & search companies
tags:
- Reference
description: Directory of organizations and brands with Wikidata-enriched profiles (headquarters,
founded, website, key people, subsidiaries). Filter by name or Wikidata ID. Pivot to coverage
via the `links.articles` URL.
parameters:
- schema:
type: string
in: query
name: name
required: false
description: Filter by company name (substring match).
- schema:
type: string
in: query
name: wikidata_id
required: false
description: Filter by Wikidata ID (e.g. Q95 or 95).
- schema:
type: integer
in: query
name: page
required: false
description: Page number (default 1).
- schema:
type: integer
in: query
name: per_page
required: false
description: Results per page (default 100, max 250; the Free plan is capped at 10 and Starter
at 50).
responses:
'200':
description: Paginated list of companies
content:
application/json:
schema:
description: Paginated list of companies
type: object
properties:
status:
type: string
enum:
- ok
limit:
type: integer
description: Results per page
page:
type: integer
description: Current page number
has_next_pages:
type: boolean
description: Whether more pages are available
results:
type: array
items:
type: object
properties:
id:
type: integer
description: Company (entity) ID
name:
type: string
description: Company name
type:
type: string
description: Entity type (organization or brand)
links:
type: object
properties:
self:
type: string
description: Link to this reference profile
articles:
type: string
description: Link to articles mentioning this entity
wikipedia:
type: string
description: Wikipedia URL (empty if unknown)
wikidata:
type: string
description: Wikidata URL (empty if unknown)
profile:
type:
- object
- 'null'
description: Wikidata-enriched metadata (varies by entity)
additionalProperties: true
'401':
description: Authentication error
content:
application/json:
schema:
description: Authentication error
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
/v1/companies/{id}:
get:
summary: Get a company profile
tags:
- Reference
description: Returns a single company profile with Wikidata-enriched metadata and links to coverage.
parameters:
- schema:
type: string
in: query
name: coverage
required: false
description: Set to "false" to skip the coverage block (article counts, timeline, top sources/topics).
- schema:
type: integer
in: path
name: id
required: true
description: Company (entity) ID.
responses:
'200':
description: A single company profile
content:
application/json:
schema:
description: A single company profile
type: object
properties:
id:
type: integer
description: Company (entity) ID
name:
type: string
description: Company name
type:
type: string
description: Entity type (organization or brand)
links:
type: object
properties:
self:
type: string
description: Link to this reference profile
articles:
type: string
description: Link to articles mentioning this entity
wikipedia:
type: string
description: Wikipedia URL (empty if unknown)
wikidata:
type: string
description: Wikidata URL (empty if unknown)
profile:
type:
- object
- 'null'
description: Wikidata-enriched metadata (varies by entity)
additionalProperties: true
coverage:
type:
- object
- 'null'
description: Aggregated coverage stats (omitted when coverage=false, null on error)
properties:
article_count:
type: integer
description: Total articles in coverage scope
first_seen:
type:
- string
- 'null'
description: Date of the earliest article (YYYY-MM-DD)
last_seen:
type:
- string
- 'null'
description: Date of the latest article (YYYY-MM-DD)
sentiment:
type: object
properties:
positive:
type: integer
neutral:
type: integer
negative:
type: integer
momentum:
type: object
properties:
last_30_days:
type: integer
previous_30_days:
type: integer
change_pct:
type:
- integer
- 'null'
description: Percent change vs previous 30 days
timeline:
type: array
items:
type: object
properties:
period:
type: string
description: Month bucket (YYYY-MM-DD)
count:
type: integer
top_sources:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
domain:
type: string
count:
type: integer
top_topics:
type: array
items:
type: object
properties:
id:
type:
- integer
- string
description: Item ID
name:
type: string
count:
type: integer
top_countries:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
code:
type: string
count:
type: integer
top_languages:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
code:
type: string
count:
type: integer
related_entities:
type: array
items:
type: object
properties:
id:
type:
- integer
- string
description: Item ID
name:
type: string
count:
type: integer
recent_articles:
type: array
description: Up to 5 most recent articles (full article objects)
items:
type: object
properties:
id:
type: integer
description: Unique article ID
href:
type:
- string
- 'null'
description: Original article URL
published_at:
type:
- string
- 'null'
format: date-time
description: Publication date in ISO 8601
title:
type:
- string
- 'null'
description: Article title
description:
type:
- string
- 'null'
description: Article description (plain text)
body:
type:
- string
- 'null'
description: Article body (plain text)
body_html:
type:
- string
- 'null'
description: Article body (HTML)
language:
type: string
description: ISO 639-1 language code
translations:
type: object
description: Machine translations of the article title and description. Always
present; fields stay null for English articles and for languages without a
translation model
properties:
en:
type: object
properties:
title:
type:
- string
- 'null'
description: Title translated to English
description:
type:
- string
- 'null'
description: Description translated to English (plain text)
author:
type: object
properties:
id:
type:
- integer
- 'null'
description: Author ID
name:
type: string
description: Author name
image:
type: string
description: Main article image URL
categories:
type: array
items:
type: object
properties:
id:
type: integer
description: Category ID
name:
type: string
description: Category name
score:
type: number
description: Relevance score
taxonomy:
type: string
description: Taxonomy identifier
links:
type: object
properties:
self:
type: string
description: Link to category endpoint
topics:
type: array
items:
type: object
properties:
id:
type: string
description: Topic ID
name:
type: string
description: Topic name
score:
type: number
description: Relevance score
links:
type: object
properties:
self:
type: string
description: Link to topic endpoint
industries:
type: array
items:
type: object
properties:
id:
type: integer
description: Industry ID
name:
type: string
description: Industry name
links:
type: object
properties:
self:
type: string
description: Link to industry endpoint
entities:
type: array
items:
type: object
properties:
id:
type: integer
description: Entity ID
name:
type: string
description: Entity name
type:
type: string
enum:
- person
- location
- organization
- brand
- product
- natural-disaster
- disease
- event
- sport
- unknown
description: Entity type
frequency:
type: integer
description: Number of mentions in the article
sentiment:
type: object
description: Sentiment toward this entity (aggregated across its mentions)
properties:
score:
type: number
description: Entity sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Entity sentiment polarity
mentions:
type: object
description: Per-mention polarity breakdown
properties:
positive:
type: integer
neutral:
type: integer
negative:
type: integer
title:
type: object
properties:
pos:
type: array
items:
type: object
properties:
start:
type: integer
description: Start character offset
end:
type: integer
description: End character offset
description: Mention positions in title
body:
type: object
properties:
pos:
type: array
items:
type: object
properties:
start:
type: integer
description: Start character offset
end:
type: integer
description: End character offset
description: Mention positions in body
links:
type: object
properties:
self:
type: string
description: Link to entity endpoint
wikipedia:
type: string
description: Wikipedia URL
wikidata:
type: string
description: Wikidata URL
metadata:
type: object
description: Additional entity metadata (varies by entity type)
additionalProperties: true
locations_mentioned:
type: array
items:
type: object
properties:
name:
type: string
description: Location name
country:
type: string
description: Country code
lat:
type:
- number
- 'null'
description: Latitude
lng:
type:
- number
- 'null'
description: Longitude
type:
type: string
description: Location type
source:
type: object
properties:
id:
type:
- integer
- 'null'
description: Source ID
domain:
type: string
description: Source domain
home_page_url:
type: string
description: Source home page URL
type:
type: string
description: Source type
bias:
type: string
description: Media bias (left, center, right)
rankings:
type: object
properties:
opr:
type: integer
description: Open PageRank score
location:
type: object
properties:
country_name:
type: string
description: Source country name
country_code:
type: string
description: Source country ISO code
favicon:
type: string
description: Source favicon URL
sentiment:
type: object
properties:
overall:
type: object
properties:
score:
type: number
description: Sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Sentiment polarity
title:
type: object
properties:
score:
type: number
description: Sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Sentiment polarity
body:
type: object
properties:
score:
type: number
description: Sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Sentiment polarity
summary:
type: array
items:
type: object
properties:
sentence:
type: string
description: Summary sentence
sentiment:
type: object
properties:
score:
type: number
description: Sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Sentiment polarity
readability:
type: object
properties:
flesch_kincaid_grade:
type: number
description: Flesch-Kincaid grade level
flesch_reading_ease:
type: number
description: Flesch Reading Ease score (0-100)
automated_readability_index:
type: number
description: Automated Readability Index
difficulty_level:
type: string
enum:
- beginner
- intermediate
- advanced
- expert
- unknown
description: Difficulty level
target_audience:
type: string
enum:
- children
- general
- professional
- academic
- unknown
description: Target audience
reading_age:
type: number
description: Estimated reading age
avg_words_per_sentence:
type: number
description: Average words per sentence
avg_syllables_per_word:
type: number
description: Average syllables per word
keywords:
type: array
items:
type: string
description: Article keywords
links:
type: array
items:
type: object
properties:
url:
type: string
description: Link URL
type:
type: string
description: Link type
media:
type: array
items:
type: object
properties:
url:
type: string
description: Media URL
type:
type: string
description: Media type (image, video, etc.)
shares:
type: object
properties:
total:
type: integer
description: Total social shares
facebook:
type: integer
description: Facebook shares
twitter:
type: integer
description: Twitter/X shares
reddit:
type: integer
description: Reddit shares
story:
type: object
properties:
id:
type: integer
description: Story ID
uri:
type: string
description: Story endpoint URI
is_duplicate:
type: boolean
description: Whether this is a duplicate article
is_free:
type: boolean
description: Whether the article is freely accessible
is_breaking:
type: boolean
description: Whether this is breaking news
read_time:
type: integer
description: Estimated read time in minutes
sentences_count:
type: integer
description: Number of sentences
paragraphs_count:
type: integer
description: Number of paragraphs
words_count:
type: integer
description: Number of words
characters_count:
type: integer
description: Number of characters
'401':
description: Authentication error
content:
application/json:
schema:
description: Authentication error
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
'402':
description: No points left on account
content:
application/json:
schema:
description: No points left on account
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
'404':
description: Company not found
content:
application/json:
schema:
description: Company not found
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
/v1/journalists:
get:
summary: List & search journalists
tags:
- Reference
description: 'Directory of journalists, normalized by name (bylines across multiple outlets are
merged into one record with an `outlets` array). Filter by name. Note: exact namesakes and generic
bylines (e.g. "admin") may be merged — true disambiguation is planned for a later release.'
parameters:
- schema:
type: string
in: query
name: name
required: false
description: Filter by journalist name (substring match).
- schema:
type: integer
in: query
name: page
required: false
description: Page number (default 1).
- schema:
type: integer
in: query
name: per_page
required: false
description: Results per page (default 100, max 250; the Free plan is capped at 10 and Starter
at 50).
responses:
'200':
description: Paginated list of journalists
content:
application/json:
schema:
description: Paginated list of journalists
type: object
properties:
status:
type: string
enum:
- ok
limit:
type: integer
description: Results per page
page:
type: integer
description: Current page number
has_next_pages:
type: boolean
description: Whether more pages are available
results:
type: array
items:
type: object
properties:
id:
type: integer
description: Journalist (author) ID
name:
type: string
description: Journalist name
outlets:
type: array
description: Outlets the journalist writes for
items:
type: object
additionalProperties: true
outlet_count:
type: integer
description: Number of outlets (list endpoint only)
links:
type: object
properties:
self:
type: string
description: Link to this journalist profile
articles:
type: string
description: Link to articles by this journalist
'401':
description: Authentication error
content:
application/json:
schema:
description: Authentication error
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
/v1/journalists/{id}:
get:
summary: Get a journalist profile
tags:
- Reference
description: 'Returns a journalist profile: name, all `outlets` they publish under (merged by name),
and a `coverage` block (article counts, timeline, sentiment, top topics, top covered entities).'
parameters:
- schema:
type: string
in: query
name: coverage
required: false
description: Set to "false" to skip the coverage block (activity, timeline, top topics/entities).
- schema:
type: integer
in: path
name: id
required: true
description: Journalist (author) ID.
responses:
'200':
description: A single journalist profile
content:
application/json:
schema:
description: A single journalist profile
type: object
properties:
id:
type: integer
description: Journalist (author) ID
name:
type: string
description: Journalist name
outlets:
type: array
description: Outlets the journalist writes for
items:
type: object
additionalProperties: true
outlet_count:
type: integer
description: Number of outlets (list endpoint only)
links:
type: object
properties:
self:
type: string
description: Link to this journalist profile
articles:
type: string
description: Link to articles by this journalist
coverage:
type:
- object
- 'null'
description: Aggregated coverage stats (omitted when coverage=false, null on error)
properties:
article_count:
type: integer
description: Total articles in coverage scope
first_seen:
type:
- string
- 'null'
description: Date of the earliest article (YYYY-MM-DD)
last_seen:
type:
- string
- 'null'
description: Date of the latest article (YYYY-MM-DD)
sentiment:
type: object
properties:
positive:
type: integer
neutral:
type: integer
negative:
type: integer
momentum:
type: object
properties:
last_30_days:
type: integer
previous_30_days:
type: integer
change_pct:
type:
- integer
- 'null'
description: Percent change vs previous 30 days
timeline:
type: array
items:
type: object
properties:
period:
type: string
description: Month bucket (YYYY-MM-DD)
count:
type: integer
top_topics:
type: array
items:
type: object
properties:
id:
type:
- integer
- string
description: Item ID
name:
type: string
count:
type: integer
top_entities:
type: array
items:
type: object
properties:
id:
type:
- integer
- string
description: Item ID
name:
type: string
count:
type: integer
top_countries:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
code:
type: string
count:
type: integer
top_languages:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
code:
type: string
count:
type: integer
recent_articles:
type: array
description: Up to 5 most recent articles (full article objects)
items:
type: object
properties:
id:
type: integer
description: Unique article ID
href:
type:
- string
- 'null'
description: Original article URL
published_at:
type:
- string
- 'null'
format: date-time
description: Publication date in ISO 8601
title:
type:
- string
- 'null'
description: Article title
description:
type:
- string
- 'null'
description: Article description (plain text)
body:
type:
- string
- 'null'
description: Article body (plain text)
body_html:
type:
- string
- 'null'
description: Article body (HTML)
language:
type: string
description: ISO 639-1 language code
translations:
type: object
description: Machine translations of the article title and description. Always
present; fields stay null for English articles and for languages without a
translation model
properties:
en:
type: object
properties:
title:
type:
- string
- 'null'
description: Title translated to English
description:
type:
- string
- 'null'
description: Description translated to English (plain text)
author:
type: object
properties:
id:
type:
- integer
- 'null'
description: Author ID
name:
type: string
description: Author name
image:
type: string
description: Main article image URL
categories:
type: array
items:
type: object
properties:
id:
type: integer
description: Category ID
name:
type: string
description: Category name
score:
type: number
description: Relevance score
taxonomy:
type: string
description: Taxonomy identifier
links:
type: object
properties:
self:
type: string
description: Link to category endpoint
topics:
type: array
items:
type: object
properties:
id:
type: string
description: Topic ID
name:
type: string
description: Topic name
score:
type: number
description: Relevance score
links:
type: object
properties:
self:
type: string
description: Link to topic endpoint
industries:
type: array
items:
type: object
properties:
id:
type: integer
description: Industry ID
name:
type: string
description: Industry name
links:
type: object
properties:
self:
type: string
description: Link to industry endpoint
entities:
type: array
items:
type: object
properties:
id:
type: integer
description: Entity ID
name:
type: string
description: Entity name
type:
type: string
enum:
- person
- location
- organization
- brand
- product
- natural-disaster
- disease
- event
- sport
- unknown
description: Entity type
frequency:
type: integer
description: Number of mentions in the article
sentiment:
type: object
description: Sentiment toward this entity (aggregated across its mentions)
properties:
score:
type: number
description: Entity sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Entity sentiment polarity
mentions:
type: object
description: Per-mention polarity breakdown
properties:
positive:
type: integer
neutral:
type: integer
negative:
type: integer
title:
type: object
properties:
pos:
type: array
items:
type: object
properties:
start:
type: integer
description: Start character offset
end:
type: integer
description: End character offset
description: Mention positions in title
body:
type: object
properties:
pos:
type: array
items:
type: object
properties:
start:
type: integer
description: Start character offset
end:
type: integer
description: End character offset
description: Mention positions in body
links:
type: object
properties:
self:
type: string
description: Link to entity endpoint
wikipedia:
type: string
description: Wikipedia URL
wikidata:
type: string
description: Wikidata URL
metadata:
type: object
description: Additional entity metadata (varies by entity type)
additionalProperties: true
locations_mentioned:
type: array
items:
type: object
properties:
name:
type: string
description: Location name
country:
type: string
description: Country code
lat:
type:
- number
- 'null'
description: Latitude
lng:
type:
- number
- 'null'
description: Longitude
type:
type: string
description: Location type
source:
type: object
properties:
id:
type:
- integer
- 'null'
description: Source ID
domain:
type: string
description: Source domain
home_page_url:
type: string
description: Source home page URL
type:
type: string
description: Source type
bias:
type: string
description: Media bias (left, center, right)
rankings:
type: object
properties:
opr:
type: integer
description: Open PageRank score
location:
type: object
properties:
country_name:
type: string
description: Source country name
country_code:
type: string
description: Source country ISO code
favicon:
type: string
description: Source favicon URL
sentiment:
type: object
properties:
overall:
type: object
properties:
score:
type: number
description: Sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Sentiment polarity
title:
type: object
properties:
score:
type: number
description: Sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Sentiment polarity
body:
type: object
properties:
score:
type: number
description: Sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Sentiment polarity
summary:
type: array
items:
type: object
properties:
sentence:
type: string
description: Summary sentence
sentiment:
type: object
properties:
score:
type: number
description: Sentiment score from -1 (negative) to 1 (positive)
polarity:
type: string
enum:
- positive
- negative
- neutral
- ''
description: Sentiment polarity
readability:
type: object
properties:
flesch_kincaid_grade:
type: number
description: Flesch-Kincaid grade level
flesch_reading_ease:
type: number
description: Flesch Reading Ease score (0-100)
automated_readability_index:
type: number
description: Automated Readability Index
difficulty_level:
type: string
enum:
- beginner
- intermediate
- advanced
- expert
- unknown
description: Difficulty level
target_audience:
type: string
enum:
- children
- general
- professional
- academic
- unknown
description: Target audience
reading_age:
type: number
description: Estimated reading age
avg_words_per_sentence:
type: number
description: Average words per sentence
avg_syllables_per_word:
type: number
description: Average syllables per word
keywords:
type: array
items:
type: string
description: Article keywords
links:
type: array
items:
type: object
properties:
url:
type: string
description: Link URL
type:
type: string
description: Link type
media:
type: array
items:
type: object
properties:
url:
type: string
description: Media URL
type:
type: string
description: Media type (image, video, etc.)
shares:
type: object
properties:
total:
type: integer
description: Total social shares
facebook:
type: integer
description: Facebook shares
twitter:
type: integer
description: Twitter/X shares
reddit:
type: integer
description: Reddit shares
story:
type: object
properties:
id:
type: integer
description: Story ID
uri:
type: string
description: Story endpoint URI
is_duplicate:
type: boolean
description: Whether this is a duplicate article
is_free:
type: boolean
description: Whether the article is freely accessible
is_breaking:
type: boolean
description: Whether this is breaking news
read_time:
type: integer
description: Estimated read time in minutes
sentences_count:
type: integer
description: Number of sentences
paragraphs_count:
type: integer
description: Number of paragraphs
words_count:
type: integer
description: Number of words
characters_count:
type: integer
description: Number of characters
'401':
description: Authentication error
content:
application/json:
schema:
description: Authentication error
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
'402':
description: No points left on account
content:
application/json:
schema:
description: No points left on account
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
'404':
description: Journalist not found
content:
application/json:
schema:
description: Journalist not found
type: object
properties:
status:
type: string
enum:
- not_ok
description: Response status
request_id:
type:
- 'null'
- string
description: Unique request identifier
errors:
type: array
items:
type: object
properties:
status:
type: integer
description: HTTP status code
code:
type: string
description: Error code (e.g. ER0201)
message:
type: string
description: Human-readable error message
links:
type: object
properties:
about:
type: string
description: Link to error documentation
timestamp:
type: string
format: date-time
description: Error timestamp
example:
status: not_ok
request_id: req_abc123def456
errors:
- status: 401
code: ER0201
message: Invalid or missing API key.
links:
about: https://docs.apitube.io/platform/news-api/http-response-codes
timestamp: '2026-03-23T14:30:00Z'
servers:
- url: https://api.apitube.io
security:
- ApiKeyHeader: []
- ApiKeyQuery: []
tags:
- name: News
description: Search, filter, and retrieve news articles from thousands of global sources. Includes full-text
search, top headlines, related stories, category/topic/industry/entity browsing, and trends.
- name: Fact Check
description: Verify factual claims against the live news corpus (retrieval-augmented). Returns per-claim
verdicts on an 8-level scale with confidence, explanation, and supporting evidence.
- name: Account
description: API key balance and subscription plan information.
- name: Suggest
description: Autocomplete and typeahead suggestions for entities.
- name: System
description: Health checks and service status.
externalDocs:
description: APITube News API Documentation
url: https://docs.apitube.io