Follow your own feed
You will build: a feed of your own (a regulator’s press releases, a ministry’s notices, a trade body’s news) followed by your workspace and read back through the API, each item tagged with sectors and states.
You need: a key with sources:write to add or remove a feed, and sources:read to read. sources:write is unticked by default when a key is made; tick it for this key alone.
-
Add the feed. Send its address, or a page that names its feed in a
<link rel="alternate">; Alethman finds the feed itself.Terminal window curl -X POST "https://dash.alethman.com/api/v1/sources" \-H "Authorization: Bearer $ALETHMAN_KEY" \-H "Content-Type: application/json" \-d '{"url": "https://www.rbi.org.in/pressreleases_rss.xml"}'The answer is
201with the new source. Alethman reads the feed once while you wait, soitemsalready counts what it found:{"data": {"id": "34c8efbf-5e0c-4ace-bfeb-816f16bf59df","url": "https://www.rbi.org.in/pressreleases_rss.xml","title": "PRESS RELEASES FROM RBI","kind": "rss","status": "active","last_error": null,"items": 41}} -
Check it is polling.
GET /sourceslists every feed withlast_polled_at,last_ok_atandlast_error. Feeds are read every 20 minutes. A feed that stops answering keeps its items, shows the reason inlast_error, is tried less often (40 minutes, 80, up to once a day), and turnsstatusfailingafter three failures in a row. -
Read the items.
GET /sources/itemsreturns items from all your feeds, newest first. Narrow withsource,sector,state,qorsince:Terminal window curl "https://dash.alethman.com/api/v1/sources/items?source=34c8efbf-5e0c-4ace-bfeb-816f16bf59df&limit=5" \-H "Authorization: Bearer $ALETHMAN_KEY"{"data": [{"id": 30037,"source": { "id": "34c8efbf-5e0c-4ace-bfeb-816f16bf59df", "title": "PRESS RELEASES FROM RBI" },"title": "Conversion/Switch of State Government Securities","url": "https://www.rbi.org.in/scripts/BS_PressReleaseDisplay.aspx?prid=64017","published_at": "2026-11-20T14:36:08.151Z","sectors": ["politics_governance"],"states": []}]}
Polling for new items
Section titled “Polling for new items”/sources/items has no cursor. Poll with since set to the newest published_at you hold, and keep item ids to drop any you have already seen:
import osimport time
import requests
API = "https://dash.alethman.com/api/v1"s = requests.Session()s.headers["Authorization"] = f"Bearer {os.environ['ALETHMAN_KEY']}"
since, seen = "2026-11-21T00:00:00Z", set()while True: items = s.get(f"{API}/sources/items", params={"since": since, "limit": 200}, timeout=30).json()["data"] for it in reversed(items): # oldest first if it["id"] not in seen: seen.add(it["id"]) print(it["published_at"][:16], it["source"]["title"], "·", it["title"]) if items: since = items[0]["published_at"] time.sleep(600)const API = "https://dash.alethman.com/api/v1";const headers = { Authorization: `Bearer ${process.env.ALETHMAN_KEY}` };let since = "2026-11-21T00:00:00Z";const seen = new Set();
for (;;) { const res = await fetch(`${API}/sources/items?${new URLSearchParams({ since, limit: "200" })}`, { headers }); const { data } = await res.json(); for (const it of [...data].reverse()) { if (seen.has(it.id)) continue; seen.add(it.id); console.log(it.published_at.slice(0, 16), it.source.title, "·", it.title); } if (data.length) since = data[0].published_at; await new Promise((r) => setTimeout(r, 600_000));}Each feed is read every 20 minutes, so polling the API every 10 to 20 minutes misses nothing.
Limits and refusals
Section titled “Limits and refusals”| What | Limit | Answer |
|---|---|---|
| Feeds per workspace | 50 | 422, “A workspace can follow 50 sources of its own. Remove one first.” |
| New feeds | 20 a minute per workspace | 400, “Twenty new sources a minute is the limit.” |
| A feed you already follow | 422, “That feed is already one of your sources.” |
|
| An address that is not a feed and names none | 422, with the reason |
|
url not http(s), or over 2,000 characters |
400 |
The complete list is on Add a source.
Removing a feed
Section titled “Removing a feed”curl -X DELETE "https://dash.alethman.com/api/v1/sources/34c8efbf-5e0c-4ace-bfeb-816f16bf59df" \ -H "Authorization: Bearer $ALETHMAN_KEY"Its stored items go with it. Adding and removing feeds are written to the workspace’s audit log under the key’s name.