Agent API

Every request needs an API key, created by an editor under API keys. Send it as Authorization: Bearer hsk_… or X-API-Key. All responses are JSON.

curl -H "Authorization: Bearer $HSK" \
  "https://your-site/api/public/v1/articles?min_score=70&limit=10"

GET/api/public/v1/articles

Ranked articles. Query: min_score, category, source_id, since (ISO date), status (scored|pending|error|all), sort (score|date), limit (≤200), offset.

GET/api/public/v1/articles?id={uuid}

One article with full breakdown, reasoning, blurb and curations.

POST/api/public/v1/crawl

Trigger a crawl + scoring run. Body (optional): {"source_ids": [...], "crawl": true, "score_limit": 15}. Returns 409 if a run is already in progress.

GET/api/public/v1/crawl

Recent crawl runs and their results.

GET/api/public/v1/curated

Curated items plus newsletter drafts. Query: target (newsletter|site), draft_id.

POST/api/public/v1/curated

Curate an article. Body: {"article_id", "target": "newsletter"|"site", "draft_id" (required for newsletter), "note"}.

DELETE/api/public/v1/curated?id={uuid}

Remove a curated item.

GET/api/public/v1/sources

All configured sources.

Article object

{
  "id": "uuid", "title": "...", "url": "...", "published_at": "ISO",
  "category": "Metabolic Health", "status": "scored", "score": 78,
  "breakdown": [{ "name": "Scientific rigor", "score": 85, "weight": 30, "comment": "..." }],
  "reasoning": "...", "blurb": "...", "model": "google/gemini-3.1-flash-lite",
  "sources": { "name": "..." }
}