Build on Cloptima
A governed AI gateway you can point an existing SDK at, a GraphQL 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 (org, tokens, cloud, k8s, finops, integrations, 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/graphql \
-H "Authorization: Bearer $CLOPTIMA_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"query":"{ llmSpendSummary { totalCostUsd } }"}'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
GraphQL control plane
Everything that is not inference: cost, LLM spend, gateway policies, budgets, Kubernetes, teams, and integrations. Introspect the schema for the full contract.
POST https://api.cloptima.ai/graphql- One endpoint; PAT callers need the resource-domain scope each operation maps to
- Operation-level failures are reported in `errors` with a 200 status, per the GraphQL spec
MCP server
160+ Cloptima 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 cost, 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
PR cost impact
Upload a CI-produced infrastructure plan artifact and Cloptima comments the projected cost impact on the pull request.
POST https://api.cloptima.ai/v1/pr-impact/upload- Terraform/OpenTofu, Pulumi, CloudFormation, Kubernetes/Helm/Kustomize, and dbt artifacts
- Requires finops: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, GraphQL, MCP, or the CLI within minutes.