Skip to main content

API Documentation

Early access

The 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.

EventMeaning
response.createdThe response started (status in_progress). Has the response id.
response.in_progressSent right after created.
response.output_item.addedA new output item (a message or a function_call) begins.
response.content_part.addedA text part of the message begins.
response.output_text.deltaThe next piece of text. Append delta to what you have. Sent many times.
response.output_text.doneThe full text of that part.
response.function_call_arguments.delta / .doneArguments of a function call, when you send tools.
response.content_part.done / response.output_item.doneThe part or item is complete.
response.completedFinished. response.usage and metadata.cm_charge_credits hold the usage and cost.
response.incompleteStopped early: incomplete_details.reason is max_output_tokens or content_filter.
response.failedFailed: 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.

EndpointFormatWorks with
POST /api/v1/responsesOpenAI Responses (recommended)OpenAI SDK client.responses; stored conversations, quotes, idempotent retries
POST /api/v1/chat/completionsOpenAI Chat CompletionsOpenAI SDK chat.completions, LangChain, LlamaIndex, Vercel AI SDK and most tools
POST /api/v1/messagesAnthropic MessagesAnthropic 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

FeatureChat CompletionsAnthropic Messages
Text, system prompts, images (data URLs)YesYes
StreamingYes, chat.completion.chunkYes, Anthropic stream events
Function / tool callingYes, function toolsYes, client tools
JSON outputresponse_format json_object / json_schemaUse a tool or ask for JSON
Reasoningreasoning_effortthinking.budget_tokens
Group turns in Sessionsmetadata.cm_sessionmetadata.cm_session
Not supportedn > 1, stop, logprobs, audiotop_k, stop_sequences, server tools
  • Both formats are stateless: send the whole conversation each time. For server-side history use previous_response_id on /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 the X-Request-Id header 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/stream endpoint is for the signed-in web app only. API keys sent there get 410 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"}}
HTTPcodeWhat to do
400invalid_request_error, unsupported_parameterFix the field named in param. Unknown fields are rejected, never silently dropped.
401invalid_api_key, key_expiredCheck the key (mistyped, revoked or expired). Create or rotate a key.
402insufficient_funds, spend_limit_reachedAdd Credits, lower max_output_tokens, or raise the monthly cap named in limit_source. Nothing was charged.
403account_restricted, insufficient_scope, mode_not_permitted, ip_not_allowed, browser_origin_blockedUse a key that has access, call from your server, or ask support. Don't retry unchanged.
404model_not_found, response_not_foundUse an id from GET /api/v1/models; only stored responses (store: true) can be retrieved or continued.
409idempotency_conflictSame Idempotency-Key with a different body, or the first request is still running (Retry-After: 1).
413context_too_largeShorten the input or the conversation history.
429rate_limit_exceededWait Retry-After seconds. limit_source: key_rpm, key_tpm, in_flight_budget or ip_rpm.
500internal_errorRetry, ideally with the same Idempotency-Key.
503control_plane_stale, pricing_unavailable, no_eligible_model, api_wallet_unavailableRetry 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.

HeaderExampleMeaning
x-ratelimit-limit-requests60Requests per minute for this key
x-ratelimit-remaining-requests59Requests left in the current window
x-ratelimit-reset-requests1m0sUntil the window has room again (250ms, 13s, 6m1s)
x-ratelimit-limit-tokens1000000Tokens per minute for this key
x-ratelimit-remaining-tokens998976Tokens left in the bucket
x-ratelimit-reset-tokens62msUntil the bucket is full again
Retry-After3Seconds to wait (on 429 and some 409 responses)
x-request-idreq_...Quote it when you contact support
ChatterMate-Version2026-11-01API behavior version that served the request
Idempotent-ReplayedtrueA 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.

ChatterMate.Ai API โ€” questions? Open a conversation at chattermate.ai