{"openapi":"3.1.0","info":{"title":"Humanizer Tool API","version":"1","summary":"Humanize AI-written text and detect AI content over REST.","description":"Authenticate every call with your API key: `Authorization: Bearer ht_live_…` (or `x-api-key`). Keys are server-side secrets — never ship them in a browser or mobile app.\n\n**Metering.** Humanize and detect draw from one word pool per account. Words are counted with Unicode word segmentation, so text written without spaces (Chinese, Japanese, Thai…) counts per word; non-empty text is at least 1 word and at least one word per 30 non-space characters. The pool is reserved before the engine runs and refunded if it fails. Over the pool → `402 quota_exceeded`, nothing consumed. Over the per-request cap → `413 text_too_long`, nothing consumed.\n\n**Test keys** (`ht_test_…`) return deterministic sample output, are never metered, do not appear in `/usage` counters and are limited to 60 requests/minute. The per-request word cap (`413`) applies to them too, so you can rehearse it.\n\n| Plan | Price | Words | Max words / request | Requests / min |\n|---|---|---|---|---|\n| Free trial | free | 2,000 once | 1,000 | 5 |\n| Starter | $29/mo | 100,000/mo | 1,500 | 30 |\n| Growth | $99/mo | 500,000/mo | 3,000 | 60 |\n| Scale | $249/mo | 1,500,000/mo | 5,000 | 120 |\n| Enterprise | $499/mo | 4,000,000/mo | 6,000 | 240 |\n\nErrors always use one envelope: `{ \"error\": { \"type\", \"code\", \"message\", \"request_id\", \"details\" } }`. Every response carries `X-Request-Id`.","contact":{"name":"Humanizer Tool","url":"https://api.humanizertool.io"},"termsOfService":"https://api.humanizertool.io/legal/api-terms"},"servers":[{"url":"https://api.humanizertool.io/v1","description":"Production REST base"}],"tags":[{"name":"Text","description":"Humanize and detect."},{"name":"Account","description":"Who am I, what is left."},{"name":"Meta","description":"No authentication required."}],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"paths":{"/health":{"get":{"tags":["Meta"],"operationId":"getHealth","summary":"Service health","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"version":{"type":"string"},"service":{"type":"string"}}},"example":{"ok":true,"version":"1","service":"humanizer-api"}}}}}}},"/openapi.json":{"get":{"tags":["Meta"],"operationId":"getOpenApi","summary":"This document","security":[],"responses":{"200":{"description":"OpenAPI 3.1 document","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/me":{"get":{"tags":["Account"],"operationId":"getMe","summary":"Account, key and plan limits","responses":{"200":{"description":"The account behind the key.","headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Unique id of this request; quote it when contacting support."},"X-Words-Remaining":{"schema":{"type":"integer"},"description":"Words left in the current pool."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"description":"Upstream engine unavailable (nothing consumed) or API disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/usage":{"get":{"tags":["Account"],"operationId":"getUsage","summary":"Word pool and request counts for the current period","responses":{"200":{"description":"Usage for the current period (the trial pool on the free plan).","headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Unique id of this request; quote it when contacting support."},"X-Words-Remaining":{"schema":{"type":"integer"},"description":"Words left in the current pool."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageReport"}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"description":"Upstream engine unavailable (nothing consumed) or API disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/humanize":{"post":{"tags":["Text"],"operationId":"humanize","summary":"Rewrite text so it reads as human-written","description":"Requires the `humanize` scope. Charges the input's word count from the pool. `output` is the rewritten text only; if the engine answers with something that is not a rewrite (e.g. a chat reply), the call is retried once and then fails with `503 upstream_unavailable`, nothing charged.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HumanizeRequest"},"example":{"text":"In today's fast-paced digital landscape, companies are leveraging cutting-edge tools to stay ahead.","style":"neutral"}}}},"responses":{"200":{"description":"Humanized text.","headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Unique id of this request; quote it when contacting support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute for this key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix seconds when the current minute window ends."},"X-Words-Remaining":{"schema":{"type":"integer"},"description":"Words left in the current pool."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HumanizeResponse"},"example":{"id":"hum_x8Kq2mN4pL7r","object":"humanize","output":"Companies are using modern tools to stay ahead.","words_in":16,"words_out":8,"style":"neutral","usage":{"words_used":16,"words_limit":2000,"words_remaining":1984,"period_end":null},"request_id":"req_0123456789abcdef01234567"}}}},"400":{"description":"Invalid request body (`details.issues` lists the validation issues).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Word quota exhausted (`details`: words_used, words_limit, period_end, upgrade_url). Nothing is consumed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Unique id of this request; quote it when contacting support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute for this key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix seconds when the current minute window ends."},"X-Words-Remaining":{"schema":{"type":"integer"},"description":"Words left in the current pool."}}},"403":{"description":"The key lacks the scope for this endpoint (`details.scope`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/NotFound"},"413":{"description":"Text exceeds `max_words_per_request` for your plan (`details`: max_words, words). Nothing is consumed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Honour `Retry-After` (seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalError"},"503":{"description":"Upstream engine unavailable (nothing consumed) or API disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/detect":{"post":{"tags":["Text"],"operationId":"detect","summary":"Estimate how likely a text is AI-written","description":"Requires the `detect` scope. Text must be at least 300 characters. Charges the input's word count from the same pool as humanize. Texts over 250 words are scored in sentence-aligned chunks; `score`/`human_score` are word-weighted averages and the counts are sums. Detect latency scales with length: use a client timeout of at least 180 s.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetectRequest"}}}},"responses":{"200":{"description":"Detection result.","headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Unique id of this request; quote it when contacting support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute for this key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix seconds when the current minute window ends."},"X-Words-Remaining":{"schema":{"type":"integer"},"description":"Words left in the current pool."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetectResponse"},"example":{"id":"det_a1B2c3D4e5F6","object":"detect","score":82,"verdict":"ai","human_score":18,"ai_word_count":54,"total_word_count":66,"sentences":[{"text":"In today's fast-paced digital landscape, companies are leveraging cutting-edge tools.","flagged":true}],"usage":{"words_used":66,"words_limit":2000,"words_remaining":1934,"period_end":null},"request_id":"req_0123456789abcdef01234567"}}}},"400":{"description":"Invalid request body (`details.issues` lists the validation issues).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Word quota exhausted (`details`: words_used, words_limit, period_end, upgrade_url). Nothing is consumed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Unique id of this request; quote it when contacting support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute for this key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix seconds when the current minute window ends."},"X-Words-Remaining":{"schema":{"type":"integer"},"description":"Words left in the current pool."}}},"403":{"description":"The key lacks the scope for this endpoint (`details.scope`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/NotFound"},"413":{"description":"Text exceeds `max_words_per_request` for your plan (`details`: max_words, words). Nothing is consumed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Text shorter than 300 characters (`details.min_chars`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Honour `Retry-After` (seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalError"},"503":{"description":"Upstream engine unavailable (nothing consumed) or API disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"responses":{"NotFound":{"description":"Unknown path or unsupported method → `404 not_found` (never 405). Same envelope as every error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Unexpected server error → `500 internal_error`. Safe to retry; quote `request_id` to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer ht_live_…` (preferred)."},"apiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key","description":"Alternative to the Authorization header."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["type","code","message","request_id","details"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","billing_error","permission_error","rate_limit_error","api_error"]},"code":{"type":"string","enum":["invalid_request","missing_api_key","invalid_api_key","key_revoked","key_expired","quota_exceeded","scope_not_allowed","plan_required","not_found","text_too_long","text_too_short","rate_limited","internal_error","upstream_unavailable","api_disabled","db_unavailable"]},"message":{"type":"string"},"request_id":{"type":"string","example":"req_0123456789abcdef01234567"},"details":{"type":"object","additionalProperties":true}}}}},"Usage":{"type":"object","description":"Word pool after this request.","required":["words_used","words_limit","words_remaining","period_end"],"properties":{"words_used":{"type":"integer"},"words_limit":{"type":"integer"},"words_remaining":{"type":"integer"},"period_end":{"type":["string","null"],"format":"date-time","description":"End of the current billing period; null on the free trial."}}},"HumanizeRequest":{"type":"object","required":["text"],"properties":{"text":{"type":"string","minLength":1,"maxLength":200000,"description":"Up to your plan's `max_words_per_request` words."},"style":{"type":"string","enum":["neutral","academic","business","creative","technical","friendly","informal"],"default":"neutral"},"length":{"type":"string","enum":["concise","normal","expanded"],"default":"normal"},"similarity":{"type":"string","enum":["low","moderate","high"],"default":"moderate","description":"How close the output stays to the input."},"language":{"type":"string","default":"auto","description":"`auto` or an ISO-639-1 code such as `en`, `de`, `es`."}}},"HumanizeResponse":{"type":"object","required":["id","object","output","words_in","words_out","style","usage","request_id"],"properties":{"id":{"type":"string","example":"hum_x8Kq2mN4pL7r"},"object":{"type":"string","const":"humanize"},"output":{"type":"string"},"words_in":{"type":"integer"},"words_out":{"type":"integer"},"style":{"type":"string","enum":["neutral","academic","business","creative","technical","friendly","informal"]},"usage":{"$ref":"#/components/schemas/Usage"},"request_id":{"type":"string"}}},"DetectRequest":{"type":"object","required":["text"],"properties":{"text":{"type":"string","minLength":300,"maxLength":200000}}},"DetectResponse":{"type":"object","required":["id","object","score","verdict","human_score","ai_word_count","total_word_count","sentences","usage","request_id"],"properties":{"id":{"type":"string","example":"det_a1B2c3D4e5F6"},"object":{"type":"string","const":"detect"},"score":{"type":"number","minimum":0,"maximum":100,"description":"AI likelihood, 0–100."},"verdict":{"type":"string","enum":["human","mixed","ai"]},"human_score":{"type":"number","minimum":0,"maximum":100},"ai_word_count":{"type":"integer"},"total_word_count":{"type":"integer"},"sentences":{"type":"array","description":"Sentences flagged as likely AI-written.","items":{"type":"object","required":["text","flagged"],"properties":{"text":{"type":"string"},"flagged":{"type":"boolean","const":true}}}},"usage":{"$ref":"#/components/schemas/Usage"},"request_id":{"type":"string"}}},"Plan":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string","enum":["free","starter","growth","scale","enterprise"]},"name":{"type":"string"}}},"Period":{"type":"object","required":["start","end"],"properties":{"start":{"type":["string","null"],"format":"date-time"},"end":{"type":["string","null"],"format":"date-time"}}},"Account":{"type":"object","required":["object","email","plan","key","limits","period"],"properties":{"object":{"type":"string","const":"account"},"email":{"type":["string","null"]},"plan":{"$ref":"#/components/schemas/Plan"},"key":{"type":"object","required":["id","name","prefix","mode","scopes","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"prefix":{"type":"string","example":"ht_live_Ab3x"},"mode":{"type":"string","enum":["live","test"]},"scopes":{"type":"array","items":{"type":"string","enum":["humanize","detect"]}},"created_at":{"type":"string","format":"date-time"}}},"limits":{"type":"object","required":["words_per_month","trial_words","max_words_per_request","requests_per_minute"],"properties":{"words_per_month":{"type":["integer","null"]},"trial_words":{"type":["integer","null"]},"max_words_per_request":{"type":"integer"},"requests_per_minute":{"type":"integer"}}},"period":{"$ref":"#/components/schemas/Period"},"request_id":{"type":"string"}}},"UsageReport":{"type":"object","required":["object","plan","period","words","requests","by_endpoint"],"properties":{"object":{"type":"string","const":"usage"},"plan":{"$ref":"#/components/schemas/Plan"},"period":{"$ref":"#/components/schemas/Period"},"words":{"type":"object","required":["used","limit","remaining"],"properties":{"used":{"type":"integer"},"limit":{"type":"integer"},"remaining":{"type":"integer"}}},"requests":{"type":"object","required":["period"],"properties":{"period":{"type":"integer"}}},"by_endpoint":{"type":"object","required":["humanize","detect"],"properties":{"humanize":{"$ref":"#/components/schemas/EndpointCount"},"detect":{"$ref":"#/components/schemas/EndpointCount"}}},"request_id":{"type":"string"}}},"EndpointCount":{"type":"object","required":["requests","words"],"properties":{"requests":{"type":"integer"},"words":{"type":"integer"}}}}}}