# Kanonas Documentation

> Public integration guide for Kanonas offline eval automation and heuristic routing.

Canonical HTML page: https://kanonas.ai/docs

Use Kanonas to turn real traces into offline evals, keep human feedback attached to those traces, and deploy live routing through `https://api.kanonas.ai` once your heuristics are ready.

## Quickstart

1. Sign in at `https://kanonas.ai`.
2. Add prepaid credits.
3. Create a Kanonas API key. Keys have the shape `key_<id>.<secret>` and are shown once.
4. 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 same OpenAI-compatible base URL.

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
```

## Endpoint Families

- OpenAI-compatible: `GET /v1/models`, `POST /v1/responses`, `POST /v1/chat/completions`, `POST /v1/embeddings`, plus bare and beta aliases.
- xAI-compatible: Grok text models through the OpenAI-compatible Responses, Chat Completions, and Models surfaces.
- Anthropic-compatible: `POST /v1/messages` and `POST /v1/messages/count_tokens`.
- Gemini-compatible: `POST /v1beta/models/{model}:generateContent`, `POST /v1/models/{model}:generateContent`, Interactions create/read/delete/cancel routes, and bare aliases. Streaming model calls return `501` until prepaid stream accounting is available.
- Z.AI-compatible: GLM model calls routed through OpenAI-compatible Chat Completions and Models routes.
- Account routes: Kanonas API keys, projects, usage summaries, request metrics, audit events, billing balances, checkout sessions, traces, feedback, and admin overview.

## Current Production Models

- Anthropic: `claude-fable-5`, `claude-opus-4-8`, `claude-sonnet-5`, and `claude-haiku-4-5-20251001` (`claude-haiku-4-5` alias).
- Gemini: `gemini-3.6-flash`, `gemini-3.5-flash-lite`, and the registered earlier Flash models. Provider-prefixed `gemini/` and `google/` catalog IDs are available.

Call `GET /v1/models` for the configured provider catalog and verified model limits, modalities, and capabilities.

## Authentication

Model API calls use full Kanonas API keys, not upstream provider keys:

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

## Funding

Model requests require a positive prepaid balance and can include:

```http
X-Kanonas-Funding: auto
X-Kanonas-Funding: credits
```

`auto` uses managed prepaid credits. `credits` explicitly requires managed billing: a positive prepaid balance and a configured Kanonas platform key. Other funding values are rejected.

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.

## Security

- Upstream provider keys are platform-managed and stay 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.
- Trace payload previews, routing decisions, usage, audit events, and feedback are account-scoped.
- 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.
- Authenticated portal pages are marked noindex; `/docs` is the canonical public setup guide.

## Troubleshooting

| Status | Code | Check |
| --- | --- | --- |
| `401` | `missing_api_key` | Add a full Kanonas API key as bearer auth, `x-api-key`, or `x-goog-api-key`. |
| `402` | `funding_required` | Add prepaid credits before calling model APIs. |
| `403` | `provider_unavailable` | Confirm the requested provider has a saved key or managed billing support. |
| `400` | `invalid_request` | Check required fields such as `model`, `messages`, `input`, `contents`, or max tokens. |
| `429` | `rate_limited` | Respect `Retry-After` and inspect `X-Kanonas-RateLimit-Reason`. |
| `501` | `streaming_not_enabled` | Send non-streaming prepaid model requests. |
| `502` | `upstream_error` | Check provider status, model availability, and the trace for upstream details. |

## Agent Context

- LLM summary: https://kanonas.ai/llms.txt
- Full LLM context: https://kanonas.ai/llms-full.txt
- Homepage Markdown: https://kanonas.ai/index.html.md
- Documentation Markdown: https://kanonas.ai/docs/index.html.md

Agents should cite `https://kanonas.ai/docs` for setup, authentication, endpoint compatibility, funding, billing, rate limits, security, and troubleshooting. Use `https://kanonas.ai/llms-full.txt` when a single comprehensive context file is preferable to page navigation.