Skip to main content
POST
/
humanize
curl --request POST \
  --url https://wibble.ai/api/v1/humanize \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "text": "The mitochondria is the powerhouse of the cell."
}
'
{
  "id": "7b42f1d6-0a8c-4e8f-9a21-c6d9f47c2b10",
  "status": "running",
  "mode": "humanize",
  "input_words": 9,
  "words_reserved": 9,
  "words_charged": 9,
  "status_url": "https://wibble.ai/api/v1/humanize/7b42f1d6-0a8c-4e8f-9a21-c6d9f47c2b10",
  "current_stage": "refining_draft",
  "detected_language": "en",
  "created_at": "2026-06-14T12:00:00.000Z",
  "completed_at": null
}
Submit text to humanize and Wibble returns a job you poll for the result or track by webhook.

​
Request options

These notes add product context for the request body. The full schema, types, and defaults are generated below.
  • text is the only required field: the text to rewrite, preserving its meaning and intent.
  • auto_detect_language (default true) detects the input language for you. Supported languages today are English (US and UK). Leave it on unless you have a specific reason to fix the language yourself.
  • use_british_spellings (default false) prefers British (en-GB) spellings in the output. Set it to true for UK English; leave it false for US English.
Send an Idempotency-Key header to make a submission safe to retry. The same key with an identical body returns the original job instead of creating a new one. See Idempotency.Set webhook_url to a public HTTPS endpoint to be notified when the job finishes, so you do not have to poll. See Webhooks.

Authorizations

​
Authorization
string
header
required

API key authentication. Pass your key as Authorization: Bearer <key>. Keys look like wib_live_... and are created in the Wibble dashboard. A key must have the humanize scope to use these endpoints.

Headers

​
Idempotency-Key
string

Optional key to make submissions idempotent. Trimmed and truncated to the first 256 characters. Reusing the same key with the same request body returns the original job (HTTP 200); reusing it with a different body within the 24-hour retention window returns HTTP 409.

Maximum string length: 256

Body

application/json
​
text
string
required

The text to humanize. Must be 1 to 50,000 characters and resolve to at most 2,000 words.

Required string length: 1 - 50000
Example:

"The mitochondria is the powerhouse of the cell."

​
auto_detect_language
boolean
default:true

Whether to auto-detect the input language. Affects the initial processing stage.

​
use_british_spellings
boolean
default:false

Whether to prefer British spellings in the output.

​
webhook_url
string<uri>

Optional HTTPS URL to receive a webhook when the job finishes. Must be HTTPS, must not include credentials, and must not resolve to a private, loopback, or otherwise blocked address.

Maximum string length: 2048
Example:

"https://example.com/webhooks/wibble"

Response

Idempotent reuse. The supplied Idempotency-Key matched a previous request with an identical body, so the original job is returned.

A humanization job.

​
id
string<uuid>
required

Unique job identifier.

Example:

"7b42f1d6-0a8c-4e8f-9a21-c6d9f47c2b10"

​
status
enum<string>
required

Current job status. Terminal states are succeeded and failed.

Available options:
queued,
running,
succeeded,
failed
​
mode
string
required

The processing mode. Always humanize for this endpoint.

Example:

"humanize"

​
input_words
integer
required

Number of words counted in the input text.

Example:

9

​
words_reserved
integer
required

Number of API words reserved from the account balance for this job.

Example:

9

​
words_charged
integer
required

Net words charged (words_reserved minus refunds, floored at 0). For a failed job this is 0 because reserved words are refunded.

Example:

9

​
status_url
string<uri>
required

Absolute URL for polling this job.

Example:

"https://wibble.ai/api/v1/humanize/7b42f1d6-0a8c-4e8f-9a21-c6d9f47c2b10"

​
current_stage
string | null
required

The current pipeline stage, or null if unavailable.

Example:

"refining_draft"

​
detected_language
string | null
required

The detected input language, or null if not yet detected.

Example:

"en"

​
created_at
string<date-time>
required

ISO 8601 timestamp when the job was created.

Example:

"2026-06-14T12:00:00.000Z"

​
completed_at
string<date-time> | null
required

ISO 8601 timestamp when the job completed, or null if not finished.

Example:

null

​
output
string

The humanized text. Present only when status is succeeded; omitted otherwise.

Example:

"Mitochondria are the cell's powerhouses."

​
error
object

Present only when the job status is failed; omitted otherwise.