Skip to main content
POST
Writer & Humanizer Async Runs
The async Writer & Humanizer API lets you humanize existing text without keeping a long HTTP connection open. Use it for Zapier, n8n, agent platforms, workflow engines, or any integration where the synchronous /api/stealthify request may exceed the caller’s timeout.
The existing POST /api/stealthify endpoint is unchanged and remains supported for current API clients. This async API is an alternative for long-running humanization, not a replacement.

Flow

1

Create a run

Send POST /api/stealthify/runs with text to humanize, or upload a PDF/DOCX file as multipart/form-data. Optionally include webhookUrl, webhookSecret, and idempotency-key.
2

Store the run id

The API returns 202 Accepted with runId, status: "queued", and statusUrl.
3

Poll or wait for webhook

Call GET /api/stealthify/runs/{runId} until status is completed, failed, or cancelled. If webhookUrl was provided, StealthGPT also sends the terminal payload to that URL.

Authentication

string
required
Your Stealth API token from the Stealth API dashboard.

Create a run

POST https://stealthgpt.ai/api/stealthify/runs

Headers

string
required
Your Stealth API token.
string
required
application/json to send text, or multipart/form-data to upload a file.
string
Optional key, 1-255 characters. Reuse the same key when retrying the same create request to avoid enqueueing duplicate runs.

Request body

string
required
Existing text to humanize — send only that source text, with no instruction wrappers. This endpoint does not generate a new essay from a prompt.
Put only the source text in text. Do not wrap it with instructions such as “Humanize the following text”, “Rewrite this to sound more human”, or “Make this undetectable”. Those prefixes confuse the model and hurt output quality. Use qualityMode, model, and outputFormat for control instead.
string
default:"quality"
"quality" runs quality checks and repairs. "fast" performs a faster single-pass rewrite.
string
default:"heavy"
"heavy" uses the full StealthGPT humanizer pipeline. "lite" is faster and intended for light AI-smell cleanup.
string
default:"text"
"text" returns plain text. "markdown" preserves/restores markdown formatting where supported.
string
Optional URL that receives a POST callback when the run reaches a terminal status.
string
Optional signing secret, 16-255 characters. When present, StealthGPT signs webhook callbacks with HMAC-SHA256.

Request body (file upload)

Instead of JSON, you can send multipart/form-data to humanize the contents of a document. The text is extracted server-side and the run behaves exactly like a text run: the humanized result is returned as plain text in the result field.
file
required
The document to humanize. Supported types: .pdf, .docx, .txt, .md. Maximum size: 4MB. Scanned or image-only documents are not supported.
All optional JSON fields (qualityMode, model, outputFormat, webhookUrl, webhookSecret) can be sent as additional form fields.
curl
Billing is identical to text runs: input words extracted from the file plus output words, at 1 credit per word.

Response: 202 Accepted

string
required
Identifier of the queued humanization run.
string
required
Always "queued" for a successful create response.
string
required
Relative polling URL: /api/stealthify/runs/{runId}.

Poll run status

GET https://stealthgpt.ai/api/stealthify/runs/{runId}

Headers

string
required
Your Stealth API token. The run must belong to this token’s account.

Path parameters

string
required
The runId returned from POST /api/stealthify/runs.

Queued response

Running response

Completed response

The completed polling response is also the successful webhook callback body.
string
required
Humanized output text.
number
required
Human-likeness score from 0 to 100. Higher is better: a higher score means the result reads as more human and is less likely to be flagged as AI; a lower score means it is more likely to be detected as AI-generated. (The field name is historical — treat a higher value as the better result.)
number
required
Total billed words for this run: input words plus output words.
number
required
Credits charged for this run. Humanization bills 1 credit per word, so this equals wordsSpent.
number
required
Prepaid word balance after this charge.
string
required
"prepaid" when covered from balance, or "payg" when metered usage was applied.
number
required
Words billed to metered usage for this request (0 when fully prepaid).

Failed response

Possible error.code values:

Webhook callbacks

If webhookUrl is present in the create request, StealthGPT sends a best-effort POST when the run reaches a terminal status: completed, failed, or cancelled.

Headers

string
application/json
string
StealthGPT-API-Webhook/1.0
string
stealthify.run.completed, stealthify.run.failed, or stealthify.run.cancelled.
string
The run id.
string
Unix timestamp in seconds. Present on every webhook callback.
string
Present when webhookSecret was provided. Format: v1={hex_hmac_sha256}.

Delivery behavior

  • Webhook delivery uses a 10-second timeout.
  • Network errors, timeouts, 429, and 5xx responses are retried up to 3 attempts.
  • 4xx responses other than 429 are treated as final failures.
  • Webhook delivery is best-effort: a failed callback does not change the run status.
  • The callback body is the same terminal payload returned by GET /api/stealthify/runs/{runId}.
  • When webhookSecret is provided, the signature is computed over ${timestamp}.${rawBody} using HMAC-SHA256.
  • Reject signed callbacks with old timestamps. A 5-minute tolerance is recommended.

Verify a signature

Use the raw request body exactly as received. Re-serializing parsed JSON can change whitespace and produce a different signature.
nodejs

Examples

Errors

Usage notes

  • Use idempotency-key whenever your create request can be retried by a queue, workflow engine, or HTTP client.
  • Poll every 5-15 seconds; there is no benefit to polling every second.
  • Store runId, statusUrl, and your own job id together so webhook handlers can reconcile callbacks with queued work.
  • Send only the source text in text — no “humanize / rewrite / make undetectable” instruction wrappers.
  • This endpoint only humanizes existing text. To generate a new essay or article from a prompt, keep using POST /api/stealthify or POST /api/stealthify/agent, depending on the workflow.