Writer & Humanizer Async Runs
Endpoints
Writer & Humanizer Async Runs
Create and poll asynchronous humanization runs with optional webhook callbacks
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
All optional JSON fields (
Billing is identical to text runs: input words extracted from the file plus output words, at 1 credit per word.
Possible
/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.
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 sendmultipart/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.qualityMode, model, outputFormat, webhookUrl, webhookSecret) can be sent as additional form fields.
curl
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
error.code values:
Webhook callbacks
IfwebhookUrl 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/jsonstring
StealthGPT-API-Webhook/1.0string
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, and5xxresponses are retried up to 3 attempts. 4xxresponses other than429are 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
webhookSecretis 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-keywhenever 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/stealthifyorPOST /api/stealthify/agent, depending on the workflow.