SWT3 API Reference

Lightweight health check. No authentication required. Use for uptime monitoring.

Response (200)

{
  "status": "healthy",
  "version": "5.42.0",
  "uptime": 1234567,
  "checks": {
    "supabase": true,
    "timestamp": "2026-08-13T12:00:00.000Z"
  }
}

Response (503 -- Degraded)

{
  "status": "degraded",
  "checks": { "supabase": false }
}

Curl

curl -s https://sovereign.tenova.io/api/v1/health | jq .

Tip: Point your monitoring tool (Datadog, UptimeRobot, Pingdom) at this endpoint. Alert on non-200 status or supabase: false.

Ingest a single witness payload. The server re-derives the fingerprint, evaluates the verdict deterministically, writes to the ledger, and returns a receipt.

Request Body

Response (200)

{
  "procedure_id": "AI-INF.1",
  "verdict": "PASS",
  "swt3_anchor": "SWT3-E-VULTR-AI-AI-INF.1-PASS-1773316622-2e16e2fe92dd",
  "clearing_level": 1,
  "witnessed_at": "2026-08-13T12:00:00.000Z",
  "verification_url": "/api/v1/attest/verify?token=SWT3-E-VULTR-AI-AI-INF.1-PASS-1773316622-2e16e2fe92dd",
  "signature_verified": true
}

Validation Rules

• Timestamp bounds: fingerprint_timestamp_ms must be within the last 24 hours and no more than 5 minutes in the future.
• Fingerprint integrity: The server re-derives SHA256("WITNESS:{tenant}:{proc}:{fa}:{fb}:{fc}:{ts_ms}") and compares the first 12 hex chars. If they differ, the request is rejected (factors tampered in transit).
• Clearing level: Must be 0, 1, 2, or 3.
• Procedure ID: Must be one of the 113 recognized AI procedures. Unknown IDs return 400 with the full list.
• Lifecycle chain ID: If provided, must match LC-[0-9a-f]{16}.
• Lifecycle stage: If provided, must be one of: initiated, checkpoint, escalated, resolved, abandoned, superseded.

Error Responses

Examples

curl -X POST https://sovereign.tenova.io/api/v1/witness \
  -H "Authorization: Bearer $SWT3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "procedure_id": "AI-INF.1",
    "factor_a": 1,
    "factor_b": 1,
    "factor_c": 0,
    "clearing_level": 1,
    "anchor_fingerprint": "2e16e2fe92dd",
    "anchor_epoch": 1774800000,
    "fingerprint_timestamp_ms": 1774800000000,
    "ai_model_id": "gpt-4o"
  }'

# The SDK handles fingerprint minting, clearing, and flushing.
# You never need to call the API directly.
from swt3_ai import Witness

witness = Witness(
    api_key="axm_live_...",
    tenant_id="YOUR_TENANT",
    clearing_level=1
)

# Wrap your OpenAI client -- all inferences are witnessed automatically
import openai
client = witness.wrap(openai.OpenAI())

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}]
)
# Anchor minted, cleared, and queued for flush. Zero blocking.

// The SDK handles fingerprint minting, clearing, and flushing.
import { Witness } from "@tenova/swt3-ai";
import OpenAI from "openai";

const witness = new Witness({
  apiKey: "axm_live_...",
  tenantId: "YOUR_TENANT",
  clearingLevel: 1
});

const client = witness.wrapTool(new OpenAI());

const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello" }]
});
// Anchor minted, cleared, and queued for flush.

Ingest up to 500 witness payloads in a single request. Each payload is validated independently -- partial success is possible.

Request Body

{
  "witnesses": [
    { "procedure_id": "AI-INF.1", "factor_a": 1, ... },
    { "procedure_id": "AI-GRD.1", "factor_a": 2, ... }
  ]
}

Response (200)

{
  "results": [
    { "procedure_id": "AI-INF.1", "verdict": "PASS", "swt3_anchor": "SWT3-..." },
    { "procedure_id": "AI-GRD.1", "verdict": "PASS", "swt3_anchor": "SWT3-..." }
  ],
  "accepted": 2,
  "rejected": 0
}

Limits

• Maximum 500 payloads per batch request.
• Each payload counts against your per-second rate limit.
• Rejected payloads include an error field in the results array.

Retrieve all anchors in a lifecycle chain. Used for forensic reconstruction of multi-step processes (emergency overrides, champion-challenger assessments).

Response (200)

{
  "chain_id": "LC-a1b2c3d4e5f67890",
  "anchors": [
    { "stage": "initiated", "procedure_id": "AI-EMRG.1", "verdict": "PASS", ... },
    { "stage": "escalated", "procedure_id": "AI-EMRG.1", "verdict": "PASS", ... },
    { "stage": "resolved", "procedure_id": "AI-EMRG.1", "verdict": "PASS", ... }
  ],
  "integrity": "verified"
}

Structural validation of a SWT3 Witness Anchor. Decomposes the token and verifies format integrity.

Response (200)

{
  "valid": true,
  "tier": "E",
  "tier_label": "Enclave",
  "provider": "VULTR",
  "uct": "AI",
  "procedure_id": "AI-INF.1",
  "verdict": "PASS",
  "timestamp": "2026-08-13T12:00:00.000Z",
  "fingerprint": "2e16e2fe92dd"
}

