HumanProse for developers

Overview

The API is a small JSON interface over HTTPS. Every rewrite is charged to the account that owns the token, exactly like a rewrite in the workspace: plan words first, then word credits. Nothing is charged when a rewrite fails. Each successful rewrite is also saved to My Documents.

Requests and responses use JSON. Successful responses wrap their content in data; errors use the same shape everywhere (see Errors).

Authentication

Create a personal API token in Account → API access. A token starts with hp_ and is shown once, so copy it when you create it. Send it in the Authorization header of every request:

Authorization: Bearer hp_your_token_here

• An account can hold up to 10 active tokens. Give each app its own token, so you can revoke one without breaking the others.
• A token can expire after one month, three months or a year, or never. Revoke a token at any time; it stops working at once.
• Keep tokens secret. Anyone with a token can spend the account's words. Do not put one in public code or a web page.

Rewrite text

POST /humanize

Rewrites one draft and returns the result, the words it counted, your usage afterwards and the saved document.

curl -X POST https://humanprose.org/api/v1/humanize \
  -H "Authorization: Bearer $HUMANPROSE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"text": "Our team finished the project two weeks early.", "mode": "business", "length": 2}'

A successful rewrite answers 200:

{
    "data": {
        "result": "We wrapped up the project a full two weeks ahead of schedule.",
        "words_charged": 8,
        "source_language": "en",
        "quality": {
            "clarity": 94,
            "flow": 92,
            "grammar": 95,
            "tone_match": 91,
            "disclaimer": "Helpful writing indicators, not scientific or detection scores."
        },
        "document": {
            "id": 1287,
            "url": "https://humanprose.org/documents/1287"
        },
        "usage": {
            "plan": "pro",
            "plan_word_limit": 50000,
            "plan_words_used": 12408,
            "plan_words_remaining": 37592,
            "word_credits": 0,
            "free_attempts_remaining": 0,
            "max_words_per_request": 3000,
            "on_trial": false
        }
    }
}

Usage

GET /usage

Your plan, the plan words and word credits left, and the largest request you can send right now (max_words_per_request).

curl https://humanprose.org/api/v1/usage \
  -H "Authorization: Bearer $HUMANPROSE_TOKEN"

{
    "data": {
        "plan": "starter",
        "plan_word_limit": 15000,
        "plan_words_used": 3120,
        "plan_words_remaining": 11880,
        "word_credits": 2000,
        "free_attempts_remaining": 0,
        "max_words_per_request": 1500,
        "on_trial": false
    }
}

Documents

GET /documents

Your saved rewrites, newest first, 20 per page. Use page and per_page (up to 50). Documents in the trash are not listed.

curl "https://humanprose.org/api/v1/documents?per_page=10" \
  -H "Authorization: Bearer $HUMANPROSE_TOKEN"

{
    "data": [
        {
            "id": 1287,
            "title": "Our team finished the project",
            "mode": "business",
            "source_language": "en",
            "input_words": 8,
            "output_words": 11,
            "is_favorite": false,
            "url": "https://humanprose.org/documents/1287",
            "created_at": "2026-11-04T09:30:12+00:00",
            "updated_at": "2026-11-04T09:30:12+00:00"
        }
    ],
    "links": {
        "first": "https://humanprose.org/api/v1/documents?per_page=10&page=1",
        "last": "https://humanprose.org/api/v1/documents?per_page=10&page=4",
        "prev": null,
        "next": "https://humanprose.org/api/v1/documents?per_page=10&page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 4,
        "per_page": 10,
        "to": 10,
        "total": 37
    }
}

GET /documents/{id}

One document with its original_text and result_text. A document that belongs to someone else, or is in the trash, answers 404.

curl https://humanprose.org/api/v1/documents/1287 \
  -H "Authorization: Bearer $HUMANPROSE_TOKEN"

Limits

• Requests: 30 per minute and 300 per hour for each account, across all of its tokens. Responses carry X-RateLimit-Limit and X-RateLimit-Remaining; a 429 carries Retry-After.
• Words: a rewrite spends the words in text, from plan words first and then word credits. One request can hold up to max_words_per_request words (see Usage).
• Wrong tokens: repeated requests with a missing or wrong token from one network are paused for a minute.
• Timeouts: a long rewrite can take up to a minute or two. Use a client timeout of at least 180 seconds.

Errors

Every error is JSON with a stable error code and a readable message, and sometimes details such as max_words, errors (validation) or retry_after:

{
    "error": "request_word_limit",
    "message": "Your current account allows up to 1,500 words per request.",
    "max_words": 1500
}

Chrome extension

HumanProse for Chrome rewrites the text you select on any page, using your API token.

1. Install the extension. Until it is listed in the Chrome Web Store: unzip the package, open chrome://extensions, turn on Developer mode, choose Load unpacked and pick the unzipped folder.
2. Create a token in Account → API access, named for example "Chrome extension".
3. Click the HumanProse icon in the toolbar, paste the token, choose a mode and length, and save.
4. Select text on a page, right-click and choose Rewrite with HumanProse. The result opens in the extension, where you can edit it, copy it or put it in place of the selection.

The extension only talks to humanprose.org, keeps the token in the browser's extension storage, and reads a page only when you choose the menu item or "Replace selection".