Skip to main content
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.
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).

​
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.

​
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.
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/.