Skip to content

Get the workspace

GEThttps://dash.alethman.com/api/v1/workspace
Scope
Any valid key

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.

This endpoint takes no parameters.

Terminal window
curl "https://dash.alethman.com/api/v1/workspace" \
-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
{
"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"
]
}
}
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 The sectors it follows. Every list in the API stays inside these.
scope.states array of strings a state slug 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.

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

Status Code When
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".
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.
  • 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.

The MCP tool get_workspace runs this endpoint’s code and returns the same JSON.