API Reference

ThoughtProof has two public surfaces: verify.thoughtproof.ai for PLV trace verification, and api.thoughtproof.ai for x402 discovery, signed receipts, JWKS, and wallet-bound issuer attestations.

API v2 returns public ALLOW | BLOCK | UNCERTAIN verdicts. Receipt services are signed with Ed25519 (EdDSA). Machine-readable specs: https://verify.thoughtproof.ai/openapi.json and https://api.thoughtproof.ai/openapi.json.

https://verify.thoughtproof.ai

Quickstart

Verify an AI-agent trace with the hosted PLV API v2:

1. Discover tiers

curl https://verify.thoughtproof.ai/v2/tiers

# default_tier: thorough_balanced
# public price: $0.06 / verification

2. Verify a reasoning trace

curl -X POST https://verify.thoughtproof.ai/v2/verify \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tp_v2_YOUR_KEY" \
  -d '{
    "question": "Should the agent approve invoice #4421?",
    "answer": "Approve €500 payment to vendor-42.",
    "trace": "Checked invoice, vendor history, and amount limits.",
    "plan_steps": [
      {"index": 0, "description": "Validate invoice authenticity", "criticality": "critical"},
      {"index": 1, "description": "Check vendor and amount policy", "criticality": "critical"}
    ],
    "mode": "faithfulness",
    "tier": "thorough_balanced"
  }'
{
  "id": "vrf_...",
  "verdict": "ALLOW",
  "confidence": 0.90,
  "schema_version": "plv-api-v2.0",
  "mode": "faithfulness",
  "steps": [...],
  "meta": { "tier": "thorough_balanced", "models_used": ["gemini", "sonnet"] }
}

3. x402 discovery for answer-level checks

curl https://api.thoughtproof.ai/v1/check

# Returns HTTP 402 with x402Version + accepts[] on Base USDC

Authentication

Include your API key in the X-API-Key header. No Bearer prefix.

X-API-Key: tp_v2_operator_secret

v2 keys use the tp_v2_... format. v1 receipt/operator keys may use tp_op_ or tp_live_.

MCP Integration (Cursor / Claude Desktop)

Add ThoughtProof as a tool to any MCP-compatible AI editor in two steps:

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "thoughtproof": {
      "command": "npx",
      "args": ["pot-mcp"],
      "env": { "TP_API_KEY": "tp_op_YOUR_KEY" }
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "thoughtproof": {
      "command": "npx",
      "args": ["pot-mcp"],
      "env": { "TP_API_KEY": "tp_op_YOUR_KEY" }
    }
  }
}

Your AI editor now has 5 tools: thoughtproof_verify, thoughtproof_score, thoughtproof_register_agent, thoughtproof_get_receipt, thoughtproof_record_event.

MCP server: npm install pot-mcp (MIT)

Endpoints

POST /v2/verify X-API-Key required

Trace-based PLV verification. Submit question, answer, trace, and plan_steps. Returns ALLOW/BLOCK/UNCERTAIN with per-step evidence. Optional Base EAS issuance is available for ALLOW verdicts.

curl -X POST https://verify.thoughtproof.ai/v2/verify \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tp_v2_YOUR_KEY" \
  -d '{"question":"...","answer":"...","trace":"...","plan_steps":[{"index":0,"description":"Check source","criticality":"critical"}]}'
GET /v2/tiers Public

Discover the six PLV tiers. Source of truth for public price_usd, tier status, default tier, and model routing.

curl https://verify.thoughtproof.ai/v2/tiers
GET /v1/check x402 discovery

Answer-level verification discovery endpoint. A GET returns HTTP 402 with a self-documenting x402 payment descriptor on Base USDC.

curl -i https://api.thoughtproof.ai/v1/check
POST /v1/operators No auth

Register a new operator and receive an API key. No signup form.

curl -X POST https://api.thoughtproof.ai/v1/operators \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-agent-app",
    "email": "you@example.com"
  }'
{
  "operatorId": "op_AAIh19KHmoohMz2l",
  "name": "my-agent-app",
  "apiKey": "tp_op_LLdmQTU6EGcGZKAUdIu...",
  "registeredAt": "2026-03-04T19:36:14Z",
  "note": "Store your apiKey securely — it is not retrievable."
}
POST /v1/agents X-API-Key required

Register an agent. Returns an agentId for trust tracking and an agent-scoped key.

curl -X POST https://api.thoughtproof.ai/v1/agents \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tp_op_YOUR_KEY" \
  -d '{
    "name": "payment-agent-v1",
    "description": "Handles vendor invoice payments"
  }'
{
  "agentId": "agent_OD_JD9t_8vvDW_5s",
  "name": "payment-agent-v1",
  "apiKey": "tp_live_9PAnnnl4YcRq...",
  "registeredAt": "2026-03-04T19:37:18Z",
  "note": "Store apiKey securely — it is not retrievable."
}
GET /v1/agents/:id/score Public

Retrieve the current trust score (0–1) for an agent. No auth required — scores are public.

curl https://api.thoughtproof.ai/v1/agents/agent_OD_JD9t_8vvDW_5s/score
{
  "agentId": "agent_OD_JD9t_8vvDW_5s",
  "name": "payment-agent-v1",
  "score": {
    "composite": 0.915,
    "impact": 0.95,
    "peer": 0.9,
    "adversarial": 0.85,
    "consistency": 0.95,
    "events": 1,
    "domains": ["finance"]
  },
  "eventCount": 1,
  "scoredAt": "2026-03-04T19:37:18Z"
}
POST /v1/agents/:id/events X-API-Key required

Record a verification event to update an agent's trust score over time.

