API Reference

Base URL: https://api.vr.dev/v1

All requests require an Authorization: Bearer <api_key> header.

---

POST /verify

Run a single verifier against a ground truth payload.

Request:

{
  "verifier_id": "vr/code.python.tests_pass",
  "completions": ["def add(a, b): return a + b"],
  "ground_truth": {
    "repo": ".",
    "test_cmd": "pytest"
  },
  "context": {}
}

Response:

{
  "passed": true,
  "score": 1.0,
  "evidence": {
    "test_output": "3 passed in 0.42s",
    "exit_code": 0
  },
  "evidence_hash": "sha256:a3f1b2c4...",
  "verifier_id": "vr/code.python.tests_pass",
  "tier": "HARD",
  "duration_ms": 1250
}

---

POST /compose

Run a pipeline of verifiers in sequence.

Request:

{
  "verifier_ids": [
    "vr/tau2.retail.order_cancelled",
    "vr/rubric.email.tone_professional"
  ],
  "completions": ["Order cancelled and confirmation sent"],
  "ground_truth": {
    "order_id": "ORD-42"
  },
  "policy_mode": "fail_closed",
  "require_hard": true
}

Response:

{
  "all_passed": true,
  "results": [
    { "verifier_id": "vr/tau2.retail.order_cancelled", "passed": true, "score": 1.0, "tier": "HARD" },
    { "verifier_id": "vr/rubric.email.tone_professional", "passed": true, "score": 0.92, "tier": "SOFT" }
  ],
  "evidence_hash": "sha256:b4c2d1e5...",
  "duration_ms": 2100
}

---

POST /batch

Verify multiple ground truth payloads against the same verifier or pipeline. Useful for evaluation runs.

Request:

{
  "verifier": "tau2.retail.order_cancelled",
  "items": [
    { "ground_truth": { "order_id": "ORD-1" } },
    { "ground_truth": { "order_id": "ORD-2" } },
    { "ground_truth": { "order_id": "ORD-3" } }
  ]
}

Response:

{
  "results": [
    { "passed": true, "score": 1.0 },
    { "passed": false, "score": 0.0 },
    { "passed": true, "score": 1.0 }
  ],
  "summary": { "total": 3, "passed": 2, "failed": 1 }
}

---

POST /export

Export verification results to training framework formats.

Request:

{
  "format": "trl",
  "pipeline_run_id": "run_abc123"
}

Formats: trl, verl, jsonl

---

GET /registry

List all available verifiers with metadata.

Query parameters:

| Param | Type | Description | |--------|--------|-------------| | tier | string | Filter: HARD, SOFT, AGENTIC | | domain | string | Filter by domain |

Response:

{
  "verifiers": [
    {
      "id": "vr/code.python.tests_pass",
      "tier": "HARD",
      "domain": "code_quality",
      "description": "..."
    }
  ],
  "total": 38
}

---

Error Codes

| Code | Meaning | |------|---------| | 400 | Invalid request body | | 401 | Missing or invalid API key | | 402 | Free tier exhausted; payment required (x402 USDC) | | 404 | Verifier not found | | 429 | Rate limit exceeded | | 500 | Internal verifier error |