Quickstart
Subscribe to your tickers, read stories, and receive your first webhook.
Which tickers are covered
newsfilter currently processes 13 tickers: AAPL, ADI, CAT, CSCO, DELL, LLY, MU, NKE, NVDA, NXPI, SNDK, STX and TXN. You can subscribe to others, but they get no news yet. Coverage that follows subscriptions, with a backfill of recent news for newly added tickers, is coming.
You need an API key and your app id. Both come from the newsfilter team; the key belongs to your app and every call made with it acts as that app.
export NEWSFILTER_KEY=nf_… # your API key
export APP=your-app-idSubscribe to your tickers
Your subscriptions decide which tickers' webhooks and catch-up events you
receive. The list is replaced as a whole. Read it first to get its
revision:
curl https://api.newsfilter.dev/v1/subscriptions/$APP \
-H "Authorization: Bearer $NEWSFILTER_KEY"{ "app": "your-app-id", "revision": 0, "tickers": [] }Then send the full list with the revision you read:
curl -X PUT https://api.newsfilter.dev/v1/subscriptions/$APP \
-H "Authorization: Bearer $NEWSFILTER_KEY" \
-H "Content-Type: application/json" \
-d '{ "tickers": ["MU", "NVDA"], "revision": 0 }'{
"app": "your-app-id",
"revision": 1,
"tickers": ["MU", "NVDA"],
"added": ["MU", "NVDA"],
"removed": []
}If the list changed since you read it, the request is refused with 409
and nothing changes. Read it again and retry. See
Replace subscriptions.
Read stories
Stories for one ticker, newest activity first:
curl "https://api.newsfilter.dev/v1/stories?ticker=MU" \
-H "Authorization: Bearer $NEWSFILTER_KEY"Or only the strong ones:
curl "https://api.newsfilter.dev/v1/strong?ticker=MU" \
-H "Authorization: Bearer $NEWSFILTER_KEY"Without ticker, the strong feed lists strong stories for every ticker
newsfilter covers.
The filtered articles themselves are at
GET /v1/articles. Lists are
paginated: pass next_cursor back as cursor until it is null.
Receive webhooks
Give the newsfilter team an HTTPS URL. You get back a signing secret
(whsec_…). From then on, every change to a story on your tickers is
POSTed to that URL, signed with Standard Webhooks.
A minimal receiver, as a Next.js route handler:
import { Webhook } from 'standardwebhooks';
const wh = new Webhook(process.env.NEWSFILTER_WEBHOOK_SECRET!);
export async function POST(req: Request) {
const body = await req.text(); // the raw body: verify before parsing
let event: { event_id: string; type: string };
try {
event = wh.verify(body, Object.fromEntries(req.headers)) as typeof event;
} catch {
return new Response('bad signature', { status: 401 });
}
await saveForLater(event); // store it, then answer; process it afterwards
return new Response(null, { status: 204 });
}Receiving webhooks covers retries, duplicates and ordering.