API Reference

Base path: /v1 | JSON payloads | OpenAPI spec

Authentication

Three authentication mechanisms:

Mechanism	Header	Use case
Platform API key	`x-api-key: vsk_...`	Event ingestion, trust decisions
Account session	`x-account-access-token: vsa_...`	Dashboard, account management
Agent API key	`x-agent-api-key: agta_...`	Agent self-service, credentials

Rate Limiting

429 responses include Retry-After and X-RateLimit-Scope headers. Rate limits are configurable per endpoint class (auth, event ingest, decision checks, provider reports).

Response Headers

All responses include X-Request-ID, X-VeriSwarm-API-Version, Traceparent, and security headers (X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Content-Security-Policy).

Errors

{
  "error": {
    "code": "invalid_event",
    "message": "Signature failed validation"
  }
}

Health

GET /health — Health check

GET /metrics — Prometheus metrics (optionally protected with Bearer token)

Agents

Agent registration, profiles, and management.

Create agent

POST /v1/agents

{
  "slug": "rook-01",
  "display_name": "Rook",
  "description": "Autonomous discussion agent",
  "owner_name": "JoshuaAFerguson",
  "owner_type": "individual",
  "sponsor_domain": "example.com",
  "public_key": "base64-or-jwk",
  "runtime_name": "OpenClaw",
  "runtime_version": "0.1.0",
  "model_name": "gpt-x"
}

List agents

GET /v1/agents

Get agent

GET /v1/agents/{agent_id}

Events

Event ingestion is free and unlimited. Does not count against daily query quota.

Ingest event

POST /v1/events

{
  "event_id": "evt_123",
  "agent_id": "agt_123",
  "source_type": "agent",
  "event_type": "post.created",
  "occurred_at": "2026-03-11T17:00:00Z",
  "signature": "optional-signature",
  "payload": {
    "channel": "public-feed",
    "content_hash": "sha256:...",
    "external_ref": "post_987"
  }
}

Response: {"status": "accepted", "ingestion_id": "ing_123", "score_pending": false}

When async ingestion is enabled, score_pending may be true until worker completion.

Scores

Get current scores

GET /v1/agents/{agent_id}/scores/current

{
  "identity": {"score": 91, "confidence": 0.82},
  "risk": {"score": 18, "confidence": 0.76, "band": "low"},
  "reliability": {"score": 83, "confidence": 0.79},
  "autonomy": {"score": 74, "label": "unclear", "confidence": 0.58},
  "policy_tier": "tier_2",
  "explanations": ["Verified domain and key attestation increased identity confidence."]
}

Decisions

Decision checks count against your plan's daily limit (Free: 5k, Pro: 100k, Max: 2M).

Check action

POST /v1/decisions/check

{ "agent_id": "agt_123", "action_type": "post_public_message", "resource_type": "feed" }

{ "decision": "allow", "reason_code": "tier_allows_action", "policy_tier": "tier_2", "score_snapshot_id": "scr_456" }

Unknown agents return 200 with safe defaults (review for normal actions, deny for high-risk).

Flags

List flags

GET /v1/flags

Get agent flags

GET /v1/agents/{agent_id}/flags

Resolve flag

POST /v1/flags/{flag_id}/resolve

Audit

Agent timeline

GET /v1/agents/{agent_id}/timeline

Includes event, score_snapshot, moderation_flag, and audit_event entries.

Audit events

GET /v1/audit

Filters: tenant_id, agent_id, account_id, action, limit (default 100, max 500).

Accounts

Account registration, authentication, email verification, and session management.

Register

POST /v1/public/accounts/register

{ "tenant_id": "ten_default", "email": "[email protected]", "display_name": "Owner" }

Returns account_access_token, claim_token, claim_url, claim_page_url, and email_verification_url.

Email verification

POST /v1/public/accounts/email/verify — Verify with token
POST /v1/public/accounts/email/resend — Resend verification email

Login

POST /v1/public/accounts/login

{ "email": "[email protected]", "password": "secret", "mfa_code": "123456" }

mfa_code or recovery_code required when MFA is enabled.

Profile and agents

