Quickstart

Ten minutes from a key to a scored, gated, sealed event.

1. Get a key

Self-serve sign-up is coming. For now, ask your VIGIL admin for a key. Keys start with vg_ and carry scopes; a producer needs events:write and read. The admin mints it with POST /keys/ and the full key is shown once.

Put it in your environment:

export VIGIL_URL=https://vigil.supertruth.ai
export VIGIL_KEY=vg_...

2. Send your first event

Every event names an agent, an event type, and a payload. The agent is registered on first use.

Python (pip install -e sdk/python from the repo):

from vigil import Vigil

vg = Vigil(api_key="vg_...")
vg.register_agent("my-agent", "My agent", exist_ok=True)
gate = vg.emit("my-agent", "output_generated", {"content_length": 812}, dti=0.9)

TypeScript (npm install @supertruth/vigil):

import { Vigil } from "@supertruth/vigil";

const vg = new Vigil({ apiKey: process.env.VIGIL_KEY! });
await vg.registerAgent("my-agent", "My agent", { existOk: true });
const gate = await vg.emit("my-agent", "output_generated", { content_length: 812 }, { dti: 0.9 });

Plain HTTP:

curl -sf -X POST "$VIGIL_URL/agents/" \
  -H "Authorization: Bearer $VIGIL_KEY" -H "Content-Type: application/json" \
  -d '{"agent_id":"docs-quickstart","name":"Docs quickstart"}' > /dev/null || true   # 409 if it already exists

curl -sf -X POST "$VIGIL_URL/events/" \
  -H "Authorization: Bearer $VIGIL_KEY" -H "Content-Type: application/json" \
  -d '{"agent_id":"docs-quickstart","event_type":"output_generated","payload":{"content_length":812},"dti":0.9}'

3. Read the gate response

{
  "event_id": 42,
  "action_id": 42,
  "gate_status": "pass",
  "bii": 0.913,
  "composite_trust": 0.8386,
  "reason": "BII 0.913 within acceptable range.",
  "requires_human_review": false
}

Field	Meaning
gate_status	pass, hold, alert or collapse. What you must do with each is on the gates page.
bii	The Behavioral Integrity Index after this event, 0.0 to 1.0.
composite_trust	(DTI x 0.80) + (BII x 0.20), or null when you sent no dti. Forced to 0.0 when BII is at or below the collapse threshold.
action_id	The enforcement action this event produced. Poll GET /enforcement/{action_id} to see a reviewer's decision.
requires_human_review	True for hold, alert and collapse.
reason	One sentence a reviewer can read.

4. Honor the gate

The API does not withhold anything itself. Your code does. The SDKs make that the default:

from vigil import HeldOutput

try:
    gate.honor()                       # raises HeldOutput on hold, alert, collapse
except HeldOutput as h:
    action = vg.wait_for_release(h.action_id, timeout=600)
    if action["review_outcome"] != "released":
        raise

If you decide to let a held output through anyway, gate.honor(allow_propagation=True) records that choice on the ledger first. Overriding the gate is itself an event.

5. See it on the ledger

curl -s -H "Authorization: Bearer $VIGIL_KEY" "$VIGIL_URL/audit/docs-quickstart/verify"

ok: true means every record in your org's chain recomputes and every HMAC matches. The ledger page explains how to verify offline with no trust in the server.

Next

• Python SDK and TypeScript SDK for the full surface.
• Adapters when the agent runs under Claude Code, the OpenAI Agents SDK or LangGraph, so the platform reports and the agent does not report on itself.
• Webhooks to be called on hold, alert, collapse and review.