curl -X POST https://api.thoughtproof.ai/v1/agents/agent_OD_JD9t_8vvDW_5s/events \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tp_op_YOUR_KEY" \
  -d '{
    "type": "verification",
    "outcome": "correct",
    "peerRating": 0.9,
    "adversarialScore": 0.85,
    "domain": "finance",
    "context": "Invoice check passed"
  }'
{ "recorded": true, "eventCount": 1, "currentScore": 0.915 }

Parameters

{
  "type":             "verification" | "peer_review" | "adversarial_test",
  "outcome":          "correct" | "incorrect" | "contested",
  "peerRating":       0.0 – 1.0,
  "adversarialScore": 0.0 – 1.0,  // 1 = survived adversarial challenge
  "domain":           string,      // e.g. "finance", "medical", "legal"
  "context":          string       // optional free-text
}
POST /v1/verify X-API-Key required

Issue a cryptographically signed receipt for an already-decided claim. This is the v1 receipt service, not the trace-verification engine. Use POST /v2/verify for PLV trace verification.

curl -X POST https://api.thoughtproof.ai/v1/verify \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tp_op_YOUR_KEY" \
  -d '{
    "agentId": "agent_OD_JD9t_8vvDW_5s",
    "claim": "Approve €500 payment to vendor-42 based on invoice #4421",
    "verdict": "VERIFIED",
    "domain": "finance",
    "metadata": {"invoiceId": "4421", "amount": "500"}
  }'
{
  "receiptId": "rcpt_ZWLFM5V5SZvHCPou",
  "agentId": "agent_OD_JD9t_8vvDW_5s",
  "agentName": "payment-agent-v1",
  "claim": "Approve €500 payment to vendor-42 based on invoice #4421",
  "verdict": "VERIFIED",
  "score": 0.915,
  "domain": "finance",
  "eventCount": 1,
  "issuedAt": "2026-03-04T19:37:19Z",
  "expiresAt": "2026-06-02T19:37:19Z",
  "jwt": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCIsImtpZCI6InRwLWF0dGVzdG9yLXYxIn0...",
  "blockHash": "sha256:c6907568f69e486ca11068dc244bbb200eeff6c93d0b78f191bd1eb7203afb30",
  "verifyUrl": "/v1/receipts/rcpt_ZWLFM5V5SZvHCPou"
}

Verdicts

Receipt verdicts are legacy v1 receipt labels.
PLV v2 public verification verdicts are: ALLOW | BLOCK | UNCERTAIN.
GET /v1/receipts/:id Public

Fetch a previously issued receipt. No auth required — receipts are publicly verifiable.

curl https://api.thoughtproof.ai/v1/receipts/rcpt_ZWLFM5V5SZvHCPou
GET /v1/issuer/wallet/:address Public

Return a signed wallet-bound ThoughtProof attestation for composed envelopes and multi-issuer orchestrators. Response includes both the machine score (score_normalized, 0–1) and a UI-friendly score (score_display, 0–100).

curl https://api.thoughtproof.ai/v1/issuer/wallet/0x742d35Cc6634C0532925a3b844Bc9e7595f7E2c1
{
  "issuer": "thoughtproof",
  "schema": "wallet_reasoning_integrity/v1",
  "wallet": "0x742d35Cc6634C0532925a3b844Bc9e7595f7E2c1",
  "found": true,
  "verdict": "VERIFIED",
  "score_normalized": 0.82,
  "score_display": 82,
  "score_scale": "0-1",
  "confidence_bps": 8200,
  "reason": "Wallet is linked to a registered agent with positive ThoughtProof receipts.",
  "evidence": {
    "attestationCount": 4,
    "latestAttestation": "rcpt_xK9mN2pQ4rT8sV",
    "source": "thoughtproof"
  },
  "issuedAt": "2026-04-11T00:00:00.000Z",
  "expiresAt": "2026-04-18T00:00:00.000Z",
  "signature": {
    "alg": "EdDSA",
    "kid": "tp-attestor-v1",
    "value": "base64url-signature"
  }
}

Score semantics: score_normalized is the canonical machine-readable score on a 0–1 scale. score_display is the same value mapped to 0–100 for UI. confidence_bps is the same confidence expressed in basis points (0–10,000).

GET /.well-known/jwks.json Public

Ed25519 public keys for verifying receipt JWTs offline.

curl https://api.thoughtproof.ai/.well-known/jwks.json
{
  "keys": [{
    "kty": "OKP", "crv": "Ed25519", "use": "sig",
    "alg": "EdDSA", "kid": "tp-attestor-v1",
    "x": "If4jWLtqPyz7dp97PxjbFoDgP0KU2I5H6oDSwJ_DoUE"
  }]
}
GET /openapi.json Public

Machine-readable OpenAPI 3.1 spec. Import into Postman, Insomnia, or any tool that supports OpenAPI.

curl https://api.thoughtproof.ai/openapi.json

JavaScript SDK

Use the hosted API directly, or self-host with pot-cli. Framework adapters remain thin integration layers:

npm install @pot-sdk2/bridge

import { quickVerify } from '@pot-sdk2/bridge';

const verdict = await fetch('https://verify.thoughtproof.ai/v2/verify', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-API-Key': 'tp_v2_YOUR_KEY' },
  body: JSON.stringify({ question, answer, trace, plan_steps })
}).then(r => r.json());

if (verdict.verdict === 'ALLOW') {
  // proceed — PLV verified the reasoning trace
}

Errors

400 Bad Request    — Missing required fields (agentId, claim, verdict)
401 Unauthorized   — Missing X-API-Key header
403 Forbidden      — Invalid API key
404 Not Found      — Agent or receipt not found
429 Too Many Req.  — Rate limit exceeded
500 Server Error   — Contact support@thoughtproof.ai

Questions? support@thoughtproof.ai · GitHub