Reference

REST API

All endpoints require a cran_… bearer token unless the Scope column shows -. User CLI tokens from cran login also send X-Cran-Project for project-scoped routes.

Token scopes

read

Run audits, list workflows, use the proxy. Standard developer token.

propose

Everything in read, plus submit proposals for human review.

apply

Everything in propose, plus apply approved proposals to production config.

Tokens minted from Dashboard → Tokens default to read + propose. Team tokens default to read.

Base URL

https://trycran.in

Endpoints

GET/api/connectread

IDE onboarding - proxy URL, model sentinel, env key names. Used by cran_connect. Requires product connection token.

Response

json

{
  "connected": true,
  "project_id": "project_…",
  "proxy_base_url": "https://trycran.in/api/v1",
  "model": "auto",
  "env_keys": { "OPENAI_API_KEY": "…", "OPENAI_BASE_URL": "…" }
}

POST/api/v1/chat/completionsread

OpenAI-compatible proxy. model: auto | workflow-slug | catalog id. Published architecture overrides system prompt, temperature, tools.

Request

json

{
  "model": "auto | openai/gpt-5.5 | my-workflow-slug",
  "messages": [{ "role": "user", "content": "Hello!" }],
  "stream": true
}

POST/api/v1/embeddingsread

OpenAI-compatible embeddings. model: auto or a catalog embedding id (OpenAI / Google / Cohere).

Request

json

{ "model": "auto", "input": "text to embed" }

POST/api/v1/images/generationsread

OpenAI-compatible image generation. model: auto or a catalog image id (gpt-image-1, dall-e-3, imagen-4).

Request

json

{ "model": "auto", "prompt": "a red bicycle", "n": 1, "size": "1024x1024" }

POST/api/cli/device/start-

Start cran login device flow. Returns device_id, user_code, verification_url.

POST/api/cli/device/poll-

Poll device approval; returns user_cli_token once when approved.

Request

json

{ "device_id": "cli_dev_…", "device_secret": "…" }

GET/api/cli/projectsread

List projects (user CLI token + optional X-Cran-Project not required).

POST/api/cli/projectspropose

Create a project. Body: { "name": "My app" }.

POST/api/cli/linkpropose

Mint product connection token once. Body: { "project_id": "…" } or { "project_name": "…" }.

Response

json

{
  "project": { "id": "…", "name": "…" },
  "connection_token": "cran_…",
  "proxy_base_url": "https://trycran.in/api/v1"
}

POST/api/auditsread

Run a faithful benchmark - compare prompts × models, get per-cell scores and a routing recommendation. See /docs/audits for full guide.

Request

json

{
  "prompts": [
    { "id": "p1", "text": "...", "expected": "optional rubric for judge" }
  ],
  "models": ["openai/gpt-4o-mini", "anthropic/claude-haiku-4-5"],
  "system": "(optional) system prompt",
  "judgeModel": "gpt-4o-mini",
  "judgeStrategy": "general | classification | sentiment | extraction | semantic | schema",
  "params": {
    "temperature": 0.7,
    "max_tokens": 512,
    "response_format": { "type": "json_object" }
  },
  "tools": [],
  "tool_choice": "auto",
  "workflow_id": "(optional) DB id - inherits system, judge, params, tools",
  "use_generated_tests": true
}

Response

json

{
  "audit_id": "aud_abc123",
  "workflow_id": "wf_…",
  "recommendation": {
    "primary": "anthropic/claude-haiku-4-5",
    "fallbacks": ["openai/gpt-4o-mini"],
    "costRoute": "google/gemini-2.5-flash-lite",
    "reason": "Highest avg score at acceptable cost"
  },
  "perModel": [
    {
      "modelId": "anthropic/claude-haiku-4-5",
      "runs": 10,
      "failures": 0,
      "avgScore": 4.7,
      "avgLatencyMs": 340,
      "p50LatencyMs": 312,
      "p95LatencyMs": 580,
      "totalCostUsd": 0.000042,
      "avgCorrectness": 4.6,
      "avgCompleteness": 4.8,
      "avgFormatting": 4.7
    }
  ],
  "cells": [ /* prompt × model results with judgment scores */ ]
}

