RuntimeAI v1 API

Reference

Base URL

Workflow

You must quote before submit. Each quote_id is one-time use. The quote_id comes from the quote response — not generated client-side. Use your personal rai_live_… key as TOKEN below (request one via Request API key). Operators may use RUNTIMEAI_API_TOKEN instead.

Authentication

All routes except GET /health and the key-request endpoints require a Bearer token.

Get a key (recommended)

Request API key by email

1. Open /runtimeai/api/request-key and enter your email.
2. Click the confirmation link in your inbox (valid 48 hours).
3. Receive your personal rai_live_… key by email — one key per email address.

Authorization: Bearer rai_live_…

Missing or invalid tokens return 401 with code UNAUTHORIZED.

Trial allowance (self-serve keys)

Customer rai_live_… keys have a trial allowance per account (acct_… / account_id on the key row — the same subject as attestation). Rotating a key does not reset it. Master RUNTIMEAI_API_TOKEN is exempt (operator). The allowance can be raised on request — email hello@vantageai.cc with your acct_ id and what you're evaluating. Defaults:

A documented 5-model 12-turn comparison is ~$0.21 (trial-sample quote) to ~$0.34 (engage-draft bakeoff). $2/month is about 9 such comparisons — enough for a real evaluation, not a research programme. Email hello@vantageai.cc with your acct_ id and what you're evaluating — we raise trial allowances for people doing real work. Quoted eval-run USD (not the production execution projection) counts toward the monthly allowance at POST /evaluations. Master token is exempt. Env overrides: RUNTIMEAI_QUOTA_DAILY_RUNS, RUNTIMEAI_QUOTA_MONTHLY_USD, RUNTIMEAI_QUOTA_CONCURRENT_RUNS, RUNTIMEAI_RATE_QUOTES_PER_MINUTE, RUNTIMEAI_RATE_POLLS_PER_MINUTE, RUNTIMEAI_RATE_ATTESTATIONS_PER_HOUR, plus per-account maps RUNTIMEAI_QUOTA_*_ACCT=acct_xxx:value.

Operator key management

Master RUNTIMEAI_API_TOKEN works on all routes and is required to manually create or revoke keys in the operator UI.

Error envelope

{
  "error": "Human-readable message",
  "code": "QUOTE_EXPIRED",
  "details": {}
}

Endpoints

{
  "scenario_id": "support_escalation_v1",
  "models": ["openai/gpt-4o-mini"],
  "turns": 12,
  "provider": "openrouter",
  "preflight": false,
  "execution_assumptions": {
    "interactions_per_biz_day": 5000,
    "biz_days_per_month": 22
  }
}

{
  "quote_id": "qt_…",
  "confirm": true,
  "callback_url": null,
  "results_email": "you@example.com"
}

{
  "digest": "64-hex payload_sha256",
  "algorithm": "sha256",
  "schema": "runtimeai.decision/v1",
  "canonicalization": "runtimeai-py-json-v1",
  "pins": {
    "model": "openai/gpt-4o-mini",
    "scenario_id": "sample.acme_release_v1",
    "runner": "vantage-core",
    "runner_version": "0.1.18",
    "suite_id": "sample.acme_release_v1"
  },
  "suite_sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "client_ts": "2026-08-01T15:00:00Z"
}

Quick start — curl

Set your base URL and token once (rai_live_… customer key or operator RUNTIMEAI_API_TOKEN):

export BASE='https://www.vantageai.cc/api/runtimeai/v1'
export TOKEN='rai_live_your_key_here'

curl -sS "$BASE/health" | python3 -m json.tool

import requests

BASE = "https://www.vantageai.cc/api/runtimeai/v1"
print(requests.get(f"{BASE}/health", timeout=30).json())

const BASE = "https://www.vantageai.cc/api/runtimeai/v1";
const res = await fetch(`${BASE}/health`);
console.log(await res.json());

Full quote → submit → poll (curl)

# 1. Quote
curl -sS -X POST "$BASE/evaluations/quote" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scenario_id": "support_escalation_v1",
    "models": ["openai/gpt-4o-mini"],
    "turns": 12,
    "provider": "openrouter",
    "preflight": false
  }' | python3 -m json.tool

export QUOTE_ID='qt_from_response'

# 2. Submit (starts real LLM run — uses OpenRouter credits)
curl -sS -X POST "$BASE/evaluations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"quote_id\":\"$QUOTE_ID\",\"confirm\":true}" | python3 -m json.tool

