API Reference

Everything you need to use SuperCompress programmatically — Python library, HTTP API, response types, and client configuration.

Python API

The supercompress package provides the core compression functions. Local and hosted paths share one CompressResult type.

compress_for_turn(context, user_query, context_blocks=None, budget_ratio=0.35, mode="compiler")

Query-aware local compression. Returns a CompressResult.

from supercompress import compress_for_turn

result = compress_for_turn(
    context="",
    user_query=user_message,
    context_blocks=[system_prompt, tool_output, chat_history],
    budget_ratio=0.35,
)

# Send result.compressed_text to your LLM
print(result.tokens_saved_pct)

compress_context(text, query, budget_ratio=0.35)

Alias for compress_for_turn with a single context string. Returns a CompressResult.

from supercompress import compress_context

result = compress_context(
    text="Your long context…",
    query="What does fetch return?",
)

print(result.compressed_text)
print(f"Saved {result.tokens_saved_pct:.1f}% tokens")

Hosted client — SuperCompress.compress(...)

Same CompressResult type as the local engine.

from supercompress.client import SuperCompress

sc = SuperCompress(api_key="sc_live_…")
result = sc.compress(context, query, mode="precision")

CompressResult fields

HTTP API

The hosted API uses compiler mode by default — no budget needed. Compiler mode maximizes token removal while preserving answer-critical evidence.

curl -d "context=Your long text&query=What matters?" https://supercompress.dev/compress \
  -H "X-API-Key: sc_live_YOUR_KEY"

POST request

Send as JSON (standard) or form-encoded (simpler for curl). All three work:

# Option 1: JSON (standard)
POST https://supercompress.dev/api/v1/compress
Content-Type: application/json
X-API-Key: sc_live_YOUR_KEY
{
  "context": "Your long context…",
  "query": "What matters?"
}

# Option 2: Form-encoded (quick curl)
curl -d "context=...&query=..." https://supercompress.dev/compress \
  -H "X-API-Key: sc_live_YOUR_KEY"

# Prefer header auth — API keys in the URL (?api_key=) are rejected
curl -X POST https://api.supercompress.dev/compress \
  -H "X-API-Key: sc_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"context":"…","query":"…"}'

JSON and form-encoded POST both hit the same endpoint. Put the key in X-API-Key or Authorization: Bearer — never in the query string.

Parameters

Response (compiler mode)

{
  "compressed_text": "…",
  "original_tokens": 1248,
  "kept_tokens": 436,
  "tokens_saved": 812,
  "tokens_saved_pct": 65.06,
  "important_kept_pct": 0.98,
  "compression_risk": "low",
  "kept_blocks": [
    {"heading": "User account", "reason": "matches query topic"},
    {"heading": "Billing history", "reason": "contains answer evidence"}
  ],
  "dropped_blocks": [
    {"heading": "Feature requests", "reason": "irrelevant to billing question"}
  ],
  "policy_name": "SuperCompress-compiler"
}

Response fields

Authentication

Include your API key in either the X-API-Key header or the Authorization: Bearer sc_live_… header. Get a key from the dashboard.

Compiler mode (default)

Compiler mode is the production path. Users do not choose a budget or ratio. The engine:

• Segments context into semantic blocks (headings, code, logs, prose)
• Downranks repeated tool output, boilerplate, generated noise, and duplicates
• Preserves nearby headings, imports, trace/log context, and balanced markdown fences
• Reports tokens saved, important context kept %, verifier risk level, and block-level breakdowns

Compiler mode is the default on the hosted API. The local Python library uses fixed-ratio mode by default for backward compatibility, but you can enable compiler-style behavior by omitting budget_ratio.

When to use each mode

Environmental impact

The sustainability_from_tokens_saved helper converts token savings into estimated GPU-seconds, kWh, and CO₂ avoided.

from supercompress.benchmarks.metrics import sustainability_from_tokens_saved

saved = result.original_tokens - result.kept_tokens
impact = sustainability_from_tokens_saved(saved)

print(impact.co2_kg_avoided)
print(impact.watt_hours_saved)
print(impact.assumptions.to_dict())

Default assumptions: 2,500 tokens/GPU-sec, 150W GPU, 0.417 kg CO₂/kWh (US grid), and context_share_of_prefill set to 55%. This estimates the prefill work avoided by removing prompt tokens before inference; SuperCompress does not read or write the model’s KV cache. See Environment & CO₂ for the full methodology.

Error handling

Python errors

HTTP status codes