Getting Started

The Newspilot API provides programmatic access to news signal intelligence. Three endpoints let your AI agent search for related topics, discover emerging signals, and track trending stories.

Base URL:

https://api.newspilot.cc/api/v1

All endpoints return JSON. Use the Authorization: Bearer <api_key> header for authentication.

Use in AI Agents

Give your AI agent real-time news intelligence. Works with Claude Code, Codex, Cursor, Windsurf, and any tool that supports skill/md files.

Install

Run in terminal:

Run step 1 in your local terminal (not inside Codex sandbox), then add step 2 to your codex.md or AGENTS.md:

Create .cursor/rules/newspilot.mdc with:

Download the SKILL.md and include it in your agent's context:

Or download manually: Download SKILL.md

Configure API Key

Set your API key as an environment variable in your shell. The agent will read it automatically. Not sure how? Just give your key to the agent — it can configure it for you.

export NEWSPILOT_API_KEY="np_your_api_key_here"

Don't have a key? Register to get one, then create an API key from the Dashboard. Need more credits? Visit Pricing.

Try It

After installation, ask your AI agent:

Your AI agent will search Newspilot and return related topics with full context — background overview, weekly update, latest events, and parent/child topic hierarchy.

Your AI agent will call the hot_signal endpoint and present trending topics ranked by recent event count.

Make sure you have set the NEWSPILOT_API_KEY environment variable before using. Get your key from the Dashboard.

Topic Search

POST /api/v1/search

Input an event description and retrieve the most semantically similar news topics. Each result includes a rich topic profile with descriptions, hierarchy, and optional event details.

Parameters

Parameter	Type	Required	Description
query	string	Yes	Event description (declarative statement of the event, avoid temporal modifiers like "recently")
top_k	int	No	Number of topics to return (0-20, default 5)
events_per_topic	int	No	Events per topic. 0 = none (default), -1 = all, N = latest N events sorted by date descending

Code Examples

curl Python Node

Response

Response Format

Each result contains: description (topic summary), overview (detailed), weekly (this week), latest (most recent), parent (parent topic or null), children (sub-topic list), score (0-1 similarity), and events array (if requested).

New Signals

GET /api/v1/digest/new_signal

Retrieve the daily generated snapshot of newly formed signals (topics). The date field indicates which UTC+0 day this snapshot describes, and the returned topic content is resolved from the snapshot's stored topic indices.

Parameters

Parameter	Type	Required	Description
limit	int	No	Number of signals to return (0-200, default 50)

Code Examples

curl Python Node

Response

Response Format

Hot Signals

GET /api/v1/digest/hot_signal

Retrieve the daily generated snapshot of hottest signals ranked by the number of newly added events for that day. The date field indicates which UTC+0 day this snapshot describes, and the returned topic content is resolved from the snapshot's stored topic indices.

Parameters

Parameter	Type	Required	Description
limit	int	No	Number of signals to return (0-200, default 50)

Code Examples

curl Python Node

Response

Response Format

Authentication

All API requests require an API key passed via the Authorization header.

Authorization: Bearer your_api_key_here

Code Examples

curl Python Node

You can manage your API keys from the Dashboard. Keep your keys secret — do not expose them in client-side code.

Error Codes

All errors follow a consistent JSON format with an error code and human-readable message.

{
  "error": {
    "code": "INVALID_QUERY",
    "message": "query parameter is required"
  }
}

Status	Code	Scenario
400	INVALID_QUERY	Query is empty or malformed
401	UNAUTHORIZED	Invalid or missing API key
429	RATE_LIMITED	Rate limit exceeded
500	INTERNAL_ERROR	Server internal error