# Kanonas LLM Context > Kanonas helps teams outsource evals by automating offline evals on real traces, capturing thumbs-up and thumbs-down feedback, and shipping heuristic routing that improves quality and cost for the team's own use case. Kanonas is built for teams operating AI in production. It turns trace data into repeatable eval runs, combines human feedback with judge outputs, and gives teams a routing layer they can tune to their own quality and cost boundary. Live traffic can run through `https://api.kanonas.ai`, but the core product story is the eval loop that decides what should ship. ## Canonical URLs - Website: https://kanonas.ai/ - Documentation: https://kanonas.ai/docs - Privacy Policy: https://kanonas.ai/privacy - Terms of Service: https://kanonas.ai/terms - LLM summary: https://kanonas.ai/llms.txt - LLM full context: https://kanonas.ai/llms-full.txt - Homepage Markdown: https://kanonas.ai/index.html.md - Documentation Markdown: https://kanonas.ai/docs/index.html.md - Sitemap: https://kanonas.ai/sitemap.xml - Robots: https://kanonas.ai/robots.txt - API gateway: https://api.kanonas.ai - API health check: https://api.kanonas.ai/health - API service acknowledgment: https://api.kanonas.ai/ - API acknowledgment alias: https://api.kanonas.ai/ack ## Product Summary Kanonas is for teams that want to make routing decisions from evidence instead of intuition. A user signs in, creates a Kanonas API key, reviews traces, runs offline evals, and promotes heuristics only after the results improve the team's own quality and cost boundary. Live model requests can keep familiar request shapes while Kanonas records the trace evidence used to guide those routing changes. Primary provider families: - OpenAI and OpenAI-compatible clients. - xAI text models through OpenAI-compatible request shapes. - Anthropic Messages-compatible clients. - Gemini-native clients. - Z.AI GLM models through OpenAI-compatible request shapes. - LiteLLM clients that route provider-prefixed model IDs through one `completion()` interface. Primary authenticated portal areas: - Console: readiness and copyable examples. - Settings: Google sign-in account controls, Kanonas API keys, and projects. - Billing: prepaid balance, top-ups, spend, and managed billing coverage. - Traces: model-call records with payload previews, route decisions, provider attempts, metrics, labels, and feedback. - Admin: allowlisted operations dashboard for gateway health, response codes, recent errors, user activity, and model usage. ## Quickstart 1. Sign in at `https://kanonas.ai`. 2. Add prepaid credits in Billing. 3. Create a Kanonas API key. Keys have the shape `key_.` and are shown once. 4. Optionally create a Project, then create a project-scoped API key so gateway calls carry `project_id`. 5. Point the existing SDK or client at Kanonas. OpenAI-compatible clients: ```bash export OPENAI_BASE_URL=https://api.kanonas.ai/v1 export OPENAI_API_KEY=key_your_id.your_secret ``` xAI Grok text models use the OpenAI-compatible base URL. Kanonas disables xAI upstream response storage by default: ```bash curl "$OPENAI_BASE_URL/responses" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Kanonas-Funding: credits" \ -d '{"model":"grok-4.5","input":"Say ack","store":false}' ``` Anthropic-compatible clients: ```bash export ANTHROPIC_BASE_URL=https://api.kanonas.ai export ANTHROPIC_API_KEY=key_your_id.your_secret ``` Gemini-compatible clients: ```bash export GEMINI_BASE_URL=https://api.kanonas.ai export GEMINI_API_KEY=key_your_id.your_secret ``` Z.AI GLM models use the OpenAI-compatible base URL: ```bash curl "$OPENAI_BASE_URL/chat/completions" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"zai/glm-4.5","messages":[{"role":"user","content":"Say ack"}]}' ``` ## Authentication Model API calls use full Kanonas API keys, not upstream provider keys. Kanonas accepts the auth style that matches the request shape: - OpenAI-compatible: `Authorization: Bearer key_your_id.your_secret` - Anthropic-compatible: `x-api-key: key_your_id.your_secret` or bearer auth - Gemini-compatible: `x-goog-api-key: key_your_id.your_secret` or bearer auth Kanonas API keys are shown once and stored as hashes. Upstream provider credentials are platform-managed and never sent by clients. If a user loses a full Kanonas API key value, they should create a new key. Portal account-management routes generally require Firebase-authenticated signed-in users. Model routes authenticate with Kanonas API keys. Stripe webhook routes authenticate with Stripe signatures. ## Funding And Billing Kanonas model calls are prepaid. The account that owns the Kanonas API key must have a positive prepaid balance before dispatch, and successful non-streaming calls debit the estimated response cost from that balance. A request can include: ```http X-Kanonas-Funding: auto X-Kanonas-Funding: credits ``` `auto` or an omitted header uses prepaid credits. `credits` explicitly requires prepaid credits and a configured Kanonas platform key for the provider. Other funding values are rejected. Prepaid credits are funded through Stripe Checkout: - `POST /v1/billing/checkout-sessions` creates a hosted Checkout Session with Stripe promotion-code entry enabled. - `POST /v1/billing/stripe/webhook` credits paid or no-payment-required USD Checkout Sessions. - Ledger credits are idempotent by Checkout Session ID. - Usage debits are recorded after model calls when prepaid credits fund the request. Prepaid top-ups add a 5% platform fee at Stripe Checkout. A `$50.00` top-up adds `$50.00` of account credits and charges `$52.50` before any Stripe promotion code. Project-scoped requests can also include: ```http X-Kanonas-Project-Id: proj_abc123 ``` ## Projects Projects provide granular attribution for API keys, usage, traces, request metrics, and future billing boundaries. Signed-in users can create projects with `POST /v1/projects`, list them with `GET /v1/projects`, delete them with `DELETE /v1/projects/{project_id}`, and create project-scoped API keys with `POST /v1/api-keys` by including `project_id`. Requests made with a project-scoped key record `project_id` on: - Usage events. - Request metrics. - Model-call traces. - Project usage summaries. - Response headers when available. Project usage can be read with `GET /v1/projects/{project_id}/usage`. Deleting a project revokes every API key scoped to that project. ## Public API Surface Health and service acknowledgments: - `GET /`: Service acknowledgment. - `GET /ack`: Service acknowledgment alias. - `GET /health`: Health check. - `GET /healthz`: Health check alias. Gateway model catalog: - `GET /models`: Model list alias for clients using the API host. - `GET /v1/models`: Models available through configured platform provider credentials. - `GET /v1beta/openai/models`: OpenAI beta compatibility alias. OpenAI-compatible model routes: - `POST /v1/responses`: OpenAI Responses-shaped requests. - `POST /responses`: Bare Responses alias. - `POST /v1beta/openai/responses`: OpenAI beta Responses alias. - `POST /v1/chat/completions`: OpenAI Chat Completions-shaped requests, including Z.AI GLM routing. - `POST /chat/completions`: Bare Chat Completions alias. - `POST /v1beta/openai/chat/completions`: OpenAI beta Chat Completions alias. - `POST /v1/embeddings`: OpenAI Embeddings-shaped requests. - `POST /embeddings`: Bare Embeddings alias. xAI-compatible model routes: - `POST /v1/responses`: xAI Grok text requests through the OpenAI-compatible Responses surface. - `POST /v1/chat/completions`: xAI Grok chat-completions compatibility route. - `GET /v1/models`: curated xAI text model list when the platform xAI credential is configured. Anthropic-compatible routes: - `POST /v1/messages`: Anthropic Messages-shaped requests. - `POST /v1/messages/count_tokens`: Anthropic token counting helper. Gemini-compatible routes: - `POST /models/{model}:generateContent`: Generate Content alias. - `POST /v1beta/models/{model}:generateContent`: Gemini v1beta Generate Content. - `POST /v1/models/{model}:generateContent`: Gemini v1 Generate Content. - `POST /models/{model}:streamGenerateContent`: returns `501` until prepaid stream accounting is available. - `POST /v1beta/models/{model}:streamGenerateContent`: returns `501` until prepaid stream accounting is available. - `POST /v1/models/{model}:streamGenerateContent`: returns `501` until prepaid stream accounting is available. - `GET /models/{model}:cachedContents`: LiteLLM cache lookup alias. - `GET /v1beta/models/{model}:cachedContents`: Gemini v1beta cache lookup compatibility. - `GET /v1/models/{model}:cachedContents`: Gemini v1 cache lookup compatibility. - `POST /models/{model}:cachedContents`: LiteLLM cache setup alias. - `POST /cachedContents`: explicit context cache creation alias. - `POST /v1beta/cachedContents`: Gemini v1beta explicit context cache creation. - `GET /v1beta/cachedContents/{cached_content}`: Read a cached content resource. - `PATCH /v1beta/cachedContents/{cached_content}`: Update a cached content resource. - `DELETE /v1beta/cachedContents/{cached_content}`: Delete a cached content resource. - `POST /interactions`: Gemini Interactions alias. - `POST /v1beta/interactions`: Gemini v1beta Interactions. - `POST /v1/interactions`: Gemini v1 Interactions. - `GET /interactions/{interaction_id}`: Read an interaction resource alias. - `GET /v1beta/interactions/{interaction_id}`: Read a v1beta interaction resource. - `GET /v1/interactions/{interaction_id}`: Read a v1 interaction resource. - `DELETE /interactions/{interaction_id}`: Delete an interaction resource alias. - `DELETE /v1beta/interactions/{interaction_id}`: Delete a v1beta interaction resource. - `DELETE /v1/interactions/{interaction_id}`: Delete a v1 interaction resource. - `POST /interactions/{interaction_id}/cancel`: Cancel an interaction resource alias. - `POST /v1beta/interactions/{interaction_id}/cancel`: Cancel a v1beta interaction resource. - `POST /v1/interactions/{interaction_id}/cancel`: Cancel a v1 interaction resource. Portal account routes: - `GET /v1/me`: Inspect the authenticated account context. - `GET /v1/api-keys`: List Kanonas API key metadata. - `POST /v1/api-keys`: Create a Kanonas API key, optionally scoped to a project. - `DELETE /v1/api-keys/{key_id}`: Revoke a Kanonas API key. - `GET /v1/projects`: List projects. - `POST /v1/projects`: Create a project. - `DELETE /v1/projects/{project_id}`: Delete a project and revoke scoped API keys. - `GET /v1/projects/{project_id}/usage`: Read project usage. - `GET /v1/usage`: Account usage summary. - `GET /v1/usage/summary`: Usage summary alias. - `GET /usage/summary`: Bare usage summary alias. - `GET /v1/audit-events`: Recent account audit events for management-plane changes. - `GET /v1/billing/balance`: Prepaid balance and funding policy summary. - `POST /v1/billing/checkout-sessions`: Create a Stripe Checkout Session for credits plus the platform fee. - `POST /v1/billing/stripe/webhook`: Stripe-signed billing webhook. - `GET /v1/model-calls`: List recent model-call traces. - `GET /v1/model-calls/{call_id}`: Read one model-call trace. - `POST /v1/model-calls/{call_id}/feedback`: Save human feedback on a model-call trace. - `GET /v1/request-metrics`: List recent account gateway requests and failed request statuses. - `GET /v1/admin/overview`: Allowlisted admin operations dashboard payload. ## Provider And Model Behavior OpenAI-compatible clients use `https://api.kanonas.ai/v1` and can call Responses, Chat Completions, Embeddings, and Models. Bare aliases such as `/responses` and `/chat/completions` are accepted for clients configured with the API host instead of the `/v1` root. xAI Grok text models use the same OpenAI-compatible Kanonas base URL. Raw Grok IDs such as `grok-4.5` are normalized to `xai/grok-4.5`. Kanonas forces `store=false` on xAI Responses requests and rejects `previous_response_id` so upstream xAI conversation state is never persisted by default. Anthropic-compatible clients use `https://api.kanonas.ai` and call `/v1/messages` or `/v1/messages/count_tokens`. When the internal LiteLLM Proxy path is enabled, `/v1/messages` requests stay Anthropic-shaped through the proxy so LiteLLM can preserve content blocks, tools, and thinking/reasoning fields where supported. Anthropic streaming is supported through that proxy path and otherwise falls back to the legacy `501` behavior. Gemini-compatible clients use `https://api.kanonas.ai` and call Generate Content or Interactions routes. When the internal LiteLLM Proxy path is enabled, Generate Content and streaming Generate Content can route Gemini-shaped requests to Gemini or non-Gemini providers while returning Gemini-compatible responses. Gemini resource APIs such as cached contents and interactions remain direct Gemini pass-through compatibility paths. Z.AI GLM calls use the OpenAI-compatible Chat Completions and Models routes. Raw GLM model IDs such as `glm-4.5` are normalized to `zai/glm-4.5`. Model availability depends on configured platform provider credentials. Model dispatch also requires a positive prepaid account balance. Example model families include: - OpenAI frontier: `gpt-5.6`/`gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna` when the Kanonas OpenAI account has the required limited-preview entitlement. - OpenAI recent families: `gpt-5.5`, `gpt-5.5-pro`, `gpt-5.4`, `gpt-5.4-pro`, `gpt-5.4-mini`, `gpt-5.4-nano`, `gpt-4.1-mini`, `gpt-4o-mini`. Pro models require the Responses API; provider-prefixed OpenAI IDs are advertised by `GET /v1/models`. - xAI: `xai/grok-4.5`, plus raw `grok-4.5` on OpenAI-compatible routes. - Anthropic: `claude-fable-5`, `claude-opus-4-8`, `claude-sonnet-5`, `claude-haiku-4-5-20251001`, plus the official `claude-haiku-4-5` alias. - Gemini: `gemini-3.6-flash`, `gemini-3.5-flash-lite`, `gemini-3.5-flash`, `gemini-2.5-flash`, `gemini/gemini-3.1-flash-lite`, and their advertised `gemini/` or `google/` prefixes. - Z.AI: `zai/glm-5.2`, `zai/glm-4.5`, `zai/glm-4.5-air`. ## LiteLLM LiteLLM can call Kanonas as an API base for OpenAI, xAI, Anthropic, Gemini, and Z.AI model IDs. Use the Kanonas API key as `api_key`; use `https://api.kanonas.ai/v1` for OpenAI-compatible calls and `https://api.kanonas.ai` for provider-native Anthropic or Gemini routes when needed. Example: ```python from litellm import completion response = completion( model="openai/gpt-5.5", api_base="https://api.kanonas.ai/v1", api_key="key_your_id.your_secret", messages=[{"role": "user", "content": "Say ack"}], ) print(response.choices[0].message.content) ``` ## Usage Accounting Successful gateway calls record usage metadata tied to the authenticated account and, when applicable, the project. Usage summaries include account all-time views, provider views, funding-source views, and project views. Usage events can include: - Request count. - Account id and API key id. - Project id when a project-scoped key is used. - Endpoint and request shape. - Provider and model. - Input, output, total, cached, cache creation, and cache read token counts when available. - Estimated cost in USD or micros. - Funding source: `credits`. - Prepaid debit amount. - Request latency. - Optional caller-supplied `X-Kanonas-Trace-Id`. ## Observability And Traces Kanonas records model-call observability for non-streaming model requests. The Traces page shows recent gateway requests, failed request statuses, and model calls with request and response previews, metrics, route decisions, provider attempts, label source, heuristic labels, and human thumbs/comment feedback. Trace-related records can include: - Model call id. - Account id, API key id, and project id. - Caller-supplied trace id. - Request shape and endpoint. - Requested provider/model and used provider/model. - HTTP status and latency. - Token counts and estimated spend. - Funding source and prepaid debit. - Request and response payload previews or references. - Route decision metadata. - Provider attempts. - Human feedback and judge/evaluator output when available. Large payloads can be stored outside the relational record and summarized. Payload capture is bounded by configured maximum bytes, depth, fields, and string length. Trace payloads are behind authenticated account access. ## Streaming Streaming model calls return `501` today because prepaid usage debits rely on final response usage metadata. Provider-specific stream accounting must be added before streaming is reenabled. ## Rate Limits Kanonas model-route rate limits are intentionally sparse. Normal model usage is not shaped by blanket per-user quotas. The gateway returns `429` only when a request pattern creates a specific risk: - Very high account or API-key request volume that may indicate fraud, abuse, or a leaked Kanonas API key. - Prepaid-credit requests while the account balance is almost exhausted. Rate-limited responses include: ```http Retry-After: 37 X-Kanonas-RateLimit-Reason: prepaid_low_balance X-Kanonas-RateLimit-Limit: 6 X-Kanonas-RateLimit-Remaining: 0 X-Kanonas-RateLimit-Reset: 2026-06-28T12:01:00+00:00 ``` Known reason codes: - `outrageous_request_volume`: unusually high request volume. Wait, reduce concurrency, and rotate the Kanonas API key if it may be leaked. - `prepaid_low_balance`: credit-funded request while the prepaid balance is near zero. Add credits or reduce concurrent jobs. Clients should treat `429` as retryable, respect `Retry-After`, use exponential backoff with jitter, and avoid retry loops that ignore upstream provider limits. ## Error Checklist - `400`: Confirm required fields such as `model`, `input`, `messages`, `contents`, or provider-specific payload fields. - `401`: Include a valid Kanonas API key or signed-in Firebase token, depending on the route. - `402`: Add prepaid credits before calling model APIs. - `403`: The requested account route is forbidden for the signed-in user. - `429`: Respect `Retry-After` and inspect `X-Kanonas-RateLimit-Reason`. - `501`: Send non-streaming prepaid model requests. - `502`: The upstream provider or gateway returned an error. ## Security Security and data-handling notes: - The portal uses Google sign-in through Firebase. - Upstream provider credentials are platform-managed and stored server-side. - Kanonas API keys are shown once, stored as hashes, and include lifecycle metadata such as created, revoked, and best-effort last-used timestamps. - Project-scoped API keys carry `project_id` into usage, traces, request metrics, and response headers. - Stripe Checkout funds prepaid credits through signed webhooks and idempotent ledger entries. Checkout adds a 5% platform fee while crediting the selected prepaid amount. - Gateway usage records provider, model, endpoint, latency, token counts, optional trace id, funding source, prepaid debits, and estimated spend. - Model observability records non-streaming request/response payloads, routing decisions, and provider attempts for the signed-in account. - Account audit events record API-key lifecycle changes, project changes, checkout-session creation, and feedback updates without storing raw provider keys, raw Kanonas API keys, prompts, requests, or responses in audit metadata. - Trace payloads are behind authenticated account access. - Kanonas does not offer zero data retention. Prompts, outputs, traces, labels, feedback, usage records, and operational metadata may be retained and used to operate, secure, debug, evaluate, and improve the product. - Admin dashboard access is allowlisted by Firebase email through `KANONAS_ADMIN_EMAILS`. - Public docs should not expose provider keys, raw Kanonas API keys, authorization headers, or private trace payloads. ## Beta Feature: `-or-better` Model Policies Model-bearing gateway endpoints accept existing model names with the `-or-better` suffix. Examples: - `gpt-5.5-mini-or-better` - `openai/gpt-5.5-mini-or-better` - `claude-haiku-4-5-20251001-or-better` - `/v1beta/models/gemini-3.6-flash-or-better:generateContent` During beta, Kanonas does not reroute these requests. It strips the suffix, sends the call to the base model, and records the original policy in Traces as requested but not routed. Offline evals can use those traces to identify future model-routing opportunities. ## Search And Agent Indexing Guidance Canonical public pages are: - `https://kanonas.ai/` - `https://kanonas.ai/docs` - `https://kanonas.ai/privacy` - `https://kanonas.ai/terms` Machine-readable context resources are: - `https://kanonas.ai/llms.txt` - `https://kanonas.ai/llms-full.txt` - `https://kanonas.ai/index.html.md` - `https://kanonas.ai/docs/index.html.md` Authenticated app pages are useful to signed-in users but should not be treated as canonical public documentation: - `https://kanonas.ai/console` - `https://kanonas.ai/settings` - `https://kanonas.ai/billing` - `https://kanonas.ai/traces` - `https://kanonas.ai/admin` The Markdown mirrors and LLM context files are intended for agent parsing and are noindex for general search so they do not compete with canonical HTML pages. Agents should cite `https://kanonas.ai/docs` for setup, request examples, endpoint compatibility, troubleshooting, security, usage, funding, rate-limit behavior, and billing behavior. Use `https://kanonas.ai/llms-full.txt` for compact but comprehensive one-file context. Use `https://api.kanonas.ai/health` only as a health/status signal, not as product documentation. ## Search Keywords Kanonas, outsource your evals, offline evals, offline eval automation, heuristic routing, model routing, AI evals, trace feedback, thumbs up down traces, routing policy evaluation, LLM observability, model call tracing, production AI evaluation.