API Documentation

Use ChatterMate's streaming chat API directly from your applications. Authenticate with a long-lived API key — no OAuth flow required.

Authentication

All API requests require an X-API-Key header. Generate your key in Settings → API Keys. Keys are prefixed with cm_live_ and stored as SHA-256 hashes — the plaintext is shown only once on creation.

Secure

SHA-256 hashed. Never stored in plaintext.

Rate limited

Configurable per-key req/min limit.

User-scoped

Usage billed against your token balance.

POST /api/chat/stream

Streams a chat response via Server-Sent Events (SSE). Supports up to 4 models simultaneously.

Field	Type	Required	Description
prompt	string	Yes	The user's message
models	string[]	Yes	Model IDs to query. Max 4. E.g. ["gpt-4o", "claude-4.6-haiku"]
conversation_id	string \| null	No	Hex code of existing conversation to continue. Null for new.
system_prompt	string \| null	No	Override system prompt for this request.
web_search	boolean	No	Enable web search augmentation. Default: false.
attachment_ids	integer[]	No	IDs of previously uploaded files to include as context.
temperature	number	No	0.0–2.0. Default: model default.

Examples

curl -X POST https://chattermate.ai/api/chat/stream \
  -H "X-API-Key: cm_live_your_key_here" \
  -H "Content-Type: application/json" \
  --no-buffer \
  -d '{
    "prompt": "Explain quantum entanglement",
    "models": ["gpt-4o"],
    "conversation_id": null,
    "web_search": false
  }'

SSE Event Reference

The response stream is text/event-stream. Each line prefixed with data: contains a JSON object.

chunk

Streamed content token(s) from the model

{ "event": "chunk", "model": "gpt-4o", "content": "Quantum" }

model_complete

Model finished responding. Includes usage stats and optional RAG sources.

{ "event": "model_complete", "model": "gpt-4o", "tokens_used": 412, "rag_sources": [] }

balance_update

Sent after each model completes. Shows remaining token balance.

{ "event": "balance_update", "tokens_left": 48230, "credits_left": 5 }

error

Non-fatal error for a specific model (other models continue).

{ "event": "error", "model": "gpt-4o", "message": "Rate limit exceeded", "code": 429 }

balance_exhausted

Stream stopped mid-response — token balance ran out.

{ "event": "balance_exhausted", "tokens_left": 0 }

Rate Limits & Error Codes

HTTP Status Codes

200Stream started successfully

400Bad request (missing required fields)

401Invalid or revoked API key

402Token balance exhausted

429Rate limit exceeded — check Retry-After header

500Internal server error

Rate Limit Headers

X-API-KeyYour API key (request header)

Retry-AfterSeconds until rate limit resets (on 429)

X-Request-IDUnique request ID for debugging

Default rate limit: 60 req/min per key. Configurable up to 1000 req/min when creating your key.

Available Models

Fetch the current model list from GET /api/chat/models (no auth required). Use the id field in the models array.

curl https://chattermate.ai/api/chat/models

ChatterMate API — questions? Open a conversation at chattermate.ai