API Reference

The CalibraLogic public API powers the CL-Code, CL-Agent, and the official MCP server. Bring the same ECU intelligence to WinOLS, Ghidra, TunerPro, and any custom tooling.

Base URL (staging)https://website-staging.calibralogic.ai/api/v1

Production (coming)https://api.calibralogic.ai/v1

FormatJSON / SSE

Authentication

Every request requires a Bearer API key. Generate one from Account → API Keys. The full secret is shown once on creation — copy it immediately.

Authorization: Bearer sk-cl-YOUR_API_KEY

Keys are stored hashed (SHA-256) — revoking is instant and irrevocable. If a key is compromised, revoke it and create a new one.

Rate Limits

Two limiters stack on every request: a per-key window (60/min, sliding) and a per-plan window (hourly + daily). The lowest remaining count is returned in X-RateLimit-Remaining.

Plan	Hourly	Daily	Per-Key / min
Garage	120	2,000	60
TunerPOPULAR	600	15,000	60
Engineer	1,800	50,000	60

A 429 response includes reset_at in ISO-8601 UTC — back off until that moment before retrying.

Endpoints

POST

/v1/chat

Send a message to the selected engine. Supports streaming (SSE) and synchronous JSON responses. Conversation history is optional; omit conversation_id to start a new thread.

Request body

JSON

{
  "message": "P0299 — overboost on EA888 gen3",
  "engine": "cl-scan",
  "stream": true,
  "conversation_id": "optional-uuid",
  "history": [
    { "role": "user", "content": "..." },
    { "role": "assistant", "content": "..." }
  ]
}

Fields

Field	Type	Required
message	string	Yes
engine	EngineId	default: cl-scan
stream	boolean	default: true
conversation_id	uuid	Optional
history	Message[]	≤ 50 items

cURL — streaming (SSE)

cURL

curl -N -X POST https://website-staging.calibralogic.ai/api/v1/chat \
  -H "Authorization: Bearer sk-cl-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "P0420 on VAG 2.0 TSI — likely causes?",
    "engine": "cl-scan",
    "stream": true
  }'

Streaming response body

SSE

data: {"delta":"The P0420 code"}
data: {"delta":" typically indicates"}
data: {"delta":" catalyst efficiency below threshold..."}
data: {"done":true,"tokens_used":1450,"engine":"cl-scan","conversation_id":"...","request_id":"..."}

cURL — synchronous JSON

cURL

curl -X POST https://website-staging.calibralogic.ai/api/v1/chat \
  -H "Authorization: Bearer sk-cl-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Explain cold-start enrichment on EDC17C50",
    "engine": "cl-forge",
    "stream": false
  }'

GET

/v1/account

Returns the caller's plan, token balance, monthly usage, and rate-limit budget for the current window.

cURL

curl -H "Authorization: Bearer sk-cl-YOUR_API_KEY" \
  https://website-staging.calibralogic.ai/api/v1/account

JSON

{
  "user_id": "uuid",
  "plan": "engineer",
  "plan_name": "Engineer",
  "token_balance": 999935,
  "monthly_tokens": 1500000,
  "monthly_used": 65,
  "purchased_tokens": 10000,
  "default_engine": "cl-forge",
  "reset_at": "2026-05-01T00:00:00.000Z",
  "engines_available": [
    "cl-scan", "cl-forge", "cl-matrix",
    "cl-engineering", "cl-assembly", "ultra"
  ],
  "rate_limits": {
    "per_hour": 1800,
    "per_day": 50000,
    "remaining_hour": 1782,
    "remaining_day": 49981
  }
}

GET

/v1/conversations

List the caller's conversations, newest first. Supports cursor pagination via ?before=<ISO timestamp> and ?limit=1..100 (default 20).

cURL

curl -H "Authorization: Bearer sk-cl-YOUR_API_KEY" \
  "https://website-staging.calibralogic.ai/api/v1/conversations?limit=20"

JSON

{
  "conversations": [
    {
      "id": "uuid",
      "title": "P0420 on VAG 2.0 TSI",
      "created_at": "...",
      "last_message_at": "...",
      "message_count": 6,
      "bookmarked": false
    }
  ],
  "has_more": false,
  "next_before": null
}

GET

/v1/conversations/{id}

Fetch a single conversation with all messages in chronological order. Responses never leak the underlying model or provider name — only the engine id.

cURL

curl -H "Authorization: Bearer sk-cl-YOUR_API_KEY" \
  https://website-staging.calibralogic.ai/api/v1/conversations/<uuid>

JSON

{
  "id": "uuid",
  "title": "P0420 on VAG 2.0 TSI",
  "created_at": "...",
  "last_message_at": "...",
  "message_count": 6,
  "bookmarked": false,
  "messages": [
    {
      "id": "uuid",
      "role": "user",
      "content": "...",
      "engine": null,
      "tokens_used": 0,
      "created_at": "..."
    },
    {
      "id": "uuid",
      "role": "assistant",
      "content": "...",
      "engine": "cl-scan",
      "tokens_used": 1450,
      "created_at": "..."
    }
  ]
}

Engines & Pricing

Cost per request equals the engine multiplier applied to actual provider tokens. Engine access is tied to your plan tier.

Engine	Multiplier	Minimum plan	Use case
cl-scan	1×	Garage	DTC lookup, quick diagnostics
cl-forge	2×	Tuner	Calibration map analysis
cl-matrix	2.5×	Tuner	Data log interpretation
cl-engineering	6×	Engineer	Deep calibration strategy
cl-assembly	8×	Engineer	Firmware reverse engineering
ultra	30×	Engineer	Premium multi-step reasoning

Error codes

400

Bad Request

Invalid JSON, missing message, or unknown engine id.

401

Unauthorized

API key is missing, revoked, or malformed.

402

Insufficient Tokens

Account balance is below the engine's estimated cost.

403

Engine Not Available

The engine is not included in your plan tier.

404

Not Found

Conversation id does not exist or does not belong to you.

429

Rate Limited

Per-key (60/min) or per-plan hourly/daily window exceeded.

500

Server Error

Provider or internal failure. Retry with X-Request-ID in support requests.

Every response includes an X-Request-ID header — include it when contacting support.

SDKs & tools

CL-Code

VS Code extension — inline ECU intelligence

Coming soon

CL-Agent

CLI for headless workflows and CI

Coming soon

MCP Server

Model Context Protocol bridge for Claude & compatible agents

Coming soon

WinOLS plugin

Map lookup and calibration hints inside WinOLS

Coming soon

Ghidra plugin

Symbolic annotations for ECU binaries

Coming soon

TunerPro plugin

Definition-aware assistance for TunerPro XDFs

Coming soon

Need help integrating?

Email support@calibralogic.ai with your X-Request-ID for fast triage, or browse the getting started guide.

Create an API key Getting started