Writer & Humanizer Async Runs

curl --request POST \
  --url https://stealthgpt.ai/api/stealthify/runs \
  --header 'Content-Type: <content-type>' \
  --header 'api-token: <api-token>' \
  --data '
{
  "text": "<string>",
  "qualityMode": "<string>",
  "model": "<string>",
  "outputFormat": "<string>",
  "webhookUrl": "<string>",
  "webhookSecret": "<string>"
}
'

{
  "runId": "<string>",
  "status": "<string>",
  "statusUrl": "<string>",
  "result": "<string>",
  "howLikelyToBeDetected": 123,
  "wordsSpent": 123,
  "creditsSpent": 123,
  "remainingCredits": 123,
  "billingMode": "<string>",
  "meteredChargedCredits": 123,
  "content-type": "<string>",
  "user-agent": "<string>",
  "x-stealthgpt-event": "<string>",
  "x-stealthgpt-run-id": "<string>",
  "x-stealthgpt-timestamp": "<string>",
  "x-stealthgpt-signature": "<string>"
}

POST

api

stealthify

runs

Writer & Humanizer Async Runs

curl --request POST \
  --url https://stealthgpt.ai/api/stealthify/runs \
  --header 'Content-Type: <content-type>' \
  --header 'api-token: <api-token>' \
  --data '
{
  "text": "<string>",
  "qualityMode": "<string>",
  "model": "<string>",
  "outputFormat": "<string>",
  "webhookUrl": "<string>",
  "webhookSecret": "<string>"
}
'

{
  "runId": "<string>",
  "status": "<string>",
  "statusUrl": "<string>",
  "result": "<string>",
  "howLikelyToBeDetected": 123,
  "wordsSpent": 123,
  "creditsSpent": 123,
  "remainingCredits": 123,
  "billingMode": "<string>",
  "meteredChargedCredits": 123,
  "content-type": "<string>",
  "user-agent": "<string>",
  "x-stealthgpt-event": "<string>",
  "x-stealthgpt-run-id": "<string>",
  "x-stealthgpt-timestamp": "<string>",
  "x-stealthgpt-signature": "<string>"
}

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

Create a run

Send POST /api/stealthify/runs with text to humanize. Optionally include webhookUrl, webhookSecret, and idempotency-key.

Store the run id

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

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

api-token

string

required

Your Stealth API token from the Stealth API dashboard.

Create a run

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

Headers

api-token

string

required

Your Stealth API token.

Content-Type

string

required

Must be application/json.

idempotency-key

string

Optional key, 1-255 characters. Reuse the same key when retrying the same create request to avoid enqueueing duplicate runs.

Request body

text

string

required

Existing text to humanize. This endpoint does not generate a new essay from a prompt.

qualityMode

string

default:"quality"

"quality" runs quality checks and repairs. "fast" performs a faster single-pass rewrite.

model

string

default:"heavy"

"heavy" uses the full StealthGPT humanizer pipeline. "lite" is faster and intended for light AI-smell cleanup.

outputFormat

string

default:"text"

"text" returns plain text. "markdown" preserves/restores markdown formatting where supported.

webhookUrl

string

Optional URL that receives a POST callback when the run reaches a terminal status.

webhookSecret

string

Optional signing secret, 16-255 characters. When present, StealthGPT signs webhook callbacks with HMAC-SHA256.

Response: 202 Accepted

runId

string

required

Identifier of the queued humanization run.

status

string

required

Always "queued" for a successful create response.

statusUrl

string

required

Relative polling URL: /api/stealthify/runs/{runId}.

{
  "runId": "stealthify-api-run:abc123",
  "status": "queued",
  "statusUrl": "/api/stealthify/runs/stealthify-api-run:abc123"
}

Poll run status

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

Headers

api-token

string

required

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

Path parameters

runId

string

required

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

Queued response

{
  "runId": "stealthify-api-run:abc123",
  "status": "queued"
}

Running response

{
  "runId": "stealthify-api-run:abc123",
  "createdAt": "2026-05-28T14:55:00.000Z",
  "updatedAt": "2026-05-28T14:55:03.000Z",
  "currentOperation": "humanizing",
  "status": "running"
}

Completed response

The completed polling response is also the successful webhook callback body.

result

string

required

Humanized output text.

howLikelyToBeDetected

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.)

wordsSpent

number

required

Total billed words for this run: input words plus output words.

creditsSpent

number

required

Credits charged for this run. Humanization bills 1 credit per word, so this equals wordsSpent.

remainingCredits

number

required

Prepaid word balance after this charge.

billingMode

string

required

"prepaid" when covered from balance, or "payg" when metered usage was applied.

meteredChargedCredits

number

required

