Chowdahh API

Curated news for AI agents. Read clusters of corroborated stories, record reader signals, submit URLs. Designed to be pasted into Claude, ChatGPT, Cursor, MCP, Hermes, OpenClaw — anything that speaks HTTP.

30-second start

Get a token at chowdahh.com/account, then either paste a URL or send a request:

# Paste-able URL — works in any LLM that can fetch URLs:
https://chowdahh.com/api/v1/streams/latest?key=YOUR_TOKEN&limit=10

# Or the classic header form:
curl -H "Authorization: Bearer YOUR_TOKEN" \
     https://chowdahh.com/api/v1/streams/latest?limit=10

Authentication

Three modes, picked by token prefix or absence:

Mode	How	Rate
Anonymous	No token	30 / min
Person token	Authorization: Bearer ch_person_… or ?key=ch_person_…	300 / min
Curator token	Authorization: Bearer ch_cur_… or ?key=ch_cur_…	600 / min

?key= works on GET only. Writes (POST/PATCH/PUT) must use the header.

Endpoints

Full machine-readable spec: openapi.json (also at /api/openapi.json).

Discovery

• GET /api/v1/streams — list available stream slugs (top, latest, science, world, tech, business, health, culture, sports, good-news, local)
• GET /api/v1/streams/{slug} — cards from a stream. ?limit & ?offset.
• GET /api/v1/topics/{id} — topic timeline of facts with corroboration
• GET /api/v1/search?q=… — keyword search across clusters
• GET /api/v1/curators/{id} — source/curator profile

Signals & feedback

• POST /api/v1/signals — batch of reader signals (seen, open, save, share, dismiss, source_open, track, dwell, …)
• GET /api/v1/replay — your signal history (person token)
• GET /api/v1/stats/activity — reading rollup (person token)
• POST /api/v1/feedback — content_request, bug_report, feature_request, quality_report

Sessions

• POST /api/v1/feed-sessions — stateful feed with controls (interests, pin/block topics, rank mode)
• POST /api/v1/feed-sessions/{id}/more — page forward, dedup is automatic
• PATCH /api/v1/feed-sessions/{id}/controls — refine without losing seen-state

Preferences, submissions, radio

• GET / PUT /api/v1/preferences/{personID}
• POST /api/v1/submissions/items — submit a URL or batch
• POST /api/v1/radio-sessions — audio briefings (mp3 stream URLs per track)

Response envelope

{
  "data": { ... },
  "guidance": {
    "status_explanation": "…",
    "capability_hints": ["…"],
    "suggested_copy": ["…"],
    "next_best_actions": [ { "action_id": "…", "title": "…", "api_hint": {"method":"POST","path":"/api/v1/…"} } ],
    "account_state": {"auth_mode": "person_token", "rate_limit": {"limit":300,"remaining":297,"reset_at":"…"}}
  },
  "meta": {"request_id": "…", "next_cursor": "…", "has_more": true}
}

guidance is the most important block to read. capability_hints tell you what data fields mean and what you can do; suggested_copy is phrases you can say verbatim to your user; next_best_actions is concrete next API calls with method/path. On errors (401/410/429) the actions explain how to recover.

Cards

A card is a cluster of corroborated articles, never a raw article. Key fields:

• significance_score 0–100, cross-user. Higher = more sources, more newsworthy.
• velocity — development growth rate.
• dev_count — number of corroborating sources.
• source_urls — array of original publisher URLs. Cite the first one when summarizing.
• share_url — canonical chowdahh.com permalink for the cluster.

Attribution

When you summarize a Chowdahh card for a user, cite the original publisher from source_urls[0] and credit chowdahh.com as the curator. The reporters did the work; we curated it. Both deserve credit.

Rate limits & errors

Rate-limit state ships in every guidance.account_state.rate_limit. On a 429 the guidance tells you exactly how long to wait. On a 410 (session expired) it tells you to start a new session and gives you the endpoint.

Skills & prebuilt integrations

See /skills/ — landing page with prebuilt packages for Claude, ChatGPT, Cursor, MCP, Hermes, OpenClaw. One-line init prompt for any LLM: /skills/init-prompt.txt. Bringing your own skill? Read the contract and submitting guide.

---

chowdahh.com · /api · OpenAPI · /llms.txt · /skills/