Add a source
https://dash.alethman.com/api/v1/sourcesFollow a new feed. Alethman reads the address before saving anything, so a source that answers 201 has already been polled once and holds what that read stored. A site’s home page works when it names its feed. A workspace follows up to 50 sources of its own, and up to 20 can be added a minute. Every add is written to the workspace’s audit log under the key’s name.
Request
Section titled “Request”This endpoint takes no parameters.
JSON, with Content-Type: application/json, at most 4,000 characters.
| Field | Type | Values | What it is |
|---|---|---|---|
url |
string (url) | up to 2000 characters | The feed’s address, or a page that names its feed. http or https, at most 2,000 characters. |
{ "url": "https://www.rbi.org.in/pressreleases_rss.xml"}Example
Section titled “Example”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"}'import osimport requests
r = requests.post( "https://dash.alethman.com/api/v1/sources", headers={"Authorization": f"Bearer {os.environ['ALETHMAN_KEY']}"}, json={"url": "https://www.rbi.org.in/pressreleases_rss.xml"}, timeout=30,)r.raise_for_status()print(r.json())const url = "https://dash.alethman.com/api/v1/sources";
const res = await fetch(url, { method: "POST", headers: { Authorization: `Bearer ${process.env.ALETHMAN_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({"url":"https://www.rbi.org.in/pressreleases_rss.xml"}),});if (!res.ok) throw new Error((await res.json()).error.message);console.log(await res.json());Response
Section titled “Response”201 Created, application/json, with the rate-limit headers. A real response, shortened: long lists are cut to a few items.
{ "data": { "id": "34c8efbf-5e0c-4ace-bfeb-816f16bf59df", "url": "https://www.rbi.org.in/pressreleases_rss.xml", "site_url": "http://www.rbi.org.in/", "title": "PRESS RELEASES FROM RBI", "kind": "rss", "status": "active", "last_polled_at": "2026-11-21T04:50:25.731Z", "last_ok_at": "2026-11-21T04:50:25.731Z", "last_error": null, "items": 41, "items_7d": 41, "created_at": "2026-11-21T04:50:25.731Z" }}Fields
Section titled “Fields”| Field | Type | Values | What it is |
|---|---|---|---|
data |
object | A feed the workspace follows, on top of Alethman’s own coverage. | |
data.id |
string (uuid) | The source’s id. | |
data.url |
string (url) | The feed’s address. | |
data.site_url |
string or null | The site the feed belongs to. | |
data.title |
string | The feed’s title. | |
data.kind |
string | rss, atom |
rss or atom. |
data.status |
string | active, paused, failing |
active: polled about every 20 minutes. paused: an owner or admin paused it. failing: recent polls failed; see last_error. |
data.last_polled_at |
string (time) or null | The last poll, successful or not. | |
data.last_ok_at |
string (time) or null | The last successful poll. | |
data.last_error |
string or null | Why the last poll failed, or null. | |
data.items |
integer | Items stored from this feed. | |
data.items_7d |
integer | Items stored in the last 7 days. | |
data.created_at |
string (time) | When the workspace started following it. |
Errors
Section titled “Errors”Every error has the body {"error": {"code": …, "message": …}}; branch on code. See Errors for how to handle each.
| Status | Code | When |
|---|---|---|
| 400 | bad_request |
No Content-Type: application/json (“Send a JSON body with Content-Type: application/json.”), a body over 4,000 characters (“The body is too large.”), invalid JSON (“The body is not valid JSON.”), a url that is missing, not http(s) or over 2,000 characters (“url must be an http(s) address.”), or more than 20 adds in a minute (“Twenty new sources a minute is the limit.”). |
| 401 | unauthenticated |
No Authorization header, or one that is not Bearer <key>. Answered with WWW-Authenticate: Bearer realm="alethman". |
| 401 | invalid_key |
The key is unknown, revoked or expired, its workspace is suspended, or the person who made it is no longer an active owner or admin. Answered with WWW-Authenticate: Bearer realm="alethman", error="invalid_token". |
| 403 | insufficient_scope |
The key is valid but does not carry the scope this endpoint needs. The message names the scope. |
| 422 | unprocessable |
The address could not be followed. The message says why: “That page does not name a feed. Paste the feed’s own address (it usually ends in /feed, /rss or .xml).”, “The feed was read but has no items in it yet.”, “The address could not be read.”, “That feed is already one of your sources.”, or “A workspace can follow 50 sources of its own. Remove one first.” |
| 409 | workspace_not_ready |
The workspace has not been set up yet. An owner or admin finishes the setup walkthrough in the dashboard first. |
| 429 | rate_limited |
More than 120 requests in a minute on one key (wait for Retry-After seconds), or more than 30 failed key attempts in a minute from one address (wait 60 seconds). |
| 500 | internal |
Something failed on Alethman’s side. Retry with backoff; if it persists, write to Alethman with the time of the request. |
Good to know
Section titled “Good to know”- A site’s home page is accepted when it names its feed; the feed’s own address is stored.
- The feed is read before anything is saved, so a 201 means it worked, and a 422 saved nothing.
- The 20-a-minute limit answers 400, not 429, and does not touch the key’s 120 a minute.
- Every add is written to the workspace’s audit log with the key’s name.
From an AI assistant
Section titled “From an AI assistant”Not offered over MCP. Every MCP tool is read-only, so an assistant can read your sources but not change them.