# Advanced Usage
Source: https://docs.stealthgpt.ai/api-reference/advanced-usage

Learn advanced techniques and best practices for getting the most out of the StealthGPT API, including optimization strategies and advanced configuration options

## Writing Mode

When generating content (`rephrase: false`), choose how the model interprets your prompt:

<Card title="Writing Mode Options" icon="pen-nib">
  <CardGroup>
    <Card title="default" icon="file-lines">
      Follows your prompt as written. Use for emails, lists, product copy, summaries, or any format you specify — does not force essay structure.
    </Card>

    <Card title="essay" icon="graduation-cap">
      Structures the output as an academic essay. Pair with `tone` (Standard, HighSchool, College, PhD) to set education level. Send `"writingMode": "essay"` to use it.
    </Card>
  </CardGroup>
</Card>

```json theme={null}
{
  "prompt": "Write a product description for a premium leather wallet",
  "rephrase": false,
  "writingMode": "default"
}
```

## Optimizing Tone Selection

Tone applies when `writingMode` is `essay`. StealthGPT offers several tone options to match your content needs:

<Card title="Tone Options" icon="sliders">
  <CardGroup>
    <Card title="Standard" icon="pen">
      Default tone for general-purpose content. Balanced readability and formality.
    </Card>

    <Card title="HighSchool" icon="graduation-cap">
      Simpler style with occasional grammatical errors. High on Flesch-Kincaid Readability.
    </Card>

    <Card title="College" icon="book">
      Semi-complex style with occasional minor errors. Medium Flesch-Kincaid score.
    </Card>

    <Card title="PhD" icon="user-graduate">
      Complex, sophisticated style. No grammatical errors. Low Flesch-Kincaid score.
    </Card>
  </CardGroup>
</Card>

Choose the tone that best matches your target audience and content requirements.

## Humanizer Model Selection

Use the `model` parameter to choose the humanizer pipeline. Each request is billed on **input words plus output words**. See [Models](/api-reference/models) for a full comparison of Super, Standard, and Lite.

<Card title="Model Options" icon="cpu">
  <CardGroup>
    <Card title="super" icon="sparkles">
      Flagship. Highest bypass rate, billed at **\$0.05 / 100 words**. The structural rewrite also strips invisible text watermarks such as Claude's mark and Gemini's SynthID.
    </Card>

    <Card title="standard" icon="clock-rotate-left">
      Previous-generation full rewrite, billed at **\$0.20 / 1,000 words**. The structural rewrite also strips invisible text watermarks such as Claude's mark and Gemini's SynthID.
    </Card>

    <Card title="lite" icon="zap">
      Fast AI-smell cleanup that keeps the text mostly unchanged. Billed at **\$0.20 / 1,000 words**. This mode is not designed to bypass AI detectors.
    </Card>
  </CardGroup>
</Card>

```json theme={null}
{
  "prompt": "Your text here",
  "rephrase": true,
  "model": "super"
}
```

## Humanize Input (Rephrase Mode)

When humanizing existing text (`rephrase: true` on `/api/stealthify` or `/api/stealthify/runs`), send **only the source text**. Do not wrap it with model instructions. `rephrase: false` on either endpoint writes from the prompt first.

| Do | Don't |
| - | - |
| `"prompt": "Renewable energy offers several advantages..."` | `"prompt": "Humanize the following text: Renewable energy offers..."` |
| `"prompt": "Students should sleep eight hours..."` | `"prompt": "Rewrite this to sound more human and undetectable:\n\nStudents should..."` |

Instruction prefixes like "Humanize the following", "Make this undetectable", or "Rewrite in a natural tone" confuse the humanizer and degrade results. Use API parameters (`tone`, `model`, `qualityMode`, `outputFormat`) for control instead.

The prompt-crafting tips below apply to **generation** (`rephrase: false`), not to humanize/rephrase requests.

## Crafting Effective Prompts

The quality of generated content depends significantly on your prompt. Here are some techniques to improve your prompts when `rephrase` is `false`:

<AccordionGroup>
  <Accordion title="Be Specific">
    Instead of: "Write about cars"

    Try: "Write about the environmental impact of electric vehicles compared to traditional combustion engines"
  </Accordion>

  <Accordion title="Include Context">
    Instead of: "Write a product description"

    Try: "Write a product description for a premium leather wallet targeted at young professionals who value both style and functionality"
  </Accordion>

  <Accordion title="Specify Format">
    Instead of: "Write about climate change"

    Try: "Create a 5-point listicle about practical steps individuals can take to reduce their carbon footprint"
  </Accordion>

  <Accordion title="Define Voice and Tone">
    Instead of: "Write about cryptocurrency"

    Try: "Explain cryptocurrency concepts in a conversational tone as if speaking to someone with no technical background"
  </Accordion>
</AccordionGroup>

## Output Format

Control the formatting of the returned content with the `outputFormat` parameter:

<Card title="Output Format Options" icon="file-text">
  <CardGroup>
    <Card title="text" icon="type">
      Default format. Returns plain text without markdown formatting.
    </Card>

    <Card title="markdown" icon="markdown">
      Returns formatted content with markdown syntax (headings, lists, bold, etc.).
    </Card>
  </CardGroup>
</Card>

```json theme={null}
{
  "prompt": "Write a summary of quantum computing",
  "rephrase": false,
  "outputFormat": "markdown"
}
```

## Content Length Optimization

For optimal performance, we recommend keeping responses under 2,000 characters. When you need longer content:

1. Break down your content needs into smaller, focused requests
2. Use the [`/api/stealthify/agent`](/api-reference/endpoints/stealthify-agent) endpoint for complete long-form articles
3. Chain multiple requests together, using the output of one as input for another

## Using Templates

You can include templates in your prompts to guide the structure of generated content:

```json theme={null}
{
  "prompt": "Please write an email following this template:\n\nSubject: [Product] - New Features\n\nHello [Name],\n\nI'm excited to share the latest updates to [Product]...\n\nBest regards,\n[Your Name]",
  "rephrase": false
}
```

## Iterative Rephrasing

For maximum undetectability, consider an iterative approach:

<Steps>
  <Step title="Generate Initial Content">
    Create the first version of your content with `rephrase: false`
  </Step>

  <Step title="First Rephrasing">
    Submit the generated content with `rephrase: true`
  </Step>

  <Step title="Second Rephrasing">
    For even higher undetectability, submit the rephrased content for another round
  </Step>
</Steps>

<Warning>
  Too many rephrasing iterations may affect content coherence or meaning. Test and find the optimal balance.
</Warning>

## Multilingual Support

Non-English input is detected, humanized, and returned in the original language.

## Premium Quality with Stealth Agent

When undetectability and quality are paramount, send the prompt to `POST /api/stealthify/agent` instead. The Stealth Agent runs a multi-step pipeline (research → draft → optional fact-check → humanize → optional images) that consistently produces higher-quality, more grounded, and harder-to-detect long-form content than a single-pass humanizer can.

<CardGroup>
  <Card title="Academic preset" icon="graduation-cap" href="/api-reference/stealth-agent/use-cases#academic">
    Essays, literature reviews, and research-style writing with auto-formatted citations.
  </Card>

  <Card title="SEO preset" icon="magnifying-glass-chart" href="/api-reference/stealth-agent/use-cases#seo">
    Long-form blog posts grounded in keyword research and competitor analysis.
  </Card>

  <Card title="Social preset" icon="share-nodes" href="/api-reference/stealth-agent/use-cases#social">
    LinkedIn or Medium posts that match each platform's voice and structure.
  </Card>
</CardGroup>

See the [Stealth Agent overview](/api-reference/stealth-agent/overview), [usage guide](/api-reference/stealth-agent/guide), and [use cases](/api-reference/stealth-agent/use-cases) for details. Billing is `ceil(outputWords × 10)` Stealth API words per successful run; see [Pricing](/api-reference/pricing).


# Authentication
Source: https://docs.stealthgpt.ai/api-reference/authentication

Learn how to authenticate your requests to the StealthGPT API

## Obtaining Your API Token

To use the StealthGPT API, you'll need an API token that uniquely identifies your account and authorizes your requests.

