{"openapi":"3.0.3","info":{"title":"HelpFraud Business API","version":"1.0.0","description":"Internal risk indicators, not proven fraud. External providers are not connected."},"servers":[{"url":"https://helpfraud.com/api/v1"}],"security":[{"BearerAuth":[]}],"paths":{"/check":{"post":{"operationId":"_check","summary":"/check","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["input"],"properties":{"input":{"type":"string","minLength":1,"maxLength":10000},"type":{"type":"string","enum":["WEBSITE","MESSAGE","EMAIL","PHONE"]}}},"example":{"input":"https://example.com","type":"WEBSITE"}}}},"responses":{"200":{"description":"Successful response","headers":{"x-request-id":{"schema":{"type":"string"}},"x-ratelimit-limit":{"schema":{"type":"integer"}},"x-ratelimit-remaining":{"schema":{"type":"integer"}},"x-helpfraud-monthly-limit":{"schema":{"type":"integer"}},"x-helpfraud-monthly-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Check"}}}},"400":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"retry-after":{"schema":{"type":"integer"}}}},"500":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/check/url":{"post":{"operationId":"_check_url","summary":"/check/url","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["input"],"properties":{"input":{"type":"string","minLength":1,"maxLength":10000},"type":{"type":"string","enum":["WEBSITE","MESSAGE","EMAIL","PHONE"]}}},"example":{"input":"https://example.com"}}}},"responses":{"200":{"description":"Successful response","headers":{"x-request-id":{"schema":{"type":"string"}},"x-ratelimit-limit":{"schema":{"type":"integer"}},"x-ratelimit-remaining":{"schema":{"type":"integer"}},"x-helpfraud-monthly-limit":{"schema":{"type":"integer"}},"x-helpfraud-monthly-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Check"}}}},"400":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"retry-after":{"schema":{"type":"integer"}}}},"500":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/check/message":{"post":{"operationId":"_check_message","summary":"/check/message","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["input"],"properties":{"input":{"type":"string","minLength":1,"maxLength":10000},"type":{"type":"string","enum":["WEBSITE","MESSAGE","EMAIL","PHONE"]}}},"example":{"input":"Please verify this message."}}}},"responses":{"200":{"description":"Successful response","headers":{"x-request-id":{"schema":{"type":"string"}},"x-ratelimit-limit":{"schema":{"type":"integer"}},"x-ratelimit-remaining":{"schema":{"type":"integer"}},"x-helpfraud-monthly-limit":{"schema":{"type":"integer"}},"x-helpfraud-monthly-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Check"}}}},"400":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"retry-after":{"schema":{"type":"integer"}}}},"500":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/check/email":{"post":{"operationId":"_check_email","summary":"/check/email","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["input"],"properties":{"input":{"type":"string","minLength":1,"maxLength":10000},"type":{"type":"string","enum":["WEBSITE","MESSAGE","EMAIL","PHONE"]}}},"example":{"input":"support@example.com"}}}},"responses":{"200":{"description":"Successful response","headers":{"x-request-id":{"schema":{"type":"string"}},"x-ratelimit-limit":{"schema":{"type":"integer"}},"x-ratelimit-remaining":{"schema":{"type":"integer"}},"x-helpfraud-monthly-limit":{"schema":{"type":"integer"}},"x-helpfraud-monthly-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Check"}}}},"400":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"retry-after":{"schema":{"type":"integer"}}}},"500":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/check/phone":{"post":{"operationId":"_check_phone","summary":"/check/phone","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["input"],"properties":{"input":{"type":"string","minLength":1,"maxLength":10000},"type":{"type":"string","enum":["WEBSITE","MESSAGE","EMAIL","PHONE"]}}},"example":{"input":"+442079460123"}}}},"responses":{"200":{"description":"Successful response","headers":{"x-request-id":{"schema":{"type":"string"}},"x-ratelimit-limit":{"schema":{"type":"integer"}},"x-ratelimit-remaining":{"schema":{"type":"integer"}},"x-helpfraud-monthly-limit":{"schema":{"type":"integer"}},"x-helpfraud-monthly-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Check"}}}},"400":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"retry-after":{"schema":{"type":"integer"}}}},"500":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/check/bulk":{"post":{"operationId":"_check_bulk","summary":"/check/bulk","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","required":["input"],"properties":{"input":{"type":"string","minLength":1,"maxLength":10000},"type":{"type":"string","enum":["WEBSITE","MESSAGE","EMAIL","PHONE"]}}}}}},"example":{"items":[{"input":"https://example.com","type":"WEBSITE"}]}}}},"responses":{"200":{"description":"Successful response","headers":{"x-request-id":{"schema":{"type":"string"}},"x-ratelimit-limit":{"schema":{"type":"integer"}},"x-ratelimit-remaining":{"schema":{"type":"integer"}},"x-helpfraud-monthly-limit":{"schema":{"type":"integer"}},"x-helpfraud-monthly-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkCheck"}}}},"400":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"retry-after":{"schema":{"type":"integer"}}}},"500":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/domain/{domain}":{"get":{"operationId":"_domain__domain_","summary":"/domain/{domain}","parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","headers":{"x-request-id":{"schema":{"type":"string"}},"x-ratelimit-limit":{"schema":{"type":"integer"}},"x-ratelimit-remaining":{"schema":{"type":"integer"}},"x-helpfraud-monthly-limit":{"schema":{"type":"integer"}},"x-helpfraud-monthly-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"retry-after":{"schema":{"type":"integer"}}}},"500":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/domains/recent":{"get":{"operationId":"_domains_recent","summary":"/domains/recent","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"maximum":10000,"default":1}},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"risk","in":"query","schema":{"type":"string","enum":["LOW","SOME_RISK","SUSPICIOUS","HIGH"]}},{"name":"tld","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","headers":{"x-request-id":{"schema":{"type":"string"}},"x-ratelimit-limit":{"schema":{"type":"integer"}},"x-ratelimit-remaining":{"schema":{"type":"integer"}},"x-helpfraud-monthly-limit":{"schema":{"type":"integer"}},"x-helpfraud-monthly-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"retry-after":{"schema":{"type":"integer"}}}},"500":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/alerts":{"get":{"operationId":"_alerts","summary":"/alerts","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"maximum":10000,"default":1}},{"name":"unread","in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Successful response","headers":{"x-request-id":{"schema":{"type":"string"}},"x-ratelimit-limit":{"schema":{"type":"integer"}},"x-ratelimit-remaining":{"schema":{"type":"integer"}},"x-helpfraud-monthly-limit":{"schema":{"type":"integer"}},"x-helpfraud-monthly-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"retry-after":{"schema":{"type":"integer"}}}},"500":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/openapi.json":{"get":{"operationId":"_openapi_json","summary":"/openapi.json","security":[],"responses":{"200":{"description":"Successful response","headers":{"x-request-id":{"schema":{"type":"string"}},"x-ratelimit-limit":{"schema":{"type":"integer"}},"x-ratelimit-remaining":{"schema":{"type":"integer"}},"x-helpfraud-monthly-limit":{"schema":{"type":"integer"}},"x-helpfraud-monthly-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"retry-after":{"schema":{"type":"integer"}}}},"500":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured error with request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"BUSINESS account API key. Example only: hf_live_example"}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["INVALID_REQUEST","INVALID_INPUT","INVALID_API_KEY","PLAN_UPGRADE_REQUIRED","FORBIDDEN","NOT_FOUND","CONFLICT","PAYLOAD_TOO_LARGE","UNSUPPORTED_MEDIA_TYPE","RATE_LIMIT_EXCEEDED","DATABASE_UNAVAILABLE","INTERNAL_ERROR"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}},"Check":{"type":"object","required":["object","id","type","input","normalized_input","risk","summary","signals","created_at","request_id"],"properties":{"object":{"type":"string","enum":["check"]},"id":{"type":"string"},"type":{"type":"string"},"input":{"type":"string"},"normalized_input":{"type":"string"},"risk":{"type":"object","properties":{"score":{"type":"integer","minimum":0,"maximum":100},"level":{"type":"string"},"label":{"type":"string"}}},"summary":{"type":"string"},"signals":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"severity":{"type":"integer"},"category":{"type":"string"}}}},"created_at":{"type":"string","format":"date-time"},"request_id":{"type":"string"}}},"BulkCheck":{"type":"object","properties":{"object":{"type":"string","enum":["bulk_check"]},"succeeded":{"type":"integer"},"failed":{"type":"integer"},"results":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"ok":{"type":"boolean"},"check":{"$ref":"#/components/schemas/Check"},"error":{"$ref":"#/components/schemas/Error"}}}},"request_id":{"type":"string"}}}}},"x-helpfraud-limits":{"requestsPerMinute":60,"monthlyUnits":5000,"bulkMaxItems":50,"bulkCost":"One unit per item; at least one unit per authenticated request","bodyMaxBytes":262144}}