---
id: api
name: SupWriter Text API
version: 1.0.0
---

# SupWriter Text API

One REST API for four tools — **humanize**, **paraphrase**, **grammar check**, and **AI detection** — the same engines that power the SupWriter app. Hand this file to your AI coding agent and ask it to integrate SupWriter; everything it needs is below.

## Base URL

`https://supwriter.com/api/v1`

## Authentication

Every request needs a personal API key, created at **Settings → API & MCP** (requires a Pro or Ultra plan). Send it as a Bearer token over HTTPS:

```
Authorization: Bearer sw_live_xxxxxxxx
```

`x-api-key: sw_live_…` is also accepted. Keep the key server-side — never ship it to the browser.

## Response envelope

Success (HTTP 200):

```json
{ "success": true, "data": { /* endpoint-specific, see below */ } }
```

Error (with the matching HTTP status):

```json
{ "success": false, "error": { "code": "invalid_api_key", "message": "…" } }
```

## Endpoints

All endpoints are `POST` with a JSON body. `text` is always required.

### POST /humanize

Rewrite AI-generated text so it reads as naturally human-written.

- Request: `{ "text": string, "intensity"?: "low"|"medium"|"high", "format"?: "plain"|"markdown", "language"?: string, "tone"?: string, "purpose"?: string }`
- `data`: `{ "humanized_text": string, "word_count": number, "credits_used": number, "credits_remaining": number, "processing_time_ms": number }`

### POST /paraphrase

Reword while preserving meaning, then humanize the result.

- Request: `{ "text": string, "mode"?: "standard"|"formal"|"casual"|"academic"|"creative", "language"?: string }`
- `data`: `{ "paraphrased_text": string, "word_count": number, "credits_used": number, "processing_time_ms": number }`

### POST /grammar

Fix grammar, spelling, and punctuation.

- Request: `{ "text": string, "mode"?: "basic"|"thorough"|"style", "language"?: string }`
- `data`: `{ "corrected_text": string, "word_count": number, "credits_used": number, "processing_time_ms": number }`

### POST /detect

Score text for AI authorship across 12 detectors with a sentence-level breakdown.

- Request: `{ "text": string }`
- `data`: `{ "detection_score": number (0-100, higher = more likely AI), "detectors": { [name: string]: "right"|"warn"|"bad" }, "sentences": [{ "sentence": string, "score": number, "classification": "HUMAN_ONLY"|"MIXED"|"AI_GENERATED" }], "word_count": number, "credits_used": number, "credits_remaining": number }`

## Errors

| HTTP | `code`                   | Meaning                                          |
| ---- | ------------------------ | ------------------------------------------------ |
| 401  | `invalid_api_key`        | Missing or invalid API key.                      |
| 403  | `plan_required`          | API access requires a Pro or Ultra plan.         |
| 403  | `insufficient_credits`   | Not enough word credits on the plan.             |
| 403  | `plan_limit`             | Text exceeds the plan's per-request word cap.    |
| 403  | `language_not_available` | Requested language requires a higher plan.       |
| 400  | `invalid_input`          | Missing or malformed `text`.                     |
| 429  | `rate_limited`           | Over the per-minute limit; honor `Retry-After`.  |
| 500  | `provider_error`         | Upstream processing failed; safe to retry.       |

## Rate limits & billing

- **Pro:** 60 requests/minute, 1,500 words/request. **Ultra:** 120 requests/minute, 3,000 words/request — per key.
- Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`; a 429 also sends `Retry-After`.
- Billing: 1 word credit per word. AI detection is metered on the API (it's free only in the web app).

## Example (cURL)

```bash
curl -s https://supwriter.com/api/v1/humanize \
  -H "Authorization: Bearer $SUPWRITER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Your AI-generated text here.","intensity":"medium"}'
```

## Implementation checklist

1. Read `SUPWRITER_API_KEY` from a server-side env var; never expose it client-side. HTTPS only.
2. Write one typed client function per tool (or a single `call(tool, body)`), POSTing to the base URL with the Bearer header.
3. On success, unwrap `data`; on failure, map `error.code` to typed errors.
4. Retry on `429` up to 3 times, waiting `Retry-After` seconds.
5. Surface `credits_remaining` so users can see usage.

Full human-readable reference: https://supwriter.com/developers