<Steps>
  <Step title="Sign Up">
    Create an account on the [StealthGPT platform](https://www.stealthgpt.ai)
  </Step>

  <Step title="Activate API Access">
    Enable API access in your [dashboard](https://www.stealthgpt.ai/stealthapi) and add a payment method during activation (required before API access is enabled)
  </Step>

  <Step title="Access Your API Token">
    Find your API token in the [StealthGPT Dashboard](https://www.stealthgpt.ai/api-dashboard/api-key) under the "API Key" tab
  </Step>
</Steps>

<Warning>
  Keep your API token secure. Don't share it publicly or commit it to version control systems. Treat it as you would any sensitive credential.
</Warning>

## Using Your API Token

Include your API token in the headers of all requests to the StealthGPT API.

```bash theme={null}
curl --location 'https://www.stealthgpt.ai/api/stealthify' \
    --header 'api-token: YOUR_API_TOKEN' \
    --header 'Content-Type: application/json' \
    --data '{
        "prompt": "Your source text to humanize goes here — no instruction wrappers.",
        "rephrase": true,
        "tone": "College",
        "model": "super"
    }'
```

<Tip>
  Replace `YOUR_API_TOKEN` with the actual token from your dashboard.
</Tip>

## Token Security

If you believe your API token has been compromised:

1. Go to the [StealthGPT Dashboard](https://www.stealthgpt.ai/api-dashboard/api-key) under the "API Key" tab
2. Use the regenerate option to create a new API token
3. Update your applications with the new API token as soon as possible


# Changelog
Source: https://docs.stealthgpt.ai/api-reference/changelog

Track important updates and changes to the StealthGPT API.

<Update label="2026-10-07">
  ## AI Detector document limit

  `POST /api/stealthify/detect` now accepts documents up to 50,000 characters. The previous cap was 3,000 words.

  ### Where to Start

  * [AI Detector](/api-reference/endpoints/detect)
</Update>

<Update label="2026-10-07">
  ## Writer mode on async runs

  `POST /api/stealthify/runs` can generate content the same way as the synchronous writer, then humanize the draft.

  ### What's New

  * **`rephrase`**: `true` (default) humanizes `text`. `false` writes from `text`, then humanizes the draft
  * **`tone` and `writingMode`**: same writer controls as `POST /api/stealthify`, used only when `rephrase` is `false`
  * **`writingMode` default is `default`**: omitted `writingMode` follows the prompt on both `POST /api/stealthify` and `POST /api/stealthify/runs`. Send `"writingMode": "essay"` to keep the academic essay structure
  * **Existing clients**: requests that omit `rephrase` still humanize

  ### Where to Start

  * [Async Writer & Humanizer](/api-reference/endpoints/stealthify-runs)
</Update>

<Update label="2026-09-04">
  ## Introducing Super

  The flagship Super humanizer is available on the Writer & Humanizer API. `heavy` is deprecated and now routes to `standard`. Standard and lite pricing drops to \$0.10 / 1,000 words. Super is billed at \$0.05 / 100 words.

  ### What's New

  * **`super` model**: flagship next-gen humanizer on `POST /api/stealthify`, `POST /api/stealthify/runs`, and the MCP `humanize_text` tool
  * **`heavy` is deprecated**: `model: "heavy"` is accepted as an alias of `standard`
  * **Pricing**: `standard` and `lite` are **\$0.10 / 1,000 words**; Super is **\$0.05 / 100 words**

  ### Where to Start

  * [Models](/api-reference/models)
  * [Writer & Humanizer](/api-reference/endpoints/stealthify)
  * [Async Writer & Humanizer](/api-reference/endpoints/stealthify-runs)
  * [Pricing](/api-reference/pricing)
  * [Advanced Usage: model selection](/api-reference/advanced-usage)
</Update>

<Update label="2026-09-01">
  ## Standard Humanizer Model

  The previous-generation full rewrite is available again as `model: "standard"` on the Writer & Humanizer API.

  ### What's New

  * **`standard` model**: previous-generation full rewrite, using the earlier humanizer pipeline
  * **Available on**: `POST /api/stealthify`, `POST /api/stealthify/runs`, and the MCP `humanize_text` tool
  * **Default unchanged**: requests that omit `model` still use `heavy`

  ### Where to Start

  * [Writer & Humanizer](/api-reference/endpoints/stealthify)
  * [Async Writer & Humanizer](/api-reference/endpoints/stealthify-runs)
  * [Advanced Usage: model selection](/api-reference/advanced-usage)
</Update>

<Update label="2026-08-14">
  ## Automatic Claude Watermark Removal During Humanization

  Humanization now strips invisible Claude and Gemini text watermarks automatically. A text watermark is not a logo on the page, it is a statistical pattern baked into the model's word choices, invisible to a reader, and it can travel with copy and paste. Claude and Gemini (via SynthID) both mark output this way. Light edits often leave the signal intact. A structural rewrite at the sentence level is the category of change those marks are not built to survive, and that is what the humanizer already does.

  ### What's New

  * **Automatic on every humanize**: Claude, Gemini SynthID, and other invisible text watermarks are stripped as part of the rewrite, no extra step or parameter
  * **Sentence-level rewrite, not a synonym swap**: meaning stays intact; the mark does not survive
  * **Applies across humanizer surfaces**: `POST /api/stealthify` (`rephrase: true`), `POST /api/stealthify/runs`, and the humanize stage of Stealth Agent

  ### Where to Start

  * [Writer & Humanizer](/api-reference/endpoints/stealthify)
  * [Async Writer & Humanizer](/api-reference/endpoints/stealthify-runs)
</Update>

<Update label="2026-07-08">
  ## Humanize PDF & DOCX Files

  `POST /api/stealthify/runs` now accepts file uploads. Send a document as `multipart/form-data` and the text is extracted server-side, then humanized like a regular text run — the result is returned as plain text in the usual `result` field.

  ### What's New

  * **File upload on the async endpoint**: send `multipart/form-data` with a `file` field instead of a JSON `text` body
  * **Supported types**: `.pdf`, `.docx`, `.txt`, `.md` (max 4MB; scanned or image-only documents are not supported)
  * **Same options**: `qualityMode`, `model`, `outputFormat`, `webhookUrl`, and `webhookSecret` can be passed as form fields
  * **Same billing**: file runs use the same per-word rates as text runs

  ### Compatibility

  JSON requests to `POST /api/stealthify/runs` are unchanged. The legacy `POST /api/stealthify` endpoint is unaffected.

  ### Where to Start

  * [File upload reference](/api-reference/endpoints/stealthify-runs#request-body-file-upload)
  * [Async Writer & Humanizer reference](/api-reference/endpoints/stealthify-runs)
</Update>

<Update label="2026-07-01">
  ## Zapier Integration (Live)

  The StealthGPT [Zapier integration](/api-reference/integrations/zapier) is now live. Connect StealthGPT to 8,000+ apps and generate or humanize content inside your Zaps — no code required.

  ### What's New

  * **Live on Zapier**: add StealthGPT from **App Connections → Create connection**
  * **Bring your own API token** from your [Stealth API dashboard](https://www.stealthgpt.ai/api-dashboard)
  * Actions for **Generate Long-Form Content**, **Humanize Text**, and **Get Run Status** — built on the async API

  ### Where to Start

  * [StealthGPT for Zapier](/api-reference/integrations/zapier)
</Update>

<Update label="2026-06-17">
  ## WordPress Plugin (Live)

  The official [StealthGPT WordPress plugin](https://wordpress.org/plugins/stealthgpt/) is now available on the WordPress.org directory. Generate long-form content or humanize existing text directly in WordPress — the result lands in a draft post for review before publishing.

  ### What's New

  * **Live on WordPress.org**: install from **Plugins → Add New → search "StealthGPT"**
  * **Bring your own API key**; full generation and humanization, both written to drafts
  * Async by design — runs complete via webhook with background polling fallback

  ### Where to Start

  * [StealthGPT for WordPress](/api-reference/integrations/wordpress)
</Update>

<Update label="2026-06-11">
  ## More Integrations: Zapier & WordPress (in review)

  Two more integrations are built and currently in review on their respective marketplaces:

  * **Zapier app** — Generate Long-Form Content, Humanize Text, and Get Run Status across 7,000+ apps. In review by Zapier.
  * **WordPress plugin** — generate or humanize content into draft posts, BYO API key. In review for the WordPress.org directory.

  Until they're live, automate StealthGPT via the [n8n node](/api-reference/integrations/n8n), [MCP clients](/api-reference/integrations/mcp), or the [async REST API](/api-reference/endpoints/stealthify-agent-runs).

  ### Where to Start

  * [Zapier (coming soon)](/api-reference/integrations/zapier)
  * [WordPress (coming soon)](/api-reference/integrations/wordpress)
</Update>

<Update label="2026-06-08">
  ## n8n Node (Verified)

  StealthGPT is now an official, **n8n-verified** node, [`n8n-nodes-stealthgpt`](https://www.npmjs.com/package/n8n-nodes-stealthgpt) — listed on the [n8n integrations directory](https://n8n.io/integrations/stealthgpt/). Start content-pipeline runs and humanize text directly inside n8n workflows, using the async API under the hood.

  ### What's New

  * **Verified by n8n**: available on self-hosted **and n8n Cloud** (instance owner enables once)
  * **Operations**: Content Generation and Text Humanization, each with **Start Run** and **Get Run Status**
  * **Wait for completion**: start-and-wait (poll until terminal) or start-only for webhook/manual polling

  ### Where to Start

  * [Automate StealthGPT with n8n](/api-reference/integrations/n8n)
</Update>

<Update label="2026-06-02">
  ## MCP Server + OAuth

  StealthGPT now ships a remote **MCP (Model Context Protocol) server**, so AI agents and MCP-aware clients can generate and humanize content as a tool. Connect it in Cursor, Claude Desktop/Code, and as a one-click custom connector in **claude.ai (web)**.

  ### What's New

  * **MCP endpoint**: `https://www.stealthgpt.ai/api/mcp/mcp` (Streamable HTTP)
  * **Tools**: `generate_content`, `humanize_text`, `get_run_status`
  * **Dual auth**: OAuth 2.1 (one-click sign-in for claude.ai web) or `Authorization: Bearer YOUR_API_TOKEN` (Cursor, VS Code, Claude Desktop, CLIs) — both resolve to the same account
  * **Async by design**: tools return a `runId`; poll `get_run_status` until terminal

  ### Where to Start

  * [Use Stealth Agent from MCP clients](/api-reference/integrations/mcp)
</Update>

<Update label="2026-05-28">
  ## Async Writer & Humanizer Runs

  Writer & Humanizer now supports native async runs for long-running humanization. Create a run with `POST /api/stealthify/runs`, poll `GET /api/stealthify/runs/{runId}`, and optionally receive a terminal webhook callback through `webhookUrl`.

  ### What's New

  * **New create endpoint**: `POST /api/stealthify/runs`
  * **New polling endpoint**: `GET /api/stealthify/runs/{runId}`
  * **Idempotent create retries**: send `idempotency-key` to avoid duplicate queued runs
  * **Webhook callbacks**: receive `completed`, `failed`, or `cancelled` payloads at `webhookUrl`

  ### Compatibility

  The existing `POST /api/stealthify` endpoint is unchanged and remains supported for current API clients.

  ### Where to Start

  * [Async Writer & Humanizer reference](/api-reference/endpoints/stealthify-runs)
  * [Writer & Humanizer endpoint](/api-reference/endpoints/stealthify)
  * [Pricing](/api-reference/pricing)
</Update>

<Update label="2026-05-27">
  ## Async Stealth Agent Runs

  Stealth Agent now supports native async runs for long-running integrations. Create a run with `POST /api/stealthify/agent/runs`, poll `GET /api/stealthify/agent/runs/{runId}`, and optionally receive a terminal webhook callback through `webhookUrl`.

  ### What's New

  * **New create endpoint**: `POST /api/stealthify/agent/runs`
  * **New polling endpoint**: `GET /api/stealthify/agent/runs/{runId}`
  * **Idempotent create retries**: send `idempotency-key` to avoid duplicate queued runs
  * **Webhook callbacks**: receive `completed`, `failed`, or `cancelled` payloads at `webhookUrl`

  ### Where to Start

  * [Async runs reference](/api-reference/endpoints/stealthify-agent-runs)
  * [Stealth Agent overview](/api-reference/stealth-agent/overview)
  * [Usage guide](/api-reference/stealth-agent/guide)
</Update>

<Update label="2026-04-27">
  ## AI Detector Endpoint

  A new `POST /api/stealthify/detect` endpoint exposes the same AI-detection backend that powers the [AI Detector tool](https://www.stealthgpt.ai/free-ai-detector) on the website. Submit text and receive a `howLikelyToBeDetected` score (0-100) using the standard Stealth API authentication and billing model.

  ### What's New

  * **New endpoint**: `POST /api/stealthify/detect`
  * **Request body**: `{ "text": string }` (max 3,000 words)
  * **Response**: `howLikelyToBeDetected` (0-100), `wordsSpent`, `remainingCredits`, `billingMode`, `meteredChargedCredits`
  * **Billing**: charged words = input words (1 charged word per input word)

  ### Where to Start

  * [Endpoint reference](/api-reference/endpoints/detect)
  * [Pricing](/api-reference/pricing)
</Update>

<Update label="2026-04-27">
  ## Business Mode Removed, Replaced by Stealth Agent

  Business mode on `/api/stealthify` has been **removed** and replaced by the new [Stealth Agent](/api-reference/endpoints/stealthify-agent) endpoint. Stealth Agent runs a full pipeline (research → draft → optional fact-check → humanize → optional images) in a single call, producing higher-quality long-form output than the previous Business engine.

  ### What's Changed

  * **`business` flag removed**: The 10x business engine no longer runs. The `business` field is still accepted in `/api/stealthify` request bodies for backward compatibility but has no effect — no client changes are required.
  * **Billing simplified**: All `/api/stealthify` requests are billed at the standard rate. The 10x business multiplier no longer applies.
  * **Migration path**: Workloads that previously relied on Business mode (academic, SEO long-form, professional posts) should switch to `POST /api/stealthify/agent`.

  ### Where to Start

  * [Stealth Agent overview](/api-reference/stealth-agent/overview)
  * [Usage guide](/api-reference/stealth-agent/guide)
  * [Use cases](/api-reference/stealth-agent/use-cases)
  * [Endpoint reference](/api-reference/endpoints/stealthify-agent)
</Update>

<Update label="2026-04-17">
  ## Business Mode Temporarily Disabled

  Business mode on `/api/stealthify` is currently disabled.

  ### What's Changed

  * **`business` flag ignored**: Requests are processed with the standard engine regardless of whether `business` is sent as `true` or `false`
  * **Standard billing applied**: All `/api/stealthify` usage is billed at the standard rate, with no 10x Business multiplier
  * **Schema unchanged**: The `business` field is still accepted in request bodies for backward compatibility; no client changes are required

  See the [Writer & Humanizer endpoint](/api-reference/endpoints/stealthify), [Advanced Usage](/api-reference/advanced-usage), and [Pricing](/api-reference/pricing) pages for details.
</Update>

<Update label="2026-04-09">
  ## Stealth Agent API

  Documentation is available for **`POST /api/stealthify/agent`**: multi-step Stealth Agent generation (academic, SEO, or social) with the same Stealth API authentication and billing model as `/api/stealthify`. See [Stealth Agent](/api-reference/endpoints/stealthify-agent).
</Update>

<Update label="2026-04-07">
  ## Free-to-Start API Billing

  StealthGPT API billing has moved to a free-to-start pay-as-you-go model.

  ### What's Changed

  * **Free activation flow**: New users now activate API billing by adding a payment method instead of buying a fixed starter pack
  * **Usage-based invoicing**: API usage is billed automatically as pay-as-you-go
  * **Tiered billing thresholds**: Invoicing thresholds now scale by tier based on spend within each billing period
  * **Automatic tier advancement**: Accounts can move up to higher invoice thresholds automatically as billing-period spend increases; for higher limits or custom arrangements, email [joey@stealthgpt.ai](mailto:joey@stealthgpt.ai)

  ### Impact for Existing Users

  * **Users with prepaid words**: Existing balances continue to be used first with no interruption
  * **Legacy users**: If prompted, accept updated billing terms in the dashboard to keep uninterrupted API access
</Update>

<Update label="2026-02-23">
  ## Pay-As-You-Go Billing Enabled

  StealthGPT API now supports pay-as-you-go billing after your starter/prepaid words are used.

  ### What's New

  * **Hybrid Billing Model**: Start with free starter access after activation/payment setup (and/or prepaid words), then continue automatically on usage-based billing
  * **Standard Usage Rate**: \$0.20 per 1,000 words for standard requests (`business=false`)
  * **Business Usage Rate**: \$2.00 per 1,000 words for business requests (`business=true`)
  * **Legacy Account Action Required**: Legacy users must accept the new terms in their billing dashboard to continue billing under the updated model

  ### How It Works

  After your prepaid word balance reaches zero, requests continue without interruption and usage is billed automatically based on endpoint mode and word consumption.
</Update>

<Update label="2025-09-09">
  ## New Detector Optimization

  You can now optimize your content for specific AI detection tools using the new `detector` parameter.

  ### What's New

  * **Detector Parameter**: Choose between `"turnitin"` (default) or `"gptzero"` to optimize your content for different detection systems
  * **Automatic Optimization**: The API automatically adjusts generation settings based on your selected detector
  * **Enhanced Compatibility**: Improved performance across different AI detection platforms

  ### Getting Started

  Simply add the `detector` parameter to your `/api/stealthify` requests to get content optimized for your preferred detection tool.
</Update>

<Update label="2025-05-19">
  ## Tokens Deprecated, Words Introduced

  The StealthGPT API now uses a word-based system instead of tokens. All references to `tokens` have been replaced with `words` throughout the documentation and API responses.

  ### Deprecated Fields in [/api/stealthify](/api-reference/endpoints/stealthify)

  * `tokensSpent` (use `wordsSpent` instead)
  * `systemTokensSpent`
  * `totalTokensSpent`

  ### New Field

  * `wordsSpent` (number of words used for content generation or rephrasing)
</Update>


# Code Examples
Source: https://docs.stealthgpt.ai/api-reference/code-examples

Explore practical examples of integrating and using the StealthGPT API in different programming languages

## Python

<Tabs>
  <Tab title="Content Generation">
    ```python theme={null}
    import requests

    def generate_content(prompt, tone=None, writing_mode='default'):
        """
        Generate content using StealthGPT API

        Args:
            prompt (str): The prompt for content generation
            tone (str, optional): Standard, HighSchool, College, or PhD. Used when writing_mode is essay.
            writing_mode (str, optional): default follows the prompt. essay writes an academic essay.

        Returns:
            str: Generated content

        Note:
            For premium long-form output, use POST /api/stealthify/agent instead.
            See https://www.stealthgpt.ai docs: api-reference/stealth-agent/guide
        """
        api_token = 'YOUR_API_TOKEN'
        url = 'https://www.stealthgpt.ai/api/stealthify'

        payload = {
            'prompt': prompt,
            'rephrase': False,
            'writingMode': writing_mode,
            'model': 'super'
        }

        if tone:
            payload['tone'] = tone
            
        # Set headers
        headers = {
            'api-token': api_token,
            'Content-Type': 'application/json'
        }
        
        # Send request
        response = requests.post(url, headers=headers, json=payload)
        
        # Check for successful response
        if response.status_code == 200:
            return response.json()['result']
        else:
            raise Exception(f"Error {response.status_code}: {response.text}")
            
    # Example usage
    content = generate_content(
        prompt="Explain the benefits of cloud computing for small businesses",
        tone="College",
        writing_mode="essay"
    )
    print(content)
    ```
  </Tab>

  <Tab title="Content Rephrasing">
    ```python theme={null}
    import requests

    def rephrase_content(text):
        """
        Rephrase content using StealthGPT API

        Args:
            text (str): The text to rephrase. Send only the source text.

        Returns:
            str: Rephrased content
        """
        api_token = 'YOUR_API_TOKEN'
        url = 'https://www.stealthgpt.ai/api/stealthify'

        payload = {
            'prompt': text,
            'rephrase': True,
            'model': 'super'
        }
            
        # Set headers
        headers = {
            'api-token': api_token,
            'Content-Type': 'application/json'
        }
        
        # Send request
        response = requests.post(url, headers=headers, json=payload)
        
        # Check for successful response
        if response.status_code == 200:
            return response.json()['result']
        else:
            raise Exception(f"Error {response.status_code}: {response.text}")
            
    # Example usage
    rephrased = rephrase_content(
        "Artificial intelligence is transforming many industries by automating tasks that previously required human intelligence."
    )
    print(rephrased)
    ```
  </Tab>
</Tabs>

## Node.js

<Tabs>
  <Tab title="Content Generation">
    ```javascript theme={null}
    const axios = require('axios');

    /**
     * Generate content using StealthGPT API
     * 
     * @param {string} prompt - The prompt for content generation
     * @param {Object} options - Optional parameters
     * @param {string} options.tone - Standard, HighSchool, College, or PhD. Used when writingMode is essay.
     * @param {string} options.writingMode - default follows the prompt. essay writes an academic essay.
     * @returns {Promise<string>} - Generated content
     *
     * Note: For premium long-form output, use POST /api/stealthify/agent instead.
     * See: api-reference/stealth-agent/guide
     */
    async function generateContent(prompt, options = {}) {
      const apiToken = 'YOUR_API_TOKEN';
      const url = 'https://www.stealthgpt.ai/api/stealthify';
      
      // Prepare request payload
      const payload = {
        prompt,
        rephrase: false,
        model: 'super',
        ...options
      };
      
      try {
        // Send request
        const response = await axios.post(url, payload, {
          headers: {
            'api-token': apiToken,
            'Content-Type': 'application/json'
          }
        });
        
        return response.data.result;
      } catch (error) {
        if (error.response) {
          throw new Error(`Error ${error.response.status}: ${JSON.stringify(error.response.data)}`);
        } else {
          throw error;
        }
      }
    }

    // Example usage
    generateContent(
      'Explain the benefits of cloud computing for small businesses',
      {
        tone: 'College',
        writingMode: 'essay'
      }
    )
      .then(content => console.log(content))
      .catch(error => console.error(error));
    ```
  </Tab>

  <Tab title="Content Rephrasing">
    ```javascript theme={null}
    const axios = require('axios');

    /**
     * Rephrase content using StealthGPT API
     * 
     * @param {string} text - The source text to rephrase
     * @returns {Promise<string>} - Rephrased content
     */
    async function rephraseContent(text) {
      const apiToken = 'YOUR_API_TOKEN';
      const url = 'https://www.stealthgpt.ai/api/stealthify';
      
      // Prepare request payload
      const payload = {
        prompt: text,
        rephrase: true,
        model: 'super'
      };
      
      try {
        // Send request
        const response = await axios.post(url, payload, {
          headers: {
            'api-token': apiToken,
            'Content-Type': 'application/json'
          }
        });
        
        return response.data.result;
      } catch (error) {
        if (error.response) {
          throw new Error(`Error ${error.response.status}: ${JSON.stringify(error.response.data)}`);
        } else {
          throw error;
        }
      }
    }

    // Example usage
    rephraseContent(
      'Artificial intelligence is transforming many industries by automating tasks that previously required human intelligence.'
    )
      .then(content => console.log(content))
      .catch(error => console.error(error));
    ```
  </Tab>
</Tabs>

## Ruby

<Tabs>
  <Tab title="Content Generation">
    ```ruby theme={null}
    require 'net/http'
    require 'uri'
    require 'json'

    def generate_content(prompt, tone: nil, writing_mode: "default")
      api_token = 'YOUR_API_TOKEN'
      url = URI.parse('https://www.stealthgpt.ai/api/stealthify')

      payload = {
        prompt: prompt,
        rephrase: false,
        writingMode: writing_mode,
        model: "super"
      }

      payload[:tone] = tone if tone
      
      # Set up the HTTP request
      http = Net::HTTP.new(url.host, url.port)
      http.use_ssl = true
      request = Net::HTTP::Post.new(url.path)
      request['api-token'] = api_token
      request['Content-Type'] = 'application/json'
      request.body = payload.to_json
      
      # Send the request
      response = http.request(request)
      
      # Check for successful response
      if response.code == '200'
        return JSON.parse(response.body)['result']
      else
        raise "Error #{response.code}: #{response.body}"
      end
    end

    # Example usage
    content = generate_content(
      "Explain the benefits of cloud computing for small businesses",
      tone: "College",
      writing_mode: "essay"
    )
    puts content
    ```
  </Tab>

  <Tab title="Content Rephrasing">
    ```ruby theme={null}
    require 'net/http'
    require 'uri'
    require 'json'

    def rephrase_content(text)
      api_token = 'YOUR_API_TOKEN'
      url = URI.parse('https://www.stealthgpt.ai/api/stealthify')

      payload = {
        prompt: text,
        rephrase: true,
        model: "super"
      }
      
      # Set up the HTTP request
      http = Net::HTTP.new(url.host, url.port)
      http.use_ssl = true
      request = Net::HTTP::Post.new(url.path)
      request['api-token'] = api_token
      request['Content-Type'] = 'application/json'
      request.body = payload.to_json
      
      # Send the request
      response = http.request(request)
      
      # Check for successful response
      if response.code == '200'
        return JSON.parse(response.body)['result']
      else
        raise "Error #{response.code}: #{response.body}"
      end
    end

    # Example usage
    rephrased = rephrase_content(
      "Artificial intelligence is transforming many industries by automating tasks that previously required human intelligence."
    )
    puts rephrased
    ```
  </Tab>
</Tabs>

## Additional Languages

For examples in other programming languages or for more complex integration scenarios, please refer to the following resources:

* [API Reference Documentation](/api-reference/endpoints/stealthify)


# Balance
Source: https://docs.stealthgpt.ai/api-reference/endpoints/balance

GET https://www.stealthgpt.ai/api/stealthify/balance
Check your account balance with the /api/stealthify/balance endpoint

The `/api/stealthify/balance` endpoint allows you to check your current account balance and available words without making any content generation requests.

## Request Parameters

<ParamField type="string">
  Your unique API authentication token. You can find this in your StealthGPT dashboard under the API Key tab.
</ParamField>

## Response

<ResponseField name="credits" type="number">
  Number of words available in your account
</ResponseField>

<ResponseField name="payg" type="object | null">
  Pay-as-you-go (metered) billing status and any usage pending billing. When `null`, the account is not enrolled in metered billing.
</ResponseField>

<ResponseField name="payg.mode" type="string">
  Current pay-as-you-go billing mode. One of `metered_active`, `metered_past_due`, or `metered_setup_required`.
</ResponseField>

<ResponseField name="payg.unbilledCredits" type="number">
  Words accumulated for metered billing that have not yet been reported/flushed.
</ResponseField>

<ResponseField name="payg.lastUsageReportAt" type="string (ISO 8601 date-time) | null">
  Last time metered usage was reported/flushed (ISO 8601 date-time string).
</ResponseField>

## Example Request

<CodeGroup>
  ```bash curl-example theme={null}
  curl --location 'https://www.stealthgpt.ai/api/stealthify/balance' \
      --header 'api-token: YOUR_API_TOKEN'
  ```

  ```python python-example theme={null}
  import requests

  response = requests.get(
      'https://www.stealthgpt.ai/api/stealthify/balance',
      headers={
          'api-token': 'YOUR_API_TOKEN'
      }
  )

  print(response.json())
  ```

  ```javascript nodejs-example theme={null}
  const axios = require('axios');

  axios.get('https://www.stealthgpt.ai/api/stealthify/balance', {
      headers: {
          'api-token': 'YOUR_API_TOKEN'
      }
  }).then(response => {
      console.log(response.data);
  });
  ```
</CodeGroup>

## Example Response

```json theme={null}
{
  "credits": 985000,
  "payg": {
    "mode": "metered_active",
    "unbilledCredits": 12450,
    "lastUsageReportAt": "2026-02-13T10:15:30.000Z"
  }
}
```

## Usage Notes

* This endpoint is lightweight and can be called frequently to track your balance
* No words are consumed when checking your balance
* Use this endpoint to implement balance tracking in your applications or to check before making requests


# AI Detector
Source: https://docs.stealthgpt.ai/api-reference/endpoints/detect

POST https://www.stealthgpt.ai/api/stealthify/detect
Score text for AI-generated content with the /api/stealthify/detect endpoint

The `/api/stealthify/detect` endpoint runs the same AI-detection backend that powers the [StealthGPT AI Detector](https://www.stealthgpt.ai/free-ai-detector) on the website. Submit a piece of text and receive a 0-100 score indicating how likely it is to be flagged as AI-generated by detection tools.

## Request Parameters

<ParamField type="string">
  Your unique API authentication token. You can find this in your StealthGPT dashboard under the API Key tab.
</ParamField>

<ParamField type="string">
  The text to analyze. Maximum 50,000 characters per request.
</ParamField>

## Response

<ResponseField name="howLikelyToBeDetected" type="number">
  A score from 0 to 100 indicating how likely the text is to be flagged as AI-generated by detection tools. Higher means more likely to be flagged.
</ResponseField>

<ResponseField name="wordsSpent" type="number">
  Number of words charged for this request (equal to the input word count).
</ResponseField>

<ResponseField name="remainingCredits" type="number">
  Number of prepaid words remaining in your account after this request.
</ResponseField>

<ResponseField name="billingMode" type="string">
  Whether the request was billed from prepaid words (`prepaid`) or pay-as-you-go metered billing (`payg`).
</ResponseField>

<ResponseField name="meteredChargedCredits" type="number">
  If billed via pay-as-you-go, the number of words added to metered usage for this request (0 when billed from prepaid).
</ResponseField>

## Example Request

<CodeGroup>
  ```bash curl-example theme={null}
  curl --location 'https://www.stealthgpt.ai/api/stealthify/detect' \
      --header 'api-token: YOUR_API_TOKEN' \
      --header 'Content-Type: application/json' \
      --data '{
          "text": "Renewable energy sources, including solar and wind power, represent inexhaustible resources unlike finite fossil fuels."
      }'
  ```

  ```python python-example theme={null}
  import requests

  response = requests.post(
      'https://www.stealthgpt.ai/api/stealthify/detect',
      headers={
          'api-token': 'YOUR_API_TOKEN',
          'Content-Type': 'application/json'
      },
      json={
          'text': 'Renewable energy sources, including solar and wind power, represent inexhaustible resources unlike finite fossil fuels.'
      }
  )

  print(response.json())
  ```

  ```javascript nodejs-example theme={null}
  const axios = require('axios');

  axios.post('https://www.stealthgpt.ai/api/stealthify/detect', {
      text: 'Renewable energy sources, including solar and wind power, represent inexhaustible resources unlike finite fossil fuels.'
  }, {
      headers: {
          'api-token': 'YOUR_API_TOKEN',
          'Content-Type': 'application/json'
      }
  }).then(response => {
      console.log(response.data);
  });
  ```
</CodeGroup>

## Example Response

```json theme={null}
{
  "howLikelyToBeDetected": 87,
  "wordsSpent": 16,
  "remainingCredits": 984984,
  "billingMode": "prepaid",
  "meteredChargedCredits": 0
}
```

## Score Interpretation

The `howLikelyToBeDetected` score is a probability expressed on a 0-100 scale.

| Score range | Interpretation |
| - | - |
| 0 - 30 | Likely human-written. Low risk of being flagged as AI. |
| 31 - 70 | Mixed signals. May be partially AI-generated or heavily edited. |
| 71 - 100 | Likely AI-generated. High risk of being flagged by detectors. |

<Note>
  Detection scores are probabilistic. Short inputs (under \~50 words) and highly templated text (e.g. resumes, legal boilerplate) can produce noisy results regardless of how the text was written.
</Note>

## Pairing With Humanizer

A common workflow is to humanize text with [`/api/stealthify`](/api-reference/endpoints/stealthify) and then verify the result with `/api/stealthify/detect`:

```javascript theme={null}
const stealthified = await fetch('https://www.stealthgpt.ai/api/stealthify', {
  method: 'POST',
  headers: {
    'api-token': 'YOUR_API_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ prompt: sourceText, rephrase: true }),
}).then(r => r.json())

const detection = await fetch('https://www.stealthgpt.ai/api/stealthify/detect', {
  method: 'POST',
  headers: {
    'api-token': 'YOUR_API_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ text: stealthified.result }),
}).then(r => r.json())

console.log('humanizer score:', stealthified.howLikelyToBeDetected)
console.log('independent detector score:', detection.howLikelyToBeDetected)
```

<Warning>
  The two `howLikelyToBeDetected` fields are **inverse** orientations. On
  `/api/stealthify` (and the humanizer runs) it is a **human-likeness** score
  where **higher is better** (more human). On `/api/stealthify/detect` it is an
  **AI-likelihood** score where **higher means more likely AI**. A good
  humanizer result is therefore **high** on `/api/stealthify` and **low** on
  `/api/stealthify/detect`.
</Warning>

Use `/api/stealthify/detect` when you need to score arbitrary text that did not pass through the humanizer.

## Usage Notes

* Billing is `input words` per request (1 charged word per input word). See [Pricing](/api-reference/pricing) for rates.
* Inputs over 50,000 characters return `400 Bad Request`. Split long documents into multiple calls and average the scores client-side if needed.
* The detector is language-agnostic; non-English input is supported.


# Writer & Humanizer
Source: https://docs.stealthgpt.ai/api-reference/endpoints/stealthify

POST https://www.stealthgpt.ai/api/stealthify
Generate or rephrase content with the /api/stealthify endpoint

The `/api/stealthify` endpoint is the core of the StealthGPT API, allowing you to generate new content or rephrase existing text to be undetectable by AI detection tools.

<Warning>
  **`model` is required.** You must explicitly pass `"super"`, `"standard"`, or `"lite"`. Requests that omit `model` return `400 Bad Request`. There is no default, please pick one.
</Warning>

<Info>
  For integrations that cannot keep a request open, use the async [`POST /api/stealthify/runs`](/api-reference/endpoints/stealthify-runs) flow. `rephrase` works the same way there. This synchronous endpoint remains unchanged for existing API clients.
</Info>

<Info>
  Humanization automatically strips invisible AI text watermarks. Claude and Gemini embed a statistical pattern in their word choices, invisible to a reader, but it travels with copy and paste and can survive light editing. The humanizer rewrites at the sentence and structure level rather than swapping synonyms, which is the category of change those marks are not built to survive. Meaning stays intact; Claude, Gemini SynthID, and other invisible text watermarks do not.
</Info>

## Request Parameters

<ParamField type="string">
  Your unique API authentication token. You can find this in your StealthGPT dashboard under the API Key tab.
</ParamField>

<ParamField type="string">
  When `rephrase` is `false`, the topic or instructions for content generation. When `rephrase` is `true`, the existing text to humanize — send only that source text, with no instruction wrappers. Maximum 3,000 words per request.
</ParamField>

<ParamField type="boolean">
  Set to `true` to rephrase the provided prompt text, or `false` to generate new content based on the prompt
</ParamField>

<ParamField type="string">
  Selects the humanizer model. **Required** — you must pass one of `"super"`, `"standard"`, or `"lite"`. Omitting `model` returns `400`. See [Models](/api-reference/models) for a full comparison.

  <Expandable title="Available model options">
    <ResponseField>
      <ResponseField name="super">
        **Flagship.** Next-gen humanizer billed at **\$0.05 / 100 words**. Highest bypass rate; the structural rewrite also strips invisible text watermarks such as Claude's mark and Gemini's SynthID.
      </ResponseField>

      <ResponseField name="standard">
        Billed at **\$0.20 / 1,000 words**. Previous-generation full rewrite; removes invisible text watermarks such as Claude's mark and Gemini's SynthID.
      </ResponseField>

      <ResponseField name="lite">
        Fast AI-smell cleanup that keeps the text mostly unchanged. Billed at **\$0.20 / 1,000 words**. This mode is **not** designed to bypass AI detectors.
      </ResponseField>
    </ResponseField>
  </Expandable>
</ParamField>

<Warning>
  **Humanize / rephrase input:** when `rephrase` is `true`, put **only the source text** in `prompt`. Do not add 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. Control style with API parameters (`tone`, `model`, `qualityMode`, etc.) instead. Instruction-style prompts are for generation (`rephrase: false`) only.
</Warning>

<ParamField type="string">
  Controls the style and complexity of generated content when `writingMode` is `essay` (ignored in default mode and when `rephrase` is `true`)

  <Expandable title="Available tone options">
    <ResponseField>
      <ResponseField name="Standard" type="default">
        Ideal for casual writing. Easy to read and understand, suitable for general purposes.
      </ResponseField>

      <ResponseField name="HighSchool">
        Mimics the style of high school level writing. May contain grammatical errors. Scores high on Flesch-Kincaid Readability.
      </ResponseField>

      <ResponseField name="College">
        Semi-complex style typical of college-level writing. May include minor grammatical errors. Moderate Flesch-Kincaid Readability score.
      </ResponseField>

      <ResponseField name="PhD">
        Complex, sophisticated style. No grammatical errors. Low Flesch-Kincaid Readability score, ideal for academic writing.
      </ResponseField>
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField type="string">
  Controls how content is generated when `rephrase` is `false`. Has no effect when `rephrase` is `true`.

  <Expandable title="Available writingMode options">
    <ResponseField>
      <ResponseField name="default" type="default">
        Follows the user's prompt as written. Does not force essay structure — suitable for emails, lists, product copy, summaries, or any other format you specify.
      </ResponseField>

      <ResponseField name="essay">
        Structures the output as an academic essay. Use with `tone` to set education level (Standard, HighSchool, College, PhD).
      </ResponseField>
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField type="string">
  Controls rewrite quality vs speed.

  <Expandable title="Available qualityMode options">
    <ResponseField>
      <ResponseField name="quality">
        Default. Runs our quality checks/repairs for better reliability and lower detection risk.
      </ResponseField>

      <ResponseField name="fast">
        Skips quality checks/repairs and performs a single-pass rewrite. Output may have more errors and be more detectable.
      </ResponseField>
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField type="string">
  Controls the formatting of the returned content.

  <Expandable title="Available output formats">
    <ResponseField>
      <ResponseField name="text">
        Default format. Returns plain text output.
      </ResponseField>

      <ResponseField name="markdown">
        Returns formatted content with markdown syntax (headings, lists, bold, etc.).
      </ResponseField>
    </ResponseField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="result" type="string">
  The generated or rephrased content
</ResponseField>

<ResponseField name="howLikelyToBeDetected" type="number">
  Human-likeness score from 0 to 100. **Higher is better**: a higher score means the content 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.)
</ResponseField>

<ResponseField name="remainingCredits" type="number">
  Prepaid word balance remaining after this request.
</ResponseField>

<ResponseField name="wordsSpent" type="number">
  Words charged for this request.
</ResponseField>

<ResponseField name="billingMode" type="string">
  Whether the request was billed from prepaid words (`prepaid`) or pay-as-you-go metered billing (`payg`).
</ResponseField>

<ResponseField name="meteredChargedCredits" type="number">
  If billed via pay-as-you-go, words added to metered usage for this request (0 when billed from prepaid).
</ResponseField>

## Example Request

<CodeGroup>
  ```bash curl-example theme={null}
  curl --location 'https://www.stealthgpt.ai/api/stealthify' \
      --header 'api-token: YOUR_API_TOKEN' \
      --header 'Content-Type: application/json' \
      --data '{
          "prompt": "Explain the benefits of renewable energy",
          "rephrase": false,
          "writingMode": "essay",
          "tone": "College",
          "qualityMode": "quality",
          "model": "super",
          "outputFormat": "markdown"
      }'
  ```

  ```python python-example theme={null}
  import requests

  response = requests.post(
      'https://www.stealthgpt.ai/api/stealthify',
      headers={
          'api-token': 'YOUR_API_TOKEN',
          'Content-Type': 'application/json'
      },
      json={
          'prompt': 'Explain the benefits of renewable energy',
          'rephrase': False,
          'writingMode': 'essay',
          'tone': 'College',
          'qualityMode': 'quality',
          'model': 'super',
          'outputFormat': 'markdown'
      }
  )

  print(response.json())
  ```

  ```javascript nodejs-example theme={null}
  const axios = require('axios');

  axios.post('https://www.stealthgpt.ai/api/stealthify', {
      prompt: 'Explain the benefits of renewable energy',
      rephrase: false,
      writingMode: 'essay',
      tone: 'College',
      qualityMode: 'quality',
      model: 'super',
      outputFormat: 'markdown'
  }, {
      headers: {
          'api-token': 'YOUR_API_TOKEN',
          'Content-Type': 'application/json'
      }
  }).then(response => {
      console.log(response.data);
  });
  ```
</CodeGroup>

<Tip>
  Super is billed at **\$0.05 / 100 words** (vs **\$0.20 / 1,000 words** for `standard` and `lite`). Both rates apply to **input words plus output words**.
</Tip>

## Example Response

```json theme={null}
{
  "result": "Renewable energy offers several significant advantages in our modern world. Students and researchers point to multiple benefits like reduced carbon emissions, which helps fight climate change. These energy sources, including solar and wind power, represent inexhaustible resources unlike finite fossil fuels. Many communities find economic advantages through job creation in the growing renewable sector. Additionally, these technologies typically require less maintenance after installation and reduce dependency on foreign energy imports. Advancements continue making these options more cost-competitive, with prices dropping significantly over recent years. While challenges exist in implementation, the long-term benefits to environmental health, economic stability, and energy independence make renewable energy sources increasingly attractive options for our global energy needs.",
  "howLikelyToBeDetected": 92,
  "wordsSpent": 260,
  "remainingCredits": 985000,
  "billingMode": "prepaid",
  "meteredChargedCredits": 0
}
```

## Usage Notes

* For optimal performance, we recommend keeping responses under 2,000 characters
* When `rephrase` is `true`, send only the source text in `prompt` — no "humanize / rewrite / make undetectable" wrappers
* When `rephrase` is `false`, the quality and relevance of generated content depends on the phrasing of your prompts
* Humanization automatically strips invisible AI text watermarks (Claude, Gemini SynthID, and similar marks) as part of the sentence-level rewrite, no extra parameter
* For more advanced usage techniques, see our [Advanced Usage Guide](/api-reference/advanced-usage)


# Stealth Agent
Source: https://docs.stealthgpt.ai/api-reference/endpoints/stealthify-agent

POST https://www.stealthgpt.ai/api/stealthify/agent
Long-form Stealth Agent generation via POST /api/stealthify/agent

The `/api/stealthify/agent` endpoint runs a **Stealth Agent** pipeline: research, generation, humanization, and optional fact-checking and image insertion. It uses the same Stealth API word balance and pay-as-you-go rules as `/api/stealthify`.

Requests can take several minutes. Use a client timeout of **at least 10 minutes** (the server allows up to 600 seconds).

<Info>
  For production integrations, workflow engines, or UI backends, use the async [`POST /api/stealthify/agent/runs`](/api-reference/endpoints/stealthify-agent-runs) endpoint. It returns immediately with a `runId`, supports `idempotency-key`, and can send a webhook callback.
</Info>

## Authentication

<ParamField type="string">
  Your Stealth API token from the [Stealth API dashboard](https://www.stealthgpt.ai/api-dashboard).
</ParamField>

## Request body

Send JSON with a required `preset` that selects one of three shapes (discriminated union). Unknown fields are rejected (`strict` schema).

### Academic

<ParamField type="string">
  Must be `"academic"`.
</ParamField>

<ParamField type="string">
  Topic or instructions for the academic-style document (non-empty).
</ParamField>

<ParamField type="boolean">
  When `true`, runs a fact-check pass on the draft and applies fixes before humanization.
</ParamField>

<ParamField type="boolean">
  When `true`, may embed generated images in the final markdown where supported.
</ParamField>

### SEO

<ParamField type="string">
  Must be `"seo"`.
</ParamField>

<ParamField type="string">
  Topic or brief for SEO-oriented content (non-empty).
</ParamField>

<ParamField type="boolean">
  Same behavior as academic.
</ParamField>

<ParamField type="boolean">
  Same behavior as academic.
</ParamField>

### Social

<ParamField type="string">
  Must be `"social"`.
</ParamField>

<ParamField type="string">
  Topic or brief for the social post (non-empty).
</ParamField>

<ParamField type="string">
  Target platform: `"linkedin"` or `"medium"`.
</ParamField>

<ParamField type="boolean">
  Same behavior as academic.
</ParamField>

<ParamField type="boolean">
  Same behavior as academic.
</ParamField>

## Successful response (200)

<ResponseField name="runId" type="string">
  Identifier of the Stealth Agent run (stored server-side).
</ResponseField>

<ResponseField name="documentId" type="string">
  Identifier of the saved document record for this run.
</ResponseField>

<ResponseField name="preset" type="string">
  Echoes the request preset: `academic`, `seo`, or `social`.
</ResponseField>

<ResponseField name="result" type="string">
  Final content as markdown (same primary output that is stored for the document; may include embedded images when `enableImageGeneration` is true).
</ResponseField>

<ResponseField name="outputWords" type="number">
  Word count of `result` used for billing.
</ResponseField>

<ResponseField name="creditsSpent" type="number">
  Stealth API words charged for this request (see [Pricing](/api-reference/pricing)).
</ResponseField>

<ResponseField name="remainingCredits" type="number">
  Prepaid word balance after this charge (metered usage may still be reported separately).
</ResponseField>

<ResponseField name="billingMode" type="string">
  `"prepaid"` when the request was covered from balance, or `"payg"` when metered pay-as-you-go usage was applied for part or all of the charge.
</ResponseField>

<ResponseField name="meteredChargedCredits" type="number">
  Words billed to metered usage for this request (0 when fully prepaid).
</ResponseField>

## Errors

| Status | Meaning |
| - | - |
| **400** | Invalid JSON or validation error. Body may include `message` and `info` (issue details). |
| **401** | Missing `api-token` header or token not found. |
| **402** | Insufficient credits, pay-as-you-go not available, payment method missing, or billing cap delay. `message` describes the case. |
| **499** | Request was aborted (client disconnect or cancellation). |
| **500** | Server error. `message` may contain a short description. |

## Example: academic

<CodeGroup>
  ```bash curl theme={null}
  curl --request POST \
    --url 'https://www.stealthgpt.ai/api/stealthify/agent' \
    --header 'Content-Type: application/json' \
    --header 'api-token: YOUR_API_TOKEN' \
    --max-time 600 \
    --data '{
      "preset": "academic",
      "prompt": "Outline creatine benefits for older adults in resistance training",
      "enableFactCheck": true,
      "enableImageGeneration": false
    }'
  ```

  ```python python theme={null}
  import requests

  response = requests.post(
      "https://www.stealthgpt.ai/api/stealthify/agent",
      headers={
          "api-token": "YOUR_API_TOKEN",
          "Content-Type": "application/json",
      },
      json={
          "preset": "academic",
          "prompt": "Outline creatine benefits for older adults in resistance training",
          "enableFactCheck": True,
          "enableImageGeneration": False,
      },
      timeout=600,
  )
  print(response.status_code, response.json())
  ```

  ```javascript nodejs theme={null}
  const axios = require("axios");

  axios
    .post(
      "https://www.stealthgpt.ai/api/stealthify/agent",
      {
        preset: "academic",
        prompt:
          "Outline creatine benefits for older adults in resistance training",
        enableFactCheck: true,
        enableImageGeneration: false,
      },
      {
        headers: {
          "api-token": "YOUR_API_TOKEN",
          "Content-Type": "application/json",
        },
        timeout: 600_000,
      },
    )
    .then((r) => console.log(r.data))
    .catch(console.error);
  ```
</CodeGroup>

## Example: social

```json theme={null}
{
  "preset": "social",
  "prompt": "Post about sustainable remote work habits",
  "platform": "linkedin",
  "enableFactCheck": false,
  "enableImageGeneration": true
}
```

## Usage notes

* Billing uses **output words** only: charged words = `ceil(outputWords × 10)` toward your Stealth API balance (see [Pricing](/api-reference/pricing)).
* You must have prepaid words **or** accepted pay-as-you-go terms with a valid payment method when balance is low—same rules as other Stealth API endpoints.
* Prefer the async runs endpoint when retries are possible: `POST /api/stealthify/agent/runs` supports `idempotency-key`.
* Retry synchronous requests with care: each successful `200` run creates a new run and document and charges credits again.


# Stealth Agent Async Runs
Source: https://docs.stealthgpt.ai/api-reference/endpoints/stealthify-agent-runs

POST https://www.stealthgpt.ai/api/stealthify/agent/runs
Create and poll asynchronous Stealth Agent runs with optional webhook callbacks

The async Stealth Agent API lets you start a long-running generation job, return immediately, and receive the final result later by polling or webhook callback. Use it for integrations, automations, UI backends, and agent platforms where a multi-minute HTTP request is unreliable.

<Info>
  If you need a simple one-off script and can keep the connection open for up to 10 minutes, use the synchronous [`POST /api/stealthify/agent`](/api-reference/endpoints/stealthify-agent) endpoint. For production integrations, prefer async runs.
</Info>

## Flow

<Steps>
  <Step title="Create a run">
    Send `POST /api/stealthify/agent/runs` with the same preset body as the synchronous endpoint. Optionally include `webhookUrl` and `idempotency-key`.
  </Step>

  <Step title="Store the run id">
    The API returns `202 Accepted` with `runId`, `status: "queued"`, and `statusUrl`.
  </Step>

  <Step title="Poll or wait for webhook">
    Call `GET /api/stealthify/agent/runs/{runId}` until `status` is `completed`, `failed`, or `cancelled`. If `webhookUrl` was provided, StealthGPT also sends the terminal payload to that URL.
  </Step>
</Steps>

## Authentication

<ParamField type="string">
  Your Stealth API token from the [Stealth API dashboard](https://www.stealthgpt.ai/api-dashboard).
</ParamField>

## Create a run

`POST https://www.stealthgpt.ai/api/stealthify/agent/runs`

### Headers

<ParamField type="string">
  Your Stealth API token.
</ParamField>

<ParamField type="string">
  Must be `application/json`.
</ParamField>

<ParamField type="string">
  Optional key, 1-255 characters. Reuse the same key when retrying the same create request to avoid enqueueing duplicate runs.
</ParamField>

### Request body

The async create body uses the same strict `preset` discriminated union as [`POST /api/stealthify/agent`](/api-reference/endpoints/stealthify-agent), plus optional `webhookUrl` and `webhookSecret`.

<ParamField type="string">
  One of `"academic"`, `"seo"`, or `"social"`.
</ParamField>

<ParamField type="string">
  Topic or instructions for the document (non-empty).
</ParamField>

<ParamField type="string">
  Required only when `preset` is `"social"`. Must be `"linkedin"` or `"medium"`.
</ParamField>

<ParamField type="boolean">
  When `true`, runs a fact-check pass on the draft and applies fixes before humanization.
</ParamField>

<ParamField type="boolean">
  When `true`, may embed generated images in the final markdown where supported.
</ParamField>

<ParamField type="string">
  Optional URL that receives a `POST` callback when the run reaches a terminal status.
</ParamField>

<ParamField type="string">
  Optional signing secret, 16-255 characters. When present, StealthGPT signs webhook callbacks with HMAC-SHA256.
</ParamField>

### Response: 202 Accepted

<ResponseField name="runId" type="string">
  Identifier of the queued Stealth Agent run.
</ResponseField>

<ResponseField name="status" type="string">
  Always `"queued"` for a successful create response.
</ResponseField>

<ResponseField name="statusUrl" type="string">
  Relative polling URL: `/api/stealthify/agent/runs/{runId}`.
</ResponseField>

```json theme={null}
{
  "runId": "run_abc123",
  "status": "queued",
  "statusUrl": "/api/stealthify/agent/runs/run_abc123"
}
```

## Poll run status

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

### Headers

<ParamField type="string">
  Your Stealth API token. The run must belong to this token's account.
</ParamField>

### Path parameters

<ParamField type="string">
  The `runId` returned from `POST /api/stealthify/agent/runs`.
</ParamField>

### Queued response

Returned before the generation row has started.

```json theme={null}
{
  "runId": "run_abc123",
  "status": "queued"
}
```

### Running response

<ResponseField name="runId" type="string">
  Run identifier.
</ResponseField>

<ResponseField name="preset" type="string">
  `academic`, `seo`, or `social`.
</ResponseField>

<ResponseField name="status" type="string">
  `"running"`.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO timestamp for run creation.
</ResponseField>

<ResponseField name="updatedAt" type="string">
  ISO timestamp for the latest run update.
</ResponseField>

<ResponseField name="currentStepId" type="string | null">
  Current pipeline step, or `null` while the run is starting. Possible step ids include `web_research`, `keywords_research`, `competitor_analysis`, `social_research`, `generate_text`, `meta_generation`, `fact_check`, `humanize`, `image_generation`, and `citations`.
</ResponseField>

<ResponseField name="currentOperation" type="string | null">
  Human-readable current operation, or `null` while the run is starting.
</ResponseField>

```json theme={null}
{
  "runId": "run_abc123",
  "preset": "academic",
  "createdAt": "2026-05-27T14:55:00.000Z",
  "updatedAt": "2026-05-27T14:56:22.000Z",
  "currentStepId": "humanize",
  "currentOperation": "Humanizing draft",
  "status": "running"
}
```

### Completed response

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

<ResponseField name="documentId" type="string">
  Identifier of the saved document record for this run.
</ResponseField>

<ResponseField name="result" type="string">
  Final content as markdown.
</ResponseField>

<ResponseField name="outputWords" type="number">
  Word count of `result` used for billing.
</ResponseField>

<ResponseField name="creditsSpent" type="number">
  Stealth API words charged for this request.
</ResponseField>

<ResponseField name="remainingCredits" type="number">
  Prepaid word balance after this charge.
</ResponseField>

<ResponseField name="billingMode" type="string">
  `"prepaid"` when covered from balance, or `"payg"` when metered usage was applied.
</ResponseField>

<ResponseField name="meteredChargedCredits" type="number">
  Words billed to metered usage for this request (0 when fully prepaid).
</ResponseField>

```json theme={null}
{
  "runId": "run_abc123",
  "preset": "academic",
  "createdAt": "2026-05-27T14:55:00.000Z",
  "updatedAt": "2026-05-27T14:59:12.000Z",
  "currentStepId": "citations",
  "currentOperation": "Inserting citations",
  "status": "completed",
  "documentId": "doc_123",
  "result": "# Creatine and resistance training in older adults\n\n...",
  "outputWords": 1420,
  "creditsSpent": 14200,
  "remainingCredits": 485800,
  "billingMode": "prepaid",
  "meteredChargedCredits": 0
}
```

### Failed response

`failed` can mean generation failed or billing could not be completed after generation.

```json theme={null}
{
  "runId": "run_abc123",
  "preset": "academic",
  "createdAt": "2026-05-27T14:55:00.000Z",
  "updatedAt": "2026-05-27T14:58:30.000Z",
  "currentStepId": "generate_text",
  "currentOperation": "Generating draft",
  "status": "failed",
  "error": {
    "code": "generation_failed",
    "message": "Stealth Agent generation failed"
  }
}
```

Possible `error.code` values:

| Code | Meaning |
| - | - |
| `generation_failed` | The generation pipeline failed before a completed document was available. |
| `payg_terms_required` | Credits ran out and pay-as-you-go terms have not been accepted. |
| `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. |
| `cancelled` | The run was cancelled before completion. |

### Cancelled response

```json theme={null}
{
  "runId": "run_abc123",
  "preset": "academic",
  "createdAt": "2026-05-27T14:55:00.000Z",
  "updatedAt": "2026-05-27T14:56:10.000Z",
  "currentStepId": "web_research",
  "currentOperation": "Researching sources",
  "status": "cancelled",
  "error": {
    "code": "cancelled",
    "message": "Stealth Agent generation was cancelled"
  }
}
```

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

<ResponseField name="content-type" type="string">
  `application/json`
</ResponseField>

<ResponseField name="user-agent" type="string">
  `StealthGPT-API-Webhook/1.0`
</ResponseField>

<ResponseField name="x-stealthgpt-event" type="string">
  `stealth_agent.run.completed`, `stealth_agent.run.failed`, or `stealth_agent.run.cancelled`.
</ResponseField>

<ResponseField name="x-stealthgpt-run-id" type="string">
  The run id.
</ResponseField>

<ResponseField name="x-stealthgpt-timestamp" type="string">
  Unix timestamp in seconds. Present on every webhook callback.
</ResponseField>

<ResponseField name="x-stealthgpt-signature" type="string">
  Present when `webhookSecret` was provided. Format: `v1={hex_hmac_sha256}`.
</ResponseField>

### 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/agent/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.

```javascript nodejs theme={null}
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

<CodeGroup>
  ```bash curl theme={null}
  curl --request POST \
    --url 'https://www.stealthgpt.ai/api/stealthify/agent/runs' \
    --header 'Content-Type: application/json' \
    --header 'api-token: YOUR_API_TOKEN' \
    --header 'idempotency-key: article-123' \
    --data '{
      "preset": "academic",
      "prompt": "Outline creatine benefits for older adults in resistance training",
      "enableFactCheck": true,
      "enableImageGeneration": false,
      "webhookUrl": "https://example.com/webhooks/stealth-agent",
      "webhookSecret": "whsec_your_random_signing_secret"
    }'
  ```

  ```python python theme={null}
  import time
  import requests

  headers = {
      "api-token": "YOUR_API_TOKEN",
      "Content-Type": "application/json",
      "idempotency-key": "article-123",
  }

  create_response = requests.post(
      "https://www.stealthgpt.ai/api/stealthify/agent/runs",
      headers=headers,
      json={
          "preset": "academic",
          "prompt": "Outline creatine benefits for older adults in resistance training",
          "enableFactCheck": True,
          "enableImageGeneration": False,
          "webhookUrl": "https://example.com/webhooks/stealth-agent",
          "webhookSecret": "whsec_your_random_signing_secret",
      },
      timeout=30,
  )
  create_response.raise_for_status()

  run = create_response.json()
  status_url = f"https://www.stealthgpt.ai{run['statusUrl']}"

  while True:
      status_response = requests.get(
          status_url,
          headers={"api-token": "YOUR_API_TOKEN"},
          timeout=30,
      )
      status_response.raise_for_status()
      status = status_response.json()

      if status["status"] in ("completed", "failed", "cancelled"):
          print(status)
          break

      time.sleep(10)
  ```

  ```javascript nodejs theme={null}
  const createResponse = await fetch(
    'https://www.stealthgpt.ai/api/stealthify/agent/runs',
    {
      method: 'POST',
      headers: {
        'api-token': process.env.STEALTHGPT_API_TOKEN,
        'Content-Type': 'application/json',
        'idempotency-key': 'article-123',
      },
      body: JSON.stringify({
        preset: 'academic',
        prompt: 'Outline creatine benefits for older adults in resistance training',
        enableFactCheck: true,
        enableImageGeneration: false,
        webhookUrl: 'https://example.com/webhooks/stealth-agent',
        webhookSecret: 'whsec_your_random_signing_secret',
      }),
      signal: AbortSignal.timeout(30_000),
    },
  )

  if (!createResponse.ok) {
    throw new Error(`create failed: ${createResponse.status}`)
  }

  const run = await createResponse.json()

  for (;;) {
    const statusResponse = await fetch(`https://www.stealthgpt.ai${run.statusUrl}`, {
      headers: { 'api-token': process.env.STEALTHGPT_API_TOKEN },
      signal: AbortSignal.timeout(30_000),
    })

    if (!statusResponse.ok) {
      throw new Error(`poll failed: ${statusResponse.status}`)
    }

    const status = await statusResponse.json()

    if (['completed', 'failed', 'cancelled'].includes(status.status)) {
      console.log(status)
      break
    }

    await new Promise((resolve) => setTimeout(resolve, 10_000))
  }
  ```
</CodeGroup>

## Errors

| Endpoint | Status | Meaning |
| - | - | - |
| `POST /runs` | **400** | Invalid request body or `idempotency-key`. |
| `POST /runs` | **401** | Missing `api-token` header or token not found. |
| `POST /runs` | **402** | Insufficient credits, pay-as-you-go not available, payment method missing, or billing cap delay. |
| `POST /runs` | **500** | Server error while creating the run. |
| `GET /runs/{runId}` | **400** | Invalid `runId`. |
| `GET /runs/{runId}` | **401** | Missing `api-token` header or token not found. |
| `GET /runs/{runId}` | **404** | Run not found or belongs to another account. |
| `GET /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.
* Billing uses **output words** only: charged words = `ceil(outputWords × 10)` toward your Stealth API balance.


# Writer & Humanizer Async Runs
Source: https://docs.stealthgpt.ai/api-reference/endpoints/stealthify-runs

POST https://www.stealthgpt.ai/api/stealthify/runs
Create and poll asynchronous writer and humanizer runs with optional webhook callbacks

The async Writer & Humanizer API lets you generate new content or 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.

<Warning>
  **`model` is required.** You must explicitly pass `"super"`, `"standard"`, or `"lite"`. Requests that omit `model` return `400 Bad Request`. There is no default, please pick one.
</Warning>

<Info>
  The existing [`POST /api/stealthify`](/api-reference/endpoints/stealthify) endpoint is unchanged and remains supported for current API clients. This async API is an alternative for long-running humanization, not a replacement.
</Info>

<Info>
  Humanization automatically strips invisible AI text watermarks. Claude and Gemini embed a statistical pattern in their word choices, invisible to a reader, but it travels with copy and paste and can survive light editing. The humanizer rewrites at the sentence and structure level rather than swapping synonyms, which is the category of change those marks are not built to survive. Meaning stays intact; Claude, Gemini SynthID, and other invisible text watermarks do not.
</Info>

## Flow

<Steps>
  <Step title="Create a run">
    Send `POST /api/stealthify/runs` with text to humanize (`rephrase: true`) or a prompt to write (`rephrase: false`). You can also upload a PDF/DOCX file as `multipart/form-data`. Optionally include `webhookUrl`, `webhookSecret`, and `idempotency-key`.
  </Step>

  <Step title="Store the run id">
    The API returns `202 Accepted` with `runId`, `status: "queued"`, and `statusUrl`.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Authentication

<ParamField type="string">
  Your Stealth API token from the [Stealth API dashboard](https://www.stealthgpt.ai/api-dashboard).
</ParamField>

## Create a run

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

### Headers

<ParamField type="string">
  Your Stealth API token.
</ParamField>

<ParamField type="string">
  `application/json` to send text, or `multipart/form-data` to upload a file.
</ParamField>

<ParamField type="string">
  Optional key, 1-255 characters. Reuse the same key when retrying the same create request to avoid enqueueing duplicate runs.
</ParamField>

### Request body

<ParamField type="string">
  When `rephrase` is `true` (the default), the existing text to humanize — send only that source text, with no instruction wrappers. When `rephrase` is `false`, the topic or instructions for content generation. Maximum 3,000 words when `rephrase` is `false`.
</ParamField>

<ParamField type="boolean">
  `true` humanizes `text`. `false` writes new content from `text` the same way as `POST /api/stealthify` with `rephrase: false`, then humanizes that draft. Omit it to keep the existing humanize-only behavior.
</ParamField>

<ParamField type="string">
  Style of generated content when `rephrase` is `false`: `Standard`, `HighSchool`, `College`, or `PhD`. Ignored when `rephrase` is `true` and when `writingMode` is `default`.
</ParamField>

<ParamField type="string">
  How content is generated when `rephrase` is `false`. `default` follows the prompt without forcing essay structure. `essay` structures the output as an academic essay and uses `tone`. Ignored when `rephrase` is `true`.
</ParamField>

<ParamField type="string">
  **Required.** `"super"` is the flagship humanizer, billed at **\$0.05 / 100 words**. `"standard"` is the previous-generation full rewrite. Super and Standard structural rewrites also remove Claude and Gemini SynthID text watermarks. `"lite"` is faster and intended for light AI-smell cleanup. Omitting `model` returns `400`. See [Models](/api-reference/models).
</ParamField>

<Warning>
  When `rephrase` is `true`, 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. Instruction-style prompts are for `rephrase: false` only.
</Warning>

<ParamField type="string">
  `"quality"` runs quality checks and repairs. `"fast"` performs a faster single-pass rewrite.
</ParamField>

<ParamField type="string">
  `"text"` returns plain text. `"markdown"` preserves/restores markdown formatting where supported.
</ParamField>

<ParamField type="string">
  Optional URL that receives a `POST` callback when the run reaches a terminal status.
</ParamField>

<ParamField type="string">
  Optional signing secret, 16-255 characters. When present, StealthGPT signs webhook callbacks with HMAC-SHA256.
</ParamField>

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

<ParamField type="file">
  The document to humanize. Supported types: `.pdf`, `.docx`, `.txt`, `.md`. Maximum size: 4MB. Scanned or image-only documents are not supported.
</ParamField>

All JSON fields (`model` required; `rephrase`, `tone`, `writingMode`, `qualityMode`, `outputFormat`, `webhookUrl`, `webhookSecret` optional) can be sent as additional form fields. Send `rephrase` as `true` or `false`. A file upload with `rephrase` omitted, or `rephrase: true`, humanizes the extracted text. `rephrase: false` treats the extracted text as a writer prompt.

```bash curl theme={null}
curl --request POST \
  --url 'https://www.stealthgpt.ai/api/stealthify/runs' \
  --header 'api-token: YOUR_API_TOKEN' \
  --form 'file=@essay.pdf' \
  --form 'qualityMode=quality' \
  --form 'model=super'
```

Billing is identical to text runs: **input words plus output words**. Super is **\$0.05 / 100 words**. `standard` and `lite` are **\$0.20 / 1,000 words**.

### Response: 202 Accepted

<ResponseField name="runId" type="string">
  Identifier of the queued humanization run.
</ResponseField>

<ResponseField name="status" type="string">
  Always `"queued"` for a successful create response.
</ResponseField>

<ResponseField name="statusUrl" type="string">
  Relative polling URL: `/api/stealthify/runs/{runId}`.
</ResponseField>

```json theme={null}
{
  "runId": "stealthify-api-run:abc123",
  "status": "queued",
  "statusUrl": "/api/stealthify/runs/stealthify-api-run:abc123"
}
```

## Poll run status

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

### Headers

<ParamField type="string">
  Your Stealth API token. The run must belong to this token's account.
</ParamField>

### Path parameters

<ParamField type="string">
  The `runId` returned from `POST /api/stealthify/runs`.
</ParamField>

### Queued response

```json theme={null}
{
  "runId": "stealthify-api-run:abc123",
  "status": "queued"
}
```

### Running response

```json theme={null}
{
  "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.

<ResponseField name="result" type="string">
  Humanized output text.
</ResponseField>

<ResponseField name="howLikelyToBeDetected" type="number">
  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.)
</ResponseField>

<ResponseField name="wordsSpent" type="number">
  Words charged for this run.
</ResponseField>

<ResponseField name="creditsSpent" type="number">
  Same as `wordsSpent`. Kept on the async contract; it is not a separate charge.
</ResponseField>

<ResponseField name="remainingCredits" type="number">
  Prepaid word balance after this charge.
</ResponseField>

<ResponseField name="billingMode" type="string">
  `"prepaid"` when covered from balance, or `"payg"` when metered usage was applied.
</ResponseField>

<ResponseField name="meteredChargedCredits" type="number">
  Words added to metered usage for this request (0 when fully prepaid).
</ResponseField>

```json theme={null}
{
  "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

```json theme={null}
{
  "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

<ResponseField name="content-type" type="string">
  `application/json`
</ResponseField>

<ResponseField name="user-agent" type="string">
  `StealthGPT-API-Webhook/1.0`
</ResponseField>

<ResponseField name="x-stealthgpt-event" type="string">
  `stealthify.run.completed`, `stealthify.run.failed`, or `stealthify.run.cancelled`.
</ResponseField>

<ResponseField name="x-stealthgpt-run-id" type="string">
  The run id.
</ResponseField>

<ResponseField name="x-stealthgpt-timestamp" type="string">
  Unix timestamp in seconds. Present on every webhook callback.
</ResponseField>

<ResponseField name="x-stealthgpt-signature" type="string">
  Present when `webhookSecret` was provided. Format: `v1={hex_hmac_sha256}`.
</ResponseField>

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

```javascript nodejs theme={null}
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

<CodeGroup>
  ```bash curl theme={null}
  curl --request POST \
    --url 'https://www.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": "super",
      "outputFormat": "text",
      "webhookUrl": "https://example.com/webhooks/stealthify",
      "webhookSecret": "whsec_your_random_signing_secret"
    }'
  ```

  ```python python theme={null}
  import time
  import requests

  headers = {
      "api-token": "YOUR_API_TOKEN",
      "Content-Type": "application/json",
      "idempotency-key": "humanize-job-123",
  }

  create_response = requests.post(
      "https://www.stealthgpt.ai/api/stealthify/runs",
      headers=headers,
      json={
          "text": "Renewable energy offers several significant advantages in our modern world...",
          "qualityMode": "quality",
          "model": "super",
          "outputFormat": "text",
      },
      timeout=30,
  )
  create_response.raise_for_status()

  run = create_response.json()
  status_url = f"https://www.stealthgpt.ai{run['statusUrl']}"

  while True:
      status_response = requests.get(
          status_url,
          headers={"api-token": "YOUR_API_TOKEN"},
          timeout=30,
      )
      status_response.raise_for_status()
      status = status_response.json()

      if status["status"] in ("completed", "failed", "cancelled"):
          print(status)
          break

      time.sleep(10)
  ```

  ```javascript nodejs theme={null}
  const createResponse = await fetch('https://www.stealthgpt.ai/api/stealthify/runs', {
    method: 'POST',
    headers: {
      'api-token': process.env.STEALTHGPT_API_TOKEN,
      'Content-Type': 'application/json',
      'idempotency-key': 'humanize-job-123',
    },
    body: JSON.stringify({
      text: 'Renewable energy offers several significant advantages in our modern world...',
      qualityMode: 'quality',
      model: 'super',
      outputFormat: 'text',
    }),
    signal: AbortSignal.timeout(30_000),
  })

  if (!createResponse.ok) {
    throw new Error(`create failed: ${createResponse.status}`)
  }

  const run = await createResponse.json()

  for (;;) {
    const statusResponse = await fetch(`https://www.stealthgpt.ai${run.statusUrl}`, {
      headers: { 'api-token': process.env.STEALTHGPT_API_TOKEN },
      signal: AbortSignal.timeout(30_000),
    })

    if (!statusResponse.ok) {
      throw new Error(`poll failed: ${statusResponse.status}`)
    }

    const status = await statusResponse.json()

    if (['completed', 'failed', 'cancelled'].includes(status.status)) {
      console.log(status)
      break
    }

    await new Promise((resolve) => setTimeout(resolve, 10_000))
  }
  ```
</CodeGroup>

## Errors

| Endpoint | Status | Meaning |
| - | - | - |
| `POST /api/stealthify/runs` | **400** | Invalid request body, `idempotency-key`, or uploaded file (unsupported type, over 4MB, empty, or no readable text). |
| `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.
* 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`](/api-reference/endpoints/stealthify) or [`POST /api/stealthify/agent`](/api-reference/endpoints/stealthify-agent), depending on the workflow.


# Error Handling
Source: https://docs.stealthgpt.ai/api-reference/error-handling

Learn how to handle and resolve common errors you might encounter when using the StealthGPT API

## HTTP Status Codes

The StealthGPT API uses standard HTTP status codes to indicate the success or failure of requests:

<ResponseField>
  <ResponseField name="200 OK" type="success">
    The request was successful and the response contains the expected data.
  </ResponseField>

  <ResponseField name="400 Bad Request" type="error">
    The request was malformed or contained invalid parameters.
  </ResponseField>

  <ResponseField name="401 Unauthorized" type="error">
    Authentication failed, usually due to an invalid or missing API token.
  </ResponseField>

  <ResponseField name="402 Payment required" type="error">
    Your request cannot be billed. This can happen when you run out of prepaid words and either (a) you haven't accepted pay-as-you-go terms (legacy accounts), (b) you don't have a saved payment method, (c) your account is past due, or (d) billing is temporarily delayed.
  </ResponseField>

  <ResponseField name="403 Forbidden" type="error">
    The requested operation could not be completed (e.g., result not available).
  </ResponseField>

  <ResponseField name="429 Too Many Requests" type="error">
    You've exceeded the rate limits for the API.
  </ResponseField>

  <ResponseField name="500 Internal Server Error" type="error">
    An error occurred on the server. These are typically temporary.
  </ResponseField>
</ResponseField>

## Error Response Format

All error responses follow this consistent format:

```json theme={null}
{
  "message": "Human-readable error message"
}
```

Some error responses may include additional information:

```json theme={null}
{
  "message": "Invalid request",
  "info": [
    {
      "code": "invalid_type",
      "expected": "boolean",
      "received": "string",
      "path": ["rephrase"],
      "message": "Expected boolean, received string"
    }
  ]
}
```

## Common Errors and Solutions

### Authentication Errors

<AccordionGroup>
  <Accordion title="Invalid API Token">
    **Error:** 401 Unauthorized

    **Response:**

    ```json theme={null}
    {
      "message": "Unauthorized"
    }
    ```

    **Solution:** Verify that you're including the correct API token in the `api-token` header. Check your StealthGPT dashboard under the "API Key" tab for the correct token.

    ```bash theme={null}
    # Incorrect
    --header 'api-token: invalid_token'

    # Correct
    --header 'api-token: your_valid_token_here'
    ```
  </Accordion>

  <Accordion title="Missing API Token">
    **Error:** 401 Unauthorized

    **Response:**

    ```json theme={null}
    {
      "message": "API token is missing. You can find it here https://www.stealthgpt.ai/api-dashboard"
    }
    ```

    **Solution:** Ensure you're including the `api-token` header in all requests.

    ```bash theme={null}
    # Missing header
    curl --location 'https://www.stealthgpt.ai/api/stealthify' \
        --header 'Content-Type: application/json' \
        --data '{ "prompt": "test", "rephrase": false }'

    # Correct
    curl --location 'https://www.stealthgpt.ai/api/stealthify' \
        --header 'api-token: YOUR_API_TOKEN' \
        --header 'Content-Type: application/json' \
        --data '{ "prompt": "test", "rephrase": false }'
    ```
  </Accordion>
</AccordionGroup>

### Request Errors

<AccordionGroup>
  <Accordion title="Missing Required Parameters">
    **Error:** 400 Bad Request

    **Response:**

    ```json theme={null}
    {
      "message": "Invalid request",
      "info": [
        {
          "code": "invalid_type",
          "expected": "boolean",
          "received": "undefined",
          "path": ["rephrase"],
          "message": "Required"
        }
      ]
    }
    ```

    **Solution:** Ensure all required parameters are included in your request. For the `/api/stealthify` endpoint, both `prompt` and `rephrase` are required.

    ```bash theme={null}
    # Missing rephrase parameter
    --data '{ "prompt": "test" }'

    # Correct
    --data '{ "prompt": "test", "rephrase": false }'
    ```
  </Accordion>

  <Accordion title="Invalid Parameter Values">
    **Error:** 400 Bad Request

    **Response:**

    ```json theme={null}
    {
      "message": "Invalid request",
      "info": [
        {
          "code": "invalid_type",
          "expected": "boolean",
          "received": "string",
          "path": ["rephrase"],
          "message": "Expected boolean, received string"
        }
      ]
    }
    ```

    **Solution:** Check that parameter values are in the correct format.

    ```bash theme={null}
    # Invalid boolean value (should be true/false, not "true"/"false")
    --data '{ "prompt": "test", "rephrase": "false" }'

    # Correct
    --data '{ "prompt": "test", "rephrase": false }'
    ```
  </Accordion>

  <Accordion title="Empty Prompt">
    **Error:** 400 Bad Request

    **Response:**

    ```json theme={null}
    {
      "message": "Invalid request",
      "info": [
        {
          "code": "too_small",
          "minimum": 1,
          "type": "string",
          "inclusive": true,
          "exact": false,
          "path": ["prompt"],
          "message": "String must contain at least 1 character(s)"
        }
      ]
    }
    ```

    **Solution:** Ensure the prompt parameter contains non-empty content.

    ```bash theme={null}
    # Empty prompt
    --data '{ "prompt": "", "rephrase": false }'

    # Correct
    --data '{ "prompt": "Write about renewable energy", "rephrase": false }'
    ```
  </Accordion>

  <Accordion title="Word Limit Exceeded">
    **Error:** 400 Bad Request

    **Response:**

    ```json theme={null}
    {
      "message": "The text exceeds the 3,000 word limit"
    }
    ```

    **Solution:** Keep your prompt text under 3,000 words.
  </Accordion>

  <Accordion title="Not Enough Credits">
    **Error:** 402 Payment Required

    **Response:**

    ```json theme={null}
    {
      "message": "Payment required or payment method not set up"
    }
    ```

    **Solution:**

    * If you are **out of prepaid words**, you can:
      * Add prepaid words, or
      * Set up pay-as-you-go billing (saved payment method) and accept the updated pay-as-you-go terms (legacy accounts)
  </Accordion>

  <Accordion title="Result Not Available">
    **Error:** 403 Forbidden

    **Response:**

    ```json theme={null}
    {
      "message": "Result is not available"
    }
    ```

    **Solution:** This typically occurs with the articles endpoint when there was an issue generating the article. Try again with a different prompt.
  </Accordion>
</AccordionGroup>

### Rate Limit Errors

<AccordionGroup>
  <Accordion title="Too Many Requests">
    **Error:** 429 Too Many Requests

    **Solution:** Implement request throttling in your application and avoid making too many requests in a short period.

    ```python theme={null}
    # Python example with retry logic
    import requests
    import time

    def call_api_with_retry(url, headers, data, max_retries=3, retry_delay=5):
        for attempt in range(max_retries):
            response = requests.post(url, headers=headers, json=data)
            
            if response.status_code == 429:
                # Wait before retrying
                time.sleep(retry_delay)
                continue
                
            return response
            
        return response  # Return last response if all retries failed
    ```
  </Accordion>
</AccordionGroup>

### Network and Server Errors

<AccordionGroup>
  <Accordion title="Network Timeout">
    **Error:** 504 Gateway Timeout

    **Solution:** Implement timeout handling and retry logic for network issues.

    ```python theme={null}
    # Python example with timeout handling
    import requests
    from requests.exceptions import Timeout, ConnectionError

    def call_api_with_timeout(prompt, rephrase, timeout=10):
        try:
            response = requests.post(
                'https://www.stealthgpt.ai/api/stealthify',
                headers={
                    'api-token': 'YOUR_API_TOKEN',
                    'Content-Type': 'application/json'
                },
                json={
                    'prompt': prompt,
                    'rephrase': rephrase
                },
                timeout=timeout
            )
            response.raise_for_status()
            return response.json()
        except Timeout:
            print("Request timed out. The server might be experiencing high load.")
            raise
        except ConnectionError:
            print("Network connection error. Please check your internet connection.")
            raise
    ```
  </Accordion>

  <Accordion title="Server Error">
    **Error:** 500 Internal Server Error

    **Solution:** Implement exponential backoff retry logic for server-side errors.

    ```go theme={null}
    // Go example with exponential backoff
    package main

    import (
        "bytes"
        "encoding/json"
        "fmt"
        "net/http"
        "time"
    )

    func callAPIWithBackoff(prompt string, rephrase bool) (*http.Response, error) {
        maxRetries := 3
        baseDelay := time.Second

        requestBody, _ := json.Marshal(map[string]interface{}{
            "prompt":   prompt,
            "rephrase": rephrase,
        })

        for i := 0; i < maxRetries; i++ {
            req, _ := http.NewRequest("POST", "https://www.stealthgpt.ai/api/stealthify", 
                bytes.NewBuffer(requestBody))
            
            req.Header.Set("api-token", "YOUR_API_TOKEN")
            req.Header.Set("Content-Type", "application/json")

            resp, err := http.DefaultClient.Do(req)
            if err != nil {
                return nil, err
            }

            if resp.StatusCode != 500 {
                return resp, nil
            }

            // Exponential backoff
            delay := baseDelay * time.Duration(1<<uint(i))
            time.Sleep(delay)
        }

        return nil, fmt.Errorf("max retries exceeded")
    }
    ```
  </Accordion>
</AccordionGroup>

### Language-Specific Error Handling Examples

Here are comprehensive error handling examples in different programming languages:

<CodeGroup>
  ```python Python theme={null}
  import requests
  from requests.exceptions import RequestException
  import time

  class StealthGPTError(Exception):
      """Custom exception for StealthGPT API errors"""
      pass

  def call_stealthgpt_api(prompt, rephrase, max_retries=3):
      headers = {
          'api-token': 'YOUR_API_TOKEN',
          'Content-Type': 'application/json'
      }
      data = {
          'prompt': prompt,
          'rephrase': rephrase
      }

      for attempt in range(max_retries):
          try:
              response = requests.post(
                  'https://www.stealthgpt.ai/api/stealthify',
                  headers=headers,
                  json=data,
                  timeout=10
              )
              
              if response.status_code == 200:
                  return response.json()
              
              error_data = response.json()
              error_message = error_data.get('message', 'Unknown error')
                  
              if response.status_code == 429:
                  retry_after = int(response.headers.get('Retry-After', 5))
                  time.sleep(retry_after)
                  continue
                  
              if response.status_code == 400:
                  raise StealthGPTError(f"Invalid request: {error_message}")
                  
              if response.status_code == 401:
                  raise StealthGPTError("Unauthorized: Invalid API token")
              
              if response.status_code == 402:
                  raise StealthGPTError(f"Payment required: {error_message}")
                  
              response.raise_for_status()
              
          except requests.exceptions.Timeout:
              if attempt == max_retries - 1:
                  raise StealthGPTError("Request timed out after multiple attempts")
              time.sleep(2 ** attempt)  # Exponential backoff
              
          except requests.exceptions.RequestException as e:
              raise StealthGPTError(f"Request failed: {str(e)}")
              
      raise StealthGPTError("Max retries exceeded")
  ```

  ```javascript JavaScript theme={null}
  class StealthGPTClient {
    constructor(apiToken) {
      this.apiToken = apiToken;
      this.baseURL = 'https://www.stealthgpt.ai/api';
      this.maxRetries = 3;
    }

    async stealthify(prompt, rephrase) {
      let lastError;
      
      for (let attempt = 0; attempt < this.maxRetries; attempt++) {
        try {
          const response = await fetch(`${this.baseURL}/stealthify`, {
            method: 'POST',
            headers: {
              'api-token': this.apiToken,
              'Content-Type': 'application/json',
            },
            body: JSON.stringify({ prompt, rephrase }),
          });

          if (!response.ok) {
            const errorData = await response.json();
            const errorMessage = errorData.message || 'Unknown error';
            
            switch (response.status) {
              case 400:
                throw new Error(`Invalid request: ${errorMessage}`);
              case 401:
                throw new Error('Unauthorized: Invalid API token');
              case 402:
                throw new Error(`Payment required: ${errorMessage}`);
              case 403:
                throw new Error(`Forbidden: ${errorMessage}`);
              case 429:
                const retryAfter = parseInt(response.headers.get('Retry-After') || '5');
                await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
                continue;
              default:
                throw new Error(`API error: ${errorMessage}`);
            }
          }

          return await response.json();
          
        } catch (error) {
          lastError = error;
          
          if (error.message.includes('Invalid') || 
              error.message.includes('Unauthorized') || 
              error.message.includes('Payment required')) {
            throw error; // Don't retry client errors
          }
          
          // Exponential backoff for other errors
          await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000));
        }
      }

      throw lastError || new Error('Max retries exceeded');
    }
  }
  ```
</CodeGroup>

## Best Practices for Error Handling

1. **Implement Retry Logic**: For transient errors (like 429 or 500), implement retry logic with exponential backoff.

2. **Validate Inputs**: Validate all parameters before sending requests to avoid 400 errors.

3. **Check Response Status**: Always check the HTTP status code before trying to process the response.

4. **Error Logging**: Log detailed error information for troubleshooting.

5. **Handle Errors Gracefully**: Provide user-friendly error messages in your application rather than exposing raw API errors.

```javascript theme={null}
// Node.js example of comprehensive error handling
async function callStealthGPT(prompt, rephrase) {
  try {
    const response = await axios.post('https://www.stealthgpt.ai/api/stealthify', {
      prompt,
      rephrase
    }, {
      headers: {
        'api-token': process.env.API_TOKEN,
        'Content-Type': 'application/json'
      }
    });
    
    return response.data;
  } catch (error) {
    // Handle different error types
    if (error.response) {
      // The request was made and server responded with an error code
      const errorMessage = error.response.data.message || 'Unknown error';
      
      switch (error.response.status) {
        case 400:
          console.error('Invalid request parameters:', error.response.data);
          throw new Error(`Invalid request: ${errorMessage}`);
        case 401:
          console.error('Authentication failed');
          throw new Error('API authentication failed. Please check your API token.');
        case 402:
          console.error('Payment required');
          throw new Error(`Payment required: ${errorMessage}`);
        case 403:
          console.error('Forbidden');
          throw new Error(`Operation not allowed: ${errorMessage}`);
        case 429:
          console.error('Rate limit exceeded');
          throw new Error('Too many requests. Please try again later.');
        default:
          console.error(`Error ${error.response.status}:`, error.response.data);
          throw new Error('An error occurred while processing your request.');
      }
    } else if (error.request) {
      // The request was made but no response received
      console.error('No response received:', error.request);
      throw new Error('No response from server. Please check your connection.');
    } else {
      // Something else caused the error
      console.error('Error setting up request:', error.message);
      throw new Error('Failed to send request.');
    }
  }
} 
```


# Use Stealth Agent from MCP clients
Source: https://docs.stealthgpt.ai/api-reference/integrations/mcp

Call StealthGPT as a tool from Cursor, Claude, ChatGPT and other MCP-aware agents

StealthGPT ships a remote **MCP (Model Context Protocol) server**, so AI agents and MCP-aware clients can generate and humanize content as a tool — without you writing any integration code. This is the **agent / tool invocation** workflow pattern: the model decides when to call the tools and you stay inside your editor or chat.

<Info>
  One server, many clients. The same MCP server works with Cursor, Claude, ChatGPT, and any MCP-compatible runtime. You don't install a per-client plugin.
</Info>

## Server endpoint

```
https://www.stealthgpt.ai/api/mcp/mcp
```

Transport: **Streamable HTTP** (the modern MCP transport). A legacy SSE endpoint is also available at `/api/mcp/sse`.

## Authentication

The server supports two ways to authenticate, and both resolve to the same StealthGPT account (identical billing):

* **OAuth (one-click)** — used by **claude.ai (web)** and other clients with built-in custom-connector support. You sign in with your StealthGPT account and approve access; there's no token to copy. See [Connect in claude.ai (web)](#connect-in-claudeai-web).
* **API token (bearer header)** — used by IDE/desktop clients like **Cursor**, **VS Code**, **Claude Desktop**, and CLIs:

  ```
  Authorization: Bearer YOUR_API_TOKEN
  ```

  Get your token from the [Stealth API dashboard](https://www.stealthgpt.ai/api-dashboard).

## Tools

| Tool | Purpose | Key arguments |
| - | - | - |
| `generate_content` | Start a full Stealth Agent run (research → draft → optional fact-check → humanize → optional images). | `preset` (`academic` \| `seo` \| `social`), `prompt`, `platform` (for `social`), `enableFactCheck`, `enableImageGeneration` |
| `humanize_text` | Start a humanization run for existing text. | `text`, `qualityMode` (`fast` \| `quality`), `model` (`super` \| `standard` \| `lite`; `super` is the strongest), `outputFormat` (`text` \| `markdown`, defaults to `markdown`) |
| `get_run_status` | Get the current status and final result of a run. | `runId` |
| `enable_pay_as_you_go` | StealthAPI accounts: get a link where you add a card to turn on pay-as-you-go billing. See [Turn on pay-as-you-go from the agent](#turn-on-pay-as-you-go-from-the-agent). | none |

`generate_content` and `humanize_text` return a `runId` immediately (the work runs asynchronously). The agent then calls `get_run_status` with that `runId` until the status is `completed`, `failed`, or `cancelled`.

<Note>
  On a completed humanization, `howLikelyToBeDetected` is a 0–100 **human-likeness** score where **higher is better** (more human, less likely to be flagged as AI).
</Note>

<Note>
  `humanize_text` defaults to `outputFormat: "markdown"`, unlike the REST endpoints, which default to `"text"`. Pass `"text"` explicitly if you want unformatted prose.
</Note>

## Install

One-click for Cursor:

[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=stealthgpt\&config=eyJ1cmwiOiJodHRwczovL3N0ZWFsdGhncHQuYWkvYXBpL21jcC9tY3AifQ==)

<Note>
  The one-click button adds the server URL; add your `Authorization: Bearer YOUR_API_TOKEN` header in the generated `mcp.json`. (Cursor connects with a bearer token. For a no-token, one-click sign-in use **claude.ai (web)** with OAuth — see [below](#connect-in-claudeai-web).)
</Note>

Or configure manually for your client:

<Tabs>
  <Tab title="Cursor">
    Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global), then reload MCP servers:

    ```json theme={null}
    {
      "mcpServers": {
        "stealthgpt": {
          "url": "https://www.stealthgpt.ai/api/mcp/mcp",
          "headers": { "Authorization": "Bearer YOUR_API_TOKEN" }
        }
      }
    }
    ```
  </Tab>

  <Tab title="VS Code">
    Add to `.vscode/mcp.json`:

    ```json theme={null}
    {
      "servers": {
        "stealthgpt": {
          "type": "http",
          "url": "https://www.stealthgpt.ai/api/mcp/mcp",
          "headers": { "Authorization": "Bearer YOUR_API_TOKEN" }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Windsurf">
    Add to your Windsurf MCP config (`~/.codeium/windsurf/mcp_config.json`):

    ```json theme={null}
    {
      "mcpServers": {
        "stealthgpt": {
          "serverUrl": "https://www.stealthgpt.ai/api/mcp/mcp",
          "headers": { "Authorization": "Bearer YOUR_API_TOKEN" }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Desktop">
    Add it as a custom connector (Settings → Connectors → Add custom connector) using the URL `https://www.stealthgpt.ai/api/mcp/mcp` and sign in with OAuth — same flow as [claude.ai (web)](#connect-in-claudeai-web).

    Alternatively, bridge over stdio with a bearer token using `mcp-remote`:

    ```json theme={null}
    {
      "mcpServers": {
        "stealthgpt": {
          "command": "npx",
          "args": [
            "mcp-remote",
            "https://www.stealthgpt.ai/api/mcp/mcp",
            "--header",
            "Authorization: Bearer YOUR_API_TOKEN"
          ]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Other clients">
    Any client that supports a remote (Streamable HTTP) MCP server with custom headers:

    * **URL:** `https://www.stealthgpt.ai/api/mcp/mcp`
    * **Header:** `Authorization: Bearer YOUR_API_TOKEN`
  </Tab>
</Tabs>

Once connected, the tools appear in the client and the agent calls them when relevant — for example:

> Humanize this paragraph: …

or

> Generate an SEO article about home solar energy.

## Example flow

1. The agent calls `humanize_text` with your text → receives `{ "runId": "…", "status": "queued" }`.
2. The agent polls `get_run_status` with that `runId`.
3. When `status` is `completed`, it returns the humanized `result`, `howLikelyToBeDetected`, and billing fields (`wordsSpent`, `creditsSpent`, `remainingCredits`, `billingMode`, `meteredChargedCredits`).

## Billing

How MCP runs are billed depends on your account:

* **StealthGPT subscription** — runs come out of your plan, the same as on the website. `humanize_text` uses your plan's words, and `generate_content` uses one Stealth Agent article from your monthly allowance. Completed runs report `billingMode: "subscription"`. Connect with OAuth by signing in with your StealthGPT account.
* **StealthAPI account** — runs are billed in API credits, prepaid or pay-as-you-go, like the REST API.

If you have both an active subscription and a StealthAPI account, MCP runs use your API credits by default. You can switch them to your subscription under **MCP billing** in your [usage settings](https://www.stealthgpt.ai/account/usage). This setting only applies to MCP runs; REST API calls always use API credits.

If your plan has no words or articles left, the run is refused with a message that links to your plan.

## Turn on pay-as-you-go from the agent

This applies to StealthAPI accounts. If a run fails with `Payment required`, the agent can call `enable_pay_as_you_go`. It returns a `setupUrl` for a Stripe page where you add a card. Pay-as-you-go turns on when you finish, and the agent can retry the run. The agent can't complete this step for you, and the link expires after 24 hours.

If pay-as-you-go is already on, the tool returns `status: "active"`. If your last invoice is unpaid or you haven't accepted the pay-as-you-go terms, it returns a link to your usage settings instead. Accounts billed through a subscription get `status: "subscription_billing"`.

## Connect in claude.ai (web)

The MCP server is available as a **custom connector** inside claude.ai — connect once with one-click OAuth (no API token to paste):

<Steps>
  <Step title="Open connector settings">
    In claude.ai, go to **Settings → Connectors → Add custom connector**.
  </Step>

  <Step title="Add the server">
    Set a name (e.g. `StealthGPT`) and the URL:

    ```
    https://www.stealthgpt.ai/api/mcp/mcp
    ```
  </Step>

  <Step title="Sign in and approve">
    Click **Connect**, sign in with your StealthGPT account, and approve access on the consent screen. The connector switches to **Connected**.
  </Step>

  <Step title="Use the tools">
    Ask Claude to generate or humanize content, e.g. *"Humanize this paragraph…"* or *"Generate an SEO article about home solar energy."* Claude calls the tools and polls the run for you.
  </Step>
</Steps>

<Note>
  OAuth and the bearer token resolve to the same StealthGPT account, so runs are billed identically regardless of how you connect.
</Note>

### ChatGPT

A ChatGPT connector / app uses the same MCP server and OAuth. It's in progress and subject to ChatGPT's connector requirements (workspace tier and tool conventions) — this page will be updated when it's available.

## Notes & limits

* Runs are billed to the signed-in account, as described in [Billing](#billing).
* Generation can take from seconds (humanize-only, `lite`) to a few minutes (full `academic`/`seo` pipeline). Because it's async, the tool call returns quickly and the agent polls.
* See the [async workflow](/api-reference/endpoints/stealthify-runs) and [Stealth Agent async runs](/api-reference/endpoints/stealthify-agent-runs) pages for the underlying REST contract.


# Automate StealthGPT with n8n
Source: https://docs.stealthgpt.ai/api-reference/integrations/n8n

Generate long-form content and humanize text inside n8n workflows with the StealthGPT community node

StealthGPT ships an official, **n8n-verified** node, [`n8n-nodes-stealthgpt`](https://www.npmjs.com/package/n8n-nodes-stealthgpt) — listed on the [n8n integrations directory](https://n8n.io/integrations/stealthgpt/). You can start full content-pipeline runs and humanize text directly from your n8n workflows. It uses the async API under the hood (start a run, then wait for completion or poll), which fits n8n's long-running execution model.

<Info>
  This is a **verified** node, so it's available on both **self-hosted n8n and n8n Cloud**. An instance owner enables it once (see Install); after that everyone on the instance can use it in their workflows.
</Info>

## Install

<Steps>
  <Step title="Open community nodes (instance owner)">
    In n8n, go to **Settings → Community nodes → Install**.
  </Step>

  <Step title="Install the verified node">
    Enter the package name and install:

    ```
    n8n-nodes-stealthgpt
    ```

    As a verified node it installs cleanly on self-hosted and n8n Cloud.
  </Step>

  <Step title="Find the node">
    Add a new node and search for **StealthGPT** — it appears in the nodes panel for everyone on the instance.
  </Step>
</Steps>

<Note>
  Only an instance owner needs to do this one-time install. See n8n's guide on [using verified community nodes](https://n8n.io/integrations/stealthgpt/).
</Note>

## Credentials

Create a **StealthGPT API** credential:

1. Add the StealthGPT node to a workflow and create a new credential when prompted.
2. Paste your **API token** from the [Stealth API dashboard](https://www.stealthgpt.ai/api-dashboard).
3. Save — n8n validates the token against your account balance.

Your API token lives only in your n8n credential store. It is never embedded in the node package.

## Operations

The node exposes two resources:

| Resource | Operation | What it does |
| - | - | - |
| **Content Generation** | Start Run | Start a full Stealth Agent run (research → draft → optional fact-check → humanize → optional images). Inputs: `preset` (`academic` \| `seo` \| `social`), `prompt`, `platform` (for `social`), `enableFactCheck`, `enableImageGeneration`. |
| **Content Generation** | Get Run Status | Retrieve the status and result of a content generation run by `runId`. |
| **Text Humanization** | Start Run | Turn existing text into natural, human, publish-ready content. Inputs: `text`, `qualityMode` (`fast` \| `quality`), `model` (`super` \| `standard` \| `lite`), `outputFormat` (`text` \| `markdown`). |
| **Text Humanization** | Get Run Status | Retrieve the status and result of a humanization run by `runId`. |

### Wait for completion

Both **Start Run** operations include a **Wait for completion** toggle:

* **On** (default): the node starts the run and polls until it reaches a terminal state (`completed`, `failed`, or `cancelled`), then outputs the final result. Tune the poll interval and max wait time in the node options for long pipeline runs.
* **Off**: the node returns the `runId` and `statusUrl` immediately, so you can continue the workflow and check the run later with **Get Run Status** (useful with n8n's **Wait** node or a scheduled poll).

<Note>
  On a completed humanization, `howLikelyToBeDetected` is a 0–100 **human-likeness** score where **higher is better** (more human, less likely to be flagged as AI).
</Note>

## Example workflows

* **RSS → SEO article → CMS draft:** RSS Trigger → StealthGPT (Content Generation, `seo`) → your CMS/WordPress node to create a draft.
* **Webhook → Humanize → Docs/Slack:** Webhook → StealthGPT (Text Humanization) → Google Docs / Slack.
* **Airtable brief → generate → store:** Airtable Trigger → StealthGPT (Content Generation) → write the result back to Airtable.

## Notes & limits

* Runs are billed to the account that owns the API token, using standard word-based billing — identical to the REST API and MCP server.
* Full `academic`/`seo` pipeline runs can take a few minutes; humanize-only runs are faster. Because the API is async, prefer **Wait for completion** (or start + poll) over blocking the whole workflow on one request.
* For the underlying REST contract, see the [async humanization runs](/api-reference/endpoints/stealthify-runs) and [Stealth Agent async runs](/api-reference/endpoints/stealthify-agent-runs) pages.


# StealthGPT for WordPress
Source: https://docs.stealthgpt.ai/api-reference/integrations/wordpress

Generate and humanize content into WordPress drafts with the official StealthGPT plugin

The official **[StealthGPT WordPress plugin](https://wordpress.org/plugins/stealthgpt/)** lets editors generate long-form content or humanize existing text directly inside WordPress, with the result written to a **draft post** for review before publishing. You bring your own StealthGPT API key, and runs complete reliably via webhook (with background polling as a fallback), so long generations never block the editor.

<Info>
  Available now on the [WordPress.org plugin directory](https://wordpress.org/plugins/stealthgpt/).
</Info>

## Install

<Steps>
  <Step title="Add the plugin">
    In WordPress admin, go to **Plugins → Add New**, search for **StealthGPT**, and click **Install Now** (or download it from the [WordPress.org page](https://wordpress.org/plugins/stealthgpt/)).
  </Step>

  <Step title="Activate">
    Click **Activate** once installed.
  </Step>

  <Step title="Add your API key">
    Open the StealthGPT plugin settings and paste your **API token** from the [Stealth API dashboard](https://www.stealthgpt.ai/api-dashboard). The key is stored on your site and used for all runs.
  </Step>
</Steps>

## Usage

* **Generate content** — from a topic/brief, choose a preset (`academic` / `seo` / `social`) and start a run; the finished, humanized markdown is inserted into a new **draft** post.
* **Humanize** — turn existing post content or pasted text into natural, human, publish-ready output, also saved to a draft.
* Everything runs asynchronously: you can keep working while the run completes, then review and publish the draft.

## Notes & limits

* **Bring your own API key** — runs are billed to the account that owns the token, using standard word-based billing (identical to the REST API, MCP, and n8n).
* Output is always written to a **draft** (never auto-published), so an editor reviews before publishing.
* Full `academic` / `seo` pipeline runs can take a few minutes; humanize-only runs are faster.
* For the underlying contract, see the [async humanization runs](/api-reference/endpoints/stealthify-runs) and [Stealth Agent async runs](/api-reference/endpoints/stealthify-agent-runs) pages.


# Automate StealthGPT with Zapier
Source: https://docs.stealthgpt.ai/api-reference/integrations/zapier

Connect StealthGPT to 8,000+ apps with the Zapier integration

The StealthGPT Zapier integration lets you generate long-form content and humanize text from your Zaps, then push the result into 8,000+ connected apps — no code required. It's built on the async API, so long-running generations complete reliably via callbacks.

## Connect StealthGPT

<Steps>
  <Step title="Go to App Connections">
    In Zapier, open the left menu and click **App Connections**.
  </Step>

  <Step title="Create a connection">
    Click **+ Create connection** in the top right.
  </Step>

  <Step title="Find StealthGPT">
    Start typing **StealthGPT**, select it from the list, then click **Add connection**.
  </Step>

  <Step title="Paste your API token">
    Grab your token from your [Stealth API dashboard](https://www.stealthgpt.ai/api-dashboard), paste it in, and click **Connect**.
  </Step>
</Steps>

<Note>
  Your API token is validated against your account balance when you connect. Runs are billed to the account that owns the token, using the same word-based billing as the REST API and MCP server.
</Note>

## What you can do

| Action | What it does |
| - | - |
| **Generate Long-Form Content** | Start a full Stealth Agent run (`academic` / `seo` / `social`) and get publish-ready markdown. |
| **Humanize Text** | Turn existing text into natural, human, publish-ready content. |
| **Get Run Status / Fetch Result** | Retrieve the status and result of a run by `runId`. |

Zap templates:

* Airtable row → Generate SEO article → WordPress draft
* RSS item → Generate SEO article → Google Docs
* Webhook → Humanize Text → Slack / Docs

## Other ways to automate

You can also automate StealthGPT via:

* [n8n](/api-reference/integrations/n8n) — verified community node
* [MCP clients](/api-reference/integrations/mcp) — Cursor, Claude, and more
* The [async REST API](/api-reference/endpoints/stealthify-agent-runs) directly


# Introduction
Source: https://docs.stealthgpt.ai/api-reference/introduction

Welcome to the StealthGPT API documentation

# StealthGPT API

Welcome to the StealthGPT API documentation. Our powerful language model helps you generate and rephrase content in a stealthy manner, utilizing advanced natural language processing to create unique, high-quality content that remains undetectable.

## Latest Feature

<Card title="Introducing StealthGPT Super" icon="crown">
  Generate completely undetectable AI text with StealthGPT's newest model: [Super](/api-reference/models#super). Our benchmark tests rate it as able to bypass Pangram in nearly every instance.
</Card>

## Key Features

<CardGroup>
  <Card title="Stealthy Content Generation" icon="wand-magic-sparkles">
    Generate high-quality, unique content based on your prompts, ensuring discretion and undetectability.
  </Card>

  <Card title="Advanced Rephrasing" icon="shuffle">
    Transform existing content without compromising meaning or context, evading AI detectors and plagiarism checkers. Humanization also strips invisible Claude and Gemini text watermarks automatically.
  </Card>

  <Card title="Easy Integration" icon="puzzle-piece">
    Seamlessly integrate into your applications regardless of programming language.
  </Card>

  <Card title="Scalable and Flexible" icon="arrows-up-down-left-right">
    Support various operational scales, from small projects to large-scale content generation.
  </Card>

  <Card title="Multi-Language Support" icon="globe">
    Automatic language detection for any language in the world—no additional configuration required.
  </Card>

  <Card title="AI Detector" icon="shield-halved">
    Score arbitrary text for AI-generated content using the same detector that powers stealthgpt.ai.
  </Card>
</CardGroup>

## Getting Started

The quickest way to start using the StealthGPT API is to follow our [Quick Start Guide](/api-reference/quickstart).

For more detailed information, explore:

* [Authentication](/api-reference/authentication)
* [Models](/api-reference/models)
* [Writer & Humanizer](/api-reference/endpoints/stealthify)
* [AI Detector](/api-reference/endpoints/detect)
* [Stealth Agent overview](/api-reference/stealth-agent/overview) — long-form research, drafting, and humanization
* [Stealth Agent guide](/api-reference/stealth-agent/guide) and [use cases](/api-reference/stealth-agent/use-cases)
* [Stealth Agent endpoint reference](/api-reference/endpoints/stealthify-agent)
* [Code Examples](/api-reference/code-examples)
* [Pricing](/api-reference/pricing)

## Need Help?

If you encounter any issues or have questions, check out our [Error Handling](/api-reference/error-handling) guide or contact our support team at [support@stealthgpt.ai](mailto:support@stealthgpt.ai).


# Models
Source: https://docs.stealthgpt.ai/api-reference/models

Choose a Writer & Humanizer model

Super is StealthGPT's newest flagship and most capable Writer & Humanizer model. Standard balances capability and cost, while Lite prioritizes speed and light touchups.

| Model | Use | Price |
| - | - | - |
| <span />`super` | Highest detector bypass. Its structural rewrite also removes Claude and Gemini SynthID text watermarks. | \$0.05 / 100 words |
| `standard` | General-purpose full rewrite that balances quality and cost. Removes Claude and Gemini SynthID text watermarks. | \$0.20 / 1,000 words |
| `lite` | Fast, light cleanup for drafts. Not designed for detector bypass or watermark removal. | \$0.20 / 1,000 words |

These rates apply to **input words plus output words** on each Writer & Humanizer request. See [Pricing](/api-reference/pricing) for account billing and rate limits.

## Supported interfaces

All three current model IDs work with:

* [`POST /api/stealthify`](/api-reference/endpoints/stealthify) for synchronous generation or humanization.
* [`POST /api/stealthify/runs`](/api-reference/endpoints/stealthify-runs) for asynchronous generation (`rephrase: false`) or humanization (`rephrase: true`), including PDF, DOCX, TXT, and MD uploads up to 4 MB.
* MCP [`humanize_text`](/api-reference/integrations/mcp) for asynchronous humanization from MCP clients.

## Usage

* For humanization, send only the source text in `prompt` (synchronous) or `text` (asynchronous). Do not add instructions such as "Humanize this."
* `qualityMode: "quality"` is the default. Use `"fast"` for a single-pass rewrite.
* `outputFormat` accepts `"text"` or `"markdown"`. All models accept multilingual source text.

### Synchronous

```bash theme={null}
curl --request POST \
  --url 'https://www.stealthgpt.ai/api/stealthify' \
  --header 'api-token: YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "prompt": "Source text to humanize.",
    "rephrase": true,
    "model": "super"
  }'
```

### Asynchronous

```bash theme={null}
curl --request POST \
  --url 'https://www.stealthgpt.ai/api/stealthify/runs' \
  --header 'api-token: YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "text": "Source text to humanize.",
    "model": "super"
  }'
```


# Pricing
Source: https://docs.stealthgpt.ai/api-reference/pricing

Understand the word-based pricing model for StealthGPT API

# Word-Based Pricing

StealthGPT API uses a free-to-start + pay-as-you-go model.

## Billing Model

* **Starter access**: \$0 to begin after activating API access and adding a payment method
* **Pay-as-you-go rate**: After your included/prepaid words are used, `standard` and `lite` are billed at \$0.20 per 1,000 words. **Super** is billed at \$0.05 per 100 words. On `/api/stealthify`, both rates apply to **input words plus output words**.
* **Tiered billing thresholds**: Your invoice threshold starts lower and can advance automatically as spend increases within a billing period.

## API Billing Tiers

StealthGPT API pay-as-you-go accounts start at Tier 1. Each tier sets an automatic invoice threshold, and your account can move to the next tier after reaching the required spend within the current billing cycle.

* **Tier 1** — Invoice threshold: \$50. Spend to advance: \$200 (to reach Tier 2).
* **Tier 2** — Invoice threshold: \$500. Spend to advance: \$1,000 (to reach Tier 3).
* **Tier 3** — Invoice threshold: \$1,000. Spend to advance: \$2,000 (to reach Tier 4).
* **Tier 4** — Invoice threshold: \$2,000. Spend to advance: \$4,000 (to reach Tier 5).
* **Tier 5** — Invoice threshold: \$10,000. Highest tier (no automatic advancement).

<Note>
  Need custom tier settings, higher invoice thresholds, or tailored billing limits?
  Email [joey@stealthgpt.ai](mailto:joey@stealthgpt.ai) and include your expected
  billing-cycle usage and required limits.
</Note>

## Word Consumption Rates

`/api/stealthify` counts **input words plus output words**. `standard` and `lite` are billed at **\$0.20 / 1,000** of those words. **Super** is billed at **\$0.05 / 100** of those words. `/api/stealthify/detect` charges **input words** per request (one billed word per input word). `/api/stealthify/agent` charges **`ceil(output words × 10)`** Stealth API words per successful request, where output words are counted from the primary markdown result.

<Table>
  <thead>
    <tr>
      <th>Endpoint</th>
      <th>Word Consumption</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>/api/stealthify (`standard`, `lite`)</td>
      <td>Charged words = input words + output words, at \$0.20 / 1,000 words.</td>
    </tr>

    <tr>
      <td>/api/stealthify (`super`)</td>
      <td>Charged words = input words + output words, at \$0.05 / 100 words</td>
    </tr>

    <tr>
      <td>/api/stealthify/detect</td>
      <td>Charged words = input words</td>
    </tr>

    <tr>
      <td>/api/stealthify/agent</td>
      <td>Charged words = ceil(output words × 10), where output words are derived from the returned markdown</td>
    </tr>
  </tbody>
</Table>

<Note>
  For multi-step long-form output (academic essays, SEO posts, platform-tuned social posts), use [Stealth Agent](/api-reference/stealth-agent/overview). The `× 10` multiplier on output words funds the research → draft → optional fact-check → humanize → optional images pipeline.
</Note>

## Rate Limits

StealthGPT API has the following rate limits to ensure optimal performance and fair usage:

* **3,500 RPM** (Requests Per Minute)
* **350,000 WPM** (Words Per Minute)

## How to Get Started

### Get Started

1. Activate API access at [stealthgpt.ai/stealthapi](https://www.stealthgpt.ai/stealthapi)
2. Add a payment method during activation (required before API access is enabled)
3. Start using the API with free starter access; pay-as-you-go billing applies after starter/prepaid words are exhausted


# Quick Start Guide
Source: https://docs.stealthgpt.ai/api-reference/quickstart

Get started with the StealthGPT API in minutes

<Steps>
  <Step title="Sign Up and Get API Key">
    Create an account on the [StealthGPT platform](https://www.stealthgpt.ai), activate API access, and add a payment method during activation (required before API access is enabled). Your API key will be available in the dashboard under the "API Key" tab.
  </Step>

  <Step title="Choose Your Endpoint">
    StealthGPT offers these HTTP APIs:

    <CardGroup>
      <Card title="/api/stealthify" icon="wand-magic-sparkles">
        Generate or rephrase content based on your prompt
      </Card>

      <Card title="/api/stealthify/agent" icon="robot">
        Long-form Stealth Agent runs (academic, SEO, or social presets)
      </Card>
    </CardGroup>
  </Step>

  <Step title="Send Your First Request">
    Make your first API call using one of our code examples:

    <CodeGroup>
      ```bash curl-example theme={null}
      curl --location 'https://www.stealthgpt.ai/api/stealthify' \
          --header 'api-token: YOUR_API_TOKEN' \
          --header 'Content-Type: application/json' \
          --data '{
              "prompt": "Write a paragraph about artificial intelligence",
              "rephrase": false,
              "model": "super"
          }'
      ```

      ```python python-example theme={null}
      import requests

      response = requests.post(
          'https://www.stealthgpt.ai/api/stealthify',
          headers={
              'api-token': 'YOUR_API_TOKEN',
              'Content-Type': 'application/json'
          },
          json={
              'prompt': 'Write a paragraph about artificial intelligence',
              'rephrase': False,
              'model': 'super'
          }
      )

      print(response.json())
      ```

      ```javascript nodejs-example theme={null}
      const axios = require('axios');

      axios.post('https://www.stealthgpt.ai/api/stealthify', {
          prompt: 'Write a paragraph about artificial intelligence',
          rephrase: false,
          model: 'super'
      }, {
          headers: {
              'api-token': 'YOUR_API_TOKEN',
              'Content-Type': 'application/json'
          }
      }).then(response => {
          console.log(response.data);
      });
      ```
    </CodeGroup>
  </Step>

  <Step title="Explore and Experiment">
    Experiment with different parameters and settings to optimize your content generation. Check our [API Reference](/api-reference/endpoints/stealthify) for detailed parameter options.
  </Step>
</Steps>

## What's Next?

* Learn about all available [API endpoints](/api-reference/endpoints/stealthify)
* Explore [advanced usage techniques](/api-reference/advanced-usage)
* View [code examples](/api-reference/code-examples) in various programming languages


# Usage Guide
Source: https://docs.stealthgpt.ai/api-reference/stealth-agent/guide

End-to-end guide for calling /api/stealthify/agent in production

This guide walks through everything you need to call Stealth Agent reliably from your own backend. It assumes you've read the [overview](/api-reference/stealth-agent/overview) and picked a [use case](/api-reference/stealth-agent/use-cases).

Use this when a single humanizer call is not enough and the piece needs research, a draft, and optional fact-checking.

## TL;DR

<Steps>
  <Step title="Get an API token">
    Activate API access at [stealthgpt.ai/stealthapi](https://www.stealthgpt.ai/stealthapi) and add a payment method.
  </Step>

  <Step title="Build a request body for one preset">
    Pick `academic`, `seo`, or `social`. Include `prompt`. For `social`, include `platform`. Optionally enable `enableFactCheck` and `enableImageGeneration`.
  </Step>

  <Step title="POST with a 10-minute timeout">
    Send to `https://www.stealthgpt.ai/api/stealthify/agent` with `api-token` and `Content-Type: application/json` headers. Configure your HTTP client for at least 600s.
  </Step>

  <Step title="Handle the response">
    On `200`, persist `runId`, `documentId`, `result`, and the billing fields. On `4xx`/`5xx`, branch on status — see [Error handling](#error-handling) below.
  </Step>
</Steps>

<Info>
  For production integrations and automation platforms, use [`POST /api/stealthify/agent/runs`](/api-reference/endpoints/stealthify-agent-runs) instead. It returns immediately with a `runId`, supports `idempotency-key`, and can deliver the terminal result to `webhookUrl`.
</Info>

## Step 1: Pick a preset and build the request

The endpoint accepts a discriminated union on `preset`. Unknown fields are rejected by the schema, so don't send extras.

<Tabs>
  <Tab title="academic">
    ```json theme={null}
    {
      "preset": "academic",
      "prompt": "Explain how mitochondria became eukaryotic energy organelles, with citations.",
      "enableFactCheck": true,
      "enableImageGeneration": false
    }
    ```
  </Tab>

  <Tab title="seo">
    ```json theme={null}
    {
      "preset": "seo",
      "prompt": "Write a 1,800-word guide on choosing PostgreSQL vs MySQL for early-stage SaaS.",
      "enableFactCheck": true,
      "enableImageGeneration": true
    }
    ```
  </Tab>

  <Tab title="social">
    ```json theme={null}
    {
      "preset": "social",
      "platform": "linkedin",
      "prompt": "Post about lessons learned migrating to documented async standups.",
      "enableFactCheck": false,
      "enableImageGeneration": false
    }
    ```
  </Tab>
</Tabs>

See the full schema and per-field documentation in the [endpoint reference](/api-reference/endpoints/stealthify-agent).

## Step 2: Configure your HTTP client

Stealth Agent runs are **multi-step** and can take **several minutes**. The server allows up to **600 seconds** per request — your client must allow at least that long.

<Warning>
  Most HTTP clients default to 30–60 seconds. If you don't raise the timeout, your client will abort runs mid-pipeline and the user will see a misleading error while the server keeps working.
</Warning>

<CodeGroup>
  ```bash curl theme={null}
  curl --request POST \
    --url 'https://www.stealthgpt.ai/api/stealthify/agent' \
    --header 'Content-Type: application/json' \
    --header 'api-token: YOUR_API_TOKEN' \
    --max-time 600 \
    --data '{
      "preset": "seo",
      "prompt": "Write a 1,800-word guide on choosing PostgreSQL vs MySQL for early-stage SaaS.",
      "enableFactCheck": true,
      "enableImageGeneration": true
    }'
  ```

  ```python python (requests) theme={null}
  import requests

  response = requests.post(
      "https://www.stealthgpt.ai/api/stealthify/agent",
      headers={
          "api-token": "YOUR_API_TOKEN",
          "Content-Type": "application/json",
      },
      json={
          "preset": "seo",
          "prompt": "Write a 1,800-word guide on choosing PostgreSQL vs MySQL for early-stage SaaS.",
          "enableFactCheck": True,
          "enableImageGeneration": True,
      },
      timeout=600,
  )

  response.raise_for_status()
  data = response.json()
  print(data["runId"], data["outputWords"], "words")
  ```

  ```javascript nodejs (fetch) theme={null}
  const controller = new AbortController()
  const timeout = setTimeout(() => controller.abort(), 600_000)

  try {
    const res = await fetch('https://www.stealthgpt.ai/api/stealthify/agent', {
      method: 'POST',
      headers: {
        'api-token': 'YOUR_API_TOKEN',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        preset: 'seo',
        prompt: 'Write a 1,800-word guide on choosing PostgreSQL vs MySQL for early-stage SaaS.',
        enableFactCheck: true,
        enableImageGeneration: true,
      }),
      signal: controller.signal,
    })

    if (!res.ok) {
      const error = await res.json().catch(() => ({}))
      throw new Error(`Stealth Agent failed: ${res.status} ${error.message ?? ''}`)
    }

    const data = await res.json()
    console.log(data.runId, data.outputWords, 'words')
  } finally {
    clearTimeout(timeout)
  }
  ```

  ```javascript nodejs (axios) theme={null}
  const axios = require('axios')

  const { data } = await axios.post(
    'https://www.stealthgpt.ai/api/stealthify/agent',
    {
      preset: 'seo',
      prompt: 'Write a 1,800-word guide on choosing PostgreSQL vs MySQL for early-stage SaaS.',
      enableFactCheck: true,
      enableImageGeneration: true,
    },
    {
      headers: {
        'api-token': 'YOUR_API_TOKEN',
        'Content-Type': 'application/json',
      },
      timeout: 600_000,
    },
  )

  console.log(data.runId, data.outputWords, 'words')
  ```
</CodeGroup>

## Step 3: Choose sync or async delivery

A 5–10 minute synchronous request is fine for a CLI or a one-off script, but it's a poor fit for an HTTP-facing API, UI, workflow engine, or agent integration.

<CardGroup>
  <Card title="Use sync for scripts" icon="terminal" href="/api-reference/endpoints/stealthify-agent">
    `POST /api/stealthify/agent` returns the final markdown directly, but your HTTP client must wait up to 10 minutes.
  </Card>

  <Card title="Use async for integrations" icon="webhook" href="/api-reference/endpoints/stealthify-agent-runs">
    `POST /api/stealthify/agent/runs` returns `202 Accepted`, lets you poll `statusUrl`, and can call your `webhookUrl` on completion.
  </Card>
</CardGroup>

If you use async runs, the production pattern is:

<Steps>
  <Step title="Accept a generation request synchronously">
    Validate inputs, persist your own job row, and call `POST /api/stealthify/agent/runs` with an `idempotency-key`.
  </Step>

  <Step title="Store the run id">
    Save `runId` and `statusUrl` from the `202 Accepted` response next to your own job id.
  </Step>

  <Step title="Poll or receive webhook">
    Poll `GET /api/stealthify/agent/runs/{runId}` every 5-15 seconds, or provide `webhookUrl` in the create request and wait for the terminal callback.
  </Step>

  <Step title="Persist the terminal payload">
    On `completed`, store `documentId`, `result`, and billing fields. On `failed` or `cancelled`, store `error.code` and `error.message`.
  </Step>
</Steps>

This pattern makes client timeouts non-disruptive, avoids tying up frontend servers, and gives workflow platforms a stable polling/callback contract.

## Step 4: Preflight balance check (optional but recommended)

Stealth Agent can return `402 Payment Required` if the account has no prepaid balance and pay-as-you-go is not enabled. To give a better user experience, call [`GET /api/stealthify/balance`](/api-reference/endpoints/balance) before queuing a long run:

```python python theme={null}
balance = requests.get(
    "https://www.stealthgpt.ai/api/stealthify/balance",
    headers={"api-token": "YOUR_API_TOKEN"},
    timeout=10,
).json()

prepaid = balance["credits"]
payg_mode = (balance.get("payg") or {}).get("mode")

if prepaid <= 0 and payg_mode != "metered_active":
    raise RuntimeError(
        "No prepaid words and metered billing is not active — "
        "have the user accept pay-as-you-go terms before queuing the run."
    )
```

This is best-effort: another concurrent run can still drain the balance while your job waits in the queue. Always also handle the `402` response from the agent endpoint itself.

## Step 5: Read the response

A successful response is a single JSON payload — there is no polling and no `runId`-based status endpoint to call afterwards.

```json theme={null}
{
  "runId": "0c5d…",
  "documentId": "9e1b…",
  "preset": "seo",
  "result": "# How to choose between PostgreSQL and MySQL\n\n…",
  "outputWords": 1842,
  "creditsSpent": 18420,
  "remainingCredits": 481580,
  "billingMode": "prepaid",
  "meteredChargedCredits": 0
}
```

What to persist on your side:

* **`result`** — the markdown to render or save.
* **`runId`** — useful when reporting issues to support.
* **`documentId`** — the persisted document on StealthGPT's side; pair it with your own row.
* **`creditsSpent` / `billingMode` / `meteredChargedCredits`** — for usage dashboards and reconciliation.

`outputWords` is the canonical word count used for billing (`creditsSpent === ceil(outputWords × 10)`); use it directly instead of recounting `result` on your side.

## Error handling

Stealth Agent returns standard HTTP status codes. Branch on `response.status` first, then read `message` and (when present) `info`:

| Status | Meaning | Recommended action |
| - | - | - |
| **400** | Invalid JSON or schema violation. `info` lists the failing fields. | Don't retry. Fix the request body and resubmit. |
| **401** | Missing `api-token` header or token not found. | Don't retry. Surface to the user that the integration is misconfigured. |
| **402** | Insufficient credits, payg not available, payment method missing, or billing cap delay. | If `message` mentions a cap delay, retry after a few seconds. Otherwise prompt the user to top up or accept payg terms. |
| **499** | Request was aborted (your client disconnected). | No charge. Safe to retry. |
| **500** | Server error. | Retry with exponential backoff (e.g. 30s → 2m → 10m). After 3 attempts, escalate. |

A safe Node.js retry wrapper:

```javascript nodejs theme={null}
async function runStealthAgent(body, { attempts = 3 } = {}) {
  for (let i = 0; i < attempts; i++) {
    try {
      const res = await fetch('https://www.stealthgpt.ai/api/stealthify/agent', {
        method: 'POST',
        headers: {
          'api-token': process.env.STEALTHGPT_API_TOKEN,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(body),
        signal: AbortSignal.timeout(600_000),
      })

      if (res.ok) return await res.json()

      const isRetriable = res.status >= 500 || res.status === 499
      if (!isRetriable) {
        const error = await res.json().catch(() => ({}))
        throw new Error(`stealth-agent ${res.status}: ${error.message ?? ''}`)
      }
    } catch (error) {
      if (i === attempts - 1) throw error
    }

    const backoffMs = Math.min(30_000 * 2 ** i, 600_000)
    await new Promise((resolve) => setTimeout(resolve, backoffMs))
  }

  throw new Error('stealth-agent: exhausted retries')
}
```

## Idempotency and retries

For the synchronous endpoint, each `200` response **creates a new run, persists a new document, and charges credits again**. For async runs, send an `idempotency-key` when creating the run so retries of the same create request do not enqueue duplicates.

<CardGroup>
  <Card title="Retry only on 499 / 5xx" icon="rotate">
    Those statuses confirm no charge happened. Anything else (200, 4xx) is final.
  </Card>

  <Card title="Use async idempotency keys" icon="fingerprint">
    Send `idempotency-key` to `POST /api/stealthify/agent/runs` when retries are possible.
  </Card>

  <Card title="Cap retry attempts" icon="hourglass-half">
    Three attempts with exponential backoff is plenty. Beyond that, escalate to manual review — you may be hitting a real outage.
  </Card>

  <Card title="Avoid blind sync retries" icon="triangle-exclamation">
    A timeout you observe locally does not mean the server failed. Prefer async runs when the caller cannot wait reliably.
  </Card>
</CardGroup>

## Cost control checklist

Stealth Agent charges `ceil(outputWords × 10)` per successful run. To keep spend predictable:

<Steps>
  <Step title="Constrain output length in the prompt">
    Include a target word range (`"Write a 1,200-word essay…"`). The agent respects length hints; longer outputs cost proportionally more.
  </Step>

  <Step title="Don't auto-retry 200 responses">
    Each sync retry is a fresh charge. For async create retries, reuse the same `idempotency-key`.
  </Step>

  <Step title="Skip optional steps you don't need">
    `enableFactCheck` and `enableImageGeneration` add latency. They don't change the per-word price, but turning them off makes the run faster — useful if you're rate-limited or paying for compute on your worker side.
  </Step>

  <Step title="Track usage with the response fields">
    Record `creditsSpent` and `billingMode` on every job. A weekly aggregation surfaces drift before you see it on the invoice.
  </Step>
</Steps>

## Long-form example

```python python (stealth agent) theme={null}
requests.post(
    "https://www.stealthgpt.ai/api/stealthify/agent",
    headers={"api-token": TOKEN, "Content-Type": "application/json"},
    json={
        "preset": "academic",
        "prompt": "Write a 1,500-word essay on the causes of the French Revolution.",
        "enableFactCheck": True,
    },
    timeout=600,
)
```

Migration checklist:

<AccordionGroup>
  <Accordion title="Pick the right preset for your prompt">
    Citations or scholarly tone → `academic`. Public-facing blog content → `seo`. LinkedIn or Medium → `social`.
  </Accordion>

  <Accordion title="Drop fields the agent doesn't use">
    Writer fields such as `tone`, `writingMode`, `rephrase`, `qualityMode`, and `outputFormat` are not part of the agent schema and will fail the strict validator. Send only the documented fields.
  </Accordion>

  <Accordion title="Raise your client timeout">
    Replace 30–60s defaults with 600s. The legacy endpoint typically returned in seconds; the agent can take minutes.
  </Accordion>

  <Accordion title="Switch from `wordsSpent` to `outputWords` + `creditsSpent`">
    The agent does not return `wordsSpent`. Use `outputWords` for the word count and `creditsSpent` for the actual charge.
  </Accordion>

  <Accordion title="Move the call into a background worker">
    Synchronous multi-minute calls block UI threads and request handlers. Queue them.
  </Accordion>
</AccordionGroup>

## Where to go next

<CardGroup>
  <Card title="Async runs" icon="webhook" href="/api-reference/endpoints/stealthify-agent-runs">
    Create runs, poll status, receive callbacks, and use idempotency keys.
  </Card>

  <Card title="Use cases" icon="lightbulb" href="/api-reference/stealth-agent/use-cases">
    Concrete prompt patterns and recommended option combinations.
  </Card>

  <Card title="Pricing" icon="receipt" href="/api-reference/pricing">
    Per-endpoint billing rules, tiers, and pay-as-you-go behavior.
  </Card>
</CardGroup>


# Stealth Agent
Source: https://docs.stealthgpt.ai/api-reference/stealth-agent/overview

Multi-step Stealth Agent for long-form content

The **Stealth Agent** is StealthGPT's long-form content API. It researches the topic, drafts the content, optionally fact-checks it, humanizes the prose, and optionally inserts images.

<CardGroup>
  <Card title="Synchronous endpoint" icon="terminal" href="/api-reference/endpoints/stealthify-agent">
    `POST /api/stealthify/agent` — wait for the final markdown in one long-running HTTP request.
  </Card>

  <Card title="Async runs endpoint" icon="webhook" href="/api-reference/endpoints/stealthify-agent-runs">
    `POST /api/stealthify/agent/runs` — create a run, poll status, and optionally receive a webhook callback.
  </Card>
</CardGroup>

## Why Stealth Agent

A single-pass humanizer (the `/api/stealthify` endpoint) is excellent at rewriting text you already have. For long-form generation where the model has to **plan, research, cite, and write from scratch**, a single pass is not enough. The Stealth Agent runs each step as a dedicated stage with its own model, prompt, and validation:

<CardGroup>
  <Card title="Researched, not invented" icon="magnifying-glass">
    Web research grounds the draft in real sources before the writing model sees the prompt, reducing hallucinations.
  </Card>

  <Card title="Optional fact-checking" icon="shield-check">
    `enableFactCheck: true` runs an additional pass that verifies claims and rewrites unsupported ones before humanization.
  </Card>

  <Card title="Humanized last" icon="wand-magic-sparkles">
    Humanization runs **after** drafting and fact-checking, so the final text reads naturally, stays low-detection, and strips invisible Claude and Gemini text watermarks automatically.
  </Card>

  <Card title="Format-aware output" icon="file-lines">
    Each preset returns markdown shaped for its medium — academic structure with citations, SEO sections with headings, or platform-tuned social posts.
  </Card>
</CardGroup>

## Presets

The endpoint accepts a discriminated union on `preset`. You pick the preset that matches your output, and the agent picks the right pipeline.

<Tabs>
  <Tab title="academic">
    **Use for**: essays, literature reviews, study-guide style explainers, research-paper drafts.

    Pipeline: web research → academic draft → optional fact-check → humanize → academic post-processing (citations + optional images).

    Returns markdown with citations formatted in your chosen style (APA by default).
  </Tab>

  <Tab title="seo">
    **Use for**: long-form blog posts, evergreen guides, comparison articles, programmatic-SEO landing pages.

    Pipeline: web research + keyword research (in parallel) → competitor analysis → SEO draft → meta generation → optional fact-check → humanize → optional images.

    Returns markdown with H1/H2/H3 structure shaped for search intent and discovered keywords.
  </Tab>

  <Tab title="social">
    **Use for**: LinkedIn thought-leadership posts and Medium articles.

    Pipeline: web research + platform-specific social research (in parallel) → platform-aware draft → optional fact-check → humanize → optional images.

    `platform` is required and must be `"linkedin"` or `"medium"`. The voice, structure, and length adapt to the platform.
  </Tab>
</Tabs>

## What you get back

Every successful run returns final markdown plus billing metadata. The synchronous endpoint returns it directly as `200 OK`; the async endpoint returns it from polling or webhook callback once the run is `completed`.

| Field | What it is |
| - | - |
| `result` | Final humanized content as markdown. The exact same content stored against `documentId`. |
| `runId` | Server-side identifier of the run. Useful for support tickets and future replay endpoints. |
| `documentId` | Identifier of the persisted document for this run. |
| `preset` | Echoes your input preset. |
| `outputWords` | Word count of `result`, used for billing. |
| `creditsSpent` | `ceil(outputWords × 10)` Stealth API words charged for this run. |
| `remainingCredits` | Prepaid balance after the charge. |
| `billingMode` | `"prepaid"` or `"payg"`. |
| `meteredChargedCredits` | Words billed to metered usage (0 when fully prepaid). |

See the [synchronous endpoint reference](/api-reference/endpoints/stealthify-agent) or [async runs reference](/api-reference/endpoints/stealthify-agent-runs) for complete schemas and error codes.

## Billing model

Stealth Agent uses the **same Stealth API balance and pay-as-you-go rules** as `/api/stealthify`, but charges by output:

* **`creditsSpent = ceil(outputWords × 10)`** — input length does not change the price.
* Billing falls back from prepaid balance to pay-as-you-go automatically when terms are accepted and a payment method is on file.
* Cancelled requests (HTTP `499`) are not charged.

See [Pricing](/api-reference/pricing) for full rate cards and tiers.

## How long does a run take

Stealth Agent runs are **multi-step** and can take **several minutes**. For direct synchronous calls, the server allows up to **600 seconds** per request and your client must use a 10-minute timeout. For production integrations, use async runs so your create request returns immediately and the final result is delivered through polling or webhook.

The [usage guide](/api-reference/stealth-agent/guide) walks through timeout configuration, balance preflight checks, error recovery, and idempotency considerations end-to-end.

## Next steps

<CardGroup>
  <Card title="Usage guide" icon="book-open" href="/api-reference/stealth-agent/guide">
    End-to-end walkthrough: pick a preset, configure the client, handle errors, and ship to production.
  </Card>

  <Card title="Use cases" icon="lightbulb" href="/api-reference/stealth-agent/use-cases">
    Concrete prompts and recommended preset/option combinations for common workflows.
  </Card>

  <Card title="Async runs" icon="webhook" href="/api-reference/endpoints/stealthify-agent-runs">
    Create runs, poll status, receive callbacks, and use idempotency keys.
  </Card>
</CardGroup>


# Use Cases
Source: https://docs.stealthgpt.ai/api-reference/stealth-agent/use-cases

Practical Stealth Agent recipes by preset, with prompt patterns and recommended options

This page is a recipe book for `POST /api/stealthify/agent`. Each recipe shows when to reach for a preset, a prompt pattern that works, and the recommended `enableFactCheck` / `enableImageGeneration` settings. For the full request schema see the [endpoint reference](/api-reference/endpoints/stealthify-agent); for end-to-end integration see the [usage guide](/api-reference/stealth-agent/guide).

<Note>
  All Stealth Agent runs charge `ceil(outputWords × 10)` Stealth API words. The recipes below note when fact-check or image generation is worth the extra latency; both add wall-clock time but do not change the billing formula.
</Note>

## Picking a preset

<CardGroup>
  <Card title="academic" icon="graduation-cap">
    Anything that needs **citations** or a structured argument: essays, lit reviews, study materials, research drafts.
  </Card>

  <Card title="seo" icon="magnifying-glass-chart">
    Anything **published on a website** to drive search traffic: blog posts, comparison pages, evergreen guides.
  </Card>

  <Card title="social" icon="share-nodes">
    Anything **published on LinkedIn or Medium**: thought-leadership posts, founder updates, technical write-ups.
  </Card>
</CardGroup>

If your output needs to look like a webpage with H2/H3 headings → `seo`. If it needs citations → `academic`. If it needs platform voice → `social`.

## Academic

The `academic` preset is the right choice whenever the output should read as scholarly and is expected to include citations. The pipeline runs web research, drafts in academic register, optionally fact-checks, humanizes, and post-processes the markdown to insert citations in your chosen style (APA by default).

<AccordionGroup>
  <Accordion title="Student-style essay or assignment draft">
    Use as a study scaffold. Keep prompts focused on a single thesis; the agent will research and structure the argument.

    ```json theme={null}
    {
      "preset": "academic",
      "prompt": "Write a 1,200-word essay arguing that mandatory financial-literacy courses in U.S. high schools improve adult savings rates. Cover history, current evidence, and counter-arguments.",
      "enableFactCheck": true,
      "enableImageGeneration": false
    }
    ```

    **Why these options**: `enableFactCheck: true` because graded work is the highest-stakes use case for hallucinations; images are usually disallowed in academic submissions.
  </Accordion>

  <Accordion title="Literature review section">
    Useful as a starting draft you'll edit by hand. Be explicit about scope and time window.

    ```json theme={null}
    {
      "preset": "academic",
      "prompt": "Draft a literature review on the effects of high-intensity interval training (HIIT) on VO2 max in adults aged 50+. Focus on peer-reviewed studies from 2018 onward and contrast HIIT with moderate continuous training.",
      "enableFactCheck": true,
      "enableImageGeneration": false
    }
    ```

    **Why these options**: lit reviews live and die by source quality — always fact-check.
  </Accordion>

  <Accordion title="Research-paper draft (introduction + background)">
    Stealth Agent is best used for **the introduction and background sections** of a paper. The methods, results, and discussion sections need your real data.

    ```json theme={null}
    {
      "preset": "academic",
      "prompt": "Write the introduction and background sections for a paper titled 'Sleep Latency and Working-Memory Performance in University Students'. Include the gap in current research and the study's contribution.",
      "enableFactCheck": true,
      "enableImageGeneration": false
    }
    ```
  </Accordion>

  <Accordion title="Study guide / explainer">
    A lower-stakes academic use case. Fact-check is still recommended but not required if you'll review the output.

    ```json theme={null}
    {
      "preset": "academic",
      "prompt": "Create a study guide on the causes and consequences of the 2008 financial crisis suitable for undergraduate economics students. Include key terms, a timeline, and three discussion questions at the end.",
      "enableFactCheck": false,
      "enableImageGeneration": false
    }
    ```
  </Accordion>
</AccordionGroup>

## SEO

The `seo` preset combines web research with a parallel keyword-research and competitor-analysis pass before drafting. Use it for any content destined for a website where ranking matters. The output is markdown structured as a publishable article.

<AccordionGroup>
  <Accordion title="Pillar / evergreen blog post">
    The most common use case. Give the agent a clear topic and the search intent you're targeting.

    ```json theme={null}
    {
      "preset": "seo",
      "prompt": "Write a comprehensive guide on choosing between PostgreSQL and MySQL for early-stage SaaS startups. Cover use cases, performance, ecosystem, and cost. Aim for 1,800–2,200 words.",
      "enableFactCheck": true,
      "enableImageGeneration": true
    }
    ```

    **Why these options**: technical accuracy is critical for developer audiences (`enableFactCheck: true`), and inline images significantly improve dwell time on long-form posts.
  </Accordion>

  <Accordion title="Comparison / 'X vs Y' article">
    The keyword + competitor passes shine here because comparison queries are crowded.

    ```json theme={null}
    {
      "preset": "seo",
      "prompt": "Compare Stripe and Adyen for European subscription businesses processing $5M–$50M ARR. Cover fees, payment-method coverage, dashboard quality, and developer experience.",
      "enableFactCheck": true,
      "enableImageGeneration": false
    }
    ```

    **Why these options**: pricing/feature claims need verification; comparison posts read better with tables than with images.
  </Accordion>

  <Accordion title="Programmatic / template-driven landing page">
    Send a structured prompt per template variant. Keep prompts narrow so each page has unique substance.

    ```json theme={null}
    {
      "preset": "seo",
      "prompt": "Write a 900-word page titled 'How to deduct home-office expenses as a freelancer in California for tax year 2025'. Include eligibility, the simplified vs actual-expense methods, and three concrete examples.",
      "enableFactCheck": true,
      "enableImageGeneration": false
    }
    ```

    **Why these options**: tax content has high accuracy stakes — always fact-check; for thin programmatic pages, skip images to keep them lean.
  </Accordion>

  <Accordion title="Listicle ('best X for Y')">
    Listicles benefit most from competitor analysis because they share SERP space with established roundups.

    ```json theme={null}
    {
      "preset": "seo",
      "prompt": "Write 'The 7 best note-taking apps for engineers in 2026'. For each, cover platform support, markdown handling, code-block features, and pricing. Include a final recommendation.",
      "enableFactCheck": true,
      "enableImageGeneration": true
    }
    ```
  </Accordion>
</AccordionGroup>

## Social

The `social` preset requires a `platform` (`"linkedin"` or `"medium"`). Pipelines diverge: LinkedIn produces shorter, hook-driven posts; Medium produces longer narrative articles with section structure.

<AccordionGroup>
  <Accordion title="LinkedIn thought-leadership post">
    Best for founders, operators, and consultants. Be concrete about the angle and the audience.

    ```json theme={null}
    {
      "preset": "social",
      "platform": "linkedin",
      "prompt": "Post about the lessons we learned moving our 30-person engineering org from a synchronous-meeting culture to documented async standups, written in the voice of a CTO. Include one hard tradeoff.",
      "enableFactCheck": false,
      "enableImageGeneration": false
    }
    ```

    **Why these options**: opinion-based posts don't need fact-checking; LinkedIn rewards text-only posts in the feed algorithm.
  </Accordion>

  <Accordion title="LinkedIn product or launch announcement">
    Provide the actual facts in the prompt. The agent's job is voice and structure, not invention.

    ```json theme={null}
    {
      "preset": "social",
      "platform": "linkedin",
      "prompt": "Announce the launch of our open-source Postgres connection-pool library, 'Pgly'. Key facts: 30k req/s on a single c7g.large, 2-line drop-in replacement for pgbouncer, MIT-licensed, repo at github.com/example/pgly. Include a clear call to action to star the repo.",
      "enableFactCheck": false,
      "enableImageGeneration": true
    }
    ```

    **Why these options**: facts are supplied in the prompt so external fact-checking is unnecessary; an image (logo or screenshot) lifts a launch post.
  </Accordion>

  <Accordion title="Medium long-form technical write-up">
    Medium handles longer articles well — give the agent room to develop the idea.

    ```json theme={null}
    {
      "preset": "social",
      "platform": "medium",
      "prompt": "Write a Medium article titled 'Why we replaced our message queue with PostgreSQL LISTEN/NOTIFY'. Cover the original setup, three failure modes that motivated the migration, the new architecture, and the operational tradeoffs we accepted.",
      "enableFactCheck": false,
      "enableImageGeneration": true
    }
    ```

    **Why these options**: it's an opinion piece grounded in your experience, not a research piece; images break up long technical articles.
  </Accordion>

  <Accordion title="Medium tutorial">
    Tutorials benefit from fact-check when they cover external APIs that change.

    ```json theme={null}
    {
      "preset": "social",
      "platform": "medium",
      "prompt": "Tutorial: 'Streaming OpenAI completions to a React UI with the Vercel AI SDK in 2026'. Walk through project setup, the streamText API, error handling, and a working end-to-end example.",
      "enableFactCheck": true,
      "enableImageGeneration": true
    }
    ```
  </Accordion>
</AccordionGroup>

## Anti-patterns

Stealth Agent is built for **long-form, single-call generation**. Don't use it when:

* **You already have the text and only need to humanize/rephrase it.** Use `/api/stealthify` with `rephrase: true` — it's faster and a fraction of the cost.
* **You need a structured response** (JSON, classification, extraction). Stealth Agent returns markdown only.
* **You need sub-second latency** for an interactive UI. Runs take minutes; queue them as background jobs and notify the user when `result` is ready.
* **You want chat-style multi-turn refinement.** The endpoint is single-shot. Iterate by adjusting the prompt and re-running.

## Recipe checklist

Before sending any Stealth Agent request, confirm:

<Steps>
  <Step title="Pick the preset">
    Citations needed → `academic`. Web SEO → `seo`. LinkedIn or Medium → `social` with the right `platform`.
  </Step>

  <Step title="Write a focused prompt">
    State the topic, audience, and approximate length. Supply any non-public facts the agent must include verbatim.
  </Step>

  <Step title="Decide on fact-check">
    Default `false`. Turn on for graded academic work, technical claims, regulated topics (legal, medical, tax, finance), and crowded SEO niches.
  </Step>

  <Step title="Decide on image generation">
    Default `false`. Turn on for SEO long-form, Medium articles, and LinkedIn launch posts. Skip for academic submissions and thin pages.
  </Step>

  <Step title="Set a 10-minute client timeout">
    The server allows up to 600s. Most HTTP clients default lower — see the [usage guide](/api-reference/stealth-agent/guide) for snippets.
  </Step>
</Steps>


# Workflow patterns
Source: https://docs.stealthgpt.ai/api-reference/workflow-patterns

Three recommended ways to integrate the async Stealth Agent API

Stealth Agent and humanization runs are **asynchronous**: you start a run, get a `runId` immediately, and the long-running work (research, drafting, humanization, scoring) happens in the background. There are three recommended patterns for consuming it.

## 1. Queue and poll

Best for scripts, cron jobs, and simple backends.

1. **Start** a run: `POST /api/stealthify/runs` (`rephrase: true` humanizes, `rephrase: false` writes) or `POST /api/stealthify/agent/runs` (full pipeline) → `202` with `runId` + `statusUrl`.
2. **Poll** `GET .../runs/{runId}` every 5–15 seconds until `status` is `completed`, `failed`, or `cancelled`.
3. Read the final `result` and billing metadata from the completed response.

Use an `idempotency-key` header on create so retries never enqueue duplicate runs or double-charge.

→ [Humanizer async runs](/api-reference/endpoints/stealthify-runs) · [Stealth Agent async runs](/api-reference/endpoints/stealthify-agent-runs)

## 2. Fire and webhook

Best for no-code tools (n8n, Make, WordPress) and event-driven backends that don't want to poll.

1. **Start** a run and include `webhookUrl` (and optionally `webhookSecret`).
2. When the run reaches a terminal state, StealthGPT `POST`s the result (or terminal failure) to your `webhookUrl`.
3. Verify the `x-stealthgpt-signature` HMAC (when `webhookSecret` is set) and reconcile by `x-stealthgpt-run-id`.

Webhooks are best-effort with retries on `429`/`5xx`; treat delivery as at-least-once and dedupe by run id + status.

→ See the **Webhook callbacks** section on the [async runs](/api-reference/endpoints/stealthify-runs) page.

## 3. Agent / tool invocation

Best for AI agents and chat clients — let the model call StealthGPT as a tool via our MCP server (Cursor today; claude.ai web & ChatGPT via OAuth coming soon).

→ [Use Stealth Agent from MCP clients](/api-reference/integrations/mcp)

## Picking a pattern

| You are… | Use |
| - | - |
| A backend / script | Queue and poll |
| A no-code or event-driven workflow | Fire and webhook |
| An AI agent / LLM client | Agent / tool invocation (MCP) |