API Documentation

# Quick Start

1. **Sign up** at turingpass.ai and create an API key
2. **Install the SDK** (or use curl/fetch directly)
3. **Make your first request**

```bash
curl -X POST https://turingpass.ai/api/v1/scrape \
  -H "Authorization: Bearer tp_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'
```

All API requests require an API key passed via the Authorization header:

```
Authorization: Bearer tp_live_xxxxxxxxxxxx
```

Create and manage keys in the dashboard under **API Keys**.

The core endpoint. Fetches a URL and returns the HTML.

**Request Body:**
| Field | Type | Default | Description |
|-------|------|---------|-------------|
| url | string | required | Target URL |
| options.render | boolean | false | Enable browser rendering |
| options.stealth | boolean | false | Stealth browser mode |
| options.solveCaptcha | boolean | false | Auto-solve CAPTCHAs |
| options.proxy | string | "datacenter" | "datacenter" or "residential" |
| options.waitFor | string | - | Wait condition or CSS selector |
| options.timeout | number | 30000 | Max wait time (ms) |
| options.headers | object | - | Custom request headers |
| options.screenshot | boolean | false | Return base64 screenshot |
| options.extract | object | null | AI extraction schema |

AI-powered structured data extraction. Define a schema, get JSON.

**Request Body:**
| Field | Type | Description |
|-------|------|-------------|
| url | string | Target URL (fetched + rendered first) |
| html | string | Alternative: pass raw HTML directly |
| schema | object | Field definitions with type + description |
| model | string | "fast" (Haiku) or "smart" (Sonnet) |

**Example:**
```json
{
  "url": "https://store.com/product/123",
  "schema": {
    "title": { "type": "string", "description": "Product title" },
    "price": { "type": "number", "description": "Price in USD" },
    "rating": { "type": "number", "description": "Rating out of 5" }
  }
}
```

Standalone CAPTCHA solving. Returns clearance cookies.

**Request Body:**
| Field | Type | Description |
|-------|------|-------------|
| url | string | URL with CAPTCHA |
| type | string | "auto", "cloudflare", "recaptcha_v2", "hcaptcha" |
| returnCookies | boolean | Return solved cookies (default: true) |

Poll for async job results. Returns job status + result when complete.

**Response statuses:** queued, processing, completed, failed

| Plan | Req/min | Req/month | Concurrent |
|------|---------|-----------|------------|
| Free | 10 | 500 | 2 |
| Starter | 60 | 10,000 | 5 |
| Pro | 300 | 100,000 | 20 |
| Enterprise | 1,000 | 1,000,000 | 100 |

Rate limit headers are included in every response:
- `X-RateLimit-Limit`
- `X-RateLimit-Remaining`
- `X-RateLimit-Reset`

| Code | Meaning |
|------|---------|
| 400 | Bad request (invalid URL, missing fields) |
| 401 | Invalid or missing API key |
| 403 | Feature not available on your plan |
| 429 | Rate limit or monthly quota exceeded |
| 500 | Internal server error |
| 502 | Upstream scraping failure |