API reference
Base URL: https://vigil.supertruth.ai. The pages in this section are generated at build time from the running service's openapi.json, one page per tag, with the scope each route requires.
Authentication
Every route except /, /health, /docs, /openapi.json and /redoc requires Authorization: Bearer <key>. Keys start with vg_ and are stored as SHA-256 hashes. Missing or unknown key: 401. Known key without the needed scope: 403. Every authenticated response carries Cache-Control: no-store.
Scopes
| Scope | Lets a key |
|---|---|
events:write | Register agents, post events, toggle monitoring, send OpenTelemetry traces |
read | Read agents, scores, audit, enforcement state, policies, registries, usage |
review | Run scenario packs, run the Investigator, and decide holds on the gate service |
admin | Everything above plus keys, webhooks, policy versions, registries, admin stats |
platform | Create orgs and mint keys into other orgs. Nothing implies it. |
An admin key satisfies every scope except platform.
Orgs
Every key belongs to one org and every request runs inside that org. agent_id is unique per org, not globally. A key never sees another org's rows; the answer is 404, not 403.
Rate limits
600 requests per minute per key, 1200 per minute per key on POST /events/. Over the limit returns 429 with Cache-Control: no-store. The SDKs retry 429 and 5xx three times with jittered backoff.
Maintenance
While VIGIL_READ_ONLY is set on the service, the producer routes (POST /events/, POST /otel/v1/traces, POST /test/run, POST /ai/investigator/run) return 503 and every read keeps working.
Who am I
curl -sf -H "Authorization: Bearer $VIGIL_KEY" "$VIGIL_URL/orgs/me"
Any key can call this; it returns the key's org.