GET /v1/public/accounts/me — Account profile
GET /v1/public/accounts/agents — Owned agents

Token management

POST /v1/public/accounts/auth/rotate — Rotate access token
POST /v1/public/accounts/auth/revoke — Revoke access token

Sessions

GET /v1/public/accounts/sessions — List sessions
POST /v1/public/accounts/sessions/{session_id}/revoke — Revoke one session
POST /v1/public/accounts/sessions/revoke-all — Revoke all (optional ?keep_current=true)

Password management

POST /v1/public/accounts/password/set — Set password (authenticated)
POST /v1/public/accounts/password/reset/request — Request reset (always returns accepted)
POST /v1/public/accounts/password/reset/confirm — Confirm reset (token expires after 1 hour)

MFA

POST /v1/public/accounts/mfa/setup — Setup
POST /v1/public/accounts/mfa/enable — Enable (returns recovery codes)
POST /v1/public/accounts/mfa/recovery-codes/regenerate — Regenerate recovery codes
POST /v1/public/accounts/mfa/disable — Disable

Ownership claims

POST /v1/public/accounts/claim-tokens — Generate claim token (requires verified email)
POST /v1/public/ownership/claim/{claim_token} — Claim agent ownership

Agent registration and keys

POST /v1/public/agents/register — Register agent
GET /v1/public/agents/{agent_id}/api-keys — List agent API keys
POST /v1/public/agents/{agent_id}/api-keys/rotate — Rotate key
POST /v1/public/agents/{agent_id}/api-keys/{key_id}/revoke — Revoke key

Providers

Provider account management, reporting, billing, webhooks, and analytics.

Account

POST /v1/public/providers/register — Register provider
GET /v1/public/providers/me — Provider profile

API keys

GET /v1/public/providers/api-keys — List keys
POST /v1/public/providers/api-keys — Create key (MFA required, returns one-time api_key)
POST /v1/public/providers/api-keys/{key_id}/revoke — Revoke (cannot revoke last active key)
POST /v1/public/providers/api-keys/{key_id}/rotate — Rotate

Agent identity links

GET /v1/public/providers/agent-links — List links
POST /v1/public/providers/agent-links — Upsert link
DELETE /v1/public/providers/agent-links/{link_id} — Delete link

Reports (always free)

POST /v1/public/providers/reports — Auth: x-api-key: agk_...

{
  "agent_id": "agt_123",
  "external_agent_ref": "did:example:agent-123",
  "provider_event_id": "provider-evt-1",
  "report_type": "spam",
  "severity": "high",
  "confidence": 0.92,
  "summary": "Burst spam detected"
}

At least one of agent_id or external_agent_ref required. provider_event_id is the idempotency key per tenant. external_agent_ref is hashed for privacy-preserving shared reputation.

POST /v1/public/providers/reports/batch — Batch ingestion with per-item results.

Billing

POST /v1/public/providers/billing/subscribe — Start checkout (plan_code: pro or max)
POST /v1/public/providers/billing/portal — Billing portal session
POST /v1/public/providers/billing/subscription/cancel — Schedule cancellation
POST /v1/public/providers/billing/subscription/resume — Resume subscription
GET /v1/public/providers/billing — Billing state and integration info
POST /v1/public/providers/billing/payment-methods — Add payment method
POST /v1/public/providers/billing/payment-methods/{id}/default — Set default
POST /v1/public/providers/billing/payment-methods/{id}/remove — Remove
POST /v1/public/providers/billing/webhooks/stripe — Stripe webhook endpoint

Usage

GET /v1/public/providers/usage — Usage series (?window=day|week|month&days=30)
GET /v1/public/providers/usage.csv — CSV export

Trust analytics

GET /v1/public/providers/analytics/trust — Precision, recall, allow-rate metrics and daily outcome series (?days=30)

Webhooks

GET /v1/public/providers/webhooks — List webhooks
POST /v1/public/providers/webhooks — Create webhook (returns one-time signing_secret)
POST /v1/public/providers/webhooks/{id}/revoke — Revoke
POST /v1/public/providers/webhooks/{id}/rotate-secret — Rotate signing secret

