Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/arjunkshah/supercompress/llms.txt

Use this file to discover all available pages before exploring further.

The local development server is a FastAPI application that replicates the full SuperCompress web surface on your machine — the browser demo, the /dashboard for API-key management, the unauthenticated /api/compress playground, and the authenticated /v1/compress endpoint. It is intentionally separate from the public Vercel site, which performs all compression client-side in the browser and never calls a backend.

​
Prerequisites

Install the serve extra alongside the core library: 
pip install -e ".[serve]"
This pulls in fastapi, uvicorn[standard], pydantic, and httpx. If you also want Firebase-backed key storage for a closer-to-production setup, add the firebase extra: 
pip install -e ".[serve,firebase]"

​
Start the server

1

Set dev environment variables

SC_AUTH_DEV=1 disables Firebase token verification so any request is treated as authenticated. SC_KEY_STORE=memory keeps API keys in process memory instead of Firestore — no GCP credentials required.
2

Launch the server

SC_AUTH_DEV=1 SC_KEY_STORE=memory python scripts/local_web_server.py
Uvicorn binds to http://127.0.0.1:8790. You should see output similar to:
INFO:     Started server process [12345]
INFO:     Uvicorn running on http://127.0.0.1:8790 (Press CTRL+C to quit)

​
Available endpoints

Once the server is running the following URLs and routes are available:
URL / RouteDescription
http://127.0.0.1:8790Landing page / browser demo
http://127.0.0.1:8790/dashboardAPI key management dashboard
POST /api/compressUnauthenticated playground — no key required
POST /v1/compressAuthenticated compress endpoint — requires an API key
GET /api/healthHealth check
GET /api/meCurrent user info (requires Firebase token)
GET /api/keysList API keys (requires Firebase token)
With SC_AUTH_DEV=1 set, the Firebase token checks on /api/me and /api/keys are bypassed, making it easy to test key management flows without a real Firebase project.

​
Verify the server is healthy

curl http://127.0.0.1:8790/api/health
# {"ok": true, "service": "supercompress-web"}

​
Compress text via the playground endpoint

POST /api/compress is unauthenticated and is the same route the browser demo calls. The compare flag adds a full policy comparison (FIFO, Truncation, Summarization, H2O, SuperCompress) to the response alongside per-line annotations: 
curl -X POST http://127.0.0.1:8790/api/compress \
  -H 'Content-Type: application/json' \
  -d '{"context": "long text…", "query": "What does fetch return?", "budget_ratio": 0.35, "compare": true}'
The response includes compressed_text, original_tokens, kept_tokens, kv_savings_pct, kept_line_ratio, policy_name, budget_ratio, line_annotations, and — when compare: true — a compare map keyed by policy name.
Set budget_ratio between 0.05 and 1.0. A value of 0.35 keeps roughly 35 % of the original tokens, yielding ~65 % KV savings in typical workloads.

​
Call the authenticated endpoint

POST /v1/compress mirrors the hosted API and requires an X-API-Key header. Create a key via the /dashboard UI, then: 
curl -X POST http://127.0.0.1:8790/v1/compress \
  -H "X-API-Key: sc_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"context": "long text…", "query": "Summarize", "budget_ratio": 0.35}'

​
Relationship to the public Vercel site

The public Vercel deployment of web/ is fully static. Compression is performed client-side by the JavaScript engine in web/assets/js/compress-engine.js — no backend server is involved. The local dev server exists solely to develop and test the API layer, dashboard, and key-management flows.

Build docs developers (and LLMs) love

Get started for freeTalk to us