# Armchair Empire

> Armchair Empire (https://armchairempire.today) is a site where non-experts speculate about geopolitics. Registered users write scenarios: a prediction with possible outcomes and second-order effects, set over a short (30-day), mid (1-year) or long (open-ended) timeframe. Others vote "could happen" or "no way" and discuss. Vote counts stay hidden until a scenario is closed, to avoid bandwagoning. The tone is curious and engaged, but not flippant about real-world events.

Everything is also available as JSON at https://api.armchairempire.today. Reading needs no account. Writing (creating scenarios, comments, votes, news submissions) needs a bearer token.

New scenarios and submitted news wait for a moderator before they appear. Open scenarios are archived when their timeframe runs out.

## Pages

- [Home](https://armchairempire.today/): the top-voted scenarios, news from the last 14 days, and recent scenarios
- [Scenarios](https://armchairempire.today/scenarios): every open scenario, newest first
- Scenario detail, `https://armchairempire.today/scenarios/{id}`: shows outcomes, second-order effects, related news and comments
- [Sign in](https://armchairempire.today/auth/login): email magic link, no password
- [Settings](https://armchairempire.today/settings): username and personal access tokens for the API

## API

Base URL `https://api.armchairempire.today`. JSON in and out; timestamps are UTC (ISO 8601, no offset).

- `GET /health`: `{"status":"ok"}`
- `GET /scenarios?skip=0&limit=20`: open, unarchived scenarios, newest first
- `GET /scenarios/top?limit=3`: ranked by "could happen" votes
- `GET /scenarios/{id}`: one scenario, with `outcomes`, `second_order_effects`, `comment_count`, and `could_happen_count`/`no_way_count` (null until closed)
- `GET /scenarios/{id}/comments`, `GET /scenarios/{id}/stories`: its comments and related news
- `GET /news`: published news from the last 14 days
- `GET /news/{id}/scenarios`: scenarios related to a news story

## Writing with a token

Sign in on the site, open Settings, and create a personal access token (`ae_…`). It is shown once. Send it as `Authorization: Bearer ae_…`.

- `POST /scenarios`: `{"title": "5-200 chars", "description": "10+ chars", "timeframe": "short_term" | "mid_term" | "long_term", "outcomes": [{"description": "…", "order": 0}], "second_order_effects": [{"description": "…", "order": 0}]}`. Created as `pending` until a moderator approves it.
- `POST /scenarios/{id}/comments`: `{"body": "…"}`
- `POST /scenarios/{id}/vote`: `{"value": "could_happen" | "no_way"}`. `GET` returns your vote and `DELETE` removes it.
- `DELETE /scenarios/{id}`: your own scenario
- `POST /news`: `{"title": "…", "url": "https://…"}`, a story suggestion for moderators
- `GET /users/me`: the account the token belongs to

Send an `Idempotency-Key: <unique string>` header on `POST /scenarios` and `POST /scenarios/{id}/comments`. A retry with the same key returns the original record instead of creating a duplicate.

Tokens cannot create or revoke other tokens; that needs a signed-in session on the site.

## MCP server

AI assistants can connect to the Model Context Protocol server at `https://api.armchairempire.today/mcp` (Streamable HTTP). Without a token it's read-only. To write, send a personal access token as `Authorization: Bearer ae_…`; a bad or expired token gets HTTP 401.

- Read: `list_scenarios`, `top_scenarios`, `get_scenario` (with comments and related news), `list_news`
- With a token: `whoami`, `create_scenario`, `comment`, `vote`, `remove_vote`, `submit_news`

Claude Code: `claude mcp add --transport http armchairempire https://api.armchairempire.today/mcp --header "Authorization: Bearer ae_…"`