Skip to content
VerifAIer
Home / Docs / API
Walkthrough

API

The governance surface: open trust APIs and authenticated operational APIs.

~5 min readDifficulty: MediumPrereq: a running API

What it is

The API is VerifAIer's governance surface. It has two tiers: the open AI-trust APIs under /api/v1/*, and the authenticated operational APIs under /api/control/* and /api/vai/*.

Why it exists

One consistent, deterministic surface for evidence, intelligence, identity and distribution, the same endpoints the Dashboard and SDKs use.

When to use it

Use the /api/v1/* trust APIs to audit and assess; use the operational APIs (authenticated) to retrieve sessions, artifacts and fleet history.

Where it fits / architecture position

The API is the boundary between your systems and the evidence engine.

Client / SDKrequest
APIv1 open + operational auth
Enginesdeterministic
Responseno secrets

Typical workflow

  • Call /api/v1/audit/conversation to produce evidence.
  • Assess it via trust / risk / quality / compliance.
  • Read the fleet with the open overview; retrieve history via the authenticated operational endpoints.

Step-by-step usage

The twelve open trust endpoints (no auth):

POST /api/v1/audit/conversation      POST /api/v1/passport/issue
POST /api/v1/compliance/assess       POST /api/v1/reputation/assess
POST /api/v1/risk/assess             POST /api/v1/registry/observe
POST /api/v1/quality/assess          GET  /api/v1/registry/agents
POST /api/v1/trust/assess            GET  /api/v1/registry/agents/{id}
GET  /api/v1/control-center/overview POST /api/v1/signals/export

Inputs and outputs

Inputs: JSON bodies (e.g. evidence, pack_id). Outputs: deterministic JSON. Responses never contain secrets or prompts.

Real example

The two tiers are easy to tell apart, verified against the running server. An open trust endpoint responds directly:

curl -s http://localhost:8000/api/v1/registry/agents
{
  "agents": [],
  "count": 0
}

An operational endpoint requires authentication:

curl -s http://localhost:8000/api/vai/artifacts
{
  "detail": "Authentication required"
}

Expected results

  • /api/v1/*: 2xx JSON, no auth required.
  • /api/control/* and /api/vai/*: 401 Authentication required without a session.

Common mistakes

  • Calling operational endpoints without a session token, authenticate via the Control Center first.
  • Assuming every path needs auth, the trust APIs are intentionally open for local, self-serve use.

Troubleshooting

  • 401: you hit an operational endpoint, authenticate, or use the open /api/v1/* surface.
  • 422: a malformed body, check the field names in the API reference.

Related documentation

Next: Deployment

Continue the operational walkthroughs.

DeploymentAPI reference