API Reference

HumanizeAI v1 is a JSON-over-HTTPS API. All endpoints live under https://api.humanizeai.chat/v1. Need a key? See pricing & sign up.

Quickstart: POST your text to /v1/humanize with your Authorization: Bearer sk_live_... key. Get back rewritten text plus a detection score breakdown. That's it.

Authentication

Every request must carry an API key in the Authorization header. Keys start with sk_live_ (production) or ck_test_ (test mode). Generate keys in your dashboard settings.

Header

Authorization: Bearer sk_live_a1b2c3d4e5f6...

Keys can be scoped (full or read-only) and given an expiration. Treat them like passwords — never embed in client-side code or commit to git. We auto-detect leaks via the sk_live_ prefix and warn you if a key shows up in a public source.

Rate limits

Two limits apply: a per-minute burst (RPM) and a per-period total (calls/month). Both are enforced at the edge. Every response includes these headers:

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 27
X-RateLimit-Reset: 1714765200
X-Usage-Period-Used: 1247
X-Usage-Period-Limit: 5000
X-Usage-Period-Reset: 1717286400

If you hit the per-minute limit you get a 429 Too Many Requests. If you hit the period cap you get a 402 Plan Limit Reached — soft caps and overage billing are configurable in your dashboard.

Errors

Errors are returned with a meaningful HTTP status and a JSON body:

{ "error": { "type": "invalid_request", "code": "missing_field", "message": "Field \"text\" is required.", "request_id": "req_..." } }

Status	Meaning	What to do
`400`	Bad request	Missing or invalid field. Check the error.message for details.
`401`	Unauthorized	Missing or invalid API key. Make sure Authorization: Bearer sk_live_... is set.
`402`	Plan limit reached	Period cap exhausted. Upgrade or wait for next period reset (see /v1/me).
`429`	Rate limited	Too many requests per minute for your plan. Back off and retry after the X-RateLimit-Reset timestamp.
`502`	Upstream model failure	Transient model error. Safe to retry with exponential backoff.

Endpoints

POST/v1/humanize

Rewrite AI text to read human. Returns rewritten text + detection score.

Request body

{ "text": "...", "tone": "casual|academic|professional|creative|seo", "target_detector": "all|gptzero|turnitin|originality|copyleaks", "frozen_keywords": ["term1","term2"], "style_id": "stl_...", "style_sample": "...", "return_detection": true }

Response

{ "id": "hum_...", "text": "...", "detection": { "score": 92, "burstiness": 78, "vocabulary": 85, "perplexity": 88, "label": "Likely Human" }, "frozen_keywords_preserved": [...], "tokens_used": 1247, "credits_used": 1, "credits_remaining": 4999, "model": "stealth-70b", "request_ms": 3104 }

POST/v1/detect

Score text against AI detectors. Read-only, faster than /humanize.

Request body

{ "text": "...", "detectors": ["gptzero","turnitin","originality"] }

Response

{ "score": 84, "by_detector": { "gptzero": 88, "turnitin": 82, "originality": 81 }, "label": "Likely Human" }

POST/v1/grammar

Grammar, spelling, and style suggestions.

Request body

{ "text": "...", "level": "academic|casual|business" }

Response

{ "suggestions": [ { "type":"grammar", "span":[12,18], "before":"...", "after":"...", "reason":"..." } ] }

POST/v1/plagiarism

Plagiarism risk scan with matched-source phrases.

Request body

{ "text": "...", "depth": "basic|full" }

Response

{ "risk_score": 12, "matches": [ { "phrase":"...", "source_url":"...", "match_pct": 0.94 } ] }

POST/v1/cite

Generate APA, MLA, or Chicago citations from any text.

Request body

{ "text": "...", "format": "apa|mla|chicago", "max_results": 10 }

Response

{ "citations": [ { "citation":"Smith, J. (2024)...", "url":"...", "doi":"..." } ] }

GET/v1/me

Current key info: plan, usage this period, rate-limit headroom.

Request body

(no body)

Response

{ "key_id":"key_...", "user_id":"u_...", "plan":"api_builder", "period_start":"2026-05-01T00:00:00Z", "period_used":1247, "period_limit":5000, "rate_limit_rpm":30 }

GET/v1/usage

Detailed usage breakdown by day + endpoint.

Request body

(no body) — query params: ?start=YYYY-MM-DD&end=YYYY-MM-DD&endpoint=humanize

Response

{ "days": [ { "date":"2026-05-07", "endpoint":"humanize", "calls": 142, "credits": 142 } ] }

GET / POST / DELETE/v1/styles[/{id}]

Manage saved writing styles (Pro+).

Request body

POST { "name":"...", "sample":"..." } — DELETE no body

Response

{ "id":"stl_...", "name":"...", "created_at":"..." }

Webhooks

Builder and Scale plans support webhook delivery for async notifications. Configure in the dashboard. Events: humanize.completed, usage.limit-warning, usage.limit-reached. Signed with HMAC-SHA256; verify the X-HumanizeAI-Signature header against your webhook secret.

Need help?

Email dev@humanizeai.chat for technical support. For Enterprise inquiries: enterprise@humanizeai.chat.