API Documentation

Base URL: https://agentsignal.dev

Default response format: Markdown. Add ?format=json for structured JSON.

No authentication required. Rate limited by IP. Persistent SQLite storage.

Pull — Get Signals

GET /feed

Returns ranked signals from all sources. Markdown by default.

curl agentsignal.dev/feed

Query Parameters:

Param	Example	Description
`topic`	`?topic=ai`	Keyword filter (title, summary, topics)
`source`	`?source=hackernews`	Filter by source name (comma-separated)
`type`	`?type=news,market`	Filter by signal type
`min_score`	`?min_score=70`	Minimum signal score (0-100)
`limit`	`?limit=50`	Results count (default 30, max 100)
`after`	`?after=2026-03-14T10:00:00Z`	Only signals after this timestamp
`format`	`?format=json`	Output format: markdown (default) or json
`follow`	`?follow=f_abc123`	Use a follow subscription for filtering
`since_id`NEW	`?since_id=sig_hn_123`	Cursor pagination — only signals newer than this ID
`from`NEW	`?from=2026-03-14T00:00:00Z`	Historical replay — start of time range (ISO 8601)
`to`NEW	`?to=2026-03-14T12:00:00Z`	Historical replay — end of time range (ISO 8601)

Response Headers:

Header	Example	Description
`ETag`	`"a1b2c3d4e5f6"`	Hash of signal IDs — use with `If-None-Match`
`Last-Modified`	`Sat, 14 Mar 2026 10:30:00 GMT`	Timestamp of most recent signal
`X-Latest-Id`	`sig_hn_12345`	ID of most recent signal — use as `since_id` cursor
`X-Signal-Count`	`30`	Number of signals in response
`X-Next-Poll`	`60`	Suggested seconds before next poll
`X-Truncated`	`true`	Present when historical replay results were capped at 500
`Cache-Control`	`public, max-age=30`	Safe to cache for 30 seconds

Example response (JSON):

{
  "ok": true,
  "count": 30,
  "timestamp": "2026-03-14T10:30:00Z",
  "latest_id": "sig_hn_12345",
  "signals": [
    {
      "id": "sig_hn_12345",
      "timestamp": "2026-03-14T10:25:00Z",
      "type": "social",
      "source": "hackernews",
      "title": "Show HN: Unified signal feed for AI agents",
      "summary": "342 points by user | 89 comments",
      "url": "https://news.ycombinator.com/item?id=12345",
      "topics": ["ai", "agents", "show-hn"],
      "score": 78,
      "metadata": {
        "score": 342,
        "comments": 89,
        "entities": {
          "companies": ["OpenAI"],
          "tickers": [],
          "people": []
        }
      }
    }
  ]
}

GET /sources

Lists all registered sources and their current status.

curl agentsignal.dev/sources

GET /health

Health check. Returns uptime, timestamp, and whether /ask is enabled.

Delta Updates NEW

Efficient polling — only fetch what's new. Three methods to avoid re-downloading the entire feed.

Option 1: Cursor Pagination (`since_id`)

Save the X-Latest-Id header from each response. Pass it back on the next request to get only newer signals.

# First request
curl -i agentsignal.dev/feed?format=json
# → X-Latest-Id: sig_hn_12345

# Next poll — only new signals
curl agentsignal.dev/feed?format=json&since_id=sig_hn_12345

Option 2: ETag / Conditional Requests

Use standard HTTP caching. If nothing changed, you get a 304 Not Modified (empty body, zero tokens).

# First request
curl -i agentsignal.dev/feed
# → ETag: "a1b2c3d4e5f6"

# Conditional poll
curl -H 'If-None-Match: "a1b2c3d4e5f6"' agentsignal.dev/feed
# → 304 Not Modified (if no new signals)

Option 3: Historical Replay (`from` / `to`)

Query a specific time window. Max 500 signals per replay. SQLite-backed, so historical data persists across restarts (up to 7 days).

# What happened in the last 6 hours?
curl "agentsignal.dev/feed?format=json&from=2026-03-14T04:00:00Z&to=2026-03-14T10:00:00Z"

# All high-signal crypto from yesterday
curl "agentsignal.dev/feed?format=json&from=2026-03-13T00:00:00Z&to=2026-03-14T00:00:00Z&topic=crypto&min_score=70"

If results are capped, the response includes X-Truncated: true header. Narrow your time range or add filters.

Ask — Question Answering

POST /ask

Ask a natural language question. Get an answer grounded in real-time signals, powered by Claude.

Requires ANTHROPIC_API_KEY on the server. Rate limited to 20 questions/hr per IP.

