Skip to main content

Documentation Index

Fetch the complete documentation index at: https://rocks.docs.rive.wtf/llms.txt

Use this file to discover all available pages before exploring further.

Every API key is tied to one IP. To apply for a key, DM southctrl on Discord.
Use the endpoint path below, replace the required params, and send Authorization: Bearer YOUR_API_KEY.

​
Most Used Endpoints

Top Headlines

Get the latest headlines

Everything

Search wider news coverage
Use top headlines for fast breaking news and everything when you need broader search results.

​
Top Headlines

Get the latest breaking news headlines.

​
Endpoint

GET /api/news/top-headlines

​
Query Parameters

​
country
string
default:"us"
2-letter ISO 3166-1 country code. Defaults to us if no other filter is provided.
​
category
string
Category to filter by. Options: business, entertainment, general, health, science, sports, technology.
​
sources
string
Comma-separated news source IDs. Cannot be used with country or category. Example: techcrunch,bbc-news.
​
q
string
Keywords in headlines.

​
Example Request

cURL
curl "https://rocks.rive.wtf/api/news/top-headlines" \
  -H "Authorization: Bearer YOUR_API_KEY"
cURL with filters
curl "https://rocks.rive.wtf/api/news/top-headlines?country=us&category=business" \
  -H "Authorization: Bearer YOUR_API_KEY"
JavaScript
const response = await fetch('https://rocks.rive.wtf/api/news/top-headlines?country=us&category=technology', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});
const data = await response.json();
console.log(data);
Python
import requests
headers = {'Authorization': 'Bearer YOUR_API_KEY'}
params = {'country': 'us', 'category': 'business'}
response = requests.get(
    'https://rocks.rive.wtf/api/news/top-headlines',
    headers=headers,
    params=params
)
print(response.json())

​
Example Response

{
  "status": "ok",
  "totalResults": 37,
  "articles": [
    {
      "source": {
        "id": "cnn",
        "name": "CNN"
      },
      "author": "John Doe",
      "title": "Breaking: Major economic developments today",
      "description": "A summary of the article content.",
      "url": "https://cnn.com/article",
      "urlToImage": "https://cnn.com/image.jpg",
      "publishedAt": "2026-03-17T00:16:00Z",
      "content": "Full article content..."
    }
  ]
}

​
Everything

Search across all news articles with advanced filtering.

​
Endpoint

GET /api/news/everything

​
Query Parameters

​
q
string
Keywords in article titles and body.
​
domains
string
Comma-separated list of domains to restrict results to. Example: wsj.com,bbc.co.uk.
​
sources
string
Comma-separated news source IDs to filter by.
​
from
string
Oldest article date in ISO 8601 format. Example: 2026-03-01.
​
to
string
Newest article date in ISO 8601 format. Example: 2026-03-17.
​
sortBy
string
default:"publishedAt"
Sort order. Options: relevancy, popularity, publishedAt.

​
Example Request

cURL
curl "https://rocks.rive.wtf/api/news/everything?domains=wsj.com" \
  -H "Authorization: Bearer YOUR_API_KEY"
cURL with filters
curl "https://rocks.rive.wtf/api/news/everything?q=tesla&from=2026-02-17&sortBy=publishedAt" \
  -H "Authorization: Bearer YOUR_API_KEY"
JavaScript
const response = await fetch('https://rocks.rive.wtf/api/news/everything?q=apple&from=2026-03-16&to=2026-03-16&sortBy=popularity', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});
const data = await response.json();
console.log(data);
Python
import requests
headers = {'Authorization': 'Bearer YOUR_API_KEY'}
params = {
    'q': 'tesla',
    'from': '2026-02-17',
    'sortBy': 'publishedAt'
}
response = requests.get(
    'https://rocks.rive.wtf/api/news/everything',
    headers=headers,
    params=params
)
print(response.json())

​
Example Response

{
  "status": "ok",
  "totalResults": 4267,
  "articles": [
    {
      "source": {
        "id": "the-wall-street-journal",
        "name": "Wall Street Journal"
      },
      "author": "Jane Smith",
      "title": "Tesla announces new battery deal",
      "description": "A summary of the article content.",
      "url": "https://wsj.com/article",
      "urlToImage": "https://wsj.com/image.jpg",
      "publishedAt": "2026-03-17T08:00:00Z",
      "content": "Full article content..."
    }
  ]
}

​
Common Sources

SourceID
Wall Street Journalthe-wall-street-journal
TechCrunchtechcrunch
BBC Newsbbc-news
CNNcnn
Associated Pressassociated-press
Bloombergbloomberg
Business Insiderbusiness-insider
Vergethe-verge
At least one filter is required for /top-headlines. If none are provided, the API defaults to country=us.