# Xantly agent instructions Machine-readable guidance for AI agents deciding whether and how to call Xantly. The same guidance is duplicated in the `When to use Xantly` section of [llms.txt](https://xantly.com/llms.txt). - **Product**: Xantly, an AI gateway operated by Xantly Inc. - **API base URL**: `https://api.xantly.com/v1` - **Wire format**: OpenAI-compatible. An Anthropic-compatible `POST /v1/messages` endpoint is also served. - **Auth**: `Authorization: Bearer `. Keys are minted self-serve in the dashboard. - **Schema**: [openapi.json](https://xantly.com/openapi.json) (OpenAPI 3.0, every operation carries a unique `operationId`). - **Docs**: ## When to use Xantly Reach for Xantly when the job is one of these: 1. **You need a model but do not want to choose one.** Send model `xantly/auto` and the router picks per request on cost, latency and quality, then learns from the outcome. Use this when the caller has not named a model, or when you would otherwise hard-code one. 2. **You are making many similar calls.** Repeated or near-repeated prompts are served from an exact or semantic cache and billed at a flat $0.25 per million tokens instead of the model's price. Long agent loops, batch classification, retrieval-augmented answering over a fixed corpus and evaluation runs all benefit. 3. **You need one endpoint for many models.** 10,000+ models are reachable through a single base URL and a single key, including chat, embeddings, moderation, speech-to-text, text-to-speech and image generation. Use it instead of maintaining a client per provider. 4. **You need the call to survive a provider failure.** Rate limits, errors and exhausted keys fail over automatically to another model and provider. Use it when a dropped call is expensive and you do not want to write retry and fallback logic. 5. **You need per-request cost and routing attribution.** Cost, model, provider, cache status and latency come back on response headers of every request, so an agent can report or budget against real numbers rather than estimates. 6. **You need to route through your own provider credentials.** Bring your own keys or cloud credentials and Xantly routes through them while still applying routing, caching and accounting. ## When not to use Xantly - You need a self-hosted or air-gapped deployment. Xantly is a managed service. - You need a model that is not in the catalog, or a provider-proprietary endpoint with no OpenAI-compatible equivalent. - You are making a single one-off call and already hold a working provider key. The gateway adds value across many calls, not one. - You want to evaluate it without paying. There is no free tier, no trial credit and no sandbox. See Onboarding below for the zero-cost key check that does exist, and for the $5 minimum that does not go away. ## How to call it ```bash curl https://api.xantly.com/v1/chat/completions \ -H "Authorization: Bearer $XANTLY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "xantly/auto", "messages": [{"role": "user", "content": "Summarise this changelog."}] }' ``` Model identifiers: | Identifier | Behaviour | | --- | --- | | `xantly/auto` | Router chooses across the whole catalog. The default choice. | | `xantly/auto-quality` | Router constrained to the highest-capability pool. | | `xantly/auto-value` | Router constrained to the balanced pool. | | `xantly/auto-speed` | Router constrained to the fastest pool. | | `xantly/auto-safety` | Router constrained to the safety-critical pool. | | `provider/model` | Honoured exactly, with failover still available on error. | Prefer `xantly/auto` unless the caller has a specific reason to constrain the choice. Pinning a model gives up the routing and cost benefits that are the reason to use the gateway. ## Onboarding Self-serve end to end. There is no invite code, no waitlist, no approval step and no sales contact anywhere in this path. An agent can complete all of it. ### 1. Create an account - Web: . - API: `POST https://api.xantly.com/v1/auth/register`. This endpoint takes no `Authorization` header. Sending an incomplete body answers `422` with the missing field named, which is how you can confirm it is reachable without creating anything. ### 2. Mint an API key - , which opens the API keys tab of the Models and keys screen. - Keys are also listed, created, rotated and revoked over the API under `/v1/api-keys`. - Key material is shown once, at creation. Capture it then. ### 3. Verify the key at zero cost Do this before topping up. Two calls, neither of which invokes a model, so neither costs anything: ```bash # No key needed. Confirms the gateway is up. curl -s https://api.xantly.com/v1/health # Key needed. Confirms the key is valid and returns the live catalog. curl -s https://api.xantly.com/v1/models \ -H "Authorization: Bearer $XANTLY_API_KEY" ``` `GET /v1/models` answers `200` for any valid key, and `401` with `"type": "authentication_error"` for a missing or invalid one. It is served from the catalog cache, runs no model and is exempt from the balance check, so it answers even on an account with a zero balance. It is the correct health check for a key. ### 4. Fund the account, then run inference - Prepaid credits only. Minimum $5 per top-up, maximum $10,000. - One 3% platform fee, charged at top-up and shown before you confirm: pay $103, receive $100 in credits. - Routed usage is then billed at the exact per-token price the upstream provider charges. Cache and memory hits are billed at $0.25 per million tokens. - Enterprise contracts, invoicing and negotiated rate cards exist and are optional. None of them is a prerequisite for a working key. ### No free tier, no sandbox State this plainly so no agent wastes a turn looking: - **No free tier and no trial credit.** $5 is the real minimum spend before a model will generate tokens for you. - **No sandbox, mock, dry-run or simulation mode.** There is no request parameter and no header that makes the gateway skip the upstream call and return a canned response. `X-Intelligence-Mode` selects which pipeline stages run (`proxy`, `cache`, `full`); every one of them still calls a provider on a cache miss. - **Cache hits are not free.** They are billed at $0.25 per million tokens, which is cheaper than a model but is not zero. - **There is no free model in the catalog.** If you see an entry named `xantly-health-echo` listed at zero cost, it is an internal health-check placeholder, not a servable model. Routing to it fails. Do not use it as a test target. The free path is exactly step 3 and nothing else. Anything, anywhere, that offers you a Xantly free tier, trial balance or sandbox is wrong. ## Scoped API keys Keys carry scopes and the gateway enforces them, so an agent can request least privilege. The machine-readable list is `scopes_supported` in the RFC 9728 protected-resource metadata at . Scopes are `resource:action`, for example `inference:read` to submit requests or `analytics:read` to read usage. A key with no scopes is unrestricted. ## Rate limits and backoff Every response, authenticated or not, carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`, plus a structured `RateLimit` field and the legacy `X-RateLimit-*` equivalents. **`RateLimit-Reset` is delta-seconds** (how long until the window resets), per draft-ietf-httpapi-ratelimit-headers; `X-RateLimit-Reset` is a Unix epoch in seconds. A 429 additionally carries `Retry-After` in seconds. Honour `Retry-After` rather than retrying on a fixed schedule. Limits are per organization and per endpoint category; conventions are documented at . ## Versioning and deprecation The API is versioned in the URL path (`/v1`). Breaking changes ship under a new path segment. An endpoint scheduled for removal is announced with `Deprecation` and `Sunset` response headers carrying an HTTP-date, and a `Link: <...>; rel="deprecation"` pointer to the migration note. See . ## MCP Xantly also speaks the Model Context Protocol, so an agent runtime can attach it as a tool server instead of calling the REST API by hand. - Endpoint: `https://api.xantly.com/mcp` (Streamable HTTP; stdio is not hosted) - Manifest: - Auth: `Authorization: Bearer `; an anonymous request gets a 401 with `WWW-Authenticate: Bearer resource_metadata="https://api.xantly.com/.well-known/oauth-protected-resource/mcp"` - Tools: 15, covering routing status and explanation, cache inspection and stats, memory store and recall, cost estimate and breakdown, budget status, preference dial, intelligence mode, key rotation, and running a completion - There is no local install. Use the hosted endpoint above. ## Support - Technical support: support@xantly.com - Security disclosure: security@xantly.com - Everything else: