API Endpoints — Compresh Docs

Compresh is a transparent proxy. You send requests to Compresh using the same format you already use with OpenAI or Anthropic. Compresh compresses the conversation context, forwards the request to your provider, and returns the response — identical to what you'd get directly, plus a few extra headers showing your savings.

Base URL

https://api.compre.sh/v1

POST /v1/chat/completions

OpenAI-compatible chat completions endpoint. Request and response formats are identical to the OpenAI Chat Completions API.

curl -X POST https://api.compre.sh/v1/chat/completions \
  -H "Authorization: Bearer comp_your_key" \
  -H "Content-Type: application/json" \
  -H "X-Session-Id: my-session-123" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Explain context windows."}
    ]
  }'

The response body is exactly what OpenAI returns. Compresh adds custom headers to the response (see below).

POST /v1/messages

Anthropic-compatible messages endpoint. Request and response formats are identical to the Anthropic Messages API.

curl -X POST https://api.compre.sh/v1/messages \
  -H "Authorization: Bearer comp_your_key" \
  -H "Content-Type: application/json" \
  -H "X-Session-Id: my-session-123" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Explain context windows."}
    ]
  }'

GET /health

Public health check endpoint. No authentication required.

curl https://api.compre.sh/v1/health

Returns:

{
  "status": "ok",
  "version": "1.0.0"
}

Session tracking

Compresh tracks conversations via the X-Session-Id header. This is how compression improves over time — Compresh builds a semantic tag cloud for each session and uses it to compress redundant context in subsequent turns.

Send X-Session-Id: your-session-id in your request to associate turns with a conversation.
If you don't send it, Compresh auto-generates one and returns it in X-Compresh-Session-Id.
Use the same session ID across turns to maximize compression savings.

Tip

Compression kicks in after the first few turns. By Turn 10+, expect 60–80% token savings. Short conversations (<5 turns) see minimal compression — that's by design.

Custom response headers

Every proxied response includes these Compresh-specific headers:

Header	Type	Description
`X-Compresh-Saved-Tokens`	integer	Number of input tokens saved by compression
`X-Compresh-Savings-Percent`	float	Percentage of input tokens saved (0–100)
`X-Compresh-Original-Tokens`	integer	Original input token count before compression
`X-Compresh-Optimized-Tokens`	integer	Actual input token count sent to provider
`X-Compresh-Session-Id`	string	Session ID for this conversation (auto-generated if not provided)
`X-Compresh-Proxy-Overhead-Ms`	integer	Milliseconds of latency added by the Compresh proxy

POST /v1/tul1

Server-side TUL 1.0 enhancement layer for the Mode B path (local compresh-mcp + server enhancement). Receives a transcript, applies Q-protective ranking + epistemic markers, and returns the enhanced compressed view. Gated by your Compresh API key + plan.

curl -X POST https://api.compre.sh/v1/tul1 \
  -H "Authorization: Bearer sk-comp_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "abc-123",
    "messages": [
      {"role": "user", "content": "..."},
      {"role": "assistant", "content": "..."}
    ],
    "protection_mode": "balanced",
    "provider_hint": "anthropic",
    "model_hint": "claude-sonnet-4-5"
  }'

Response (200)

{
  "ok": true,
  "applied": true,
  "tier": "pro_annual",
  "compresh_md": "[T0 (User)]\nSummary: ...",
  "raw_tail": [...],
  "n_compressed_turns": 5,
  "n_total": 9,
  "saving_chars": 1284,
  "saving_tokens": 321,
  "session_id": "abc-123",
  "protection_mode": "balanced",
  "fee_cents": 0.12,
  "tier_label": "tier-a",
  "version": "tul1-v0"
}

Response (402 — Payment Required)

Returned when the caller is anonymous, on the free tier with $0 budget, or otherwise not entitled to TUL 1.0 access.

{
  "ok": false,
  "error": "TUL 1.0 requires Pro subscription or Free tier with budget > $0",
  "your_tier": "trial",
  "your_budget_cents": 0,
  "signup_url": "https://compre.sh/upgrade"
}

Most callers don't hit this endpoint directly — compresh-mcp (>=0.2.0) and the OpenClaw hook use it automatically when a valid API key is configured.