{"openapi":"3.0.0","info":{"title":"Kakunin API","version":"1.0.0","description":"KYC compliance infrastructure for AI agents. Issues X.509 certificates, monitors behavioral events, and generates MiCA/EU AI Act compliance reports.","contact":{"name":"Kakunin Support","email":"support@kakunin.ai","url":"https://docs.kakunin.ai"},"license":{"name":"Commercial","url":"https://kakunin.ai/terms"}},"servers":[{"url":"https://api.kakunin.ai","description":"Production"},{"url":"http://localhost:3000","description":"Local dev"}],"tags":[{"name":"Agents","description":"Register and manage AI agents"},{"name":"Certificates","description":"Issue, verify, and revoke X.509 certificates"},{"name":"Events","description":"Ingest behavioral events and risk scores"},{"name":"Webhooks","description":"Register and manage webhook endpoints"},{"name":"Audit","description":"Query append-only audit log"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key (kak_live_... or kak_test_...)"}},"schemas":{"ErrorResponse":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"FinancialScope":{"type":"object","properties":{"max_single_trade_usd":{"type":"number","minimum":0,"exclusiveMinimum":true},"daily_limit_usd":{"type":"number","minimum":0,"exclusiveMinimum":true},"permitted_instruments":{"type":"array","items":{"type":"string"}},"permitted_venues":{"type":"array","items":{"type":"string"}},"leverage_permitted":{"type":"boolean"},"max_leverage_ratio":{"type":"number","minimum":0,"exclusiveMinimum":true}},"required":["max_single_trade_usd","daily_limit_usd","permitted_instruments","permitted_venues","leverage_permitted"]},"Agent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenant_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"model":{"type":"string","nullable":true},"model_hash":{"type":"string"},"version":{"type":"string","nullable":true},"status":{"$ref":"#/components/schemas/AgentStatus"},"inbox_address":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","tenant_id","name","model","model_hash","version","status","inbox_address","metadata","created_at","updated_at"]},"AgentStatus":{"type":"string","enum":["pending","active","suspended","retired"]},"Certificate":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"agent_id":{"type":"string","format":"uuid"},"serial_number":{"type":"string"},"kms_key_arn":{"type":"string"},"certificate_pem":{"type":"string"},"status":{"type":"string","enum":["active","revoked","expired"]},"issued_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"revoked_at":{"type":"string","nullable":true,"format":"date-time"},"revocation_reason":{"type":"string","nullable":true}},"required":["id","agent_id","serial_number","kms_key_arn","certificate_pem","status","issued_at","expires_at","revoked_at","revocation_reason"]},"BehaviorEvent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"agent_id":{"type":"string","format":"uuid"},"action_type":{"type":"string","enum":["api_call","data_access","authentication","authorization","transaction","transaction_anomaly","model_inference","tool_use"]},"risk_score":{"type":"number","minimum":0,"maximum":1},"risk_band":{"type":"string","enum":["low","medium","high"]},"occurred_at":{"type":"string","format":"date-time"},"details":{"type":"object","additionalProperties":{"nullable":true}}},"required":["id","agent_id","action_type","risk_score","risk_band","occurred_at","details"]},"Webhook":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["certificate.issued","certificate.revoked","risk.alert","agent.halted"]}},"active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}},"required":["id","url","events","active","created_at"]},"AuditLog":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"event_type":{"type":"string"},"actor_type":{"type":"string","enum":["user","agent","system"]},"actor_id":{"type":"string"},"description":{"type":"string","nullable":true},"affected_id":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"created_at":{"type":"string","format":"date-time"}},"required":["id","event_type","actor_type","actor_id","description","affected_id","metadata","created_at"]}},"parameters":{}},"paths":{"/v1/agents":{"post":{"summary":"Register an AI agent","security":[{"bearerAuth":[]}],"tags":["Agents"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"example":"RiskEngine-v2"},"model_hash":{"type":"string","minLength":1,"example":"sha256:abc123..."},"model":{"type":"string","example":"gpt-4o"},"version":{"type":"string","example":"2.1.0"},"description":{"type":"string"},"financial_scope":{"$ref":"#/components/schemas/FinancialScope"},"metadata":{"type":"object","additionalProperties":{"nullable":true}}},"required":["name","model_hash"]}}}},"responses":{"201":{"description":"Agent registered","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Agent"}},"required":["data"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/agents/{id}":{"get":{"summary":"Get agent by ID","security":[{"bearerAuth":[]}],"tags":["Agents"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Agent","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Agent"}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/agents/{id}/certify":{"post":{"summary":"Issue X.509 certificate for agent","description":"Issues an RSA-2048 certificate via AWS KMS. Fails if agent already has an active certificate.","security":[{"bearerAuth":[]}],"tags":["Certificates"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"201":{"description":"Certificate issued","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Certificate"}},"required":["data"]}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Agent already has active certificate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Agent is retired or invalid state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"KMS not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/certificates/{id}/revoke":{"post":{"summary":"Revoke a certificate","security":[{"bearerAuth":[]}],"tags":["Certificates"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":500}},"required":["reason"]}}}},"responses":{"200":{"description":"Revoked","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"certificate_id":{"type":"string"},"status":{"type":"string","enum":["revoked"]},"revoked_at":{"type":"string"},"reason":{"type":"string"}},"required":["certificate_id","status","revoked_at","reason"]}},"required":["data"]}}}},"404":{"description":"Certificate not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Already revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Certificate is expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/verify/{serial}":{"get":{"summary":"Verify agent certificate by serial number","description":"Public endpoint — no auth required. Rate limited: 100 req/60s per IP.","tags":["Certificates"],"parameters":[{"schema":{"type":"string","example":"AABBCCDDEEFF00112233"},"required":true,"name":"serial","in":"path"}],"responses":{"200":{"description":"Certificate status","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"serial_number":{"type":"string"},"status":{"type":"string","enum":["active","revoked","expired"]},"agent_id":{"type":"string","format":"uuid"},"issued_at":{"type":"string"},"expires_at":{"type":"string"}},"required":["serial_number","status","agent_id","issued_at","expires_at"]}},"required":["data"]}}}},"404":{"description":"Certificate not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/events":{"post":{"summary":"Ingest behavioral event","description":"Records an agent action and computes a risk score. High-risk events (≥0.85) trigger auto-revocation after 3 in 15 min.","security":[{"bearerAuth":[]}],"tags":["Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string","format":"uuid"},"actionType":{"type":"string","enum":["api_call","data_access","authentication","authorization","transaction","transaction_anomaly","model_inference","tool_use"]},"chainId":{"type":"string","format":"uuid"},"sessionId":{"type":"string"},"occurredAt":{"type":"string","format":"date-time"},"details":{"type":"object","additionalProperties":{"nullable":true}}},"required":["agentId","actionType"]}}}},"responses":{"201":{"description":"Event recorded","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BehaviorEvent"}},"required":["data"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/webhooks":{"post":{"summary":"Register a webhook endpoint","security":[{"bearerAuth":[]}],"tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","example":"https://yourservice.com/webhooks/kakunin"},"events":{"type":"array","items":{"type":"string","enum":["certificate.issued","certificate.revoked","risk.alert"]},"minItems":1}},"required":["url","events"]}}}},"responses":{"201":{"description":"Webhook registered. Secret shown once — store it securely.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/Webhook"},{"type":"object","properties":{"secret":{"type":"string"},"secret_hint":{"type":"string"}},"required":["secret","secret_hint"]}]}},"required":["data"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"summary":"List webhooks","security":[{"bearerAuth":[]}],"tags":["Webhooks"],"responses":{"200":{"description":"Webhooks list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}}},"required":["data"]}}}}}}},"/v1/audit-log":{"get":{"summary":"Query audit log","security":[{"bearerAuth":[]}],"tags":["Audit"],"parameters":[{"schema":{"type":"string"},"required":false,"name":"event_type","in":"query"},{"schema":{"type":"string","enum":["user","agent","system"]},"required":false,"name":"actor_type","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"before","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Audit log entries","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AuditLog"}},"next_cursor":{"type":"string","nullable":true}},"required":["data","next_cursor"]}}}}}}},"/v1/crl":{"get":{"summary":"Get Certificate Revocation List","description":"Returns current CRL. Accept: application/pkix-crl for DER, text/plain for PEM.","tags":["Certificates"],"responses":{"200":{"description":"CRL in requested format"},"503":{"description":"CRL not yet generated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}