Documentation

Installation

No SDK required. LightReach uses standard HTTP with your existing tools.

Connect Cursor

LightReach exposes a strict OpenAI-compatible API so Cursor can use it as a drop-in base URL. Cursor traffic is automatically attributed as integration=cursor.

https://api.compress.lightreach.io/v1/cursor

lightreach

Compress Cloud is ready after you create a LightReach API key. Provider keys are optional for a specific provider account or billing arrangement.

Quality policy

Cursor does not pick quality. Admins set a fixed HLE ceiling for Cursor traffic in Dashboard → Settings → Tags → System tags → click the Cursor card. This configures the integration=cursor policy and lets you control cost without asking developers to tune per-user model settings.

Connect Claude Code

LightReach exposes an Anthropic-compatible Messages API so Claude Code can use it as a drop-in base URL. Claude Code traffic is automatically attributed as integration=claude.

export ANTHROPIC_BASE_URL=https://api.compress.lightreach.io/v1/claude
export ANTHROPIC_AUTH_TOKEN=lr_your_key_here

claude --model lightreach

Compress Cloud is ready after you create a LightReach API key. Provider keys are optional for a specific provider account or billing arrangement.

Quality policy

Claude Code does not pick quality. Admins set a fixed HLE ceiling for Claude Code traffic in Dashboard → Settings → Tags → System tags → click the Claude Code card. This configures the integration=claude policy and lets you control cost without asking developers to change their workflow.

Authentication

Authenticate with a LightReach API key (lr_…). Most clients use an Authorization Bearer header. We also accept X-API-Key for server-to-server usage.

Authorization: Bearer lr_your_api_key_here
X-API-Key: lr_your_api_key_here

OpenAI-compatible API

Use these endpoints when you want strict OpenAI client compatibility (Cursor, OpenAI SDKs, or any tool that speaks/v1/chat/completions).

This is the right choice for IDE products (Cursor, Claude Code, Windsurf) because they generally integrate by setting an OpenAI-style Base URL and letting the IDE run tools locally on the developer machine.

curl -sS https://api.compress.lightreach.io/v1/cursor/chat/completions \
  -H "Authorization: Bearer lr_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "lightreach",
    "messages": [{"role":"user","content":"Write a concise commit message for a refactor."}],
    "stream": true
  }'

Send a chat completion request with automatic model routing, optional compression, and full cost tracking.

Use this endpoint from your codebase (HTTP / Python / Node) when you want OpenAI-style response fields plus LightReach-native metadata (compression stats, routing transparency, and cost receipts). For IDE products like Cursor/Claude Code/Windsurf, use the OpenAI-compatible endpoints instead.

Request Body

Response

{
  "id": "chatcmpl-1741400000000",
  "object": "chat.completion",
  "created": 1741400000,
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "Quantum computing uses quantum mechanics..."},
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 320, "completion_tokens": 120, "total_tokens": 440},
  "content": "Quantum computing uses quantum mechanics...",
  "compression_stats": {
    "compression_enabled": true,
    "original_tokens": 450,
    "compressed_tokens": 320,
    "token_savings": 130,
    "compression_ratio": 0.711,
    "token_accounting_note": "token_savings is input-side only (original - compressed). Output tokens are reported separately in llm_stats."
  },
  "llm_stats": {
    "provider": "openai",
    "model": "gpt-4o-mini",
    "input_tokens": 320,
    "output_tokens": 120,
    "total_tokens": 440,
    "finish_reason": "stop"
  },
  "warnings": [],
  "model_used": "gpt-4o-mini",
  "provider_used": "openai",
  "cost_estimate": 0.00042,
  "routing_info": {
    "selected_model": "gpt-4o-mini",
    "selected_provider": "openai",
    "requested_hle": 25,
    "effective_hle": 25,
    "hle_source": "request",
    "hle_clamped": false
  },
  "tool_calls": null,
  "lightreach": {
    "latency_ms": 812
  }
}

Intelligent Routing

The routing system automatically selects the most cost-effective model that meets your quality requirements. It uses HLE (Humanity's Last Exam) scores as a standardized benchmark for model capability.

Prompt Compression

The greedy compression algorithm identifies and replaces repeated patterns with shorter references. Compression is lossless. The LLM receives instructions to expand the references, preserving full semantic meaning.

Compression works best on prompts with repeated content, such as system prompts with examples, RAG contexts with similar documents, or multi-turn conversations with repeated context.

Context windows & compaction

Long-running chats and tool outputs can exceed a model’s context window. LightReach separates this into two mechanisms: