HTTP API

The EZVals server exposes a REST API that powers the web UI. You can use these endpoints to build custom interfaces or integrations.

Data Endpoints

GET /results

Get current run results with aggregated statistics. Response:

{
  "session_name": "my-session",
  "run_name": "baseline",
  "run_id": "1704067200",
  "total_evaluations": 10,
  "total_errors": 1,
  "total_passed": 8,
  "average_latency": 0.45,
  "eval_path": "evals/",
  "results": [...],
  "score_chips": [
    {"key": "accuracy", "type": "ratio", "passed": 8, "total": 10},
    {"key": "latency", "type": "avg", "avg": 0.95, "count": 10}
  ]
}

`GET /api/runs/{run_id}/results/{index}`

Get a single result by index.

run_id: Run ID or "latest"
index: 0-based result index

Response:

{
  "result": {...},
  "index": 0,
  "total": 10,
  "run_id": "1704067200",
  "session_name": "my-session",
  "run_name": "baseline",
  "eval_path": "evals/"
}

Run Management

POST /api/runs/rerun

Rerun evaluations. Omit indices to rerun all. Request:

{
  "indices": [0, 2, 5]
}

Response:

{"ok": true, "run_id": "1704067200"}

POST /api/runs/new

Create a new run. Request:

{
  "run_name": "my-run"
}

Response:

{"ok": true, "run_id": "1704067200", "run_name": "my-run"}

POST /api/runs/stop

Stop all running/pending evaluations. Response:

{"ok": true}

`PATCH /api/runs/{run_id}`

Rename a run. Request:

{
  "run_name": "new-name"
}

Response:

{"ok": true, "run": {"run_id": "1704067200", "run_name": "new-name"}}

`DELETE /api/runs/{run_id}`

Delete a run. Response:

{"ok": true}

Result Updates

`PATCH /api/runs/{run_id}/results/{index}`

Update annotations or scores on a result. Request:

{
  "result": {
    "annotation": "Reviewed - looks good",
    "scores": [{"key": "manual", "passed": true}]
  }
}

Response:

{"ok": true, "result": {...}}

Only annotation, annotations, and scores fields can be updated.

Export

`GET /api/runs/{run_id}/export/json`

Download run results as JSON file.

`GET /api/runs/{run_id}/export/csv`

Download run results as CSV file.

`POST /api/runs/{run_id}/export/markdown`

Generate a Markdown report with ASCII bar charts and filtered results table. Request:

{
  "visible_indices": [0, 2, 5],
  "visible_columns": ["eval", "dataset", "input", "output", "scores"],
  "stats": {
    "total": 10,
    "filtered": 3,
    "avgLatency": 0.45,
    "chips": [
      {"key": "accuracy", "type": "ratio", "passed": 8, "total": 10},
      {"key": "latency", "type": "avg", "avg": 0.95, "count": 10}
    ]
  },
  "run_name": "baseline",
  "session_name": "my-session"
}

Response: Markdown file download

Sessions

GET /api/sessions

List all session names. Response:

{
  "sessions": ["model-comparison", "regression-tests"]
}

`GET /api/sessions/{session_name}/runs`

List all runs in a session. Response:

{
  "session_name": "model-comparison",
  "runs": [
    {
      "run_id": "1704067200",
      "run_name": "baseline",
      "total_evaluations": 10,
      "total_passed": 8,
      "total_errors": 1,
      "timestamp": 1704067200
    }
  ]
}

`DELETE /api/sessions/{session_name}`

Delete a session and all its runs. Response:

{"ok": true}

`POST /api/runs/{run_id}/activate`

Switch the active run being viewed. Response:

{"ok": true}

`GET /api/runs/{run_id}/data`

Get run data without changing the active run. Used for comparison mode. Response: Same structure as GET /results but for the specified run.

Configuration

GET /api/config

Get current configuration. Response:

{
  "concurrency": 4,
  "verbose": false,
  "timeout": 30.0
}

PUT /api/config

Update configuration. Request:

{
  "concurrency": 8,
  "timeout": 60.0
}

Response:

{"ok": true, "config": {...}}

Getting Started

Examples

Core Concepts

Guides

API Reference

Resources

Data Endpoints

GET /results

`GET /api/runs/{run_id}/results/{index}`

Run Management

POST /api/runs/rerun

POST /api/runs/new

POST /api/runs/stop

`PATCH /api/runs/{run_id}`

`DELETE /api/runs/{run_id}`

Result Updates

`PATCH /api/runs/{run_id}/results/{index}`

Export

`GET /api/runs/{run_id}/export/json`

`GET /api/runs/{run_id}/export/csv`

`POST /api/runs/{run_id}/export/markdown`

Sessions

GET /api/sessions

`GET /api/sessions/{session_name}/runs`

`DELETE /api/sessions/{session_name}`

`POST /api/runs/{run_id}/activate`

`GET /api/runs/{run_id}/data`

Configuration

GET /api/config

PUT /api/config

​Data Endpoints

​GET /results

​GET /api/runs/{run_id}/results/{index}

​Run Management

​POST /api/runs/rerun

​POST /api/runs/new

​POST /api/runs/stop

​PATCH /api/runs/{run_id}

​DELETE /api/runs/{run_id}

​Result Updates

​PATCH /api/runs/{run_id}/results/{index}

​Export

​GET /api/runs/{run_id}/export/json

​GET /api/runs/{run_id}/export/csv

​POST /api/runs/{run_id}/export/markdown

​Sessions

​GET /api/sessions

​GET /api/sessions/{session_name}/runs

​DELETE /api/sessions/{session_name}

​POST /api/runs/{run_id}/activate

​GET /api/runs/{run_id}/data

​Configuration

​GET /api/config

​PUT /api/config

Data Endpoints

GET /results

`GET /api/runs/{run_id}/results/{index}`

Run Management

POST /api/runs/rerun

POST /api/runs/new

POST /api/runs/stop

`PATCH /api/runs/{run_id}`

`DELETE /api/runs/{run_id}`

Result Updates

`PATCH /api/runs/{run_id}/results/{index}`

Export

`GET /api/runs/{run_id}/export/json`

`GET /api/runs/{run_id}/export/csv`

`POST /api/runs/{run_id}/export/markdown`

Sessions

GET /api/sessions

`GET /api/sessions/{session_name}/runs`

`DELETE /api/sessions/{session_name}`

`POST /api/runs/{run_id}/activate`

`GET /api/runs/{run_id}/data`

Configuration

GET /api/config

PUT /api/config