NewsAPI Search

Search news articles via NewsAPI with filtering by time windows, sources, domains, and languages.

Security Scan

The skill appears to implement a straightforward NewsAPI client, but the package metadata does not declare the API key it actually requires and the scripts load the user's ~/.openclaw/.env wholesale — this mismatch and env-file handling merit caution.

Purpose & Capability

The name/description (NewsAPI search) aligns with the included scripts and behavior: both scripts call newsapi.org endpoints and implement search/sources functionality. However, the skill metadata declares no required environment variables or primary credential while the code clearly requires NEWSAPI_KEY — this registry omission is an inconsistency.

Instruction Scope

SKILL.md and the scripts' runtime instructions are narrowly scoped: they read a local ~/.openclaw/.env file for the API key and make HTTPS requests only to newsapi.org. The instructions do not direct reading of unrelated system files, nor do they post data to third‑party endpoints other than NewsAPI.

Install Mechanism

There is no install spec or remote download. This is an instruction-only skill with included JS scripts; nothing in the package pulls external code or installers.

Credentials

The code requires NEWSAPI_KEY but the registry metadata didn't declare it. The scripts implement a loader that reads ~/.openclaw/.env and sets process.env for every key there — so if that file contains other secrets they will be loaded into the process environment (even if the scripts don't explicitly use them). Requiring a single NewsAPI key is reasonable for the stated purpose, but the metadata mismatch and the wholesale .env loading are proportionality concerns.

Persistence & Privilege

The skill does not request always:true, does not modify other skills or system-wide configs, and does not persist beyond its scripts. Autonomous invocation is allowed by platform default but is not combined here with other high-privilege requests.

What to consider before installing

This package is mostly what it says: a NewsAPI client implemented in Node. Before installing or running it, verify and decide whether you are comfortable putting your NewsAPI key in ~/.openclaw/.env and ensure that file does not contain unrelated secrets. The registry metadata failing to declare NEWSAPI_KEY is a red flag — ask the publisher to update the metadata or add the key declaration yourself. Review the scripts locally (they are small and readable) to confirm there are no hidden endpoints or behaviors, and ensure the .env file has restrictive permissions (e.g., 600). If you plan to let an agent invoke the skill autonomously, consider the limited free-tier quota (100/day) and avoid storing other credentials in ~/.openclaw/.env to reduce accidental exposure.

Search 5,000+ news sources via NewsAPI. Supports comprehensive article discovery (/everything) and breaking headlines (/top-headlines).

Quick Start

# Basic search
node scripts/search.js "technology" --days 7

# Filter by quality sources
node scripts/search.js "technology" --sources bbc-news,reuters,al-jazeera-english

# Exclude low-quality domains
node scripts/search.js "technology" --exclude tmz.com,radaronline.com

# Breaking headlines
node scripts/search.js "technology" --headlines --country us

# List available sources
node scripts/sources.js --country us --category general

Setup

Add API key to ~/.openclaw/.env:

NEWSAPI_KEY=your_api_key

Get key from https://newsapi.org (free tier: 100 requests/day)

Endpoints

Everything Search

Comprehensive search across millions of articles.

Time Windows:

node scripts/search.js "query" --hours 24
node scripts/search.js "query" --days 7        # default
node scripts/search.js "query" --weeks 2
node scripts/search.js "query" --months 1
node scripts/search.js "query" --from 2026-01-01 --to 2026-01-31

Filters:

node scripts/search.js "query" --sources bbc-news,cnn           # max 20
node scripts/search.js "query" --domains nytimes.com,bbc.co.uk
node scripts/search.js "query" --exclude gossip-site.com
node scripts/search.js "query" --lang en                       # or 'any'

Search Fields:

node scripts/search.js "query" --title-only                    # title only
node scripts/search.js "query" --in title,description          # specific fields

Advanced Query Syntax:

• "exact phrase" — exact match
• +musthave — required word
• -exclude — excluded word
• word1 AND word2 — both required
• word1 OR word2 — either accepted
• (word1 OR word2) AND word3 — grouping

Pagination & Sorting:

node scripts/search.js "query" --page 2 --limit 20
node scripts/search.js "query" --sort relevancy      # default
node scripts/search.js "query" --sort date           # newest first
node scripts/search.js "query" --sort popularity

Top Headlines

Live breaking news by country or category.

# By country
node scripts/search.js "query" --headlines --country us

# By category
node scripts/search.js --headlines --country us --category business

# By source
node scripts/search.js --headlines --sources bbc-news,cnn

Categories: business, entertainment, general, health, science, sports, technology

Note: Cannot mix --country/--category with --sources in headlines mode.

List Sources

node scripts/sources.js                    # all sources
node scripts/sources.js --country us       # filter by country
node scripts/sources.js --category business
node scripts/sources.js --lang en
node scripts/sources.js --json             # JSON output

Advanced Usage

For complete parameter reference, see references/api-reference.md.

For common workflows and search patterns, see references/examples.md.

Programmatic API

const { searchEverything, searchHeadlines, getSources } = require('./scripts/search.js');

const results = await searchEverything('climate change', {
  timeWindow: { type: 'days', value: 7 },
  sources: 'bbc-news,reuters',
  excludeDomains: 'tmz.com',
  limit: 20
});

const headlines = await searchHeadlines('business', {
  country: 'us',
  category: 'business'
});

Free Tier Limits

• 100 requests/day
• 100 results per request (max)
• 1-month delay on archived content

Output Format

Returns structured JSON:

{
  "query": "technology",
  "endpoint": "everything",
  "totalResults": 64,
  "returnedResults": 10,
  "page": 1,
  "results": [
    {
      "title": "...",
      "url": "...",
      "source": "BBC News",
      "publishedAt": "2026-02-05T14:30:00Z",
      "description": "...",
      "content": "..."
    }
  ]
}