Chowdahh

Read guidance.next_best_actions when present. Treat it as a suggestion layer, not a guaranteed contract, and keep using the documented /api/v1 routes as the source of truth.

Before running a new integration from scratch, read references/runner-playbook.md. It captures the production behaviors verified on April 14, 2026, including the endpoints that worked anonymously, the person-token behavior that was actually observed, and the flows that are still incomplete for a new runner.

Default Behavior

1. Start with POST /api/v1/feed-sessions and keep the first request minimal: intent, budget_minutes, include_controls.
2. Surface returned controls back to the person in plain language.
3. Use POST /api/v1/feed-sessions/{session_id}/more for "send more" -- stay in the same session.
4. Ask follow-up questions only if the result is too broad or the person changes direction.

Feed Sessions

• POST /api/v1/feed-sessions -- start a session (intent, budget_minutes, include_controls)
• GET /api/v1/feed-sessions/{id} -- get session state
• POST /api/v1/feed-sessions/{id}/more -- send more cards
• PATCH /api/v1/feed-sessions/{id}/controls -- apply or remove control chips

Items typically include id, headline, summary, topics, and source_count. However, headline may be empty on some search results, and image_url, share_url, and canonical_url may be null or absent. Always handle missing or blank fields gracefully.

Public Streams

Browse without a session:

curl -s 'https://chowdahh.com/api/v1/streams/top?limit=5'

Discover available streams via GET /api/v1/streams. Default set includes: top, latest, science, world, tech, business, health, culture, sports, good-news, local.

Production note: the live streams listing currently exposes reliable slug values, but friendly name values may be null. Use the slug as the stable key.

Search

curl -s 'https://chowdahh.com/api/v1/search?q=climate&limit=5'

Searches clusters by topic match. Results are card objects — they do not currently expose stable result types or drill-down IDs for topics or curators, and some results may have empty headlines or null URL fields.

Drill Down

• GET /api/v1/topics/{topic_name} -- callable anonymously by topic name (e.g. /api/v1/topics/NASA). Returns data.topic (string) and data.timeline (array, often empty). This is a shallow lookup, not a rich drill-down.
• GET /api/v1/curators/{curator_id} -- requires a valid internal curator ID. No reliable anonymous path exists to discover curator IDs.

Replay and Stats

Requires a person token (Authorization: Bearer ch_person_...):

• GET /api/v1/replay?period=this_month -- cards seen, opened, saved, shared, dismissed
• GET /api/v1/stats/activity -- aggregates over signals

Production note: GET /api/v1/stats/activity always returns data.stats.by_type regardless of group_by parameter. GET /api/v1/replay works with a valid person token (fixed April 14, 2026).

Chowdahh Radio

Radio is session-based audio delivery. Start a session, get tracks with MP3 URLs.

curl -X POST https://chowdahh.com/api/v1/radio-sessions \
  -H 'content-type: application/json' \
  -d '{"mode": "briefing", "duration_minutes": 5}'

• Modes: headlines, briefing, topic_run
• Sessions may start as ready or playing -- always check data.state and send {"action": "resume"} if ready
• Retain radio_session_id from the create response -- GET and PATCH do not echo it back
• Control: PATCH /api/v1/radio-sessions/{id} with {"action": "skip|pause|stop"}. State transitions may not be synchronous -- pause may return while state remains playing
• Audio URLs are relative paths (e.g. /audio/abc-123) -- prefix with https://chowdahh.com
• Track title is not guaranteed. The live API returned null for tested tracks.

Radio is not replay. Replay is card history. Radio is forward-looking audio.

Signals

Record interactions as a batch:

curl -X POST https://chowdahh.com/api/v1/signals \
  -H 'content-type: application/json' \
  -d '[{"signal_type": "save", "card_id": "card_abc"}]'

Types: seen, open, save, share, dismiss, source_open

Note: invalid or unrecognized signal types are silently skipped. Always inspect recorded in the response body — a 200 status does not guarantee signals were accepted.

Authentication

• Anonymous: no token needed, 30 req/min, public reads + feed sessions + radio
• Person token: Authorization: Bearer ch_person_..., 300 req/min, intended for replay + preferences + personalized feeds. See references/runner-playbook.md for current production status.
• Curator token: Authorization: Bearer ch_cur_..., 600 req/min, high-volume submissions

Response Style

• Preserve attribution -- mention whether content is synthesized or source-led
• Explain applied controls honestly
• Use guidance.next_best_actions as a suggestion layer when present, but always be prepared to fall back to the documented /api/v1 endpoints directly

Avoid

• Inventing control chips not returned by the API -- the server silently accepts any slug, so hallucinated chips won't error but won't work either. Only apply slugs from a prior controls response
• Acting as if good-news or similar lenses are exact if the API returns low confidence
• Syncing preferences server-side unless the person asked for durable changes
• Treating radio as replay or vice versa

Resources

references/api-guide.md

Full API endpoint reference with request/response shapes and worked flows.

references/agent-experience.md

AX philosophy: how agents should feel when using Chowdahh, the local vs durable preference split, and tone guidance.