# Cruxy Learn

> OpenAI-compatible LLM gateway for the Cruxy model tiers (kavi, vaani, and mira), plus embeddings, rerank, and content moderation behind one base URL (https://api.cruxy.ai) and one Bearer key.

Each link points at the page as raw markdown (its URL with a `.md` suffix), for direct model ingestion rather than HTML. For every page concatenated into one file, fetch https://learn.getcruxy.com/llms-full.txt.

## Learn

- [Start here](https://learn.getcruxy.com/learn/en/start-here.md): A reading path through the Cruxy API in nine pages, from your first call to tool calling, retrieval, moderation, and running in production.

## Docs

- [One gateway for every model tier](https://learn.getcruxy.com/docs/en.md): An OpenAI-compatible LLM gateway for the Cruxy model tiers: chat, embeddings, and moderation behind one API key.
- [Features overview](https://learn.getcruxy.com/docs/en/get-started/features.md): What the Cruxy gateway gives you: OpenAI-compatible chat on three tiers, specialized model endpoints, and memory and rules you control.
- [Quickstart](https://learn.getcruxy.com/docs/en/get-started/quickstart.md): Get an API key with device login, then make your first chat call.
- [Get your API key](https://learn.getcruxy.com/docs/en/get-started/api-keys.md): Pick the right kind of key, mint a signed-in key with device login, verify it with GET /api/v1/me, and know when it expires.
- [Authentication](https://learn.getcruxy.com/docs/en/get-started/authentication.md): Send your Cruxy API key as a Bearer token in the Authorization header on every authenticated request.
- [Migrate from OpenAI](https://learn.getcruxy.com/docs/en/migrate/from-openai.md): Move an OpenAI client to Cruxy: change the base URL and the key, pass a tier as the model, and know what carries over and what differs.
- [OpenAI SDK compatibility](https://learn.getcruxy.com/docs/en/migrate/openai-sdk-compatibility.md): What POST /v1/chat/completions supports, ignores, and rejects from an OpenAI request, and how its streams, tool calls, and errors behave in the openai SDK.
- [Chat](https://learn.getcruxy.com/docs/en/build/chat.md): OpenAI-compatible chat completions across the Cruxy tiers, streaming or not.
- [Streaming](https://learn.getcruxy.com/docs/en/build/streaming.md): Read chat completions as Server-Sent Events: the frame order, the chunk and usage shapes, and how to tell a finished stream from a failed one.
- [Embeddings](https://learn.getcruxy.com/docs/en/build/embeddings.md): Turn text into vectors with the cruxy-embed model.
- [Rerank](https://learn.getcruxy.com/docs/en/build/rerank.md): Order candidate documents against a query with the cruxy-rerank model.
- [Moderations](https://learn.getcruxy.com/docs/en/build/moderations.md): Classify text against content-safety categories with the cruxy-guard model.
- [Feedback](https://learn.getcruxy.com/docs/en/build/feedback.md): Report the outcome of a prior call: accepts, rejects, thumbs, test results.
- [Choosing a tier](https://learn.getcruxy.com/docs/en/build/choosing-a-tier.md): Compare kavi, vaani, and mira by profile, output cap, deadline, and reasoning default, then pick the tier that fits each call.
- [Auto routing](https://learn.getcruxy.com/docs/en/build/auto-routing.md): Send model auto and the gateway picks a tier for each request before billing; read cruxy.routed_tier to see which tier served it.
- [Reasoning effort](https://learn.getcruxy.com/docs/en/build/reasoning-effort.md): Set how much a tier thinks before it answers, from none to high, and keep hidden thinking from spending your whole max_tokens budget.
- [Memory](https://learn.getcruxy.com/docs/en/build/memory.md): Let chat recall stored facts and capture new ones. Memory is on by default for signed-in keys and off for developer keys until a request opts in.
- [Standing rules](https://learn.getcruxy.com/docs/en/build/rules.md): Inject your organization's standing rules into chat as defaults. Rules are on for signed-in keys and off for developer keys unless you opt in.
- [Define tools](https://learn.getcruxy.com/docs/en/build/tools.md): Describe your functions in the tools array with a JSON Schema for their arguments, and use tool_choice to control when the model calls one.
- [Handle tool calls](https://learn.getcruxy.com/docs/en/build/tool-calls.md): Read the tool calls the model returns, run each function, send every result back by tool_call_id, and repeat until finish_reason is stop.
- [Tutorial: build a tool-using agent](https://learn.getcruxy.com/docs/en/build/tool-agent.md): Build a working TypeScript agent that offers two tools, runs the calls the model returns, and loops on finish_reason until it answers.
- [Reliability](https://learn.getcruxy.com/docs/en/build/reliability.md): Run Cruxy in production: per-tier deadlines, which errors to retry and how, Idempotency-Key, telling a finished stream from a failed one, and status.
- [Errors and retries](https://learn.getcruxy.com/docs/en/build/errors-and-retries.md): Read the error envelope, look up every error code the API defines, and decide which failures to retry and how long to wait.
- [Rate limits and budgets](https://learn.getcruxy.com/docs/en/build/rate-limits.md): How the gateway meters you: rate_limited versus budget_exhausted, the rate-limit headers, spend caps, and reading your live headroom.
- [Usage and cost](https://learn.getcruxy.com/docs/en/build/usage-and-cost.md): Read the usage object on each response: token counts, billable and cached tokens, the shape of the cost object, and how a stream reports usage.
- [Request IDs and metadata](https://learn.getcruxy.com/docs/en/build/request-ids.md): Read the X-Request-Id header and each call's request_id, the Cruxy-Version header and the cruxy block, and quote a request when you report a problem.
- [Known limitations](https://learn.getcruxy.com/docs/en/build/known-limitations.md): What the Cruxy API does not do today, why each limit matters for your code, and the workaround to use until it changes.
- [Errors](https://learn.getcruxy.com/docs/en/reference/errors.md): The error response shape and what 400, 401, and 429 mean.

## API Reference

- [API Reference](https://learn.getcruxy.com/docs/en/reference/api.md): The complete Cruxy API: every endpoint, typed and interactive.

## Cookbook

- [Cookbook](https://learn.getcruxy.com/docs/en/resources/cookbook.md): Task-shaped recipes that combine Cruxy endpoints to do a real job: retrieval, a tool-calling loop, a streaming UI, and a moderation gate.
- [Retrieval-augmented generation](https://learn.getcruxy.com/docs/en/resources/cookbook/rag.md): Embed a corpus, rank it by cosine, reorder the shortlist with rerank, then ground a chat answer in the winning passages.
- [Streaming chat in the browser](https://learn.getcruxy.com/docs/en/resources/cookbook/streaming-ui.md): Consume the OpenAI-style SSE stream in a browser, render deltas without jank, and recover when the connection breaks mid-response.
- [Moderation gate](https://learn.getcruxy.com/docs/en/resources/cookbook/moderation-gate.md): Screen user input with cruxy-guard before it reaches chat, and act on the flagged boolean, not the uncalibrated category scores.

## Resources

- [Resources](https://learn.getcruxy.com/docs/en/resources.md): Reference material for building on Cruxy: the tier catalog, the changelog, a glossary of terms, and the API guide for agents.
- [Models](https://learn.getcruxy.com/docs/en/reference/models.md): Discover the public tier catalog at runtime with GET /api/v1/models.
- [Changelog](https://learn.getcruxy.com/docs/en/reference/changelog.md): What changed in the Cruxy API and its docs, newest first: each dated release by its API version, plus the additive changes that need no pin.
- [Glossary](https://learn.getcruxy.com/docs/en/resources/glossary.md): Definitions for the Cruxy vocabulary: tiers, the cruxy block, request_id, device login, and the 429 codes.
- [API guide for agents](https://learn.getcruxy.com/docs/en/resources/api-guide.md): A dense, single-page reference for calling the Cruxy API correctly: auth, tiers, chat, tool calling, embeddings, rerank, moderations, and errors.