# Catenary

> Catenary (https://catenary.run) is a multi-provider LLM API relay and usage ledger with pass-through wholesale token pricing, explicit provider selection, and per-key spend and model controls.

## Overview

- **Unified API Relay**: Access frontier and open-weight models across multiple upstream providers through standard OpenAI and Anthropic SDKs and CLI coding agents (Claude Code, OpenCode, Codex CLI).
- **Wholesale Token Pricing**: `1.00 Credit = $1.00 USD` of upstream wholesale compute. Catenary charges its relay fee upfront when purchasing credits rather than marking up per-token rates.
- **Per-Key Controls**: API keys (`cat_...`) support optional spend caps (`spend_limit`) and model allowlists (`allowed_models`).
- **Transparent Telemetry**: Every request logs uncached input tokens, cached input tokens, cache write tokens, output tokens, time-to-first-token (`ttft_ms`), total duration (`duration_ms`), upstream provider, and exact cost.

## API Endpoints & Dialects

- **OpenAI-Compatible Base URL**: `https://catenary.run/api/openai/v1`
  - `POST /api/openai/v1/chat/completions` (`ChatCompletions` dialect)
  - `POST /api/openai/v1/responses` (`Responses` dialect)
  - `GET /api/openai/v1/models` (filtered by the API key's `allowed_models`)
- **Anthropic-Compatible Base URL**: `https://catenary.run/api/anthropic/v1`
  - `POST /api/anthropic/v1/messages` (`Messages` dialect)
  - `GET /api/anthropic/v1/models` (filtered by the API key's `allowed_models`)
- **Authentication**:
  - `Authorization: Bearer <CATENARY_API_KEY>` or `x-api-key: <CATENARY_API_KEY>`

## Provider Routing Syntax

In any request's `model` field:
- `<model>` (e.g. `claude-sonnet-4-5`): Routes to the default active provider supporting the endpoint's dialect.
- `<model>@<provider>` (e.g. `claude-sonnet-4-5@anthropic`): Pins the request to a specific provider.

## Public Catalog & Documentation

- [Models & Pricing Catalog (Web)](https://catenary.run/models): Interactive table of supported models, providers, dialects, and tiered token pricing.
- [Models & Pricing Catalog (JSON API)](https://catenary.run/api/models): Unauthenticated JSON endpoint returning all active models, providers, supported dialects, and price schedules.
- [Terms of Service](https://catenary.run/terms): Service terms, billing, and acceptable use policy.