Words billed to metered usage for this request (0 when fully prepaid).

{
  "runId": "stealthify-api-run:abc123",
  "createdAt": "2026-05-28T14:55:00.000Z",
  "updatedAt": "2026-05-28T14:56:12.000Z",
  "currentOperation": null,
  "status": "completed",
  "result": "Renewable energy has clear benefits for communities and the climate...",
  "howLikelyToBeDetected": 92,
  "wordsSpent": 260,
  "creditsSpent": 260,
  "remainingCredits": 985000,
  "billingMode": "prepaid",
  "meteredChargedCredits": 0
}

Failed response

{
  "runId": "stealthify-api-run:abc123",
  "createdAt": "2026-05-28T14:55:00.000Z",
  "updatedAt": "2026-05-28T14:56:12.000Z",
  "currentOperation": null,
  "status": "failed",
  "error": {
    "code": "humanize_failed",
    "message": "Humanization failed"
  }
}

Possible error.code values:

Code	Meaning
`humanize_failed`	The humanization pipeline failed before output was available.
`payg_terms_required`	The user ran out of prepaid credits and has not accepted pay-as-you-go terms.
`payment_required`	Credits or pay-as-you-go access were not available when billing was finalized.
`billing_delayed`	Billing was temporarily delayed; create a new run later if needed.
`result_unavailable`	The run completed, but its linked humanized result is no longer available.
`cancelled`	The run was cancelled before completion.

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

content-type

string

application/json

user-agent

string

StealthGPT-API-Webhook/1.0

x-stealthgpt-event

string

stealthify.run.completed, stealthify.run.failed, or stealthify.run.cancelled.

x-stealthgpt-run-id

string

The run id.

x-stealthgpt-timestamp

string

Unix timestamp in seconds. Present on every webhook callback.

x-stealthgpt-signature

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

import { createHmac, timingSafeEqual } from 'node:crypto'

const WEBHOOK_TOLERANCE_SECONDS = 5 * 60

function verifyStealthGptWebhook({ rawBody, timestamp, signature, secret }) {
  if (!signature) return false

  const timestampSeconds = Number(timestamp)
  const nowSeconds = Math.floor(Date.now() / 1000)

  if (
    !Number.isFinite(timestampSeconds) ||
    Math.abs(nowSeconds - timestampSeconds) > WEBHOOK_TOLERANCE_SECONDS
  ) {
    return false
  }

  const [version, receivedDigest] = signature.split('=')

  if (version !== 'v1' || !receivedDigest) return false

  const expectedDigest = createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex')

  const expected = Buffer.from(expectedDigest, 'hex')
  const received = Buffer.from(receivedDigest, 'hex')

  return (
    expected.length === received.length &&
    timingSafeEqual(expected, received)
  )
}

Examples

curl --request POST \
  --url 'https://stealthgpt.ai/api/stealthify/runs' \
  --header 'Content-Type: application/json' \
  --header 'api-token: YOUR_API_TOKEN' \
  --header 'idempotency-key: humanize-job-123' \
  --data '{
    "text": "Renewable energy offers several significant advantages in our modern world...",
    "qualityMode": "quality",
    "model": "heavy",
    "outputFormat": "text",
    "webhookUrl": "https://example.com/webhooks/stealthify",
    "webhookSecret": "whsec_your_random_signing_secret"
  }'

Errors

Endpoint	Status	Meaning
`POST /api/stealthify/runs`	400	Invalid request body or `idempotency-key`.
`POST /api/stealthify/runs`	401	Missing `api-token` header or token not found.
`POST /api/stealthify/runs`	402	Insufficient credits, pay-as-you-go not available, or payment method missing.
`POST /api/stealthify/runs`	500	Server error while creating the run.
`GET /api/stealthify/runs/{runId}`	400	Invalid `runId`.
`GET /api/stealthify/runs/{runId}`	401	Missing `api-token` header or token not found.
`GET /api/stealthify/runs/{runId}`	404	Run not found or belongs to another account.
`GET /api/stealthify/runs/{runId}`	500	Server error while reading status.

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.
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.

Writer & Humanizer AI Detector

Documentation Index

​Flow

​Authentication

​Create a run

​Headers

​Request body

​Response: 202 Accepted

​Poll run status

​Headers

​Path parameters

​Queued response

​Running response

​Completed response

​Failed response

​Webhook callbacks

​Headers

​Delivery behavior

​Verify a signature

​Examples

​Errors

​Usage notes

Flow

Authentication

Create a run

Headers

Request body

Response: 202 Accepted

Poll run status

Headers

Path parameters

Queued response

Running response

Completed response

Failed response

Webhook callbacks

Headers

Delivery behavior

Verify a signature

Examples

Errors

Usage notes