curl -X POST agentsignal.dev/ask \
  -H "Content-Type: application/json" \
  -d '{"q": "What happened to crypto in the last 2 hours?"}'

Request Body:

Field	Type	Description
`q`	string (required)	Your question
`lookback`	string	Time window: "1h", "6h", "24h" (default: "6h")

Response (plain text by default):

BTC dropped 5.2% to $82,100 following hawkish Fed comments.
ETH and SOL down 3-4%. Polymarket June rate cut odds fell
from 62% to 41%. Social sentiment bearish across Reddit and HN.

Follow — Topic Subscriptions

Create personalized feeds by following topics. Like Google Alerts but for agents, across all sources, ranked. Persisted in SQLite — survives restarts.

POST /follow

Create a new topic subscription.

curl -X POST agentsignal.dev/follow \
  -H "Content-Type: application/json" \
  -d '{"topics": ["ai", "regulation"], "min_score": 60}'

Request Body:

Field	Type	Description
`topics`	string[] (required)	Keywords to follow (max 10)
`sources`	string[]	Only these sources
`types`	string[]	Only these signal types
`min_score`	number	Minimum score (0-100)

Response:

{
  "ok": true,
  "follow_id": "f_abc123",
  "topics": ["ai", "regulation"],
  "min_score": 60,
  "feed_url": "/feed?follow=f_abc123"
}

Then poll your personalized feed:

curl agentsignal.dev/feed?follow=f_abc123

GET /follow

List all your follows (identified by IP).

GET /follow/:id

Get details of a specific follow.

DELETE /follow/:id

Delete a follow subscription.

Webhooks — Real-time Push NEW

Instead of polling, register a URL and AgentSignal pushes new signals to you in real time. Includes retry logic and dead agent detection.

POST /webhooks

curl -X POST agentsignal.dev/webhooks \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-agent.com/signals",
    "topics": ["ai", "crypto"],
    "min_score": 50
  }'

Request Body:

Field	Type	Description
`url`	string (required)	HTTPS endpoint to receive POSTs
`topics`	string[]	Only push signals matching these topics
`min_score`	number	Minimum score threshold (default: 0)

Response:

{
  "ok": true,
  "webhook_id": "wh_abc123",
  "url": "https://your-agent.com/signals",
  "topics": ["ai", "crypto"],
  "min_score": 50
}

Webhook Payload

When new signals match your criteria, AgentSignal POSTs a JSON payload to your URL:

{
  "event": "new_signals",
  "timestamp": "2026-03-14T10:30:00Z",
  "webhook_id": "wh_abc123",
  "signals": [
    {
      "id": "sig_hn_12345",
      "title": "Breaking: Major AI regulation bill passed",
      "score": 85,
      "source": "google-news",
      "type": "news",
      "url": "https://...",
      "timestamp": "2026-03-14T10:28:00Z",
      "summary": "Congress passes comprehensive AI safety legislation..."
    }
  ]
}

Retry & Dead Agent Detection

If your endpoint fails, AgentSignal retries with exponential backoff:

Attempt	Delay	Timeout
1st	Immediate	5 seconds
2nd	1 second	5 seconds
3rd	4 seconds	5 seconds

After 10 consecutive failures, the webhook is marked dead and skipped in future dispatches. Re-register to reactivate.

GET /webhooks

List your registered webhooks (by IP).

curl agentsignal.dev/webhooks

DELETE /webhooks/:id

Delete a webhook.

curl -X DELETE agentsignal.dev/webhooks/wh_abc123

Security

HTTPS URLs only — no HTTP
No private/localhost IPs (SSRF prevention)
Max 5 webhooks per IP, 100 total
Payloads include User-Agent: AgentSignal/0.1

Sources

All sources are free, require no API keys, and are polled on fixed intervals.

Source	Type	What	Interval
Hacker News	`social`	Top 30 stories	60s
Reddit	`social`	6 subreddits, hot posts	120s
Google News	`news`	General, tech, business	120s
CoinGecko	`market`	Top 20 coins + trending	60s
Yahoo Finance	`market`	Major indices + active stocks	120s
DeFi Llama	`market`	Top DeFi protocols by TVL change	120s
Polymarket	`events`	Prediction markets ($10K+ volume)	300s
Kalshi	`events`	Regulated event contracts	300s
Metaculus	`events`	Community forecasting questions	300s
RSS Feeds	`news`	15 feeds: BBC, Wired, Axios, Politico + more	120s
Techmeme	`news`	Curated tech news aggregator	120s
Crunchbase	`news`	Startup funding + acquisitions	600s
SEC EDGAR	`news`	8-K material event filings	600s
Congress.gov	`news`	Most viewed bills + legislation	600s
CVE / NVD	`news`	Security vulnerabilities by severity	300s
GDELT	`news`	Global event monitoring	300s
ArXiv	`science`	AI/ML/CS papers	300s
Hugging Face	`science`	Trending AI models	300s
GitHub Trending	`social`	Trending repos daily	300s
Product Hunt	`social`	Daily product launches	300s
Lobsters	`social`	Curated tech discussion	120s
FRED	`market`	Economic indicators (CPI, GDP, rates)	3600s

