API Documentation

Complete reference for the Clawthor writing API.

Introduction

Clawthor provides fine-tuned writing models as tool calls through a simple REST API. Each model is specifically trained or purpose-merged for its writing task — tweets, marketing copy, literary prose, character dialogue, unrestricted creative output, long-form research, and book-quality fiction — 7 models across 3 categories.

The API is OpenAI-compatible, so you can use existing SDKs by changing the base URL.

Base URL: https://clawthor.xyz/api/v1

Authentication

API requests require a bearer token. Generate one from the dashboard at /app/keys. Keys use the prefix ck_live_ for identification.

curl https://clawthor.xyz/api/v1/models \
  -H "Authorization: Bearer ck_live_your_key_here"

The playground uses session cookies, so no API key is needed there.

Models

Returns all available models. No authentication required.

{
  "models": [
    { "id": "tweet-v1", "name": "Tweet Writer", "category": "social" },
    { "id": "marketing-v1", "name": "Marketing Writer", "category": "social" },
    { "id": "prose-v1", "name": "Prose Writer", "category": "prose" },
    { "id": "character-v1", "name": "Character Writer", "category": "prose" },
    { "id": "unfiltered-v1", "name": "Unfiltered Writer", "category": "prose" },
    { "id": "longform-v1", "name": "Longform Writer", "category": "longform" },
    { "id": "gutenberg-v1", "name": "Book Writer", "category": "longform" }
  ]
}

Each model is optimized for a specific writing style. Visit the Models page for detailed specs, system prompts, and architecture details.

Generate Text

Request Body

Example — curl

curl -X POST https://clawthor.xyz/api/v1/generate \
  -H "Authorization: Bearer ck_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tweet-v1",
    "prompt": "Write a viral tweet about AI agents managing DeFi portfolios",
    "max_tokens": 500,
    "temperature": 0.8
  }'

Example — Python

import requests

r = requests.post(
    "https://clawthor.xyz/api/v1/generate",
    headers={"Authorization": "Bearer ck_live_..."},
    json={
        "model": "marketing-v1",
        "prompt": "Write a launch email for our new cross-chain bridge",
        "max_tokens": 500,
    },
)
print(r.json()["text"])

Example — TypeScript

const res = await fetch("https://clawthor.xyz/api/v1/generate", {
  method: "POST",
  headers: {
    "Authorization": "Bearer ck_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "gutenberg-v1",
    prompt: "Write the first chapter of a noir novel set in a city where all money is on-chain",
    max_tokens: 500,
  }),
})
const data = await res.json()
console.log(data.text)

Response

{
  "id": "gen_a1b2c3d4",
  "model": "tweet-v1",
  "text": "We just shipped the fastest DEX on Base...",
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 387,
    "total_tokens": 429
  },
  "created_at": "2026-02-10T..."
}

Streaming

Set stream: true to receive Server-Sent Events:

data: {"id":"gen_a1b2c3d4","delta":"We ","model":"tweet-v1"}
data: {"id":"gen_a1b2c3d4","delta":"just ","model":"tweet-v1"}
...
data: [DONE]

OpenAI Compatible

Drop-in replacement for the OpenAI chat completions endpoint. Use your existing OpenAI SDK by changing the base URL:

Python

from openai import OpenAI

client = OpenAI(
    base_url="https://clawthor.xyz/api/v1",
    api_key="ck_live_your_key"
)

response = client.chat.completions.create(
    model="longform-v1",
    messages=[{"role": "user", "content": "Write a research report on the state of L2 scaling in 2026"}]
)
print(response.choices[0].message.content)

TypeScript

import OpenAI from "openai"

const client = new OpenAI({
  baseURL: "https://clawthor.xyz/api/v1",
  apiKey: "ck_live_your_key",
})

const res = await client.chat.completions.create({
  model: "prose-v1",
  messages: [{ role: "user", content: "Write the opening of a literary short story set in a flooded city" }],
})

Usage & Limits

Returns your usage stats for the last 30 days.

Rate Limit Headers

Every response includes these headers:

Plan Tiers

Rate Limiting

All plans are rate-limited by daily request count. Your plan tier determines how many requests you can make per day (see Plan Tiers above). Rate limits reset at midnight UTC.

When You Hit Your Limit

When you exceed your daily request quota, the API returns a 429 status code with a JSON error body and a Retry-After header indicating how many seconds until your limit resets.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 3600
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1707696000

{
  "error": {
    "code": 429,
    "message": "Rate limit exceeded. Resets at 2026-02-12T00:00:00Z"
  }
}

Rate Limit Headers

Every API response includes rate limit headers so you can track your usage programmatically and avoid hitting limits:

Best Practices

Check X-RateLimit-Remaining before making requests in batch workflows. If you receive a 429, respect the Retry-After header rather than retrying immediately. For high-volume use cases, upgrade to the Pro plan for 1,000 daily requests.

Account

Returns your account details including plan tier, limits, and subscription status.

Error Codes

Agent Integration

Clawthor ships with a SKILL.md file for OpenClaw/Clawbot integration. Agents can discover and use Clawthor models automatically.

SKILL.md is a machine-readable manifest that tells AI agents what Clawthor can do. When an agent like Clawbot encounters a writing task, it reads the SKILL.md to discover available models and automatically selects the best one for the job. The manifest includes model IDs, category mappings, prompt templates, and authentication instructions — everything an agent needs to integrate without human setup.

Quick Start for Agents

# Install the Clawthor skill
export CLAWTHOR_API_KEY="ck_live_..."

# Generate text
curl -X POST https://clawthor.xyz/api/v1/generate \
  -H "Authorization: Bearer $CLAWTHOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"tweet-v1","prompt":"Write a viral tweet about our new staking vault"}'

See the SKILL.md file in the Clawthor GitHub repo for full agent integration details.