{"openapi":"3.1.1","info":{"title":"GenderAPI v2","version":"2.0.0","description":"Separate service using existing v1 API keys and credits. v1 remains unchanged. Shared balance consistency is limited by v1 non-atomic writers. Single requests default to automatic AI fallback when the dataset cannot determine gender; batch items default to dataset only. Ordinary dataset results and automatic AI fallback cost 1 credit total, including unknown results. forceToGenderize true uses the dataset first: a resolved dataset gender costs 1 credit, otherwise nickname-based AI inference costs 2 credits total without requiring a real given name. Explicit ai_mode always costs 2 credits. AI requires provider configuration; an unavailable provider does not prevent dataset hits from succeeding. Phone validation costs 1, including invalid numbers. New billable requests require at least one credit, not the full tariff. The full single or batch tariff may make the balance negative. Zero or negative balances reject new charges; refunds remain allowed. Failed predictions are refunded. Every request is a new operation with normal billing, including repeated requests. Inferences are not verified identity. Missing, malformed or unknown API keys use a shared v1 IP trial: 10 credits per 24-hour window. Existing disabled, expired or restricted keys do not fall back. Normal tariffs apply; trial batches allow at most 10 items. Clients behind the same public IP share the quota. Additive response metadata describes access, billing, matching evidence and batch summaries. Confidence is not a calibrated probability. See /api/v2/errors for machine-readable recovery guidance."},"servers":[{"url":"https://api.genderapi.io"}],"paths":{"/api/v2":{"get":{"operationId":"getCapabilities","responses":{"200":{"description":"Deployment version, limits and AI availability.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v2/errors":{"get":{"operationId":"getErrorCatalog","responses":{"200":{"description":"Public machine-readable error codes and recovery guidance.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"object","additionalProperties":{"type":"object","required":["code","http_statuses","action","description"],"properties":{"code":{"type":"string"},"http_statuses":{"type":"array","items":{"type":"integer"}},"action":{"type":"string"},"description":{"type":"string"}}}}}}}}}}}},"/api/v2/openapi.json":{"get":{"operationId":"getOpenApi","responses":{"200":{"description":"OpenAPI 3.1.1 document.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v2/usage":{"get":{"operationId":"getUsage","security":[{"BearerAuth":[]},{}],"responses":{"200":{"description":"Current shared balance; this request is free.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["remaining_credits","expires_at"],"properties":{"remaining_credits":{"type":"integer"},"expires_at":{"type":["string","null"]},"resets_at":{"type":["string","null"],"description":"UTC trial reset timestamp, null if no trial reset is known. Not a subscription expiry."},"limit":{"type":["integer","null"],"minimum":0},"period_seconds":{"type":["integer","null"],"minimum":1}}},"meta":{"type":"object","required":["request_id"],"additionalProperties":false,"properties":{"request_id":{"type":"string","description":"Unique request ID for this HTTP attempt, also returned in X-Request-ID."},"duration_ms":{"type":"integer","minimum":0},"access":{"type":"object","required":["mode","reason"],"additionalProperties":false,"properties":{"mode":{"enum":["api_key","ip_trial","unauthenticated"]},"reason":{"enum":[null,"api_key_missing","api_key_invalid","api_key_not_found"]}}},"usage":{"type":"object","required":["charged_credits","remaining_credits"],"additionalProperties":false,"properties":{"charged_credits":{"type":["integer","null"],"minimum":0,"description":"Net charge of the recorded operation. Null if billing is unconfirmed."},"remaining_credits":{"type":["integer","null"],"description":"Balance at operation completion, may be negative; null when unavailable."},"billing_status":{"enum":["not_charged","confirmed","unconfirmed"]},"resets_at":{"type":["string","null"],"description":"UTC trial reset timestamp, null if no trial reset is known. Not a subscription expiry."},"limit":{"type":["integer","null"],"minimum":0},"period_seconds":{"type":["integer","null"],"minimum":1}},"allOf":[{"if":{"required":["billing_status"],"properties":{"billing_status":{"const":"unconfirmed"}}},"then":{"properties":{"charged_credits":{"const":null},"remaining_credits":{"const":null}}}},{"if":{"required":["billing_status"],"properties":{"billing_status":{"const":"not_charged"}}},"then":{"properties":{"charged_credits":{"const":0}}}},{"if":{"required":["billing_status"],"properties":{"billing_status":{"const":"confirmed"}}},"then":{"properties":{"charged_credits":{"type":"integer"},"remaining_credits":{"type":"integer"}}}}]},"summary":{"type":"object","required":["total","succeeded","identified","unknown","failed"],"additionalProperties":false,"properties":{"total":{"type":"integer","minimum":0,"maximum":50},"succeeded":{"type":"integer","minimum":0,"maximum":50},"identified":{"type":"integer","minimum":0,"maximum":50},"unknown":{"type":"integer","minimum":0,"maximum":50},"failed":{"type":"integer","minimum":0,"maximum":50}},"description":"total = succeeded + failed; succeeded = identified + unknown. Unknown is a successful billed prediction, not an error."}}}}},"examples":{"usage":{"summary":"Illustrative usage response (synthetic data)","value":{"data":{"remaining_credits":9,"expires_at":"2026-09-26T12:00:00.000Z","resets_at":"2026-09-26T12:00:00.000Z","limit":10,"period_seconds":86400},"meta":{"request_id":"11111111-1111-4111-8111-111111111111","duration_ms":12,"access":{"mode":"ip_trial","reason":"api_key_missing"},"usage":{"charged_credits":0,"remaining_credits":9,"billing_status":"not_charged","resets_at":"2026-09-26T12:00:00.000Z","limit":10,"period_seconds":86400}}}}}}}},"400":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"405":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"502":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"504":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v2/gender":{"post":{"operationId":"predictGender","description":"Single name, email or username. Ordinary ai_mode defaults to fallback and costs 1 credit even after AI fallback. forceToGenderize true always checks the dataset first: a resolved gender costs 1; otherwise nickname-based AI costs 2 total, including a valid null result. A real given name is not required in this mode; input.forceToGenderize marks the relaxed name requirement in the response. Combining forceToGenderize true with ai_mode off/always is invalid (422). Without force, off disables AI and always skips the dataset for 2 credits. Provider/dataset errors are errors, not misses; failed work is not charged.","security":[{"BearerAuth":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["type","value"],"properties":{"id":{"type":"string","minLength":1,"maxLength":64},"type":{"type":"string","enum":["name","email","username"]},"value":{"type":"string","minLength":1,"maxLength":254,"pattern":"\\S"},"country":{"type":"string","enum":["AD","AE","AF","AG","AI","AL","AM","AO","AQ","AR","AS","AT","AU","AW","AX","AZ","BA","BB","BD","BE","BF","BG","BH","BI","BJ","BL","BM","BN","BO","BQ","BR","BS","BT","BV","BW","BY","BZ","CA","CC","CD","CF","CG","CH","CI","CK","CL","CM","CN","CO","CR","CU","CV","CW","CX","CY","CZ","DE","DJ","DK","DM","DO","DZ","EC","EE","EG","EH","ER","ES","ET","FI","FJ","FK","FM","FO","FR","GA","GB","GD","GE","GF","GG","GH","GI","GL","GM","GN","GP","GQ","GR","GS","GT","GU","GW","GY","HK","HM","HN","HR","HT","HU","ID","IE","IL","IM","IN","IO","IQ","IR","IS","IT","JE","JM","JO","JP","KE","KG","KH","KI","KM","KN","KP","KR","KW","KY","KZ","LA","LB","LC","LI","LK","LR","LS","LT","LU","LV","LY","MA","MC","MD","ME","MF","MG","MH","MK","ML","MM","MN","MO","MP","MQ","MR","MS","MT","MU","MV","MW","MX","MY","MZ","NA","NC","NE","NF","NG","NI","NL","NO","NP","NR","NU","NZ","OM","PA","PE","PF","PG","PH","PK","PL","PM","PN","PR","PS","PT","PW","PY","QA","RE","RO","RS","RU","RW","SA","SB","SC","SD","SE","SG","SH","SI","SJ","SK","SL","SM","SN","SO","SR","SS","ST","SV","SX","SY","SZ","TC","TD","TF","TG","TH","TJ","TK","TL","TM","TN","TO","TR","TT","TV","TW","TZ","UA","UG","UM","US","UY","UZ","VA","VC","VE","VG","VI","VN","VU","WF","WS","YE","YT","ZA","ZM","ZW"]},"forceToGenderize":{"type":"boolean","description":"Try the dataset first (1 credit); on an unknown gender, infer from nickname/alias semantics with AI (2 credits total). A real given name is not required. Cannot be combined with ai_mode off or always."},"options":{"type":"object","additionalProperties":false,"properties":{"ai_mode":{"type":"string","enum":["off","fallback","always"],"description":"Defaults to fallback for single requests and off for batch items. Automatic fallback costs 1 credit total; always costs 2."}}}}}}}},"responses":{"200":{"description":"Completed. Unknown predictions are valid, billed results. Batch may contain item errors; only successful items are billed.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","additionalProperties":false,"required":["input","name","gender","country","confidence","confidence_kind","sample_count","source"],"properties":{"input":{"type":"object","required":["type","value","country"],"properties":{"type":{"type":"string","enum":["name","email","username"]},"value":{"type":"string","minLength":1,"maxLength":254,"pattern":"\\S"},"country":{"type":["string","null"]},"forceToGenderize":{"type":"boolean"}},"additionalProperties":false},"result_status":{"enum":["identified","unknown"],"description":"Whether this inference produced a non-null gender, not verified personal identity."},"reason":{"enum":[null,"not_found","no_name_candidate","ambiguous","insufficient_evidence"],"description":"Only a known reason; AI unknown results use insufficient_evidence without claiming a more specific cause."},"country_source":{"enum":[null,"dataset","ai_association"]},"match":{"type":"object","additionalProperties":false,"required":["name","method","scope","country"],"properties":{"name":{"type":["string","null"]},"method":{"enum":[null,"normalized","token","substring","model_inference"]},"scope":{"enum":[null,"country","global"]},"country":{"type":["string","null"]}},"description":"Dataset candidate and lookup scope. AI has no database match; its name and scope are null."},"name":{"type":["string","null"]},"gender":{"enum":["male","female",null]},"country":{"type":["string","null"]},"confidence":{"type":["number","null"],"minimum":0,"maximum":1},"confidence_kind":{"enum":["observed_frequency","model_reported",null]},"sample_count":{"type":["integer","null"],"minimum":0},"source":{"enum":["dataset","ai","none"]}},"allOf":[{"if":{"required":["result_status"],"properties":{"result_status":{"const":"identified"}}},"then":{"properties":{"gender":{"enum":["male","female"]},"reason":{"const":null}}}},{"if":{"required":["result_status"],"properties":{"result_status":{"const":"unknown"}}},"then":{"properties":{"gender":{"const":null},"reason":{"enum":["not_found","no_name_candidate","ambiguous","insufficient_evidence"]}}}},{"if":{"properties":{"gender":{"const":null}}},"then":{"properties":{"confidence":{"const":null},"confidence_kind":{"const":null}}}},{"if":{"properties":{"source":{"const":"ai"}}},"then":{"properties":{"sample_count":{"const":null}},"allOf":[{"if":{"properties":{"input":{"required":["forceToGenderize"],"properties":{"forceToGenderize":{"const":true}}}}},"then":{},"else":{"allOf":[{"if":{"properties":{"name":{"const":null}}},"then":{"properties":{"gender":{"const":null},"country":{"const":null},"confidence":{"const":null}}}},{"if":{"properties":{"gender":{"enum":["male","female"]}}},"then":{"properties":{"name":{"type":"string","minLength":1}}}}]}},{"if":{"properties":{"gender":{"enum":["male","female"]}}},"then":{"properties":{"confidence":{"type":"number","exclusiveMinimum":0.5,"maximum":1},"confidence_kind":{"const":"model_reported"}}}}]}}]},"meta":{"type":"object","required":["request_id","duration_ms","usage"],"additionalProperties":false,"properties":{"request_id":{"type":"string","description":"Unique request ID for this HTTP attempt, also returned in X-Request-ID."},"duration_ms":{"type":"integer","minimum":0},"access":{"type":"object","required":["mode","reason"],"additionalProperties":false,"properties":{"mode":{"enum":["api_key","ip_trial","unauthenticated"]},"reason":{"enum":[null,"api_key_missing","api_key_invalid","api_key_not_found"]}}},"usage":{"type":"object","required":["charged_credits","remaining_credits"],"additionalProperties":false,"properties":{"charged_credits":{"type":["integer","null"],"minimum":0,"description":"Net charge of the recorded operation. Null if billing is unconfirmed."},"remaining_credits":{"type":["integer","null"],"description":"Balance at operation completion, may be negative; null when unavailable."},"billing_status":{"enum":["not_charged","confirmed","unconfirmed"]},"resets_at":{"type":["string","null"],"description":"UTC trial reset timestamp, null if no trial reset is known. Not a subscription expiry."},"limit":{"type":["integer","null"],"minimum":0},"period_seconds":{"type":["integer","null"],"minimum":1}},"allOf":[{"if":{"required":["billing_status"],"properties":{"billing_status":{"const":"unconfirmed"}}},"then":{"properties":{"charged_credits":{"const":null},"remaining_credits":{"const":null}}}},{"if":{"required":["billing_status"],"properties":{"billing_status":{"const":"not_charged"}}},"then":{"properties":{"charged_credits":{"const":0}}}},{"if":{"required":["billing_status"],"properties":{"billing_status":{"const":"confirmed"}}},"then":{"properties":{"charged_credits":{"type":"integer"},"remaining_credits":{"type":"integer"}}}}]},"summary":{"type":"object","required":["total","succeeded","identified","unknown","failed"],"additionalProperties":false,"properties":{"total":{"type":"integer","minimum":0,"maximum":50},"succeeded":{"type":"integer","minimum":0,"maximum":50},"identified":{"type":"integer","minimum":0,"maximum":50},"unknown":{"type":"integer","minimum":0,"maximum":50},"failed":{"type":"integer","minimum":0,"maximum":50}},"description":"total = succeeded + failed; succeeded = identified + unknown. Unknown is a successful billed prediction, not an error."}}}},"additionalProperties":false},"examples":{"dataset":{"summary":"Illustrative dataset response (synthetic data)","value":{"data":{"input":{"type":"name","value":"Onur","country":"TR"},"name":"onur","gender":"male","country":"TR","confidence":0.9,"confidence_kind":"observed_frequency","sample_count":100,"source":"dataset","result_status":"identified","reason":null,"country_source":"dataset","match":{"name":"onur","method":"normalized","scope":"country","country":"TR"}},"meta":{"request_id":"11111111-1111-4111-8111-111111111111","duration_ms":12,"access":{"mode":"ip_trial","reason":"api_key_missing"},"usage":{"charged_credits":1,"remaining_credits":9,"billing_status":"confirmed","resets_at":"2026-09-26T12:00:00.000Z","limit":10,"period_seconds":86400}}}},"alias":{"summary":"Illustrative alias response (synthetic data)","value":{"data":{"input":{"type":"username","value":"prenses","country":"TR","forceToGenderize":true},"name":null,"gender":"female","country":"TR","confidence":0.7,"confidence_kind":"model_reported","sample_count":null,"source":"ai","result_status":"identified","reason":null,"country_source":"ai_association","match":{"name":null,"method":"model_inference","scope":null,"country":null}},"meta":{"request_id":"11111111-1111-4111-8111-111111111111","duration_ms":12,"access":{"mode":"ip_trial","reason":"api_key_missing"},"usage":{"charged_credits":2,"remaining_credits":-1,"billing_status":"confirmed","resets_at":"2026-09-26T12:00:00.000Z","limit":10,"period_seconds":86400}}}},"unknown":{"summary":"Illustrative unknown response (synthetic data)","value":{"data":{"input":{"type":"name","value":"zzzxxyy","country":null},"name":null,"gender":null,"country":null,"confidence":null,"confidence_kind":null,"sample_count":null,"source":"none","result_status":"unknown","reason":"not_found","country_source":null,"match":{"name":null,"method":null,"scope":null,"country":null}},"meta":{"request_id":"11111111-1111-4111-8111-111111111111","duration_ms":12,"access":{"mode":"ip_trial","reason":"api_key_missing"},"usage":{"charged_credits":1,"remaining_credits":8,"billing_status":"confirmed","resets_at":"2026-09-26T12:00:00.000Z","limit":10,"period_seconds":86400}}}}}}}},"400":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"insufficient":{"summary":"Illustrative insufficient response (synthetic data)","value":{"type":"urn:genderapi:problem:insufficient_credits","title":"insufficient credits","status":403,"detail":"At least one starting credit is required.","instance":"urn:uuid:11111111-1111-4111-8111-111111111111","code":"insufficient_credits","request_id":"11111111-1111-4111-8111-111111111111","documentation":"https://api.genderapi.io/api/v2/errors","action":"add_credits_or_wait_for_reset","meta":{"request_id":"11111111-1111-4111-8111-111111111111","duration_ms":12,"access":{"mode":"ip_trial","reason":"api_key_missing"},"usage":{"charged_credits":0,"remaining_credits":0,"billing_status":"not_charged","resets_at":"2026-09-26T12:00:00.000Z","limit":10,"period_seconds":86400}}}}}}}},"404":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"405":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation":{"summary":"Illustrative validation response (synthetic data)","value":{"type":"urn:genderapi:problem:validation_error","title":"validation error","status":422,"detail":"A valid email address is required.","instance":"urn:uuid:11111111-1111-4111-8111-111111111111","code":"validation_error","request_id":"11111111-1111-4111-8111-111111111111","documentation":"https://api.genderapi.io/api/v2/errors","action":"correct_request","errors":[{"pointer":"/value","message":"Invalid email address."}],"meta":{"request_id":"11111111-1111-4111-8111-111111111111","duration_ms":12,"access":{"mode":"ip_trial","reason":"api_key_missing"},"usage":{"charged_credits":0,"remaining_credits":null,"billing_status":"not_charged","resets_at":"2026-09-26T12:00:00.000Z","limit":10,"period_seconds":86400}}}}}}}},"429":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"502":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unconfirmed":{"summary":"Illustrative unconfirmed response (synthetic data)","value":{"type":"urn:genderapi:problem:billing_reconciliation_required","title":"billing reconciliation required","status":503,"detail":"Contact support; do not automatically retry.","instance":"urn:uuid:11111111-1111-4111-8111-111111111111","code":"billing_reconciliation_required","request_id":"11111111-1111-4111-8111-111111111111","documentation":"https://api.genderapi.io/api/v2/errors","action":"contact_support","meta":{"request_id":"11111111-1111-4111-8111-111111111111","duration_ms":12,"access":{"mode":"ip_trial","reason":"api_key_missing"},"usage":{"charged_credits":null,"remaining_credits":null,"billing_status":"unconfirmed","resets_at":"2026-09-26T12:00:00.000Z","limit":10,"period_seconds":86400}}}}}}}},"504":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"get":{"operationId":"predictGenderGet","description":"Browser-friendly single prediction. Same pricing and validation as POST. Every request is processed and billed separately, including repeated requests. Responses are not cacheable. HEAD is rejected. Prefer Bearer authentication for integrations; query keys appear in browser history.","security":[{"BearerAuth":[]},{"QueryKey":[]},{}],"parameters":[{"name":"type","in":"query","schema":{"type":"string","enum":["name","email","username"],"default":"name"}},{"name":"value","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":254,"pattern":"\\S"}},{"name":"country","in":"query","schema":{"type":"string","enum":["AD","AE","AF","AG","AI","AL","AM","AO","AQ","AR","AS","AT","AU","AW","AX","AZ","BA","BB","BD","BE","BF","BG","BH","BI","BJ","BL","BM","BN","BO","BQ","BR","BS","BT","BV","BW","BY","BZ","CA","CC","CD","CF","CG","CH","CI","CK","CL","CM","CN","CO","CR","CU","CV","CW","CX","CY","CZ","DE","DJ","DK","DM","DO","DZ","EC","EE","EG","EH","ER","ES","ET","FI","FJ","FK","FM","FO","FR","GA","GB","GD","GE","GF","GG","GH","GI","GL","GM","GN","GP","GQ","GR","GS","GT","GU","GW","GY","HK","HM","HN","HR","HT","HU","ID","IE","IL","IM","IN","IO","IQ","IR","IS","IT","JE","JM","JO","JP","KE","KG","KH","KI","KM","KN","KP","KR","KW","KY","KZ","LA","LB","LC","LI","LK","LR","LS","LT","LU","LV","LY","MA","MC","MD","ME","MF","MG","MH","MK","ML","MM","MN","MO","MP","MQ","MR","MS","MT","MU","MV","MW","MX","MY","MZ","NA","NC","NE","NF","NG","NI","NL","NO","NP","NR","NU","NZ","OM","PA","PE","PF","PG","PH","PK","PL","PM","PN","PR","PS","PT","PW","PY","QA","RE","RO","RS","RU","RW","SA","SB","SC","SD","SE","SG","SH","SI","SJ","SK","SL","SM","SN","SO","SR","SS","ST","SV","SX","SY","SZ","TC","TD","TF","TG","TH","TJ","TK","TL","TM","TN","TO","TR","TT","TV","TW","TZ","UA","UG","UM","US","UY","UZ","VA","VC","VE","VG","VI","VN","VU","WF","WS","YE","YT","ZA","ZM","ZW"]}},{"name":"forceToGenderize","in":"query","schema":{"type":"boolean"}},{"name":"ai_mode","in":"query","schema":{"type":"string","enum":["off","fallback","always"],"description":"Defaults to fallback for single requests and off for batch items. Automatic fallback costs 1 credit total; always costs 2."}}],"responses":{"200":{"description":"Completed. Unknown predictions are valid, billed results. Batch may contain item errors; only successful items are billed.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","additionalProperties":false,"required":["input","name","gender","country","confidence","confidence_kind","sample_count","source"],"properties":{"input":{"type":"object","required":["type","value","country"],"properties":{"type":{"type":"string","enum":["name","email","username"]},"value":{"type":"string","minLength":1,"maxLength":254,"pattern":"\\S"},"country":{"type":["string","null"]},"forceToGenderize":{"type":"boolean"}},"additionalProperties":false},"result_status":{"enum":["identified","unknown"],"description":"Whether this inference produced a non-null gender, not verified personal identity."},"reason":{"enum":[null,"not_found","no_name_candidate","ambiguous","insufficient_evidence"],"description":"Only a known reason; AI unknown results use insufficient_evidence without claiming a more specific cause."},"country_source":{"enum":[null,"dataset","ai_association"]},"match":{"type":"object","additionalProperties":false,"required":["name","method","scope","country"],"properties":{"name":{"type":["string","null"]},"method":{"enum":[null,"normalized","token","substring","model_inference"]},"scope":{"enum":[null,"country","global"]},"country":{"type":["string","null"]}},"description":"Dataset candidate and lookup scope. AI has no database match; its name and scope are null."},"name":{"type":["string","null"]},"gender":{"enum":["male","female",null]},"country":{"type":["string","null"]},"confidence":{"type":["number","null"],"minimum":0,"maximum":1},"confidence_kind":{"enum":["observed_frequency","model_reported",null]},"sample_count":{"type":["integer","null"],"minimum":0},"source":{"enum":["dataset","ai","none"]}},"allOf":[{"if":{"required":["result_status"],"properties":{"result_status":{"const":"identified"}}},"then":{"properties":{"gender":{"enum":["male","female"]},"reason":{"const":null}}}},{"if":{"required":["result_status"],"properties":{"result_status":{"const":"unknown"}}},"then":{"properties":{"gender":{"const":null},"reason":{"enum":["not_found","no_name_candidate","ambiguous","insufficient_evidence"]}}}},{"if":{"properties":{"gender":{"const":null}}},"then":{"properties":{"confidence":{"const":null},"confidence_kind":{"const":null}}}},{"if":{"properties":{"source":{"const":"ai"}}},"then":{"properties":{"sample_count":{"const":null}},"allOf":[{"if":{"properties":{"input":{"required":["forceToGenderize"],"properties":{"forceToGenderize":{"const":true}}}}},"then":{},"else":{"allOf":[{"if":{"properties":{"name":{"const":null}}},"then":{"properties":{"gender":{"const":null},"country":{"const":null},"confidence":{"const":null}}}},{"if":{"properties":{"gender":{"enum":["male","female"]}}},"then":{"properties":{"name":{"type":"string","minLength":1}}}}]}},{"if":{"properties":{"gender":{"enum":["male","female"]}}},"then":{"properties":{"confidence":{"type":"number","exclusiveMinimum":0.5,"maximum":1},"confidence_kind":{"const":"model_reported"}}}}]}}]},"meta":{"type":"object","required":["request_id","duration_ms","usage"],"additionalProperties":false,"properties":{"request_id":{"type":"string","description":"Unique request ID for this HTTP attempt, also returned in X-Request-ID."},"duration_ms":{"type":"integer","minimum":0},"access":{"type":"object","required":["mode","reason"],"additionalProperties":false,"properties":{"mode":{"enum":["api_key","ip_trial","unauthenticated"]},"reason":{"enum":[null,"api_key_missing","api_key_invalid","api_key_not_found"]}}},"usage":{"type":"object","required":["charged_credits","remaining_credits"],"additionalProperties":false,"properties":{"charged_credits":{"type":["integer","null"],"minimum":0,"description":"Net charge of the recorded operation. Null if billing is unconfirmed."},"remaining_credits":{"type":["integer","null"],"description":"Balance at operation completion, may be negative; null when unavailable."},"billing_status":{"enum":["not_charged","confirmed","unconfirmed"]},"resets_at":{"type":["string","null"],"description":"UTC trial reset timestamp, null if no trial reset is known. Not a subscription expiry."},"limit":{"type":["integer","null"],"minimum":0},"period_seconds":{"type":["integer","null"],"minimum":1}},"allOf":[{"if":{"required":["billing_status"],"properties":{"billing_status":{"const":"unconfirmed"}}},"then":{"properties":{"charged_credits":{"const":null},"remaining_credits":{"const":null}}}},{"if":{"required":["billing_status"],"properties":{"billing_status":{"const":"not_charged"}}},"then":{"properties":{"charged_credits":{"const":0}}}},{"if":{"required":["billing_status"],"properties":{"billing_status":{"const":"confirmed"}}},"then":{"properties":{"charged_credits":{"type":"integer"},"remaining_credits":{"type":"integer"}}}}]},"summary":{"type":"object","required":["total","succeeded","identified","unknown","failed"],"additionalProperties":false,"properties":{"total":{"type":"integer","minimum":0,"maximum":50},"succeeded":{"type":"integer","minimum":0,"maximum":50},"identified":{"type":"integer","minimum":0,"maximum":50},"unknown":{"type":"integer","minimum":0,"maximum":50},"failed":{"type":"integer","minimum":0,"maximum":50}},"description":"total = succeeded + failed; succeeded = identified + unknown. Unknown is a successful billed prediction, not an error."}}}},"additionalProperties":false},"examples":{"dataset":{"summary":"Illustrative dataset response (synthetic data)","value":{"data":{"input":{"type":"name","value":"Onur","country":"TR"},"name":"onur","gender":"male","country":"TR","confidence":0.9,"confidence_kind":"observed_frequency","sample_count":100,"source":"dataset","result_status":"identified","reason":null,"country_source":"dataset","match":{"name":"onur","method":"normalized","scope":"country","country":"TR"}},"meta":{"request_id":"11111111-1111-4111-8111-111111111111","duration_ms":12,"access":{"mode":"ip_trial","reason":"api_key_missing"},"usage":{"charged_credits":1,"remaining_credits":9,"billing_status":"confirmed","resets_at":"2026-09-26T12:00:00.000Z","limit":10,"period_seconds":86400}}}},"alias":{"summary":"Illustrative alias response (synthetic data)","value":{"data":{"input":{"type":"username","value":"prenses","country":"TR","forceToGenderize":true},"name":null,"gender":"female","country":"TR","confidence":0.7,"confidence_kind":"model_reported","sample_count":null,"source":"ai","result_status":"identified","reason":null,"country_source":"ai_association","match":{"name":null,"method":"model_inference","scope":null,"country":null}},"meta":{"request_id":"11111111-1111-4111-8111-111111111111","duration_ms":12,"access":{"mode":"ip_trial","reason":"api_key_missing"},"usage":{"charged_credits":2,"remaining_credits":-1,"billing_status":"confirmed","resets_at":"2026-09-26T12:00:00.000Z","limit":10,"period_seconds":86400}}}},"unknown":{"summary":"Illustrative unknown response (synthetic data)","value":{"data":{"input":{"type":"name","value":"zzzxxyy","country":null},"name":null,"gender":null,"country":null,"confidence":null,"confidence_kind":null,"sample_count":null,"source":"none","result_status":"unknown","reason":"not_found","country_source":null,"match":{"name":null,"method":null,"scope":null,"country":null}},"meta":{"request_id":"11111111-1111-4111-8111-111111111111","duration_ms":12,"access":{"mode":"ip_trial","reason":"api_key_missing"},"usage":{"charged_credits":1,"remaining_credits":8,"billing_status":"confirmed","resets_at":"2026-09-26T12:00:00.000Z","limit":10,"period_seconds":86400}}}}}}}},"400":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"insufficient":{"summary":"Illustrative insufficient response (synthetic data)","value":{"type":"urn:genderapi:problem:insufficient_credits","title":"insufficient credits","status":403,"detail":"At least one starting credit is required.","instance":"urn:uuid:11111111-1111-4111-8111-111111111111","code":"insufficient_credits","request_id":"11111111-1111-4111-8111-111111111111","documentation":"https://api.genderapi.io/api/v2/errors","action":"add_credits_or_wait_for_reset","meta":{"request_id":"11111111-1111-4111-8111-111111111111","duration_ms":12,"access":{"mode":"ip_trial","reason":"api_key_missing"},"usage":{"charged_credits":0,"remaining_credits":0,"billing_status":"not_charged","resets_at":"2026-09-26T12:00:00.000Z","limit":10,"period_seconds":86400}}}}}}}},"404":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"405":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation":{"summary":"Illustrative validation response (synthetic data)","value":{"type":"urn:genderapi:problem:validation_error","title":"validation error","status":422,"detail":"A valid email address is required.","instance":"urn:uuid:11111111-1111-4111-8111-111111111111","code":"validation_error","request_id":"11111111-1111-4111-8111-111111111111","documentation":"https://api.genderapi.io/api/v2/errors","action":"correct_request","errors":[{"pointer":"/value","message":"Invalid email address."}],"meta":{"request_id":"11111111-1111-4111-8111-111111111111","duration_ms":12,"access":{"mode":"ip_trial","reason":"api_key_missing"},"usage":{"charged_credits":0,"remaining_credits":null,"billing_status":"not_charged","resets_at":"2026-09-26T12:00:00.000Z","limit":10,"period_seconds":86400}}}}}}}},"429":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"502":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unconfirmed":{"summary":"Illustrative unconfirmed response (synthetic data)","value":{"type":"urn:genderapi:problem:billing_reconciliation_required","title":"billing reconciliation required","status":503,"detail":"Contact support; do not automatically retry.","instance":"urn:uuid:11111111-1111-4111-8111-111111111111","code":"billing_reconciliation_required","request_id":"11111111-1111-4111-8111-111111111111","documentation":"https://api.genderapi.io/api/v2/errors","action":"contact_support","meta":{"request_id":"11111111-1111-4111-8111-111111111111","duration_ms":12,"access":{"mode":"ip_trial","reason":"api_key_missing"},"usage":{"charged_credits":null,"remaining_credits":null,"billing_status":"unconfirmed","resets_at":"2026-09-26T12:00:00.000Z","limit":10,"period_seconds":86400}}}}}}}},"504":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v2/gender/batch":{"post":{"operationId":"predictGenderBatch","description":"Maximum 50 items (10 for IP trials). Each item supports name/email/username with independent country and AI options. Defaults to off; ordinary fallback costs 1, always costs 2, force costs 1 for dataset or 2 for AI. Planning failure rejects the whole batch before debit. Partial failures return 200; all failed work returns a problem with data and legacy results arrays. Each result includes charged_credits. meta.summary counts identified, unknown and failed results. Unknown predictions are successful billable items.","security":[{"BearerAuth":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["items"],"properties":{"items":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","additionalProperties":false,"required":["type","value"],"properties":{"id":{"type":"string","minLength":1,"maxLength":64},"type":{"type":"string","enum":["name","email","username"]},"value":{"type":"string","minLength":1,"maxLength":254,"pattern":"\\S"},"country":{"type":"string","enum":["AD","AE","AF","AG","AI","AL","AM","AO","AQ","AR","AS","AT","AU","AW","AX","AZ","BA","BB","BD","BE","BF","BG","BH","BI","BJ","BL","BM","BN","BO","BQ","BR","BS","BT","BV","BW","BY","BZ","CA","CC","CD","CF","CG","CH","CI","CK","CL","CM","CN","CO","CR","CU","CV","CW","CX","CY","CZ","DE","DJ","DK","DM","DO","DZ","EC","EE","EG","EH","ER","ES","ET","FI","FJ","FK","FM","FO","FR","GA","GB","GD","GE","GF","GG","GH","GI","GL","GM","GN","GP","GQ","GR","GS","GT","GU","GW","GY","HK","HM","HN","HR","HT","HU","ID","IE","IL","IM","IN","IO","IQ","IR","IS","IT","JE","JM","JO","JP","KE","KG","KH","KI","KM","KN","KP","KR","KW","KY","KZ","LA","LB","LC","LI","LK","LR","LS","LT","LU","LV","LY","MA","MC","MD","ME","MF","MG","MH","MK","ML","MM","MN","MO","MP","MQ","MR","MS","MT","MU","MV","MW","MX","MY","MZ","NA","NC","NE","NF","NG","NI","NL","NO","NP","NR","NU","NZ","OM","PA","PE","PF","PG","PH","PK","PL","PM","PN","PR","PS","PT","PW","PY","QA","RE","RO","RS","RU","RW","SA","SB","SC","SD","SE","SG","SH","SI","SJ","SK","SL","SM","SN","SO","SR","SS","ST","SV","SX","SY","SZ","TC","TD","TF","TG","TH","TJ","TK","TL","TM","TN","TO","TR","TT","TV","TW","TZ","UA","UG","UM","US","UY","UZ","VA","VC","VE","VG","VI","VN","VU","WF","WS","YE","YT","ZA","ZM","ZW"]},"forceToGenderize":{"type":"boolean","description":"Try the dataset first (1 credit); on an unknown gender, infer from nickname/alias semantics with AI (2 credits total). A real given name is not required. Cannot be combined with ai_mode off or always."},"options":{"type":"object","additionalProperties":false,"properties":{"ai_mode":{"type":"string","enum":["off","fallback","always"],"description":"Defaults to fallback for single requests and off for batch items. Automatic fallback costs 1 credit total; always costs 2."}}}}}}}}}}},"responses":{"200":{"description":"Completed. Unknown predictions are valid, billed results. Batch may contain item errors; only successful items are billed.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","required":["index"],"properties":{"index":{"type":"integer","minimum":0},"id":{"type":"string"},"charged_credits":{"type":"integer","minimum":0,"maximum":2},"data":{"type":"object","additionalProperties":false,"required":["input","name","gender","country","confidence","confidence_kind","sample_count","source"],"properties":{"input":{"type":"object","required":["type","value","country"],"properties":{"type":{"type":"string","enum":["name","email","username"]},"value":{"type":"string","minLength":1,"maxLength":254,"pattern":"\\S"},"country":{"type":["string","null"]},"forceToGenderize":{"type":"boolean"}},"additionalProperties":false},"result_status":{"enum":["identified","unknown"],"description":"Whether this inference produced a non-null gender, not verified personal identity."},"reason":{"enum":[null,"not_found","no_name_candidate","ambiguous","insufficient_evidence"],"description":"Only a known reason; AI unknown results use insufficient_evidence without claiming a more specific cause."},"country_source":{"enum":[null,"dataset","ai_association"]},"match":{"type":"object","additionalProperties":false,"required":["name","method","scope","country"],"properties":{"name":{"type":["string","null"]},"method":{"enum":[null,"normalized","token","substring","model_inference"]},"scope":{"enum":[null,"country","global"]},"country":{"type":["string","null"]}},"description":"Dataset candidate and lookup scope. AI has no database match; its name and scope are null."},"name":{"type":["string","null"]},"gender":{"enum":["male","female",null]},"country":{"type":["string","null"]},"confidence":{"type":["number","null"],"minimum":0,"maximum":1},"confidence_kind":{"enum":["observed_frequency","model_reported",null]},"sample_count":{"type":["integer","null"],"minimum":0},"source":{"enum":["dataset","ai","none"]}},"allOf":[{"if":{"required":["result_status"],"properties":{"result_status":{"const":"identified"}}},"then":{"properties":{"gender":{"enum":["male","female"]},"reason":{"const":null}}}},{"if":{"required":["result_status"],"properties":{"result_status":{"const":"unknown"}}},"then":{"properties":{"gender":{"const":null},"reason":{"enum":["not_found","no_name_candidate","ambiguous","insufficient_evidence"]}}}},{"if":{"properties":{"gender":{"const":null}}},"then":{"properties":{"confidence":{"const":null},"confidence_kind":{"const":null}}}},{"if":{"properties":{"source":{"const":"ai"}}},"then":{"properties":{"sample_count":{"const":null}},"allOf":[{"if":{"properties":{"input":{"required":["forceToGenderize"],"properties":{"forceToGenderize":{"const":true}}}}},"then":{},"else":{"allOf":[{"if":{"properties":{"name":{"const":null}}},"then":{"properties":{"gender":{"const":null},"country":{"const":null},"confidence":{"const":null}}}},{"if":{"properties":{"gender":{"enum":["male","female"]}}},"then":{"properties":{"name":{"type":"string","minLength":1}}}}]}},{"if":{"properties":{"gender":{"enum":["male","female"]}}},"then":{"properties":{"confidence":{"type":"number","exclusiveMinimum":0.5,"maximum":1},"confidence_kind":{"const":"model_reported"}}}}]}}]},"error":{"type":"object","required":["type","title","status","detail","instance","code","request_id"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer","minimum":400,"maximum":599},"detail":{"type":"string"},"instance":{"type":"string"},"code":{"type":"string"},"request_id":{"type":"string"},"documentation":{"type":"string"},"action":{"type":"string"},"errors":{"type":"array","items":{"type":"object","required":["pointer","message"],"properties":{"pointer":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}}}}},"oneOf":[{"required":["data"],"not":{"required":["error"]}},{"required":["error"],"not":{"required":["data"]},"properties":{"charged_credits":{"const":0}}}],"additionalProperties":false}},"meta":{"type":"object","required":["request_id","duration_ms","usage"],"additionalProperties":false,"properties":{"request_id":{"type":"string","description":"Unique request ID for this HTTP attempt, also returned in X-Request-ID."},"duration_ms":{"type":"integer","minimum":0},"access":{"type":"object","required":["mode","reason"],"additionalProperties":false,"properties":{"mode":{"enum":["api_key","ip_trial","unauthenticated"]},"reason":{"enum":[null,"api_key_missing","api_key_invalid","api_key_not_found"]}}},"usage":{"type":"object","required":["charged_credits","remaining_credits"],"additionalProperties":false,"properties":{"charged_credits":{"type":["integer","null"],"minimum":0,"description":"Net charge of the recorded operation. Null if billing is unconfirmed."},"remaining_credits":{"type":["integer","null"],"description":"Balance at operation completion, may be negative; null when unavailable."},"billing_status":{"enum":["not_charged","confirmed","unconfirmed"]},"resets_at":{"type":["string","null"],"description":"UTC trial reset timestamp, null if no trial reset is known. Not a subscription expiry."},"limit":{"type":["integer","null"],"minimum":0},"period_seconds":{"type":["integer","null"],"minimum":1}},"allOf":[{"if":{"required":["billing_status"],"properties":{"billing_status":{"const":"unconfirmed"}}},"then":{"properties":{"charged_credits":{"const":null},"remaining_credits":{"const":null}}}},{"if":{"required":["billing_status"],"properties":{"billing_status":{"const":"not_charged"}}},"then":{"properties":{"charged_credits":{"const":0}}}},{"if":{"required":["billing_status"],"properties":{"billing_status":{"const":"confirmed"}}},"then":{"properties":{"charged_credits":{"type":"integer"},"remaining_credits":{"type":"integer"}}}}]},"summary":{"type":"object","required":["total","succeeded","identified","unknown","failed"],"additionalProperties":false,"properties":{"total":{"type":"integer","minimum":0,"maximum":50},"succeeded":{"type":"integer","minimum":0,"maximum":50},"identified":{"type":"integer","minimum":0,"maximum":50},"unknown":{"type":"integer","minimum":0,"maximum":50},"failed":{"type":"integer","minimum":0,"maximum":50}},"description":"total = succeeded + failed; succeeded = identified + unknown. Unknown is a successful billed prediction, not an error."}}}},"additionalProperties":false},"examples":{"batch":{"summary":"Illustrative batch response (synthetic data)","value":{"data":[{"index":0,"id":"known","charged_credits":1,"data":{"input":{"type":"name","value":"Onur","country":"TR"},"name":"onur","gender":"male","country":"TR","confidence":0.9,"confidence_kind":"observed_frequency","sample_count":100,"source":"dataset","result_status":"identified","reason":null,"country_source":"dataset","match":{"name":"onur","method":"normalized","scope":"country","country":"TR"}}},{"index":1,"id":"missing","charged_credits":1,"data":{"input":{"type":"name","value":"zzzxxyy","country":null},"name":null,"gender":null,"country":null,"confidence":null,"confidence_kind":null,"sample_count":null,"source":"none","result_status":"unknown","reason":"not_found","country_source":null,"match":{"name":null,"method":null,"scope":null,"country":null}}},{"index":2,"id":"failed","charged_credits":0,"error":{"type":"urn:genderapi:problem:ai_upstream_error","title":"ai upstream error","status":502,"detail":"The AI provider could not complete the request.","instance":"urn:uuid:11111111-1111-4111-8111-111111111111","code":"ai_upstream_error","request_id":"11111111-1111-4111-8111-111111111111","documentation":"https://api.genderapi.io/api/v2/errors","action":"inspect_billing_before_retry"}}],"meta":{"request_id":"11111111-1111-4111-8111-111111111111","duration_ms":12,"access":{"mode":"ip_trial","reason":"api_key_missing"},"usage":{"charged_credits":2,"remaining_credits":6,"billing_status":"confirmed","resets_at":"2026-09-26T12:00:00.000Z","limit":10,"period_seconds":86400},"summary":{"total":3,"succeeded":2,"identified":1,"unknown":1,"failed":1}}}}}}}},"400":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"405":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"502":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"batchFailed":{"summary":"Illustrative batchFailed response (synthetic data)","value":{"type":"urn:genderapi:problem:ai_upstream_error","title":"ai upstream error","status":502,"detail":"The AI provider could not complete the request.","instance":"urn:uuid:11111111-1111-4111-8111-111111111111","code":"ai_upstream_error","request_id":"11111111-1111-4111-8111-111111111111","documentation":"https://api.genderapi.io/api/v2/errors","action":"inspect_billing_before_retry","data":[{"index":0,"charged_credits":0,"error":{"type":"urn:genderapi:problem:ai_upstream_error","title":"ai upstream error","status":502,"detail":"The AI provider could not complete the request.","instance":"urn:uuid:11111111-1111-4111-8111-111111111111","code":"ai_upstream_error","request_id":"11111111-1111-4111-8111-111111111111","documentation":"https://api.genderapi.io/api/v2/errors","action":"inspect_billing_before_retry"}}],"results":[{"index":0,"charged_credits":0,"error":{"type":"urn:genderapi:problem:ai_upstream_error","title":"ai upstream error","status":502,"detail":"The AI provider could not complete the request.","instance":"urn:uuid:11111111-1111-4111-8111-111111111111","code":"ai_upstream_error","request_id":"11111111-1111-4111-8111-111111111111","documentation":"https://api.genderapi.io/api/v2/errors","action":"inspect_billing_before_retry"}}],"meta":{"request_id":"11111111-1111-4111-8111-111111111111","duration_ms":12,"access":{"mode":"ip_trial","reason":"api_key_missing"},"usage":{"charged_credits":0,"remaining_credits":6,"billing_status":"confirmed","resets_at":"2026-09-26T12:00:00.000Z","limit":10,"period_seconds":86400},"summary":{"total":1,"succeeded":0,"identified":0,"unknown":0,"failed":1}}}}}}}},"503":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"504":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v2/phone/validate":{"post":{"operationId":"validatePhone","description":"country is required unless number starts with +. This checks number structure, not subscriber existence.","security":[{"BearerAuth":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["number"],"properties":{"number":{"type":"string","minLength":3,"maxLength":32,"pattern":"^\\+?[0-9 ()-]+$"},"country":{"type":"string","enum":["AD","AE","AF","AG","AI","AL","AM","AO","AQ","AR","AS","AT","AU","AW","AX","AZ","BA","BB","BD","BE","BF","BG","BH","BI","BJ","BL","BM","BN","BO","BQ","BR","BS","BT","BV","BW","BY","BZ","CA","CC","CD","CF","CG","CH","CI","CK","CL","CM","CN","CO","CR","CU","CV","CW","CX","CY","CZ","DE","DJ","DK","DM","DO","DZ","EC","EE","EG","EH","ER","ES","ET","FI","FJ","FK","FM","FO","FR","GA","GB","GD","GE","GF","GG","GH","GI","GL","GM","GN","GP","GQ","GR","GS","GT","GU","GW","GY","HK","HM","HN","HR","HT","HU","ID","IE","IL","IM","IN","IO","IQ","IR","IS","IT","JE","JM","JO","JP","KE","KG","KH","KI","KM","KN","KP","KR","KW","KY","KZ","LA","LB","LC","LI","LK","LR","LS","LT","LU","LV","LY","MA","MC","MD","ME","MF","MG","MH","MK","ML","MM","MN","MO","MP","MQ","MR","MS","MT","MU","MV","MW","MX","MY","MZ","NA","NC","NE","NF","NG","NI","NL","NO","NP","NR","NU","NZ","OM","PA","PE","PF","PG","PH","PK","PL","PM","PN","PR","PS","PT","PW","PY","QA","RE","RO","RS","RU","RW","SA","SB","SC","SD","SE","SG","SH","SI","SJ","SK","SL","SM","SN","SO","SR","SS","ST","SV","SX","SY","SZ","TC","TD","TF","TG","TH","TJ","TK","TL","TM","TN","TO","TR","TT","TV","TW","TZ","UA","UG","UM","US","UY","UZ","VA","VC","VE","VG","VI","VN","VU","WF","WS","YE","YT","ZA","ZM","ZW"]}}}}}},"responses":{"200":{"description":"Completed. Unknown predictions are valid, billed results. Batch may contain item errors; only successful items are billed.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["valid","possible","e164","country","country_calling_code"],"properties":{"valid":{"type":"boolean"},"possible":{"type":"boolean"},"e164":{"type":["string","null"]},"country":{"type":["string","null"]},"country_calling_code":{"type":["integer","null"]}},"additionalProperties":false},"meta":{"type":"object","required":["request_id","duration_ms","usage"],"additionalProperties":false,"properties":{"request_id":{"type":"string","description":"Unique request ID for this HTTP attempt, also returned in X-Request-ID."},"duration_ms":{"type":"integer","minimum":0},"access":{"type":"object","required":["mode","reason"],"additionalProperties":false,"properties":{"mode":{"enum":["api_key","ip_trial","unauthenticated"]},"reason":{"enum":[null,"api_key_missing","api_key_invalid","api_key_not_found"]}}},"usage":{"type":"object","required":["charged_credits","remaining_credits"],"additionalProperties":false,"properties":{"charged_credits":{"type":["integer","null"],"minimum":0,"description":"Net charge of the recorded operation. Null if billing is unconfirmed."},"remaining_credits":{"type":["integer","null"],"description":"Balance at operation completion, may be negative; null when unavailable."},"billing_status":{"enum":["not_charged","confirmed","unconfirmed"]},"resets_at":{"type":["string","null"],"description":"UTC trial reset timestamp, null if no trial reset is known. Not a subscription expiry."},"limit":{"type":["integer","null"],"minimum":0},"period_seconds":{"type":["integer","null"],"minimum":1}},"allOf":[{"if":{"required":["billing_status"],"properties":{"billing_status":{"const":"unconfirmed"}}},"then":{"properties":{"charged_credits":{"const":null},"remaining_credits":{"const":null}}}},{"if":{"required":["billing_status"],"properties":{"billing_status":{"const":"not_charged"}}},"then":{"properties":{"charged_credits":{"const":0}}}},{"if":{"required":["billing_status"],"properties":{"billing_status":{"const":"confirmed"}}},"then":{"properties":{"charged_credits":{"type":"integer"},"remaining_credits":{"type":"integer"}}}}]},"summary":{"type":"object","required":["total","succeeded","identified","unknown","failed"],"additionalProperties":false,"properties":{"total":{"type":"integer","minimum":0,"maximum":50},"succeeded":{"type":"integer","minimum":0,"maximum":50},"identified":{"type":"integer","minimum":0,"maximum":50},"unknown":{"type":"integer","minimum":0,"maximum":50},"failed":{"type":"integer","minimum":0,"maximum":50}},"description":"total = succeeded + failed; succeeded = identified + unknown. Unknown is a successful billed prediction, not an error."}}}},"additionalProperties":false},"examples":{"phone":{"summary":"Illustrative phone response (synthetic data)","value":{"data":{"valid":false,"possible":false,"e164":null,"country":null,"country_calling_code":null},"meta":{"request_id":"11111111-1111-4111-8111-111111111111","duration_ms":12,"access":{"mode":"ip_trial","reason":"api_key_missing"},"usage":{"charged_credits":1,"remaining_credits":7,"billing_status":"confirmed","resets_at":"2026-09-26T12:00:00.000Z","limit":10,"period_seconds":86400}}}}}}}},"400":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"405":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"502":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"504":{"description":"RFC 9457 problem. Billing uncertainty requires support; do not automatically retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Existing 24-character API key, same balance as v1."},"QueryKey":{"type":"apiKey","in":"query","name":"key","description":"Existing API key for browser GET requests."}},"schemas":{"Problem":{"type":"object","required":["type","title","status","detail","instance","code","request_id"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer","minimum":400,"maximum":599},"detail":{"type":"string"},"instance":{"type":"string"},"code":{"type":"string"},"request_id":{"type":"string"},"documentation":{"type":"string"},"action":{"type":"string"},"errors":{"type":"array","items":{"type":"object","required":["pointer","message"],"properties":{"pointer":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}},"meta":{"type":"object","required":["request_id","duration_ms","usage"],"additionalProperties":false,"properties":{"request_id":{"type":"string","description":"Unique request ID for this HTTP attempt, also returned in X-Request-ID."},"duration_ms":{"type":"integer","minimum":0},"access":{"type":"object","required":["mode","reason"],"additionalProperties":false,"properties":{"mode":{"enum":["api_key","ip_trial","unauthenticated"]},"reason":{"enum":[null,"api_key_missing","api_key_invalid","api_key_not_found"]}}},"usage":{"type":"object","required":["charged_credits","remaining_credits"],"additionalProperties":false,"properties":{"charged_credits":{"type":["integer","null"],"minimum":0,"description":"Net charge of the recorded operation. Null if billing is unconfirmed."},"remaining_credits":{"type":["integer","null"],"description":"Balance at operation completion, may be negative; null when unavailable."},"billing_status":{"enum":["not_charged","confirmed","unconfirmed"]},"resets_at":{"type":["string","null"],"description":"UTC trial reset timestamp, null if no trial reset is known. Not a subscription expiry."},"limit":{"type":["integer","null"],"minimum":0},"period_seconds":{"type":["integer","null"],"minimum":1}},"allOf":[{"if":{"required":["billing_status"],"properties":{"billing_status":{"const":"unconfirmed"}}},"then":{"properties":{"charged_credits":{"const":null},"remaining_credits":{"const":null}}}},{"if":{"required":["billing_status"],"properties":{"billing_status":{"const":"not_charged"}}},"then":{"properties":{"charged_credits":{"const":0}}}},{"if":{"required":["billing_status"],"properties":{"billing_status":{"const":"confirmed"}}},"then":{"properties":{"charged_credits":{"type":"integer"},"remaining_credits":{"type":"integer"}}}}]},"summary":{"type":"object","required":["total","succeeded","identified","unknown","failed"],"additionalProperties":false,"properties":{"total":{"type":"integer","minimum":0,"maximum":50},"succeeded":{"type":"integer","minimum":0,"maximum":50},"identified":{"type":"integer","minimum":0,"maximum":50},"unknown":{"type":"integer","minimum":0,"maximum":50},"failed":{"type":"integer","minimum":0,"maximum":50}},"description":"total = succeeded + failed; succeeded = identified + unknown. Unknown is a successful billed prediction, not an error."}}},"data":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","required":["index"],"properties":{"index":{"type":"integer","minimum":0},"id":{"type":"string"},"charged_credits":{"type":"integer","minimum":0,"maximum":2},"data":{"type":"object","additionalProperties":false,"required":["input","name","gender","country","confidence","confidence_kind","sample_count","source"],"properties":{"input":{"type":"object","required":["type","value","country"],"properties":{"type":{"type":"string","enum":["name","email","username"]},"value":{"type":"string","minLength":1,"maxLength":254,"pattern":"\\S"},"country":{"type":["string","null"]},"forceToGenderize":{"type":"boolean"}},"additionalProperties":false},"result_status":{"enum":["identified","unknown"],"description":"Whether this inference produced a non-null gender, not verified personal identity."},"reason":{"enum":[null,"not_found","no_name_candidate","ambiguous","insufficient_evidence"],"description":"Only a known reason; AI unknown results use insufficient_evidence without claiming a more specific cause."},"country_source":{"enum":[null,"dataset","ai_association"]},"match":{"type":"object","additionalProperties":false,"required":["name","method","scope","country"],"properties":{"name":{"type":["string","null"]},"method":{"enum":[null,"normalized","token","substring","model_inference"]},"scope":{"enum":[null,"country","global"]},"country":{"type":["string","null"]}},"description":"Dataset candidate and lookup scope. AI has no database match; its name and scope are null."},"name":{"type":["string","null"]},"gender":{"enum":["male","female",null]},"country":{"type":["string","null"]},"confidence":{"type":["number","null"],"minimum":0,"maximum":1},"confidence_kind":{"enum":["observed_frequency","model_reported",null]},"sample_count":{"type":["integer","null"],"minimum":0},"source":{"enum":["dataset","ai","none"]}},"allOf":[{"if":{"required":["result_status"],"properties":{"result_status":{"const":"identified"}}},"then":{"properties":{"gender":{"enum":["male","female"]},"reason":{"const":null}}}},{"if":{"required":["result_status"],"properties":{"result_status":{"const":"unknown"}}},"then":{"properties":{"gender":{"const":null},"reason":{"enum":["not_found","no_name_candidate","ambiguous","insufficient_evidence"]}}}},{"if":{"properties":{"gender":{"const":null}}},"then":{"properties":{"confidence":{"const":null},"confidence_kind":{"const":null}}}},{"if":{"properties":{"source":{"const":"ai"}}},"then":{"properties":{"sample_count":{"const":null}},"allOf":[{"if":{"properties":{"input":{"required":["forceToGenderize"],"properties":{"forceToGenderize":{"const":true}}}}},"then":{},"else":{"allOf":[{"if":{"properties":{"name":{"const":null}}},"then":{"properties":{"gender":{"const":null},"country":{"const":null},"confidence":{"const":null}}}},{"if":{"properties":{"gender":{"enum":["male","female"]}}},"then":{"properties":{"name":{"type":"string","minLength":1}}}}]}},{"if":{"properties":{"gender":{"enum":["male","female"]}}},"then":{"properties":{"confidence":{"type":"number","exclusiveMinimum":0.5,"maximum":1},"confidence_kind":{"const":"model_reported"}}}}]}}]},"error":{"type":"object","required":["type","title","status","detail","instance","code","request_id"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer","minimum":400,"maximum":599},"detail":{"type":"string"},"instance":{"type":"string"},"code":{"type":"string"},"request_id":{"type":"string"},"documentation":{"type":"string"},"action":{"type":"string"},"errors":{"type":"array","items":{"type":"object","required":["pointer","message"],"properties":{"pointer":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}}}}},"oneOf":[{"required":["data"],"not":{"required":["error"]}},{"required":["error"],"not":{"required":["data"]},"properties":{"charged_credits":{"const":0}}}],"additionalProperties":false}},"results":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","required":["index"],"properties":{"index":{"type":"integer","minimum":0},"id":{"type":"string"},"charged_credits":{"type":"integer","minimum":0,"maximum":2},"data":{"type":"object","additionalProperties":false,"required":["input","name","gender","country","confidence","confidence_kind","sample_count","source"],"properties":{"input":{"type":"object","required":["type","value","country"],"properties":{"type":{"type":"string","enum":["name","email","username"]},"value":{"type":"string","minLength":1,"maxLength":254,"pattern":"\\S"},"country":{"type":["string","null"]},"forceToGenderize":{"type":"boolean"}},"additionalProperties":false},"result_status":{"enum":["identified","unknown"],"description":"Whether this inference produced a non-null gender, not verified personal identity."},"reason":{"enum":[null,"not_found","no_name_candidate","ambiguous","insufficient_evidence"],"description":"Only a known reason; AI unknown results use insufficient_evidence without claiming a more specific cause."},"country_source":{"enum":[null,"dataset","ai_association"]},"match":{"type":"object","additionalProperties":false,"required":["name","method","scope","country"],"properties":{"name":{"type":["string","null"]},"method":{"enum":[null,"normalized","token","substring","model_inference"]},"scope":{"enum":[null,"country","global"]},"country":{"type":["string","null"]}},"description":"Dataset candidate and lookup scope. AI has no database match; its name and scope are null."},"name":{"type":["string","null"]},"gender":{"enum":["male","female",null]},"country":{"type":["string","null"]},"confidence":{"type":["number","null"],"minimum":0,"maximum":1},"confidence_kind":{"enum":["observed_frequency","model_reported",null]},"sample_count":{"type":["integer","null"],"minimum":0},"source":{"enum":["dataset","ai","none"]}},"allOf":[{"if":{"required":["result_status"],"properties":{"result_status":{"const":"identified"}}},"then":{"properties":{"gender":{"enum":["male","female"]},"reason":{"const":null}}}},{"if":{"required":["result_status"],"properties":{"result_status":{"const":"unknown"}}},"then":{"properties":{"gender":{"const":null},"reason":{"enum":["not_found","no_name_candidate","ambiguous","insufficient_evidence"]}}}},{"if":{"properties":{"gender":{"const":null}}},"then":{"properties":{"confidence":{"const":null},"confidence_kind":{"const":null}}}},{"if":{"properties":{"source":{"const":"ai"}}},"then":{"properties":{"sample_count":{"const":null}},"allOf":[{"if":{"properties":{"input":{"required":["forceToGenderize"],"properties":{"forceToGenderize":{"const":true}}}}},"then":{},"else":{"allOf":[{"if":{"properties":{"name":{"const":null}}},"then":{"properties":{"gender":{"const":null},"country":{"const":null},"confidence":{"const":null}}}},{"if":{"properties":{"gender":{"enum":["male","female"]}}},"then":{"properties":{"name":{"type":"string","minLength":1}}}}]}},{"if":{"properties":{"gender":{"enum":["male","female"]}}},"then":{"properties":{"confidence":{"type":"number","exclusiveMinimum":0.5,"maximum":1},"confidence_kind":{"const":"model_reported"}}}}]}}]},"error":{"type":"object","required":["type","title","status","detail","instance","code","request_id"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer","minimum":400,"maximum":599},"detail":{"type":"string"},"instance":{"type":"string"},"code":{"type":"string"},"request_id":{"type":"string"},"documentation":{"type":"string"},"action":{"type":"string"},"errors":{"type":"array","items":{"type":"object","required":["pointer","message"],"properties":{"pointer":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}}}}},"oneOf":[{"required":["data"],"not":{"required":["error"]}},{"required":["error"],"not":{"required":["data"]},"properties":{"charged_credits":{"const":0}}}],"additionalProperties":false},"deprecated":true,"description":"Legacy alias for data on all-failed batches. Retained for compatibility."}}},"ItemProblem":{"type":"object","required":["type","title","status","detail","instance","code","request_id"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer","minimum":400,"maximum":599},"detail":{"type":"string"},"instance":{"type":"string"},"code":{"type":"string"},"request_id":{"type":"string"},"documentation":{"type":"string"},"action":{"type":"string"},"errors":{"type":"array","items":{"type":"object","required":["pointer","message"],"properties":{"pointer":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}}}},"Prediction":{"type":"object","additionalProperties":false,"required":["input","name","gender","country","confidence","confidence_kind","sample_count","source"],"properties":{"input":{"type":"object","required":["type","value","country"],"properties":{"type":{"type":"string","enum":["name","email","username"]},"value":{"type":"string","minLength":1,"maxLength":254,"pattern":"\\S"},"country":{"type":["string","null"]},"forceToGenderize":{"type":"boolean"}},"additionalProperties":false},"result_status":{"enum":["identified","unknown"],"description":"Whether this inference produced a non-null gender, not verified personal identity."},"reason":{"enum":[null,"not_found","no_name_candidate","ambiguous","insufficient_evidence"],"description":"Only a known reason; AI unknown results use insufficient_evidence without claiming a more specific cause."},"country_source":{"enum":[null,"dataset","ai_association"]},"match":{"type":"object","additionalProperties":false,"required":["name","method","scope","country"],"properties":{"name":{"type":["string","null"]},"method":{"enum":[null,"normalized","token","substring","model_inference"]},"scope":{"enum":[null,"country","global"]},"country":{"type":["string","null"]}},"description":"Dataset candidate and lookup scope. AI has no database match; its name and scope are null."},"name":{"type":["string","null"]},"gender":{"enum":["male","female",null]},"country":{"type":["string","null"]},"confidence":{"type":["number","null"],"minimum":0,"maximum":1},"confidence_kind":{"enum":["observed_frequency","model_reported",null]},"sample_count":{"type":["integer","null"],"minimum":0},"source":{"enum":["dataset","ai","none"]}},"allOf":[{"if":{"required":["result_status"],"properties":{"result_status":{"const":"identified"}}},"then":{"properties":{"gender":{"enum":["male","female"]},"reason":{"const":null}}}},{"if":{"required":["result_status"],"properties":{"result_status":{"const":"unknown"}}},"then":{"properties":{"gender":{"const":null},"reason":{"enum":["not_found","no_name_candidate","ambiguous","insufficient_evidence"]}}}},{"if":{"properties":{"gender":{"const":null}}},"then":{"properties":{"confidence":{"const":null},"confidence_kind":{"const":null}}}},{"if":{"properties":{"source":{"const":"ai"}}},"then":{"properties":{"sample_count":{"const":null}},"allOf":[{"if":{"properties":{"input":{"required":["forceToGenderize"],"properties":{"forceToGenderize":{"const":true}}}}},"then":{},"else":{"allOf":[{"if":{"properties":{"name":{"const":null}}},"then":{"properties":{"gender":{"const":null},"country":{"const":null},"confidence":{"const":null}}}},{"if":{"properties":{"gender":{"enum":["male","female"]}}},"then":{"properties":{"name":{"type":"string","minLength":1}}}}]}},{"if":{"properties":{"gender":{"enum":["male","female"]}}},"then":{"properties":{"confidence":{"type":"number","exclusiveMinimum":0.5,"maximum":1},"confidence_kind":{"const":"model_reported"}}}}]}}]},"Meta":{"type":"object","required":["request_id","duration_ms","usage"],"additionalProperties":false,"properties":{"request_id":{"type":"string","description":"Unique request ID for this HTTP attempt, also returned in X-Request-ID."},"duration_ms":{"type":"integer","minimum":0},"access":{"type":"object","required":["mode","reason"],"additionalProperties":false,"properties":{"mode":{"enum":["api_key","ip_trial","unauthenticated"]},"reason":{"enum":[null,"api_key_missing","api_key_invalid","api_key_not_found"]}}},"usage":{"type":"object","required":["charged_credits","remaining_credits"],"additionalProperties":false,"properties":{"charged_credits":{"type":["integer","null"],"minimum":0,"description":"Net charge of the recorded operation. Null if billing is unconfirmed."},"remaining_credits":{"type":["integer","null"],"description":"Balance at operation completion, may be negative; null when unavailable."},"billing_status":{"enum":["not_charged","confirmed","unconfirmed"]},"resets_at":{"type":["string","null"],"description":"UTC trial reset timestamp, null if no trial reset is known. Not a subscription expiry."},"limit":{"type":["integer","null"],"minimum":0},"period_seconds":{"type":["integer","null"],"minimum":1}},"allOf":[{"if":{"required":["billing_status"],"properties":{"billing_status":{"const":"unconfirmed"}}},"then":{"properties":{"charged_credits":{"const":null},"remaining_credits":{"const":null}}}},{"if":{"required":["billing_status"],"properties":{"billing_status":{"const":"not_charged"}}},"then":{"properties":{"charged_credits":{"const":0}}}},{"if":{"required":["billing_status"],"properties":{"billing_status":{"const":"confirmed"}}},"then":{"properties":{"charged_credits":{"type":"integer"},"remaining_credits":{"type":"integer"}}}}]},"summary":{"type":"object","required":["total","succeeded","identified","unknown","failed"],"additionalProperties":false,"properties":{"total":{"type":"integer","minimum":0,"maximum":50},"succeeded":{"type":"integer","minimum":0,"maximum":50},"identified":{"type":"integer","minimum":0,"maximum":50},"unknown":{"type":"integer","minimum":0,"maximum":50},"failed":{"type":"integer","minimum":0,"maximum":50}},"description":"total = succeeded + failed; succeeded = identified + unknown. Unknown is a successful billed prediction, not an error."}}},"Usage":{"type":"object","required":["charged_credits","remaining_credits"],"additionalProperties":false,"properties":{"charged_credits":{"type":["integer","null"],"minimum":0,"description":"Net charge of the recorded operation. Null if billing is unconfirmed."},"remaining_credits":{"type":["integer","null"],"description":"Balance at operation completion, may be negative; null when unavailable."},"billing_status":{"enum":["not_charged","confirmed","unconfirmed"]},"resets_at":{"type":["string","null"],"description":"UTC trial reset timestamp, null if no trial reset is known. Not a subscription expiry."},"limit":{"type":["integer","null"],"minimum":0},"period_seconds":{"type":["integer","null"],"minimum":1}},"allOf":[{"if":{"required":["billing_status"],"properties":{"billing_status":{"const":"unconfirmed"}}},"then":{"properties":{"charged_credits":{"const":null},"remaining_credits":{"const":null}}}},{"if":{"required":["billing_status"],"properties":{"billing_status":{"const":"not_charged"}}},"then":{"properties":{"charged_credits":{"const":0}}}},{"if":{"required":["billing_status"],"properties":{"billing_status":{"const":"confirmed"}}},"then":{"properties":{"charged_credits":{"type":"integer"},"remaining_credits":{"type":"integer"}}}}]},"Access":{"type":"object","required":["mode","reason"],"additionalProperties":false,"properties":{"mode":{"enum":["api_key","ip_trial","unauthenticated"]},"reason":{"enum":[null,"api_key_missing","api_key_invalid","api_key_not_found"]}}},"BatchResults":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","required":["index"],"properties":{"index":{"type":"integer","minimum":0},"id":{"type":"string"},"charged_credits":{"type":"integer","minimum":0,"maximum":2},"data":{"type":"object","additionalProperties":false,"required":["input","name","gender","country","confidence","confidence_kind","sample_count","source"],"properties":{"input":{"type":"object","required":["type","value","country"],"properties":{"type":{"type":"string","enum":["name","email","username"]},"value":{"type":"string","minLength":1,"maxLength":254,"pattern":"\\S"},"country":{"type":["string","null"]},"forceToGenderize":{"type":"boolean"}},"additionalProperties":false},"result_status":{"enum":["identified","unknown"],"description":"Whether this inference produced a non-null gender, not verified personal identity."},"reason":{"enum":[null,"not_found","no_name_candidate","ambiguous","insufficient_evidence"],"description":"Only a known reason; AI unknown results use insufficient_evidence without claiming a more specific cause."},"country_source":{"enum":[null,"dataset","ai_association"]},"match":{"type":"object","additionalProperties":false,"required":["name","method","scope","country"],"properties":{"name":{"type":["string","null"]},"method":{"enum":[null,"normalized","token","substring","model_inference"]},"scope":{"enum":[null,"country","global"]},"country":{"type":["string","null"]}},"description":"Dataset candidate and lookup scope. AI has no database match; its name and scope are null."},"name":{"type":["string","null"]},"gender":{"enum":["male","female",null]},"country":{"type":["string","null"]},"confidence":{"type":["number","null"],"minimum":0,"maximum":1},"confidence_kind":{"enum":["observed_frequency","model_reported",null]},"sample_count":{"type":["integer","null"],"minimum":0},"source":{"enum":["dataset","ai","none"]}},"allOf":[{"if":{"required":["result_status"],"properties":{"result_status":{"const":"identified"}}},"then":{"properties":{"gender":{"enum":["male","female"]},"reason":{"const":null}}}},{"if":{"required":["result_status"],"properties":{"result_status":{"const":"unknown"}}},"then":{"properties":{"gender":{"const":null},"reason":{"enum":["not_found","no_name_candidate","ambiguous","insufficient_evidence"]}}}},{"if":{"properties":{"gender":{"const":null}}},"then":{"properties":{"confidence":{"const":null},"confidence_kind":{"const":null}}}},{"if":{"properties":{"source":{"const":"ai"}}},"then":{"properties":{"sample_count":{"const":null}},"allOf":[{"if":{"properties":{"input":{"required":["forceToGenderize"],"properties":{"forceToGenderize":{"const":true}}}}},"then":{},"else":{"allOf":[{"if":{"properties":{"name":{"const":null}}},"then":{"properties":{"gender":{"const":null},"country":{"const":null},"confidence":{"const":null}}}},{"if":{"properties":{"gender":{"enum":["male","female"]}}},"then":{"properties":{"name":{"type":"string","minLength":1}}}}]}},{"if":{"properties":{"gender":{"enum":["male","female"]}}},"then":{"properties":{"confidence":{"type":"number","exclusiveMinimum":0.5,"maximum":1},"confidence_kind":{"const":"model_reported"}}}}]}}]},"error":{"type":"object","required":["type","title","status","detail","instance","code","request_id"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer","minimum":400,"maximum":599},"detail":{"type":"string"},"instance":{"type":"string"},"code":{"type":"string"},"request_id":{"type":"string"},"documentation":{"type":"string"},"action":{"type":"string"},"errors":{"type":"array","items":{"type":"object","required":["pointer","message"],"properties":{"pointer":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}}}}},"oneOf":[{"required":["data"],"not":{"required":["error"]}},{"required":["error"],"not":{"required":["data"]},"properties":{"charged_credits":{"const":0}}}],"additionalProperties":false}},"BatchSummary":{"type":"object","required":["total","succeeded","identified","unknown","failed"],"additionalProperties":false,"properties":{"total":{"type":"integer","minimum":0,"maximum":50},"succeeded":{"type":"integer","minimum":0,"maximum":50},"identified":{"type":"integer","minimum":0,"maximum":50},"unknown":{"type":"integer","minimum":0,"maximum":50},"failed":{"type":"integer","minimum":0,"maximum":50}},"description":"total = succeeded + failed; succeeded = identified + unknown. Unknown is a successful billed prediction, not an error."}}}}