Build on Cloptima
A governed AI gateway you can point an existing SDK at, a REST control plane for everything else, and first-class MCP and CLI access for agents. Authenticate once with a Personal Access Token and every surface below works the same way.
Quickstart
1. Create a Personal Access Token
In the console, go to Organization Settings → Access Tokens, or run `cloptima tokens create`. Scopes are resource domains, such as `org`, `tokens`, `integrations`, and `ai`; write implies read within the same domain. `ai:invoke` and `telemetry:write` are isolated and must be granted explicitly.
2. Call the API
Every authenticated endpoint accepts the token as `Authorization: Bearer <token>`. Browser sessions use OpenID Connect; agents and scripts should use a PAT.
curl -s https://api.cloptima.ai/healthz
curl -s "https://api.cloptima.ai/v1/llm/spend/summary?window=30d" \
-H "Authorization: Bearer $CLOPTIMA_ACCESS_TOKEN"3. Or point an existing SDK at the gateway
The AI gateway is OpenAI- and Anthropic-compatible. Change the base URL and your existing client keeps working, with policy, budgets, caching, and attribution applied around the unchanged request body.
# OpenAI-compatible
export OPENAI_BASE_URL="https://api.cloptima.ai/v1/ai"
export OPENAI_API_KEY="clop_vk_..."
# Anthropic-compatible
export ANTHROPIC_BASE_URL="https://api.cloptima.ai"
export ANTHROPIC_API_KEY="clop_vk_..."API surfaces
Every endpoint below is described in the OpenAPI document.
AI gateway (OpenAI- and Anthropic-compatible)
Governed inference. Point an existing SDK at the Cloptima base URL; the provider request and response bodies are unchanged.
POST https://api.cloptima.ai/v1/ai/chat/completions- /v1/ai/chat/completions, /v1/ai/completions, /v1/ai/responses, /v1/ai/embeddings
- /v1/messages and /v1/ai/messages for Anthropic-shaped clients
- /v1/ai/models and /v1/ai/models/{model} for model discovery
- Requires the isolated ai:invoke scope for PAT callers
REST control plane
JSON operations under /v1, each declared in the OpenAPI description with the PAT scope, plan features, and roles it needs. The organization record, plan checkout, LLM spend, finance, credits, exports, and unit economics are served here.
GET https://api.cloptima.ai/v1/llm/unit-economics?unit_type=ticket&group_by=app_id- snake_case JSON; money and ratios are decimal strings
- Errors are `{"error": {"code", "message"}}` with a matching HTTP status
MCP server
50+ AI gateway and LLM FinOps tools for MCP-compatible agents, over Streamable HTTP or a local stdio server embedded in the CLI.
POST https://api.cloptima.ai/v1/mcp- Protocol revision 2026-07-28, bearer PAT only
- `cloptima mcp serve` exposes the same tools locally; add --read-only to reject mutations
- Manifest at /.well-known/mcp
CLI
Query LLM spend and governance data from a terminal, a CI pipeline, or an agent. JSON, table, and CSV output.
cloptima llm breakdown --window 30d --output json- `cloptima auth login`, or set CLOPTIMA_ACCESS_TOKEN for non-interactive use
- Install with `brew tap cloptima/tap && brew install cloptima-cli`, or use the Docker image
Telemetry ingest
Send usage from direct provider calls or a third-party observability tool, so spend outside the gateway is still attributed.
POST https://api.cloptima.ai/v1/ai/integrations/sdk/events- SDK, LiteLLM, Portkey, Helicone, Langfuse, OTLP GenAI, and Datadog sources
- Business denominators via /v1/ai/integrations/unit-metrics for unit economics
- Requires ai:admin or telemetry:write
Errors
Errors are always JSON. Policy and guardrail blocks additionally carry a stable reason code and, for limit violations, the numbers you need to adjust and retry.
| Status | Meaning |
|---|---|
| 400 | Request body failed validation, or required Cloptima attribution metadata is missing. |
| 401 | Missing or invalid credentials. Send a valid PAT as a bearer token. |
| 402 | A budget or spend control denied the request. Retry after the window resets, or raise the limit. |
| 403 | Authenticated but not permitted — a missing PAT scope, entitlement, or a policy/guardrail block. The body names the reason. |
| 404 | No such resource. |
| 429 | Rate limit exceeded. Retryable — back off and retry. |
| 502 | The upstream provider failed. `retryable` indicates whether retrying can succeed. |
| 503 | The gateway shed the request under load. Retryable; any budget reservation is released first. |
Get an API Token
Create a Personal Access Token and call the gateway, the REST API, MCP, or the CLI within minutes.