Humanize API

Run the same ClearPen humanizer that powers the app — straight from your own scripts, editor, or workflow tools. One authenticated POST, one clean JSON response.

The API is available on Pro and Power plans. API calls draw from the same monthly word allowance as the app. Use it to protect your own real writing from unfair AI flags — not to mass-produce content.

Authentication

Create a key in Settings → API & Developers. The full secret (cp_live_…) is shown once at creation — store it somewhere safe. Send it as a bearer token on every request:

Authorization: Bearer cp_live_your_key_here

Keep keys server-side. Never embed a key in client-side code or a public repo. Revoke a leaked key any time from Settings.

Humanize text

POST https://www.clearpen.ai/api/v1/humanize

Request body

text (string, required) — the text to humanize. Minimum 10 words; the per-request maximum is your plan's limit (2,250 words on Pro, 3,750 on Power).
tone (string, optional) — academic (default), casual, professional, or business.

Example

curl https://www.clearpen.ai/api/v1/humanize \
  -H "Authorization: Bearer cp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "text": "The proliferation of artificial intelligence has fundamentally transformed...",
    "tone": "academic"
  }'

Response

{
  "id": "9f1c…",
  "text": "AI has changed how we write, and...",
  "aiScoreBefore": 96,
  "aiScoreAfter": 4,
  "wordCount": 142,
  "processingTimeMs": 18450,
  "usage": {
    "wordsUsed": 12842,
    "wordsLimit": 80000,
    "wordsRemaining": 67158
  }
}

aiScoreBefore / aiScoreAfter — AI-detection probability (0–100) before and after, as shown in the app.
usage — your monthly word allowance after this call.

Errors

Errors return a non-2xx status and a JSON body { "error": "...", "code": "..." }.

Status	code	Meaning
401	missing_api_key / invalid_api_key	Missing, invalid, or revoked key.
403	plan_required	Your plan doesn't include API access.
400	text_too_short / text_too_long	Outside the word limits.
429	quota_exceeded	Monthly word allowance used up.
429	rate_limited	Too many requests — slow down.
500	pipeline_error	Transient failure — retry.

Rate limits & usage

Requests are rate-limited per key to protect the service.
Words consumed by the API count against your normal monthly allowance — the same pool the app uses.
A request typically completes in well under a minute.