API Reference

The ThoughtProof API lets you verify AI agent reasoning chains and receive cryptographically signed receipts — before your agent acts.

All responses are JSON. Receipts are signed with Ed25519 (EdDSA). Public keys at /.well-known/jwks.json. Machine-readable spec at /openapi.json.

https://api.thoughtproof.ai

Quickstart

Three steps to your first verified reasoning chain:

1. Get an API key (free, no credit card)

curl -X POST https://api.thoughtproof.ai/v1/operators \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent-app", "email": "you@example.com"}'

# Returns: {"apiKey": "tp_op_..."}

2. Register your agent

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"}'

# Returns: {"agentId": "agent_..."}

3. Verify a claim — get a signed receipt

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_YOUR_AGENT_ID",
    "claim": "Approve €500 payment to vendor-42 based on invoice #4421",
    "verdict": "VERIFIED",
    "domain": "finance"
  }'
{
  "receiptId": "rcpt_xK9mN2pQ4rT8sV",
  "verdict": "VERIFIED",
  "score": 0.915,
  "issuedAt": "2026-03-04T19:37:19Z",
  "expiresAt": "2026-06-02T19:37:19Z",
  "jwt": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...",
  "blockHash": "sha256:c6907568f69e486...",
  "verifyUrl": "/v1/receipts/rcpt_xK9mN2pQ4rT8sV"
}

Authentication

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

X-API-Key: tp_op_YOUR_API_KEY

Keys are prefixed tp_op_ (operator) or tp_live_ (agent). Get a free key via POST /v1/operators — no signup form, no credit card.

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 /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 verification receipt for an agent's claim. The receipt is an EdDSA JWT. Use it as an audit trail before any sensitive action.

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

VERIFIED   — Claim survived adversarial challenge at current trust score
UNVERIFIED — Claim failed adversarial challenge
UNCERTAIN  — Insufficient evidence to verify
DISSENT    — Verifiers disagree (flag for human review)
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 /.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 @pot-sdk2/bridge to call the API from your code:

npm install @pot-sdk2/bridge

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

const receipt = await quickVerify(
  "Approve €500 payment to vendor-42",
  {
    mode: 'remote',
    apiKey: 'tp_op_YOUR_KEY',
    agentId: 'agent_YOUR_AGENT_ID',
    verdict: 'VERIFIED',
    domain: 'finance',
  }
);

if (receipt.verdict === 'VERIFIED') {
  // proceed — receipt.jwt is your audit trail
  console.log('Receipt:', receipt.receiptId);
}

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