{"openapi":"3.1.0","info":{"title":"UltraHumanizer API","version":"1.0.0","description":"Natural rewriting, editorial controls and detail-change signals. Prepaid credits are separate from website plans. See /developer/docs for counting, retention and limits.","contact":{"name":"UltraHumanizer","email":"support@ultrahumanizer.ai","url":"https://ultrahumanizer.ai/developer"}},"servers":[{"url":"https://ultrahumanizer.ai","description":"Production API"}],"x-release-status":"live-v1","security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Server-side API key from /developer/dashboard."}}},"paths":{"/api/v1/humanize":{"post":{"operationId":"humanize","summary":"Rewrite source text","description":"One result per request. Maximum 1,000 input credits and 12,000 UTF-8 bytes. Two concurrent generations per account; 30 generation requests per minute. Results can be replayed for 24 hours. Detail changes do not verify factual accuracy.","parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9_.:-]+$"},"description":"Persist one unique ID per operation and reuse only with the same body."}],"requestBody":{"required":true,"content":{"application/json":{"example":{"text":"You can utilize Acme for $20 per month.","tone":"natural","length":"keep","strength":"balanced","reading_level":"general","protected_terms":["Acme"],"task":"humanize"},"schema":{"type":"object","required":["text"],"additionalProperties":false,"properties":{"text":{"type":"string","minLength":1},"task":{"type":"string","enum":["humanize","slop"],"default":"humanize"},"tone":{"type":"string","enum":["natural","conversational","professional"],"default":"natural"},"length":{"type":"string","enum":["keep","shorter","expand"],"default":"keep"},"strength":{"type":"string","enum":["light","balanced","strong"],"default":"balanced"},"reading_level":{"type":"string","enum":["general","simple","academic"],"default":"general"},"protected_terms":{"type":"array","maxItems":30,"items":{"type":"string","minLength":1,"maxLength":100},"default":[]}}}}}},"responses":{"200":{"description":"Illustrative successful rewrite","content":{"application/json":{"example":{"request_id":"req_example","text":"You can use Acme for $20 per month.","usage":{"billing_unit_version":"2026-10-v1","input_units":8,"charged_units":8},"detail_changes":[],"warnings":[],"engine_version":"uh-editorial-2026-10"},"schema":{"type":"object","required":["request_id","text","usage","detail_changes","warnings","engine_version"],"properties":{"request_id":{"type":"string"},"text":{"type":"string"},"engine_version":{"type":"string"},"usage":{"type":"object","required":["billing_unit_version","input_units","charged_units"],"properties":{"billing_unit_version":{"type":"string"},"input_units":{"type":"integer","minimum":0},"charged_units":{"type":"integer","minimum":0}}},"detail_changes":{"type":"array","items":{"type":"object","required":["kind","value","before","after"],"properties":{"kind":{"type":"string","enum":["number","date","link","email","quote","citation","term"]},"value":{"type":"string"},"before":{"type":"integer","minimum":0},"after":{"type":"integer","minimum":0}}}},"warnings":{"type":"array","items":{"type":"string"}}}}}}},"400":{"description":"Correct missing or unsupported fields; do not retry unchanged input.","content":{"application/json":{"schema":{"type":"object","required":["request_id","error"],"properties":{"request_id":{"type":"string"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"example":{"request_id":"req_example","error":{"code":"invalid_request","message":"Correct missing or unsupported fields; do not retry unchanged input."}}}}},"401":{"description":"Check the server-side credential or replace a revoked key.","content":{"application/json":{"schema":{"type":"object","required":["request_id","error"],"properties":{"request_id":{"type":"string"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"example":{"request_id":"req_example","error":{"code":"invalid_api_key","message":"Check the server-side credential or replace a revoked key."}}}}},"402":{"description":"Add credits before submitting a new request.","content":{"application/json":{"schema":{"type":"object","required":["request_id","error"],"properties":{"request_id":{"type":"string"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"example":{"request_id":"req_example","error":{"code":"insufficient_credits","message":"Add credits before submitting a new request."}}}}},"409":{"description":"Use a new key for a different body; reuse the same key only for the same operation.","content":{"application/json":{"schema":{"type":"object","required":["request_id","error"],"properties":{"request_id":{"type":"string"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"example":{"request_id":"req_example","error":{"code":"idempotency_conflict","message":"Use a new key for a different body; reuse the same key only for the same operation."}}}}},"413":{"description":"Reduce input size or split the source into coherent sections.","content":{"application/json":{"schema":{"type":"object","required":["request_id","error"],"properties":{"request_id":{"type":"string"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"example":{"request_id":"req_example","error":{"code":"input_limit_exceeded","message":"Reduce input size or split the source into coherent sections."}}}}},"429":{"description":"Respect Retry-After, then retry with backoff and the same idempotency key.","content":{"application/json":{"schema":{"type":"object","required":["request_id","error"],"properties":{"request_id":{"type":"string"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"example":{"request_id":"req_example","error":{"code":"rate_limited","message":"Respect Retry-After, then retry with backoff and the same idempotency key."}}}}},"503":{"description":"Retry with bounded backoff and the same idempotency key.","content":{"application/json":{"schema":{"type":"object","required":["request_id","error"],"properties":{"request_id":{"type":"string"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"example":{"request_id":"req_example","error":{"code":"temporarily_unavailable","message":"Retry with bounded backoff and the same idempotency key."}}}}},"504":{"description":"Treat status as uncertain. Recover or retry the same operation; do not create a new billable request.","content":{"application/json":{"schema":{"type":"object","required":["request_id","error"],"properties":{"request_id":{"type":"string"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"example":{"request_id":"req_example","error":{"code":"request_timeout","message":"Treat status as uncertain. Recover or retry the same operation; do not create a new billable request."}}}}}}}},"/api/v1/estimate":{"post":{"operationId":"estimate","summary":"Estimate input units (non-billable)","description":"Non-billable. Counting version 2026-10-v1: max(word/script units, ceil(UTF-8 bytes / 12)). Not a credit reservation. See the documentation for the algorithm.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"additionalProperties":false,"properties":{"text":{"type":"string","minLength":1}}}}}},"responses":{"200":{"description":"Illustrative estimate","content":{"application/json":{"example":{"input_units":8,"billing_unit_version":"2026-10-v1","within_limits":true},"schema":{"type":"object","required":["input_units","billing_unit_version","within_limits"],"properties":{"input_units":{"type":"integer","minimum":0},"billing_unit_version":{"type":"string"},"within_limits":{"type":"boolean"}}}}}},"400":{"description":"Correct missing or unsupported fields; do not retry unchanged input.","content":{"application/json":{"schema":{"type":"object","required":["request_id","error"],"properties":{"request_id":{"type":"string"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"example":{"request_id":"req_example","error":{"code":"invalid_request","message":"Correct missing or unsupported fields; do not retry unchanged input."}}}}},"401":{"description":"Check the server-side credential or replace a revoked key.","content":{"application/json":{"schema":{"type":"object","required":["request_id","error"],"properties":{"request_id":{"type":"string"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"example":{"request_id":"req_example","error":{"code":"invalid_api_key","message":"Check the server-side credential or replace a revoked key."}}}}},"429":{"description":"Respect Retry-After, then retry with backoff and the same idempotency key.","content":{"application/json":{"schema":{"type":"object","required":["request_id","error"],"properties":{"request_id":{"type":"string"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"example":{"request_id":"req_example","error":{"code":"rate_limited","message":"Respect Retry-After, then retry with backoff and the same idempotency key."}}}}}}}},"/api/v1/usage":{"get":{"operationId":"usage","summary":"Read API credit balance (non-billable)","responses":{"200":{"description":"Illustrative balance, separate from website subscription allowances","content":{"application/json":{"example":{"available_credits":29992,"reserved_credits":0},"schema":{"type":"object","required":["available_credits","reserved_credits"],"properties":{"available_credits":{"type":"integer","minimum":0},"reserved_credits":{"type":"integer","minimum":0}}}}}},"401":{"description":"Check the server-side credential or replace a revoked key.","content":{"application/json":{"schema":{"type":"object","required":["request_id","error"],"properties":{"request_id":{"type":"string"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"example":{"request_id":"req_example","error":{"code":"invalid_api_key","message":"Check the server-side credential or replace a revoked key."}}}}},"429":{"description":"Respect Retry-After, then retry with backoff and the same idempotency key.","content":{"application/json":{"schema":{"type":"object","required":["request_id","error"],"properties":{"request_id":{"type":"string"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"example":{"request_id":"req_example","error":{"code":"rate_limited","message":"Respect Retry-After, then retry with backoff and the same idempotency key."}}}}}}}},"/api/v1/requests/{id}":{"get":{"operationId":"recoverRequest","summary":"Recover request status and result","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Original result is available for 24 hours.","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string"},"status":{"type":"string","enum":["pending","complete","failed"]},"charged_units":{"type":"integer"},"result_available":{"type":"boolean"},"result":{"type":["object","null"]}}}}}},"401":{"description":"Check the server-side credential or replace a revoked key.","content":{"application/json":{"schema":{"type":"object","required":["request_id","error"],"properties":{"request_id":{"type":"string"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"example":{"request_id":"req_example","error":{"code":"invalid_api_key","message":"Check the server-side credential or replace a revoked key."}}}}},"404":{"description":"request_not_found"},"429":{"description":"Respect Retry-After, then retry with backoff and the same idempotency key.","content":{"application/json":{"schema":{"type":"object","required":["request_id","error"],"properties":{"request_id":{"type":"string"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"example":{"request_id":"req_example","error":{"code":"rate_limited","message":"Respect Retry-After, then retry with backoff and the same idempotency key."}}}}}}}}}}