GET/api/auditsread

List recent audits for the project. Query: ?limit=20 (1–50).

Response

json

{
  "project_id": "project_…",
  "audits": [{
    "id": "aud_…",
    "status": "completed",
    "prompt_count": 10,
    "model_count": 3,
    "recommendation": { "primary": "…", "fallbacks": [], "costRoute": null },
    "started_at": "…",
    "finished_at": "…"
  }]
}

GET/api/audits/:idread

Fetch a persisted audit. Returns snake_case DB shape { audit, items }. MCP cran_get_audit normalizes to camelCase.

GET/api/audits/:id/policyread

Generate a deployable routing policy (LiteLLM / Vercel AI SDK / OpenAI SDK code) from an audit's recommendation.

Request

json

?format=litellm | vercel-ai-sdk | openai-sdk | json

GET/api/workflowsread

List all workflows registered in the active project.

GET/api/workflows/:idread

Fetch a single workflow including system prompt, sample inputs, generated tests, and current architecture.

POST/api/workflows/:id/classifyread

Auto-detect the workflow class (classification, extraction, chat, etc.) and suggest a judge strategy.

POST/api/workflows/:id/generate-testsread

Generate an adversarial stress-test suite (10–20 prompts) tailored to the workflow class.

POST/api/manifestsread

Submit a codebase manifest - registers LLM call sites as workflows. See /agent-manifest.schema.json for shape.

Request

json

{
  "schema_version": "1.0.0",
  "agent": { "name": "cursor", "os": "darwin" },
  "project": {
    "name": "my-app",
    "description": "...",
    "stack": ["nextjs", "typescript"],
    "ai_sdks_in_use": ["openai@^4"]
  },
  "workflows": [ /* ... workflow objects */ ]
}

POST/api/proposalspropose

Submit a change proposal (model swap, prompt edit, routing rule) for human review in the dashboard.

Request

json

{
  "workflow_id": "wf_abc123",
  "proposal_type": "model_change | prompt_edit | routing_rule",
  "title": "Switch to claude-haiku-4-5",
  "diff": { "before": { "model": "gpt-4o" }, "after": { "model": "claude-haiku-4-5" } },
  "reasoning": "Audit shows 0.4 higher score at 60% lower cost."
}

GET/api/proposalspropose

List proposals in the active project filtered by status.

Request

json

?status=submitted | approved | rejected | applied

GET/api/agent-manifest.schema.json-

Canonical JSON Schema for codebase manifests (cran_get_manifest_schema).

POST/api/architecture-auditsread

Run cross-workflow architecture review (prompt bloat, unused tools, consolidation).

GET/api/architecture-auditsread

List recent architecture audit reports for the project.

GET/api/models-

List the full model catalog with pricing and context windows. No authentication required.

GET/api/limitsread

Get the active rate limits and spend caps for the project.

PUT/api/limitsread

Update rate limits or spend cap for the project.

Request

json

{
  "rpm": 60,
  "spend_cap_usd": 50.00
}

GET/api/health-

Liveness check. Returns 200 with provider key availability status.

Model catalog

Use these IDs in the models array for audits or as the model field in proxy calls. All IDs follow the format provider/short-name.

