Skip to content

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

Every object the API returns, field by field, is on Objects.