Skip to main content
The Wibble API humanizes text. You submit text to a single endpoint, Wibble processes it asynchronously, and you retrieve the rewritten result by polling or by receiving a webhook. This page is the API overview; each topic links to a core concept page that covers it in depth. All requests go to the production base URL: 
https://wibble.ai/api/v1

​
Authentication

Every request requires a Bearer API key in the Authorization header: 
Authorization: Bearer wib_live_...
Keys are created in the Wibble dashboard and look like wib_live_.... A key must carry the humanize scope to call these endpoints. Requests with a missing or invalid key return 401 unauthorized.
Treat API keys as secrets. The v1 API is designed for server-to-server use; use keys only from server-side code, never from a browser or mobile client. Anyone with the key can spend your account’s API words.

​
Jobs

Humanization is asynchronous. POST /humanize reserves API words and returns a job with status queued (HTTP 202). You then track the job by polling GET /humanize/{id} or by receiving a webhook. A job moves through four statuses; succeeded and failed are terminal.
StatusMeaning
queuedAccepted and waiting to start.
runningBeing processed.
succeededFinished. output contains the humanized text.
failedDid not finish. Reserved words were refunded.
For the full job object, the difference between polling and webhooks, and the recommended poll interval, see Jobs.

​
Words and billing

Each job reserves API words up front based on its input word count, and words_charged is the net amount billed after any refund. A failed job is charged 0. A 402 insufficient_words response means the account balance cannot cover the request. See Words and billing for packs, refunds, and how to buy words.

​
Limits

LimitValue
Input text50,000 characters and 2,000 words per request
Request body128,000 bytes
Concurrent jobs5 active jobs per account
Submission rate (POST)20 requests per minute per key
Lookup rate (GET)120 requests per minute per key
Idempotency key retention24 hours
Rate-limited responses (429) include a Retry-After header along with X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers describing the current window.

​
Idempotency

Send an Idempotency-Key header to make a submission safe to retry. Reusing a key with an identical body returns the original job, and reusing it with a different body within the retention window returns 409 idempotency_conflict. See Idempotency for the retry pattern and conflict handling.

​
Errors

Errors use a consistent envelope with a machine-readable code and a human-readable message: 
{
  "error": {
    "code": "validation_error",
    "message": "Text is required"
  }
}
Some errors add fields to the envelope — for example, 402 insufficient_words includes balance and words_required. See Errors for the full list of codes and how to handle each one.

​
Webhooks

Set webhook_url on a submission to receive a signed POST when the job reaches a terminal state. Wibble sends humanize.job.succeeded and humanize.job.failed events, each attempted up to 3 times with exponential backoff. Verify every delivery before trusting it. See Webhooks for the payload, signature verification, and delivery details.

​
Next steps

Quickstart

Submit your first job and read the result end to end.

Submit a job

Reference for POST /humanize, including every request option and response.

Retrieve a job

Reference for GET /humanize/{id} and the job object.

Webhooks

Verify deliveries and handle job events reliably.