Examples & SDKs

Copy-paste examples for the real endpoints, in three languages, plus the exact SDK method for each.

curl examples

The open endpoints need no auth; the authenticated ones take a session token or API-key header.

bash

BASE=http://localhost:8000

# health
curl -s $BASE/health

# audit (open), keep the response
curl -s -X POST $BASE/api/v1/audit/conversation \
  -H 'Content-Type: application/json' \
  -d '{"input":"The capital of Australia is Sydney."}'

# trust assessment (open), pass a full EvidenceEnvelope
curl -s -X POST $BASE/api/v1/trust/assess \
  -H 'Content-Type: application/json' \
  -d @sample-evidence.json   # {"evidence": { ... }}

# registry (open)
curl -s $BASE/api/v1/registry/agents

# authenticated /api/vai, session token header
curl -s $BASE/api/vai/dashboard -H 'X-Session-Token: <token from /api/auth/login>'

# authenticated /api/control, API key header
curl -s $BASE/api/control/sessions -H 'X-API-Key: vrf_<prefix>_<secret>'

Python examples

Working example with requests, then the transport-agnostic SDK.

python

import requests
BASE = "http://localhost:8000"

# 1) audit (open)
audit = requests.post(f"{BASE}/api/v1/audit/conversation",
                      json={"input": "The capital of Australia is Sydney."}).json()
print(audit["risk"], audit["provider"], audit["envelope"]["id"])

# 2) assess from a full evidence envelope
evidence = load_envelope()  # EvidenceEnvelope.to_dict()
trust = requests.post(f"{BASE}/api/v1/trust/assess", json={"evidence": evidence}).json()
print(trust["trust_score"], trust["trust_level"])

# 3) authenticated data plane, session token
tok = requests.post(f"{BASE}/api/auth/login",
                    json={"email": "owner@example.com", "password": "..."}).json()["session_token"]
dash = requests.get(f"{BASE}/api/vai/dashboard", headers={"X-Session-Token": tok}).json()

python (SDK)

# The official client. Prepare a call, or configure a sender and let it send.
import requests
from vailidator.sdk import VerifAIerClient

def send(method, url, body=None, params=None, timeout=None):
    return requests.request(method, url, json=body, params=params).text

client = VerifAIerClient.for_user("you")
gov = client.governance.with_base_url("http://localhost:8000").with_sender(send)
print(gov.assess_trust({"evidence": envelope}).payload["trust_level"])

client.governance.prepare("assessTrust", body) returns a PreparedCall and sends nothing, which is what the retired verifaier_sdk existed for. Configure a sender and the same accessor executes it. The open tier takes no authentication, so the client attaches no credential.

TypeScript examples

Working example with fetch, then the SDK.

typescript

const BASE = "http://localhost:8000";

// audit (open)
const audit = await fetch(`${BASE}/api/v1/audit/conversation`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ input: "The capital of Australia is Sydney." }),
}).then(r => r.json());

// assess from evidence
const trust = await fetch(`${BASE}/api/v1/trust/assess`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ evidence }),
}).then(r => r.json());
console.log(trust.trust_score, trust.trust_level);

There is no current TypeScript client. @verifaier/sdk under sdk/typescript is the OEM SDK Foundation and is retired (WP-10I): never published to npm, kept because partners may have vendored it, and superseded by VerifAIerClient.governance. The fetch example above is the supported TypeScript path, and the open tier needs no credential to use it.

Operation mapping

Every open governance endpoint has one named method on VerifAIerClient.governance. The table is derived from api/public_contract.py::PUBLIC_OPERATIONS · the allowlist that makes an endpoint public · rather than written out beside it, so the client and the contract cannot disagree.

Endpoint	Operation	Method
`POST /api/v1/audit/conversation`	`auditConversation`	`audit_conversation()`
`POST /api/v1/compliance/assess`	`assessCompliance`	`assess_compliance()`
`POST /api/v1/risk/assess`	`assessRisk`	`assess_risk()`
`POST /api/v1/quality/assess`	`assessQuality`	`assess_quality()`
`POST /api/v1/trust/assess`	`assessTrust`	`assess_trust()`
`POST /api/v1/passport/issue`	`issuePassport`	`issue_passport()`
`POST /api/v1/reputation/assess`	`assessReputation`	`assess_reputation()`
`POST /api/v1/registry/observe`	`observeRegistryEntry`	`observe_registry_entry()`
`GET /api/v1/registry/agents`	`listRegistryAgents`	`list_registry_agents()`
`GET /api/v1/registry/agents/{agent_id}`	`getRegistryAgent`	`get_registry_agent()`
`GET /api/v1/control-center/overview`	`getControlCenterOverview`	`get_control_center_overview()`
`POST /api/v1/signals/export`	`exportSignals`	`export_signals()`

Twelve operations, twelve methods. The retired verifaier_sdk.PATHS table listed eleven: it never gained getRegistryAgent. A hand-written table nothing cross-checks drifts; a derived one cannot.

First-audit API path (end to end)

Audit once, then compose everything from the returned envelope:

bash

BASE=http://localhost:8000
# 1. audit → capture the full evidence envelope your client assembles
curl -s -X POST $BASE/api/v1/audit/conversation -H 'Content-Type: application/json' \
  -d '{"input":"The capital of Australia is Sydney."}'
# 2. trust / passport / reputation from that evidence
curl -s -X POST $BASE/api/v1/trust/assess     -H 'Content-Type: application/json' -d @sample-evidence.json
curl -s -X POST $BASE/api/v1/passport/issue   -H 'Content-Type: application/json' -d @sample-evidence.json
curl -s -X POST $BASE/api/v1/registry/observe -H 'Content-Type: application/json' -d @sample-evidence.json
# 3. read the fleet
curl -s $BASE/api/v1/control-center/overview

A ready-to-run sample project (run_first_audit.py, run_first_audit.sh, sample-evidence.json) ships with First audit.