Skip to content

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.

  1. 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 201 with the new source. Alethman reads the feed once while you wait, so items already 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
    }
    }
  2. Check it is polling. GET /sources lists every feed with last_polled_at, last_ok_at and last_error. Feeds are read every 20 minutes. A feed that stops answering keeps its items, shows the reason in last_error, is tried less often (40 minutes, 80, up to once a day), and turns status failing after three failures in a row.

  3. Read the items. GET /sources/items returns items from all your feeds, newest first. Narrow with source, sector, state, q or since:

    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": []
    }
    ]
    }

/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 os
import 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)

Each feed is read every 20 minutes, so polling the API every 10 to 20 minutes misses nothing.

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.

Terminal window
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.