API Documentation

Base URL

https://api.newsmesh.co/v1

Authentication

All API endpoints require an API key passed as a query parameter:

?apiKey=your_api_key_here

Endpoints

Get Trending Articles

GET/v1/trending

Get trending articles from a curated feed (cached, fast response).

Query Parameters

apiKey (required)
limit (optional, default: 10, max: 10 on Free & Starter, max: 25 on Growth & Pro)

Response Fields

article_id — Unique article identifier
title — Article headline
description — Brief summary
link — Original article URL
media_url — Featured image URL
published_date — ISO 8601 timestamp
source — News outlet name
category — Article category
topics — Array of related topics
people — Array of people mentioned
author — Array of article authors (or null if unavailable)

Response

{
  "data": [
    {
      "article_id": "4d5a309dfceb13e6fdb34fd1410fe22e",
      "title": "Cuomo rips Mamdani's freebie 'fantasy,' says AOC proved socialism fails",
      "description": "Former Gov. Andrew Cuomo and Zohran Mamdani clashed over economic policies.",
      "link": "https://www.foxnews.com/politics/cuomo-rips-mamdanis-freebie-fantasy",
      "media_url": "https://a57.foxnews.com/static.foxnews.com/.../cuomo.png",
      "published_date": "2025-10-08T18:35:50+00:00",
      "source": "Fox News",
      "category": "politics",
      "topics": ["economic policies", "governance", "socialism"],
      "people": ["Andrew Cuomo", "Zohran Mamdani", "AOC"],
      "author": ["Jane Smith"]
    }
  ]
}

Example

$ curl "https://api.newsmesh.co/v1/trending?apiKey=nm_xxx&limit=10"

Get Latest Articles

GET/v1/latest

Get latest articles (automatically applies history window based on your plan).

Query Parameters

apiKey (required)
limit (optional, default: 10, max: 10 on Free & Starter, max: 25 on Growth & Pro)
category (optional) — Comma-separated, max 10
country (optional) — Filter by content relevance (what countries the article discusses)
sourceCountry (optional) — Filter by news outlet's country (where the source is based)
cursor (optional) — Pagination cursor from previous response

Available Countries

Both country and sourceCountry accept ISO 3166-1 alpha-2 codes (35 countries supported):

View all country codes

au Australiaie Irelandsg Singaporebe Belgiumil Israelza South Africabr Brazilit Italykr South Koreaca Canadajp Japantw Taiwancn Chinamy Malaysiath Thailandco Colombiamx Mexicotr Turkeyeg Egyptnl Netherlandsae UAEfr Franceng Nigeriaua Ukrainede Germanyno Norwaygb United Kingdomhk Hong Kongph Philippinesus United Statesin Indiaru Russiave Venezuelaid Indonesiasa Saudi Arabia

Available Categories

politics, technology, business, health, entertainment, sports, science, lifestyle, environment, world

Examples

# Get latest 10 articles
$ curl "https://api.newsmesh.co/v1/latest?apiKey=nm_xxx&limit=10"

# Get sports articles
$ curl "https://api.newsmesh.co/v1/latest?apiKey=nm_xxx&category=sports"

# Filter by multiple categories
$ curl "https://api.newsmesh.co/v1/latest?apiKey=nm_xxx&category=politics,business"

# Get news about events in the US
$ curl "https://api.newsmesh.co/v1/latest?apiKey=nm_xxx&country=us"

# Get news about multiple countries
$ curl "https://api.newsmesh.co/v1/latest?apiKey=nm_xxx&country=us,gb,ca"

# Combine country and category filters
$ curl "https://api.newsmesh.co/v1/latest?apiKey=nm_xxx&country=us&category=politics"

Search Articles

GET/v1/search

Search articles by keyword with optional date filtering and sorting. Supports advanced query syntax including phrases, exclusions, and boolean operators. Word forms are matched automatically (e.g., "walk" matches "walking", "walked").

Query Parameters

apiKey (required)
q (required) — Search query. Supports: "phrase", -exclude, AND, OR
searchIn (optional) — Fields to search: title, description
from (optional) — Start date YYYY-MM-DD
to (optional) — End date YYYY-MM-DD
category (optional) — Filter by category (comma-separated)
sources (optional) — Include only specific sources by domain URL (e.g., nytimes.com, wsj.com)
excludeSources (optional) — Exclude specific sources by domain URL
country (optional) — Filter by content relevance (ISO codes: us, gb, ca)
sourceCountry (optional) — Filter by news outlet's country (ISO codes: us, gb, ca)
limit (optional, default: 10, max: 10 on Free & Starter, max: 25 on Growth & Pro)
sortBy (optional, default: date_descending)
cursor (optional) — Pagination cursor

