# API Reference for Agents
## Server Salt (for signed endpoints)
serverSalt = "7885458f2ca86c5b4504d1f381eb2c87e9adfb1c81891b62c1b1d608f97e21ca"
Sign any `url` parameter with: hex(sha256(url + serverSalt))
## GET /
Query params:
- sources: comma-separated source slugs (e.g. svd,dn)
- keywords: comma-separated OR groups, plus-separated AND terms (e.g. ai,gpt,jensen+huang)
- since: duration like 10m, 1h, 3h, 12h, 1d
- format: html (default), json, rss, markdown
- fontSize: integer pixel size
- extraSpacing: integer line spacing
- limit: max results (default 100, max 200)
- before: unix timestamp for pagination
- ids: comma-separated URL hashes for specific articles
## GET /api/headlines
Paginated JSON API. Same filtering params as `/`.
Additional params:
- before: unix timestamp; fetch headlines older than this
- limit: page size (default 100, max 200)
Response:
{
"headlines": [...],
"has_more": bool,
"next_before": unix_timestamp,
"total": int
}
## GET /summary/:window
HTML summaries. Windows: 1h, 3h, 12h, 24h.
## GET /article-data
Requires: url, sign (computed with serverSalt above)
Returns: { hash, title, title_en, description, description_en }
## GET /story-keywords
Requires: url, sign (computed with serverSalt above)
Returns: { article_ids: [...], count: int, fallback: bool }
## GET /next-article
Article-to-article chain navigation (story follower / recommendation walk).
Requires: url, sign (sha256(url + serverSalt) for the url parameter)
Optional: chain = comma-separated url hashes of visited articles, current last.
Returns:
{
"mode": "story" | "recommended" | "end",
"score": int,
"related_count": int,
"article": { url, hash, title, title_en, description, description_en, source, first_seen } | null
}
`story` = same-story article (BM25 + entity overlap; hybridized with
embedding cosine when `--enable-embeddings` is on).
`recommended` = story chain exhausted; next article chosen by tag/entity
similarity (or embedding cosine) against the last 5 chain articles.
`end` = nothing left; article is null.
Response fields: `embedding` (true if cosine took part in the score),
`article.cosine` (0 unless embedding-based).
Available query parameters:
* ?sources=svd,dn
* ?keywords=ai,gpt
* ?since=10m
* ?format=markdown (or json, rss)
* ?fontSize=20
* ?extraSpacing=2
Summary of filtered headlines