{"openapi":"3.0.3","info":{"title":"Kaidn API","version":"1.0.0","description":"Fraud and abuse scoring for signups, logins and checkouts.\n\nSend an event about a user and get back a score, a verdict (`allow`, `review` or `block`) and the plain-English reasons behind it. Rules decide; the AI layer only explains, so a verdict is never produced by a language model.\n\nAuthenticate every request with your tenant API key in the `x-api-key` header. Keys are issued at https://kaidn.io/register and the free tier covers 10,000 events a month.","contact":{"name":"Kaidn support","email":"support@kaidn.io","url":"https://kaidn.io"},"license":{"name":"Proprietary","url":"https://kaidn.io/terms"}},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header","description":"Your tenant API key. A `Bearer` token in `Authorization` is also accepted."}},"schemas":{}},"paths":{"/v1/health":{"get":{"operationId":"getHealth","summary":"Service health and intel-feed freshness","tags":["Service"],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"status":{"type":"string"}},"description":"Success."}}}},"400":{"description":"The request body or query string failed validation.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"The request body or query string failed validation."}}}},"429":{"description":"Rate limit exceeded. Back off and retry.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"Rate limit exceeded. Back off and retry."}}}}}}},"/v1/ip":{"get":{"operationId":"getIp","summary":"Echo the caller's IP","tags":["Service"],"description":"Returns the public IP Kaidn sees for this request, for pre-filling a checker.","responses":{"200":{"description":"Success. Field-level shape for this endpoint is documented at https://kaidn.io/docs.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Success. Field-level shape for this endpoint is documented at https://kaidn.io/docs."}}}},"400":{"description":"The request body or query string failed validation.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"The request body or query string failed validation."}}}},"429":{"description":"Rate limit exceeded. Back off and retry.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"Rate limit exceeded. Back off and retry."}}}}}}},"/v1/check":{"post":{"operationId":"postCheck","summary":"Check any identifier","tags":["Checks"],"description":"Pass an email, IP or phone and get its risk back without recording an event.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"email":{"type":"string","maxLength":320},"ip":{"type":"string","maxLength":45,"format":"ip"}}}}}},"responses":{"200":{"description":"Success. Field-level shape for this endpoint is documented at https://kaidn.io/docs.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Success. Field-level shape for this endpoint is documented at https://kaidn.io/docs."}}}},"400":{"description":"The request body or query string failed validation.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"The request body or query string failed validation."}}}},"429":{"description":"Rate limit exceeded. Back off and retry.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"Rate limit exceeded. Back off and retry."}}}}}}},"/v1/check/email":{"post":{"operationId":"postCheckEmail","summary":"Check an email address","tags":["Checks"],"description":"Disposable-domain, MX and address-integrity checks for one address.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"additionalProperties":false,"properties":{"email":{"type":"string","minLength":3,"maxLength":320}}}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"email":{"type":"object","additionalProperties":true,"properties":{"fraud_score":{"type":"number"},"is_disposable":{"type":"boolean"},"mx_valid":{"type":"boolean"},"catch_all":{"type":"boolean"},"looks_gibberish":{"type":"boolean"},"has_plus_tag":{"type":"boolean"},"canonical":{"type":"string","nullable":true},"is_aliased":{"type":"boolean"},"alias_tricks":{"type":"array","items":{"type":"string"}},"is_malformed":{"type":"boolean"},"reject_reason":{"type":"string","nullable":true},"recent_abuse":{"type":"boolean"}},"required":["fraud_score"]},"reputation":{"type":"object","additionalProperties":true,"properties":{"recent_abuse":{"type":"boolean"},"network_risk":{"type":"number"},"network_operators":{"type":"integer"},"honeypot_hits":{"type":"integer"}}},"summary":{"type":"string"}},"description":"Success."}}}},"400":{"description":"The request body or query string failed validation.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"error":{"type":"string"}},"required":["error"],"description":"The request body or query string failed validation."}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"error":{"type":"string"}},"required":["error"],"description":"Missing or invalid API key."}}}},"429":{"description":"Rate limit exceeded. Back off and retry.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"error":{"type":"string"}},"required":["error"],"description":"Rate limit exceeded. Back off and retry."}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"error":{"type":"string"}},"required":["error"],"description":"Unexpected server error."}}}}}}},"/v1/check/ip":{"post":{"operationId":"postCheckIp","summary":"Check an IP address","tags":["Checks"],"description":"Datacenter, proxy and ASN classification for one address.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ip"],"additionalProperties":false,"properties":{"ip":{"type":"string","minLength":3,"maxLength":45,"format":"ip"}}}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"ip":{"type":"object","additionalProperties":true,"properties":{"fraud_score":{"type":"number"},"is_datacenter":{"type":"boolean"},"datacenter_provider":{"type":"string","nullable":true},"is_proxy":{"type":"boolean"},"is_tor":{"type":"boolean"},"country":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"isp":{"type":"string","nullable":true},"asn":{"type":"integer","nullable":true},"recent_abuse":{"type":"boolean"}},"required":["fraud_score"]},"reputation":{"type":"object","additionalProperties":true,"properties":{"recent_abuse":{"type":"boolean"},"network_risk":{"type":"number"},"network_operators":{"type":"integer"},"honeypot_hits":{"type":"integer"}}},"summary":{"type":"string"}},"description":"Success."}}}},"400":{"description":"The request body or query string failed validation.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"error":{"type":"string"}},"required":["error"],"description":"The request body or query string failed validation."}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"error":{"type":"string"}},"required":["error"],"description":"Missing or invalid API key."}}}},"429":{"description":"Rate limit exceeded. Back off and retry.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"error":{"type":"string"}},"required":["error"],"description":"Rate limit exceeded. Back off and retry."}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"error":{"type":"string"}},"required":["error"],"description":"Unexpected server error."}}}}}}},"/v1/check/phone":{"post":{"operationId":"postCheckPhone","summary":"Check a phone number","tags":["Checks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phone"],"additionalProperties":false,"properties":{"phone":{"type":"string","minLength":3,"maxLength":32,"format":"phone"},"country":{"type":"string","minLength":2,"maxLength":2,"format":"iso-country"}}}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"phone":{"type":"object","additionalProperties":true,"properties":{"fraud_score":{"type":"number"},"valid":{"type":"boolean"},"is_voip":{"type":"boolean"},"is_disposable":{"type":"boolean"},"line_type":{"type":"string","nullable":true},"country":{"type":"string","nullable":true},"carrier":{"type":"string","nullable":true},"recent_abuse":{"type":"boolean"}},"required":["fraud_score"]},"reputation":{"type":"object","additionalProperties":true,"properties":{"recent_abuse":{"type":"boolean"},"network_risk":{"type":"number"},"network_operators":{"type":"integer"},"honeypot_hits":{"type":"integer"}}},"summary":{"type":"string"}},"description":"Success."}}}},"400":{"description":"The request body or query string failed validation.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"error":{"type":"string"}},"required":["error"],"description":"The request body or query string failed validation."}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"error":{"type":"string"}},"required":["error"],"description":"Missing or invalid API key."}}}},"429":{"description":"Rate limit exceeded. Back off and retry.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"error":{"type":"string"}},"required":["error"],"description":"Rate limit exceeded. Back off and retry."}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"error":{"type":"string"}},"required":["error"],"description":"Unexpected server error."}}}}}}},"/v1/lookups":{"get":{"operationId":"getLookups","summary":"Lookup history","tags":["Service"],"description":"Past email, IP and phone checks made by this tenant.","responses":{"200":{"description":"Success. Field-level shape for this endpoint is documented at https://kaidn.io/docs.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Success. Field-level shape for this endpoint is documented at https://kaidn.io/docs."}}}},"400":{"description":"The request body or query string failed validation.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"The request body or query string failed validation."}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"Missing or invalid API key."}}}},"429":{"description":"Rate limit exceeded. Back off and retry.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"Rate limit exceeded. Back off and retry."}}}}}}},"/v1/score":{"post":{"operationId":"postScore","summary":"Score an event","tags":["Scoring"],"description":"The core call. Describe a signup, login, checkout or any other event and get back a score from 0 to 100, a verdict of `allow`, `review` or `block`, and the reasons that produced it. Rules decide the verdict; the AI layer only writes the explanation.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["event"],"additionalProperties":false,"properties":{"event":{"type":"string","minLength":1,"maxLength":64},"user_id":{"type":"string","maxLength":256},"ip":{"type":"string","maxLength":45},"email":{"type":"string","maxLength":320},"device_id":{"type":"string","maxLength":256},"device_token":{"type":"string","maxLength":512},"device":{"type":"object","additionalProperties":false,"properties":{"is_headless":{"type":"boolean"},"ua_consistent":{"type":"boolean"},"is_emulated":{"type":"boolean"},"is_noise_injected":{"type":"boolean"},"is_tampered":{"type":"boolean"},"is_context_mismatch":{"type":"boolean"},"is_engine_mismatch":{"type":"boolean"},"is_os_mismatch":{"type":"boolean"},"is_font_standardized":{"type":"boolean"},"antidetect_score":{"type":"integer","minimum":0,"maximum":100},"antidetect_confidence":{"type":"string","enum":["low","medium","high"]},"is_emulator":{"type":"boolean"},"is_rooted":{"type":"boolean"},"is_cloned":{"type":"boolean"},"is_hooked":{"type":"boolean"},"is_sideloaded":{"type":"boolean"},"is_adb_enabled":{"type":"boolean"},"is_mock_location":{"type":"boolean"},"is_vpn_active":{"type":"boolean"},"is_debuggable":{"type":"boolean"}}},"timezone":{"type":"string","maxLength":64},"phone":{"type":"string","maxLength":32},"phone_country":{"type":"string","maxLength":8},"event_country":{"type":"string","maxLength":8},"ip_country":{"type":"string","maxLength":8},"source":{"type":"string","maxLength":64},"site":{"type":"string","maxLength":256},"campaign":{"type":"string","maxLength":256},"affiliate":{"type":"string","maxLength":256},"link":{"type":"string","maxLength":512}}}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"event_id":{"type":"string"},"score":{"type":"number"},"verdict":{"type":"string","enum":["allow","review","block"]},"reasons":{"type":"array","items":{"type":"string"}},"reason_text":{"type":"string"},"checks":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"check":{"type":"string"},"key":{"type":"string"},"weight":{"type":"number"},"reason":{"type":"string"},"message":{"type":"string"},"evidence":{"type":"object","additionalProperties":true}},"required":["check","weight","reason","message"]}},"device":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string"},"resolved_id":{"type":"string"},"resolution":{"type":"string","enum":["deterministic","probabilistic"]},"resolution_rung":{"type":"integer"},"collision_risk":{"type":"number"},"risk_measured":{"type":"boolean"},"token_rejected":{"type":"string","enum":["malformed","bad_signature","expired"]},"account_count":{"type":"integer"},"account_count_same_network":{"type":"integer"},"distinct_ips":{"type":"integer"},"unique":{"type":"boolean"},"connection_type":{"type":"string","enum":["datacenter","residential"],"nullable":true},"os":{"type":"string","nullable":true},"browser":{"type":"string","nullable":true},"mobile":{"type":"boolean","nullable":true},"is_headless":{"type":"boolean","nullable":true},"ua_consistent":{"type":"boolean","nullable":true},"is_emulated":{"type":"boolean","nullable":true},"is_noise_injected":{"type":"boolean","nullable":true},"is_tampered":{"type":"boolean","nullable":true},"is_context_mismatch":{"type":"boolean","nullable":true},"is_engine_mismatch":{"type":"boolean","nullable":true},"is_os_mismatch":{"type":"boolean","nullable":true},"timezone":{"type":"string","nullable":true},"ja4":{"type":"boolean"},"ja4_known_tool":{"type":"string","nullable":true}}},"device_token":{"type":"string"},"identity":{"type":"object","additionalProperties":true,"properties":{"email_canonical":{"type":"string"},"email_is_aliased":{"type":"boolean"},"email_alias_tricks":{"type":"array","items":{"type":"string"}}}},"warnings":{"type":"array","items":{"type":"string"}}},"required":["event_id","score","verdict","reasons","reason_text","checks"],"description":"Success."}}}},"400":{"description":"The request body or query string failed validation.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"error":{"type":"string"}},"required":["error"],"description":"The request body or query string failed validation."}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"error":{"type":"string"}},"required":["error"],"description":"Missing or invalid API key."}}}},"429":{"description":"Rate limit exceeded. Back off and retry.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"error":{"type":"string"}},"required":["error"],"description":"Rate limit exceeded. Back off and retry."}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"error":{"type":"string"}},"required":["error"],"description":"Unexpected server error."}}}}}}},"/v1/batch/score":{"post":{"operationId":"postBatchScore","summary":"Score many events at once","tags":["Bulk"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["rows"],"additionalProperties":false,"properties":{"rows":{"type":"array","minItems":1,"maxItems":1000,"items":{"type":"object","required":["event"],"additionalProperties":false,"properties":{"event":{"type":"string","minLength":1,"maxLength":64},"user_id":{"type":"string","maxLength":256},"ip":{"type":"string","maxLength":45},"email":{"type":"string","maxLength":320},"device_id":{"type":"string","maxLength":256},"device_token":{"type":"string","maxLength":512},"device":{"type":"object","additionalProperties":false,"properties":{"is_headless":{"type":"boolean"},"ua_consistent":{"type":"boolean"},"is_emulated":{"type":"boolean"},"is_noise_injected":{"type":"boolean"},"is_tampered":{"type":"boolean"},"is_context_mismatch":{"type":"boolean"},"is_engine_mismatch":{"type":"boolean"},"is_os_mismatch":{"type":"boolean"},"is_font_standardized":{"type":"boolean"},"antidetect_score":{"type":"integer","minimum":0,"maximum":100},"antidetect_confidence":{"type":"string","enum":["low","medium","high"]},"is_emulator":{"type":"boolean"},"is_rooted":{"type":"boolean"},"is_cloned":{"type":"boolean"},"is_hooked":{"type":"boolean"},"is_sideloaded":{"type":"boolean"},"is_adb_enabled":{"type":"boolean"},"is_mock_location":{"type":"boolean"},"is_vpn_active":{"type":"boolean"},"is_debuggable":{"type":"boolean"}}},"timezone":{"type":"string","maxLength":64},"phone":{"type":"string","maxLength":32},"phone_country":{"type":"string","maxLength":8},"event_country":{"type":"string","maxLength":8},"ip_country":{"type":"string","maxLength":8},"source":{"type":"string","maxLength":64},"site":{"type":"string","maxLength":256},"campaign":{"type":"string","maxLength":256},"affiliate":{"type":"string","maxLength":256},"link":{"type":"string","maxLength":512}}}}}}}}},"responses":{"200":{"description":"Success. Field-level shape for this endpoint is documented at https://kaidn.io/docs.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Success. Field-level shape for this endpoint is documented at https://kaidn.io/docs."}}}},"400":{"description":"The request body or query string failed validation.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"The request body or query string failed validation."}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"Missing or invalid API key."}}}},"429":{"description":"Rate limit exceeded. Back off and retry.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"Rate limit exceeded. Back off and retry."}}}}}}},"/v1/batch/check/email":{"post":{"operationId":"postBatchCheckEmail","summary":"Check many email addresses at once","tags":["Bulk"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["rows"],"additionalProperties":false,"properties":{"rows":{"type":"array","minItems":1,"maxItems":1000,"items":{"type":"object","required":["email"],"additionalProperties":false,"properties":{"email":{"type":"string","minLength":3,"maxLength":320}}}}}}}}},"responses":{"200":{"description":"Success. Field-level shape for this endpoint is documented at https://kaidn.io/docs.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Success. Field-level shape for this endpoint is documented at https://kaidn.io/docs."}}}},"400":{"description":"The request body or query string failed validation.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"The request body or query string failed validation."}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"Missing or invalid API key."}}}},"429":{"description":"Rate limit exceeded. Back off and retry.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"Rate limit exceeded. Back off and retry."}}}}}}},"/v1/batch/check/ip":{"post":{"operationId":"postBatchCheckIp","summary":"Check many IP addresses at once","tags":["Bulk"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["rows"],"additionalProperties":false,"properties":{"rows":{"type":"array","minItems":1,"maxItems":1000,"items":{"type":"object","required":["ip"],"additionalProperties":false,"properties":{"ip":{"type":"string","minLength":3,"maxLength":45}}}}}}}}},"responses":{"200":{"description":"Success. Field-level shape for this endpoint is documented at https://kaidn.io/docs.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Success. Field-level shape for this endpoint is documented at https://kaidn.io/docs."}}}},"400":{"description":"The request body or query string failed validation.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"The request body or query string failed validation."}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"Missing or invalid API key."}}}},"429":{"description":"Rate limit exceeded. Back off and retry.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"Rate limit exceeded. Back off and retry."}}}}}}},"/v1/batch/check/phone":{"post":{"operationId":"postBatchCheckPhone","summary":"Check many phone numbers at once","tags":["Bulk"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["rows"],"additionalProperties":false,"properties":{"rows":{"type":"array","minItems":1,"maxItems":1000,"items":{"type":"object","required":["phone"],"additionalProperties":false,"properties":{"phone":{"type":"string","minLength":3,"maxLength":32},"country":{"type":"string","minLength":2,"maxLength":2}}}}}}}}},"responses":{"200":{"description":"Success. Field-level shape for this endpoint is documented at https://kaidn.io/docs.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Success. Field-level shape for this endpoint is documented at https://kaidn.io/docs."}}}},"400":{"description":"The request body or query string failed validation.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"The request body or query string failed validation."}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"Missing or invalid API key."}}}},"429":{"description":"Rate limit exceeded. Back off and retry.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"Rate limit exceeded. Back off and retry."}}}}}}},"/v1/batch/lists":{"post":{"operationId":"postBatchLists","summary":"Add many list entries at once","tags":["Bulk"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["rows"],"additionalProperties":false,"properties":{"rows":{"type":"array","minItems":1,"maxItems":1000,"items":{"type":"object","required":["list","type","value"],"additionalProperties":false,"properties":{"list":{"type":"string","enum":["allow","block"]},"type":{"type":"string","enum":["ip","email","device","user"]},"value":{"type":"string","minLength":1,"maxLength":320}}}}}}}}},"responses":{"200":{"description":"Success. Field-level shape for this endpoint is documented at https://kaidn.io/docs.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Success. Field-level shape for this endpoint is documented at https://kaidn.io/docs."}}}},"400":{"description":"The request body or query string failed validation.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"The request body or query string failed validation."}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"Missing or invalid API key."}}}},"429":{"description":"Rate limit exceeded. Back off and retry.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"Rate limit exceeded. Back off and retry."}}}}}}},"/v1/label":{"post":{"operationId":"postLabel","summary":"Record what actually happened","tags":["Scoring"],"description":"The feedback loop. Tell Kaidn whether an event you scored turned out to be fraud or legitimate, so accuracy can be measured against real outcomes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["label"],"additionalProperties":false,"properties":{"label":{"type":"string","enum":["fraud","chargeback","legit"]},"event_id":{"type":"string","maxLength":64},"entities":{"type":"object","additionalProperties":false,"properties":{"ip":{"type":"string","maxLength":45,"format":"ip"},"email":{"type":"string","maxLength":320,"format":"email"},"device_id":{"type":"string","maxLength":256}}},"note":{"type":"string","maxLength":500}}}}}},"responses":{"200":{"description":"Success. Field-level shape for this endpoint is documented at https://kaidn.io/docs.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Success. Field-level shape for this endpoint is documented at https://kaidn.io/docs."}}}},"400":{"description":"The request body or query string failed validation.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"The request body or query string failed validation."}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"Missing or invalid API key."}}}},"429":{"description":"Rate limit exceeded. Back off and retry.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"Rate limit exceeded. Back off and retry."}}}}}}},"/v1/forget":{"post":{"operationId":"postForget","summary":"Erase a data subject","tags":["Privacy"],"description":"GDPR Article 17. Removes every row Kaidn holds for the identifier and compacts the store, so the data is gone from the file rather than merely hidden from a query.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"email":{"type":"string","maxLength":320},"phone":{"type":"string","maxLength":32},"ip":{"type":"string","maxLength":45},"device_id":{"type":"string","maxLength":256},"user_id":{"type":"string","maxLength":256}}}}}},"responses":{"200":{"description":"Success. Field-level shape for this endpoint is documented at https://kaidn.io/docs.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Success. Field-level shape for this endpoint is documented at https://kaidn.io/docs."}}}},"400":{"description":"The request body or query string failed validation.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"The request body or query string failed validation."}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"Missing or invalid API key."}}}},"429":{"description":"Rate limit exceeded. Back off and retry.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"Rate limit exceeded. Back off and retry."}}}}}}},"/v1/subject":{"post":{"operationId":"postSubject","summary":"Export what is held about a subject","tags":["Privacy"],"description":"GDPR Article 15, scoped to your own tenant. Built so a controller can answer a subject access request from their backend; it is not a route a data subject calls directly.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"email":{"type":"string","maxLength":320},"phone":{"type":"string","maxLength":32},"ip":{"type":"string","maxLength":45},"device_id":{"type":"string","maxLength":256},"user_id":{"type":"string","maxLength":256},"limit":{"type":"integer","minimum":1,"maximum":5000}}}}}},"responses":{"200":{"description":"Success. Field-level shape for this endpoint is documented at https://kaidn.io/docs.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Success. Field-level shape for this endpoint is documented at https://kaidn.io/docs."}}}},"400":{"description":"The request body or query string failed validation.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"The request body or query string failed validation."}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"Missing or invalid API key."}}}},"429":{"description":"Rate limit exceeded. Back off and retry.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"Rate limit exceeded. Back off and retry."}}}}}}},"/v1/suppressions":{"get":{"operationId":"getSuppressions","summary":"Suppression audit trail","tags":["Privacy"],"description":"Local suppressions from labels and erasures. Hashes only, never raw identifiers.","parameters":[{"schema":{"type":"string","pattern":"^\\d+$"},"in":"query","name":"limit","required":false}],"responses":{"200":{"description":"Success. Field-level shape for this endpoint is documented at https://kaidn.io/docs.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Success. Field-level shape for this endpoint is documented at https://kaidn.io/docs."}}}},"400":{"description":"The request body or query string failed validation.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"The request body or query string failed validation."}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"Missing or invalid API key."}}}},"429":{"description":"Rate limit exceeded. Back off and retry.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"Rate limit exceeded. Back off and retry."}}}}}}},"/v1/events":{"get":{"operationId":"getEvents","summary":"List scored events","tags":["Events"],"description":"Newest first. Filter by verdict or event type, and page with limit and offset.","parameters":[{"schema":{"type":"string","pattern":"^\\d+$"},"in":"query","name":"limit","required":false},{"schema":{"type":"string","pattern":"^\\d+$"},"in":"query","name":"offset","required":false},{"schema":{"type":"string","enum":["allow","review","block"]},"in":"query","name":"verdict","required":false},{"schema":{"type":"string","maxLength":64},"in":"query","name":"event","required":false}],"responses":{"200":{"description":"Success. Field-level shape for this endpoint is documented at https://kaidn.io/docs.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Success. Field-level shape for this endpoint is documented at https://kaidn.io/docs."}}}},"400":{"description":"The request body or query string failed validation.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"The request body or query string failed validation."}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"Missing or invalid API key."}}}},"429":{"description":"Rate limit exceeded. Back off and retry.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"Rate limit exceeded. Back off and retry."}}}}}}},"/v1/stats":{"get":{"operationId":"getStats","summary":"Verdict totals","tags":["Events"],"description":"Counts and average score per verdict over a rolling window.","parameters":[{"schema":{"type":"string","pattern":"^\\d+$"},"in":"query","name":"window_hours","required":false}],"responses":{"200":{"description":"Success. Field-level shape for this endpoint is documented at https://kaidn.io/docs.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Success. Field-level shape for this endpoint is documented at https://kaidn.io/docs."}}}},"400":{"description":"The request body or query string failed validation.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"The request body or query string failed validation."}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"Missing or invalid API key."}}}},"429":{"description":"Rate limit exceeded. Back off and retry.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"Rate limit exceeded. Back off and retry."}}}}}}},"/v1/device/{deviceId}/observations":{"get":{"operationId":"getDeviceByDeviceIdObservations","summary":"Device timeline","tags":["Events"],"description":"Everything observed for one device id, for investigating a suspected ring.","parameters":[{"schema":{"type":"string","pattern":"^\\d+$"},"in":"query","name":"hours","required":false},{"schema":{"type":"string","maxLength":256},"in":"path","name":"deviceId","required":true}],"responses":{"200":{"description":"Success. Field-level shape for this endpoint is documented at https://kaidn.io/docs.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Success. Field-level shape for this endpoint is documented at https://kaidn.io/docs."}}}},"400":{"description":"The request body or query string failed validation.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"The request body or query string failed validation."}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"Missing or invalid API key."}}}},"429":{"description":"Rate limit exceeded. Back off and retry.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"Rate limit exceeded. Back off and retry."}}}}}}},"/v1/config":{"get":{"operationId":"getConfig","summary":"Read your scoring configuration","tags":["Config"],"description":"The per-tenant check weights and the review and block thresholds in force.","responses":{"200":{"description":"Success. Field-level shape for this endpoint is documented at https://kaidn.io/docs.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Success. Field-level shape for this endpoint is documented at https://kaidn.io/docs."}}}},"400":{"description":"The request body or query string failed validation.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"The request body or query string failed validation."}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"Missing or invalid API key."}}}},"429":{"description":"Rate limit exceeded. Back off and retry.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"Rate limit exceeded. Back off and retry."}}}}}},"put":{"operationId":"putConfig","summary":"Update your scoring configuration","tags":["Config"],"responses":{"200":{"description":"Success. Field-level shape for this endpoint is documented at https://kaidn.io/docs.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Success. Field-level shape for this endpoint is documented at https://kaidn.io/docs."}}}},"400":{"description":"The request body or query string failed validation.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"The request body or query string failed validation."}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"Missing or invalid API key."}}}},"429":{"description":"Rate limit exceeded. Back off and retry.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"Rate limit exceeded. Back off and retry."}}}}}}},"/v1/lists":{"get":{"operationId":"getLists","summary":"List your allowlist and blocklist entries","tags":["Lists"],"responses":{"200":{"description":"Success. Field-level shape for this endpoint is documented at https://kaidn.io/docs.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Success. Field-level shape for this endpoint is documented at https://kaidn.io/docs."}}}},"400":{"description":"The request body or query string failed validation.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"The request body or query string failed validation."}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"Missing or invalid API key."}}}},"429":{"description":"Rate limit exceeded. Back off and retry.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"Rate limit exceeded. Back off and retry."}}}}}},"post":{"operationId":"postLists","summary":"Add an allowlist or blocklist entry","tags":["Lists"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["list","type","value"],"additionalProperties":false,"properties":{"list":{"type":"string","enum":["allow","block"]},"type":{"type":"string","enum":["ip","email","device","user"]},"value":{"type":"string","minLength":1,"maxLength":320}}}}}},"responses":{"200":{"description":"Success. Field-level shape for this endpoint is documented at https://kaidn.io/docs.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Success. Field-level shape for this endpoint is documented at https://kaidn.io/docs."}}}},"400":{"description":"The request body or query string failed validation.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"The request body or query string failed validation."}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"Missing or invalid API key."}}}},"429":{"description":"Rate limit exceeded. Back off and retry.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"Rate limit exceeded. Back off and retry."}}}}}}},"/v1/lists/{id}":{"delete":{"operationId":"deleteListsById","summary":"Delete a list entry","tags":["Lists"],"parameters":[{"schema":{"type":"string","pattern":"^\\d+$"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success. Field-level shape for this endpoint is documented at https://kaidn.io/docs.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Success. Field-level shape for this endpoint is documented at https://kaidn.io/docs."}}}},"400":{"description":"The request body or query string failed validation.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"The request body or query string failed validation."}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"Missing or invalid API key."}}}},"429":{"description":"Rate limit exceeded. Back off and retry.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong."}},"required":["error"],"description":"Rate limit exceeded. Back off and retry."}}}}}}}},"servers":[{"url":"https://api.kaidn.io","description":"Production"}],"security":[{"apiKey":[]}],"tags":[{"name":"Scoring","description":"Score an event and record its outcome."},{"name":"Checks","description":"Look up a single email, IP or phone."},{"name":"Bulk","description":"The same checks over many rows at once."},{"name":"Events","description":"Read back what was scored."},{"name":"Lists","description":"Your own allowlists and blocklists."},{"name":"Config","description":"Per-tenant weights and thresholds."},{"name":"Privacy","description":"Erasure and suppression, for GDPR requests."},{"name":"Service","description":"Health and metadata."}],"externalDocs":{"url":"https://kaidn.io/docs","description":"Guides and quickstarts"}}