{"openapi":"3.0.3","info":{"title":"Agent Action Receipts (Signed Tamper-Evident Audit Log) API","version":"1.0.0","description":"Issues and verifies HMAC-SHA256 signed, hash-chained, tamper-evident receipts of AI agent tool executions without storing raw PII."},"servers":[{"url":"https://api.tinplate.dev","description":"Production Edge Gateway"}],"components":{"schemas":{"ReceiptIssueResponseData":{"type":"object","properties":{"receipt_token":{"type":"string"},"receipt_hash":{"type":"string"},"kid":{"type":"string"},"issued_at":{"type":"string"},"expires_at":{"type":"string","nullable":true},"payload":{"type":"object","properties":{"ver":{"type":"number","enum":[1]},"jti":{"type":"string"},"iat":{"type":"integer"},"exp":{"type":"integer","nullable":true},"agent_id":{"type":"string"},"session_id":{"type":"string","nullable":true},"tool_name":{"type":"string"},"policy_decision":{"type":"string","enum":["allow","repaired","escalated","blocked"]},"input_sha256":{"type":"string"},"output_sha256":{"type":"string","nullable":true},"prev_hash":{"type":"string"}},"required":["ver","jti","iat","exp","agent_id","session_id","tool_name","policy_decision","input_sha256","output_sha256","prev_hash"]}},"required":["receipt_token","receipt_hash","kid","issued_at","expires_at","payload"]},"ReceiptIssueRequest":{"type":"object","properties":{"agent_id":{"type":"string","minLength":1,"maxLength":128,"example":"agent_finops_01"},"session_id":{"type":"string","minLength":1,"maxLength":128,"example":"sess_99a8b7"},"tool_name":{"type":"string","minLength":1,"maxLength":128,"example":"wire_transfer"},"action_input":{"nullable":true,"example":{"amount":2500,"currency":"EUR","iban":"DE89370400440532013000"}},"action_output":{"nullable":true,"example":{"status":"queued","tx_id":"tx_1001"}},"policy_decision":{"type":"string","enum":["allow","repaired","escalated","blocked"],"default":"allow"},"prev_receipt_hash":{"type":"string","maxLength":128,"default":"genesis"},"secret":{"type":"string","minLength":16,"maxLength":512,"example":"hmac-secret-key-at-least-16-bytes"},"kid":{"type":"string","minLength":1,"maxLength":64,"default":"v1"},"ttl_seconds":{"type":"integer","minimum":60,"maximum":315360000},"issued_at_epoch":{"type":"integer"}},"required":["agent_id","tool_name","secret"]},"ReceiptVerifyResponseData":{"type":"object","properties":{"valid":{"type":"boolean"},"chain_intact":{"type":"boolean"},"input_matched":{"type":"boolean","nullable":true},"output_matched":{"type":"boolean","nullable":true},"reason":{"type":"string","nullable":true},"verified_count":{"type":"integer"},"links":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"valid":{"type":"boolean"},"receipt_hash":{"type":"string"},"kid":{"type":"string","nullable":true},"reason":{"type":"string","nullable":true},"payload":{"type":"object","nullable":true,"properties":{"ver":{"type":"number","enum":[1]},"jti":{"type":"string"},"iat":{"type":"integer"},"exp":{"type":"integer","nullable":true},"agent_id":{"type":"string"},"session_id":{"type":"string","nullable":true},"tool_name":{"type":"string"},"policy_decision":{"type":"string","enum":["allow","repaired","escalated","blocked"]},"input_sha256":{"type":"string"},"output_sha256":{"type":"string","nullable":true},"prev_hash":{"type":"string"}},"required":["ver","jti","iat","exp","agent_id","session_id","tool_name","policy_decision","input_sha256","output_sha256","prev_hash"]}},"required":["index","valid","receipt_hash","kid","reason","payload"]}}},"required":["valid","chain_intact","input_matched","output_matched","reason","verified_count","links"]},"ReceiptVerifyRequest":{"type":"object","properties":{"receipt_token":{"type":"string","maxLength":16384},"chain":{"type":"array","items":{"type":"string","maxLength":16384},"minItems":1,"maxItems":200},"secret":{"type":"string","minLength":1,"maxLength":512},"keys":{"type":"object","additionalProperties":{"type":"string"}},"expected_input":{"nullable":true},"expected_output":{"nullable":true},"now_epoch":{"type":"integer"}}},"ResponseMeta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","format":"uuid"},"ms":{"type":"integer","minimum":0},"version":{"type":"string","example":"1.0.0"}}},"ErrorEnvelope":{"type":"object","required":["ok","error","meta"],"properties":{"ok":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"invalid_input"},"message":{"type":"string","example":"Request body failed validation"}}},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}}},"parameters":{}},"paths":{"/v1/agent-action-receipts/issue":{"post":{"tags":["29_AGENT_ACTION_RECEIPTS"],"summary":"Issue a signed, hash-chained receipt for an AI agent tool action","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReceiptIssueRequest"}}}},"responses":{"200":{"description":"Signed receipt token, receipt hash for chaining, and canonical payload","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/ReceiptIssueResponseData"},"meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["ok","data","meta"]}}}},"400":{"description":"Invalid input or malformed JSON request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid authentication credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request payload exceeds subscribed plan byte cap","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/agent-action-receipts/verify":{"post":{"tags":["29_AGENT_ACTION_RECEIPTS"],"summary":"Verify a single agent action receipt or an ordered hash-chain of receipts","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReceiptVerifyRequest"}}}},"responses":{"200":{"description":"Signature, hash-chain continuity, and input/output integrity verification result","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/ReceiptVerifyResponseData"},"meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["ok","data","meta"]}}}},"400":{"description":"Invalid input or malformed JSON request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid authentication credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request payload exceeds subscribed plan byte cap","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}