# TypeOS Humanizer API — Full Documentation

The TypeOS Humanizer API lets developers and AI agents humanize AI-generated text programmatically. It transforms text written by ChatGPT, Claude, Gemini, or any other LLM into natural, human-sounding prose that bypasses AI detection tools.

Base URL: https://typeos.com

---

## Authentication

All API requests (except /api/v1/health) require a Bearer token in the Authorization header.

```
Authorization: Bearer tpk_YOUR_API_KEY
```

API keys start with the prefix `tpk_`. Create one at https://typeos.com/dashboard/developers or via the TypeOS dashboard.

---

## Endpoints

### POST /api/v1/humanize

Humanize AI-generated text.

**Headers:**
- Authorization: Bearer tpk_YOUR_API_KEY (required)
- Content-Type: application/json (required)

**Request body (JSON):**
- text (string, required): The AI-generated text to humanize. Minimum 100 characters and 50 words.
- mode (string, optional): Humanization mode. One of:
  - "quality" (default) — highest quality rewriting, most natural output
  - "balance" — balanced between speed and quality
  - "enhanced" — enhanced rewriting with stronger paraphrasing

**Example request:**
```
curl -X POST https://typeos.com/api/v1/humanize \
  -H "Authorization: Bearer tpk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Artificial intelligence has revolutionized the way we process and analyze data...", "mode": "quality"}'
```

**Success response (200):**
```json
{
  "success": true,
  "humanizedText": "The way we handle and make sense of data has been completely transformed by AI...",
  "wordsUsed": 150,
  "remainingWords": 19850
}
```

**Error responses:**
- 400: Invalid request (missing text, bad mode, text too short)
  ```json
  {"success": false, "error": "Field \"text\" is required and must be a string"}
  ```
- 401: Missing or invalid API key
  ```json
  {"success": false, "error": "Missing or invalid API key. Use: Authorization: Bearer tpk_..."}
  ```
- 403: Word quota exceeded
  ```json
  {"success": false, "error": "Word quota exceeded — upgrade your API plan", "upgradeRequired": true, "remainingWords": 0}
  ```
- 429: Rate limit exceeded (includes Retry-After header)
  ```json
  {"success": false, "error": "Rate limit exceeded", "retryAfterMs": 45000}
  ```
- 500: Internal server error
  ```json
  {"success": false, "error": "Internal server error"}
  ```

**Response headers on success:**
- X-RateLimit-Remaining: number of requests remaining in the current window

---

### GET /api/v1/usage

Check your current word usage and remaining balance for the billing period.

**Headers:**
- Authorization: Bearer tpk_YOUR_API_KEY (required)

**Example request:**
```
curl https://typeos.com/api/v1/usage \
  -H "Authorization: Bearer tpk_YOUR_API_KEY"
```

**Success response (200):**
```json
{
  "success": true,
  "plan": "api_developer",
  "usage": {
    "wordsUsed": 8500,
    "wordsIncluded": 20000,
    "wordsRemaining": 11500,
    "unlimited": false
  },
  "rateLimit": {
    "requestsPerMinute": 30
  }
}
```

---

### GET /api/v1/health

Health check endpoint. No authentication required.

**Example request:**
```
curl https://typeos.com/api/v1/health
```

**Response (200):**
```json
{
  "status": "ok",
  "timestamp": "2026-03-18T12:00:00.000Z"
}
```

---

## Pricing

| Plan          | Price    | Words/month       | Words/request | Rate limit   |
|---------------|----------|-------------------|---------------|--------------|
| Developer     | $49/mo   | 50,000            | 1,500         | 30 req/min   |
| Startup       | $149/mo  | 200,000           | 3,000         | 60 req/min   |
| Business      | $349/mo  | 500,000           | 3,000         | 120 req/min  |
| Scale         | $599/mo  | 1,000,000         | 5,000         | 200 req/min  |
| Enterprise    | Custom   | 2M+               | Custom        | Custom       |

Overage rate: $1.50 per 1,000 words on all paid plans.

Manage your plan at https://typeos.com/dashboard/developers

---

## Rate Limits

Rate limits are enforced per API key using a sliding 1-minute window.

| Plan          | Requests per minute |
|---------------|---------------------|
| API Free      | 5                   |
| API Developer | 30                  |
| API Startup   | 60                  |
| API Business  | 120                 |