export EVAL_ID='evaluation_id_from_response'

# 3. Poll until status ≠ running
while true; do
  curl -sS "$BASE/evaluations/$EVAL_ID" \
    -H "Authorization: Bearer $TOKEN" | python3 -m json.tool
  sleep 5
done

# 4. Download reports (Bearer auth — works from curl/scripts)
curl -sS -o "comparison.json" \
  -H "Authorization: Bearer $TOKEN" \
  "$BASE/evaluations/$EVAL_ID/comparison"

curl -sS -o "runtimeai-comparison.pdf" \
  -H "Authorization: Bearer $TOKEN" \
  "$BASE/evaluations/$EVAL_ID/comparison.pdf"

# Per-run scorecard from poll response runs[].links (example RUN_ID)
curl -sS -o "scorecard.json" \
  -H "Accept: application/json" \
  "https://www.vantageai.cc/api/run/RUN_ID/scorecard?download=1"

curl -sS -o "scorecard.pdf" \
  "https://www.vantageai.cc/api/run/RUN_ID/scorecard.pdf"

Python example

Requires requests. Submit uses real OpenRouter credits when the server has OPENROUTER_API_KEY set.

import os
import time
import json
import requests
from pathlib import Path

BASE = os.environ.get(
    "RUNTIMEAI_API_BASE",
    "https://www.vantageai.cc/api/runtimeai/v1",
)
TOKEN = os.environ["RUNTIMEAI_API_TOKEN"]  # or rai_live_… customer key

def api(method: str, path: str, **kwargs):
    headers = {"Authorization": f"Bearer {TOKEN}"}
    if kwargs.get("json") is not None:
        headers["Content-Type"] = "application/json"
    url = f"{BASE}{path}"
    resp = requests.request(method, url, headers=headers, timeout=120, **kwargs)
    resp.raise_for_status()
    return resp.json()

# Smoke (no auth)
print(requests.get(f"{BASE}/health", timeout=30).json())

scenarios = api("GET", "/scenarios")
print("scenarios:", [s["id"] for s in scenarios["scenarios"]])

quote = api(
    "POST",
    "/evaluations/quote",
    json={
        "scenario_id": "support_escalation_v1",
        "models": ["openai/gpt-4o-mini"],
        "turns": 12,
        "provider": "openrouter",
        "preflight": False,
    },
)
quote_id = quote["quote_id"]
print("quote_id:", quote_id, "est_total:", quote["summary"]["est_cost_usd_total"])

submit = api(
    "POST",
    "/evaluations",
    json={"quote_id": quote_id, "confirm": True},
)
eval_id = submit["evaluation_id"]
print("evaluation_id:", eval_id)

while True:
    status = api("GET", f"/evaluations/{eval_id}")
    print("status:", status["status"], status.get("progress"))
    if status["status"] != "running":
        for run in status.get("runs", []):
            if run.get("links"):
                print("scorecard json:", run["links"].get("scorecard"))
                print("scorecard pdf:", run["links"].get("pdf"))
        if status.get("links"):
            print("comparison json:", status["links"].get("comparison"))
            print("comparison pdf:", status["links"].get("comparison_pdf"))
        break
    time.sleep(5)

# Download comparison reports with Bearer auth
cmp = requests.get(
    f"{BASE}/evaluations/{eval_id}/comparison",
    headers={"Authorization": f"Bearer {TOKEN}"},
    timeout=120,
)
cmp.raise_for_status()
Path("comparison.json").write_text(json.dumps(cmp.json(), indent=2), encoding="utf-8")

pdf = requests.get(
    f"{BASE}/evaluations/{eval_id}/comparison.pdf",
    headers={"Authorization": f"Bearer {TOKEN}"},
    timeout=120,
)
pdf.raise_for_status()
Path("runtimeai-comparison.pdf").write_bytes(pdf.content)

Postman

Download RuntimeAI-v1.postman_collection.json

Setup

1. Open Postman → Import → File → select the collection JSON (or use the download link above).
2. Create environment RuntimeAI Production with variables:

Run in order

Collection-level Bearer auth uses {{token}} — set it once in the environment. Typical completion time: 3–10 minutes for one model at 12 turns.

Postman troubleshooting

Error codes

Related

• Request API key — self-serve email workflow
• How To — sandbox UI walkthrough
• RuntimeAI sim — interactive evaluation UI