Model	ID	Context	$/M in	$/M out
GPT-5.5	`openai/gpt-5.5`	1050k	$5	$30
GPT-5.5 Pro	`openai/gpt-5.5-pro`	1050k	$30	$180
GPT-5.4	`openai/gpt-5.4`	1050k	$2.5	$15
GPT-5.4 Pro	`openai/gpt-5.4-pro`	1050k	$30	$180
GPT-5.4 mini	`openai/gpt-5.4-mini`	272k	$0.75	$4.5
GPT-5.4 nano	`openai/gpt-5.4-nano`	272k	$0.2	$1.25
GPT-5.2	`openai/gpt-5.2`	272k	$1.75	$14
GPT-5.2 Pro	`openai/gpt-5.2-pro`	272k	$21	$168
GPT-5.1	`openai/gpt-5.1`	272k	$1.25	$10
GPT-5	`openai/gpt-5`	272k	$1.25	$10
GPT-5 mini	`openai/gpt-5-mini`	272k	$0.25	$2
GPT-5 nano	`openai/gpt-5-nano`	272k	$0.05	$0.4
GPT-5 Pro	`openai/gpt-5-pro`	128k	$15	$120
GPT-4.1	`openai/gpt-4.1`	1048k	$2	$8
GPT-4.1 mini	`openai/gpt-4.1-mini`	1048k	$0.4	$1.6
GPT-4.1 nano	`openai/gpt-4.1-nano`	1048k	$0.1	$0.4
GPT-4o	`openai/gpt-4o`	128k	$2.5	$10
GPT-4o mini	`openai/gpt-4o-mini`	128k	$0.15	$0.6
o3	`openai/o3`	200k	$2	$8
o3-pro	`openai/o3-pro`	200k	$20	$80
o3-mini	`openai/o3-mini`	200k	$1.1	$4.4
o4-mini	`openai/o4-mini`	200k	$1.1	$4.4
o1	`openai/o1`	200k	$15	$60
Claude Fable 5	`anthropic/claude-fable-5`	1000k	$10	$50
Claude Opus 4.8	`anthropic/claude-opus-4-8`	1000k	$5	$25
Claude Sonnet 5	`anthropic/claude-sonnet-5`	1000k	$2	$10
Claude Opus 4.7	`anthropic/claude-opus-4-7`	1000k	$5	$25
Claude Opus 4.6	`anthropic/claude-opus-4-6`	1000k	$5	$25
Claude Opus 4.5	`anthropic/claude-opus-4-5`	200k	$5	$25
Claude Opus 4.1	`anthropic/claude-opus-4-1`	200k	$15	$75
Claude Sonnet 4.6	`anthropic/claude-sonnet-4-6`	1000k	$3	$15
Claude Sonnet 4.5	`anthropic/claude-sonnet-4-5`	200k	$3	$15
Claude Sonnet 4	`anthropic/claude-sonnet-4`	1000k	$3	$15
Claude 3.7 Sonnet	`anthropic/claude-3-7-sonnet`	200k	$3	$15
Claude Haiku 4.5	`anthropic/claude-haiku-4-5`	200k	$1	$5
Claude 3 Haiku	`anthropic/claude-3-haiku`	200k	$0.25	$1.25
Gemini 3.1 Propreview	`google/gemini-3.1-pro`	1049k	$2	$12
Gemini 3 Propreview	`google/gemini-3-pro`	1049k	$2	$12
Gemini 3.5 Flash	`google/gemini-3.5-flash`	1049k	$1.5	$9
Gemini 3 Flashpreview	`google/gemini-3-flash`	1049k	$0.5	$3
Gemini 3.1 Flash Litepreview	`google/gemini-3.1-flash-lite`	1049k	$0.25	$1.5
Gemini 2.5 Pro	`google/gemini-2.5-pro`	1049k	$1.25	$10
Gemini 2.5 Flash	`google/gemini-2.5-flash`	1049k	$0.3	$2.5
Gemini 2.5 Flash Lite	`google/gemini-2.5-flash-lite`	1049k	$0.1	$0.4
Gemini 2.0 Flash	`google/gemini-2.0-flash`	1049k	$0.1	$0.4
Gemini 2.0 Flash Lite	`google/gemini-2.0-flash-lite`	1049k	$0.075	$0.3
Grok 4	`xai/grok-4`	256k	$3	$15
Grok 3 Mini	`xai/grok-3-mini`	131k	$0.3	$0.5
Llama 3.3 70B (Groq)	`groq/llama-3.3-70b-versatile`	131k	$0.59	$0.79
Llama 3.1 8B (Groq)	`groq/llama-3.1-8b-instant`	131k	$0.05	$0.08
Mistral Large	`mistral/mistral-large-latest`	131k	$2	$6
Mistral Small	`mistral/mistral-small-latest`	131k	$0.1	$0.3
DeepSeek V3	`deepseek/deepseek-chat`	128k	$0.27	$1.1
DeepSeek R1	`deepseek/deepseek-reasoner`	128k	$0.55	$2.19
Llama 3.3 70B (Together)	`together/llama-3.3-70b-instruct-turbo`	131k	$0.88	$0.88
Qwen 2.5 72B (Together)	`together/qwen2.5-72b-instruct-turbo`	33k	$1.2	$1.2
Llama 3.3 70B (Fireworks)	`fireworks/llama-v3p3-70b-instruct`	131k	$0.9	$0.9
Kimi K2 (Fireworks)	`fireworks/kimi-k2-instruct`	131k	$0.6	$2.5
Command A	`cohere/command-a`	256k	$2.5	$10
GPT-4o (Azure)	`azure/gpt-4o`	128k	$2.5	$10
GPT-4o mini (Azure)	`azure/gpt-4o-mini`	128k	$0.15	$0.6
GPT-4.1 (Azure)	`azure/gpt-4.1`	1048k	$2	$8
OpenRouter Auto	`openrouter/auto`	128k	$5	$15
Llama 3.3 70B (OpenRouter)	`openrouter/llama-3.3-70b-instruct`	131k	$0.3	$0.4
Sonar Pro	`perplexity/sonar-pro`	200k	$3	$15
Sonar	`perplexity/sonar`	128k	$1	$1
Llama 3.3 70B (Cerebras)	`cerebras/llama-3.3-70b`	128k	$0.85	$1.2
GPT-OSS 120B (Cerebras)	`cerebras/gpt-oss-120b`	128k	$0.35	$0.75
Llama 3.3 70B (SambaNova)	`sambanova/llama-3.3-70b`	128k	$0.6	$1.2
Llama 3.3 70B (NVIDIA NIM)	`nvidia/llama-3.3-70b-instruct`	128k	$0.3	$0.3
Llama 3.3 70B (Hugging Face)	`huggingface/llama-3.3-70b-instruct`	128k	$0.4	$0.4
Llama 3.3 70B (Hyperbolic)	`hyperbolic/llama-3.3-70b-instruct`	131k	$0.4	$0.4
Llama 3.3 70B (Novita)	`novita/llama-3.3-70b-instruct`	131k	$0.39	$0.39
Kimi K2 Turbo	`moonshot/kimi-k2-turbo`	256k	$0.6	$2.5
Kimi K2 Thinking	`moonshot/kimi-k2-thinking`	256k	$0.6	$2.5
Qwen Max	`qwen/qwen-max`	131k	$1.6	$6.4
Qwen Plus	`qwen/qwen-plus`	131k	$0.4	$1.2
GLM-4.6	`zhipu/glm-4.6`	200k	$0.6	$2.2
Embedding 3 Small	`openai/text-embedding-3-small`	8k	$0.02	$0
Embedding 3 Large	`openai/text-embedding-3-large`	8k	$0.13	$0
Gemini Embedding	`google/gemini-embedding`	2k	$0.15	$0
Cohere Embed v4	`cohere/embed-v4`	128k	$0.12	$0
GPT Image 1	`openai/gpt-image-1`	0k	$0	$0
DALL·E 3	`openai/dall-e-3`	0k	$0	$0
Imagen 4preview	`google/imagen-4`	0k	$0	$0

Error codes

400invalid_request_error

Malformed body, unsupported model ID, or missing required field.

401unauthorized

Token missing, malformed, or revoked.

403forbidden

Token scope insufficient for the requested action.

404not_found

Resource does not exist or belongs to a different project.

429budget_exceeded

Project spend budget reached. Increase in Dashboard → Settings.

402spend_cap_exceeded

Per-project rate cap reached. Includes Retry-After header.

503service_unavailable

Persistence not configured or provider key missing.