Proxy API

Base URL & authentication

All endpoints live under https://trycran.in/api/v1. Authenticate with your Cran agent token (cran_…) as the bearer - never a provider sk-… key.

Authorization: Bearer cran_YOUR_TOKEN

Endpoints

The proxy exposes the OpenAI-compatible surface across three modalities:

Model resolution

The model field accepts three forms. Cran resolves it before dispatching:

• "auto" (or omitted) - your project’s latest published architecture: primary model + fallback chain + optional cost route.
• a workflow slug- that workflow’s published architecture.
• a catalog id (e.g. openai/gpt-5.5, anthropic/claude-haiku-4-5) - routed directly, unmanaged.

Drop-in examples

Two lines change - base URL and key. Everything else is your existing code.

from openai import OpenAI

client = OpenAI(
    base_url="https://trycran.in/api/v1",   # was: default OpenAI
    api_key="cran_YOUR_TOKEN",   # was: sk-…
)

res = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Hello!"}],
)

Reliability

Every routed call runs through the gateway’s reliability layer:

• Fallback chain- on a provider error, Cran retries the next model in the architecture’s chain (within the same modality).
• Retries - transient 429/5xx are retried with jittered backoff, honoring the provider’s Retry-After header (capped).
• Circuit breaker - a model that keeps failing is briefly taken out of rotation.

Caching & secure routing

Per-architecture exact-match response caching can be enabled (see Gateway configuration). For zero-retention, send x-cran-no-store: true - Cran still meters usage (tokens, cost, latency) but persists no prompt or response content.

-H "x-cran-no-store: true"

Response headers

• x-cran-model - the model that actually served the request.
• x-cran-source - auto / workflow / direct.
• x-cran-cache - hit or miss.
• x-cran-gateway-ms - time spent inside the gateway before the provider call.

Errors