API Documentation
Early accessThe developer API is in early access (coming soon) and not yet generally available: it is turned on account by account. When it is on for you, call every model from OpenAI, Anthropic, Google and xAI from your server through one endpoint, https://chattermate.ai/api/v1, in the format your code already uses: the Responses API, OpenAI Chat Completions or Anthropic Messages. Existing SDK code works by changing two settings: the base URL and the API key. Test keys are free and return mock replies; live keys are enabled separately.
Authentication
Send your API key as Authorization: Bearer cm_test_... (the OpenAI SDKs do this for you; X-API-Key also works). Create keys in Settings โ API Keys. A key is shown once; ChatterMate.Ai keeps only a one-way hash. Start with a test key (cm_test_): it returns realistic mock replies and is never charged. Switch to a live key (cm_live_) when live access is on for your account; until then live requests return 403 account_restricted.
Server-side only
Requests from a browser (with an Origin header) get 403 browser_origin_blocked. Keep the key in a server secret.
Test keys first
cm_test_ keys work on every /api/v1 endpoint, cost nothing and give stable output for CI.
Limits you control
Per-key requests and tokens per minute, monthly spend caps, IP allowlists and expiry.
Quick start
POST /api/v1/responses takes the OpenAI Responses request format. Each example makes one plain call and one streaming call. Add "stream": true to get Server-Sent Events and print each response.output_text.delta as it arrives.
export CHATTERMATE_API_KEY="cm_test_..." # server-side only; never commit it
export CHATTERMATE_BASE_URL="https://chattermate.ai/api/v1"
# 1. One reply (JSON)
curl "$CHATTERMATE_BASE_URL/responses" \
-H "Authorization: Bearer $CHATTERMATE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "cm/api-flash", "input": "Write a one-line welcome message for my app."}'
# 2. Stream the reply (Server-Sent Events)
curl -N "$CHATTERMATE_BASE_URL/responses" \
-H "Authorization: Bearer $CHATTERMATE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "cm/api-flash", "input": "Tell me a short story.", "stream": true}'
# Each event is one "event:" line and one "data:" line, for example:
# event: response.output_text.delta
# data: {"type":"response.output_text.delta","sequence_number":4,"item_id":"msg_...","output_index":0,"content_index":0,"delta":"Once upon","logprobs":[]}Streaming events
Events arrive in this order. Every event has a type and an increasing sequence_number; ChatterMate.Ai adds no custom event types. While a model thinks, the stream sends : keep-alive comment lines that SDKs ignore.
| Event | Meaning |
|---|---|
| response.created | The response started (status in_progress). Has the response id. |
| response.in_progress | Sent right after created. |
| response.output_item.added | A new output item (a message or a function_call) begins. |
| response.content_part.added | A text part of the message begins. |
| response.output_text.delta | The next piece of text. Append delta to what you have. Sent many times. |
| response.output_text.done | The full text of that part. |
| response.function_call_arguments.delta / .done | Arguments of a function call, when you send tools. |
| response.content_part.done / response.output_item.done | The part or item is complete. |
| response.completed | Finished. response.usage and metadata.cm_charge_credits hold the usage and cost. |
| response.incomplete | Stopped early: incomplete_details.reason is max_output_tokens or content_filter. |
| response.failed | Failed: response.error.code says why (for example partial_output_failure). |
Every response has a metadata.cm_charge_credits (what it cost, in Credits; always "0" on test keys), cm_served_model and cm_mode_version. Only call ChatterMate.Ai from your backend; your web page calls your own route.
API formats
The same models, modes, billing, limits, logs and test keys sit behind three request formats. Pick the one your code or framework already speaks; nothing else changes. Responses is the most complete and the one new code should use.
| Endpoint | Format | Works with |
|---|---|---|
| POST /api/v1/responses | OpenAI Responses (recommended) | OpenAI SDK client.responses; stored conversations, quotes, idempotent retries |
| POST /api/v1/chat/completions | OpenAI Chat Completions | OpenAI SDK chat.completions, LangChain, LlamaIndex, Vercel AI SDK and most tools |
| POST /api/v1/messages | Anthropic Messages | Anthropic SDK client.messages, Claude-based agents |
# pip install openai
import os
from openai import OpenAI
client = OpenAI(base_url="https://chattermate.ai/api/v1", api_key=os.environ["CHATTERMATE_API_KEY"])
reply = client.chat.completions.create(
model="cm/api-flash",
messages=[
{"role": "system", "content": "You are a concise assistant."},
{"role": "user", "content": "Give me three names for a coffee shop."},
],
)
print(reply.choices[0].message.content)
# Streaming: the last chunk carries usage and has no choices.
stream = client.chat.completions.create(
model="cm/api-flash",
messages=[{"role": "user", "content": "Write a short poem about rain."}],
stream=True,
stream_options={"include_usage": True},
)
for chunk in stream:
if chunk.choices:
print(chunk.choices[0].delta.content or "", end="", flush=True)curl https://chattermate.ai/api/v1/chat/completions \
-H "Authorization: Bearer $CHATTERMATE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"cm/api-flash","messages":[{"role":"user","content":"Hello"}]}'What each format supports
| Feature | Chat Completions | Anthropic Messages |
|---|---|---|
| Text, system prompts, images (data URLs) | Yes | Yes |
| Streaming | Yes, chat.completion.chunk | Yes, Anthropic stream events |
| Function / tool calling | Yes, function tools | Yes, client tools |
| JSON output | response_format json_object / json_schema | Use a tool or ask for JSON |
| Reasoning | reasoning_effort | thinking.budget_tokens |
| Group turns in Sessions | metadata.cm_session | metadata.cm_session |
| Not supported | n > 1, stop, logprobs, audio | top_k, stop_sequences, server tools |
- Both formats are stateless: send the whole conversation each time. For server-side history use
previous_response_idon/api/v1/responses. - Errors keep each format's own shape (
{"error": {...}}for OpenAI,{"type": "error", ...}for Anthropic), so SDK exceptions and retries work unchanged. The HTTP status and theX-Request-Idheader are the same on all three. - Logs show which format each request used. Rate limits, spend caps and trust tiers count all three together.
- The older
/api/chat/streamendpoint is for the signed-in web app only. API keys sent there get410 legacy_endpoint_retired.
Models and modes
The model field takes a ChatterMate.Ai mode such as cm/api-flash or cm/api-smart (ChatterMate.Ai picks a healthy model and fails over before any text is sent), or one pinned vendor model written as provider/model-id, for example anthropic/... or openai/... (exactly that model, no failover, its own price). Copy ids from the list; bare vendor ids return 404 model_not_found.
curl "https://chattermate.ai/api/v1/models" \
-H "Authorization: Bearer $CHATTERMATE_API_KEY"Prices for every mode and model, in Credits per 1M tokens, are on the API pricing page and at GET /api/v1/pricing (no key needed, 60 requests a minute per address, cacheable).
Conversations (multi-turn)
Pass the previous response's id as previous_response_id and ChatterMate.Ai adds the earlier turns for you. This works for stored responses (store is true by default) of the same account and key type. Send instructions again on each turn; earlier turns count toward the context limit and are billed as input.
first = client.responses.create(model="cm/api-flash", input="My name is Ada.")
second = client.responses.create(
model="cm/api-flash",
input="What is my name?",
previous_response_id=first.id,
)
print(second.output_text)
client.responses.retrieve(first.id) # the stored Response object
client.responses.delete(first.id) # {"id": ..., "object": "response.deleted", "deleted": true}Send "store": false for requests whose content should never be kept (they can't be retrieved or continued). Long jobs can run with background: true and be polled, cancelled or resumed with GET /api/v1/responses/{id}.
Check the price before sending
POST /api/v1/responses/quote takes the same body as a real request and returns the most it can cost (the amount held while it runs). It's free: nothing is sent to a model. You pay for actual usage, which is never more than max_charge. Lower max_output_tokens to lower the hold. To count tokens only, use POST /api/v1/responses/input_tokens.
curl "https://chattermate.ai/api/v1/responses/quote" \
-H "Authorization: Bearer $CHATTERMATE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "cm/api-flash", "input": "Write a short poem about autumn.", "max_output_tokens": 300}'
# {"object": "response.quote", "model": "cm/api-flash", "input_tokens": 9, "max_output_tokens": 300,
# "reasoning_reserve_tokens": 4096, "max_charge": "2.19854",
# "breakdown": {"input": "0.00054", "output": "0.15", "reasoning": "2.048"}, "minimum_applied": false,
# "currency": "credits", "prices": {"unit": "per_1m_tokens", ...}, "test_mode": true}
# Numbers are illustrative. 1 Credit = $0.01.Errors
Errors use one JSON shape. param names the field to fix, limit_source names the limit or budget that refused the request, and request_id matches the x-request-id header; quote it when you contact support. The OpenAI SDKs raise their usual exceptions and unwrap the envelope: err.code holds the code below (Python err.body and Node err.error are the error object).
{"error": {"type": "not_found_error", "code": "model_not_found",
"message": "The model 'acme/old-model' does not exist or is not available to this key. List models with GET /api/v1/models.",
"param": "model", "limit_source": null, "request_id": "req_08cbe8be6c254f90abf2a5cd2f7c5f82"}}| HTTP | code | What to do |
|---|---|---|
| 400 | invalid_request_error, unsupported_parameter | Fix the field named in param. Unknown fields are rejected, never silently dropped. |
| 401 | invalid_api_key, key_expired | Check the key (mistyped, revoked or expired). Create or rotate a key. |
| 402 | insufficient_funds, spend_limit_reached | Add Credits, lower max_output_tokens, or raise the monthly cap named in limit_source. Nothing was charged. |
| 403 | account_restricted, insufficient_scope, mode_not_permitted, ip_not_allowed, browser_origin_blocked | Use a key that has access, call from your server, or ask support. Don't retry unchanged. |
| 404 | model_not_found, response_not_found | Use an id from GET /api/v1/models; only stored responses (store: true) can be retrieved or continued. |
| 409 | idempotency_conflict | Same Idempotency-Key with a different body, or the first request is still running (Retry-After: 1). |
| 413 | context_too_large | Shorten the input or the conversation history. |
| 429 | rate_limit_exceeded | Wait Retry-After seconds. limit_source: key_rpm, key_tpm, in_flight_budget or ip_rpm. |
| 500 | internal_error | Retry, ideally with the same Idempotency-Key. |
| 503 | control_plane_stale, pricing_unavailable, no_eligible_model, api_wallet_unavailable | Retry shortly with backoff. Nothing was charged. |
A stream that already started can still end with response.failed (partial_output_failure: retry as a new request; you pay only for what was produced) or response.incomplete. The developer guide's errors reference (ERRORS.md) lists every code, when it happens and whether to retry.
Rate limits and spend caps
Every key has a requests-per-minute limit (default 60), a tokens-per-minute limit (default 1,000,000; a request counts its input plus max_output_tokens) and an optional monthly cap in Credits. Accounts and projects can have monthly caps too. Set them in Settings โ API Keys or the Developer Console.
| Header | Example | Meaning |
|---|---|---|
| x-ratelimit-limit-requests | 60 | Requests per minute for this key |
| x-ratelimit-remaining-requests | 59 | Requests left in the current window |
| x-ratelimit-reset-requests | 1m0s | Until the window has room again (250ms, 13s, 6m1s) |
| x-ratelimit-limit-tokens | 1000000 | Tokens per minute for this key |
| x-ratelimit-remaining-tokens | 998976 | Tokens left in the bucket |
| x-ratelimit-reset-tokens | 62ms | Until the bucket is full again |
| Retry-After | 3 | Seconds to wait (on 429 and some 409 responses) |
| x-request-id | req_... | Quote it when you contact support |
| ChatterMate-Version | 2026-11-01 | API behavior version that served the request |
| Idempotent-Replayed | true | A retry with the same Idempotency-Key returned the stored result |
When a limit is reached
Per-minute limits return 429 rate_limit_exceeded with Retry-After (limit_source key_rpm or key_tpm). A monthly cap returns 402 spend_limit_reached (key_budget, project_budget or account_budget) until you raise it or the UTC month ends. Nothing is charged.
Safe retries
Send an Idempotency-Key header (1-255 characters). A retry with the same key and body returns the original response for 24 hours, with no second charge.
๐ก๏ธ Account trust tiers (live keys)
Live calls also have account-wide limits that grow with your payment history and account age. By default a new account starts at T0 ($25 a day, 60 requests a minute, 2 requests in flight, the Flash and Smart modes); T1 unlocks at $10 paid and 7 days ($250 a day, 500 a minute) and T2 at $250 paid and 30 days ($2,500 a day, 3,000 a minute). Larger limits are available after a review. Your current tier and what unlocks the next one are in Developer Console โ Usage. Over a tier limit you get 429 rate_limit_exceeded, 403 tier_mode_not_allowed or 402 spend_limit_reached with limit_source trust_tier or trust_tier_daily. Test keys are never limited by tier.
๐งพ What failed or refused requests cost
Nothing when no model could answer or the provider failed before any output. Actual usage when you cancel or a stream breaks after output started. A refusal by the provider's content filter is billed for the input only.
Model deprecations
On the Responses API (/api/v1/responses) you can use a mode such as cm/api-flash or pin one vendor model as provider/model-id. When a pinned model is being retired, every response for it carries these headers, and GET /api/v1/models shows deprecated_at and sunset_at.
Deprecation@<unix seconds> when the model was marked deprecated (RFC 9745)SunsetHTTP date after which the model stops answering (RFC 8594)LinkThis page, with rel="deprecation"After the sunset date, requests return 404 model_not_found. Move to a newer model from GET /api/v1/models, or to a mode, which switches models for you and never sunsets out from under your app.