> ## Documentation Index
> Fetch the complete documentation index at: https://docs.writerzroom.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Direct API Usage

> Python and HTTP integration patterns for the WriterzRoom API.

Use the WriterzRoom API directly from any HTTP client or Python environment. A formal SDK package is on the roadmap. Until then, the patterns below cover all core workflows.

## Installation

No SDK package is required. Use `httpx` or `requests` for Python integrations.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
pip install httpx
```

## Authentication

All requests require a Bearer token. Retrieve your session token from `GET /api/auth/session`.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
HEADERS = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}
BASE_URL = "https://api.writerzroom.com"
```

## Core Patterns

### Submit a Generation Request

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import httpx

response = httpx.post(
    f"{BASE_URL}/api/generate",
    headers=HEADERS,
    json={
        "template": "blog_article_generator",
        "style_profile": "general_blog",
        "generation_mode": "standard",
        "dynamic_parameters": {
            "topic": "AI in enterprise content workflows",
            "target_audience": "content directors",
            "word_count": 1200,
        },
    },
)
data = response.json()
request_id = data["request_id"]
```

### Poll for Completion

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import time

def wait_for_completion(request_id: str, timeout: int = 600, interval: int = 5) -> dict:
    deadline = time.time() + timeout
    while time.time() < deadline:
        res = httpx.get(
            f"{BASE_URL}/api/generate/status/{request_id}",
            headers=HEADERS,
        )
        data = res.json()["data"]
        status = data["status"]
        if status == "completed":
            return data
        if status == "failed":
            raise RuntimeError(f"Generation failed: {data.get('error')}")
        time.sleep(interval)
    raise TimeoutError(f"Generation did not complete within {timeout}s")
```

### Full End-to-End Example

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import httpx, time

BASE_URL = "https://api.writerzroom.com"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"}

def generate(template: str, style: str, params: dict, mode: str = "standard") -> str:
    res = httpx.post(f"{BASE_URL}/api/generate", headers=HEADERS, json={
        "template": template,
        "style_profile": style,
        "generation_mode": mode,
        "dynamic_parameters": params,
    })
    res.raise_for_status()
    request_id = res.json()["request_id"]

    deadline = time.time() + 600
    while time.time() < deadline:
        status_res = httpx.get(f"{BASE_URL}/api/generate/status/{request_id}", headers=HEADERS)
        data = status_res.json()["data"]
        if data["status"] == "completed":
            return data["content"]
        if data["status"] == "failed":
            raise RuntimeError(data.get("error"))
        time.sleep(5)
    raise TimeoutError("Generation timed out")

content = generate(
    template="blog_article_generator",
    style="general_blog",
    params={"topic": "AI in enterprise content", "target_audience": "content directors"},
)
print(content[:500])
```

### List Templates

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
res = httpx.get(f"{BASE_URL}/api/templates", headers=HEADERS)
templates = res.json()["data"]["items"]
for t in templates:
    print(t["id"], "-", t["name"])
```

### List Style Profiles

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
res = httpx.get(f"{BASE_URL}/api/style-profiles", headers=HEADERS)
profiles = res.json()["data"]["items"]
for p in profiles:
    print(p["id"], "-", p["name"], f"({p['tone']})")
```

### List Verticals

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
res = httpx.get(f"{BASE_URL}/api/verticals", headers=HEADERS)
verticals = res.json()["verticals"]
for v in verticals:
    print(v["id"], "-", v["name"])
```

## Error Handling

| Status | Meaning                                                 |
| ------ | ------------------------------------------------------- |
| `402`  | Insufficient credits or inactive subscription           |
| `403`  | Generation mode not available on current plan           |
| `404`  | Template or style profile not found                     |
| `429`  | Rate limit exceeded (10 generation requests per minute) |
| `503`  | Configuration Manager unavailable                       |

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
res = httpx.post(f"{BASE_URL}/api/generate", headers=HEADERS, json={...})
if res.status_code == 402:
    raise RuntimeError("Insufficient credits — purchase a pack at writerzroom.com/dashboard")
res.raise_for_status()
```

## Rate Limits

| Endpoint                        | Limit         |
| ------------------------------- | ------------- |
| `POST /api/generate`            | 10 per minute |
| `GET /api/generate/status/{id}` | 60 per minute |
| All other endpoints             | 200 per hour  |

<Info>
  A formal `writerzroom` Python package is on the roadmap. It will wrap these patterns with async support, automatic polling, and retry logic.
</Info>