Skip to content

Add a source

POSThttps://dash.alethman.com/api/v1/sources
MCP tool
None (writes are REST only)

Follow 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.

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.
Request body
{
"url": "https://www.rbi.org.in/pressreleases_rss.xml"
}
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"}'

201 Created, application/json, with the rate-limit headers. A real response, shortened: long lists are cut to a few items.

201 Created
{
"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"
}
}
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.

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.
  • 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.

Not offered over MCP. Every MCP tool is read-only, so an assistant can read your sources but not change them.