API Developer Docs

Authentication

Create a key in Settings → API (Pro/Ultra). Send it as a Bearer token on every request over HTTPS. Treat it like a password — it's shown only once.

Base URL: https://supwriter.com/api/v1

Quickstart

const res = await fetch("https://supwriter.com/api/v1/humanize", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SUPWRITER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ text: "Your text here." }),
});

const { success, data, error } = await res.json();
if (!success) throw new Error(error.code);
console.log(data.humanized_text);

What you can do with the API

Four endpoints, one key. Every call consumes word credits from your plan — here's the cost of each.

Plans & limits

The developer REST API is available on the Pro and Ultra plans. MCP connects on every plan — Pro and Ultra additionally unlock REST API keys and static-token (headless) MCP.

Build it with your AI agent

Copy one prompt — your agent reads the full skill.md spec and builds all four tools.

Target stack: Next.js.

Integrate SupWriter into my project.

Read the full spec first and follow it exactly: https://supwriter.com/skill.md
It documents authentication (a server-side "Authorization: Bearer sw_live_..." key), the base URL https://supwriter.com/api/v1, five endpoints — POST /humanize, /paraphrase, /grammar and /detect, plus GET /me for plan, credits and limits — and the error codes, rate limits (Pro 60 / Ultra 120 requests per minute) and per-word credit billing.

There are two ways in. Pick the one that fits what I asked for.

1) Scripts, content pipelines and CI — use the official CLI instead of writing HTTP calls:

   npm install -g supwriter

   Authenticate with the SUPWRITER_API_KEY environment variable (do not run `sw login` in CI).
   It reads stdin and writes stdout, so it composes:

     cat draft.md | sw humanize > final.md
     sw humanize 'drafts/*.md' --tone academic --out-dir humanized/
     sw detect 'content/**/*.md' --max-score 30    # exits non-zero above the threshold

   It already handles splitting documents over the per-request word limit, retrying 429s, and a distinct exit code per failure class. Run `sw --help` for the full reference — do not reimplement any of that by hand.

2) In-app features — build a typed client against the REST API that:
   - reads the API key from a server-side env var, never the browser (HTTPS only),
   - unwraps "data", maps "error.code" to typed errors, and retries 429s honoring Retry-After,
   - reads limits.words_per_request from GET /me and splits longer inputs before sending,
   - then adds a small UI to humanize, paraphrase, grammar-check and AI-detect text.

Use my existing stack and conventions, and keep the key server-side only.

Command line

The same four tools as a CLI — the quickest way to try the API, and the easiest way to put it in CI. Reads stdin, writes stdout, splits documents over your plan's word limit, and exits with a distinct code per error class.

npm install -g supwriter

sw login                                     # or set SUPWRITER_API_KEY
cat draft.md | sw humanize > final.md
sw humanize 'drafts/*.md' --tone academic --out-dir humanized/
sw grammar README.md --in-place --mode thorough
sw balance

# Fail the build when content reads as AI-generated
sw detect 'content/**/*.md' --max-score 30

Installs as both sw and supwriter. Needs Node 20.10+. Run sw --help for the full reference.

Endpoints

{
  "text": "Your AI-generated text here.",   // required
  "intensity": "medium",                      // optional: low | medium | high
  "format": "plain",                          // optional: plain | markdown
  "language": "english",                      // optional
  "tone": "general",                          // optional
  "purpose": "general"                        // optional
}

{
  "success": true,
  "data": {
    "humanized_text": "The humanized output.",
    "word_count": 42,
    "credits_used": 42,
    "credits_remaining": 14958,
    "processing_time_ms": 8120
  }
}

{
  "text": "Text to paraphrase.",   // required
  "mode": "standard",               // optional: standard | formal | casual | academic | creative
  "language": "english"             // optional
}

{
  "success": true,
  "data": {
    "paraphrased_text": "The paraphrased output.",
    "word_count": 40,
    "credits_used": 40,
    "processing_time_ms": 7600
  }
}

{
  "text": "Text too correct.",   // required
  "mode": "basic",                // optional: basic | thorough | style
  "language": "english"           // optional
}

{
  "success": true,
  "data": {
    "corrected_text": "Text to correct.",
    "word_count": 3,
    "credits_used": 3,
    "processing_time_ms": 5400
  }
}

{
  "text": "Text to analyze."   // required
}

{
  "success": true,
  "data": {
    "detection_score": 12,
    "detectors": { "turnitin": "right", "gptzero": "right", "...": "..." },
    "sentences": [{ "sentence": "...", "score": 5, "classification": "HUMAN_ONLY" }],
    "word_count": 120,
    "credits_used": 120,
    "credits_remaining": 14880,
    "processing_time_ms": 3100
  }
}

// No body — GET with the Authorization header only.

{
  "success": true,
  "data": {
    "user": { "id": "…", "email": "you@example.com", "name": "Your Name" },
    "plan": {
      "type": "pro",
      "billing_period": "monthly",
      "current_period_end": "2026-09-12T00:00:00Z",
      "cancel_at_period_end": false
    },
    "credits": {
      "remaining": 14880, "total": 15000, "used": 120,
      "plan_remaining": 14880, "extra_remaining": 0
    },
    "limits": {
      "words_per_request": 2000, "max_input_chars": 100000,
      "requests_per_minute": 60
    },
    "rate_limit": { "limit": 60, "remaining": 59, "reset": 1789123456 }
  }
}

Errors

Errors use the envelope { "success": false, "error": { "code", "message" } } with a matching HTTP status.

Rate limits & usage

• Rate limit: Pro 60 / Ultra 120 requests per minute, per key. Over the limit returns 429 rate_limited.
• Repeatedly presenting an invalid key is throttled separately, per IP — after 30 rejected keys in a minute the API answers 429 rate_limited instead of checking further ones. Valid keys never touch this budget.
• Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset; a 429 also sends Retry-After.
• Per-request word caps: Pro 2,000 words, Ultra 5,000 words.
• Every call consumes your plan's word credits — including AI detection, which the API meters (it's free only in the web app).
• Track requests over time in Settings → API — a 30-day usage chart broken down by tool.

Using your key with MCP

The SupWriter MCP server normally uses OAuth, but it also accepts an API key — useful for dev tools (Cursor, Claude Code, the CLI). Configure the connector with an Authorization: Bearer sw_live_… header to skip the browser sign-in.

Key safety

• Store keys server-side (a secret manager / environment variable) — never in client-side code or git.
• Use a separate key per app or environment so you can revoke one without breaking the others.
• If a key is exposed, revoke it in Settings → API and create a new one. Revocation is immediate for new requests.

FAQ