List source items
GET
https://dash.alethman.com/api/v1/sources/itemsWhat the workspace’s own feeds carried, newest first, each item read for sectors and states like any article.
Request
Section titled “Request”| Parameter | In | Type | Default | Values | What it does |
|---|---|---|---|---|---|
source |
query | string (uuid) | Only this source’s items. A source id from GET /sources. | ||
sector |
query | string | a sector key | Only this sector. It must be one the workspace follows; another sector returns an empty list, not an error. | |
state |
query | string | a state slug | Only this state or union territory. | |
since |
query | string (time) | Only items published after this time, as ISO 8601, e.g. 2026-11-21T00:00:00Z. |
||
q |
query | string | up to 120 characters | Words to find in the item’s title. | |
limit |
query | integer | 50 |
1 to 200 | How many items to return, 1 to 200. |
Example
Section titled “Example”curl "https://dash.alethman.com/api/v1/sources/items?since=2026-11-20T00:00:00Z&limit=20" \ -H "Authorization: Bearer $ALETHMAN_KEY"import osimport requests
r = requests.get( "https://dash.alethman.com/api/v1/sources/items", headers={"Authorization": f"Bearer {os.environ['ALETHMAN_KEY']}"}, params={"since": "2026-11-20T00:00:00Z", "limit": 20}, timeout=30,)r.raise_for_status()print(r.json())const url = new URL("https://dash.alethman.com/api/v1/sources/items");url.search = new URLSearchParams({ since: "2026-11-20T00:00:00Z", limit: "20" });
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.ALETHMAN_KEY}`, },});if (!res.ok) throw new Error((await res.json()).error.message);console.log(await res.json());Response
Section titled “Response”200 OK, application/json, with the rate-limit headers. A real response, shortened: long lists are cut to a few items.
{ "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", "summary": null, "published_at": "2026-11-20T14:36:08.151Z", "fetched_at": "2026-11-20T14:36:08.257Z", "sectors": [ "politics_governance" ], "states": [] }, { "id": 30027, "source": { "id": "34c8efbf-5e0c-4ace-bfeb-816f16bf59df", "title": "PRESS RELEASES FROM RBI" }, "title": "RBI to conduct 4-day Variable Rate Repo (VRR) auction under LAF on November 23, 2026", "url": "https://www.rbi.org.in/scripts/BS_PressReleaseDisplay.aspx?prid=64016", "summary": "On a review of current and evolving liquidity conditions in the near term, it has been decided to conduct a Variable Rate Repo (VRR) auction on Monday, November 23, 2026, as under: Sl. No. Notified Amount (₹ crore) Tenor (day) Window Timing Date of Reversal 1 50,000 4 9:30 AM to 10:00 AM November 27, 2026 (Friday) 2. The operational guidelines for the auction will be same as given in Reserve Bank’s Press Release 2021-2022/1572 dated January 20, 2022 . Ajit Prasad Deputy General Manager (Communications) Press Release: 2026-2027/1538", "published_at": "2026-11-20T14:15:10.339Z", "fetched_at": "2026-11-20T14:15:10.342Z", "sectors": [ "banking_finance_markets" ], "states": [] } ]}Fields
Section titled “Fields”| Field | Type | Values | What it is |
|---|---|---|---|
data |
array of objects | Items, newest first. | |
data[].id |
integer | The item’s id. | |
data[].source |
object | The feed it came from. | |
data[].source.id |
string (uuid) | The source’s id. | |
data[].source.title |
string | The source’s title. | |
data[].title |
string | The item’s title. | |
data[].url |
string (url) | The item’s address. | |
data[].summary |
string or null | The feed’s summary of the item, or null. | |
data[].published_at |
string (time) or null | When the feed says it was published. | |
data[].fetched_at |
string (time) | When Alethman read it. | |
data[].sectors |
array of strings | a sector key | Sectors the item was read as touching. |
data[].states |
array of strings | a state slug | States it is about. |
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 |
A parameter is out of range, not an allowed value, too long, or not an ISO 8601 time (for cursor: not one the API gave). The message names the parameter and what it accepts. |
| 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. |
| 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”- Items are read for sectors and states like any article, so
sectorandstatework here too. published_atis what the feed says and can be null;fetched_atis always set.
From an AI assistant
Section titled “From an AI assistant”The MCP tool list_source_items runs this endpoint’s code and returns the same JSON. Its default limit differs: The REST default is 50.