API reference
Base URL: https://dash.alethman.com/api/v1. Every request sends a key as Authorization: Bearer alm_live_… (Authentication), every response is JSON unless asked for Markdown, and every list reads through the workspace’s scope (Countries and scopes).
The whole API is also an OpenAPI 3.1 document: import it into Postman, Insomnia or a client generator.
| Method | Path | What it returns | Scope | MCP tool |
|---|---|---|---|---|
| GET | /workspace |
Get the workspace | any key | get_workspace |
| GET | /signals |
List articles | signals:read |
list_signals |
| GET | /stories |
List stories | intel:read |
list_stories |
| GET | /stories/{id} |
Get a story | intel:read |
get_story |
| GET | /outlooks |
List sector outlooks | intel:read |
list_outlooks |
| GET | /forecasts |
List forecasts | intel:read |
list_forecasts |
| GET | /coordination |
List coordination findings | intel:read |
list_coordination |
| GET | /reports |
List reports | reports:read |
list_reports |
| GET | /reports/{id} |
Get a report | reports:read |
get_report |
| GET | /sources |
List sources | sources:read |
list_sources |
| POST | /sources |
Add a source | sources:write |
none |
| DELETE | /sources/{id} |
Remove a source | sources:write |
none |
| GET | /sources/items |
List source items | sources:read |
list_source_items |
Workspace
Section titled “Workspace”- Get the 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
Section titled “Signals”- List articles ·
GET /signals: Articles in the workspace’s scope, newest first, each with its outlet, sectors, states and the story it was grouped into.
Stories
Section titled “Stories”- List 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 ·
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
Section titled “Outlooks”- List sector 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
Section titled “Forecasts”- List 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
Section titled “Coordination”- List coordination findings ·
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
Section titled “Reports”- List reports ·
GET /reports: The workspace’s compiled reports, newest first. - Get a report ·
GET /reports/{id}: One report, as structured JSON (the default) or as the Markdown the dashboard prints.
Sources
Section titled “Sources”- List 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 ·
POST /sources: Follow a new feed. - Remove a source ·
DELETE /sources/{id}: Stop following a feed. - List 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
Section titled “Objects”Every object the API returns, field by field, is on Objects.