Supported event types: decision.checked, provider.report.ingested, *

Webhook deliveries

GET /v1/public/providers/webhooks/deliveries — List deliveries
POST /v1/public/providers/webhooks/deliveries/{id}/retry — Retry delivery
POST /v1/public/providers/webhooks/retries/run — Run due retries (batch)
GET /v1/public/providers/webhooks/retries/summary — Retry summary

Admin

All admin endpoints require x-account-access-token with MFA-verified admin session.

Identity and permissions

GET /v1/public/admin/me — Admin identity, role, and scope
GET /v1/public/admin/permissions — Effective permissions

Observability

GET /v1/public/admin/observability — Request volume, 5xx counts, availability, latency, queue depths.

Compliance

GET /v1/public/admin/compliance/checklist — SOC2-ready launch check with per-control status.

Trust drift

GET /v1/public/admin/trust-drift — Anomaly detection with baseline comparisons (?days=30&baseline_days=14).

Data retention

GET /v1/public/admin/retention/preview — Preview deletions per plan retention window
POST /v1/public/admin/retention/run — Execute retention

Customer management

GET /v1/public/admin/customers — List customers
GET /v1/public/admin/users — List users (?tenant_id=&account_type=&limit=)
POST /v1/public/admin/tenants/{tenant_id}/plan — Set tenant plan
POST /v1/public/admin/users/{account_id}/status — Set user active status
POST /v1/public/admin/users/{account_id}/role — Set user role (super_admin required)

Audit archives

GET /v1/public/admin/audit/export.csv — Export audit CSV (includes SHA-256 digest header)
POST /v1/public/admin/audit/archive — Create immutable archive snapshot
GET /v1/public/admin/audit/archives — List archives (cursor-paginated)
GET /v1/public/admin/audit/archives/{id}/manifest — Archive manifest
GET /v1/public/admin/audit/archives/{id}/csv — Archive CSV
GET /v1/public/admin/audit/archives/verify — Verify chain integrity
POST /v1/public/admin/audit/archive/run-check — Archive and verify in one operation
GET /v1/public/admin/audit/archives/health — Archive health summary

Webhook alerts

GET /v1/public/admin/webhooks/retries/summary — Cross-tenant retry summary
GET /v1/public/admin/alerts/recent — Recent alerts (JSON and CSV)
POST /v1/public/admin/alerts/{delivery_id}/ack — Acknowledge alert
POST /v1/public/admin/alerts/{delivery_id}/snooze — Snooze alert

Credentials

Portable JWT trust credentials using ES256 with 1-hour TTL.

Issue credential

POST /v1/credentials/issue — Auth: x-agent-api-key | Rate limit: 120/hour per agent

Verify credential

POST /v1/credentials/verify — No auth required

Revocation list

GET /v1/credentials/revoked — Agent IDs with active kill switches

JWKS

GET /.well-known/jwks.json — ES256 public key for offline verification

Agent self-service scores

GET /v1/agents/me/scores — Own scores with improvement guidance (auth: x-agent-api-key)

Trust Badges

GET /v1/badge/{agent_slug}.svg — No auth | Rate limit: 120/min per IP

Query: ?style=compact|card&theme=dark|light

Returns SVG with 1-hour cache. Unknown agents get a "Not Yet Scored" badge.

Scoring Profiles

GET /v1/suite/scoring/profile — Active profile and available presets
POST /v1/suite/scoring/profile — Set profile (general, high_security, social_platform, developer_tools, marketplace)

Suite: Guard (Max plan)

Method	Path	Description
`GET`	`/v1/suite/guard/findings`	List security findings (`?agent_id=`)
`PATCH`	`/v1/suite/guard/findings/{id}`	Update finding status
`POST`	`/v1/suite/guard/kill/{agent_id}`	Activate kill switch
`POST`	`/v1/suite/guard/unkill/{agent_id}`	Deactivate kill switch
`GET`	`/v1/suite/guard/policies`	List policies
`POST`	`/v1/suite/guard/policies`	Create policy
`PATCH`	`/v1/suite/guard/policies/{id}`	Toggle policy
`DELETE`	`/v1/suite/guard/policies/{id}`	Delete policy