Curl

curl "https://sovereign.tenova.io/api/v1/verify/public?token=SWT3-E-VULTR-AI-AI-INF.1-PASS-1773316622-2e16e2fe92dd"

Verify an HMAC-signed Compliance Passport or a W3C Verifiable Credential.

Request (HMAC Passport)

{ "passport": "<base64-encoded HMAC-signed passport>" }

Request (W3C Verifiable Credential)

{ "credential": { "@context": [...], "type": [...], "proof": {...} } }

Response (200)

{
  "valid": true,
  "signature_valid": true,
  "expired": false,
  "passport_id": "PSP-a1b2c3d4",
  "format": "vc",
  "cryptosuite": "eddsa-jcs-2022"
}

Check the revocation status of a Verifiable Credential.

Response (200)

{
  "status": "active",   // "active", "revoked", or "unknown"
  "passport_id": "PSP-a1b2c3d4"
}

Export a vendor compliance summary in one of three formats, gated by subscription tier.

Create a webhook subscription. Maximum 10 subscriptions per tenant.

Request Body

{
  "url": "https://your-server.com/webhook",
  "event_types": ["verdict.failed", "drift.detected"],
  "description": "Slack alert pipeline"
}

Response (200)

{
  "id": "wh_abc123",
  "secret": "whsec_...",   // Shown once. Store securely.
  "is_active": true
}

List all webhook subscriptions. Secrets are masked.

Send a test ping event to verify your endpoint receives and processes webhooks correctly. Returns the delivery result.

View delivery history for a webhook subscription. Includes HTTP status codes, response bodies, and retry status.

Update a subscription (URL, event types, active status).

Delete a webhook subscription. Existing delivery history is retained.

AI witness posture summary: total anchors, procedure coverage, model inventory with drift status.

Auditor-ready JSON export of all AI witness evidence. Suitable for import into assessment tools.

Compute the daily Merkle root for your tenant. Domain-separated hashing (SWT3:LEAF: and SWT3:NODE: prefixes).

Request Body (optional)

{ "date": "2026-08-13" }  // defaults to today

Response (200)

{
  "merkle_root": "a1b2c3d4e5f6...",
  "date": "2026-08-13",
  "anchor_count": 47
}

List Merkle rollups for the last N days (default 30).

Get an inclusion proof for a specific anchor fingerprint. Returns the Merkle path for independent verification.

Response (200)

{
  "proof": [
    { "hash": "abc123...", "direction": "L" },
    { "hash": "def456...", "direction": "R" }
  ],
  "root": "a1b2c3d4e5f6...",
  "verified": true
}

System Security Plan in OSCAL JSON format.

Plan of Action and Milestones. Includes risk-level mapping, milestone dates, and overdue flags.

Assessment Results. Findings, objective coverage, and procedures exercised.

Complete package: SSP + POA&M + AR + cross-validation report. Signed ZIP.

List all API keys for your tenant. Keys are masked (only prefix shown). Maximum 5 active keys per tenant.

Response (200)

{
  "keys": [
    {
      "key_id": "k_abc123",
      "key_prefix": "axm_live_7f3a...",
      "created_at": "2026-08-01T00:00:00Z",
      "last_used": "2026-08-13T11:30:00Z"
    }
  ]
}

Create a new API key. The raw key is returned exactly once in the response. Store it securely.

Response (200)

{
  "key": "axm_live_7f3a9b2c4d5e6f7890abcdef12345678",  // shown once
  "key_id": "k_abc123"
}

Revoke an API key. Immediate effect. Existing anchors are not affected. Action is logged to the audit trail.

Register an agent with a charter (tool authorization and scope limits).

Request Body

{
  "agent_id": "fraud-detector-v2",
  "agent_type": "llm",
  "charter": {
    "tools": ["search_transactions", "flag_suspicious"],
    "scopes": ["read:transactions"],
    "constraints": { "max_actions_per_minute": 100 }
  }
}

List all registered agents with status and charter hash.

Revoke an agent. Mints an AI-REV.1 anchor. Subsequent witness ingestion attempts by this agent return 506.

Request Body

{ "agent_id": "fraud-detector-v2", "reason": "policy_violation" }

Resolve a procedure ID across regulatory frameworks (e.g., NIST 800-53 to CMMC to EU AI Act).

Request Body

{
  "source_framework": "NIST-800-53",
  "source_control_id": "AC-2",
  "target_framework": "CMMC"
}

Response (200)

{
  "mappings": [
    { "target_control_id": "AC.L2-3.1.1", "mapping_type": "1:1", "confidence": 0.95 }
  ]
}

Full mapping matrix between two frameworks. 1,057 crosswalk rows across 36 frameworks.

Retrieve audit session metadata (tenant scope, frameworks, status).

Cryptographic proof chain for every verdict in the assessment scope. Includes Merkle proofs for independent verification.

Assessor submits a finding (severity, control_id, description). Does not modify verdicts.

Export the conformity evidence package (SWT3 Spec v1.0.1 format). Self-contained HTML or JSON.