# Alethman API and MCP > Read your workspace's narrative intelligence from your own tools and AI assistants. The API and the MCP server, documented end to end. Source: https://docs.alethman.com/ Alethman reads India’s news as it is published, groups it into stories, and reads each for what it means for the sectors and states you follow. This is how you take that into your own systems: a REST API for programs, and an MCP server for AI assistants. Both read through your workspace, under one key. REST API ### For your programs Thirteen endpoints, plain JSON, cursor pagination, one error shape. Mirror articles into a warehouse, put sector readings on a wall screen, file reports where your team reads them. curl "https://dash.alethman.com/api/v1/stories?order=risk" \\ -H "Authorization: Bearer $ALETHMAN\_KEY" [Make your first request →](https://docs.alethman.com/quickstart/) MCP server ### For your AI assistant Eleven read-only tools for Claude, Cursor and any client that speaks the Model Context Protocol. Ask what moved in your sectors this week and get an answer from your own workspace. claude mcp add --transport http alethman \\ https://dash.alethman.com/api/mcp \\ --header "Authorization: Bearer $ALETHMAN\_KEY" [Connect a client →](https://docs.alethman.com/mcp/connect/) **13**REST endpoints **11**MCP tools **120**requests a minute per key **v1**stable; additions only ## What you can read Every endpoint returns what the dashboard shows, read through the same workspace scope: the sectors and states your workspace follows. - [Articles](https://docs.alethman.com/reference/signals/)Every article in scope, with its outlet, sectors, states and story. - [Stories](https://docs.alethman.com/reference/stories/)Articles about one event, grouped, with independent outlets and risk. - [One story in full](https://docs.alethman.com/reference/story/)Summary, places, articles, who the reporting names, coverage by country. - [Sector outlooks](https://docs.alethman.com/reference/outlooks/)Each sector’s reading: risk, direction, verdict and the stories behind it. - [Forecasts](https://docs.alethman.com/reference/forecasts/)Dated yes-or-no questions with probabilities and a public track record. - [Coordination findings](https://docs.alethman.com/reference/coordination/)Stories the reporting links into one pattern, graded by evidence. - [Reports](https://docs.alethman.com/reference/reports/)Your compiled reports, as JSON to compute on or Markdown to read. - [Your sources](https://docs.alethman.com/reference/sources/)The feeds your workspace follows, their health, and what they carried. - [Your workspace](https://docs.alethman.com/reference/workspace/)What the key’s workspace follows and which scopes the key carries. ## Start here 1. **[Quickstart](https://docs.alethman.com/quickstart/)**: make a key, call the API, read a story, in five minutes. 2. **[Authentication and keys](https://docs.alethman.com/authentication/)**: who can make keys, scopes, expiry, rotation. 3. **[Countries and scopes](https://docs.alethman.com/scopes/)**: what a workspace follows, and the sector and state keys every filter takes. 4. **[Errors](https://docs.alethman.com/errors/)** and **[Rate limits](https://docs.alethman.com/rate-limits/)**: what can go wrong and how to back off. 5. **[Guides](https://docs.alethman.com/guides/stories-for-a-state/)**: whole tasks, end to end, in curl, Python and JavaScript. The whole API is one [OpenAPI 3.1 document](https://docs.alethman.com/openapi.json), and these docs are available to language models as [llms.txt](https://docs.alethman.com/llms.txt) and [llms-full.txt](https://docs.alethman.com/llms-full.txt). --- # Quickstart > Make a key, check it, find the riskiest stories in your scope and read one in full, in about five minutes. Source: https://docs.alethman.com/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. 1. ### Make a key In the dashboard, open **[Settings › API keys](https://dash.alethman.com/settings/api)** 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:write` is 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: ```bash export ALETHMAN_KEY="alm_live_…" ``` > **Caution** > > A key reads everything your workspace can see. Keep it out of source control, browser code and screenshots. If one leaks, revoke it under Settings › API keys; requests with it fail at once. 2. ### Check the key `GET /workspace` answers for any valid key and tells you what the workspace follows, which is what every other endpoint reads through. **curl** ```bash curl https://dash.alethman.com/api/v1/workspace \ -H "Authorization: Bearer $ALETHMAN_KEY" ``` **Python** ```python import os import requests API = "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"]) ``` **JavaScript** ```js 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* ```json { "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.sectors` and `scope.states` bound every list you will read. `key.scopes` says what this key may call. A `401` here means the key was mistyped, revoked or expired ([Authentication](https://docs.alethman.com/authentication/#when-a-key-is-refused)). 3. ### Find what is moving `GET /stories` groups articles into events. Order by risk to see the most disruptive first; `independent_outlets` tells you how widely each is carried. **curl** ```bash curl "https://dash.alethman.com/api/v1/stories?order=risk&hours=48&limit=5" \ -H "Authorization: Bearer $ALETHMAN_KEY" ``` **Python** ```python 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"]) ``` **JavaScript** ```js 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)* ```json { "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" } ] } ``` 4. ### Read one story in full Take an `id` from the list. `GET /stories/{id}` gives the reading, a summary, every article, the parties the reporting names and how coverage divides. **curl** ```bash curl https://dash.alethman.com/api/v1/stories/297641 \ -H "Authorization: Bearer $ALETHMAN_KEY" ``` **Python** ```python story = s.get(f"{API}/stories/297641", timeout=30).json() print(story["tag"]["reading"]) print(story["summary"]) ``` **JavaScript** ```js const story = await (await fetch(`${API}/stories/297641`, { headers })).json(); console.log(story.tag.reading, story.summary); ``` *200 OK (shortened)* ```json { "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](https://docs.alethman.com/reference/story/). 5. ### Page through the articles `GET /signals` is every article in scope, newest first. Lists that page return `next_cursor`; pass it back as `cursor` until it is null. **curl** ```bash 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" ``` **Python** ```python 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"]: break params["cursor"] = page["next_cursor"] ``` **JavaScript** ```js 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)* ```json { "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 - **Hand it to an assistant.** The same key works in Claude, Cursor and other MCP clients: [Connect a client](https://docs.alethman.com/mcp/connect/). - **Build something whole.** [Today’s stories for a state](https://docs.alethman.com/guides/stories-for-a-state/), [Watch a sector](https://docs.alethman.com/guides/watch-a-sector/), [Export forecasts](https://docs.alethman.com/guides/export-forecasts/). - **Handle the edges.** [Errors](https://docs.alethman.com/errors/), [Rate limits](https://docs.alethman.com/rate-limits/), [Pagination](https://docs.alethman.com/pagination/). --- # Authentication and keys > Every request carries a workspace API key as a Bearer token. Who can make keys, what scopes do, expiry, rotation and why a key is refused. Source: https://docs.alethman.com/authentication/ Every request sends an API key in the `Authorization` header: ```http GET /api/v1/stories HTTP/1.1 Host: dash.alethman.com Authorization: Bearer alm_live_4Hc… ``` A key belongs to one workspace and reads only what that workspace follows. There are no user tokens, no OAuth flow and no request signing: the key is the whole credential, so treat it like a password. ## The key A key is `alm_live_` followed by 40 letters and digits. Alethman stores only a SHA-256 hash of it and its first 13 characters (so you can tell keys apart in the list), which is why it can be shown only once, when it is made. A lost key cannot be recovered; make a new one and revoke the old. ## Making a key Keys are made in the dashboard under **[Settings › API keys](https://dash.alethman.com/settings/api)**. Only a workspace **owner or admin** sees that page. | Choice | What to pick | | --- | --- | | Name | What will use it (*Risk desk ingest*, *Analyst notebook*). Up to 80 characters. It labels the key in the list and in the audit log. | | Scopes | Only what the program needs. The four read scopes are ticked by default; `sources:write` is not. | | Expires | In 30 days, in 90 days (the default), in a year, or never. | Limits that keep a stolen session from doing much: - A workspace holds at most **20 active keys**. Revoke one to make another. - A workspace can make at most **30 keys an hour**. - Making and revoking a key are written to the workspace’s **audit log** with who did it. ## Scopes A scope is a permission a key carries. An endpoint answers `403 insufficient_scope` to a key without its scope, and an MCP client sees only the tools the key’s scopes reach. `GET /workspace` needs no scope. | Scope | Lets the key | Endpoints | | --- | --- | --- | | `signals:read` | Read articles in the workspace's scope. | `GET /signals` | | `intel:read` | Read stories, sector outlooks, forecasts and coordination findings. | `GET /stories` `GET /stories/{id}` `GET /outlooks` `GET /forecasts` `GET /coordination` | | `reports:read` | Read the workspace's compiled reports, as JSON or Markdown. | `GET /reports` `GET /reports/{id}` | | `sources:read` | Read the feeds the workspace follows and what they carried. | `GET /sources` `GET /sources/items` | | `sources:write` | Add and remove the workspace's own feeds. | `POST /sources` `DELETE /sources/{id}` | > **Tip** > > Give a key only the scopes it needs. A dashboard that shows sector outlooks needs `intel:read` and nothing else; a key that only reads cannot change your sources. ## Expiry, rotation and revocation An expired or revoked key fails at once with `401 invalid_key`. To rotate without downtime: 1. Make the new key with the same scopes. 2. Deploy it alongside the old one and switch over. 3. Revoke the old key under Settings › API keys. The page lists when each key was last used, so you can confirm nothing still sends it. A key also stops working when **the person who made it** stops being an active owner or admin of the workspace, or when the workspace is suspended. Make long-lived integration keys from a seat that will stay. ## When a key is refused | Status | Code | Why | What to do | | --- | --- | --- | --- | | 401 | `unauthenticated` | No `Authorization` header, or not `Bearer `. | Send `Authorization: Bearer alm_live_…`. | | 401 | `invalid_key` | Unknown, revoked or expired key, a suspended workspace, or a maker who is no longer an owner or admin. | Check the key under Settings › API keys; make a new one. | | 403 | `insufficient_scope` | The key is valid but lacks the endpoint’s scope. The message names it. | Make a key with that scope. | | 409 | `workspace_not_ready` | The workspace has not finished its setup walkthrough. | An owner or admin finishes setup in the dashboard. | | 429 | `rate_limited` | 30 failed key attempts in a minute from one address. | Wait 60 seconds (`Retry-After: 60`) and fix the key. | A 401 carries a `WWW-Authenticate` header, as the HTTP standard asks. Neither 401 nor 403 carries rate-limit headers, because the request was never admitted. *A request with no key* ```json { "status": 401, "headers": { "content-type": "application/json", "cache-control": "no-store", "www-authenticate": "Bearer realm=\"alethman\"" }, "body": { "error": { "code": "unauthenticated", "message": "Send your key as: Authorization: Bearer alm_live_…" } } } ``` *A read-only key trying to add a source* ```json { "status": 403, "body": { "error": { "code": "insufficient_scope", "message": "This key does not carry the sources:write scope." } } } ``` ## Keeping a key safe - Keep keys in a secret manager or environment variables, never in source control. - Never put a key in code that runs in a browser. The API does not serve cross-origin browser requests for this reason; call it from your server. - One key per program, named for it, so revoking one breaks one thing. - If a key may have leaked, revoke it first and investigate after. --- # Countries and scopes > What a workspace follows bounds everything the API returns. The sector keys and state slugs every filter takes, national news, and which country the API reads. Source: https://docs.alethman.com/scopes/ Two different things are called *scope* in these docs. A **key’s scopes** are permissions: which endpoints it may call ([Authentication](https://docs.alethman.com/authentication/#scopes)). A **workspace’s scope** is coverage: which sectors and states its data is read for. This page is about the second. ## The workspace’s scope Every workspace follows a set of **sectors** and either **all of India** or a set of **states and union territories**, and may also follow **national news** (news that names no state). An owner or admin sets this in the dashboard’s setup walkthrough and can change it under Settings. Every endpoint reads through it: - **Articles** (`/signals`) are those read as touching a followed sector, in a followed state (or national, if followed). - **Stories** (`/stories`) are those whose sectors and states overlap the scope. A story outside it answers `404` on `/stories/{id}`, as if it did not exist. - **Outlooks** come one per followed sector. **Forecasts** are those in followed sectors. - **Coordination findings** are those whose stories touch the scope. - **Reports** and **sources** are the workspace’s own. `GET /workspace` returns the scope, so a program can read it instead of hard-coding it: ```json "scope": { "sectors": ["energy_power", "politics_governance", "public_order_unrest"], "states": [], "all_india": true, "national": true } ``` ## Filters narrow; they never widen `sector` and `state` filters work inside the scope. A sector or state the workspace does not follow returns an **empty list**, not an error and never another workspace’s data. A value that is not a sector key or state slug at all is a `400`. > **Note** > > When the scope changes in the dashboard, the API follows on the next request. There is nothing to refresh. ## Countries Alethman’s API reads **India**. Every sector, state, story and outlook it returns is read for Indian coverage, the same as the dashboard’s India view. There is no country parameter in version 1. When other countries come to the API, they will arrive as an addition (a new optional parameter), so code written today keeps working ([Versioning](https://docs.alethman.com/versioning/)). Foreign and national stories still appear when they are read as touching a followed sector in India: an article with an empty `states` list is national or foreign news, and appears only when the workspace follows national news. ## Sectors Nineteen sectors. Pass the key, not the name. | Key | Sector | | --- | --- | | `textiles_apparel` | Textiles and apparel | | `metals_mining` | Metals and mining | | `trade_imports_exports` | Trade, imports and exports | | `agriculture_food` | Agriculture and food | | `energy_power` | Energy and power | | `infrastructure_transport` | Infrastructure and transport | | `manufacturing_industry` | Manufacturing and industry | | `it_telecom_tech` | IT, telecom and technology | | `pharma_health` | Pharma and health | | `banking_finance_markets` | Banking, finance and markets | | `real_estate_construction` | Real estate and construction | | `public_order_unrest` | Public order and unrest | | `insurgency_terrorism` | Insurgency and terrorism | | `crime_law_enforcement` | Crime and law enforcement | | `defence_borders_foreign` | Defence, borders and foreign relations | | `politics_governance` | Politics and governance | | `environment_disaster` | Environment and disasters | | `labour_employment_education` | Labour, employment and education | | `media_information` | Media and the information space | ## States Twenty-eight states and eight union territories, as lowercase slugs. | Slug | State or union territory | | --- | --- | | `andhra-pradesh` | Andhra Pradesh | | `arunachal-pradesh` | Arunachal Pradesh | | `assam` | Assam | | `bihar` | Bihar | | `chhattisgarh` | Chhattisgarh | | `goa` | Goa | | `gujarat` | Gujarat | | `haryana` | Haryana | | `himachal-pradesh` | Himachal Pradesh | | `jharkhand` | Jharkhand | | `karnataka` | Karnataka | | `kerala` | Kerala | | `madhya-pradesh` | Madhya Pradesh | | `maharashtra` | Maharashtra | | `manipur` | Manipur | | `meghalaya` | Meghalaya | | `mizoram` | Mizoram | | `nagaland` | Nagaland | | `odisha` | Odisha | | `punjab` | Punjab | | `rajasthan` | Rajasthan | | `sikkim` | Sikkim | | `tamil-nadu` | Tamil Nadu | | `telangana` | Telangana | | `tripura` | Tripura | | `uttar-pradesh` | Uttar Pradesh | | `uttarakhand` | Uttarakhand | | `west-bengal` | West Bengal | | `andaman-and-nicobar-islands` | Andaman and Nicobar Islands | | `chandigarh` | Chandigarh | | `dadra-and-nagar-haveli-and-daman-and-diu` | Dadra and Nagar Haveli and Daman and Diu | | `delhi` | Delhi | | `jammu-and-kashmir` | Jammu and Kashmir | | `ladakh` | Ladakh | | `lakshadweep` | Lakshadweep | | `puducherry` | Puducherry | --- # Pagination > How each list endpoint pages: cursors for articles, before for reports, windows and limits for the rest, and how to keep a mirror in sync. Source: https://docs.alethman.com/pagination/ Lists come back newest first. How you get the next page depends on the list: | Endpoint | How it pages | Page size | | --- | --- | --- | | [`GET /signals`](https://docs.alethman.com/reference/signals/) | `cursor`, from the `next_cursor` of the page before | `limit` 1 to 200, default 50 | | [`GET /reports`](https://docs.alethman.com/reference/reports/) | `before`, the `created_at` of the oldest report you have | `limit` 1 to 100, default 20 | | [`GET /sources/items`](https://docs.alethman.com/reference/source-items/) | `since`, a time; no cursor | `limit` 1 to 200, default 50 | | [`GET /stories`](https://docs.alethman.com/reference/stories/) | does not page; narrow with `hours`, `sector`, `state` | `limit` 1 to 100, default 20 | | [`GET /forecasts`](https://docs.alethman.com/reference/forecasts/) | does not page; filter with `status`, `sector` | `limit` 1 to 200, default 100 | | [`GET /coordination`](https://docs.alethman.com/reference/coordination/) | does not page | `limit` 1 to 60, default 30 | | [`GET /outlooks`](https://docs.alethman.com/reference/outlooks/), [`GET /sources`](https://docs.alethman.com/reference/sources/) | one short list, whole | all of it | ## Cursors `GET /signals` returns a `next_cursor` beside `data`. Pass it back unchanged as `cursor` with the same filters to get the next page: ```json { "data": [ … 50 articles … ], "next_cursor": "MjAyNi0xMS0yMVQwNDo0NjoyNi4wMDBafDEzODYyNjk0OA" } ``` - `next_cursor` is **null when a page comes back short** (fewer rows than `limit`): there is nothing more. - A page that comes back **exactly full** always carries a cursor, even if nothing follows; the next page is then empty. Stop on an empty `data` as well as on a null cursor. - A cursor is **opaque**. Do not build or edit one; a cursor the API did not give answers `400 bad_request` (“cursor is not valid. Use the next\_cursor from a previous page.”). - A cursor points at a place in time, not a page number, so articles published while you page never shift what you see or make you read one twice. Cursors do not expire. - Keep the other parameters the same from page to page. A cursor with different filters still works, but walks the new filters from that point. **Python** ```python import os import requests API = "https://dash.alethman.com/api/v1" s = requests.Session() s.headers["Authorization"] = f"Bearer {os.environ['ALETHMAN_KEY']}" def every_article(**filters): params = {"limit": 200, **filters} while True: r = s.get(f"{API}/signals", params=params, timeout=30) r.raise_for_status() page = r.json() yield from page["data"] if not page["data"] or not page["next_cursor"]: return params["cursor"] = page["next_cursor"] for a in every_article(sector="energy_power", since="2026-11-14T00:00:00Z"): print(a["id"], a["title"]) ``` **JavaScript** ```js const API = "https://dash.alethman.com/api/v1"; const headers = { Authorization: `Bearer ${process.env.ALETHMAN_KEY}` }; async function* everyArticle(filters = {}) { let cursor = null; do { const url = new URL(`${API}/signals`); url.search = new URLSearchParams({ limit: "200", ...filters, ...(cursor ? { cursor } : {}) }); const res = await fetch(url, { headers }); if (!res.ok) throw new Error((await res.json()).error.message); const page = await res.json(); yield* page.data; cursor = page.data.length ? page.next_cursor : null; } while (cursor); } for await (const a of everyArticle({ sector: "energy_power", since: "2026-11-14T00:00:00Z" })) console.log(a.id, a.title); ``` ## Keeping a mirror in sync To keep your own copy of the articles: 1. **Backfill** once: page with `cursor` until it runs out (add `since` to bound how far back). 2. **Poll** every few minutes with `since` set to the newest `published_at` you hold. New articles arrive newest first; page with `cursor` if more than one page came in. 3. **Upsert by `id`**. An article’s `story` can change after you first see it (it joins a story, or two stories merge), so update rows you already hold rather than skipping them. > **Tip** > > Polling every 5 to 10 minutes is plenty: articles are read and grouped in cycles, so faster polling returns the same rows. A full backfill of a month at 200 a page fits well inside the 120-a-minute limit. ## Times Every time is ISO 8601 in UTC (`2026-11-21T04:46:26.000Z`). Parameters that take a time (`since`, `before`) accept any ISO 8601 form, with or without milliseconds or an offset: `2026-11-21T10:00:00+05:30` is the same instant as `2026-11-21T04:30:00Z`. --- # Errors > One error shape for every failure, a stable code to branch on, every status the API can answer, and which errors to retry. Source: https://docs.alethman.com/errors/ Every error is JSON with the same shape, whatever went wrong: ```json { "error": { "code": "bad_request", "message": "limit must be a whole number from 1 to 200." } } ``` - **`code`** is stable and machine-readable. Branch on it. - **`message`** is one sentence for a person: what was wrong and what to do. It may be reworded; never parse it. Errors are never cached (`Cache-Control: no-store`). Status codes follow HTTP: 4xx means fix the request, 5xx means retry. ## Every error | Status | Code | When | | --- | --- | --- | | 400 | `bad_request` | A parameter is out of range or not one of the allowed values, a cursor is not one the API gave, or a POST body is not valid. The message names the parameter and what it accepts. | | 401 | `unauthenticated` | No Authorization header, or one that is not Bearer . 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. | | 404 | `not_found` | No story, report or source with that id in this workspace, or a story outside the workspace's sectors and states. | | 409 | `workspace_not_ready` | The workspace has not been set up yet. An owner or admin finishes the setup walkthrough in the dashboard first. | | 422 | `unprocessable` | POST /sources could not follow the address: it is not a feed, could not be read, is already a source, or the workspace already follows 50 sources of its own. | | 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 request meets the checks in this order: the key (401, or the bad-key limit’s 429 once an address has sent 30 bad keys in a minute; a valid key is never refused by it), then the scope (403), then the key’s rate (429), then the workspace (409), then the request itself (400, 404, 422). So a 403 or a 401 never counts against the 120 a minute, and only responses from the rate check on carry the rate-limit headers. ## What each looks like **400** *GET /api/v1/signals?limit=0* ```json { "request": "GET /api/v1/signals?limit=0", "status": 400, "headers": { "content-type": "application/json", "cache-control": "no-store", "x-ratelimit-limit": "120", "x-ratelimit-remaining": "107", "x-ratelimit-reset": "1795238160" }, "body": { "error": { "code": "bad_request", "message": "limit must be a whole number from 1 to 200." } } } ``` **401** *GET /api/v1/signals (no key)* ```json { "request": "GET /api/v1/signals", "status": 401, "headers": { "content-type": "application/json", "cache-control": "no-store", "www-authenticate": "Bearer realm=\"alethman\"" }, "body": { "error": { "code": "unauthenticated", "message": "Send your key as: Authorization: Bearer alm_live_…" } } } ``` **403** *POST /api/v1/sources (read-only key)* ```json { "request": "POST /api/v1/sources", "status": 403, "headers": { "content-type": "application/json", "cache-control": "no-store" }, "body": { "error": { "code": "insufficient_scope", "message": "This key does not carry the sources:write scope." } } } ``` **404** *GET /api/v1/stories/1* ```json { "request": "GET /api/v1/stories/1", "status": 404, "headers": { "content-type": "application/json", "cache-control": "no-store", "x-ratelimit-limit": "120", "x-ratelimit-remaining": "106", "x-ratelimit-reset": "1795238160" }, "body": { "error": { "code": "not_found", "message": "No story with that id." } } } ``` **429** *The 121st request in a minute* ```json { "status": 429, "headers": { "retry-after": "23", "x-ratelimit-limit": "120", "x-ratelimit-remaining": "0", "x-ratelimit-reset": "1795238160" }, "body": { "error": { "code": "rate_limited", "message": "120 requests a minute per key. Wait for the window to reset." } } } ``` ## The 400 messages A `400 bad_request` names the parameter and what it accepts, so the message is the fix: | Message | Cause | | --- | --- | | `limit must be a whole number from 1 to 200.` | A number out of range or not a whole number. The range is the parameter’s. | | `order must be one of: voices, risk, recent.` | A value that is not one of the allowed ones. | | `since must be an ISO 8601 time, for example 2026-09-28T09:00:00Z.` | A time that does not parse. | | `q is longer than 120 characters.` | Text over the parameter’s length. | | `cursor is not valid. Use the next_cursor from a previous page.` | A cursor the API did not give. | | `source must be a source id.` | `source` on `/sources/items` is not a UUID. | `POST /sources` has its own body errors; see [Add a source](https://docs.alethman.com/reference/add-source/#errors). ## Retrying | Status | Retry? | How | | --- | --- | --- | | 400, 401, 403, 404, 409, 422 | No | The same request fails the same way. Fix it first. | | 429 | Yes | Wait `Retry-After` seconds, then retry. | | 500 | Yes | Exponential backoff with jitter: 1 s, 2 s, 4 s, up to about a minute. | | Network error, 502, 503, 504 | Yes | As for 500. These come from the network or a deploy, not the API, and may not carry the JSON body. | Every endpoint that reads is safe to retry. `POST /sources` is safe too: adding a feed you already follow answers `422` (“That feed is already one of your sources.”), never a duplicate. **Python** ```python import random import time import requests def call(s: requests.Session, url: str, **params): for attempt in range(6): try: r = s.get(url, params=params, timeout=30) except requests.ConnectionError: r = None if r is not None and r.status_code < 500 and r.status_code != 429: if not r.ok: err = r.json()["error"] raise RuntimeError(f"{r.status_code} {err['code']}: {err['message']}") return r.json() wait = int(r.headers.get("Retry-After", 0)) if r is not None and r.status_code == 429 else 2**attempt time.sleep(wait + random.random()) raise RuntimeError("gave up after 6 attempts") ``` **JavaScript** ```js async function call(url, headers) { for (let attempt = 0; attempt < 6; attempt++) { let res = null; try { res = await fetch(url, { headers }); } catch {} if (res && res.status < 500 && res.status !== 429) { if (!res.ok) { const { error } = await res.json(); throw new Error(`${res.status} ${error.code}: ${error.message}`); } return res.json(); } const wait = res?.status === 429 ? Number(res.headers.get("Retry-After") ?? 1) : 2 ** attempt; await new Promise((r) => setTimeout(r, (wait + Math.random()) * 1000)); } throw new Error("gave up after 6 attempts"); } ``` ## When it persists A `500` that keeps coming back is ours to fix. [Write to Alethman](https://alethman.com/contact/) with the time of the request (UTC), the endpoint and the parameters. Never send the key. --- # Rate limits > 120 requests a minute per key, the headers that count it down, what a 429 looks like, and the two smaller limits on bad keys and new sources. Source: https://docs.alethman.com/rate-limits/ | Limit | How much | Counted per | Over it | | --- | --- | --- | --- | | Requests | **120 a minute** | key | `429 rate_limited`, with `Retry-After` | | Failed key attempts | **30 a minute** | sending address | `429 rate_limited`, `Retry-After: 60` | | New sources | **20 a minute** | workspace | `400 bad_request` (“Twenty new sources a minute is the limit.”) | | MCP calls | share the key’s 120 a minute | key | a JSON-RPC error with HTTP 429 | The minute is a fixed window on the clock: it resets at the start of every minute, whenever the key’s first request in it came. Two keys in one workspace each get their own 120. ## The headers Every admitted request, including one that then fails with 400, 404, 409 or 422, carries three headers: | Header | Means | | --- | --- | | `X-RateLimit-Limit` | Requests allowed in a window on this key: `120`. | | `X-RateLimit-Remaining` | Requests left in the current window. | | `X-RateLimit-Reset` | When the window resets, in **Unix epoch seconds** (not seconds from now). | *Headers on a real response* ```json { "request": "GET /api/v1/signals?limit=5", "status": 200, "headers": { "content-type": "application/json", "cache-control": "no-store", "x-ratelimit-limit": "120", "x-ratelimit-remaining": "118", "x-ratelimit-reset": "1795238160" } } ``` A refused key (401) or a missing scope (403) is answered before the request is counted, so those responses carry no rate headers and cost nothing. ## When you hit it *429 Too Many Requests* ```json { "error": { "code": "rate_limited", "message": "120 requests a minute per key. Wait for the window to reset." } } ``` The response carries `Retry-After` (whole seconds, at least 1) beside the three headers. Wait that long, then carry on. The window then starts again at 120. ## Staying under it - **Page big.** `limit=200` on `/signals` reads 200 articles for one request. A month’s backfill takes minutes, not hours. - **Poll at the speed things change.** Articles arrive in cycles of a few minutes; outlooks refresh a few times a day; reports on their schedule. Polling faster returns the same answer. - **Watch `X-RateLimit-Remaining`** and slow down as it nears zero instead of waiting for a 429. - **One key per program.** A batch job and a live dashboard on separate keys cannot starve each other. > **Tip** > > A script that must not hit the limit can sleep `60 / 120 = 0.5` seconds between requests and never will. ## The bad-key limit After **30 requests with an invalid key from one address in a minute**, further invalid attempts from that address get `429` with `Retry-After: 60` instead of `401`. It exists to make a misconfigured client back off. It never refuses a valid key, even from the same address, so one broken script in an office does not lock out everyone else. --- # Versioning > The API is version 1. What can change without notice (additions), what never changes within a version, and how a breaking change would arrive. Source: https://docs.alethman.com/versioning/ The version is in the path: `https://dash.alethman.com/api/v1`. Version 1 is the only version and is stable. ## What can change within v1 Additions only. Build your client to tolerate them: - **New fields** in a response object. Ignore fields you do not know; do not fail on them. - **New endpoints**, and new optional parameters on existing ones. - **New values** in an open list: a new `event_type`, sector, attribution kind, report section or alert kind. Handle a value you do not recognise as “other” rather than failing. - **New error messages.** The `code` of an existing error never changes; the `message` may be reworded. - **New MCP tools**, and new optional arguments on existing tools. ## What never changes within v1 - A field’s name, type or meaning, and whether it can be null. - A parameter’s name, meaning, range or default. - An error’s status and `code`. - The shape of a list (`data`, `next_cursor`) and of an error (`error.code`, `error.message`). - The scopes an endpoint needs. - The `content.version` of a report: a report’s content changes format only under a new `content.version`, and old reports keep the version they were compiled with. ## A breaking change If something must break, it ships as a new version (`/api/v2`) beside v1, and v1 keeps answering while you move. Workspace owners hear about it before v1 is retired. Every change, breaking or not, lands in the [Changelog](https://docs.alethman.com/changelog/). ## Readings change; shapes do not Alethman tunes how it reads the news: how stories are grouped, how risk is read, how findings are graded. A story’s `risk_score` today may differ from what the same story would have scored last month. That is a change in the reading, not in the API: the field, its 0 to 100 range and its meaning stay the same. When the meaning of a field would change, that is a new field. --- # Changelog > Every change to the Alethman API and MCP server, newest first. Additions within v1 are listed as they ship. Source: https://docs.alethman.com/changelog/ Newest first. Within version 1 every change is an addition ([Versioning](https://docs.alethman.com/versioning/)). ## 21 November 2026 **Documentation.** The API and MCP server have their own site, generated from one OpenAPI 3.1 document ([openapi.json](https://docs.alethman.com/openapi.json)) that is tested against the API on every change. The dashboard’s old API page now points here. Limits that were in force but unwritten are now documented: the `awaiting` forecast status, the 500 `internal` error, the bad-key limit, the 20-a-minute source limit, parameter and body length limits, and which responses carry rate headers. ## 17 November 2026 **Forecasts.** `status=awaiting` on [`GET /forecasts`](https://docs.alethman.com/reference/forecasts/) returns forecasts past their deadline that are waiting for a verdict, and `counts.awaiting` counts them. `status=open` means unjudged with the deadline ahead, as on the dashboard’s Forecasts page. ## 26 October 2026 **MCP server.** The workspace is a remote MCP server at `https://dash.alethman.com/api/mcp`, with one read-only tool for each endpoint that reads ([MCP overview](https://docs.alethman.com/mcp/)). A tool’s result is capped at 40,000 characters: long lists are cut from the end with a `truncated` note, and long reports are read a page at a time. ## 25 October 2026 **Coordination findings.** Each [finding](https://docs.alethman.com/reference/coordination/) names an `orchestrator`, the `mediums` carrying it hardest and a `target`, from the roles the reporting gives each party. ## 28 September 2026 **Version 1.** Articles, stories, sector outlooks, forecasts, coordination findings, reports, your own sources and the workspace, with API keys, scopes, cursor pagination and the 120-a-minute limit. --- # API reference > Every endpoint of the Alethman API, the scope each needs and the MCP tool that runs it. Source: https://docs.alethman.com/reference/ Base URL: `https://dash.alethman.com/api/v1`. Every request sends a key as `Authorization: Bearer alm_live_…` ([Authentication](https://docs.alethman.com/authentication/)), every response is JSON unless asked for Markdown, and every list reads through the workspace’s scope ([Countries and scopes](https://docs.alethman.com/scopes/)). The whole API is also an [OpenAPI 3.1 document](https://docs.alethman.com/openapi.json): import it into Postman, Insomnia or a client generator. | Method | Path | What it returns | Scope | MCP tool | | --- | --- | --- | --- | --- | | GET | [`/workspace`](https://docs.alethman.com/reference/workspace/) | Get the workspace | any key | `get_workspace` | | GET | [`/signals`](https://docs.alethman.com/reference/signals/) | List articles | `signals:read` | `list_signals` | | GET | [`/stories`](https://docs.alethman.com/reference/stories/) | List stories | `intel:read` | `list_stories` | | GET | [`/stories/{id}`](https://docs.alethman.com/reference/story/) | Get a story | `intel:read` | `get_story` | | GET | [`/outlooks`](https://docs.alethman.com/reference/outlooks/) | List sector outlooks | `intel:read` | `list_outlooks` | | GET | [`/forecasts`](https://docs.alethman.com/reference/forecasts/) | List forecasts | `intel:read` | `list_forecasts` | | GET | [`/coordination`](https://docs.alethman.com/reference/coordination/) | List coordination findings | `intel:read` | `list_coordination` | | GET | [`/reports`](https://docs.alethman.com/reference/reports/) | List reports | `reports:read` | `list_reports` | | GET | [`/reports/{id}`](https://docs.alethman.com/reference/report/) | Get a report | `reports:read` | `get_report` | | GET | [`/sources`](https://docs.alethman.com/reference/sources/) | List sources | `sources:read` | `list_sources` | | POST | [`/sources`](https://docs.alethman.com/reference/add-source/) | Add a source | `sources:write` | none | | DELETE | [`/sources/{id}`](https://docs.alethman.com/reference/remove-source/) | Remove a source | `sources:write` | none | | GET | [`/sources/items`](https://docs.alethman.com/reference/source-items/) | List source items | `sources:read` | `list_source_items` | ## Workspace - **[Get the workspace](https://docs.alethman.com/reference/workspace/)** · `GET /workspace`: The workspace the key belongs to: what it follows, which parts of Alethman are on, its report and alert settings, and the key’s own name and scopes. ## Signals - **[List articles](https://docs.alethman.com/reference/signals/)** · `GET /signals`: Articles in the workspace’s scope, newest first, each with its outlet, sectors, states and the story it was grouped into. ## Stories - **[List stories](https://docs.alethman.com/reference/stories/)** · `GET /stories`: Stories in scope: articles about one event, grouped, with how many independent outlets carry each, where it is, its risk and a one-line reading. - **[Get a story](https://docs.alethman.com/reference/story/)** · `GET /stories/{id}`: One story in full: how Alethman read it (sectors, event type, risk and what it rests on, the parties the reporting names), a summary, its places and every article, how coverage divides, the coverage by country, and the forecasts made about it. ## Outlooks - **[List sector outlooks](https://docs.alethman.com/reference/outlooks/)** · `GET /outlooks`: The latest reading for each sector the workspace follows: a risk score and level, the direction against the reading before, a verdict, and the stories driving it. ## Forecasts - **[List forecasts](https://docs.alethman.com/reference/forecasts/)** · `GET /forecasts`: Dated yes-or-no forecasts in the workspace’s sectors, each with its probability, deadline, resolution rule and, once judged, its outcome. ## Coordination - **[List coordination findings](https://docs.alethman.com/reference/coordination/)** · `GET /coordination`: Coordination findings touching the workspace’s scope (Veritos’s campaign view): stories the reporting links into one pattern, each naming who the reporting says runs it, the outlets carrying it hardest and its target, with an evidence grade. ## Reports - **[List reports](https://docs.alethman.com/reference/reports/)** · `GET /reports`: The workspace’s compiled reports, newest first. - **[Get a report](https://docs.alethman.com/reference/report/)** · `GET /reports/{id}`: One report, as structured JSON (the default) or as the Markdown the dashboard prints. ## Sources - **[List sources](https://docs.alethman.com/reference/sources/)** · `GET /sources`: The feeds the workspace follows on top of Alethman’s own coverage (a regulator’s press releases, a trade body, a local paper), with each feed’s health. - **[Add a source](https://docs.alethman.com/reference/add-source/)** · `POST /sources`: Follow a new feed. - **[Remove a source](https://docs.alethman.com/reference/remove-source/)** · `DELETE /sources/{id}`: Stop following a feed. - **[List source items](https://docs.alethman.com/reference/source-items/)** · `GET /sources/items`: What the workspace’s own feeds carried, newest first, each item read for sectors and states like any article. ## Objects Every object the API returns, field by field, is on [Objects](https://docs.alethman.com/reference/objects/). --- # Get the workspace > The workspace the key belongs to: what it follows, which parts of Alethman are on, its report and alert settings, and the key's own name and scopes. Source: https://docs.alethman.com/reference/workspace/ ```http GET https://dash.alethman.com/api/v1/workspace ``` - **Scope:** Any valid key - **MCP tool:** [`get_workspace`](https://docs.alethman.com/mcp/tools/#get_workspace) - **Rate limit:** [120 a minute per key](https://docs.alethman.com/rate-limits/) The workspace the key belongs to: what it follows, which parts of Alethman are on, its report and alert settings, and the key’s own name and scopes. Any valid key can call it, whatever its scopes. Call it first: every other endpoint reads through the scope it returns. ## Request This endpoint takes no parameters. ## Example **curl** ```bash curl "https://dash.alethman.com/api/v1/workspace" \ -H "Authorization: Bearer $ALETHMAN_KEY" ``` **Python** ```python import os import requests r = requests.get( "https://dash.alethman.com/api/v1/workspace", headers={"Authorization": f"Bearer {os.environ['ALETHMAN_KEY']}"}, timeout=30, ) r.raise_for_status() print(r.json()) ``` **JavaScript** ```js const url = "https://dash.alethman.com/api/v1/workspace"; 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 **200 OK**, `application/json`, with the [rate-limit headers](https://docs.alethman.com/rate-limits/). A real response, shortened: long lists are cut to a few items. *200 OK* ```json { "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" ] } } ``` ### Fields | Field | Type | Values | What it is | | --- | --- | --- | --- | | `workspace` | object | | | | `workspace.name` | string | | The workspace’s name. | | `workspace.slug` | string | | Its slug. | | `scope` | object | | What the workspace follows. Every endpoint reads through this. | | `scope.sectors` | array of strings | [a sector key](https://docs.alethman.com/scopes/#sectors) | The sectors it follows. Every list in the API stays inside these. | | `scope.states` | array of strings | [a state slug](https://docs.alethman.com/scopes/#states) | The states it follows; empty when it follows all of India. | | `scope.all_india` | boolean | | True when it follows every state. | | `scope.national` | boolean | | True when it also follows national news that names no state. | | `coverage` | array of strings | `signals`, `live`, `stories`, `outlooks`, `forecasts`, `coordination` | The parts of Alethman the workspace has turned on. | | `reports` | object | | Report settings. | | `reports.frequency` | string | `daily`, `weekdays`, `weekly`, `fortnightly`, `monthly`, `on_demand` | How often reports are compiled. | | `reports.depth` | string | `brief`, `standard`, `dossier` | How long each report runs. | | `reports.organise` | string | `sector`, `state`, `risk` | How its stories are grouped. | | `reports.sections` | array of strings | `judgements`, `outlooks`, `stories`, `states`, `forecasts`, `coordination`, `sources` | The sections each report includes. | | `reports.screenshots` | boolean | | True when reports carry screenshots of key articles. | | `reports.next_at` | string (time) or null | | When the next scheduled report is due. | | `alerts` | object | | Alert settings. | | `alerts.threshold` | integer | | The risk score from which alerts fire, set by the workspace (0 to 100). | | `alerts.kinds` | array of strings | `threshold`, `rising`, `coordination`, `forecast`, `report`, `source` | The alert kinds turned on. | | `key` | object | | The key that made the request. | | `key.name` | string | | The name this key was given. | | `key.scopes` | array of strings | `signals:read`, `intel:read`, `reports:read`, `sources:read`, `sources:write` | The scopes this key carries. | ## Errors Every error has the body `{"error": {"code": …, "message": …}}`; branch on `code`. See [Errors](https://docs.alethman.com/errors/) for how to handle each. | Status | Code | When | | --- | --- | --- | | 401 | `unauthenticated` | No Authorization header, or one that is not `Bearer `. 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"`. | | 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 - Any valid key can call it, whatever its scopes, so it is the cheapest way to check a key works. - `scope` is what every other endpoint reads through. A `sector` or `state` filter outside it returns an empty list, never another workspace’s data. - `key.scopes` tells a program which endpoints it can call before it calls them. ## From an AI assistant The MCP tool [`get_workspace`](https://docs.alethman.com/mcp/tools/#get_workspace) runs this endpoint’s code and returns the same JSON. --- # List articles > Articles in the workspace's scope, newest first, each with its outlet, sectors, states and the story it was grouped into. Source: https://docs.alethman.com/reference/signals/ ```http GET https://dash.alethman.com/api/v1/signals ``` - **Scope:** [`signals:read`](https://docs.alethman.com/authentication/#scopes) - **MCP tool:** [`list_signals`](https://docs.alethman.com/mcp/tools/#list_signals) - **Rate limit:** [120 a minute per key](https://docs.alethman.com/rate-limits/) Articles in the workspace’s scope, newest first, each with its outlet, sectors, states and the story it was grouped into. The firehose under every other endpoint: use it to mirror coverage into your own store, or to watch a state or sector article by article. Pages with `next_cursor`. ## Request | Parameter | In | Type | Default | Values | What it does | | --- | --- | --- | --- | --- | --- | | `sector` | query | string | | [a sector key](https://docs.alethman.com/scopes/#sectors) | 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](https://docs.alethman.com/scopes/#states) | Only this state or union territory. | | `q` | query | string | | up to 120 characters | Words to find in the headline. | | `language` | query | string | | up to 8 characters | Only headlines in this language: an ISO 639-1 code such as `en`, `hi`, `ta`. | | `since` | query | string (time) | | | Only articles published after this time, as ISO 8601, e.g. `2026-11-21T00:00:00Z`. | | `limit` | query | integer | `50` | 1 to 200 | How many articles to return, 1 to 200. | | `cursor` | query | string | | | The `next_cursor` from the previous page. Opaque: pass it back unchanged. | ## Example **curl** ```bash curl "https://dash.alethman.com/api/v1/signals?sector=energy_power&since=2026-11-20T00:00:00Z&limit=50" \ -H "Authorization: Bearer $ALETHMAN_KEY" ``` **Python** ```python import os import requests r = requests.get( "https://dash.alethman.com/api/v1/signals", headers={"Authorization": f"Bearer {os.environ['ALETHMAN_KEY']}"}, params={"sector": "energy_power", "since": "2026-11-20T00:00:00Z", "limit": 50}, timeout=30, ) r.raise_for_status() print(r.json()) ``` **JavaScript** ```js const url = new URL("https://dash.alethman.com/api/v1/signals"); url.search = new URLSearchParams({ sector: "energy_power", since: "2026-11-20T00:00:00Z", limit: "50" }); 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 **200 OK**, `application/json`, with the [rate-limit headers](https://docs.alethman.com/rate-limits/). A real response, shortened: long lists are cut to a few items. *200 OK* ```json { "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 }, { "id": 138694799, "title": "Polling Underway Across Ladakh For Panchayat And Municipal Elections 2026", "url": "https://www.dailyexcelsior.com/polling-underway-across-ladakh-for-panchayat-and-municipal-elections-2026/", "published_at": "2026-11-21T05:01:23.000Z", "language": null, "outlet": { "id": "daily-excelsior", "name": "Daily Excelsior" }, "sectors": [ "politics_governance" ], "states": [], "story": null }, { "id": 138682757, "title": "सागर में बिजली कंपनी के स्टोर रूम में भीषण आग:10 फीट ऊंची उठीं लपटें, मीटर-उपकरण जलकर राख; 2 घंटे बाद पाया काबू", "url": "https://www.bhaskar.com/local/mp/sagar/news/makronia-sagar-electricity-company-store-room-fire-incident-139753300.html", "published_at": "2026-11-21T04:58:11.000Z", "language": "hi", "outlet": { "id": "dainik-bhaskar", "name": "Dainik Bhaskar" }, "sectors": [ "energy_power" ], "states": [], "story": null }, { "id": 138626948, "title": "Ladakh votes in panchayat and municipal polls amid bitter chill after eight-year gap", "url": "https://www.greaterkashmir.com/ladakh/ladakh-votes-in-panchayat-and-municipal-polls-amid-bitter-chill-after-eight-year-gap-12828341", "published_at": "2026-11-21T04:46:26.000Z", "language": "en", "outlet": { "id": "greater-kashmir", "name": "Greater Kashmir" }, "sectors": [ "politics_governance" ], "states": [ "ladakh" ], "story": { "id": 294998, "label": "Ladakh Elections 2026: 541 candidates file their nomination papers for 100 LAHDC seats in eight districts", "independent_outlets": 9 } } ], "next_cursor": "MjAyNi0xMS0yMVQwNDo0NjoyNi4wMDBafDEzODYyNjk0OA" } ``` ### Fields | Field | Type | Values | What it is | | --- | --- | --- | --- | | `data` | array of objects | | Articles, newest first. | | `data[].id` | integer | | The article’s id. Stable. | | `data[].title` | string | | The headline as the outlet published it, in its own language. | | `data[].url` | string (url) | | The article’s address on the outlet’s site. | | `data[].published_at` | string (time) | | When the outlet published it (UTC). | | `data[].language` | string or null | | ISO 639-1 code of the headline’s language (`en`, `hi`, `ta` …), or null where it was not detected. | | `data[].outlet` | object | | Who published it. | | `data[].outlet.id` | string | | The outlet’s stable slug. | | `data[].outlet.name` | string | | The outlet’s name. | | `data[].sectors` | array of strings | [a sector key](https://docs.alethman.com/scopes/#sectors) | Sectors the article was read as touching. Can be empty. | | `data[].states` | array of strings | [a state slug](https://docs.alethman.com/scopes/#states) | States and union territories the article is about. Empty when it names none (national or foreign news). | | `data[].story` | object or null | | The story the article was grouped into, or null while it stands alone. | | `data[].story.id` | integer | | The story’s id; pass it to GET /stories/{id}. | | `data[].story.label` | string | | The story’s headline. | | `data[].story.independent_outlets` | integer | | How many independent outlets carry the story. | | `next_cursor` | string or null | | Pass as `cursor` for the next page. Null when this page is the last (it returned fewer than `limit`). | ## Errors Every error has the body `{"error": {"code": …, "message": …}}`; branch on `code`. See [Errors](https://docs.alethman.com/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 `. 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 - To mirror coverage into your own store, page with `cursor` until `next_cursor` is null, then poll with `since` set to the newest `published_at` you hold. - `next_cursor` is set whenever a page comes back full. A full last page therefore gives a cursor whose next page is empty: stop on an empty `data` as well as on a null cursor. - `q` matches words in the headline as published, so a Hindi query finds Hindi headlines. - An article with no states is national or foreign news. It appears only when the workspace follows national news (`scope.national` on GET /workspace). ## From an AI assistant The MCP tool [`list_signals`](https://docs.alethman.com/mcp/tools/#list_signals) runs this endpoint’s code and returns the same JSON. Its default `limit` differs: The REST default is 50. --- # List stories > Stories in scope: articles about one event, grouped, with how many independent outlets carry each, where it is, its risk and a one-line reading. Source: https://docs.alethman.com/reference/stories/ ```http GET https://dash.alethman.com/api/v1/stories ``` - **Scope:** [`intel:read`](https://docs.alethman.com/authentication/#scopes) - **MCP tool:** [`list_stories`](https://docs.alethman.com/mcp/tools/#list_stories) - **Rate limit:** [120 a minute per key](https://docs.alethman.com/rate-limits/) Stories in scope: articles about one event, grouped, with how many independent outlets carry each, where it is, its risk and a one-line reading. The unit most work starts from. ## Request | Parameter | In | Type | Default | Values | What it does | | --- | --- | --- | --- | --- | --- | | `sector` | query | string | | [a sector key](https://docs.alethman.com/scopes/#sectors) | 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](https://docs.alethman.com/scopes/#states) | Only this state or union territory. | | `hours` | query | integer | `72` | 1 to 720 | How far back to look, in hours, 1 to 720 (30 days). A story counts when its latest article falls inside the window. | | `order` | query | string | `voices` | `voices`, `risk`, `recent` | `voices`: most independent outlets first. `risk`: highest risk first. `recent`: newest activity first. | | `limit` | query | integer | `20` | 1 to 100 | How many stories to return, 1 to 100. | ## Example **curl** ```bash curl "https://dash.alethman.com/api/v1/stories?state=manipur&order=risk&limit=10" \ -H "Authorization: Bearer $ALETHMAN_KEY" ``` **Python** ```python import os import requests r = requests.get( "https://dash.alethman.com/api/v1/stories", headers={"Authorization": f"Bearer {os.environ['ALETHMAN_KEY']}"}, params={"state": "manipur", "order": "risk", "limit": 10}, timeout=30, ) r.raise_for_status() print(r.json()) ``` **JavaScript** ```js const url = new URL("https://dash.alethman.com/api/v1/stories"); url.search = new URLSearchParams({ state: "manipur", order: "risk", limit: "10" }); 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 **200 OK**, `application/json`, with the [rate-limit headers](https://docs.alethman.com/rate-limits/). A real response, shortened: long lists are cut to a few items. *200 OK* ```json { "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" }, { "id": 302282, "label": "Supreme Court dismisses Tamil Nadu pleas seeking 11 TMC of Cauvery water from Karnataka", "independent_outlets": 29, "articles": 42, "trajectory": "steady", "first_seen": "2026-11-19T19:23:01.000Z", "last_seen": "2026-11-21T01:27:48.000Z", "sectors": [ "agriculture_food", "public_order_unrest", "politics_governance" ], "states": [ "tamil-nadu", "karnataka" ], "place": "Tamil Nadu", "risk_score": 35, "risk_level": "guarded", "reading": "Supreme Court dismissed Tamil Nadu's applications seeking extra Cauvery water from Karnataka for the 2026-27 irrigation year.", "event_type": "court_ruling" }, { "id": 295701, "label": "Massive fire engulfs Pune’s Timber Market; over 50 shops gutted", "independent_outlets": 13, "articles": 26, "trajectory": "decaying", "first_seen": "2026-11-18T01:18:12.000Z", "last_seen": "2026-11-20T03:26:20.000Z", "sectors": [ "public_order_unrest", "crime_law_enforcement" ], "states": [ "maharashtra" ], "place": "Pune", "risk_score": 25, "risk_level": "guarded", "reading": "A late-night fire gutted dozens of timber and plywood shops and six houses at Pune's Timber Market in Bhavani Peth; no injuries were reported.", "event_type": "crime" } ] } ``` ### Fields | Field | Type | Values | What it is | | --- | --- | --- | --- | | `data` | array of objects | | Stories in the order asked for. | | `data[].id` | integer | | The story’s id. Stable: when two stories merge, the old id still answers on GET /stories/{id}. | | `data[].label` | string | | A headline for the story, from its most representative article. | | `data[].independent_outlets` | integer | | Outlets carrying the story independently: syndicated wire copy and copy credited to a news agency count once. | | `data[].articles` | integer | | Every article in the story, syndicated copies included. | | `data[].trajectory` | string or null | `new`, `rising`, `steady`, `decaying` | Where coverage is heading: `new`, `rising`, `steady` or `decaying`. | | `data[].first_seen` | string (time) | | The first article’s publication time. | | `data[].last_seen` | string (time) | | The latest article’s publication time. | | `data[].sectors` | array of strings | [a sector key](https://docs.alethman.com/scopes/#sectors) | Sectors the story touches. | | `data[].states` | array of strings | [a state slug](https://docs.alethman.com/scopes/#states) | States and union territories the story is about. | | `data[].place` | string or null | | The story’s main place (a city, district or state), or null. | | `data[].risk_score` | integer or null | | 0 to 100: how much disruption the reporting describes, read by Alethman. Higher is more severe. Comparable across sectors and over time. | | `data[].risk_level` | string or null | `low`, `guarded`, `elevated`, `high`, `severe` | The band the score falls in: `low`, `guarded`, `elevated`, `high` or `severe`. Use it as the headline; band edges are not published and may be tuned. | | `data[].reading` | string or null | | One sentence: what happened, in plain English whatever the articles’ language. | | `data[].event_type` | string or null | `protest`, `strike_bandh`, `violence_attack`, `security_operation`, `policy_decision`, `court_ruling`, `election_politics`, `economic_indicator`, `corporate_move`, `trade_action`, `disaster_accident`, `crime`, `diplomatic`, `other` | What kind of event the story is. | ## Errors Every error has the body `{"error": {"code": …, "message": …}}`; branch on `code`. See [Errors](https://docs.alethman.com/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 `. 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 - A story counts toward the window by its latest article, so a long-running story that moved today is included even if it began weeks ago. - `independent_outlets` is the number to sort and threshold on: it counts syndicated wire copy once, where `articles` counts every copy. - This list does not page. Narrow it with `sector`, `state` and `hours`, or raise `limit` to 100. ## From an AI assistant The MCP tool [`list_stories`](https://docs.alethman.com/mcp/tools/#list_stories) runs this endpoint’s code and returns the same JSON. --- # Get a story > One story in full: how Alethman read it (sectors, event type, risk and what it rests on, the parties the reporting names), a summary, its places and every article, how coverage divides, the coverage by country, and the forecasts made about it. Source: https://docs.alethman.com/reference/story/ ```http GET https://dash.alethman.com/api/v1/stories/{id} ``` - **Scope:** [`intel:read`](https://docs.alethman.com/authentication/#scopes) - **MCP tool:** [`get_story`](https://docs.alethman.com/mcp/tools/#get_story) - **Rate limit:** [120 a minute per key](https://docs.alethman.com/rate-limits/) One story in full: how Alethman read it (sectors, event type, risk and what it rests on, the parties the reporting names), a summary, its places and every article, how coverage divides, the coverage by country, and the forecasts made about it. A story outside the workspace’s sectors and states answers 404, as if it did not exist. When two stories merge, the old id still answers with the merged story; compare `id` with `requested_id`. ## Request | Parameter | In | Type | Default | Values | What it does | | --- | --- | --- | --- | --- | --- | | `id` **required** | path | string | | up to 12 digits | The story id, from GET /stories, a signal’s `story.id`, an outlook driver or a coordination finding. A whole number of up to 12 digits. | ## Example **curl** ```bash curl "https://dash.alethman.com/api/v1/stories/297641" \ -H "Authorization: Bearer $ALETHMAN_KEY" ``` **Python** ```python import os import requests r = requests.get( "https://dash.alethman.com/api/v1/stories/297641", headers={"Authorization": f"Bearer {os.environ['ALETHMAN_KEY']}"}, timeout=30, ) r.raise_for_status() print(r.json()) ``` **JavaScript** ```js const url = "https://dash.alethman.com/api/v1/stories/297641"; 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 **200 OK**, `application/json`, with the [rate-limit headers](https://docs.alethman.com/rate-limits/). A real response, shortened: long lists are cut to a few items. *200 OK* ```json { "id": 297641, "requested_id": 297641, "label": "EPFO approves systematic PF withdrawal plan", "proposition": "The EPFO's systematic withdrawal plan will benefit retiring provident fund members.", "independent_outlets": 35, "articles_count": 89, "trajectory": "steady", "first_seen": "2026-11-18T22:24:07.000Z", "last_seen": "2026-11-21T03:51:15.000Z", "tag": { "sectors": [ "banking_finance_markets", "politics_governance" ], "event_type": "policy_decision", "theme": "epfo-provident-fund-withdrawal-reforms", "risk_score": 12, "risk_level": "low", "risk_basis": "A routine approval of pension-fund withdrawal flexibility and investment rules by the EPFO board, with no disruption or market shock described.", "reading": "The EPFO board approved reforms easing PF withdrawals, including a systematic withdrawal plan, lower minimum balance and limited alternative fund investment.", "coordinated": false, "coordination_basis": null, "named_by_reporting": [ { "kind": "state_agency", "name": "Employees' Provident Fund Organisation", "role": "responder", "article_ids": [ 132167016, 131536578, 131475996 ], "attribution": "official_statement" } ] }, "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": [ { "name": "Delhi", "kind": "city", "state": "delhi", "primary": true }, { "name": "Mumbai", "kind": "city", "state": "maharashtra", "primary": false }, { "name": "Guwahati", "kind": "city", "state": "assam", "primary": false } ], "articles": [ { "id": 135003766, "title": "Explained | Major overhaul of PF withdrawals", "url": "https://www.deccanherald.com/india/explained-major-overhaul-of-pf-withdrawals-4225245", "outlet": "Deccan Herald", "published_at": "2026-11-20T09:39:06.000Z", "language": "en", "wire": "PTI" }, { "id": 133556770, "title": "EPFO approves systematic PF withdrawal plan, cuts minimum balance requirement to 10%", "url": "https://www.greaterkashmir.com/business/epfo-approves-systematic-pf-withdrawal-plan-cuts-minimum-balance-requirement-to-10-12825076", "outlet": "Greater Kashmir", "published_at": "2026-11-20T02:25:40.000Z", "language": "en", "wire": "PTI" }, { "id": 133480577, "title": "EPFO approves periodic PF payouts for retirees, eases withdrawal norms", "url": "https://www.hindustantimes.com/india-news/epfo-approves-periodic-pf-payouts-for-retirees-eases-withdrawal-norms-101795138227494.html", "outlet": "Hindustan Times", "published_at": "2026-11-20T01:44:24.000Z", "language": "en", "wire": null } ], "bloc_finding": { "statement": "Coverage does not split. 8 independent outlets (DNA India, Mathrubhumi, Mint, Odisha Bytes, Prameya News, The Economic Times, The Indian Express, The Times of India) support the proposition \"The EPFO's systematic withdrawal plan will benefit retiring provident fund members.\" and frame it as Steady retirement income.", "evidence_grade": "D", "coordination_likelihood": "low", "what_would_change": "three or more independent outlets carrying the opposing frame would make this a split." }, "by_country": [ { "country": "IND", "articles": 89, "voices": 35, "supports": 10, "opposes": 0, "neutral": 8, "labelled": 24, "frame": "Easier access to PF savings" } ], "forecasts": [] } ``` ### Fields | Field | Type | Values | What it is | | --- | --- | --- | --- | | `id` | integer | | The story’s current id. Differs from requested\_id when the story you asked for was merged into this one. | | `requested_id` | integer | | The id you asked for. | | `label` | string | | The story’s headline. | | `proposition` | string or null | | The claim at the centre of the coverage, as one sentence outlets can agree or disagree with. | | `independent_outlets` | integer | | Independent outlets carrying it. | | `articles_count` | integer | | Every article in it. | | `trajectory` | string or null | `new`, `rising`, `steady`, `decaying` | Where coverage is heading: `new`, `rising`, `steady` or `decaying`. | | `first_seen` | string (time) | | The first article’s time. | | `last_seen` | string (time) | | The latest article’s time. | | `tag` | object or null | | How Alethman read the story, or null before it is read. | | `tag.sectors` | array of strings | [a sector key](https://docs.alethman.com/scopes/#sectors) | Sectors it touches. | | `tag.event_type` | string or null | `protest`, `strike_bandh`, `violence_attack`, `security_operation`, `policy_decision`, `court_ruling`, `election_politics`, `economic_indicator`, `corporate_move`, `trade_action`, `disaster_accident`, `crime`, `diplomatic`, `other` | What kind of event the story is. | | `tag.theme` | string or null | | A slug for its theme. | | `tag.risk_score` | integer or null | | 0 to 100: how much disruption the reporting describes, read by Alethman. Higher is more severe. Comparable across sectors and over time. | | `tag.risk_level` | string or null | `low`, `guarded`, `elevated`, `high`, `severe` | The band the score falls in: `low`, `guarded`, `elevated`, `high` or `severe`. Use it as the headline; band edges are not published and may be tuned. | | `tag.risk_basis` | string or null | | One sentence: what in the reporting the risk reading rests on. | | `tag.reading` | string or null | | One sentence: what happened. | | `tag.coordinated` | boolean | | True when the story is part of a coordination finding. | | `tag.coordination_basis` | string or null | | Why, when coordinated is true; else null. | | `tag.named_by_reporting` | array of objects | | The parties the reporting names, each with its role and how it is attributed. | | `tag.named_by_reporting[].kind` | string | | What the party is (as Party.kind). | | `tag.named_by_reporting[].name` | string | | The party’s name. | | `tag.named_by_reporting[].role` | string | | Its role (as Party.role). | | `tag.named_by_reporting[].article_ids` | array of integers | | The articles that name it so. | | `tag.named_by_reporting[].attribution` | string | `official_statement`, `claim_by_actor`, `reported`, `alleged_by_opponent`, `speculation` | How the reporting attributes the role, strongest first: `official_statement`, `claim_by_actor` (the party’s own claim), `reported` (plain reporting), `alleged_by_opponent`, `speculation`. | | `summary` | string or null | | A paragraph: what happened, where outlets agree and where they differ. | | `places` | array of objects | | Places the story names. | | `places[].name` | string | | The place’s name. | | `places[].kind` | string | | `city`, `district`, `state` and so on. | | `places[].state` | string or null | | The state it is in. | | `places[].primary` | boolean | | True for the story’s main place. | | `articles` | array of objects | | Every article in the story, newest first. | | `articles[].id` | integer | | The article’s id. | | `articles[].title` | string | | Its headline. | | `articles[].url` | string (url) | | Its address. | | `articles[].outlet` | string | | The outlet’s name. | | `articles[].published_at` | string (time) | | When it was published. | | `articles[].language` | string or null | | Its language. | | `articles[].wire` | string or null | | The news agency it credits (PTI, ANI, Reuters …), or null for the outlet’s own reporting. | | `bloc_finding` | object or null | | How coverage of the proposition divides, or null when not yet read. | | `bloc_finding.statement` | string | | Whether coverage splits into camps, and how. | | `bloc_finding.evidence_grade` | string | `A`, `B`, `C`, `D` | `A` to `D`, strongest first: how clearly coverage splits. `D`: no split. | | `bloc_finding.coordination_likelihood` | string | `low`, `moderate`, `elevated` | `low`, `moderate` or `elevated`: how far the split looks organised rather than ordinary disagreement. | | `bloc_finding.what_would_change` | string | | What new coverage would change the finding. | | `by_country` | array of objects | | The coverage by the home country of its outlets. | | `by_country[].country` | string | | ISO 3166-1 alpha-3 code of the outlets’ home country. | | `by_country[].articles` | integer | | Articles from that country’s outlets. | | `by_country[].voices` | integer | | Independent outlets from that country. | | `by_country[].supports` | integer | | Of those read for stance: outlets that support the proposition. | | `by_country[].opposes` | integer | | Outlets that oppose it. | | `by_country[].neutral` | integer | | Outlets that report it without a side. | | `by_country[].labelled` | integer | | Articles read for stance. | | `by_country[].frame` | string or null | | How that country’s outlets frame the story, in a few words. | | `forecasts` | array of objects | | Forecasts made about this story. | | `forecasts[].id` | integer | | The forecast’s id. | | `forecasts[].sector` | string | [a sector key](https://docs.alethman.com/scopes/#sectors) | A sector key. See Countries and scopes for the list. | | `forecasts[].question` | string | | A yes-or-no question with a date in it. | | `forecasts[].probability` | number | 0 to 1 | The probability of yes when the forecast was made, 0 to 1. It is never revised. | | `forecasts[].made_at` | string (time) | | When the forecast was made. | | `forecasts[].resolves_by` | string (time) | | The deadline. | | `forecasts[].resolution_rule` | string | | What counts as yes, written before the outcome was known. | | `forecasts[].status` | string | `open`, `awaiting`, `resolved` | `open`: the deadline is ahead. `awaiting`: the deadline has passed and no verdict is in yet. `resolved`: judged. | | `forecasts[].resolved_at` | string (time) or null | | When it was judged, or null. | | `forecasts[].outcome` | boolean or null | | True if it came true, false if not; null until resolved, or when a resolved forecast was voided. | | `forecasts[].verdict` | string or null | | The judgement in a sentence, with what it rests on, or null. | | `forecasts[].rationale` | string | | Why the probability was set where it was, written when it was made. | ## Errors Every error has the body `{"error": {"code": …, "message": …}}`; branch on `code`. See [Errors](https://docs.alethman.com/errors/) for how to handle each. | Status | Code | When | | --- | --- | --- | | 401 | `unauthenticated` | No Authorization header, or one that is not `Bearer `. 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. | | 404 | `not_found` | No story with that id, an id that is not a whole number of up to 12 digits, or a story outside the workspace’s sectors and states. Message: “No story with that id.” | | 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 - A story outside the workspace’s sectors and states answers 404, exactly like one that does not exist, so ids never leak another workspace’s scope. - When two stories are merged, the old id keeps answering with the merged story. Store `id`, not `requested_id`, from then on. - `tag` and `bloc_finding` are null while a new story is still being read; they fill in within the hour. - `named_by_reporting` records who the reporting names and how it attributes them. It is never Alethman’s own finding about a party. ## From an AI assistant The MCP tool [`get_story`](https://docs.alethman.com/mcp/tools/#get_story) runs this endpoint’s code and returns the same JSON. --- # List sector outlooks > The latest reading for each sector the workspace follows: a risk score and level, the direction against the reading before, a verdict, and the stories driving it. Source: https://docs.alethman.com/reference/outlooks/ ```http GET https://dash.alethman.com/api/v1/outlooks ``` - **Scope:** [`intel:read`](https://docs.alethman.com/authentication/#scopes) - **MCP tool:** [`list_outlooks`](https://docs.alethman.com/mcp/tools/#list_outlooks) - **Rate limit:** [120 a minute per key](https://docs.alethman.com/rate-limits/) The latest reading for each sector the workspace follows: a risk score and level, the direction against the reading before, a verdict, and the stories driving it. One row per sector, in the workspace’s sector order. Readings refresh several times a day. ## Request This endpoint takes no parameters. ## Example **curl** ```bash curl "https://dash.alethman.com/api/v1/outlooks" \ -H "Authorization: Bearer $ALETHMAN_KEY" ``` **Python** ```python import os import requests r = requests.get( "https://dash.alethman.com/api/v1/outlooks", headers={"Authorization": f"Bearer {os.environ['ALETHMAN_KEY']}"}, timeout=30, ) r.raise_for_status() print(r.json()) ``` **JavaScript** ```js const url = "https://dash.alethman.com/api/v1/outlooks"; 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 **200 OK**, `application/json`, with the [rate-limit headers](https://docs.alethman.com/rate-limits/). A real response, shortened: long lists are cut to a few items. *200 OK* ```json { "data": [ { "sector": "energy_power", "name": "Energy and power", "quiet": false, "risk_score": 48, "risk_level": "elevated", "previous_score": 61, "direction": "easing", "verdict": "No new Hormuz attack or Tarali ruling emerged in the last 24 hours; the Petroleum Minister again said India can manage oil and gas supply even if West Asia tensions worsen, while the IEA warned of a major Hormuz-linked supply shock and flagged India as the engine of future demand growth. Haryana's Appellate Tribunal kept Eleven Power's Gurugram-Nuh distribution licence suspended, and Karnataka pressed the Centre again on E20 ethanol testing. Coal, power and core-sector output data were strong and crude prices eased, suggesting near-term supply stress is being managed rather than escalating. Watch Hormuz shipping risk and the Gurugram-Nuh licence fight for the next flashpoint.", "drivers": [ { "story_id": 300584, "label": "How Hormuz oil shock is India's chance to reset its energy future", "why": "IEA flags Hormuz disruption as a major supply shock with India central to demand growth" }, { "story_id": 295835, "label": "Karnataka Flags Excess Ethanol in Petrol Samples, Urges Centre to Review E20 Policy", "why": "Karnataka's renewed E20 challenge keeps fuel-policy friction with the Centre alive" }, { "story_id": 295865, "label": "No immediate relief to Eleven Power in APTEL on parallel-distribution licence", "why": "Tribunal's refusal to Eleven Power prolongs Haryana distribution licence dispute" } ], "stories_read": 18, "open_forecasts": 35, "generated_at": "2026-11-20T22:29:38.066Z" }, { "sector": "public_order_unrest", "name": "Public order and unrest", "quiet": false, "risk_score": 80, "risk_level": "severe", "previous_score": 76, "direction": "rising", "verdict": "Cyclone Akvan is making landfall near Narsapur-Puri in Odisha, with tens of thousands evacuated, trains cancelled and schools shut. Manipur faces compounding shocks: methanol liquor deaths in Chandel have climbed to 11-15 with over 150 hospitalised, while security forces killed a KCP militant and arrested eight in Imphal West. Bangladesh's Awami League supporters torched police vehicles and a station in Gopalganj, adding border-adjacent risk. Political violence persists in Andhra Pradesh's Pulivendula and Kolkata's TMC-BJP clashes continue after a TMC MP's police questioning. Watch cyclone casualty figures, Manipur's liquor-death fallout, and reaction to the Thiruparankundram lamp lighting.", "drivers": [ { "story_id": 299819, "label": "ओडिशा में चक्रवात 'अकवान' का खतरा, अब तक 72 हजार लोगों को सुरक्षित स्थानों पर पहुंचाया गया", "why": "Cyclone landfall near Narsapur-Puri forces mass evacuations and shutdowns" }, { "story_id": 301791, "label": "Manipur Spurious Liquor Tragedy: Death Toll Rises To 11, Over 180 Hospitalised", "why": "Methanol liquor deaths in Chandel climb past 11, over 150 hospitalised" }, { "story_id": 302765, "label": "Manipur: Militant killed, several others arrested after encounter in Imphal West", "why": "Security forces kill KCP militant, arrest eight in Imphal West" } ], "stories_read": 30, "open_forecasts": 25, "generated_at": "2026-11-21T04:51:50.457Z" } ] } ``` ### Fields | Field | Type | Values | What it is | | --- | --- | --- | --- | | `data` | array of objects | | One reading per followed sector. | | `data[].sector` | string | [a sector key](https://docs.alethman.com/scopes/#sectors) | A sector key. See Countries and scopes for the list. | | `data[].name` | string | | The sector’s name. | | `data[].quiet` | boolean | | True when the sector had too little reporting in its window to read: the score, level, direction and verdict are then null. | | `data[].risk_score` | integer or null | | 0 to 100: how much disruption the reporting describes, read by Alethman. Higher is more severe. Comparable across sectors and over time. | | `data[].risk_level` | string or null | `low`, `guarded`, `elevated`, `high`, `severe` | The band the score falls in: `low`, `guarded`, `elevated`, `high` or `severe`. Use it as the headline; band edges are not published and may be tuned. | | `data[].previous_score` | integer or null | | The score of the reading before this one, or null for a first reading. | | `data[].direction` | string or null | `rising`, `steady`, `easing`, `new` | How this reading compares with the one before: `rising`, `steady`, `easing`, or `new` for a first reading. | | `data[].verdict` | string or null | | A short paragraph: what is driving the sector now and what to watch. | | `data[].drivers` | array of objects | | The stories driving the reading, most important first. | | `data[].drivers[].story_id` | integer | | A story id; pass it to GET /stories/{id}. | | `data[].drivers[].label` | string | | The story’s headline. | | `data[].drivers[].why` | string | | One line: why this story moves the sector. | | `data[].stories_read` | integer | | How many stories the reading weighed. | | `data[].open_forecasts` | integer | | Open forecasts in this sector. | | `data[].generated_at` | string (time) or null | | When the reading was made. | ## Errors Every error has the body `{"error": {"code": …, "message": …}}`; branch on `code`. See [Errors](https://docs.alethman.com/errors/) for how to handle each. | Status | Code | When | | --- | --- | --- | | 401 | `unauthenticated` | No Authorization header, or one that is not `Bearer `. 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 - A `quiet` sector had too little reporting in its window to read; its score, level, direction and verdict are null. That is a finding (nothing moved), not an error. - Compare `risk_score` with `previous_score` for the size of a move; `direction` is the word for it. - Readings refresh several times a day. Polling more than once an hour gains nothing. ## From an AI assistant The MCP tool [`list_outlooks`](https://docs.alethman.com/mcp/tools/#list_outlooks) runs this endpoint’s code and returns the same JSON. --- # List forecasts > Dated yes-or-no forecasts in the workspace's sectors, each with its probability, deadline, resolution rule and, once judged, its outcome. Source: https://docs.alethman.com/reference/forecasts/ ```http GET https://dash.alethman.com/api/v1/forecasts ``` - **Scope:** [`intel:read`](https://docs.alethman.com/authentication/#scopes) - **MCP tool:** [`list_forecasts`](https://docs.alethman.com/mcp/tools/#list_forecasts) - **Rate limit:** [120 a minute per key](https://docs.alethman.com/rate-limits/) Dated yes-or-no forecasts in the workspace’s sectors, each with its probability, deadline, resolution rule and, once judged, its outcome. `counts` and `track_record` cover every forecast in those sectors, not only the page returned, so they stay the same whatever `limit` you pass. ## Request | Parameter | In | Type | Default | Values | What it does | | --- | --- | --- | --- | --- | --- | | `sector` | query | string | | [a sector key](https://docs.alethman.com/scopes/#sectors) | Only this sector. It must be one the workspace follows; another sector returns an empty list, not an error. | | `status` | query | string | `all` | `open`, `awaiting`, `resolved`, `all` | `open`: deadline ahead. `awaiting`: deadline passed, verdict not in. `resolved`: judged. `all`: every forecast. | | `limit` | query | integer | `100` | 1 to 200 | How many forecasts to return, 1 to 200. | ## Example **curl** ```bash curl "https://dash.alethman.com/api/v1/forecasts?status=open&limit=20" \ -H "Authorization: Bearer $ALETHMAN_KEY" ``` **Python** ```python import os import requests r = requests.get( "https://dash.alethman.com/api/v1/forecasts", headers={"Authorization": f"Bearer {os.environ['ALETHMAN_KEY']}"}, params={"status": "open", "limit": 20}, timeout=30, ) r.raise_for_status() print(r.json()) ``` **JavaScript** ```js const url = new URL("https://dash.alethman.com/api/v1/forecasts"); url.search = new URLSearchParams({ status: "open", 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 **200 OK**, `application/json`, with the [rate-limit headers](https://docs.alethman.com/rate-limits/). A real response, shortened: long lists are cut to a few items. *200 OK* ```json { "data": [ { "id": 8419, "sector": "energy_power", "question": "Will Cyclone Akvan make landfall on the Andhra Pradesh coast by 21 November 2026?", "probability": 0.65, "made_at": "2026-11-16T15:55:38.996Z", "resolves_by": "2026-11-23T15:55:38.996Z", "resolution_rule": "Yes if IMD or Andhra Pradesh government confirms landfall by the deadline; no if the system weakens or veers away.", "status": "open", "resolved_at": null, "outcome": null, "verdict": null, "rationale": "IMD forecasts intensification and landfall around 20 November, consistent with its track record this season." }, { "id": 9610, "sector": "public_order_unrest", "question": "Will Maharashtra's subordinate court employees call off their indefinite strike by 25 Nov 2026?", "probability": 0.4, "made_at": "2026-11-17T22:24:27.754Z", "resolves_by": "2026-11-24T22:24:27.754Z", "resolution_rule": "Resolves yes if reporting confirms the strike is called off or suspended statewide by the deadline.", "status": "open", "resolved_at": null, "outcome": null, "verdict": null, "rationale": "Pay-parity strikes halting hearings usually draw quick government talks, but indefinite action with no reported negotiation yet suggests it could run longer." }, { "id": 4253, "sector": "energy_power", "question": "Will the World Meteorological Organization confirm El Niño has reached record strength in a formal bulletin by 22 Nov 2026?", "probability": 0.25, "made_at": "2026-10-22T21:54:44.291Z", "resolves_by": "2026-11-21T21:54:44.291Z", "resolution_rule": "Yes if WMO issues an updated bulletin explicitly stating record-strength El Niño conditions have been reached.", "status": "open", "resolved_at": null, "outcome": null, "verdict": null, "rationale": "WMO's 22 Oct statement used conditional language ('may reach'); formal confirmation of record strength typically lags initial warnings by months." } ], "counts": { "open": 90, "due_this_week": 42, "awaiting": 71, "resolved": 351 }, "track_record": { "resolved": 294, "void": 57, "brier_score": 0.22685238095238117 } } ``` ### Fields | Field | Type | Values | What it is | | --- | --- | --- | --- | | `data` | array of objects | | Forecasts, newest first. | | `data[].id` | integer | | The forecast’s id. | | `data[].sector` | string | [a sector key](https://docs.alethman.com/scopes/#sectors) | A sector key. See Countries and scopes for the list. | | `data[].question` | string | | A yes-or-no question with a date in it. | | `data[].probability` | number | 0 to 1 | The probability of yes when the forecast was made, 0 to 1. It is never revised. | | `data[].made_at` | string (time) | | When the forecast was made. | | `data[].resolves_by` | string (time) | | The deadline. | | `data[].resolution_rule` | string | | What counts as yes, written before the outcome was known. | | `data[].status` | string | `open`, `awaiting`, `resolved` | `open`: the deadline is ahead. `awaiting`: the deadline has passed and no verdict is in yet. `resolved`: judged. | | `data[].resolved_at` | string (time) or null | | When it was judged, or null. | | `data[].outcome` | boolean or null | | True if it came true, false if not; null until resolved, or when a resolved forecast was voided. | | `data[].verdict` | string or null | | The judgement in a sentence, with what it rests on, or null. | | `data[].rationale` | string | | Why the probability was set where it was, written when it was made. | | `counts` | object | | Counts over every forecast in the sectors. | | `counts.open` | integer | | Deadline ahead. | | `counts.due_this_week` | integer | | Open, with the deadline in the next 7 days. | | `counts.awaiting` | integer | | Deadline passed, verdict not in. | | `counts.resolved` | integer | | Judged, voided included. | | `track_record` | object | | How the forecasts have done. | | `track_record.resolved` | integer | | Judged true or false. | | `track_record.void` | integer | | Judged but voided: the question could not be settled as asked. | | `track_record.brier_score` | number or null | | The Brier score of the forecasts judged true or false: the mean squared gap between probability and outcome, 0 (perfect) to 1. 0.25 is what always saying 50% earns. Null before any is judged. | ## Errors Every error has the body `{"error": {"code": …, "message": …}}`; branch on `code`. See [Errors](https://docs.alethman.com/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 `. 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 - A probability is fixed when the forecast is made and never revised. A changed view is a new forecast. - `counts` and `track_record` cover every forecast in the workspace’s sectors (or the one `sector` asked for), not just the page returned. - `awaiting` forecasts have passed their deadline and are waiting for a verdict. They move to `resolved` when judged. - A voided forecast is `resolved` with `outcome` null: the question could not be settled as asked. It does not count toward the Brier score. ## From an AI assistant The MCP tool [`list_forecasts`](https://docs.alethman.com/mcp/tools/#list_forecasts) runs this endpoint’s code and returns the same JSON. Its default `limit` differs: The REST default is 100. --- # List coordination findings > Coordination findings touching the workspace's scope (Veritos's campaign view): stories the reporting links into one pattern, each naming who the reporting says runs it, the outlets carrying it hardest and its target, with an evidence grade. Source: https://docs.alethman.com/reference/coordination/ ```http GET https://dash.alethman.com/api/v1/coordination ``` - **Scope:** [`intel:read`](https://docs.alethman.com/authentication/#scopes) - **MCP tool:** [`list_coordination`](https://docs.alethman.com/mcp/tools/#list_coordination) - **Rate limit:** [120 a minute per key](https://docs.alethman.com/rate-limits/) Coordination findings touching the workspace’s scope (Veritos’s campaign view): stories the reporting links into one pattern, each naming who the reporting says runs it, the outlets carrying it hardest and its target, with an evidence grade. `limit` is applied before `grade`, so `grade=A&limit=10` returns the A findings among the latest ten, which may be none. ## Request | Parameter | In | Type | Default | Values | What it does | | --- | --- | --- | --- | --- | --- | | `grade` | query | string | | `A`, `B`, `C` | Only findings of this evidence grade. | | `limit` | query | integer | `30` | 1 to 60 | How many findings to read (before the grade filter) to return, 1 to 60. | ## Example **curl** ```bash curl "https://dash.alethman.com/api/v1/coordination?limit=10" \ -H "Authorization: Bearer $ALETHMAN_KEY" ``` **Python** ```python import os import requests r = requests.get( "https://dash.alethman.com/api/v1/coordination", headers={"Authorization": f"Bearer {os.environ['ALETHMAN_KEY']}"}, params={"limit": 10}, timeout=30, ) r.raise_for_status() print(r.json()) ``` **JavaScript** ```js const url = new URL("https://dash.alethman.com/api/v1/coordination"); url.search = new URLSearchParams({ limit: "10" }); 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 **200 OK**, `application/json`, with the [rate-limit headers](https://docs.alethman.com/rate-limits/). A real response, shortened: long lists are cut to a few items. *200 OK* ```json { "data": [ { "id": 1582, "label": "Idbi bank privatisation fairfax sale strike in Delhi", "pattern": "same_actor", "theme": "idbi-bank-privatisation-fairfax-sale-strike", "grade": "C", "verdict": "Organised by United Forum of IDBI Officers and Employees. Aimed at Government of India. Pushed hardest by Asianet Newsable, Daily Excelsior and Dainik Jagran.", "orchestrator": { "kind": "union", "name": "United Forum of IDBI Officers and Employees", "role": "organiser", "stories": 2, "attribution": "claim_by_actor" }, "orchestrator_allies": [], "mediums": [ { "outlet": "Asianet Newsable", "articles": 1, "stories": 1, "share": 0.083, "lift": null }, { "outlet": "Daily Excelsior", "articles": 1, "stories": 1, "share": 0.083, "lift": null }, { "outlet": "Dainik Jagran", "articles": 1, "stories": 1, "share": 0.083, "lift": null } ], "target": { "kind": "state_agency", "name": "Government of India", "role": "target", "stories": 2, "attribution": "claim_by_actor" }, "statement": "Organised by United Forum of IDBI Officers and Employees. Aimed at Government of India. Pushed hardest by Asianet Newsable, Daily Excelsior and Dainik Jagran. 2 stories in 1 place, 18 Nov to 20 Nov, 10 independent outlets. United Forum of IDBI Officers and Employees: organiser in 2 of 2 (the actor's own claim); Government of India: target in 2 of 2 (the actor's own claim). Grade C.", "what_would_change": "a second place would make this a multi-site pattern; a third story would raise the grade; a wire or press-release origin for the shared reporting would lower it; actor and theme labels are model readings of the text; a hand check of the articles confirms or overturns the link.", "sectors": [ "banking_finance_markets", "public_order_unrest" ], "states": [ "delhi" ], "story_ids": [ 300502, 298063 ], "independent_outlets": 10, "first_seen": "2026-11-18T10:18:00.000Z", "last_seen": "2026-11-19T22:30:58.000Z", "attributed_by_reporting": [ { "name": "United Forum of IDBI Officers and Employees", "kind": "union", "roles": [ "organiser" ], "carried_as": "claim_by_actor" }, { "name": "Government of India", "kind": "state_agency", "roles": [ "target" ], "carried_as": "claim_by_actor" }, { "name": "All India IDBI Officers Association", "kind": "union", "roles": [ "organiser" ], "carried_as": "claim_by_actor" }, { "name": "All India Industrial Development Bank Employees Association", "kind": "union", "roles": [ "organiser" ], "carried_as": "claim_by_actor" } ] }, { "id": 1604, "label": "Sugarcane procurement price dispute in Haryana", "pattern": "called_action", "theme": "sugarcane-procurement-price-dispute", "grade": "C", "verdict": "Organised by Bharatiya Kisan Union (Doaba). Pushed hardest by The Tribune and Hindustan Times.", "orchestrator": { "kind": "organisation", "name": "Bharatiya Kisan Union (Doaba)", "role": "organiser", "stories": 1, "attribution": "reported" }, "orchestrator_allies": [], "mediums": [ { "outlet": "The Tribune", "articles": 4, "stories": 1, "share": 0.5, "lift": null }, { "outlet": "Hindustan Times", "articles": 2, "stories": 1, "share": 0.25, "lift": null } ], "target": null, "statement": "Organised by Bharatiya Kisan Union (Doaba). Pushed hardest by The Tribune and Hindustan Times. 1 story in 1 place, 18 Nov to 21 Nov, 4 independent outlets. Bharatiya Kisan Union (Doaba): organiser in 1 of 1 (plain reporting). Grade C.", "what_would_change": "an official statement or the actor's own claim carried by two or more outlets would raise the grade; a second place would make this a multi-site pattern; a third story would raise the grade; a wire or press-release origin for the shared reporting would lower it; actor and theme labels are model readings of the text; a hand check of the articles confirms or overturns the link.", "sectors": [ "agriculture_food", "public_order_unrest" ], "states": [ "haryana" ], "story_ids": [ 295895 ], "independent_outlets": 4, "first_seen": "2026-11-18T02:11:40.000Z", "last_seen": "2026-11-20T20:29:17.000Z", "attributed_by_reporting": [ { "name": "Sugarcane Growers' Coordination Committee", "kind": "organisation", "roles": [ "organiser" ], "carried_as": "reported" }, { "name": "Swabhimani Shetkari Sanghatana", "kind": "organisation", "roles": [ "organiser" ], "carried_as": "reported" }, { "name": "Bharatiya Kisan Union (Doaba)", "kind": "organisation", "roles": [ "organiser" ], "carried_as": "reported" }, { "name": "Haryana Kisan Mazdoor Sangharsh Morcha", "kind": "organisation", "roles": [ "organiser" ], "carried_as": "reported" } ] } ], "note": "Each finding names its orchestrator, mediums and target from the roles the reporting gives each party; a medium's lift is its share of the finding against its usual share of protest, strike and attack coverage." } ``` ### Fields | Field | Type | Values | What it is | | --- | --- | --- | --- | | `data` | array of objects | | Findings, newest first. | | `data[].id` | integer | | The finding’s id. | | `data[].label` | string | | A short label for the finding. | | `data[].pattern` | string | `same_actor`, `same_theme`, `called_action` | What joins its stories: `same_actor` (the reporting names one party in each), `same_theme` (a shared theme and sector), or `called_action` (one action described as called or multi-site). | | `data[].theme` | string or null | | A slug for the shared theme. | | `data[].grade` | string | `A`, `B`, `C` | The evidence grade, strongest first. `A`: strongest support in the reporting. `B`: a pattern across stories or places. `C`: an early pattern to watch, not yet a finding to rely on. A grade says how much the reporting supports a pattern, not that anyone coordinated it. | | `data[].verdict` | string | | The finding in a sentence or two. | | `data[].orchestrator` | object or null | | The party the reporting names as running it, or null when no one is named. | | `data[].orchestrator.kind` | string | `organisation`, `movement`, `party`, `state_agency`, `armed_group`, `union`, `company`, `public_official`, `public_figure` | What the party is: an organisation, movement, party, state agency, armed group, union, company, public official or public figure. | | `data[].orchestrator.name` | string | | The party’s name as the reporting gives it. | | `data[].orchestrator.role` | string | `organiser`, `claimant`, `blamed`, `accused`, `target`, `responder` | The role the reporting gives it in this finding. | | `data[].orchestrator.stories` | integer | | In how many of the finding’s stories it has that role. | | `data[].orchestrator.attribution` | string | `official_statement`, `claim_by_actor`, `reported`, `alleged_by_opponent`, `speculation` | How the reporting attributes the role, strongest first: `official_statement`, `claim_by_actor` (the party’s own claim), `reported` (plain reporting), `alleged_by_opponent`, `speculation`. | | `data[].orchestrator_allies` | array of objects | | Parties named alongside the orchestrator in the same role. | | `data[].orchestrator_allies[].kind` | string | `organisation`, `movement`, `party`, `state_agency`, `armed_group`, `union`, `company`, `public_official`, `public_figure` | What the party is: an organisation, movement, party, state agency, armed group, union, company, public official or public figure. | | `data[].orchestrator_allies[].name` | string | | The party’s name as the reporting gives it. | | `data[].orchestrator_allies[].role` | string | `organiser`, `claimant`, `blamed`, `accused`, `target`, `responder` | The role the reporting gives it in this finding. | | `data[].orchestrator_allies[].stories` | integer | | In how many of the finding’s stories it has that role. | | `data[].orchestrator_allies[].attribution` | string | `official_statement`, `claim_by_actor`, `reported`, `alleged_by_opponent`, `speculation` | How the reporting attributes the role, strongest first: `official_statement`, `claim_by_actor` (the party’s own claim), `reported` (plain reporting), `alleged_by_opponent`, `speculation`. | | `data[].mediums` | array of objects | | The outlets carrying the finding hardest, most first. | | `data[].mediums[].outlet` | string | | The outlet’s name. | | `data[].mediums[].articles` | integer | | Its articles in the finding. | | `data[].mediums[].stories` | integer | | The finding’s stories it carried. | | `data[].mediums[].share` | number | | Its share of the finding’s articles, 0 to 1. | | `data[].mediums[].lift` | number or null | | Its share of this finding against its usual share of protest, strike and attack coverage: above 1 means it carries this more than usual. Null when there is too little history to compare. | | `data[].target` | object or null | | The party the reporting names as its target, or null. | | `data[].target.kind` | string | `organisation`, `movement`, `party`, `state_agency`, `armed_group`, `union`, `company`, `public_official`, `public_figure` | What the party is: an organisation, movement, party, state agency, armed group, union, company, public official or public figure. | | `data[].target.name` | string | | The party’s name as the reporting gives it. | | `data[].target.role` | string | `organiser`, `claimant`, `blamed`, `accused`, `target`, `responder` | The role the reporting gives it in this finding. | | `data[].target.stories` | integer | | In how many of the finding’s stories it has that role. | | `data[].target.attribution` | string | `official_statement`, `claim_by_actor`, `reported`, `alleged_by_opponent`, `speculation` | How the reporting attributes the role, strongest first: `official_statement`, `claim_by_actor` (the party’s own claim), `reported` (plain reporting), `alleged_by_opponent`, `speculation`. | | `data[].statement` | string | | The full finding as one paragraph, citable as it stands. | | `data[].what_would_change` | string | | What new reporting would raise, lower or overturn the grade. | | `data[].sectors` | array of strings | [a sector key](https://docs.alethman.com/scopes/#sectors) | Sectors its stories touch. | | `data[].states` | array of strings | [a state slug](https://docs.alethman.com/scopes/#states) | States its stories are in. | | `data[].story_ids` | array of integers | | Its stories; pass each to GET /stories/{id}. | | `data[].independent_outlets` | integer | | Independent outlets across its stories. | | `data[].first_seen` | string (time) | | The first article’s time. | | `data[].last_seen` | string (time) | | The latest article’s time. | | `data[].attributed_by_reporting` | array of objects | | Every party the reporting names in the finding’s stories, with how it is attributed. | | `data[].attributed_by_reporting[].name` | string | | The party’s name. | | `data[].attributed_by_reporting[].kind` | string | | What the party is (as Party.kind). | | `data[].attributed_by_reporting[].roles` | array of strings | | The roles the reporting gives it. | | `data[].attributed_by_reporting[].carried_as` | string | `official_statement`, `claim_by_actor`, `reported`, `alleged_by_opponent`, `speculation` | How the reporting attributes the role, strongest first: `official_statement`, `claim_by_actor` (the party’s own claim), `reported` (plain reporting), `alleged_by_opponent`, `speculation`. | | `note` | string | | How to read the parties and lift, in one sentence. | ## Errors Every error has the body `{"error": {"code": …, "message": …}}`; branch on `code`. See [Errors](https://docs.alethman.com/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 `. 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 - `limit` is applied before `grade`: `grade=A&limit=10` returns the A findings among the latest ten. Ask for the maximum (60) when filtering by grade. - A grade is how strongly the reporting supports the pattern, not a claim that anyone coordinated anything. Read `statement` and `what_would_change` with it. - Parties, mediums and targets come from the roles the reporting gives each party. `attributed_by_reporting` shows every party and how it was attributed. - Only events of the kinds that can be organised (protests, strikes, attacks and security operations) are considered. ## From an AI assistant The MCP tool [`list_coordination`](https://docs.alethman.com/mcp/tools/#list_coordination) runs this endpoint’s code and returns the same JSON. Its default `limit` differs: The REST default is 30. --- # List reports > The workspace's compiled reports, newest first. Source: https://docs.alethman.com/reference/reports/ ```http GET https://dash.alethman.com/api/v1/reports ``` - **Scope:** [`reports:read`](https://docs.alethman.com/authentication/#scopes) - **MCP tool:** [`list_reports`](https://docs.alethman.com/mcp/tools/#list_reports) - **Rate limit:** [120 a minute per key](https://docs.alethman.com/rate-limits/) The workspace’s compiled reports, newest first. Page back through older ones with `before`, set to the `created_at` of the last report you have. ## Request | Parameter | In | Type | Default | Values | What it does | | --- | --- | --- | --- | --- | --- | | `limit` | query | integer | `20` | 1 to 100 | How many reports to return, 1 to 100. | | `before` | query | string (time) | | | Only reports compiled before this time, as ISO 8601. | ## Example **curl** ```bash curl "https://dash.alethman.com/api/v1/reports?limit=5" \ -H "Authorization: Bearer $ALETHMAN_KEY" ``` **Python** ```python import os import requests r = requests.get( "https://dash.alethman.com/api/v1/reports", headers={"Authorization": f"Bearer {os.environ['ALETHMAN_KEY']}"}, params={"limit": 5}, timeout=30, ) r.raise_for_status() print(r.json()) ``` **JavaScript** ```js const url = new URL("https://dash.alethman.com/api/v1/reports"); url.search = new URLSearchParams({ limit: "5" }); 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 **200 OK**, `application/json`, with the [rate-limit headers](https://docs.alethman.com/rate-limits/). A real response, shortened: long lists are cut to a few items. *200 OK* ```json { "data": [ { "id": "d35a4dc6-3109-41cf-a2a9-b9a7850ca1d1", "title": "Weekly report, 10 Nov to 17 Nov 2026", "trigger": "scheduled", "period_start": "2026-11-10T03:42:23.800Z", "period_end": "2026-11-17T03:42:23.800Z", "created_at": "2026-11-17T03:42:28.840Z" }, { "id": "e64e8f99-0464-4bf3-a423-189e4041b0ef", "title": "Weekly report, 2 Nov to 9 Nov 2026", "trigger": "scheduled", "period_start": "2026-11-02T03:30:22.932Z", "period_end": "2026-11-09T03:30:22.932Z", "created_at": "2026-11-09T03:30:37.749Z" }, { "id": "bde58b9c-86ae-4e1b-87e1-5a0b204eedf3", "title": "Weekly report, 19 Oct to 26 Oct 2026", "trigger": "scheduled", "period_start": "2026-10-19T03:30:14.125Z", "period_end": "2026-10-26T03:30:14.125Z", "created_at": "2026-10-26T03:30:18.907Z" } ] } ``` ### Fields | Field | Type | Values | What it is | | --- | --- | --- | --- | | `data` | array of objects | | Reports, newest first. | | `data[].id` | string (uuid) | | The report’s id. | | `data[].title` | string | | The report’s title. | | `data[].trigger` | string | `scheduled`, `on_demand` | `scheduled` (the workspace’s report schedule) or `on_demand` (someone asked for it). | | `data[].period_start` | string (time) | | Start of the period it covers. | | `data[].period_end` | string (time) | | End of the period it covers. | | `data[].created_at` | string (time) | | When it was compiled. | ## Errors Every error has the body `{"error": {"code": …, "message": …}}`; branch on `code`. See [Errors](https://docs.alethman.com/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 `. 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 - To page back, pass the `created_at` of the oldest report you have as `before`. - Reports are compiled on the workspace’s schedule (`reports.frequency` on GET /workspace) or when someone asks for one in the dashboard. ## From an AI assistant The MCP tool [`list_reports`](https://docs.alethman.com/mcp/tools/#list_reports) runs this endpoint’s code and returns the same JSON. --- # Get a report > One report, as structured JSON (the default) or as the Markdown the dashboard prints. Source: https://docs.alethman.com/reference/report/ ```http GET https://dash.alethman.com/api/v1/reports/{id} ``` - **Scope:** [`reports:read`](https://docs.alethman.com/authentication/#scopes) - **MCP tool:** [`get_report`](https://docs.alethman.com/mcp/tools/#get_report) - **Rate limit:** [120 a minute per key](https://docs.alethman.com/rate-limits/) One report, as structured JSON (the default) or as the Markdown the dashboard prints. Markdown is the one to read, file or hand to a model; JSON is the one to compute on. ## Request | Parameter | In | Type | Default | Values | What it does | | --- | --- | --- | --- | --- | --- | | `id` **required** | path | string (uuid) | | | The report id, from GET /reports. | | `format` | query | string | `json` | `json`, `markdown` | `json`: the report with its structured content. `markdown`: the report as written, `text/markdown`. | ## Example **curl** ```bash curl "https://dash.alethman.com/api/v1/reports/d35a4dc6-3109-41cf-a2a9-b9a7850ca1d1?format=markdown" \ -H "Authorization: Bearer $ALETHMAN_KEY" ``` **Python** ```python import os import requests r = requests.get( "https://dash.alethman.com/api/v1/reports/d35a4dc6-3109-41cf-a2a9-b9a7850ca1d1", headers={"Authorization": f"Bearer {os.environ['ALETHMAN_KEY']}"}, params={"format": "markdown"}, timeout=30, ) r.raise_for_status() print(r.text) ``` **JavaScript** ```js const url = new URL("https://dash.alethman.com/api/v1/reports/d35a4dc6-3109-41cf-a2a9-b9a7850ca1d1"); url.search = new URLSearchParams({ format: "markdown" }); 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.text()); ``` ## Response **200 OK**, `application/json`, with the [rate-limit headers](https://docs.alethman.com/rate-limits/). A real response, shortened: long lists are cut to a few items. **format=json** *200 OK · application/json* ```json { "id": "d35a4dc6-3109-41cf-a2a9-b9a7850ca1d1", "title": "Weekly report, 10 Nov to 17 Nov 2026", "trigger": "scheduled", "period_start": "2026-11-10T03:42:23.800Z", "period_end": "2026-11-17T03:42:23.800Z", "created_at": "2026-11-17T03:42:28.840Z", "content": { "version": 1, "title": "Weekly report, 10 Nov to 17 Nov 2026", "org": "Risk desk", "period": { "end": "2026-11-17T03:42:23.800Z", "hours": 168, "start": "2026-11-10T03:42:23.800Z" }, "data_through": "2026-11-17T03:41:59.024Z", "generated_at": "2026-11-17T03:42:23.839Z", "judgements": [ { "flag": true, "link": "/sectors/crime_law_enforcement", "text": "Crime and law enforcement reads severe at 80, up 5 from the reading before. Risk is rising on multiple fronts." } ], "memo": { "has": { "stories": true, "readings": true, "coordination": true }, "moves": [ { "href": "/sectors/infrastructure_transport", "name": "Infrastructure and transport", "delta": 18, "score": 58, "sector": "infrastructure_transport", "previous": 40 }, { "href": "/sectors/real_estate_construction", "name": "Real estate and construction", "delta": 8, "score": 17, "sector": "real_estate_construction", "previous": 9 } ] } } } ``` **format=markdown** *200 OK · text/markdown* ```md # Weekly report, 10 Nov to 17 Nov 2026 Risk desk. Period 10 Nov to 17 Nov 2026 (IST). Compiled 17 Nov 2026, 09:12 IST from Alethman's standing readings. Sectors: Textiles and apparel, Metals and mining, Trade, imports and exports, Agriculture and food, Energy and power, Infrastructure and transport, Manufacturing and industry, IT, telecom and technology, Pharma and health, Banking, finance and markets, Real estate and construction, Public order and unrest, Insurgency and terrorism, Crime and law enforcement, Defence, borders and foreign relations, Politics and governance, Environment and disasters, Labour, employment and education, Media and the information space. States: all of India, with national coverage. ## Memo summary **What changed most** (sector readings against the reading before): - Infrastructure and transport: 40 to 58, up 18 - Real estate and construction: 9 to 17, up 8 - Manufacturing and industry: 15 to 22, up 7 … ``` ### Fields | Field | Type | Values | What it is | | --- | --- | --- | --- | | `id` | string (uuid) | | The report’s id. | | `title` | string | | The report’s title. | | `trigger` | string | `scheduled`, `on_demand` | `scheduled` (the workspace’s report schedule) or `on_demand` (someone asked for it). | | `period_start` | string (time) | | Start of the period it covers. | | `period_end` | string (time) | | End of the period it covers. | | `created_at` | string (time) | | When it was compiled. | | `content` | object | | The report’s structured content, as the dashboard renders it. It carries `version` (the content format; fields are added within a version, never renamed), `title`, `org`, `period`, `data_through`, `generated_at`, and one key per section the workspace’s reports include: `judgements`, `memo`, `outlooks`, `stories`, `states`, `forecasts`, `coordination`, `sources`, `products`, `settings`. For a report to read, ask for `format=markdown`. | ## Errors Every error has the body `{"error": {"code": …, "message": …}}`; branch on `code`. See [Errors](https://docs.alethman.com/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 `. 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. | | 404 | `not_found` | No report with that id in this workspace. Message: “No report with that id in this workspace.” | | 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 - `format=markdown` answers `text/markdown; charset=utf-8`, not JSON; errors are still JSON. - `content.version` is the content format. Fields are added within a version and never renamed or removed. - Which sections `content` carries follows the workspace’s report settings, so check for a key before reading it. ## From an AI assistant The MCP tool [`get_report`](https://docs.alethman.com/mcp/tools/#get_report) runs this endpoint’s code and returns the same JSON, with Markdown as its default format. --- # List sources > The feeds the workspace follows on top of Alethman's own coverage (a regulator's press releases, a trade body, a local paper), with each feed's health. Source: https://docs.alethman.com/reference/sources/ ```http GET https://dash.alethman.com/api/v1/sources ``` - **Scope:** [`sources:read`](https://docs.alethman.com/authentication/#scopes) - **MCP tool:** [`list_sources`](https://docs.alethman.com/mcp/tools/#list_sources) - **Rate limit:** [120 a minute per key](https://docs.alethman.com/rate-limits/) The feeds the workspace follows on top of Alethman’s own coverage (a regulator’s press releases, a trade body, a local paper), with each feed’s health. ## Request This endpoint takes no parameters. ## Example **curl** ```bash curl "https://dash.alethman.com/api/v1/sources" \ -H "Authorization: Bearer $ALETHMAN_KEY" ``` **Python** ```python import os import requests r = requests.get( "https://dash.alethman.com/api/v1/sources", headers={"Authorization": f"Bearer {os.environ['ALETHMAN_KEY']}"}, timeout=30, ) r.raise_for_status() print(r.json()) ``` **JavaScript** ```js const url = "https://dash.alethman.com/api/v1/sources"; 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 **200 OK**, `application/json`, with the [rate-limit headers](https://docs.alethman.com/rate-limits/). A real response, shortened: long lists are cut to a few items. *200 OK* ```json { "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": 300, "items_7d": 41, "created_at": "2026-09-30T06:58:18.672Z" } ] } ``` ### Fields | Field | Type | Values | What it is | | --- | --- | --- | --- | | `data` | array of objects | | The workspace’s feeds. | | `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 Every error has the body `{"error": {"code": …, "message": …}}`; branch on `code`. See [Errors](https://docs.alethman.com/errors/) for how to handle each. | Status | Code | When | | --- | --- | --- | | 401 | `unauthenticated` | No Authorization header, or one that is not `Bearer `. 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 - `status: failing` means the last polls failed; `last_error` says why, and polling continues. A feed that recovers goes back to `active` by itself. ## From an AI assistant The MCP tool [`list_sources`](https://docs.alethman.com/mcp/tools/#list_sources) runs this endpoint’s code and returns the same JSON. --- # Add a source > Follow a new feed. Source: https://docs.alethman.com/reference/add-source/ ```http POST https://dash.alethman.com/api/v1/sources ``` - **Scope:** [`sources:write`](https://docs.alethman.com/authentication/#scopes) - **MCP tool:** None (writes are REST only) - **Rate limit:** [120 a minute per key](https://docs.alethman.com/rate-limits/) 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. ## Request This endpoint takes no parameters. ### Body 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* ```json { "url": "https://www.rbi.org.in/pressreleases_rss.xml" } ``` ## Example **curl** ```bash 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"}' ``` **Python** ```python import os import 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()) ``` **JavaScript** ```js 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 **201 Created**, `application/json`, with the [rate-limit headers](https://docs.alethman.com/rate-limits/). A real response, shortened: long lists are cut to a few items. *201 Created* ```json { "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 | 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 Every error has the body `{"error": {"code": …, "message": …}}`; branch on `code`. See [Errors](https://docs.alethman.com/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 `. 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 - 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 Not offered over MCP. Every MCP tool is read-only, so an assistant can read your sources but not change them. --- # Remove a source > Stop following a feed. Source: https://docs.alethman.com/reference/remove-source/ ```http DELETE https://dash.alethman.com/api/v1/sources/{id} ``` - **Scope:** [`sources:write`](https://docs.alethman.com/authentication/#scopes) - **MCP tool:** None (writes are REST only) - **Rate limit:** [120 a minute per key](https://docs.alethman.com/rate-limits/) Stop following a feed. Its stored items go with it. Written to the workspace’s audit log under the key’s name. ## Request | Parameter | In | Type | Default | Values | What it does | | --- | --- | --- | --- | --- | --- | | `id` **required** | path | string (uuid) | | | The source id, from GET /sources. | ## Example **curl** ```bash curl -X DELETE "https://dash.alethman.com/api/v1/sources/34c8efbf-5e0c-4ace-bfeb-816f16bf59df" \ -H "Authorization: Bearer $ALETHMAN_KEY" ``` **Python** ```python import os import requests r = requests.delete( "https://dash.alethman.com/api/v1/sources/34c8efbf-5e0c-4ace-bfeb-816f16bf59df", headers={"Authorization": f"Bearer {os.environ['ALETHMAN_KEY']}"}, timeout=30, ) r.raise_for_status() print("removed" if r.status_code == 204 else r.status_code) ``` **JavaScript** ```js const url = "https://dash.alethman.com/api/v1/sources/34c8efbf-5e0c-4ace-bfeb-816f16bf59df"; const res = await fetch(url, { method: "DELETE", headers: { Authorization: `Bearer ${process.env.ALETHMAN_KEY}`, }, }); if (!res.ok) throw new Error((await res.json()).error.message); console.log("removed"); ``` ## Response **204 No Content.** The source is gone; there is no body. The rate-limit headers are set as on every admitted request. ## Errors Every error has the body `{"error": {"code": …, "message": …}}`; branch on `code`. See [Errors](https://docs.alethman.com/errors/) for how to handle each. | Status | Code | When | | --- | --- | --- | | 401 | `unauthenticated` | No Authorization header, or one that is not `Bearer `. 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. | | 404 | `not_found` | No source with that id in this workspace. Message: “No source with that id in this workspace.” | | 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 - Removing a source deletes the items stored from it. Adding the same feed again starts it fresh. - Every removal is written to the workspace’s audit log with the key’s name. ## 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. --- # List source items > What the workspace's own feeds carried, newest first, each item read for sectors and states like any article. Source: https://docs.alethman.com/reference/source-items/ ```http GET https://dash.alethman.com/api/v1/sources/items ``` - **Scope:** [`sources:read`](https://docs.alethman.com/authentication/#scopes) - **MCP tool:** [`list_source_items`](https://docs.alethman.com/mcp/tools/#list_source_items) - **Rate limit:** [120 a minute per key](https://docs.alethman.com/rate-limits/) What the workspace’s own feeds carried, newest first, each item read for sectors and states like any article. ## 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](https://docs.alethman.com/scopes/#sectors) | 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](https://docs.alethman.com/scopes/#states) | 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 **curl** ```bash curl "https://dash.alethman.com/api/v1/sources/items?since=2026-11-20T00:00:00Z&limit=20" \ -H "Authorization: Bearer $ALETHMAN_KEY" ``` **Python** ```python import os import 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()) ``` **JavaScript** ```js 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 **200 OK**, `application/json`, with the [rate-limit headers](https://docs.alethman.com/rate-limits/). A real response, shortened: long lists are cut to a few items. *200 OK* ```json { "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 | 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](https://docs.alethman.com/scopes/#sectors) | Sectors the item was read as touching. | | `data[].states` | array of strings | [a state slug](https://docs.alethman.com/scopes/#states) | States it is about. | ## Errors Every error has the body `{"error": {"code": …, "message": …}}`; branch on `code`. See [Errors](https://docs.alethman.com/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 `. 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 - Items are read for sectors and states like any article, so `sector` and `state` work here too. - `published_at` is what the feed says and can be null; `fetched_at` is always set. ## From an AI assistant The MCP tool [`list_source_items`](https://docs.alethman.com/mcp/tools/#list_source_items) runs this endpoint’s code and returns the same JSON. Its default `limit` differs: The REST default is 50. --- # Objects > Every object the Alethman API returns, field by field: type, allowed values and meaning. Source: https://docs.alethman.com/reference/objects/ Times are ISO 8601 in UTC. Ids are stable. A field listed here is always present; one that can be empty is marked `or null`. New fields can be added within version 1 ([Versioning](https://docs.alethman.com/versioning/)), so ignore fields you do not know. | Object | Returned by | | --- | --- | | [Signal](https://docs.alethman.com/reference/objects/#signal) | GET /signals | | [Story](https://docs.alethman.com/reference/objects/#story) | GET /stories | | [Story (in full)](https://docs.alethman.com/reference/objects/#story-in-full) | GET /stories/{id} | | [Outlook](https://docs.alethman.com/reference/objects/#outlook) | GET /outlooks | | [Forecast](https://docs.alethman.com/reference/objects/#forecast) | GET /forecasts, and in a story’s `forecasts` | | [Coordination finding](https://docs.alethman.com/reference/objects/#coordination-finding) | GET /coordination | | [Party](https://docs.alethman.com/reference/objects/#party) | a coordination finding’s `orchestrator`, `orchestrator_allies` and `target` | | [Report (in a list)](https://docs.alethman.com/reference/objects/#report-in-a-list) | GET /reports | | [Report](https://docs.alethman.com/reference/objects/#report) | GET /reports/{id} | | [Source](https://docs.alethman.com/reference/objects/#source) | GET /sources and POST /sources | | [Source item](https://docs.alethman.com/reference/objects/#source-item) | GET /sources/items | | [Workspace](https://docs.alethman.com/reference/objects/#workspace) | GET /workspace | | [Error](https://docs.alethman.com/reference/objects/#error) | every error | ## Signal One article in the workspace’s scope. Returned by GET /signals. | Field | Type | Values | What it is | | --- | --- | --- | --- | | `id` | integer | | The article’s id. Stable. | | `title` | string | | The headline as the outlet published it, in its own language. | | `url` | string (url) | | The article’s address on the outlet’s site. | | `published_at` | string (time) | | When the outlet published it (UTC). | | `language` | string or null | | ISO 639-1 code of the headline’s language (`en`, `hi`, `ta` …), or null where it was not detected. | | `outlet` | object | | Who published it. | | `outlet.id` | string | | The outlet’s stable slug. | | `outlet.name` | string | | The outlet’s name. | | `sectors` | array of strings | [a sector key](https://docs.alethman.com/scopes/#sectors) | Sectors the article was read as touching. Can be empty. | | `states` | array of strings | [a state slug](https://docs.alethman.com/scopes/#states) | States and union territories the article is about. Empty when it names none (national or foreign news). | | `story` | object or null | | The story the article was grouped into, or null while it stands alone. | | `story.id` | integer | | The story’s id; pass it to GET /stories/{id}. | | `story.label` | string | | The story’s headline. | | `story.independent_outlets` | integer | | How many independent outlets carry the story. | ## Story Articles about one event, grouped. Returned by GET /stories. | Field | Type | Values | What it is | | --- | --- | --- | --- | | `id` | integer | | The story’s id. Stable: when two stories merge, the old id still answers on GET /stories/{id}. | | `label` | string | | A headline for the story, from its most representative article. | | `independent_outlets` | integer | | Outlets carrying the story independently: syndicated wire copy and copy credited to a news agency count once. | | `articles` | integer | | Every article in the story, syndicated copies included. | | `trajectory` | string or null | `new`, `rising`, `steady`, `decaying` | Where coverage is heading: `new`, `rising`, `steady` or `decaying`. | | `first_seen` | string (time) | | The first article’s publication time. | | `last_seen` | string (time) | | The latest article’s publication time. | | `sectors` | array of strings | [a sector key](https://docs.alethman.com/scopes/#sectors) | Sectors the story touches. | | `states` | array of strings | [a state slug](https://docs.alethman.com/scopes/#states) | States and union territories the story is about. | | `place` | string or null | | The story’s main place (a city, district or state), or null. | | `risk_score` | integer or null | | 0 to 100: how much disruption the reporting describes, read by Alethman. Higher is more severe. Comparable across sectors and over time. | | `risk_level` | string or null | `low`, `guarded`, `elevated`, `high`, `severe` | The band the score falls in: `low`, `guarded`, `elevated`, `high` or `severe`. Use it as the headline; band edges are not published and may be tuned. | | `reading` | string or null | | One sentence: what happened, in plain English whatever the articles’ language. | | `event_type` | string or null | `protest`, `strike_bandh`, `violence_attack`, `security_operation`, `policy_decision`, `court_ruling`, `election_politics`, `economic_indicator`, `corporate_move`, `trade_action`, `disaster_accident`, `crime`, `diplomatic`, `other` | What kind of event the story is. | ## Story (in full) One story in full. Returned by GET /stories/{id}. | Field | Type | Values | What it is | | --- | --- | --- | --- | | `id` | integer | | The story’s current id. Differs from requested\_id when the story you asked for was merged into this one. | | `requested_id` | integer | | The id you asked for. | | `label` | string | | The story’s headline. | | `proposition` | string or null | | The claim at the centre of the coverage, as one sentence outlets can agree or disagree with. | | `independent_outlets` | integer | | Independent outlets carrying it. | | `articles_count` | integer | | Every article in it. | | `trajectory` | string or null | `new`, `rising`, `steady`, `decaying` | Where coverage is heading: `new`, `rising`, `steady` or `decaying`. | | `first_seen` | string (time) | | The first article’s time. | | `last_seen` | string (time) | | The latest article’s time. | | `tag` | object or null | | How Alethman read the story, or null before it is read. | | `tag.sectors` | array of strings | [a sector key](https://docs.alethman.com/scopes/#sectors) | Sectors it touches. | | `tag.event_type` | string or null | `protest`, `strike_bandh`, `violence_attack`, `security_operation`, `policy_decision`, `court_ruling`, `election_politics`, `economic_indicator`, `corporate_move`, `trade_action`, `disaster_accident`, `crime`, `diplomatic`, `other` | What kind of event the story is. | | `tag.theme` | string or null | | A slug for its theme. | | `tag.risk_score` | integer or null | | 0 to 100: how much disruption the reporting describes, read by Alethman. Higher is more severe. Comparable across sectors and over time. | | `tag.risk_level` | string or null | `low`, `guarded`, `elevated`, `high`, `severe` | The band the score falls in: `low`, `guarded`, `elevated`, `high` or `severe`. Use it as the headline; band edges are not published and may be tuned. | | `tag.risk_basis` | string or null | | One sentence: what in the reporting the risk reading rests on. | | `tag.reading` | string or null | | One sentence: what happened. | | `tag.coordinated` | boolean | | True when the story is part of a coordination finding. | | `tag.coordination_basis` | string or null | | Why, when coordinated is true; else null. | | `tag.named_by_reporting` | array of objects | | The parties the reporting names, each with its role and how it is attributed. | | `tag.named_by_reporting[].kind` | string | | What the party is (as Party.kind). | | `tag.named_by_reporting[].name` | string | | The party’s name. | | `tag.named_by_reporting[].role` | string | | Its role (as Party.role). | | `tag.named_by_reporting[].article_ids` | array of integers | | The articles that name it so. | | `tag.named_by_reporting[].attribution` | string | `official_statement`, `claim_by_actor`, `reported`, `alleged_by_opponent`, `speculation` | How the reporting attributes the role, strongest first: `official_statement`, `claim_by_actor` (the party’s own claim), `reported` (plain reporting), `alleged_by_opponent`, `speculation`. | | `summary` | string or null | | A paragraph: what happened, where outlets agree and where they differ. | | `places` | array of objects | | Places the story names. | | `places[].name` | string | | The place’s name. | | `places[].kind` | string | | `city`, `district`, `state` and so on. | | `places[].state` | string or null | | The state it is in. | | `places[].primary` | boolean | | True for the story’s main place. | | `articles` | array of objects | | Every article in the story, newest first. | | `articles[].id` | integer | | The article’s id. | | `articles[].title` | string | | Its headline. | | `articles[].url` | string (url) | | Its address. | | `articles[].outlet` | string | | The outlet’s name. | | `articles[].published_at` | string (time) | | When it was published. | | `articles[].language` | string or null | | Its language. | | `articles[].wire` | string or null | | The news agency it credits (PTI, ANI, Reuters …), or null for the outlet’s own reporting. | | `bloc_finding` | object or null | | How coverage of the proposition divides, or null when not yet read. | | `bloc_finding.statement` | string | | Whether coverage splits into camps, and how. | | `bloc_finding.evidence_grade` | string | `A`, `B`, `C`, `D` | `A` to `D`, strongest first: how clearly coverage splits. `D`: no split. | | `bloc_finding.coordination_likelihood` | string | `low`, `moderate`, `elevated` | `low`, `moderate` or `elevated`: how far the split looks organised rather than ordinary disagreement. | | `bloc_finding.what_would_change` | string | | What new coverage would change the finding. | | `by_country` | array of objects | | The coverage by the home country of its outlets. | | `by_country[].country` | string | | ISO 3166-1 alpha-3 code of the outlets’ home country. | | `by_country[].articles` | integer | | Articles from that country’s outlets. | | `by_country[].voices` | integer | | Independent outlets from that country. | | `by_country[].supports` | integer | | Of those read for stance: outlets that support the proposition. | | `by_country[].opposes` | integer | | Outlets that oppose it. | | `by_country[].neutral` | integer | | Outlets that report it without a side. | | `by_country[].labelled` | integer | | Articles read for stance. | | `by_country[].frame` | string or null | | How that country’s outlets frame the story, in a few words. | | `forecasts` | array of objects | | Forecasts made about this story. | | `forecasts[].id` | integer | | The forecast’s id. | | `forecasts[].sector` | string | [a sector key](https://docs.alethman.com/scopes/#sectors) | A sector key. See Countries and scopes for the list. | | `forecasts[].question` | string | | A yes-or-no question with a date in it. | | `forecasts[].probability` | number | 0 to 1 | The probability of yes when the forecast was made, 0 to 1. It is never revised. | | `forecasts[].made_at` | string (time) | | When the forecast was made. | | `forecasts[].resolves_by` | string (time) | | The deadline. | | `forecasts[].resolution_rule` | string | | What counts as yes, written before the outcome was known. | | `forecasts[].status` | string | `open`, `awaiting`, `resolved` | `open`: the deadline is ahead. `awaiting`: the deadline has passed and no verdict is in yet. `resolved`: judged. | | `forecasts[].resolved_at` | string (time) or null | | When it was judged, or null. | | `forecasts[].outcome` | boolean or null | | True if it came true, false if not; null until resolved, or when a resolved forecast was voided. | | `forecasts[].verdict` | string or null | | The judgement in a sentence, with what it rests on, or null. | | `forecasts[].rationale` | string | | Why the probability was set where it was, written when it was made. | ## Outlook The latest reading for one of the workspace’s sectors. Returned by GET /outlooks. | Field | Type | Values | What it is | | --- | --- | --- | --- | | `sector` | string | [a sector key](https://docs.alethman.com/scopes/#sectors) | A sector key. See Countries and scopes for the list. | | `name` | string | | The sector’s name. | | `quiet` | boolean | | True when the sector had too little reporting in its window to read: the score, level, direction and verdict are then null. | | `risk_score` | integer or null | | 0 to 100: how much disruption the reporting describes, read by Alethman. Higher is more severe. Comparable across sectors and over time. | | `risk_level` | string or null | `low`, `guarded`, `elevated`, `high`, `severe` | The band the score falls in: `low`, `guarded`, `elevated`, `high` or `severe`. Use it as the headline; band edges are not published and may be tuned. | | `previous_score` | integer or null | | The score of the reading before this one, or null for a first reading. | | `direction` | string or null | `rising`, `steady`, `easing`, `new` | How this reading compares with the one before: `rising`, `steady`, `easing`, or `new` for a first reading. | | `verdict` | string or null | | A short paragraph: what is driving the sector now and what to watch. | | `drivers` | array of objects | | The stories driving the reading, most important first. | | `drivers[].story_id` | integer | | A story id; pass it to GET /stories/{id}. | | `drivers[].label` | string | | The story’s headline. | | `drivers[].why` | string | | One line: why this story moves the sector. | | `stories_read` | integer | | How many stories the reading weighed. | | `open_forecasts` | integer | | Open forecasts in this sector. | | `generated_at` | string (time) or null | | When the reading was made. | ## Forecast A dated, checkable forecast. Returned by GET /forecasts, and in a story’s `forecasts`. | Field | Type | Values | What it is | | --- | --- | --- | --- | | `id` | integer | | The forecast’s id. | | `sector` | string | [a sector key](https://docs.alethman.com/scopes/#sectors) | A sector key. See Countries and scopes for the list. | | `question` | string | | A yes-or-no question with a date in it. | | `probability` | number | 0 to 1 | The probability of yes when the forecast was made, 0 to 1. It is never revised. | | `made_at` | string (time) | | When the forecast was made. | | `resolves_by` | string (time) | | The deadline. | | `resolution_rule` | string | | What counts as yes, written before the outcome was known. | | `status` | string | `open`, `awaiting`, `resolved` | `open`: the deadline is ahead. `awaiting`: the deadline has passed and no verdict is in yet. `resolved`: judged. | | `resolved_at` | string (time) or null | | When it was judged, or null. | | `outcome` | boolean or null | | True if it came true, false if not; null until resolved, or when a resolved forecast was voided. | | `verdict` | string or null | | The judgement in a sentence, with what it rests on, or null. | | `rationale` | string | | Why the probability was set where it was, written when it was made. | ## Coordination finding A coordination finding: stories the reporting links into one pattern. Returned by GET /coordination. | Field | Type | Values | What it is | | --- | --- | --- | --- | | `id` | integer | | The finding’s id. | | `label` | string | | A short label for the finding. | | `pattern` | string | `same_actor`, `same_theme`, `called_action` | What joins its stories: `same_actor` (the reporting names one party in each), `same_theme` (a shared theme and sector), or `called_action` (one action described as called or multi-site). | | `theme` | string or null | | A slug for the shared theme. | | `grade` | string | `A`, `B`, `C` | The evidence grade, strongest first. `A`: strongest support in the reporting. `B`: a pattern across stories or places. `C`: an early pattern to watch, not yet a finding to rely on. A grade says how much the reporting supports a pattern, not that anyone coordinated it. | | `verdict` | string | | The finding in a sentence or two. | | `orchestrator` | object or null | | The party the reporting names as running it, or null when no one is named. | | `orchestrator.kind` | string | `organisation`, `movement`, `party`, `state_agency`, `armed_group`, `union`, `company`, `public_official`, `public_figure` | What the party is: an organisation, movement, party, state agency, armed group, union, company, public official or public figure. | | `orchestrator.name` | string | | The party’s name as the reporting gives it. | | `orchestrator.role` | string | `organiser`, `claimant`, `blamed`, `accused`, `target`, `responder` | The role the reporting gives it in this finding. | | `orchestrator.stories` | integer | | In how many of the finding’s stories it has that role. | | `orchestrator.attribution` | string | `official_statement`, `claim_by_actor`, `reported`, `alleged_by_opponent`, `speculation` | How the reporting attributes the role, strongest first: `official_statement`, `claim_by_actor` (the party’s own claim), `reported` (plain reporting), `alleged_by_opponent`, `speculation`. | | `orchestrator_allies` | array of objects | | Parties named alongside the orchestrator in the same role. | | `orchestrator_allies[].kind` | string | `organisation`, `movement`, `party`, `state_agency`, `armed_group`, `union`, `company`, `public_official`, `public_figure` | What the party is: an organisation, movement, party, state agency, armed group, union, company, public official or public figure. | | `orchestrator_allies[].name` | string | | The party’s name as the reporting gives it. | | `orchestrator_allies[].role` | string | `organiser`, `claimant`, `blamed`, `accused`, `target`, `responder` | The role the reporting gives it in this finding. | | `orchestrator_allies[].stories` | integer | | In how many of the finding’s stories it has that role. | | `orchestrator_allies[].attribution` | string | `official_statement`, `claim_by_actor`, `reported`, `alleged_by_opponent`, `speculation` | How the reporting attributes the role, strongest first: `official_statement`, `claim_by_actor` (the party’s own claim), `reported` (plain reporting), `alleged_by_opponent`, `speculation`. | | `mediums` | array of objects | | The outlets carrying the finding hardest, most first. | | `mediums[].outlet` | string | | The outlet’s name. | | `mediums[].articles` | integer | | Its articles in the finding. | | `mediums[].stories` | integer | | The finding’s stories it carried. | | `mediums[].share` | number | | Its share of the finding’s articles, 0 to 1. | | `mediums[].lift` | number or null | | Its share of this finding against its usual share of protest, strike and attack coverage: above 1 means it carries this more than usual. Null when there is too little history to compare. | | `target` | object or null | | The party the reporting names as its target, or null. | | `target.kind` | string | `organisation`, `movement`, `party`, `state_agency`, `armed_group`, `union`, `company`, `public_official`, `public_figure` | What the party is: an organisation, movement, party, state agency, armed group, union, company, public official or public figure. | | `target.name` | string | | The party’s name as the reporting gives it. | | `target.role` | string | `organiser`, `claimant`, `blamed`, `accused`, `target`, `responder` | The role the reporting gives it in this finding. | | `target.stories` | integer | | In how many of the finding’s stories it has that role. | | `target.attribution` | string | `official_statement`, `claim_by_actor`, `reported`, `alleged_by_opponent`, `speculation` | How the reporting attributes the role, strongest first: `official_statement`, `claim_by_actor` (the party’s own claim), `reported` (plain reporting), `alleged_by_opponent`, `speculation`. | | `statement` | string | | The full finding as one paragraph, citable as it stands. | | `what_would_change` | string | | What new reporting would raise, lower or overturn the grade. | | `sectors` | array of strings | [a sector key](https://docs.alethman.com/scopes/#sectors) | Sectors its stories touch. | | `states` | array of strings | [a state slug](https://docs.alethman.com/scopes/#states) | States its stories are in. | | `story_ids` | array of integers | | Its stories; pass each to GET /stories/{id}. | | `independent_outlets` | integer | | Independent outlets across its stories. | | `first_seen` | string (time) | | The first article’s time. | | `last_seen` | string (time) | | The latest article’s time. | | `attributed_by_reporting` | array of objects | | Every party the reporting names in the finding’s stories, with how it is attributed. | | `attributed_by_reporting[].name` | string | | The party’s name. | | `attributed_by_reporting[].kind` | string | | What the party is (as Party.kind). | | `attributed_by_reporting[].roles` | array of strings | | The roles the reporting gives it. | | `attributed_by_reporting[].carried_as` | string | `official_statement`, `claim_by_actor`, `reported`, `alleged_by_opponent`, `speculation` | How the reporting attributes the role, strongest first: `official_statement`, `claim_by_actor` (the party’s own claim), `reported` (plain reporting), `alleged_by_opponent`, `speculation`. | ## Party A party the reporting names, in one role. Returned by a coordination finding’s `orchestrator`, `orchestrator_allies` and `target`. | Field | Type | Values | What it is | | --- | --- | --- | --- | | `kind` | string | `organisation`, `movement`, `party`, `state_agency`, `armed_group`, `union`, `company`, `public_official`, `public_figure` | What the party is: an organisation, movement, party, state agency, armed group, union, company, public official or public figure. | | `name` | string | | The party’s name as the reporting gives it. | | `role` | string | `organiser`, `claimant`, `blamed`, `accused`, `target`, `responder` | The role the reporting gives it in this finding. | | `stories` | integer | | In how many of the finding’s stories it has that role. | | `attribution` | string | `official_statement`, `claim_by_actor`, `reported`, `alleged_by_opponent`, `speculation` | How the reporting attributes the role, strongest first: `official_statement`, `claim_by_actor` (the party’s own claim), `reported` (plain reporting), `alleged_by_opponent`, `speculation`. | ## Report (in a list) A compiled report. Returned by GET /reports. | Field | Type | Values | What it is | | --- | --- | --- | --- | | `id` | string (uuid) | | The report’s id. | | `title` | string | | The report’s title. | | `trigger` | string | `scheduled`, `on_demand` | `scheduled` (the workspace’s report schedule) or `on_demand` (someone asked for it). | | `period_start` | string (time) | | Start of the period it covers. | | `period_end` | string (time) | | End of the period it covers. | | `created_at` | string (time) | | When it was compiled. | ## Report A compiled report with its content. Returned by GET /reports/{id}. | Field | Type | Values | What it is | | --- | --- | --- | --- | | `id` | string (uuid) | | The report’s id. | | `title` | string | | The report’s title. | | `trigger` | string | `scheduled`, `on_demand` | `scheduled` (the workspace’s report schedule) or `on_demand` (someone asked for it). | | `period_start` | string (time) | | Start of the period it covers. | | `period_end` | string (time) | | End of the period it covers. | | `created_at` | string (time) | | When it was compiled. | | `content` | object | | The report’s structured content, as the dashboard renders it. It carries `version` (the content format; fields are added within a version, never renamed), `title`, `org`, `period`, `data_through`, `generated_at`, and one key per section the workspace’s reports include: `judgements`, `memo`, `outlooks`, `stories`, `states`, `forecasts`, `coordination`, `sources`, `products`, `settings`. For a report to read, ask for `format=markdown`. | ## Source A feed the workspace follows, on top of Alethman’s own coverage. Returned by GET /sources and POST /sources. | Field | Type | Values | What it is | | --- | --- | --- | --- | | `id` | string (uuid) | | The source’s id. | | `url` | string (url) | | The feed’s address. | | `site_url` | string or null | | The site the feed belongs to. | | `title` | string | | The feed’s title. | | `kind` | string | `rss`, `atom` | `rss` or `atom`. | | `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. | | `last_polled_at` | string (time) or null | | The last poll, successful or not. | | `last_ok_at` | string (time) or null | | The last successful poll. | | `last_error` | string or null | | Why the last poll failed, or null. | | `items` | integer | | Items stored from this feed. | | `items_7d` | integer | | Items stored in the last 7 days. | | `created_at` | string (time) | | When the workspace started following it. | ## Source item One item a followed feed carried. Returned by GET /sources/items. | Field | Type | Values | What it is | | --- | --- | --- | --- | | `id` | integer | | The item’s id. | | `source` | object | | The feed it came from. | | `source.id` | string (uuid) | | The source’s id. | | `source.title` | string | | The source’s title. | | `title` | string | | The item’s title. | | `url` | string (url) | | The item’s address. | | `summary` | string or null | | The feed’s summary of the item, or null. | | `published_at` | string (time) or null | | When the feed says it was published. | | `fetched_at` | string (time) | | When Alethman read it. | | `sectors` | array of strings | [a sector key](https://docs.alethman.com/scopes/#sectors) | Sectors the item was read as touching. | | `states` | array of strings | [a state slug](https://docs.alethman.com/scopes/#states) | States it is about. | ## Workspace The workspace a key belongs to. Returned by GET /workspace. | Field | Type | Values | What it is | | --- | --- | --- | --- | | `workspace` | object | | | | `workspace.name` | string | | The workspace’s name. | | `workspace.slug` | string | | Its slug. | | `scope` | object | | What the workspace follows. Every endpoint reads through this. | | `scope.sectors` | array of strings | [a sector key](https://docs.alethman.com/scopes/#sectors) | The sectors it follows. Every list in the API stays inside these. | | `scope.states` | array of strings | [a state slug](https://docs.alethman.com/scopes/#states) | The states it follows; empty when it follows all of India. | | `scope.all_india` | boolean | | True when it follows every state. | | `scope.national` | boolean | | True when it also follows national news that names no state. | | `coverage` | array of strings | `signals`, `live`, `stories`, `outlooks`, `forecasts`, `coordination` | The parts of Alethman the workspace has turned on. | | `reports` | object | | Report settings. | | `reports.frequency` | string | `daily`, `weekdays`, `weekly`, `fortnightly`, `monthly`, `on_demand` | How often reports are compiled. | | `reports.depth` | string | `brief`, `standard`, `dossier` | How long each report runs. | | `reports.organise` | string | `sector`, `state`, `risk` | How its stories are grouped. | | `reports.sections` | array of strings | `judgements`, `outlooks`, `stories`, `states`, `forecasts`, `coordination`, `sources` | The sections each report includes. | | `reports.screenshots` | boolean | | True when reports carry screenshots of key articles. | | `reports.next_at` | string (time) or null | | When the next scheduled report is due. | | `alerts` | object | | Alert settings. | | `alerts.threshold` | integer | | The risk score from which alerts fire, set by the workspace (0 to 100). | | `alerts.kinds` | array of strings | `threshold`, `rising`, `coordination`, `forecast`, `report`, `source` | The alert kinds turned on. | | `key` | object | | The key that made the request. | | `key.name` | string | | The name this key was given. | | `key.scopes` | array of strings | `signals:read`, `intel:read`, `reports:read`, `sources:read`, `sources:write` | The scopes this key carries. | ## Error Every error has this body. Returned by every error. | Field | Type | Values | What it is | | --- | --- | --- | --- | | `error` | object | | | | `error.code` | string | `bad_request`, `unauthenticated`, `invalid_key`, `insufficient_scope`, `not_found`, `workspace_not_ready`, `unprocessable`, `rate_limited`, `internal` | A stable, machine-readable code. Branch on this, never on the message. | | `error.message` | string | | One sentence for a person: what was wrong and what to do. | --- # The MCP server > Your workspace as a remote Model Context Protocol server. An AI assistant reads your stories, outlooks, forecasts and reports with eleven read-only tools, under your API key. Source: https://docs.alethman.com/mcp/ Your workspace is also a remote [Model Context Protocol](https://modelcontextprotocol.io) server. An assistant that speaks MCP (Claude Code, Claude Desktop, Cursor and others) can read it for you: ask *“what is driving the energy outlook this week?”* and it calls your workspace’s tools to answer, from your own sectors and states. | | | | --- | --- | | Endpoint | `https://dash.alethman.com/api/mcp` | | Transport | Streamable HTTP, stateless: one JSON-RPC message per POST, one JSON answer. No session, no event stream. | | Authentication | The same API key as the REST API, as `Authorization: Bearer alm_live_…` ([Authentication](https://docs.alethman.com/authentication/)) | | Tools | Eleven, all read-only ([Tools](https://docs.alethman.com/mcp/tools/)) | | Limits | The key’s 120 requests a minute; every MCP message counts as one | | Protocol versions | `2025-06-18`, `2025-03-26`, `2024-11-05` | ## How it fits together Each tool runs the same code as a REST endpoint, under the same scope, and returns that endpoint’s JSON as text. So everything in the [API reference](https://docs.alethman.com/reference/) (fields, limits, errors) holds for the tools too, with two differences made for conversations: - **Smaller default pages.** Where you name no `limit`, a tool asks for fewer items than the endpoint would (25 articles instead of 50, 25 forecasts instead of 100, 10 coordination findings instead of 30). - **Answers that fit.** No result is longer than 40,000 characters. A longer list is cut from the end with a `truncated` note (and, for articles, a cursor to carry on), and a long report is read a page at a time. A key’s scopes decide which tools an assistant sees. Give the assistant’s key `intel:read` alone, and it can read stories, outlooks, forecasts and coordination findings, and nothing else. > **Tip** > > Nothing an assistant does over MCP can change your workspace: every tool is read-only, and adding or removing sources stays with the REST API and the dashboard. ## What an exchange looks like The client opens with `initialize`; the server names itself and tells the assistant how to use the tools: *initialize → result* ```json { "protocolVersion": "2025-06-18", "capabilities": { "tools": { "listChanged": false } }, "serverInfo": { "name": "alethman", "title": "Alethman", "version": "1.0.0" }, "instructions": "Alethman reads the news for this workspace, which follows 19 sectors. Every tool is read-only and returns JSON. Start with get_workspace to see what the workspace follows; list_outlooks for the current reading by sector; list_stories and get_story for events; list_signals for the articles themselves; list_reports and get_report for compiled reports. Ids from one tool feed the next." } ``` Then the assistant calls tools as the conversation needs them: *tools/call* ```json { "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "list_sources", "arguments": {} } } ``` *result* ```json { "jsonrpc": "2.0", "id": 3, "result": { "content": [ { "type": "text", "text": "{\"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-21T05:11:08.842Z\",\"last_ok_at\":\"2026-11-21T05:11:08.842Z\",\"last_error\":null,\"items\":300,\"items_7d\":41,\"created_at\":\"2026-09-30T06:58:18.672Z\"}]}" } ] } } ``` ## What it does not cover yet The tools read the narrative intelligence your workspace runs on: articles, stories, sector outlooks, forecasts, coordination findings (Veritos’s campaign view), reports and your sources. Veritos’s claim checks, Polity and Nostradamus are not offered over MCP or the REST API yet. ## Next - [Connect a client](https://docs.alethman.com/mcp/connect/): Claude Code, Claude Desktop, Cursor, anything else. - [Tools](https://docs.alethman.com/mcp/tools/): every tool’s arguments, defaults and an example. - [Protocol and errors](https://docs.alethman.com/mcp/protocol/): methods, versions, and what each failure looks like. - [Brief yourself from Claude](https://docs.alethman.com/guides/assistant-briefing/): a worked conversation. --- # Connect a client > Add Alethman to Claude Code, Claude Desktop, Cursor or any MCP client, check it works, and fix it when it does not. Source: https://docs.alethman.com/mcp/connect/ You need an API key made under **[Settings › API keys](https://dash.alethman.com/settings/api)** by an owner or admin, with the scopes you want the assistant to have ([Authentication](https://docs.alethman.com/authentication/)). Below, replace `alm_live_YOUR_KEY` with it. > **Caution** > > A key in a client config is a password on disk. Use a key made for the assistant alone, with read scopes only, so you can revoke it without breaking anything else. ## Claude Code ```bash claude mcp add --transport http alethman https://dash.alethman.com/api/mcp \ --header "Authorization: Bearer alm_live_YOUR_KEY" ``` - Add `--scope user` to have Alethman in every project, not only this one. - Inside Claude Code, run `/mcp` to check it is connected and see its tools. - To remove it: `claude mcp remove alethman`. ## Claude Desktop Claude Desktop reaches a remote server that takes a Bearer key through the `mcp-remote` bridge, which needs [Node.js](https://nodejs.org) 18 or later. 1. Open **Settings › Developer › Edit Config**. This opens `claude_desktop_config.json`. 2. Add Alethman under `mcpServers`: *claude\_desktop\_config.json* ```json { "mcpServers": { "alethman": { "command": "npx", "args": [ "-y", "mcp-remote", "https://dash.alethman.com/api/mcp", "--header", "Authorization:${AUTH_HEADER}" ], "env": { "AUTH_HEADER": "Bearer alm_live_YOUR_KEY" } } } } ``` 3. Save and restart Claude Desktop. Alethman’s tools appear under the tools icon in a new chat. The header goes through an environment variable, with **no space after `Authorization:`**, because Claude Desktop on Windows does not escape spaces inside `args`. This form works on every platform. ## Cursor In `~/.cursor/mcp.json` for every project, or `.cursor/mcp.json` in one project: *~/.cursor/mcp.json* ```json { "mcpServers": { "alethman": { "url": "https://dash.alethman.com/api/mcp", "headers": { "Authorization": "Bearer alm_live_YOUR_KEY" } } } } ``` The MCP section of Cursor’s settings shows it as connected, with eleven tools (fewer if the key lacks some scopes). ## Any other client Configure it as a **Streamable HTTP** server: | Setting | Value | | --- | --- | | URL | `https://dash.alethman.com/api/mcp` | | Header | `Authorization: Bearer alm_live_YOUR_KEY` | | Transport | Streamable HTTP (POST); no SSE stream is needed | A client that can only sign in with OAuth and cannot send a custom header cannot use a key directly yet. Where the client can run a local command, use `mcp-remote` as in the Claude Desktop config above. ## Check it with curl You can talk to the server without a client, which is the quickest way to tell a key problem from a client problem: **List the tools** ```bash curl -s https://dash.alethman.com/api/mcp \ -H "Authorization: Bearer $ALETHMAN_KEY" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' ``` **Call one** ```bash curl -s https://dash.alethman.com/api/mcp \ -H "Authorization: Bearer $ALETHMAN_KEY" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_stories","arguments":{"order":"risk","limit":5}}}' ``` ## When it does not connect | What you see | Likely cause | Fix | | --- | --- | --- | | Client says unauthorised, or curl answers 401 | Key mistyped, revoked or expired; or no `Bearer` before it | Check the key under Settings › API keys; in Claude Desktop, check `AUTH_HEADER` starts with `Bearer` . | | Connected, but fewer than eleven tools | The key lacks some scopes | Tools appear only for the key’s scopes. Make a key with the ones you want. | | A tool answers “This key does not carry the … scope” | As above, for that tool | As above. | | 409, “This workspace has not been set up yet” | The workspace’s setup walkthrough is unfinished | An owner or admin finishes it in the dashboard. | | 405 | The client opened a GET event stream | The server is POST only and stateless. Choose Streamable HTTP, not the older SSE transport. | | Claude Desktop shows nothing after restart | Node.js missing, or the JSON does not parse | Run `npx -y mcp-remote --help` in a terminal; validate the config file. | | Answers stop for a minute | The key’s 120 requests a minute are used | Wait for the minute; give the assistant its own key. | --- # MCP tools > The eleven read-only tools the Alethman MCP server offers: arguments, defaults, scopes and an example call for each. Source: https://docs.alethman.com/mcp/tools/ Every tool is read-only (`readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`) and returns JSON as one text block, the same JSON as the REST endpoint it names. `tools/list` shows only the tools the key’s scopes reach. A result is at most 40,000 characters: a list that would run longer is cut from the end and says so in a `truncated` field, with the cursor to carry on where the list pages. | Tool | Title | Scope | Runs | | --- | --- | --- | --- | | [`get_workspace`](https://docs.alethman.com/mcp/tools/#get_workspace) | Workspace | any key | [`GET /workspace`](https://docs.alethman.com/reference/workspace/) | | [`list_signals`](https://docs.alethman.com/mcp/tools/#list_signals) | Articles in scope | `signals:read` | [`GET /signals`](https://docs.alethman.com/reference/signals/) | | [`list_outlooks`](https://docs.alethman.com/mcp/tools/#list_outlooks) | Sector outlooks | `intel:read` | [`GET /outlooks`](https://docs.alethman.com/reference/outlooks/) | | [`list_stories`](https://docs.alethman.com/mcp/tools/#list_stories) | Stories | `intel:read` | [`GET /stories`](https://docs.alethman.com/reference/stories/) | | [`get_story`](https://docs.alethman.com/mcp/tools/#get_story) | One story | `intel:read` | [`GET /stories/{id}`](https://docs.alethman.com/reference/story/) | | [`list_forecasts`](https://docs.alethman.com/mcp/tools/#list_forecasts) | Forecasts | `intel:read` | [`GET /forecasts`](https://docs.alethman.com/reference/forecasts/) | | [`list_coordination`](https://docs.alethman.com/mcp/tools/#list_coordination) | Coordination findings | `intel:read` | [`GET /coordination`](https://docs.alethman.com/reference/coordination/) | | [`list_reports`](https://docs.alethman.com/mcp/tools/#list_reports) | Reports | `reports:read` | [`GET /reports`](https://docs.alethman.com/reference/reports/) | | [`get_report`](https://docs.alethman.com/mcp/tools/#get_report) | One report | `reports:read` | [`GET /reports/{id}`](https://docs.alethman.com/reference/report/) | | [`list_sources`](https://docs.alethman.com/mcp/tools/#list_sources) | Your sources | `sources:read` | [`GET /sources`](https://docs.alethman.com/reference/sources/) | | [`list_source_items`](https://docs.alethman.com/mcp/tools/#list_source_items) | What your sources carried | `sources:read` | [`GET /sources/items`](https://docs.alethman.com/reference/source-items/) | > **Note** > > Assistants decide when to call a tool from its title and description. You can also ask for one by name: “use list\_stories with order risk”. ## `get_workspace` **Workspace** · any key · runs [`GET /workspace`](https://docs.alethman.com/reference/workspace/) The workspace this key belongs to: its name, the sectors and states it follows, coverage, report and alert settings, and the key’s scopes. Assistants call it first to learn what the other tools can return. No arguments. *tools/call* ```json { "jsonrpc": "2.0", "id": 7, "method": "tools/call", "params": { "name": "get_workspace", "arguments": {} } } ``` Try asking: *“What does this workspace follow?”* The result’s text is the JSON documented on [Get the workspace](https://docs.alethman.com/reference/workspace/). ## `list_signals` **Articles in scope** · scope `signals:read` · runs [`GET /signals`](https://docs.alethman.com/reference/signals/) Articles in the workspace’s scope, newest first. Pages with next\_cursor. | Argument | Type | Default | Values | What it does | | --- | --- | --- | --- | --- | | `sector` | string | | [a sector key](https://docs.alethman.com/scopes/#sectors) | One sector key. Results stay inside the workspace’s own sectors. | | `state` | string | | [a state slug](https://docs.alethman.com/scopes/#states) | One state or union territory slug. | | `q` | string | | up to 120 characters | Words to find in the headline. | | `language` | string | | up to 8 characters | ISO 639-1 language code, e.g. en, hi, ta. | | `since` | string (time) | | | Only articles published after this time, as ISO 8601. | | `limit` | integer | `25` | 1 to 200 | How many articles to return. The REST default is 50. | | `cursor` | string | | | next\_cursor from a previous page. | *tools/call* ```json { "jsonrpc": "2.0", "id": 7, "method": "tools/call", "params": { "name": "list_signals", "arguments": { "state": "ladakh", "limit": 5 } } } ``` Try asking: *“Show me the latest five articles about Ladakh.”* The result’s text is the JSON documented on [List articles](https://docs.alethman.com/reference/signals/). ## `list_outlooks` **Sector outlooks** · scope `intel:read` · runs [`GET /outlooks`](https://docs.alethman.com/reference/outlooks/) The latest reading for each followed sector: risk score and level, direction, verdict and the stories driving it. No arguments. *tools/call* ```json { "jsonrpc": "2.0", "id": 7, "method": "tools/call", "params": { "name": "list_outlooks", "arguments": {} } } ``` Try asking: *“Which of my sectors is rising this week, and why?”* The result’s text is the JSON documented on [List sector outlooks](https://docs.alethman.com/reference/outlooks/). ## `list_stories` **Stories** · scope `intel:read` · runs [`GET /stories`](https://docs.alethman.com/reference/stories/) Stories in scope, with independent outlets, risk, place and a one-line reading. | Argument | Type | Default | Values | What it does | | --- | --- | --- | --- | --- | | `sector` | string | | [a sector key](https://docs.alethman.com/scopes/#sectors) | One sector key. Results stay inside the workspace’s own sectors. | | `state` | string | | [a state slug](https://docs.alethman.com/scopes/#states) | One state or union territory slug. | | `hours` | integer | `72` | 1 to 720 | How far back to look, in hours. | | `order` | string | `voices` | `voices`, `risk`, `recent` | voices: most independent outlets first; risk: highest risk first; recent: newest first. | | `limit` | integer | `20` | 1 to 100 | How many stories to return. | *tools/call* ```json { "jsonrpc": "2.0", "id": 7, "method": "tools/call", "params": { "name": "list_stories", "arguments": { "state": "manipur", "order": "risk", "limit": 5 } } } ``` Try asking: *“What are the five riskiest stories in Manipur right now?”* The result’s text is the JSON documented on [List stories](https://docs.alethman.com/reference/stories/). ## `get_story` **One story** · scope `intel:read` · runs [`GET /stories/{id}`](https://docs.alethman.com/reference/story/) One story in full: its reading, summary, places, articles, coverage by country and forecasts. A story outside the workspace’s scope answers not found. | Argument | Type | Default | Values | What it does | | --- | --- | --- | --- | --- | | `id` **required** | integer | | 1 to … | The story id, from list\_stories, list\_signals or an outlook driver. | *tools/call* ```json { "jsonrpc": "2.0", "id": 7, "method": "tools/call", "params": { "name": "get_story", "arguments": { "id": 297641 } } } ``` Try asking: *“Tell me more about story 297641: who reported it and how do outlets differ?”* The result’s text is the JSON documented on [Get a story](https://docs.alethman.com/reference/story/). ## `list_forecasts` **Forecasts** · scope `intel:read` · runs [`GET /forecasts`](https://docs.alethman.com/reference/forecasts/) Forecasts in the workspace’s sectors, with counts and the track record. | Argument | Type | Default | Values | What it does | | --- | --- | --- | --- | --- | | `sector` | string | | [a sector key](https://docs.alethman.com/scopes/#sectors) | One sector key. Results stay inside the workspace’s own sectors. | | `status` | string | `all` | `open`, `awaiting`, `resolved`, `all` | open (unjudged, deadline ahead), awaiting (deadline passed, no verdict yet), resolved, or all. | | `limit` | integer | `25` | 1 to 200 | How many forecasts to return. The REST default is 100. | *tools/call* ```json { "jsonrpc": "2.0", "id": 7, "method": "tools/call", "params": { "name": "list_forecasts", "arguments": { "status": "open", "limit": 10 } } } ``` Try asking: *“Which open forecasts fall due this week?”* The result’s text is the JSON documented on [List forecasts](https://docs.alethman.com/reference/forecasts/). ## `list_coordination` **Coordination findings** · scope `intel:read` · runs [`GET /coordination`](https://docs.alethman.com/reference/coordination/) Coordination findings touching the workspace’s scope, each with its parties, mediums and evidence grade. | Argument | Type | Default | Values | What it does | | --- | --- | --- | --- | --- | | `grade` | string | | `A`, `B`, `C` | Only findings of this evidence grade. | | `limit` | integer | `10` | 1 to 60 | How many findings to read before the grade filter. The REST default is 30. | *tools/call* ```json { "jsonrpc": "2.0", "id": 7, "method": "tools/call", "params": { "name": "list_coordination", "arguments": { "limit": 5 } } } ``` Try asking: *“Is anything in my scope looking organised? Who is behind it?”* The result’s text is the JSON documented on [List coordination findings](https://docs.alethman.com/reference/coordination/). ## `list_reports` **Reports** · scope `reports:read` · runs [`GET /reports`](https://docs.alethman.com/reference/reports/) The workspace’s compiled reports, newest first. | Argument | Type | Default | Values | What it does | | --- | --- | --- | --- | --- | | `limit` | integer | `20` | 1 to 100 | How many reports to return. | | `before` | string (time) | | | Only reports made before this time, as ISO 8601. | *tools/call* ```json { "jsonrpc": "2.0", "id": 7, "method": "tools/call", "params": { "name": "list_reports", "arguments": { "limit": 3 } } } ``` Try asking: *“List my last three reports.”* The result’s text is the JSON documented on [List reports](https://docs.alethman.com/reference/reports/). ## `get_report` **One report** · scope `reports:read` · runs [`GET /reports/{id}`](https://docs.alethman.com/reference/report/) One report. Markdown by default here (the REST default is JSON), in pages of at most 40,000 characters; each page ends with “Page n of m”. | Argument | Type | Default | Values | What it does | | --- | --- | --- | --- | --- | | `id` **required** | string (uuid) | | | The report id, from list\_reports. | | `format` | string | `markdown` | `markdown`, `json` | markdown: the report as written; json: its structured content. | | `page` | integer | `1` | 1 to … | Which page of a long Markdown report to read. | *tools/call* ```json { "jsonrpc": "2.0", "id": 7, "method": "tools/call", "params": { "name": "get_report", "arguments": { "id": "d35a4dc6-3109-41cf-a2a9-b9a7850ca1d1", "page": 1 } } } ``` Try asking: *“Summarise my latest weekly report in five bullets.”* The result’s text is the JSON documented on [Get a report](https://docs.alethman.com/reference/report/) when `format` is `json`, or the report’s Markdown, one page at a time, when it is `markdown`. ## `list_sources` **Your sources** · scope `sources:read` · runs [`GET /sources`](https://docs.alethman.com/reference/sources/) The feeds the workspace follows, with each feed’s health. No arguments. *tools/call* ```json { "jsonrpc": "2.0", "id": 7, "method": "tools/call", "params": { "name": "list_sources", "arguments": {} } } ``` Try asking: *“Are any of my feeds failing?”* The result’s text is the JSON documented on [List sources](https://docs.alethman.com/reference/sources/). ## `list_source_items` **What your sources carried** · scope `sources:read` · runs [`GET /sources/items`](https://docs.alethman.com/reference/source-items/) What the workspace’s own feeds carried, newest first. | Argument | Type | Default | Values | What it does | | --- | --- | --- | --- | --- | | `source` | string (uuid) | | | One source id, from list\_sources. | | `sector` | string | | [a sector key](https://docs.alethman.com/scopes/#sectors) | One sector key. Results stay inside the workspace’s own sectors. | | `state` | string | | [a state slug](https://docs.alethman.com/scopes/#states) | One state or union territory slug. | | `since` | string (time) | | | Only items published after this time, as ISO 8601. | | `q` | string | | up to 120 characters | Words to find in the title. | | `limit` | integer | `25` | 1 to 200 | How many items to return. The REST default is 50. | *tools/call* ```json { "jsonrpc": "2.0", "id": 7, "method": "tools/call", "params": { "name": "list_source_items", "arguments": { "limit": 5 } } } ``` Try asking: *“What did my RBI feed publish today?”* The result’s text is the JSON documented on [List source items](https://docs.alethman.com/reference/source-items/). ## A tool as tools/list describes it The server’s own description of `get_story`, as a client sees it: *tools/list → get\_story* ```json { "name": "get_story", "title": "One story", "description": "One story by id: its tag (sectors, event type, risk and its basis, named parties), summary, places, articles, coverage by country and forecasts. A story outside the workspace's scope answers not found. Same as GET /api/v1/stories/{id}.", "inputSchema": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1, "description": "The story id, from list_stories, list_signals or an outlook driver." } }, "required": [ "id" ], "additionalProperties": false }, "annotations": { "title": "One story", "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } } ``` --- # Protocol and errors > The MCP methods the server answers, version negotiation, how results are sized and paged, and every way a request can fail. Source: https://docs.alethman.com/mcp/protocol/ For people writing their own MCP client, or debugging one. Clients like Claude and Cursor handle all of this for you. ## Transport Streamable HTTP, **stateless**. POST one JSON-RPC 2.0 message to `https://dash.alethman.com/api/mcp` and read one JSON answer (`Content-Type: application/json`). There is no session id and no server-sent event stream, so: - `GET` (which would open a stream) and `DELETE` (which would end a session) answer **405** with `Allow: POST`. - Send `Accept: application/json, text/event-stream` as the transport asks; the answer is always plain JSON. - One message per POST. A JSON-RPC **batch** (an array) answers 400. - A body over **64 KB** answers 413. - A notification, or a response to the server, has no id and answers **202** with no body. ## Versions The server speaks `2025-06-18` (its preference), `2025-03-26` and `2024-11-05`. `initialize` echoes the version the client asks for when it is one of these, and offers `2025-06-18` otherwise. After that, a request whose `MCP-Protocol-Version` header names a version the server does not speak answers 400. ## Methods | Method | Answers | | --- | --- | | `initialize` | `protocolVersion`, `capabilities: { tools: { listChanged: false } }`, `serverInfo` (`alethman`), and `instructions` for the assistant | | `ping` | `{}` | | `tools/list` | The tools the key’s scopes reach ([Tools](https://docs.alethman.com/mcp/tools/)) | | `tools/call` | `{ content: [{ type: "text", text }] }`, with `isError: true` when the tool failed | | `resources/list`, `resources/templates/list`, `prompts/list` | Empty lists, so clients that ask anyway stay quiet | | anything else | JSON-RPC error `-32601`, method not found | The tool list never changes during a connection (`listChanged: false`); it depends only on the key’s scopes. ## Results and their size A tool’s text is the endpoint’s JSON, at most **40,000 characters** (about the most any client accepts in one tool result, even for headlines in Indic scripts). - A **list** that would run longer is cut from the end of its longest list, and gains a field saying so: ```json "truncated": { "list": "data", "returned": 31, "of": 50, "note": "Cut to fit one answer. Ask for fewer with limit, or narrow with a filter, or page on with next_cursor." } ``` For `list_signals`, `next_cursor` then points just after the last article kept, so nothing is skipped. - A **Markdown report** (`get_report`, the default format there) comes in pages, cut at a heading where one falls. Each page but a single one ends like this: *the end of page 1* ```md … --- Page 1 of 3. Call get_report with page: 2 for the next. ``` ## Errors Two kinds, and the difference matters to a client: **Refusals before the message is read** are HTTP errors whose body is a JSON-RPC error with `code: -32001` and the REST API’s status and code in `data`: *HTTP 401* ```json { "jsonrpc": "2.0", "id": null, "error": { "code": -32001, "message": "That key is not valid. It may have been revoked or have expired.", "data": { "status": 401, "code": "invalid_key" } } } ``` | HTTP | `data.code` | Why | | --- | --- | --- | | 401 | `unauthenticated`, `invalid_key` | No key, or a key that is not valid ([Authentication](https://docs.alethman.com/authentication/#when-a-key-is-refused)) | | 403 | `forbidden_origin` | The request carried an `Origin` header from another website. MCP clients that are not browsers send none. | | 409 | `workspace_not_ready` | The workspace has not finished setup | | 429 | `rate_limited` | The key’s 120 a minute, or the bad-key limit; see `Retry-After` | **Malformed messages** answer a JSON-RPC error with the standard codes: `-32700` (not JSON, HTTP 400), `-32600` (not a JSON-RPC 2.0 request, a batch, an unsupported protocol version, or a body over 64 KB with HTTP 413), `-32601` (unknown method), `-32602` (`tools/call` without a known tool `name`, or with `arguments` that are not an object), `-32603` (a failure on Alethman’s side, HTTP 500). **A tool’s own failure** (an argument out of range, a story or report not found, a scope the key lacks) is a normal result with `isError: true` and the reason as text, so the assistant can read it and try again: *tools/call → get\_story with a story outside the workspace* ```json { "jsonrpc": "2.0", "id": 9, "result": { "content": [{ "type": "text", "text": "No story with that id." }], "isError": true } } ``` The messages are the REST API’s, so the [Errors](https://docs.alethman.com/errors/) page applies. --- # Today's stories for a state > A morning brief for one state, built from two endpoints. List the day's stories by how widely they are carried, then read the top ones in full. Source: https://docs.alethman.com/guides/stories-for-a-state/ **You will build:** a script that prints the stories of the last 24 hours in one state, most widely carried first, with a one-line reading for each and the full summary for the top three. **You need:** a key with `intel:read`, and a workspace that follows the state (or all of India). ## 1\. List the day’s stories `GET /stories` with `state`, a 24-hour window and `order=voices` puts the stories most outlets carried independently at the top. That is a good proxy for what matters most today; `order=risk` is the other useful order. ```bash curl "https://dash.alethman.com/api/v1/stories?state=maharashtra&hours=24&order=voices&limit=20" \ -H "Authorization: Bearer $ALETHMAN_KEY" ``` Each story carries `label`, `independent_outlets`, `risk_level`, `place` and `reading`: enough for a one-line brief. ## 2\. Read the top stories in full `GET /stories/{id}` adds the `summary` (where outlets agree and where they differ), every article and the parties the reporting names. ## The whole script **Python** ```python """Morning brief for one state: python brief.py maharashtra""" import os import sys import requests API = "https://dash.alethman.com/api/v1" s = requests.Session() s.headers["Authorization"] = f"Bearer {os.environ['ALETHMAN_KEY']}" def get(path, **params): r = s.get(f"{API}{path}", params=params, timeout=30) if not r.ok: err = r.json()["error"] sys.exit(f"{r.status_code} {err['code']}: {err['message']}") return r.json() state = sys.argv[1] if len(sys.argv) > 1 else "maharashtra" stories = get("/stories", state=state, hours=24, order="voices", limit=20)["data"] if not stories: sys.exit(f"No stories in {state} in the last 24 hours (or the workspace does not follow it).") print(f"{len(stories)} stories in {state}, last 24 hours\n") for st in stories: level = st["risk_level"] or "unread" print(f"[{level:>8}] {st['independent_outlets']:>3} outlets {st['label']}") if st["reading"]: print(f"{'':14}{st['reading']}") print("\nIn full:\n") for st in stories[:3]: full = get(f"/stories/{st['id']}") print(full["label"]) print(full["summary"] or (full["tag"] or {}).get("reading") or "") print(f" {full['articles_count']} articles; first seen {full['first_seen'][:16]} UTC\n") ``` **JavaScript** ```js // Morning brief for one state: node brief.mjs maharashtra const API = "https://dash.alethman.com/api/v1"; const headers = { Authorization: `Bearer ${process.env.ALETHMAN_KEY}` }; async function get(path, params = {}) { const url = new URL(API + path); url.search = new URLSearchParams(params); const res = await fetch(url, { headers }); const body = await res.json(); if (!res.ok) throw new Error(`${res.status} ${body.error.code}: ${body.error.message}`); return body; } const state = process.argv[2] ?? "maharashtra"; const { data: stories } = await get("/stories", { state, hours: "24", order: "voices", limit: "20" }); if (!stories.length) throw new Error(`No stories in ${state} in the last 24 hours.`); console.log(`${stories.length} stories in ${state}, last 24 hours\n`); for (const st of stories) { console.log(`[${(st.risk_level ?? "unread").padStart(8)}] ${String(st.independent_outlets).padStart(3)} outlets ${st.label}`); if (st.reading) console.log(" ".repeat(14) + st.reading); } console.log("\nIn full:\n"); for (const st of stories.slice(0, 3)) { const full = await get(`/stories/${st.id}`); console.log(full.label); console.log(full.summary ?? full.tag?.reading ?? ""); console.log(` ${full.articles_count} articles; first seen ${full.first_seen.slice(0, 16)} UTC\n`); } ``` *Output (shortened)* ```text 14 stories in maharashtra, last 24 hours [ guarded] 13 outlets Massive fire engulfs Pune’s Timber Market; over 50 shops gutted A late-night fire gutted dozens of timber and plywood shops and six houses at Pune's Timber Market in Bhavani Peth; no injuries were reported. … ``` > **Tip** > > Run it from cron at 07:00 IST (`30 1 * * *` in UTC) and pipe it to email or chat. It makes 4 requests, far inside the limit. ## Variations - **Several states:** loop over them, or leave out `state` to cover the whole workspace scope. - **One sector in a state:** add `sector=public_order_unrest`. - **Only what is getting worse:** keep stories whose `trajectory` is `rising` or `new`. - **Where outlets split:** a story’s `bloc_finding.statement` says whether coverage divides into camps ([Get a story](https://docs.alethman.com/reference/story/)). --- # Watch a sector > Post to a chat channel when a sector's outlook turns. Poll the outlooks, compare each reading with the one you saw last, and send the verdict and its drivers. Source: https://docs.alethman.com/guides/watch-a-sector/ **You will build:** a job that runs every hour, reads the sector outlooks, and posts to a Slack (or any webhook) channel when a sector’s risk level changes or its direction turns to `rising`. **You need:** a key with `intel:read`, and a webhook URL for your channel. ## What an outlook gives you [`GET /outlooks`](https://docs.alethman.com/reference/outlooks/) returns one reading per sector your workspace follows: ```json { "sector": "energy_power", "name": "Energy and power", "quiet": false, "risk_score": 48, "risk_level": "elevated", "previous_score": 61, "direction": "easing", "verdict": "No new Hormuz attack or Tarali ruling emerged in the last 24 hours; …", "drivers": [ { "story_id": 300584, "label": "How Hormuz oil shock is India's chance to reset its energy future", "why": "IEA flags Hormuz disruption as a major supply shock with India central to demand growth" } ] } ``` `direction` already compares the reading with the one before, so you could post on `direction == "rising"` alone. Keeping the last level you saw also catches a jump in level that came in two steps between your polls. A `quiet` sector had too little reporting to read: its score, level, direction and verdict are null. Skip it. ## The job **Python** ```python """Post sector turns to a webhook. Run hourly.""" import json import os from pathlib import Path import requests API = "https://dash.alethman.com/api/v1" HOOK = os.environ["WEBHOOK_URL"] SEEN = Path("outlooks-seen.json") WATCH = {"energy_power", "public_order_unrest"} # empty set: every sector r = requests.get(f"{API}/outlooks", headers={"Authorization": f"Bearer {os.environ['ALETHMAN_KEY']}"}, timeout=30) r.raise_for_status() seen = json.loads(SEEN.read_text()) if SEEN.exists() else {} for o in r.json()["data"]: if o["quiet"] or (WATCH and o["sector"] not in WATCH): continue before = seen.get(o["sector"]) turned = before is not None and before != o["risk_level"] if turned or o["direction"] == "rising": drivers = "\n".join(f"• {d['label']}: {d['why']}" for d in o["drivers"][:3]) text = f"*{o['name']}*: {before or '?'} → *{o['risk_level']}* ({o['direction']})\n{o['verdict']}\n{drivers}" requests.post(HOOK, json={"text": text}, timeout=30) seen[o["sector"]] = o["risk_level"] SEEN.write_text(json.dumps(seen)) ``` **JavaScript** ```js // Post sector turns to a webhook. Run hourly. import { existsSync, readFileSync, writeFileSync } from "node:fs"; const API = "https://dash.alethman.com/api/v1"; const SEEN = "outlooks-seen.json"; const WATCH = new Set(["energy_power", "public_order_unrest"]); // empty: every sector const res = await fetch(`${API}/outlooks`, { headers: { Authorization: `Bearer ${process.env.ALETHMAN_KEY}` } }); if (!res.ok) throw new Error((await res.json()).error.message); const seen = existsSync(SEEN) ? JSON.parse(readFileSync(SEEN, "utf8")) : {}; for (const o of (await res.json()).data) { if (o.quiet || (WATCH.size && !WATCH.has(o.sector))) continue; const before = seen[o.sector]; const turned = before !== undefined && before !== o.risk_level; if (turned || o.direction === "rising") { const drivers = o.drivers.slice(0, 3).map((d) => `• ${d.label}: ${d.why}`).join("\n"); const text = `*${o.name}*: ${before ?? "?"} → *${o.risk_level}* (${o.direction})\n${o.verdict}\n${drivers}`; await fetch(process.env.WEBHOOK_URL, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ text }) }); } seen[o.sector] = o.risk_level; } writeFileSync(SEEN, JSON.stringify(seen)); ``` The first run only records what it sees (except sectors already `rising`); after that, it posts on change. > **Tip** > > Outlooks refresh a few times a day, so hourly is enough. The dashboard can also email you when a sector turns, with no code: **Settings › Alerts**. Use the API when the message belongs in your own channel or system. ## Going further - **Link the drivers.** Each driver’s `story_id` opens with [`GET /stories/{id}`](https://docs.alethman.com/reference/story/), or in the dashboard. - **Add the forecasts.** `open_forecasts` counts the sector’s open forecasts; [`GET /forecasts?sector=…&status=open`](https://docs.alethman.com/reference/forecasts/) lists them. - **Watch states as well as sectors.** Poll [`GET /stories?state=…&order=risk&hours=24`](https://docs.alethman.com/reference/stories/) and post stories at `high` or above that you have not posted before (keep their ids). --- # Export forecasts to a spreadsheet > Write every forecast in your sectors to a CSV, with probability, deadline, status and outcome, and compute the track record yourself. Source: https://docs.alethman.com/guides/export-forecasts/ **You will build:** a CSV of every forecast in your workspace’s sectors, one row each, ready for a spreadsheet or BI tool, and a check of the track record against the API’s own figure. **You need:** a key with `intel:read`. ## One request [`GET /forecasts`](https://docs.alethman.com/reference/forecasts/) does not page: `limit=200` with `status=all` returns up to the 200 most recent. Ask per sector if you need more than that. ```bash curl "https://dash.alethman.com/api/v1/forecasts?status=all&limit=200" \ -H "Authorization: Bearer $ALETHMAN_KEY" ``` Beside `data`, the response carries `counts` and `track_record`. Both cover every forecast in your sectors, not only the page returned: ```json { "counts": { "open": 90, "due_this_week": 42, "awaiting": 71, "resolved": 351 }, "track_record": { "resolved": 294, "void": 57, "brier_score": 0.22685238095238117 } } ``` ## The export **Python** ```python """forecasts.csv: every forecast in the workspace's sectors.""" import csv import os import requests API = "https://dash.alethman.com/api/v1" s = requests.Session() s.headers["Authorization"] = f"Bearer {os.environ['ALETHMAN_KEY']}" sectors = s.get(f"{API}/workspace", timeout=30).json()["scope"]["sectors"] rows = {} for sector in sectors: r = s.get(f"{API}/forecasts", params={"sector": sector, "status": "all", "limit": 200}, timeout=30) r.raise_for_status() for f in r.json()["data"]: rows[f["id"]] = f cols = ["id", "sector", "question", "probability", "made_at", "resolves_by", "status", "outcome", "resolved_at", "resolution_rule", "verdict"] with open("forecasts.csv", "w", newline="", encoding="utf-8") as out: w = csv.DictWriter(out, fieldnames=cols, extrasaction="ignore") w.writeheader() w.writerows(sorted(rows.values(), key=lambda f: f["made_at"], reverse=True)) judged = [f for f in rows.values() if f["outcome"] is not None] if judged: brier = sum((f["probability"] - f["outcome"]) ** 2 for f in judged) / len(judged) print(f"{len(rows)} forecasts, {len(judged)} judged, Brier {brier:.3f}") ``` **JavaScript** ```js // forecasts.csv: every forecast in the workspace's sectors. import { writeFileSync } from "node:fs"; const API = "https://dash.alethman.com/api/v1"; const headers = { Authorization: `Bearer ${process.env.ALETHMAN_KEY}` }; const get = async (path) => { const res = await fetch(API + path, { headers }); if (!res.ok) throw new Error((await res.json()).error.message); return res.json(); }; const ws = await get("/workspace"); const rows = new Map(); for (const sector of ws.scope.sectors) { const { data } = await get(`/forecasts?${new URLSearchParams({ sector, status: "all", limit: "200" })}`); for (const f of data) rows.set(f.id, f); } const cols = ["id", "sector", "question", "probability", "made_at", "resolves_by", "status", "outcome", "resolved_at", "resolution_rule", "verdict"]; const cell = (v) => (v == null ? "" : /[",\n]/.test(String(v)) ? `"${String(v).replaceAll('"', '""')}"` : String(v)); const sorted = [...rows.values()].sort((a, b) => b.made_at.localeCompare(a.made_at)); writeFileSync("forecasts.csv", [cols.join(","), ...sorted.map((f) => cols.map((c) => cell(f[c])).join(","))].join("\n")); const judged = sorted.filter((f) => f.outcome !== null); const brier = judged.reduce((s, f) => s + (f.probability - Number(f.outcome)) ** 2, 0) / judged.length; console.log(`${rows.size} forecasts, ${judged.length} judged, Brier ${brier.toFixed(3)}`); ``` ## Reading the columns | Column | Notes | | --- | --- | | `probability` | 0 to 1, the chance given when the forecast was made. It never changes afterwards. | | `resolves_by` | The deadline. A forecast past it with no verdict has `status` `awaiting`. | | `outcome` | `true` came true, `false` did not, empty until judged. A resolved forecast with an empty outcome was **voided**: the question could not be settled as asked. | | `resolution_rule` | What counts as yes, written when the forecast was made. | > **Note** > > Your Brier score from the export can differ slightly from `track_record.brier_score` if a sector holds more than 200 forecasts, since the export then misses the oldest. The API’s figure always covers every judged forecast. ## Keeping it fresh Forecasts are made and judged daily. Rerun the export daily and replace the file; rows are keyed by `id`, and a forecast’s `status`, `outcome`, `resolved_at` and `verdict` fill in when it is judged. --- # Follow your own feed > Add an RSS or Atom feed to your workspace, check it is polling, and read its items with the sectors and states Alethman read them as touching. Source: https://docs.alethman.com/guides/follow-a-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 ``; Alethman finds the feed itself. ```bash 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: ```json { "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`](https://docs.alethman.com/reference/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`](https://docs.alethman.com/reference/source-items/) returns items from all your feeds, newest first. Narrow with `source`, `sector`, `state`, `q` or `since`: ```bash curl "https://dash.alethman.com/api/v1/sources/items?source=34c8efbf-5e0c-4ace-bfeb-816f16bf59df&limit=5" \ -H "Authorization: Bearer $ALETHMAN_KEY" ``` ```json { "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": [] } ] } ``` ## Polling for new items `/sources/items` has no cursor. Poll with `since` set to the newest `published_at` you hold, and keep item `id`s to drop any you have already seen: **Python** ```python 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) ``` **JavaScript** ```js const API = "https://dash.alethman.com/api/v1"; const headers = { Authorization: `Bearer ${process.env.ALETHMAN_KEY}` }; let since = "2026-11-21T00:00:00Z"; const seen = new Set(); for (;;) { const res = await fetch(`${API}/sources/items?${new URLSearchParams({ since, limit: "200" })}`, { headers }); const { data } = await res.json(); for (const it of [...data].reverse()) { if (seen.has(it.id)) continue; seen.add(it.id); console.log(it.published_at.slice(0, 16), it.source.title, "·", it.title); } if (data.length) since = data[0].published_at; await new Promise((r) => setTimeout(r, 600_000)); } ``` Each feed is read every 20 minutes, so polling the API every 10 to 20 minutes misses nothing. ## Limits and refusals | 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](https://docs.alethman.com/reference/add-source/#errors). ## Removing a feed ```bash 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. > **Note** > > Over MCP, assistants can read your feeds (`list_sources`, `list_source_items`) but never add or remove one. --- # Brief yourself from Claude > Questions to ask an AI assistant connected to your workspace, the tools it calls for each, and how to get answers that cite stories and reports instead of guessing. Source: https://docs.alethman.com/guides/assistant-briefing/ **You will need:** Alethman connected to Claude Code, Claude Desktop, Cursor or another MCP client ([Connect a client](https://docs.alethman.com/mcp/connect/)), on a key with `intel:read` and `reports:read`. Once connected, you ask in plain words and the assistant picks the tools. Knowing which tool answers which question helps you ask well and check what it did. Every client shows the tool calls it makes; open them to see exactly what it read. ## A morning brief > What’s moving in my workspace since yesterday? Start with the sectors, then the three stories carried most widely, and tell me where outlets disagree. The assistant usually calls: 1. `get_workspace`, to learn your sectors and states. 2. `list_outlooks`, for each sector’s level, direction and verdict. 3. `list_stories` with `hours: 24` and `order: "voices"`. 4. `get_story` for the top three, whose `summary` and `bloc_finding` say where coverage agrees and where it divides. ## One sector, in depth > Why is the energy outlook where it is? Which stories drive it, and what forecasts are open? `list_outlooks` gives the verdict and its `drivers` (each with a `story_id`); `get_story` opens each driver; `list_forecasts` with `sector: "energy_power"` and `status: "open"` lists the dated forecasts with their probabilities and deadlines. ## A state > Summarise the last three days in Maharashtra, highest risk first. Leave out anything carried by fewer than five outlets. `list_stories` with `state: "maharashtra"`, `hours: 72`, `order: "risk"`; the assistant filters on `independent_outlets` itself. ## Reading a report > Read me the latest weekly report’s judgements and anything it says about public order. `list_reports`, then `get_report` with the newest id. Reports come as Markdown a page at a time; the assistant asks for `page: 2` and on as it needs them. Each page ends with “Page n of m”. ## Coordination > Are there any grade A coordination findings among the latest 60? Who does the reporting name as orchestrating them, and through which outlets? `list_coordination` with `grade: "A"` and `limit: 60`. The limit is applied before the grade filter, so with the default of 10 the tool looks at the latest ten findings only; asking for 60 makes it look further back. Each finding names its `orchestrator`, the `mediums` carrying it hardest and a `target`, from the roles the reporting gives each party, with the stories it rests on. A grade says how much the reporting supports a pattern, not that anyone coordinated it. ## The articles themselves > Find this week’s articles mentioning “Tarali” and list the outlets that ran them. `list_signals` with `q: "Tarali"` and `since` a week back. It returns 25 articles at a time; the assistant pages on with `next_cursor` if you ask for more. ## Getting good answers - **Ask for sources.** “Cite the story ids” or “link each claim to a story” makes the assistant say which `get_story` result each sentence came from. Story ids open in the dashboard too. - **Name the window.** “Since yesterday”, “this week”, “the last 72 hours” become `hours` or `since`. Without one, `list_stories` reads 72 hours. - **Name the order.** “Most widely carried” is `order: "voices"`; “most serious” is `order: "risk"`; “latest” is `order: "recent"`. - **Keep lists short.** A tool result is capped at 40,000 characters. If a result says `truncated`, ask for fewer, or narrow by sector or state. - **It reads only your workspace.** Stories outside your sectors and states are invisible to it, as they are to the API. > **Caution** > > The assistant reports what your workspace’s data says; it can still misread a long result or overstate a finding. For anything you will act on, open the story or report it cites. ## Saving a prompt In Claude Code, save a brief you run every morning as a slash command: put the prompt in `.claude/commands/brief.md` and run `/brief`. In Claude Desktop, keep it in a Project’s instructions. --- # Glossary > The words the API and these docs use, in alphabetical order, each with what it means and where it appears. Source: https://docs.alethman.com/glossary/ **API key.** A secret starting `alm_live_` that identifies a workspace and carries scopes. Sent as `Authorization: Bearer …`. Shown once when made. See [Authentication](https://docs.alethman.com/authentication/). **Article.** One piece of reporting from one outlet, read and tagged with sectors and states. The API calls the list of articles *signals* ([`GET /signals`](https://docs.alethman.com/reference/signals/)). **Attribution.** How the reporting attributes a role to a party, strongest first: `official_statement`, `claim_by_actor` (the party’s own claim), `reported`, `alleged_by_opponent`, `speculation`. A finding that rests on speculation is weaker than one that rests on official statements. **Bloc finding.** How coverage of a story’s proposition divides into camps of outlets, with an evidence grade from `A` (a clear split) to `D` (no split) and a coordination likelihood (`low`, `moderate`, `elevated`). On [`GET /stories/{id}`](https://docs.alethman.com/reference/story/) as `bloc_finding`. **Brier score.** How good a set of probability forecasts has been: the mean squared gap between the probability given and what happened (1 or 0). 0 is perfect; 0.25 is what always saying 50% earns. On [`GET /forecasts`](https://docs.alethman.com/reference/forecasts/) as `track_record.brier_score`. **Coordination finding.** A pattern that joins several stories: the same party named in each (`same_actor`), a shared theme and sector (`same_theme`), or one action described as called or multi-site (`called_action`). It names who the reporting says runs it (the orchestrator), the outlets carrying it hardest (the mediums) and its target. Part of Veritos. See [`GET /coordination`](https://docs.alethman.com/reference/coordination/). **Cursor.** An opaque string that marks a place in a list, returned as `next_cursor` and passed back as `cursor`. See [Pagination](https://docs.alethman.com/pagination/). **Direction.** How an outlook compares with the reading before it: `rising`, `steady`, `easing`, or `new` for a first reading. **Driver.** A story an outlook names as moving the sector, with a line on why. On [`GET /outlooks`](https://docs.alethman.com/reference/outlooks/) as `drivers`. **Event type.** What kind of event a story reports (a protest, an attack, a policy decision and so on). An open list: new values can appear ([Versioning](https://docs.alethman.com/versioning/)). **Evidence grade.** How much the reporting supports a coordination finding: `A` strongest, `B` a pattern across stories or places, `C` an early pattern to watch. A grade says how strongly the reporting supports a pattern, not that anyone coordinated it. **Forecast.** A dated yes-or-no question with a probability, a deadline (`resolves_by`) and a rule for what counts as yes, written before the outcome is known. `open` until its deadline, then `awaiting` a verdict, then `resolved`. Made by Nostradamus. **Independent outlets.** How many outlets carry a story on their own reporting. Syndicated wire copy, and copy credited to a news agency, count once, so a story run by fifty papers from one agency wire counts as one voice. The API’s `order=voices` sorts by it. **Lift.** For a medium in a coordination finding: its share of the finding’s articles against its usual share of protest, strike and attack coverage. Above 1, the outlet carries this pattern more than usual. Null when there is too little history to compare. **MCP (Model Context Protocol).** An open protocol that lets AI assistants call tools. Alethman’s MCP server exposes the API as eleven read-only tools. See [The MCP server](https://docs.alethman.com/mcp/). **Narrative intelligence.** What Alethman does: reads the news across outlets and languages, groups it into stories, and reports which narratives are moving, how risky they are, who the reporting says is behind them and how coverage divides. **Nostradamus.** Alethman’s view that joins a client’s own records from separate systems into the organisations, facilities and items they share. Not offered over the API yet. **Orchestrator.** The party a coordination finding’s reporting names as running it, or none when no one is named. Named from the reporting, never inferred. **Outlook.** The current reading of one sector: a risk score and level, its direction, a verdict paragraph and the stories driving it. Refreshed several times a day. See [`GET /outlooks`](https://docs.alethman.com/reference/outlooks/). **Party.** An organisation, movement, political party, state agency, armed group, union, company, public official or public figure named by the reporting, in a role: `organiser`, `claimant`, `blamed`, `accused`, `target` or `responder`. **Polity.** Alethman’s view of public spending and procurement. Not offered over the API yet. **Proposition.** The claim at the centre of a story’s coverage, as one sentence outlets can agree or disagree with. Bloc findings are read against it. **Quiet.** An outlook with too little reporting in its window to read. Its score, level, direction and verdict are null. **Report.** A compiled document for the workspace, scheduled (`scheduled`) or asked for (`on_demand`), covering a period, in Markdown or as structured JSON. See [`GET /reports`](https://docs.alethman.com/reference/reports/). **Risk level.** The band a risk score falls in: `low`, `guarded`, `elevated`, `high`, `severe`. Use it as the headline. The band edges are not published and may be tuned. **Risk score.** 0 to 100: how much disruption the reporting describes, read by Alethman. Higher is more severe, and scores compare across sectors and over time. A story says in words what its reading rests on (`risk_basis`). **Scope (of a key).** A permission a key carries: `signals:read`, `intel:read`, `reports:read`, `sources:read`, `sources:write`. See [Authentication](https://docs.alethman.com/authentication/#scopes). **Scope (of a workspace).** The sectors and states a workspace follows. Every list in the API stays inside it. See [Countries and scopes](https://docs.alethman.com/scopes/). **Sector.** One of nineteen areas a workspace can follow, such as `energy_power` or `public_order_unrest`. The full list is on [Countries and scopes](https://docs.alethman.com/scopes/#sectors). **Source.** A feed of your own (RSS or Atom) your workspace follows, beside the outlets Alethman reads for everyone. See [Follow your own feed](https://docs.alethman.com/guides/follow-a-feed/). **State.** One of India’s 36 states and union territories, by slug (`maharashtra`, `jammu-and-kashmir`). The full list is on [Countries and scopes](https://docs.alethman.com/scopes/#states). **Story.** Articles from many outlets grouped as reporting on one event or development, with a headline (`label`), its places, its trajectory and Alethman’s reading of it. See [`GET /stories`](https://docs.alethman.com/reference/stories/). **Trajectory.** Where a story’s coverage is heading: `new`, `rising`, `steady` or `decaying`. **Veritos.** Alethman’s verification view: how claims and campaigns move through coverage. Its coordination findings are on [`GET /coordination`](https://docs.alethman.com/reference/coordination/); its claim checks are not offered over the API yet. **Workspace.** One organisation’s Alethman: its sectors and states, its people, its keys, its reports and alerts. Every key belongs to one. See [`GET /workspace`](https://docs.alethman.com/reference/workspace/).