# Alethman Docs > The Alethman API and MCP server: read a workspace's narrative intelligence (articles, stories, sector outlooks, forecasts, coordination findings, reports and its own sources) from code or from an AI assistant. REST base URL: https://dash.alethman.com/api/v1 (Bearer API key, `alm_live_…`). MCP server: https://dash.alethman.com/api/mcp (Streamable HTTP, same key). Machine-readable spec: https://docs.alethman.com/openapi.json. Every page below is also plain Markdown at the linked .md address; all of them in one file: https://docs.alethman.com/llms-full.txt. ## Start here - [Alethman API and MCP](https://docs.alethman.com/index.md): Read your workspace's narrative intelligence from your own tools and AI assistants. The API and the MCP server, documented end to end. - [Quickstart](https://docs.alethman.com/quickstart.md): Make a key, check it, find the riskiest stories in your scope and read one in full, in about five minutes. - [Authentication and keys](https://docs.alethman.com/authentication.md): Every request carries a workspace API key as a Bearer token. Who can make keys, what scopes do, expiry, rotation and why a key is refused. - [Countries and scopes](https://docs.alethman.com/scopes.md): What a workspace follows bounds everything the API returns. The sector keys and state slugs every filter takes, national news, and which country the API reads. ## How the API behaves - [Pagination](https://docs.alethman.com/pagination.md): How each list endpoint pages: cursors for articles, before for reports, windows and limits for the rest, and how to keep a mirror in sync. - [Errors](https://docs.alethman.com/errors.md): One error shape for every failure, a stable code to branch on, every status the API can answer, and which errors to retry. - [Rate limits](https://docs.alethman.com/rate-limits.md): 120 requests a minute per key, the headers that count it down, what a 429 looks like, and the two smaller limits on bad keys and new sources. - [Versioning](https://docs.alethman.com/versioning.md): The API is version 1. What can change without notice (additions), what never changes within a version, and how a breaking change would arrive. - [Changelog](https://docs.alethman.com/changelog.md): Every change to the Alethman API and MCP server, newest first. Additions within v1 are listed as they ship. ## API reference - [API reference](https://docs.alethman.com/reference.md): Every endpoint of the Alethman API, the scope each needs and the MCP tool that runs it. - [Get the workspace](https://docs.alethman.com/reference/workspace.md): 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](https://docs.alethman.com/reference/signals.md): Articles in the workspace's scope, newest first, each with its outlet, sectors, states and the story it was grouped into. - [List stories](https://docs.alethman.com/reference/stories.md): 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](https://docs.alethman.com/reference/story.md): 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](https://docs.alethman.com/reference/outlooks.md): 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](https://docs.alethman.com/reference/forecasts.md): 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](https://docs.alethman.com/reference/coordination.md): 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](https://docs.alethman.com/reference/reports.md): The workspace's compiled reports, newest first. - [Get a report](https://docs.alethman.com/reference/report.md): One report, as structured JSON (the default) or as the Markdown the dashboard prints. - [List sources](https://docs.alethman.com/reference/sources.md): 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](https://docs.alethman.com/reference/add-source.md): Follow a new feed. - [Remove a source](https://docs.alethman.com/reference/remove-source.md): Stop following a feed. - [List source items](https://docs.alethman.com/reference/source-items.md): What the workspace's own feeds carried, newest first, each item read for sectors and states like any article. - [Objects](https://docs.alethman.com/reference/objects.md): Every object the Alethman API returns, field by field: type, allowed values and meaning. ## MCP server - [The MCP server](https://docs.alethman.com/mcp.md): Your workspace as a remote Model Context Protocol server. An AI assistant reads your stories, outlooks, forecasts and reports with eleven read-only tools, under your API key. - [Connect a client](https://docs.alethman.com/mcp/connect.md): Add Alethman to Claude Code, Claude Desktop, Cursor or any MCP client, check it works, and fix it when it does not. - [MCP tools](https://docs.alethman.com/mcp/tools.md): The eleven read-only tools the Alethman MCP server offers: arguments, defaults, scopes and an example call for each. - [Protocol and errors](https://docs.alethman.com/mcp/protocol.md): The MCP methods the server answers, version negotiation, how results are sized and paged, and every way a request can fail. ## Guides - [Today's stories for a state](https://docs.alethman.com/guides/stories-for-a-state.md): A morning brief for one state, built from two endpoints. List the day's stories by how widely they are carried, then read the top ones in full. - [Watch a sector](https://docs.alethman.com/guides/watch-a-sector.md): Post to a chat channel when a sector's outlook turns. Poll the outlooks, compare each reading with the one you saw last, and send the verdict and its drivers. - [Export forecasts to a spreadsheet](https://docs.alethman.com/guides/export-forecasts.md): Write every forecast in your sectors to a CSV, with probability, deadline, status and outcome, and compute the track record yourself. - [Follow your own feed](https://docs.alethman.com/guides/follow-a-feed.md): Add an RSS or Atom feed to your workspace, check it is polling, and read its items with the sectors and states Alethman read them as touching. - [Brief yourself from Claude](https://docs.alethman.com/guides/assistant-briefing.md): Questions to ask an AI assistant connected to your workspace, the tools it calls for each, and how to get answers that cite stories and reports instead of guessing. ## More - [Glossary](https://docs.alethman.com/glossary.md): The words the API and these docs use, in alphabetical order, each with what it means and where it appears.