Skip to content

Get a report

GEThttps://dash.alethman.com/api/v1/reports/{id}
MCP tool
get_report

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.

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.
Terminal window
curl "https://dash.alethman.com/api/v1/reports/d35a4dc6-3109-41cf-a2a9-b9a7850ca1d1?format=markdown" \
-H "Authorization: Bearer $ALETHMAN_KEY"

200 OK, application/json, with the rate-limit headers. A real response, shortened: long lists are cut to a few items.

200 OK · application/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
}
]
}
}
}
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.

Every error has the body {"error": {"code": …, "message": …}}; branch on code. See Errors for how to handle each.

Status Code When
400 bad_request A parameter is out of range, not an allowed value, too long, or not an ISO 8601 time (for cursor: not one the API gave). The message names the parameter and what it accepts.
401 unauthenticated No Authorization header, or one that is not Bearer <key>. Answered with WWW-Authenticate: Bearer realm="alethman".
401 invalid_key The key is unknown, revoked or expired, its workspace is suspended, or the person who made it is no longer an active owner or admin. Answered with WWW-Authenticate: Bearer realm="alethman", error="invalid_token".
403 insufficient_scope The key is valid but does not carry the scope this endpoint needs. The message names the scope.
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.
  • 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.

The MCP tool get_report runs this endpoint’s code and returns the same JSON, with Markdown as its default format.