openapi: 3.0.3
info:
title: TheNews news API
description: Global news aggregation REST API providing real-time and historical news articles from thousands of sources with filtering by category, language, country, and search. Indexes over 1 million new articles per week from 40,000+ sources across 50+ countries and 35+ languages.
version: 1.0.0
termsOfService: https://www.thenewsapi.com/terms
contact:
url: https://www.thenewsapi.com/contact
license:
name: Proprietary
url: https://www.thenewsapi.com/terms
servers:
- url: https://api.thenewsapi.com/v1
description: Production server
security:
- ApiToken: []
tags:
- name: news
description: News article retrieval and search
paths:
/news/all:
get:
operationId: getAllNews
summary: All News
description: Search and filter the entire article database with comprehensive filtering options including search, categories, language, country, domain, and date range.
tags:
- news
parameters:
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/search_fields'
- $ref: '#/components/parameters/locale'
- $ref: '#/components/parameters/categories'
- $ref: '#/components/parameters/exclude_categories'
- $ref: '#/components/parameters/domains'
- $ref: '#/components/parameters/exclude_domains'
- $ref: '#/components/parameters/source_ids'
- $ref: '#/components/parameters/exclude_source_ids'
- $ref: '#/components/parameters/language'
- $ref: '#/components/parameters/published_before'
- $ref: '#/components/parameters/published_after'
- $ref: '#/components/parameters/published_on'
- $ref: '#/components/parameters/sort'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/page'
responses:
'200':
description: Successful response with paginated article list
headers:
X-RateLimit-Limit:
description: Rate limit ceiling for the current period
schema:
type: integer
X-UsageLimit-Limit:
description: Usage limit for the current plan
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/ArticleListResponse'
example:
meta:
found: 1250000
returned: 3
limit: 3
page: 1
data:
- uuid: b5a9c0d1-e2f3-4a5b-8c6d-7e9f0a1b2c3d
title: Global Markets Rally on Positive Economic Data
description: Stock markets around the world surged following better-than-expected employment figures.
keywords: markets, economy, stocks, employment
snippet: Global markets rallied on Friday after key economic indicators surprised analysts...
url: https://example.com/article/global-markets-rally
image_url: https://example.com/images/markets.jpg
language: en
published_at: '2026-06-13T09:30:00.000000Z'
source: example.com
categories:
- business
- general
relevance_score: null
locale: us
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/ServerError'
'503':
$ref: '#/components/responses/ServiceUnavailable'
/news/top:
get:
operationId: getTopStories
summary: Top Stories
description: Retrieve live and historical top stories with advanced filtering by category, language, country, and full-text search with boolean operators.
tags:
- news
parameters:
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/search_fields'
- $ref: '#/components/parameters/locale'
- $ref: '#/components/parameters/categories'
- $ref: '#/components/parameters/exclude_categories'
- $ref: '#/components/parameters/domains'
- $ref: '#/components/parameters/exclude_domains'
- $ref: '#/components/parameters/source_ids'
- $ref: '#/components/parameters/exclude_source_ids'
- $ref: '#/components/parameters/language'
- $ref: '#/components/parameters/published_before'
- $ref: '#/components/parameters/published_after'
- $ref: '#/components/parameters/published_on'
- $ref: '#/components/parameters/sort'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/page'
responses:
'200':
description: Successful response with paginated top stories
content:
application/json:
schema:
$ref: '#/components/schemas/ArticleListResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/ServerError'
'503':
$ref: '#/components/responses/ServiceUnavailable'
/news/headlines:
get:
operationId: getHeadlines
summary: Headlines
description: Get the latest headlines organized by category with optional similar article grouping. Available on Standard plan and above.
tags:
- news
parameters:
- $ref: '#/components/parameters/locale'
- $ref: '#/components/parameters/domains'
- $ref: '#/components/parameters/exclude_domains'
- $ref: '#/components/parameters/source_ids'
- $ref: '#/components/parameters/exclude_source_ids'
- $ref: '#/components/parameters/language'
- $ref: '#/components/parameters/published_on'
- name: headlines_per_category
in: query
description: Number of headlines to return per category (1-10, default 6).
required: false
schema:
type: integer
minimum: 1
maximum: 10
default: 6
- name: include_similar
in: query
description: Whether to include similar articles for each headline (default true).
required: false
schema:
type: boolean
default: true
responses:
'200':
description: Successful response with categorized headlines
content:
application/json:
schema:
$ref: '#/components/schemas/HeadlinesResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/ServerError'
'503':
$ref: '#/components/responses/ServiceUnavailable'
/news/similar/{uuid}:
get:
operationId: getSimilarNews
summary: Similar News
description: Find articles related to a specific article by UUID with optional category, domain, language, and date filters.
tags:
- news
parameters:
- name: uuid
in: path
description: The unique UUID identifier of the article to find similar articles for.
required: true
schema:
type: string
format: uuid
- $ref: '#/components/parameters/categories'
- $ref: '#/components/parameters/exclude_categories'
- $ref: '#/components/parameters/domains'
- $ref: '#/components/parameters/exclude_domains'
- $ref: '#/components/parameters/source_ids'
- $ref: '#/components/parameters/exclude_source_ids'
- $ref: '#/components/parameters/language'
- $ref: '#/components/parameters/published_before'
- $ref: '#/components/parameters/published_after'
- $ref: '#/components/parameters/published_on'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/page'
responses:
'200':
description: Successful response with similar articles ranked by relevance
content:
application/json:
schema:
$ref: '#/components/schemas/ArticleListResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/ServerError'
'503':
$ref: '#/components/responses/ServiceUnavailable'
/news/uuid/{uuid}:
get:
operationId: getNewsByUuid
summary: News by UUID
description: Retrieve a specific article by its unique UUID identifier.
tags:
- news
parameters:
- name: uuid
in: path
description: The unique UUID identifier of the article to retrieve.
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Successful response with the requested article
content:
application/json:
schema:
$ref: '#/components/schemas/Article'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/ServerError'
'503':
$ref: '#/components/responses/ServiceUnavailable'
components:
responses:
Forbidden:
description: Endpoint access restricted — not available on current plan.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: endpoint_access_restricted
message: This endpoint is not available on your current plan.
ServiceUnavailable:
description: Service temporarily unavailable — maintenance mode.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: maintenance_mode
message: The service is temporarily unavailable for maintenance.
TooManyRequests:
description: Rate limit reached — too many requests within the 60-second window.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: rate_limit_reached
message: You have exceeded the rate limit. Please wait before retrying.
ServerError:
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: server_error
message: An internal server error occurred.
NotFound:
description: Resource not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: resource_not_found
message: The requested article was not found.
PaymentRequired:
description: Plan usage limit reached.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: usage_limit_reached
message: You have reached your plan usage limit.
Unauthorized:
description: Invalid or missing API token.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: invalid_api_token
message: Your API token is invalid.
BadRequest:
description: Malformed parameters — invalid parameter formatting.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: malformed_parameters
message: Invalid parameter formatting.
parameters:
published_after:
name: published_after
in: query
description: 'Return articles published after this date/time (UTC). Formats: Y-m-d\TH:i:s, Y-m-d\TH:i, Y-m-d\TH, Y-m-d, Y-m, Y.'
required: false
schema:
type: string
example: '2026-01-01T00:00:00'
sort:
name: sort
in: query
description: 'Sort order for results. Options: published_on (chronological), relevance_score (by search relevance).'
required: false
schema:
type: string
enum:
- published_on
- relevance_score
default: published_on
language:
name: language
in: query
description: Comma-separated language codes to filter results (e.g., en,es,fr). Supports 35+ languages.
required: false
schema:
type: string
example: en,es
locale:
name: locale
in: query
description: Comma-separated country codes to filter articles by locale (e.g., us,ca,gb). Supports 50+ countries.
required: false
schema:
type: string
example: us,ca
exclude_domains:
name: exclude_domains
in: query
description: Comma-separated list of source domains to exclude.
required: false
schema:
type: string
categories:
name: categories
in: query
description: 'Comma-separated list of categories to include. Options: general, science, sports, business, health, entertainment, tech, politics, food, travel.'
required: false
schema:
type: string
example: tech,business
search:
name: search
in: query
description: Search query with advanced operators. Supports + (AND), | (OR), - (NOT), "..." (phrase), * (prefix), () (grouping), \ (escape). URL-encode when using special characters.
required: false
schema:
type: string
exclude_categories:
name: exclude_categories
in: query
description: Comma-separated list of categories to exclude.
required: false
schema:
type: string
search_fields:
name: search_fields
in: query
description: 'Comma-separated list of fields to search. Options: title, description, keywords, main_text.'
required: false
schema:
type: string
example: title,description
exclude_source_ids:
name: exclude_source_ids
in: query
description: Comma-separated list of source IDs to exclude.
required: false
schema:
type: string
source_ids:
name: source_ids
in: query
description: Comma-separated list of source IDs to include (as returned by the /news/sources endpoint).
required: false
schema:
type: string
published_on:
name: published_on
in: query
description: 'Return articles published on this exact date (UTC). Format: Y-m-d.'
required: false
schema:
type: string
format: date
example: '2026-06-13'
domains:
name: domains
in: query
description: Comma-separated list of source domains to include (e.g., techcrunch.com,bbc.com).
required: false
schema:
type: string
example: techcrunch.com,bbc.com
published_before:
name: published_before
in: query
description: 'Return articles published before this date/time (UTC). Formats: Y-m-d\TH:i:s, Y-m-d\TH:i, Y-m-d\TH, Y-m-d, Y-m, Y.'
required: false
schema:
type: string
example: '2026-06-13T23:15:37'
page:
name: page
in: query
description: Page number for pagination. Maximum total of 20,000 results across all pages.
required: false
schema:
type: integer
minimum: 1
default: 1
limit:
name: limit
in: query
description: Maximum number of results to return per page. Upper bound is determined by the current plan.
required: false
schema:
type: integer
minimum: 1
schemas:
PaginationMeta:
type: object
description: Pagination metadata for list responses.
properties:
found:
type: integer
description: Total number of articles matching the query.
returned:
type: integer
description: Number of articles returned in this response.
limit:
type: integer
description: Maximum number of articles per page.
page:
type: integer
description: Current page number.
ArticleListResponse:
type: object
description: Paginated list of news articles.
properties:
meta:
$ref: '#/components/schemas/PaginationMeta'
data:
type: array
items:
$ref: '#/components/schemas/Article'
Article:
type: object
description: A news article with full metadata.
properties:
uuid:
type: string
format: uuid
description: Unique identifier for the article.
title:
type: string
description: Article headline.
description:
type: string
description: Short summary or excerpt of the article.
keywords:
type: string
description: Comma-separated keywords associated with the article.
snippet:
type: string
description: Brief text snippet from the article body.
url:
type: string
format: uri
description: Full URL to the original article.
image_url:
type: string
format: uri
nullable: true
description: URL of the article's primary image, if available.
language:
type: string
description: ISO 639-1 language code of the article (e.g., en, es, fr).
published_at:
type: string
format: date-time
description: UTC timestamp when the article was published.
source:
type: string
description: Domain of the source publication (e.g., bbc.com).
categories:
type: array
items:
type: string
enum:
- general
- science
- sports
- business
- health
- entertainment
- tech
- politics
- food
- travel
description: List of categories the article belongs to.
relevance_score:
type: number
format: float
nullable: true
description: Relevance score when sorting by relevance_score. Null when not applicable.
locale:
type: string
description: Country code locale of the article (e.g., us, gb, ca).
similar:
type: array
items:
$ref: '#/components/schemas/Article'
description: Array of similar articles (only present in headlines response when include_similar=true).
ErrorResponse:
type: object
description: Standard error response.
properties:
error:
type: object
properties:
code:
type: string
description: Machine-readable error code.
message:
type: string
description: Human-readable error description.
HeadlinesResponse:
type: object
description: Headlines grouped by category.
properties:
meta:
$ref: '#/components/schemas/PaginationMeta'
data:
type: array
items:
$ref: '#/components/schemas/Article'
securitySchemes:
ApiToken:
type: apiKey
in: query
name: api_token
description: API token obtained after free registration at https://www.thenewsapi.com/register