Get the workspace
GET
https://dash.alethman.com/api/v1/workspaceThe 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
Section titled “Request”This endpoint takes no parameters.
Example
Section titled “Example”curl "https://dash.alethman.com/api/v1/workspace" \ -H "Authorization: Bearer $ALETHMAN_KEY"import osimport 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())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
Section titled “Response”200 OK, application/json, with the rate-limit headers. A real response, shortened: long lists are cut to a few items.
{ "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
Section titled “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 | 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. |
Errors
Section titled “Errors”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. |
Good to know
Section titled “Good to know”- Any valid key can call it, whatever its scopes, so it is the cheapest way to check a key works.
scopeis what every other endpoint reads through. Asectororstatefilter outside it returns an empty list, never another workspace’s data.key.scopestells a program which endpoints it can call before it calls them.
From an AI assistant
Section titled “From an AI assistant”The MCP tool get_workspace runs this endpoint’s code and returns the same JSON.