Sort Options

date_descending — Newest first (default)
date_ascending — Oldest first
relevant — Most relevant to search query

Examples

# Basic search
$ curl "https://api.newsmesh.co/v1/search?apiKey=nm_xxx&q=climate"

# Phrase search (exact match)
$ curl "https://api.newsmesh.co/v1/search?apiKey=nm_xxx&q=\"climate change\""

# Exclude terms
$ curl "https://api.newsmesh.co/v1/search?apiKey=nm_xxx&q=bitcoin+-scam"

# OR search (either term matches)
$ curl "https://api.newsmesh.co/v1/search?apiKey=nm_xxx&q=tennis+OR+golf"

# Filter by source
$ curl "https://api.newsmesh.co/v1/search?apiKey=nm_xxx&q=news&sources=nytimes.com,wsj.com"

# Search with date range
$ curl "https://api.newsmesh.co/v1/search?apiKey=nm_xxx&q=election&from=2025-10-01&to=2025-10-05"

Get Single Article

GET/v1/article/{article_id}

Get a specific article by its ID.

Path Parameters

article_id (required) — Unique article identifier

Example

$ curl "https://api.newsmesh.co/v1/article/4c213ea447c9773981780776c9b7399b?apiKey=nm_xxx"

Error Responses

All endpoints return errors in a consistent format:

{
  "status": "error",
  "code": "errorCodeInCamelCase",
  "message": "Human-readable error description."
}

Common Error Codes

HTTP Status	Error Code	Description
400	`queryMissing`	Search query parameter 'q' is required
401	`apiKeyMissing`	No API key provided
401	`invalidApiKey`	Invalid or non-existent API key
403	`forbidden`	Access forbidden
429	`rateLimitExceeded`	Requests per second limit exceeded
429	`dailyLimitExceeded`	Daily request limit reached
429	`monthlyLimitExceeded`	Monthly request limit reached

Rate Limits & Plans

Plan	Price	RPS	Results per Request	Monthly Requests	History	Freshness
Free	$0/mo	1	10	750	7 days	24-hour delay
Starter	$29/mo	2	10	5,000	7 days	1-hour delay
Growth	$79/mo	10	25	75,000	30 days	Real-time
Pro	$199/mo	20	25	250,000	6 months	Real-time

CORS Policy

The Free plan only allows requests from localhost origins (for local development). Paid plans allow requests from any origin, enabling production deployments.

Response Headers

Every response includes headers to help you pace requests and monitor usage:

X-RateLimit-Limit: 5
X-RateLimit-Remaining: 4
X-RateLimit-Reset: 1
X-Account-RateLimit-Limit: 10000
X-Account-RateLimit-Remaining: 9847
X-Account-RateLimit-Reset: 1735689600

Per-Second Rate Limit

X-RateLimit-Limit — Requests allowed per second
X-RateLimit-Remaining — Requests remaining this second
X-RateLimit-Reset — Seconds until reset (always 1)

Account Rate Limit (Daily Quota)

X-Account-RateLimit-Limit — Your daily request limit
X-Account-RateLimit-Remaining — Requests remaining today
X-Account-RateLimit-Reset — When your daily limit resets (Unix timestamp, midnight UTC)

Rate Limit Exceeded (429)

When you exceed a rate limit, the response includes:

Retry-After — Seconds to wait before retrying

Pagination

Endpoints that return multiple articles support cursor-based pagination:

Make initial request without cursor parameter
Check next_cursor in response
Use next_cursor value in subsequent request
Continue until next_cursor is null

Example

# Page 1
$ curl "https://api.newsmesh.co/v1/latest?apiKey=nm_xxx&limit=25"

# Page 2 (using cursor from previous response)
$ curl "https://api.newsmesh.co/v1/latest?apiKey=nm_xxx&limit=25&cursor=eyJwdWJsaXNoZWRfZGF0ZSI6..."

Best Practices

Use /v1/trending for homepage feeds — it's cached and returns fastest
Use /v1/latest for category browsing — no date range needed
Use /v1/search for keyword search — when users need to find specific topics
Cache responses — reduce API calls by caching on your end
Handle rate limits gracefully — implement exponential backoff on 429 errors
Store pagination cursors — for implementing infinite scroll
Monitor your usage — track daily/monthly limits to avoid overage charges

Libraries

Use our official client libraries to integrate NewsMesh into your application.

🐍

Python

View Docs →

Support

For API support, contact us at:

[email protected]