API Reference

Everything you need to use SuperCompress programmatically: the HTTP API, response types, the Python client 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

FieldTypeDescription
compressed_textstrCompressed context for your LLM
original_tokensintTokens before compression
kept_tokensintTokens after compression
tokens_saved_pctfloatPercent of prompt tokens removed: (1 − kept/original) × 100.
tokens_savedintoriginal − kept
policy_namestre.g. local-query-aware, SuperCompress-compiler
modestrcompiler or precision
keep_ratiofloatRetention budget used
kept_line_ratiofloatFraction of original lines kept (hosted API)

HTTP API

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

Quick start (curl) One-liner, no JSON, no headers:
curl -d "context=Your long text&query=What matters?" https://www.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://www.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://www.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

ParameterTypeRequiredDescription
contextstringyesThe full context to compress. Supports Unicode, code, markup, logs.
querystringnoThe user's question. Omit it, or send a generic ask, to get a dump-mode digest that keeps about half of the input.
budget_rationumbernoPass only for legacy fixed-ratio mode (0.1–1.0). Omit for default compiler mode.

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

FieldTypeDescription
compressed_textstringThe compressed context. Send this to your LLM.
original_tokensintInput token count (rough estimate).
kept_tokensintTokens after compression.
tokens_savedintoriginal − kept.
tokens_saved_pctfloatPercent of prompt tokens removed.
important_kept_pctfloatEstimated fraction of important context preserved. 0.0–1.0.
compression_riskstring"low", "medium", or "high", verifier confidence.
kept_blocksarrayEvidence blocks kept, with reasons.
dropped_blocksarrayLargest removed blocks, with reasons.
policy_namestring"SuperCompress-compiler" or "SuperCompress-fixed".
query_modestring"dump" when query is missing or generic; "query" when a specific question is sent. CCR requests (ccr: true) keep their own query path and are not labelled dump mode.
noticestringPresent in dump mode (asks the caller to pass the user's question for a targeted, smaller digest) and on passthrough (explains the unchanged return).
compression_warningstringPresent on very deep cuts in query mode (1,500 or more input tokens, under 3% kept). Explains the cut and suggests a more specific query or omitting query.
passthroughbooleantrue when the original input is returned unchanged.
passthrough_reasonstringno_meaningful_savings (would save under 5%) or output_larger_than_input.
billedbooleanfalse on passthrough. That call is not billed.
quotaobjectOn billed responses: tokens_used_this_period, free_allowance, free_tokens_remaining, billing.
quota_warningstringOn billed responses when the free quota is nearly or fully used.

Passthrough and warnings

If compression would save under 5%, or the output would be larger than the input, the API returns the original text unchanged with passthrough: true, a passthrough_reason, billed: false, tokens_saved: 0, and a notice. That call is not billed. Very deep cuts on large inputs (query mode, 1,500 or more input tokens, under 3% kept) add compression_warning. Billed responses include a quota object and, when the free quota is nearly or fully used, quota_warning.

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

SituationUse
Production API call, maximize savings safelyCompiler mode (omit budget)
Research / fixed retention budgetFixed-ratio mode (pass budget_ratio)
Local offline / no API keycompress_for_turn() / compress_context()
Hosted with quality gateSuperCompress(...).compress(..., mode="precision")

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

ErrorCause
ValueErrorbudget_ratio outside (0, 1]
FileNotFoundErrorCheckpoint path doesn't exist
RuntimeErrorModel loading failure (corrupt checkpoint)

HTTP status codes

StatusMeaning
200Success, compressed text in response
400Missing or invalid context
401Missing or invalid API key
402Payment required, quota exceeded
429Rate limit exceeded
500Internal server error