Docs › HTTP API
HTTP API
Base URL https://api.runvouch.com. Auth: X-API-Key. JSON in, JSON out. Rate limit 600 requests/min per key.
On this page
Endpoints
| Method · path | Purpose |
|---|---|
POST /signup | {"email"} → free account + key (shown once) |
GET /v1/me · POST /v1/me/rotate-key | account, plan, key rotation |
PUT /v1/settings | alert_email, telegram_token, telegram_chat, webhook_url, slack_webhook_url, pagerduty_routing_key (Team) · POST /v1/settings/test-alert sends a TEST alert to every configured channel · details per channel on alerts |
POST /v1/agents · GET /v1/agents | upsert (name, cadence_s, grace_s, max_runtime_s, cap_run_cost, cap_day_cost, cap_run_tokens, evidence_required) · list with state |
POST /v1/agents/{name}/pause · GET /v1/agents/{name}/runs | pause/resume · run history |
GET /v1/runs/{run_id}/proof · GET /proof/ (public) | proof of one finished run · the daily chain, see verifiable runs |
POST /v1/runs/start · /tool · /heartbeat · /end | run lifecycle; tool events carry tool, input (hashed server-side) or input_hash, ok, cost, tokens |
GET /v1/alerts · POST /v1/alerts/{id}/ack | alerts (ack also resolves the PagerDuty incident on Team) |
GET /v1/export?from=YYYY-MM-DD&to=YYYY-MM-DD&format=csv|json | Team: streams every run that started in the range (UTC days, inclusive): agent, run_id, started, ended, status, cost, tokens, tool_calls, evidence_ok, leaf_hash. Free and Solo get 402. |
POST /v1/me/viewer-keys · GET /v1/me/viewer-keys · DELETE /v1/me/viewer-keys/{id} | Team: read-only keys (rvv_) for a shared dashboard. Body {"name"}; the key is shown once. A viewer key may GET anything under /v1 and POST /v1/alerts/{id}/ack; every other write returns 403. |
History retention
Runs, tool events and acknowledged alerts are kept for 7 days on Free and 90 days on Solo and Team (history_days in GET /v1/me). A purge runs once a day. Open alerts are never purged. A run that is part of a sealed proof day keeps its id, end time and leaf hash in a small table, so GET /v1/runs/{id}/proof still returns the leaf, its Merkle path and the sealed root after the full record is gone (with "purged": true and "record": null).
Alert webhook payload
{"kind":"RETRY_STORM","agent":"repo-janitor","run_id":"9808c5af…","message":"tool 'Bash' called 41x with identical input in one run.","ts":1787673506.3}Need a key? Get a free key · Stuck? contact