Quickstart
This walk-through takes you from no key to reading a story in full. Every response below is real, shortened where a list runs long.
You need a seat in an Alethman workspace as an owner or admin (only they can make keys), and a terminal. The examples use curl; every step has Python and JavaScript too.
-
Make a key
Section titled “Make a key”In the dashboard, open Settings › API keys and fill in Make a key:
- Name: what will use it, e.g. Risk desk ingest. It shows in the key list and in the workspace’s audit log.
- Scopes: leave the four read scopes ticked.
sources:writeis only for programs that add or remove feeds. - Expires: 90 days is the default; 30 days, a year or never are the other choices.
The key is shown once. Copy it and keep it in your secret store, then put it in your shell for this walk-through:
Terminal window export ALETHMAN_KEY="alm_live_…" -
Check the key
Section titled “Check the key”GET /workspaceanswers for any valid key and tells you what the workspace follows, which is what every other endpoint reads through.Terminal window curl https://dash.alethman.com/api/v1/workspace \-H "Authorization: Bearer $ALETHMAN_KEY"import osimport requestsAPI = "https://dash.alethman.com/api/v1"s = requests.Session()s.headers["Authorization"] = f"Bearer {os.environ['ALETHMAN_KEY']}"r = s.get(f"{API}/workspace", timeout=30)r.raise_for_status()print(r.json()["scope"])const API = "https://dash.alethman.com/api/v1";const headers = { Authorization: `Bearer ${process.env.ALETHMAN_KEY}` };const res = await fetch(`${API}/workspace`, { headers });if (!res.ok) throw new Error((await res.json()).error.message);console.log((await res.json()).scope);200 OK {"workspace": {"name": "Risk desk","slug": "risk-desk"},"scope": {"sectors": ["energy_power","politics_governance","public_order_unrest"],"states": [],"all_india": true,"national": true},"coverage": ["signals","live","stories","outlooks","forecasts","coordination"],"reports": {"frequency": "weekly","depth": "dossier","organise": "sector","sections": ["judgements","outlooks","stories","states","forecasts","coordination","sources"],"screenshots": false,"next_at": "2026-11-23T03:30:00.000Z"},"alerts": {"threshold": 40,"kinds": ["threshold","rising","coordination","forecast","report","source"]},"key": {"name": "Analyst notebook","scopes": ["signals:read","intel:read","reports:read","sources:read"]}}scope.sectorsandscope.statesbound every list you will read.key.scopessays what this key may call. A401here means the key was mistyped, revoked or expired (Authentication). -
Find what is moving
Section titled “Find what is moving”GET /storiesgroups articles into events. Order by risk to see the most disruptive first;independent_outletstells you how widely each is carried.Terminal window curl "https://dash.alethman.com/api/v1/stories?order=risk&hours=48&limit=5" \-H "Authorization: Bearer $ALETHMAN_KEY"r = s.get(f"{API}/stories", params={"order": "risk", "hours": 48, "limit": 5}, timeout=30)r.raise_for_status()for st in r.json()["data"]:print(st["id"], st["risk_level"], st["independent_outlets"], st["label"])const r = await fetch(`${API}/stories?order=risk&hours=48&limit=5`, { headers });for (const st of (await r.json()).data) console.log(st.id, st.risk_level, st.independent_outlets, st.label);200 OK (two of five) {"data": [{"id": 301791,"label": "Manipur Spurious Liquor Tragedy: Death Toll Rises To 11, Over 180 Hospitalised","independent_outlets": 24,"articles": 41,"trajectory": "steady","first_seen": "2026-11-19T13:45:01.000Z","last_seen": "2026-11-21T04:27:58.000Z","sectors": ["public_order_unrest","agriculture_food"],"states": ["manipur"],"place": "Chandel","risk_score": 72,"risk_level": "high","reading": "Suspected methanol-laced local liquor in Chandel district, Manipur, has killed at least 11 to 15 people and hospitalised more than 150.","event_type": "disaster_accident"},{"id": 297641,"label": "EPFO approves systematic PF withdrawal plan","independent_outlets": 35,"articles": 89,"trajectory": "steady","first_seen": "2026-11-18T22:24:07.000Z","last_seen": "2026-11-21T03:51:15.000Z","sectors": ["banking_finance_markets","politics_governance"],"states": ["delhi"],"place": "Delhi","risk_score": 12,"risk_level": "low","reading": "The EPFO board approved reforms easing PF withdrawals, including a systematic withdrawal plan, lower minimum balance and limited alternative fund investment.","event_type": "policy_decision"}]} -
Read one story in full
Section titled “Read one story in full”Take an
idfrom the list.GET /stories/{id}gives the reading, a summary, every article, the parties the reporting names and how coverage divides.Terminal window curl https://dash.alethman.com/api/v1/stories/297641 \-H "Authorization: Bearer $ALETHMAN_KEY"story = s.get(f"{API}/stories/297641", timeout=30).json()print(story["tag"]["reading"])print(story["summary"])const story = await (await fetch(`${API}/stories/297641`, { headers })).json();console.log(story.tag.reading, story.summary);200 OK (shortened) {"id": 297641,"requested_id": 297641,"label": "EPFO approves systematic PF withdrawal plan","independent_outlets": 35,"articles_count": 89,"trajectory": "steady","tag": {"sectors": ["banking_finance_markets","politics_governance"],"event_type": "policy_decision","risk_level": "low","reading": "The EPFO board approved reforms easing PF withdrawals, including a systematic withdrawal plan, lower minimum balance and limited alternative fund investment."},"summary": "The EPFO's Central Board of Trustees met in New Delhi on 19 November 2026 and approved a Systematic Withdrawal Plan letting retiring members draw their provident fund savings in monthly, quarterly or annual instalments while the remainder keeps earning EPF interest. The board also cut the minimum balance to be retained during partial withdrawals from 25% to 10% and restored a two-month wait for final settlement after job loss, down from 12 months; it did not raise the EPS pension. These changes take effect only after formal notification. Nobody disputes the decisions. Where outlets differ is in emphasis: The Times of India, DNA India, Prameya News and The Economic Times present the plan as a clear gain in retirement income and security, while Hindustan Times, India Today, Business Today and others focus on the larger share of savings members can now withdraw. No report so far says when the rules will be notified, and none carries criticism of the plan.","…": "places, articles, bloc_finding, by_country, forecasts"}Every field is documented on Get a story.
-
Page through the articles
Section titled “Page through the articles”GET /signalsis every article in scope, newest first. Lists that page returnnext_cursor; pass it back ascursoruntil it is null.Terminal window curl "https://dash.alethman.com/api/v1/signals?limit=4" \-H "Authorization: Bearer $ALETHMAN_KEY"# then, with the next_cursor it returned:curl "https://dash.alethman.com/api/v1/signals?limit=4&cursor=MjAyNi0xMS0yMVQwNDo0NjoyNi4wMDBafDEzODYyNjk0OA" \-H "Authorization: Bearer $ALETHMAN_KEY"params = {"limit": 200}while True:page = s.get(f"{API}/signals", params=params, timeout=30).json()for a in page["data"]:print(a["published_at"], a["outlet"]["name"], a["title"])if not page["data"] or not page["next_cursor"]:breakparams["cursor"] = page["next_cursor"]let cursor = null;do {const url = new URL(`${API}/signals`);url.searchParams.set("limit", "200");if (cursor) url.searchParams.set("cursor", cursor);const page = await (await fetch(url, { headers })).json();for (const a of page.data) console.log(a.published_at, a.outlet.name, a.title);cursor = page.data.length ? page.next_cursor : null;} while (cursor);200 OK (one of four) {"data": [{"id": 138695177,"title": "Jammu Kashmir High Court Quashes Withdrawal of NOC for Four Tourist Huts in Pahalgam","url": "https://kashmirlife.net/jammu-kashmir-high-court-quashes-withdrawal-of-noc-for-four-tourist-huts-in-pahalgam-462123/","published_at": "2026-11-21T05:01:37.000Z","language": null,"outlet": {"id": "kashmir-life","name": "Kashmir Life"},"sectors": ["politics_governance"],"states": [],"story": null}],"next_cursor": "MjAyNi0xMS0yMVQwNDo0NjoyNi4wMDBafDEzODYyNjk0OA"}
Where next
Section titled “Where next”- Hand it to an assistant. The same key works in Claude, Cursor and other MCP clients: Connect a client.
- Build something whole. Today’s stories for a state, Watch a sector, Export forecasts.
- Handle the edges. Errors, Rate limits, Pagination.