{"openapi":"3.1.0","info":{"title":"Passport Trust Substrate API","version":"1.0.0","description":"Portable, tamper-evident signed behavioral receipts, identity commitments, and agent protocol endpoints for autonomous AI agents.","contact":{"name":"Passport Operator","url":"https://passport.metis.gold"},"license":{"name":"MIT"}},"servers":[{"url":"https://passport.metis.gold","description":"Production Server"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"pp_<64-hex>","description":"Operator API Key. Obtain from /admin/api-keys or Stripe subscription checkout."},"SessionAuth":{"type":"apiKey","in":"cookie","name":"session_token","description":"Operator web session cookie."}},"schemas":{"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"GateVerifyRequest":{"type":"object","required":["operator_id","domain"],"properties":{"operator_id":{"type":"string","description":"Public operator ID (op_cus_...)"},"domain":{"type":"string","enum":["FINANCIAL_CLEARING","CUSTOMER_SUPPORT","CODE_GENERATION","SYSTEM_INTEGRATION"]}}},"GateVerifyResponse":{"type":"object","required":["allow_invocation"],"properties":{"allow_invocation":{"type":"boolean"},"reason":{"type":"string"}}},"ReceiptIssueRequest":{"type":"object","required":["agent_id","receipt_type","input_digest","authority_scope","expiry"],"properties":{"agent_id":{"type":"string"},"receipt_type":{"type":"string","enum":["custody","competence"]},"input_digest":{"type":"string","pattern":"^[0-9a-f]{64}$"},"authority_scope":{"type":"string"},"expiry":{"type":"string","format":"date-time"},"domain":{"type":"string"},"prev_receipt_hash":{"type":"string"},"blind":{"type":"boolean"}}},"EvidenceIngestRequest":{"type":"object","required":["source_type","payload","signature"],"properties":{"source_type":{"type":"string","enum":["github_push_webhook","github_commit_payload","github_issue_event","compliance_report","otel_genai_trace","task_deliverable"]},"payload":{"type":"object","description":"Parsed JSON object matching the source_type schema. Never send as raw string."},"signature":{"type":"string","pattern":"^[0-9a-f]{128}$","description":"Ed25519 signature over sha256(canonicalJson(payload))"}}}}},"paths":{"/api/health":{"get":{"summary":"Database Liveness Probe","responses":{"200":{"description":"Service healthy"},"503":{"description":"Service degraded"}}}},"/api/v1/public-key":{"get":{"summary":"Published Ed25519 Verifying Key","responses":{"200":{"description":"Published public key with kid rotation metadata"}}}},"/api/v1/gate/verify":{"post":{"summary":"Evaluate Gate Pass for Operational Domain","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GateVerifyRequest"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GateVerifyResponse"}}}}}}},"/api/v1/receipts":{"get":{"summary":"Search Receipts","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"List of operator receipts"}}},"post":{"summary":"Issue a Pending Signed Receipt","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReceiptIssueRequest"}}}},"responses":{"201":{"description":"Receipt issued and signed"}}}},"/api/v1/receipts/{id}/public-manifest":{"get":{"summary":"Get Public Receipt Manifest for Offline Verification","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Receipt manifest with Ed25519 signature and inclusion path"}}}},"/api/v1/passport/agents/{id}/evidence":{"post":{"summary":"Ingest Signed Agent Evidence","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvidenceIngestRequest"}}}},"responses":{"201":{"description":"Evidence anchored with event_commitment_hash"}}}},"/.well-known/agent.json":{"get":{"summary":"Google A2A Agent Card Discovery","responses":{"200":{"description":"A2A Agent Card"}}}},"/api/v1/a2a/tasks":{"post":{"summary":"A2A JSON-RPC 2.0 Task Delegation (send/get/cancel/list — requires a Bearer API key)","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"JSON-RPC 2.0 Task Response"}}}},"/api/v1/acp/task":{"post":{"summary":"ACP Task Create with Escrow Lock","security":[{"ApiKeyAuth":[]}],"responses":{"201":{"description":"ACP Task created"}}}},"/.well-known/did.json":{"get":{"summary":"W3C DID Document for Passport Controller","responses":{"200":{"description":"DID Document"}}}},"/api/v1/anp/agents/{commitment}":{"get":{"summary":"W3C Agent DID Document with did:key","parameters":[{"name":"commitment","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Agent DID Document"}}}},"/api/v1/agora/negotiate":{"post":{"summary":"AGORA Protocol Agreement Proposal (requires a Bearer API key)","security":[{"ApiKeyAuth":[]}],"responses":{"201":{"description":"Proposal recorded on capability ledger"}}}},"/api/v1/credentials/{commitment}":{"get":{"summary":"Issue Signed W3C Verifiable Credential for Agent Reputation","parameters":[{"name":"commitment","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"W3C AgentReputationCredential (JSON-LD)"}}}},"/api/v1/credentials/verify":{"post":{"summary":"Verify any W3C AgentReputationCredential Offline / Self-Contained","responses":{"200":{"description":"Verification success"},"422":{"description":"Tampered or invalid signature"}}}},"/api/v1/transparency/keys":{"get":{"summary":"Public Append-Only Key Transparency Log","responses":{"200":{"description":"Log of all verifier signing keys with validity windows"}}}},"/api/v1/receipts/checkpoints/latest":{"get":{"summary":"Get Latest Ed25519-Signed Merkle Checkpoint Root over Finalized Receipts","responses":{"200":{"description":"Signed Merkle checkpoint anchor"}}}},"/api/v1/compliance/packages/{commitment}":{"get":{"summary":"Generate Audit-Grade Compliance Package (NIST AI RMF / EU AI Act / SOC2)","parameters":[{"name":"commitment","in":"path","required":true,"schema":{"type":"string"}},{"name":"framework","in":"query","required":false,"schema":{"type":"string","enum":["NIST_AI_RMF","EU_AI_ACT","SOC2_TYPE2","ISO_42001"]}}],"responses":{"200":{"description":"Signed compliance evidence package"}}}},"/api/v1/compliance/frameworks":{"get":{"summary":"List Supported Compliance Frameworks & Control Mappings","responses":{"200":{"description":"List of frameworks"}}}},"/api/v1/datacenter/evidence":{"post":{"summary":"Ingest Data Center Power, Thermal, and Carbon Telemetry (Issuer-key authenticated)","security":[{"ApiKeyAuth":[]}],"responses":{"201":{"description":"Evidence ingested and signed receipt generated"},"401":{"description":"Unauthorized: valid Bearer API key required"},"403":{"description":"Forbidden: Holder keys cannot anchor fleet telemetry"}}}},"/api/v1/datacenter/clusters/{id}/scorecard":{"get":{"summary":"Get Data Center Cluster Efficiency Scorecard","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cluster energy scorecard"}}}},"/api/v1/datacenter/clusters/{id}/credential":{"get":{"summary":"Issue Signed W3C Data Center Sustainability Credential","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"W3C DataCenterSustainabilityCredential"}}}},"/api/v1/datacenter/receipts":{"get":{"summary":"List Data Center Cryptographic Receipts with Merkle Root Anchor","responses":{"200":{"description":"List of data center receipts"}}}},"/api/v1/datacenter/compliance/packages/{id}":{"get":{"summary":"Generate Data Center Regulatory Compliance Package (EU AI Act, ISO 14064, NIST)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Signed compliance evidence package"}}}},"/api/v1/passport/agents/autonomous/challenge":{"post":{"summary":"Request Ephemeral Nonce with Proof-of-Work Challenge for Autonomous Provisioning","responses":{"200":{"description":"Challenge nonce and difficulty"}}}},"/api/v1/passport/agents/autonomous/provision":{"post":{"summary":"Complete Autonomous Agent Self-Provisioning with PoW and Proof of Possession","responses":{"201":{"description":"Autonomous Holder API key and Passport issued"}}}},"/api/v1/metered/credentials/{commitment}":{"post":{"summary":"Premium credit-metered portable reputation credential issuance (Reputation-as-a-Service)","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"commitment","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Metered credential issued with meter receipt"},"401":{"description":"Unauthorized"},"402":{"description":"Insufficient credits"}}}},"/api/v1/compliance/audit-package/{commitment}":{"get":{"summary":"Assemble compliance_report receipts into a signed audit-grade evidence package (SOC2 / ISO 27001 / ISO 42001)","parameters":[{"name":"commitment","in":"path","required":true,"schema":{"type":"string"}},{"name":"framework","in":"query","required":false,"schema":{"type":"string","enum":["SOC2_TYPE2","ISO_27001","ISO_42001"]}}],"responses":{"200":{"description":"Signed audit evidence package"},"404":{"description":"No compliance_report evidence"}}}},"/api/v1/agent-pay/wallet":{"get":{"summary":"Read the agent/operator wallet credit balance (agentic payments)","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Wallet balance"}}}},"/api/v1/agent-pay/spend":{"post":{"summary":"Authorize a scoped agent payment for an attestation product (agentic payments)","security":[{"ApiKeyAuth":[]}],"responses":{"201":{"description":"Spend authorized with payment digest"},"402":{"description":"Insufficient credits / scope violation"}}}},"/api/v1/agent-pay/settlement":{"post":{"summary":"Inbound settlement from external agentic rail (Stripe agent, Visa, x402, Mastercard) — HMAC-authenticated, idempotent","security":[{"ApiKeyAuth":[]}],"responses":{"201":{"description":"Settlement credited to wallet"}}}},"/api/v1/agent-pay/withdraw":{"post":{"summary":"Burn ANGL and queue an on-chain payout to the commitment's custodial wallet (proof-of-payout receipt returned)","security":[{"ApiKeyAuth":[]}],"responses":{"201":{"description":"Withdrawal applied + receipt id"},"403":{"description":"Not owner of wallet"}}}},"/api/v1/account/topup":{"post":{"summary":"Create a one-time Stripe Checkout session accepting USDC to credit Operator.credits","responses":{"200":{"description":"Checkout session (url / clientSecret)"},"400":{"description":"Invalid amount"}}}},"/api/v1/account/wallet":{"get":{"summary":"Return (or create on first touch) the operator's custodial wallet","responses":{"200":{"description":"Operator wallet"}}}},"/api/v1/datacenter/documentation":{"get":{"summary":"Facility documentation manifest — what Passport documents for a data center","responses":{"200":{"description":"Documentation manifest"}}}},"/api/v1/passport/agents/{id}/governance":{"get":{"summary":"Composed agent wallet + live status + access tier + recent credit journal (dashboard)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Governance snapshot"},"404":{"description":"No account/journal"}}}},"/api/v1/webhooks/verify-guide":{"get":{"summary":"Receiver verification reference — algorithm + example for verifying webhook signatures/timestamps","responses":{"200":{"description":"Verification guide"}}}},"/api/v1/badge/{hash}/attestation":{"get":{"summary":"Shareable 'Passport Verified — Authenticated AI Build' attestation card (SVG) with ?format=json metadata","parameters":[{"name":"hash","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Attestation SVG card or JSON metadata"}}}},"/api/v1/artifacts/{commitment}/{artifact}/attestation":{"get":{"summary":"Per-artifact authenticity assertion — authenticate a specific artifact (commit SHA or evidence hash) to its agent","parameters":[{"name":"commitment","in":"path","required":true,"schema":{"type":"string"}},{"name":"artifact","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Artifact attestation (JSON or SVG card)"}}}}}}