Endpoints

All public endpoints live under /public/news. Base URL in local development is http://localhost:3003.

Overview

Method	Path	Auth	Description
GET	`/public/news/landing`	None	Last ~24h, max 20 articles. SEO-friendly.
GET	`/public/news`	Bearer	Query-filterable list, 7-day retention.
GET	`/public/news/:id`	Bearer	Single article by id.

GET /public/news/landing

Unauthenticated. Returns the most recent analyzed articles (capped at 20, past 24h). Intended for marketing/landing surfaces. Cached server-side for 60 seconds.

bash

curl http://localhost:3003/public/news/landing

GET /public/news

Authenticated. Filter the last 7 days of analyzed news.

Query parameters

Param	Type	Notes
`symbol`	string	Ticker, e.g. `AAPL`. Case-insensitive.
`category`	string	`earnings`, `macro`, `regulatory`, ...
`from`	ISO8601	Lower bound on `publishedAt`. Max window: 7 days.
`to`	ISO8601	Upper bound on `publishedAt`.
`limit`	number	1–100, default 50.
`minImpact`	number	0.0–1.0. Filter out low-impact noise.

Example

bash

curl -H "Authorization: Bearer ak_live_..." \
  "http://localhost:3003/public/news?symbol=AAPL&minImpact=0.5&limit=20"

GET /public/news/:id

Authenticated. Fetch a single article by its id. Useful for resolving a news reference stored elsewhere (e.g. in a trade journal).

bash

curl -H "Authorization: Bearer ak_live_..." \
  http://localhost:3003/public/news/01H...

Returns 404 if the id is unknown or older than 7 days.

Response shape

Every article follows the NewsArticleDto shape:

typescript

type NewsArticleDto = {
  id: string;
  title: string;
  source: string;
  url: string;
  publishedAt: string; // ISO 8601
  sentiment: 'bullish' | 'bearish' | 'neutral';
  symbols: string[];
  analysis: {
    summary: string;
    reason: string;
    impactScore: number; // 0.0 – 1.0
  } | null;
};

analysis is null when an article was ingested but the LLM pipeline hasn't completed yet. Retry after ~30 seconds.