API Reference

Every integration surface documented. REST endpoints, MCP tools, and SDK APIs.

REST Endpoints

POST /v1/notarize

Submit a disclosure for cryptographic notarization. Returns an Evidence Packet with COSE_Sign1 envelope, RFC 3161 timestamp, and PDF certificate.

Field Type Required Description
disclosure_type string Yes Type of disclosure: ai_generated_text, dora_incident, pld_rebuttal
content string Yes The content to be notarized (text body)
model_id string No Identifier of the AI model that generated the content
metadata object No Arbitrary key-value metadata (max 18 fields in trustlayer envelope)
token_ids array[string] No Token IDs for visible watermark stamp on PDF

Response (201 Created)

{
  "cert_id": "cert_01H8X...",
  "cose_sign1_b64": "oWx0aGV...",
  "pdf_url": "/packets/cert_01H8X.../pdf",
  "json_url": "/packets/cert_01H8X.../json",
  "verification_url": "/v1/verify/cert_01H8X...",
  "timestamp_token": "MIIbqg...",
  "chain_position": 42
}

GET /v1/verify/{cert_id}

Public verification endpoint. No authentication required. Returns the verification status and cryptographic proof components.

Response (200 OK)

{
  "cert_id": "cert_01H8X...",
  "status": "Valid",
  "protected_header": {
    "alg": "EdDSA",
    "hash": "BLAKE3",
    "primary_key_fingerprint": "sha256:..."
  },
  "timestamp": {
    "authority": "Actalis Italia",
    "token": "MIIbqg...",
    "status": "Valid"
  },
  "scitt_receipt": {
    "receipt_type": "RFC 9943",
    "inclusion_proof": { ... }
  },
  "chain_position": 42,
  "verification_steps": [
    "1. Verify COSE_Sign1 signature against public key",
    "2. Validate RFC 3161 timestamp token",
    "3. Verify SCITT receipt Merkle inclusion proof",
    "4. Check BLAKE3 hash chain integrity"
  ]
}

GET /v1/dora/evidence-pack

DORA compliance evidence pack. Returns per-check status for 7 DORA Article 19-20 compliance checks.

Response (200 OK)

{
  "checks": [
    { "id": "DORA-01", "name": "ICT Risk Management", "status": "Covered" },
    { "id": "DORA-02", "name": "Incident Reporting", "status": "Covered" },
    { "id": "DORA-03", "name": "Digital Operational Resilience", "status": "Covered" },
    { "id": "DORA-04", "name": "Third-Party Risk", "status": "Covered" },
    { "id": "DORA-05", "name": "Information Sharing", "status": "Covered" },
    { "id": "DORA-06", "name": "Testing", "status": "Covered" },
    { "id": "DORA-07", "name": "AI-Specific Oversight", "status": "NotYetEvidenced" }
  ],
  "rollup": "Compliant"
}

MCP Tools

TRAI exposes 37 tools via MCP (Model Context Protocol) for integration with Claude Code, Cursor, and Codex. The tools are organized into two tiers:

Tier Tools Purpose
v1 (7 tools) Core evidence operations Notarize, verify, timestamp, sign, hash, chain inspect, certificate lookup
v2 (30 tools) Extended compliance operations Compliance mappers (DORA, EU AI Act, ISO 42001, NIST AI RMF), risk scoring, audit trail, watermark detection, SDK operations

Key MCP tools

Tool Description
trai_notarize Submit content for cryptographic notarization
trai_verify Verify a certificate by ID
trai_sign Sign content with Ed25519 or ML-DSA-65
trai_timestamp Request an RFC 3161 timestamp
trai_hash Compute BLAKE3 hash of content
trai_chain_inspect Inspect BLAKE3 hash chain position
trai_compliance_map Map evidence to a compliance framework
trai_dora_assess Run DORA dynamic assessment
trai_watermark_detect Detect text watermarks via Kirchenbauer z-test
trai_pdf_render Render A4 PDF certificate with QR code

The MCP server runs via stdio JSON-RPC. See crates/tl-mcp-server/ for the full tool list and rule_of_two.rs for data-flow invariants.

SDK Surfaces

SDK Engine Key Functions
Python (heavy) PyO3 wheel via maturin trai.sign(), trai.verify(), trai.notarize(), trai.hash()
Python (light) Pure HTTP client TraiClient.notarize(), TraiClient.verify()
TypeScript HTTP + WASM bundle (108KB) notarize(), verify(), hash(), getChain(), renderPdf()
Go Pure Go (BLAKE3 via zeebo/blake3) trai.Verify(), trai.Hash(), trai.Notarize()

WASM browser verification

The TypeScript SDK includes a WASM bundle that performs COSE_Sign1 verification entirely in-browser. No public third-party service is involved. The bundle is 108KB / 53.6KB gzipped. 

// Browser verification (no server required)
import { verify } from '@trai/core';

const result = await verify(certificateBytes);
console.log(result.status);  // "Valid" | "Invalid" | "TimestampExpired"
console.log(result.protectedHeader);  // { alg, hash, fingerprint }

API endpoints and SDK functions are subject to change between versions. See the source code for the current implementation. All claims are independently verifiable against the test suites.