Skip to content

Quickstart

This walk-through takes you from no key to reading a story in full. Every response below is real, shortened where a list runs long.

You need a seat in an Alethman workspace as an owner or admin (only they can make keys), and a terminal. The examples use curl; every step has Python and JavaScript too.

  1. In the dashboard, open Settings › API keys and fill in Make a key:

    • Name: what will use it, e.g. Risk desk ingest. It shows in the key list and in the workspace’s audit log.
    • Scopes: leave the four read scopes ticked. sources:write is only for programs that add or remove feeds.
    • Expires: 90 days is the default; 30 days, a year or never are the other choices.

    The key is shown once. Copy it and keep it in your secret store, then put it in your shell for this walk-through:

    Terminal window
    export ALETHMAN_KEY="alm_live_…"
  2. GET /workspace answers for any valid key and tells you what the workspace follows, which is what every other endpoint reads through.

    Terminal window
    curl https://dash.alethman.com/api/v1/workspace \
    -H "Authorization: Bearer $ALETHMAN_KEY"
    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"
    ]
    }
    }

    scope.sectors and scope.states bound every list you will read. key.scopes says what this key may call. A 401 here means the key was mistyped, revoked or expired (Authentication).

  3. GET /stories groups articles into events. Order by risk to see the most disruptive first; independent_outlets tells you how widely each is carried.

    Terminal window
    curl "https://dash.alethman.com/api/v1/stories?order=risk&hours=48&limit=5" \
    -H "Authorization: Bearer $ALETHMAN_KEY"
    200 OK (two of five)
    {
    "data": [
    {
    "id": 301791,
    "label": "Manipur Spurious Liquor Tragedy: Death Toll Rises To 11, Over 180 Hospitalised",
    "independent_outlets": 24,
    "articles": 41,
    "trajectory": "steady",
    "first_seen": "2026-11-19T13:45:01.000Z",
    "last_seen": "2026-11-21T04:27:58.000Z",
    "sectors": [
    "public_order_unrest",
    "agriculture_food"
    ],
    "states": [
    "manipur"
    ],
    "place": "Chandel",
    "risk_score": 72,
    "risk_level": "high",
    "reading": "Suspected methanol-laced local liquor in Chandel district, Manipur, has killed at least 11 to 15 people and hospitalised more than 150.",
    "event_type": "disaster_accident"
    },
    {
    "id": 297641,
    "label": "EPFO approves systematic PF withdrawal plan",
    "independent_outlets": 35,
    "articles": 89,
    "trajectory": "steady",
    "first_seen": "2026-11-18T22:24:07.000Z",
    "last_seen": "2026-11-21T03:51:15.000Z",
    "sectors": [
    "banking_finance_markets",
    "politics_governance"
    ],
    "states": [
    "delhi"
    ],
    "place": "Delhi",
    "risk_score": 12,
    "risk_level": "low",
    "reading": "The EPFO board approved reforms easing PF withdrawals, including a systematic withdrawal plan, lower minimum balance and limited alternative fund investment.",
    "event_type": "policy_decision"
    }
    ]
    }
  4. Take an id from the list. GET /stories/{id} gives the reading, a summary, every article, the parties the reporting names and how coverage divides.

    Terminal window
    curl https://dash.alethman.com/api/v1/stories/297641 \
    -H "Authorization: Bearer $ALETHMAN_KEY"
    200 OK (shortened)
    {
    "id": 297641,
    "requested_id": 297641,
    "label": "EPFO approves systematic PF withdrawal plan",
    "independent_outlets": 35,
    "articles_count": 89,
    "trajectory": "steady",
    "tag": {
    "sectors": [
    "banking_finance_markets",
    "politics_governance"
    ],
    "event_type": "policy_decision",
    "risk_level": "low",
    "reading": "The EPFO board approved reforms easing PF withdrawals, including a systematic withdrawal plan, lower minimum balance and limited alternative fund investment."
    },
    "summary": "The EPFO's Central Board of Trustees met in New Delhi on 19 November 2026 and approved a Systematic Withdrawal Plan letting retiring members draw their provident fund savings in monthly, quarterly or annual instalments while the remainder keeps earning EPF interest. The board also cut the minimum balance to be retained during partial withdrawals from 25% to 10% and restored a two-month wait for final settlement after job loss, down from 12 months; it did not raise the EPS pension. These changes take effect only after formal notification. Nobody disputes the decisions. Where outlets differ is in emphasis: The Times of India, DNA India, Prameya News and The Economic Times present the plan as a clear gain in retirement income and security, while Hindustan Times, India Today, Business Today and others focus on the larger share of savings members can now withdraw. No report so far says when the rules will be notified, and none carries criticism of the plan.",
    "…": "places, articles, bloc_finding, by_country, forecasts"
    }

    Every field is documented on Get a story.

  5. GET /signals is every article in scope, newest first. Lists that page return next_cursor; pass it back as cursor until it is null.

    Terminal window
    curl "https://dash.alethman.com/api/v1/signals?limit=4" \
    -H "Authorization: Bearer $ALETHMAN_KEY"
    # then, with the next_cursor it returned:
    curl "https://dash.alethman.com/api/v1/signals?limit=4&cursor=MjAyNi0xMS0yMVQwNDo0NjoyNi4wMDBafDEzODYyNjk0OA" \
    -H "Authorization: Bearer $ALETHMAN_KEY"
    200 OK (one of four)
    {
    "data": [
    {
    "id": 138695177,
    "title": "Jammu Kashmir High Court Quashes Withdrawal of NOC for Four Tourist Huts in Pahalgam",
    "url": "https://kashmirlife.net/jammu-kashmir-high-court-quashes-withdrawal-of-noc-for-four-tourist-huts-in-pahalgam-462123/",
    "published_at": "2026-11-21T05:01:37.000Z",
    "language": null,
    "outlet": {
    "id": "kashmir-life",
    "name": "Kashmir Life"
    },
    "sectors": [
    "politics_governance"
    ],
    "states": [],
    "story": null
    }
    ],
    "next_cursor": "MjAyNi0xMS0yMVQwNDo0NjoyNi4wMDBafDEzODYyNjk0OA"
    }