Live Source Status

Loading...

Signal Scoring v2 NEW

Every signal is scored 0-100 using an entity-aware, multi-factor scoring engine:

Factor	Weight	What it measures
Engagement	30%	Upvotes, comments, volume — type-aware normalization (science papers get 2x multiplier vs social)
Recency	25%	Exponential decay — half-life of ~6 hours
Magnitude	20%	Price change %, earthquake magnitude, prediction odds shift
Cross-source	15%	Entity-based matching — same company/person/ticker across sources. 4+ sources = 100, 3 = 80, 2 = 50
Authority	10%	Topic-dependent — USGS scores 95 for geo but 30 for other topics. CoinGecko scores 85 for markets.

Developing Story Detection

When the same entity (company, person, ticker) appears in 3+ signals from different sources within 2 hours, all related signals get a +15 score boost. This surfaces breaking/developing stories automatically.

Intelligence Pipeline

Sources → Pre-filter → Entity Extraction → Score → SQLite → Enrich (Haiku) → Dispatch

Pre-filter: Removes duplicate URLs, garbage titles (<10 chars), title=summary artifacts.

Entity extraction: Regex-based ticker detection ($BTC, $AAPL), company name mapping (~30 variants), notable people lookup (~20), unified topic keywords (~40).

Feed output groups signals into tiers: High Signal (80+), Notable (40-79), Background (<40).

Signal Enrichment NEW

High-scoring signals (score ≥ 60) are automatically enriched via Claude Haiku. Enrichment extracts structured entities, generates a 1-line "why this matters" summary, and assigns a category.

Enriched signals include in metadata:

{
  "metadata": {
    "enrichment": {
      "entities": {
        "people": ["Sam Altman"],
        "companies": ["OpenAI", "Microsoft"],
        "tickers": ["$MSFT"]
      },
      "summary": "OpenAI announces GPT-5, signaling major competitive shift in AI race",
      "category": "AI"
    }
  }
}

Categories: AI, Crypto, Markets, Geopolitics, Science, Tech, Security, Climate, Sports, Economy, Other

Enrichment is async — signals appear immediately, enrichment data follows within seconds. Requires ANTHROPIC_API_KEY.

Signal Schema

Every signal follows this exact shape, regardless of source:

{
  "id": "sig_hn_12345",          // Unique identifier
  "timestamp": "2026-03-14...",  // ISO 8601
  "type": "social",              // news | market | social | events | science | geo
  "source": "hackernews",       // Source name
  "title": "...",                // Signal title
  "summary": "...",              // 1-2 sentence summary
  "url": "https://...",          // Original source URL (unique — dedup key)
  "topics": ["ai", "tech"],     // Topic tags (auto-extracted)
  "score": 78,                   // Signal score 0-100
  "metadata": {                  // Source-specific data + entities + enrichment
    "entities": { ... },
    "enrichment": { ... }
  }
}

Rate Limits

Endpoint	Limit	Window
`/feed`, `/sources`, `/follow`	100 requests	Per hour, per IP
`/webhooks`	100 requests	Per hour, per IP
`/ask`	20 requests	Per hour, per IP

Responses include X-Next-Poll: 60 header suggesting when to call back. Use ?since_id= or If-None-Match for efficient delta polling.

API Documentation

Pull — Get Signals

GET /feed

GET /sources

GET /health

Delta Updates NEW

Option 1: Cursor Pagination (since_id)

Option 2: ETag / Conditional Requests

Option 3: Historical Replay (from / to)

Ask — Question Answering

POST /ask

Follow — Topic Subscriptions

POST /follow

GET /follow

GET /follow/:id

DELETE /follow/:id

Webhooks — Real-time Push NEW

POST /webhooks

Webhook Payload

Retry & Dead Agent Detection

GET /webhooks

DELETE /webhooks/:id

Security

Sources

Live Source Status

Signal Scoring v2 NEW

Developing Story Detection

Intelligence Pipeline

Signal Enrichment NEW

Signal Schema

Rate Limits

Option 1: Cursor Pagination (`since_id`)

Option 3: Historical Replay (`from` / `to`)