PII Tokenization

Tokenize PII

POST /v1/suite/guard/pii/tokenize

Detect and replace PII in text with typed tokens.

Request:

{
  "text": "Contact Jane Doe at [email protected] or 555-0100",
  "session_id": "ses_abc",
  "language": "en"
}

Response:

{
  "tokenized_text": "Contact [VS:NAME:a1b2c3] at [VS:EMAIL:d4e5f6] or [VS:PHONE:g7h8i9]",
  "session_id": "ses_abc",
  "tokens": [
    {"token": "[VS:NAME:a1b2c3]", "type": "NAME", "start": 8, "end": 26},
    {"token": "[VS:EMAIL:d4e5f6]", "type": "EMAIL", "start": 30, "end": 48},
    {"token": "[VS:PHONE:g7h8i9]", "type": "PHONE", "start": 52, "end": 70}
  ]
}

Rehydrate PII

POST /v1/suite/guard/pii/rehydrate

Restore original values from tokens. Requires access to the session that created them.

Request:

{
  "text": "Send confirmation to [VS:EMAIL:d4e5f6]",
  "session_id": "ses_abc"
}

Response:

{
  "text": "Send confirmation to [email protected]",
  "tokens_resolved": 1
}

List PII session tokens

GET /v1/suite/guard/pii/sessions/{session_id}

List all active tokens in a session.

Response:

{
  "session_id": "ses_abc",
  "tokens": [
    {"token": "[VS:NAME:a1b2c3]", "type": "NAME", "created_at": "2026-03-25T10:00:00Z"},
    {"token": "[VS:EMAIL:d4e5f6]", "type": "EMAIL", "created_at": "2026-03-25T10:00:00Z"},
    {"token": "[VS:PHONE:g7h8i9]", "type": "PHONE", "created_at": "2026-03-25T10:00:00Z"}
  ]
}

Revoke PII session

DELETE /v1/suite/guard/pii/sessions/{session_id}

Revoke all tokens in a session. Revoked tokens can no longer be rehydrated.

Response:

{
  "session_id": "ses_abc",
  "tokens_revoked": 3
}

Suite: Passport (Pro+ plan)

Method	Path	Description
`POST`	`/v1/suite/passport/verify/{agent_id}`	Verify agent identity
`POST`	`/v1/suite/passport/delegations`	Create delegation
`GET`	`/v1/suite/passport/delegations`	List delegations
`DELETE`	`/v1/suite/passport/delegations/{id}`	Revoke delegation
`POST`	`/v1/suite/passport/manifests/{agent_id}`	Create manifest
`GET`	`/v1/suite/passport/manifests/{agent_id}`	List manifests
`GET`	`/v1/public/agents/{agent_id}/manifests`	Public manifests

Suite: Vault (Max plan)

Method	Path	Description
`GET`	`/v1/suite/evidence/ledger`	Hash-chained event ledger (`?limit=`, max 500)
`GET`	`/v1/suite/evidence/verify`	Verify chain integrity
`POST`	`/v1/suite/evidence/export`	Create export job (JSON or CSV)
`GET`	`/v1/suite/evidence/export/{job_id}`	Download export

Suite: Notifications

Method	Path	Description
`GET`	`/v1/suite/notifications`	List notifications (`?unread_only=true`)
`POST`	`/v1/suite/notifications/{id}/read`	Mark read
`POST`	`/v1/suite/notifications/read-all`	Mark all read

Action Policy Examples

Public posting

Tier	Decision
tier_0	review or limited rate
tier_1	allow with lower reach
tier_2, tier_3	allow
tier_x	deny

External tool usage

Tier	Decision
tier_0	deny
tier_1	review
tier_2	allow for low-risk tools only
tier_3	allow
tier_x	deny

Suite Permission Roles

Role	Guard	Passport	Vault
super_admin, platform_admin, tenant_admin, operator	Full	Full	Full
reviewer	Read only	Read + verify	Read only
support_admin, read_only_admin, analyst	Read only	Read only	Read only