Check an agent

Two reads that need no key. An agent's owner can open its behavioral integrity record to anyone; the record shows what VIGIL holds about that agent right now, and nothing else.

GET /public/agents/{org_slug}/{agent_id} returns exactly these fields:

Field	Meaning
org	The organization's slug
agent_id, name, kind	Which agent; kind is production, sandbox or system
gate	The current gate: pass, hold, alert or collapse (null before the first scored event)
bii	The current Behavioral Integrity Index, 0.0 to 1.0, as stored at the last scored event
ledger_records	How many records on the organization's ledger belong to this agent
ledger_head	The organization's current ledger head hash; the same value GET /audit/{agent_id}/verify reports as head
last_event_at	When the agent's most recent event was recorded, UTC
observed	Whether the agent has been told it is under observation. It is scored either way
policy_digest	Digest of the policy version that produced the current score
public_links	Links the owner declared, at most five {kind, url} entries; VIGIL does not check them
verify_url	Where to read how to verify the ledger yourself

There is no event content, no payload, no score history, no review note and no configuration on this route. Every value is one the owner already reads with a key; the public read computes nothing new.

GET /public/agents/{org_slug} lists the organization's public agents with the same fields, limit (1 to 100, default 50) and offset.

Both answer 404 for an agent that is not public, not active, or not in that organization, and for an organization with no public agent. Both are rate limited per client address (60 a minute by default) and send X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Responses carry Cache-Control: public, max-age=60 and may be read from any origin in a browser.

The same record as a page: https://app.vigil.supertruth.ai/a/{org_slug}/{agent_id}.

The two calls

curl:

curl -s https://vigil.supertruth.ai/public/agents/supertruth/truth-agent
curl -s "https://vigil.supertruth.ai/public/agents/supertruth?limit=20"

Python:

import httpx

BASE = "https://vigil.supertruth.ai"

def check_agent(org: str, agent_id: str) -> dict | None:
    r = httpx.get(f"{BASE}/public/agents/{org}/{agent_id}", timeout=10)
    if r.status_code == 404:
        return None                       # not public, not active, or no such agent
    r.raise_for_status()
    return r.json()

rec = check_agent("supertruth", "truth-agent")
if rec:
    print(rec["gate"], rec["bii"], rec["ledger_records"], rec["ledger_head"][:12])

TypeScript:

const BASE = "https://vigil.supertruth.ai";

export async function checkAgent(org: string, agentId: string) {
  const res = await fetch(`${BASE}/public/agents/${encodeURIComponent(org)}/${encodeURIComponent(agentId)}`);
  if (res.status === 404) return null;   // not public, not active, or no such agent
  if (!res.ok) throw new Error(`VIGIL ${res.status}`);
  return (await res.json()) as {
    org: string; agent_id: string; name: string; kind: string;
    gate: "pass" | "hold" | "alert" | "collapse" | null; bii: number | null;
    ledger_records: number; ledger_head: string | null; last_event_at: string | null;
    observed: boolean; policy_digest: string;
    public_links: { kind: string; url: string }[]; verify_url: string;
  };
}

Make your agent public

The flag is off for every agent until an admin key in the agent's own organization turns it on with PATCH /admin/agents/{agent_id}. The same call sets public_links: up to five entries, kind one of website, github, x, moltbook, other, url an http or https address of at most 200 characters. The list is replaced whole; [] clears it. {"public": false} closes the record again; retiring the agent (is_active: false) closes it too.

This snippet registers an agent, scores one event, opens the record, reads it with no key, and closes it:

curl -sf -X POST "$VIGIL_URL/agents/" -H "Authorization: Bearer $VIGIL_KEY" -H "Content-Type: application/json" \
  -d '{"agent_id":"docs-public","name":"Docs public"}' > /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-public","event_type":"output_generated","payload":{"content_length":512},"dti":0.9}' > /dev/null
curl -sf -X PATCH "$VIGIL_URL/admin/agents/docs-public" -H "Authorization: Bearer $VIGIL_KEY" -H "Content-Type: application/json" \
  -d '{"public":true,"public_links":[{"kind":"website","url":"https://example.com"}]}' > /dev/null   # admin key
org=$(curl -sf -H "Authorization: Bearer $VIGIL_KEY" "$VIGIL_URL/orgs/me" | python3 -c 'import json,sys; print(json.load(sys.stdin)["slug"])')
curl -sf "$VIGIL_URL/public/agents/$org/docs-public"                    # no key
curl -sf "$VIGIL_URL/public/agents/$org?limit=5" > /dev/null            # no key
curl -sf -X PATCH "$VIGIL_URL/admin/agents/docs-public" -H "Authorization: Bearer $VIGIL_KEY" -H "Content-Type: application/json" \
  -d '{"public":false}' > /dev/null

What the record proves, and what it does not

It proves that a VIGIL-registered runtime reporting as this agent has the behavior record shown, and that the ledger holding it has not been edited: every record carries its content hash and the previous chain hash, the database rejects UPDATE and DELETE, and the head hash commits to the whole history.

It does not prove identity or key custody. It does not say who operates the agent, who holds the agent's keys, or that an account on any other site belongs to it; the public_links are the owner's own words. VIGIL scores the events the runtime reported. An action the agent took outside that runtime, or that its runtime never reported, is not on the record.

Verify the ledger yourself

The head hash on the public record is the head of the organization's chain. With a key from the owner, GET /audit/{agent_id}/verify recomputes the chain and reports the same head, GET /audit/export returns the raw rows, and the standalone verifier in the ledger checks them with no dependency on VIGIL. Without a key, the record still tells you the gate, the score, how long the chain is and where it stands today; if the head you saw yesterday is no longer a prefix of today's chain in the owner's export, something was rewritten.

For agents

Load the skill file at /skills/check-an-agent.md to call these two reads before acting on another agent's output. It sends no key and needs none. With a key, the MCP server tool get_trust returns the same gate and BII for agents in your own organization.