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": "owner@example.com", "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": "owner@example.com", "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 jane@example.com 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 jane@example.com",
  "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/vault/ledger	Vault ledger (?limit=, max 500)
GET	/v1/suite/vault/verify	Verify Vault chain integrity
POST	/v1/suite/vault/export	Create Vault export job (JSON or CSV)
GET	/v1/suite/vault/export/{job_id}	Download Vault export

Widget Chat

Method	Path	Description
POST	/v1/agents/widget/chat	Public widget chat (auth: widget token)
POST	/v1/agents/widget/secure-chat	Secure widget chat (auth: session token)
POST	/v1/agents/widget/session	Create a widget session token (auth: API key)

See Widget Chat docs for full configuration and embed details.

LLM / Cortex

Method	Path	Description
POST	/v1/agents/llm/chat	Send a message and receive a complete response
POST	/v1/agents/llm/stream	Send a message and receive a streamed SSE response

IP Allowlist

Method	Path	Description
GET	/v1/public/providers/ip-allowlist	List allowed IP ranges
PUT	/v1/public/providers/ip-allowlist	Set allowed IP ranges (replaces existing list)

Custom Domain

Method	Path	Description
GET	/v1/public/providers/custom-domain	Get custom domain configuration
PUT	/v1/public/providers/custom-domain	Set custom domain
DELETE	/v1/public/providers/custom-domain	Remove custom domain

Team / Workspace

Method	Path	Description
GET	/v1/public/accounts/team	List workspace members
POST	/v1/public/accounts/team/invite	Invite a member by email
POST	/v1/public/accounts/team/{member_id}/role	Change member role
DELETE	/v1/public/accounts/team/{member_id}	Remove member from workspace
POST	/v1/public/accounts/workspace/switch	Switch active workspace

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

---

Compliance

OWASP Attestation

GET /v1/compliance/owasp-attestation

Per-tenant OWASP Agentic AI Top 10 coverage report. Returns coverage status (covered/partial/gap) for each of the 10 risks, evidence counts, and overall score.

Auth: x-api-key or x-account-access-token

Compliance Frameworks

GET /v1/compliance/frameworks

List available compliance frameworks. Counsel-reviewed: eu-ai-act, nist-ai-rmf, iso-42001. Technical preview (mapped from live posture): 42-cfr-part-2, colorado-ai-act, us-state-conv, ny-raise-act, california-sb-53. Each entry carries a technical_preview: true flag when applicable.

GET /v1/compliance/{framework_id}

Per-tenant compliance report for a specific framework. Returns pass/warn/fail per control with evidence counts and recommendations.

Auth: x-api-key or x-account-access-token

---

Cedar Policies

Method	Path	Description
GET	/v1/policies	List active policies for tenant
POST	/v1/policies	Create a Cedar policy (Max/Enterprise only)
GET	/v1/policies/{id}	Get policy with full Cedar text
PUT	/v1/policies/{id}	Update policy (increments version)
DELETE	/v1/policies/{id}	Soft-delete policy
POST	/v1/policies/validate	Validate Cedar syntax
POST	/v1/policies/test	Dry-run policy against test input

Auth: x-api-key or x-account-access-token

---

SRE & Observability

Method	Path	Description
GET	/v1/analytics/sre/dashboard	Combined SRE dashboard (circuit breakers + SLO + error budget + provider health)
GET	/v1/analytics/sre/circuit-breakers	Circuit breaker states per LLM provider
POST	/v1/analytics/sre/circuit-breakers/{provider}/{model}/reset	Reset a circuit breaker
GET	/v1/analytics/sre/error-budget	Error budget status based on SLO targets
GET	/v1/analytics/sre/slo-config	Get tenant SLO configuration
PUT	/v1/analytics/sre/slo-config	Update SLO targets

Auth: x-api-key or x-account-access-token

---

Context Governance

Method	Path	Description
GET	/v1/analytics/context/dashboard	Combined context governance (topics + quality + gaps)
GET	/v1/analytics/context/topics	Event topic distribution and trending
GET	/v1/analytics/context/quality	KB coverage, event health, per-agent breakdown
GET	/v1/analytics/context/gaps	Knowledge gap detection (high-failure agents with low KB)

Auth: x-api-key or x-account-access-token

---

Guard Extensions

Method	Path	Description
POST	/v1/guard/scan-mcp	Scan MCP tool definitions for security risks (6 checks)
POST	/v1/guard/verify	Cross-model verification (majority-voting LLM consensus)

Auth: x-api-key or x-account-access-token (Guard plan required)

---

A2A Extensions

POST /v1/a2a/{agent_id}/keys — Provision Ed25519 transport keys for an agent.

Task submissions now accept optional signature envelope for Ed25519-signed messages. Agent cards include x-veriswarm-transport extension when keys are provisioned.

Auth: x-api-key or x-account-access-token

---

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