When rate limited, the API returns HTTP 429 with:
- A Retry-After header (seconds until the next request is allowed)
- retryAfterMs field in the JSON body (milliseconds)

---

## Modes

The humanizer supports three modes that control the style of rewriting:

- **quality** (default): Produces the most natural, human-sounding output. Best for essays, articles, and long-form content.
- **balance**: A middle ground between speed and quality. Good for general-purpose use.
- **enhanced**: Strongest paraphrasing. Restructures sentences more aggressively. Best when the original text is highly formulaic.

Pass the mode in the request body: `{"text": "...", "mode": "quality"}`

---

## CLI Tool (typeos-humanize)

A command-line tool for humanizing text from your terminal. Install via npx (Node.js 18+ required).

### Configure your API key

```
npx typeos-humanize config --key tpk_YOUR_API_KEY
```

This saves the key to ~/.typeos/config.json. Alternatively, set the TYPEOS_API_KEY environment variable.

### Humanize text

```
# Inline text
npx typeos-humanize "Your AI-generated text goes here..."

# From a file
npx typeos-humanize --file essay.txt --output humanized.txt

# From stdin (piping)
cat essay.txt | npx typeos-humanize

# With a specific mode
npx typeos-humanize --mode enhanced "Your text here..."

# JSON output (for scripts and agents)
npx typeos-humanize --json "Your text here..."
```

### Check usage

```
npx typeos-humanize usage
```

Output:
```
Plan:        api_developer
Words used:  8,500 / 50,000
Remaining:   41,500
Rate limit:  30 req/min
```

### Health check

```
npx typeos-humanize health
```

### Exit codes

- 0: Success
- 1: General error
- 2: Rate limited
- 3: Quota exceeded (upgrade required)

### JSON output

All commands support `--json` for machine-readable output, useful for scripts and AI agent tool calls.

---

## Code Examples

### Node.js / TypeScript

```typescript
const response = await fetch("https://typeos.com/api/v1/humanize", {
  method: "POST",
  headers: {
    "Authorization": "Bearer tpk_YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    text: "Artificial intelligence has revolutionized how we analyze data...",
    mode: "quality",
  }),
});

const data = await response.json();

if (data.success) {
  console.log(data.humanizedText);
  console.log(`Words used: ${data.wordsUsed}, remaining: ${data.remainingWords}`);
} else {
  console.error(data.error);
}
```

### Python

```python
import requests

response = requests.post(
    "https://typeos.com/api/v1/humanize",
    headers={
        "Authorization": "Bearer tpk_YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "text": "Artificial intelligence has revolutionized how we analyze data...",
        "mode": "quality",
    },
)

data = response.json()

if data["success"]:
    print(data["humanizedText"])
    print(f"Words used: {data['wordsUsed']}, remaining: {data['remainingWords']}")
else:
    print(f"Error: {data['error']}")
```

### cURL

```bash
curl -X POST https://typeos.com/api/v1/humanize \
  -H "Authorization: Bearer tpk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Artificial intelligence has revolutionized how we analyze data...",
    "mode": "quality"
  }'
```

### Check usage via cURL

```bash
curl https://typeos.com/api/v1/usage \
  -H "Authorization: Bearer tpk_YOUR_API_KEY"
```

---

## For AI Agents

If you are an AI agent or coding assistant integrating the TypeOS Humanizer:

1. Get an API key from https://typeos.com/dashboard/developers
2. Use POST /api/v1/humanize with the Bearer token to humanize text
3. Check remaining quota with GET /api/v1/usage before large batches
4. Handle 429 (rate limit) by respecting the Retry-After header
5. Handle 403 (quota exceeded) by notifying the user to upgrade
6. Use --json flag with the CLI for structured output in tool calls
7. The "quality" mode produces the most natural results; use it by default

---

## Agent Skill (Claude)

A ready-to-install Claude Agent Skill is available for the TypeOS Humanizer API. It teaches Claude how to use the API, handle errors, and follow best practices automatically.

Install via npx:
```
npx typeos-humanize install-skill
```

Or manually:
- Download: https://typeos.com/typeos-humanizer-skill/SKILL.md
- Claude.ai: Settings > Capabilities > Skills > Upload the skill folder (zipped)
- Claude Code / Cursor: Place in your skills directory, or use the npx command above

---

## Support

- Dashboard: https://typeos.com/dashboard/developers
- Email: daniel@typeos.com
- Website: https://typeos.com