The News API Top Stories API
Top stories filtered by keyword, category, and date.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/the-news-api:the-news-api-top-stories-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: News Top Stories API
description: The News API provides access to worldwide news articles and top stories from over 40,000 sources in 50 countries. Search and filter news by keyword, category, language, country, and date. All endpoints require an API token obtained by registering at thenewsapi.com.
version: 1.0.0
contact:
url: https://www.thenewsapi.com/
termsOfService: https://www.thenewsapi.com/terms
servers:
- url: https://api.thenewsapi.com/v1
security:
- apiToken: []
tags:
- name: Top Stories
description: Top stories filtered by keyword, category, and date.
paths:
/news/top:
get:
operationId: getTopStories
summary: Get Top Stories
description: Retrieve live and historical top stories globally or filtered by keyword, category, country, language, domain, or date. Supports advanced boolean search operators.
tags:
- Top Stories
parameters:
- name: api_token
in: query
required: true
description: Your API authentication token.
schema:
type: string
- name: search
in: query
required: false
description: 'Search query with boolean operators: + (AND), | (OR), - (negation), " (phrase), * (prefix), () (precedence).'
schema:
type: string
- name: search_fields
in: query
required: false
description: 'Comma-separated fields to search: title, description, keywords, main_text. Default: title,main_text.'
schema:
type: string
- name: locale
in: query
required: false
description: Comma-separated country codes to filter by.
schema:
type: string
- name: categories
in: query
required: false
description: 'Comma-separated categories: general, science, sports, business, health, entertainment, tech, politics, food, travel.'
schema:
type: string
- name: exclude_categories
in: query
required: false
description: Comma-separated categories to exclude.
schema:
type: string
- name: domains
in: query
required: false
description: Comma-separated domains to include.
schema:
type: string
- name: exclude_domains
in: query
required: false
description: Comma-separated domains to exclude.
schema:
type: string
- name: source_ids
in: query
required: false
description: Comma-separated source IDs to include.
schema:
type: string
- name: exclude_source_ids
in: query
required: false
description: Comma-separated source IDs to exclude.
schema:
type: string
- name: language
in: query
required: false
description: Comma-separated language codes to filter by.
schema:
type: string
- name: published_before
in: query
required: false
description: Filter to articles published before this datetime (Y-m-d\TH:i:s).
schema:
type: string
- name: published_after
in: query
required: false
description: Filter to articles published after this datetime.
schema:
type: string
- name: published_on
in: query
required: false
description: Filter to articles published on this exact date (Y-m-d).
schema:
type: string
format: date
- name: sort
in: query
required: false
description: Sort by published_at (default) or relevance_score.
schema:
type: string
enum:
- published_at
- relevance_score
- name: limit
in: query
required: false
description: Number of results per page (plan-dependent maximum).
schema:
type: integer
minimum: 1
- name: page
in: query
required: false
description: Page number for pagination (default 1, max result set 20,000).
schema:
type: integer
minimum: 1
default: 1
responses:
'200':
description: List of top news articles.
content:
application/json:
schema:
$ref: '#/components/schemas/NewsListResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/RateLimited'
components:
schemas:
Article:
type: object
description: A news article.
properties:
uuid:
type: string
description: Unique identifier for the article.
title:
type: string
description: Article headline.
description:
type: string
description: Short description of the article.
keywords:
type: string
description: Comma-separated keywords associated with the article.
snippet:
type: string
description: Short excerpt from the article body.
url:
type: string
format: uri
description: URL to the full article.
image_url:
type: string
format: uri
description: URL to the article's featured image.
language:
type: string
description: Language code of the article (e.g., en, es, fr).
published_at:
type: string
format: date-time
description: Publication datetime in UTC.
source:
type: string
description: Domain of the publishing source.
categories:
type: array
items:
type: string
description: Categories the article belongs to.
locale:
type: string
description: Country/locale code (e.g., us, gb, ca).
relevance_score:
type:
- number
- 'null'
description: Relevance score for search results or similarity matching.
Error:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: Error code.
message:
type: string
description: Human-readable error description.
NewsListResponse:
type: object
properties:
meta:
$ref: '#/components/schemas/Meta'
data:
type: array
items:
$ref: '#/components/schemas/Article'
description: Array of news articles.
Meta:
type: object
description: Pagination metadata.
properties:
found:
type: integer
description: Total number of articles matching the query.
returned:
type: integer
description: Number of articles returned on this page.
limit:
type: integer
description: Maximum results per page.
page:
type: integer
description: Current page number.
responses:
RateLimited:
description: Too many requests - rate limit reached (60-second window).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Unauthorized - invalid API token.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
BadRequest:
description: Bad request - malformed parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
apiToken:
type: apiKey
name: api_token
in: query