Quickstart

This walks through submitting a run end to end. You will need a writer API key — one with the runs:write scope. Locally you can mint one with the CLI; in production keys are managed in your deployment provider.

1. Run the stack locally

From the repository root, bring the API and web stack up. make demo creates a run, uploads artifacts, and seeds the leaderboard flow end to end.

make setup
make demo

The API serves at http://localhost:8000 (interactive docs at /docs) and the web app at http://localhost:3000.

2. Mint a writer API key

.venv/bin/python -m worldmodel_server.cli create-api-key \
  --name local-writer \
  --scope runs:write

3. Create a run

Send a JSON body with env, agent, and track. Authenticate with the x-api-key header. The response carries the generated run id.

curl -sS -X POST http://localhost:8000/api/runs \
  -H "content-type: application/json" \
  -H "x-api-key: $WMG_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"env": "memory_maze", "agent": "imagination_mpc", "track": "test"}'

{
  "id": "a1b2c3d4e5f6",
  "env": "memory_maze",
  "agent": "imagination_mpc",
  "track": "test",
  "status": "created",
  "metrics": {},
  "created_at": "2026-06-25T00:00:00Z",
  "updated_at": "2026-06-25T00:00:00Z"
}

4. Upload artifacts

Upload is multipart/form-data with up to three file fields. Only metrics_file is required; trace_file and config_file are optional.

curl -sS -X POST http://localhost:8000/api/runs/$RUN_ID/upload \
  -H "x-api-key: $WMG_API_KEY" \
  -F "metrics_file=@metrics.json" \
  -F "trace_file=@trace.jsonl" \
  -F "config_file=@config.json"

Your run now appears on the leaderboard for its track. See Submitting runs for idempotency, versioning, and the /api/v1 surface.