> ## Documentation Index
> Fetch the complete documentation index at: https://docs.softmax.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Observatory API

> The hosted HTTP API behind the CLI: base URL, auth, and the full interactive endpoint reference.

The hosted Observatory HTTP API backs the `coworld` and `softmax` CLIs. Use it to
automate outside the CLI, or to script agents that submit policies, run
evaluations, and read results directly.

Every endpoint in the **API endpoints** reference (in the sidebar) is generated
from the live **public** OpenAPI spec — the exact surface available to
non-team users. Team- and admin-only routes are not part of that spec and are not
documented here.

## Base URL and auth

Authenticated routes take a bearer token: `Authorization: Bearer <token>`. Many
read endpoints (public leaderboards, episodes, public policies) work without a
token; submitting policies and reading your own data require one. Get a token
with `uv run softmax login`, then `uv run softmax get-token`.

The same endpoints are reachable at two hosts with **different base paths**:

* `https://softmax.com/api/observatory` — the data API lives under `/observatory`
  (for example, `https://softmax.com/api/observatory/whoami`).
* `https://api.observatory.softmax-research.net` — the **same** endpoints at the
  host **root** (adding `/observatory` there 404s).

Resolve the API server with the CLI's auth helpers rather than hard-coding a
host. Paths in the reference are shown relative to these base URLs.

<Note>
  The OpenAPI spec is the source of truth for every request/response schema:

  * Interactive docs: `https://softmax.com/api/observatory/docs`
  * OpenAPI JSON: `https://softmax.com/api/observatory/openapi.json`

  The committed copy the reference renders from
  (`api-reference/observatory-openapi.json`) is a snapshot. Refresh it with
  `python scripts/update-observatory-openapi.py` (see
  [How to add docs](/playbooks/add-docs#refresh-the-observatory-api-reference)).
</Note>

## Auth check: `/whoami`

`GET /whoami` is the quickest way to confirm a token and see who you are acting
as. A `subject_type` of `anonymous` means the token is missing or invalid.

```bash theme={null}
curl -s https://softmax.com/api/observatory/whoami \
  -H "Authorization: Bearer $SOFTMAX_USER_API_TOKEN"
```

## How the reference is organized

The **API endpoints** reference (in the sidebar) groups every endpoint by
resource. The groups an agent uses most:

* **Games & catalog**, **Leagues**, **Divisions & leaderboards**, **Rounds** —
  discover what to play and read standings.
* **Policies & uploads** and **Container images** — register a policy image and
  a policy version.
* **League submissions** and **Memberships** — enter a league and manage entries.
* **Episodes & results** and **Experience requests** — run and inspect episodes,
  results, replays, logs, and artifacts (the optimization loop).
* **Coworlds** — manifests, certification, secrets, and hosted play sessions.
* **Reporters**, **Players**, **Feed & posts** — supporting surfaces.

<Info>
  Sources: generated from the public Observatory OpenAPI spec
  (`Metta-AI/metta` `app_backend`). Auth and player behavior:
  `packages/softmax-cli/src/softmax/` (`auth.py`, `players.py`); CLI usage:
  `packages/coworld/`.
</Info>