Compression API - gotcontext.ai docs

Compression#

POST/v1/compress

Compress any text document using graph-based semantic compression. Achieves 80 to 95% token reduction on medium-to-large documents. Optionally supply a query to guide the compressor toward sections most relevant to your question.

AuthBearer token required

Fidelity levels: abstract (5% kept), outline (10%), balanced (20%), detailed (40%), raw (100%, no compression). Small documents under 100 tokens may expand slightly due to skeleton overhead.

Request body

{
        "text": string,       // required — document to compress (min 1 char)
        "fidelity": string,   // optional — "abstract" | "outline" | "balanced" | "detailed" | "raw"
                    //            default: "balanced"
        "query": string|null, // optional — query-guided mode; prioritises relevant sections
        "cost_model": string|null // optional — model name for cost estimate (e.g. "claude-opus-4")
      }

Response

{
        "compressed": string,   // compressed skeleton text
        "stats": {
          "original_tokens": number,
          "compressed_tokens": number,
          "savings_pct": number,        // e.g. 87.4
          "compression_ratio": number,  // e.g. 7.9
          "estimated_cost_saved": string|null  // e.g. "$0.042" — only when cost_model supplied
        }
      }

curl -X POST https://api.gotcontext.ai/v1/compress \
        -H "Authorization: Bearer gc_your_key_here" \
        -H "Content-Type: application/json" \
        -d '{
          "text": "Transformer models fundamentally changed NLP...",
          "fidelity": "balanced",
          "query": "attention mechanism",
          "cost_model": "claude-sonnet-4-6"
        }'

Error responses

400Invalid fidelity value (valid options: abstract, outline, balanced, detailed, raw)

422Missing or empty text field (Pydantic validation)

401Missing or invalid Bearer token

429Rate limit exceeded (see Rate Limits section)

Code Compression#

POST/v1/compress-code

AST-aware code compression. Parses function/class boundaries, extracts imports and docstrings, ranks symbols by PageRank on the dependency graph. Returns a skeleton preserving signatures and docstrings. Significantly better than plain text compression for code.

AuthBearer token required

Supported languages with AST-native parsing: Python. JavaScript/TypeScript use regex-based chunking. Java, Go, Rust, C++ fall back to line-based chunking.

Request body

{
        "code": string,        // required — source code to compress (min 1 char)
        "language": string|null, // optional — hint: "python"|"javascript"|"typescript"|"java"|"go"|"rust"|"cpp"
                       //             auto-detected from content when omitted
        "fidelity": string,    // optional — same levels as /compress, default: "balanced"
      }

Response

{
        "compressed": string,
        "stats": {
          "original_tokens": number,
          "compressed_tokens": number,
          "savings_pct": number,
          "language_detected": string  // e.g. "python", "javascript", "unknown"
        }
      }

curl -X POST https://api.gotcontext.ai/v1/compress-code \
        -H "Authorization: Bearer gc_your_key_here" \
        -H "Content-Type: application/json" \
        -d '{
          "code": "def process(items):\n    ...",
          "language": "python",
          "fidelity": "balanced"
        }'

Error responses

400Invalid fidelity or unrecognised language hint

422Missing or empty code field

401Missing or invalid Bearer token

Code Context Ranking (blast-radius + BM25)v1.5.0#

POST/v1/compress-code/structural

Structural code-context compression. Submit a file bundle + optional focus symbol; the server runs tensor-grep blast-radius + BM25 on the sandboxed files and returns a Reciprocal-Rank-Fusion-ranked context list. Intended for PR-diff-scale code payloads (≤1000 files, ≤512 KB each, ≤5 MB total). Measured 34% token reduction on a 10-file corpus with focus_symbol=cache_lookup vs naive full-bundle submission. See the smoke benchmark at benchmarks/blast_radius_smoke.py.

AuthBearer token required: Pro or higher

Degraded-path: if the tensor-grep binary is unavailable on the server or subprocess times out, the response is still 200 but carries X-Degraded: true and stats.degraded=true with an explanatory `message`. Never 500s on subprocess failure. The BM25 arm uses `tg search --count-matches`; a failure there degrades only the BM25 signal, leaving the graph-distance moat arm functional. The corresponding MCP tool is `gc_blast_radius`: same input/output, exposed to Claude Code via the MCP gateway.

Request body

{
        "files": [
          { "path": "src/app.py", "content": "def handle_request(): ..." },
          { "path": "src/utils.py", "content": "..." }
        ],
        "focus_symbol": "handle_request",       // optional — focus blast-radius on this symbol
        "query": "error handling",              // optional — BM25 query (defaults to focus_symbol)
        "top_k": 25                              // optional — cap on ranked_context length (1-500, default 50)
      }

Response

{
        "ranked_context": [
          {
            "path": "src/app.py",
            "score": 0.031,
            "rank": 1,
            "contributing_signals": ["bm25", "graph_distance"]
          }
        ],
        "stats": {
          "files_in": 10,
          "files_ranked": 5,
          "symbols_in": 23,
          "degraded": false
        },
        "message": null   // non-null only on degraded paths (tg missing, timeout, etc.)
      }

curl -X POST https://api.gotcontext.ai/v1/compress-code/structural \
        -H "Authorization: Bearer gc_your_key_here" \
        -H "Content-Type: application/json" \
        -d '{
          "files": [
            {"path":"src/app.py","content":"def handle_request(): pass"},
            {"path":"src/utils.py","content":"..."}
          ],
          "focus_symbol": "handle_request",
          "top_k": 25
        }'

Error responses

400{error_code: "sensitive_content", marker_class: string}: a submitted file matches the secret-marker detector (PEM headers, AWS AKIA keys, OpenAI sk- keys, .ssh/id_rsa, dotenv-style secrets). Marker value is never echoed back.

400{error_code: "bad_path"}: path traversal (../), absolute POSIX/Windows root, or null-byte detected in a submitted path

413Per-file (>512 KB) or aggregate (>5 MB) size cap exceeded. Validation runs pre-subprocess.

402Free-tier plan does not include structural context. Upgrade to Pro+ from the dashboard.

401Missing or invalid Bearer token

Batch Compression (synchronous)#

POST/v1/batch-compress

Compress up to 50 documents in a single call. Documents are processed concurrently (max 4 at once to avoid saturating the embedding model). Each document may have its own fidelity and query. Failed documents are reported inline. The overall batch always returns 200.

AuthBearer token required

Request body

{
        "documents": [    // required — 1 to 50 items
          {
            "text": string,       // required
            "fidelity": string,   // optional, default "balanced"
            "query": string|null  // optional
          }
        ]
      }

Response

{
        "results": [
          {
            "compressed": string,
            "original_tokens": number,
            "compressed_tokens": number,
            "savings_pct": number,
            "compression_ratio": number,
            "error": string|null   // set when this document failed; other fields are 0
          }
        ],
        "summary": {
          "total_documents": number,
          "successful": number,
          "failed": number,
          "total_tokens_in": number,
          "total_tokens_saved": number,
          "avg_savings_pct": number,
          "avg_compression_ratio": number
        }
      }

curl -X POST https://api.gotcontext.ai/v1/batch-compress \
        -H "Authorization: Bearer gc_your_key_here" \
        -H "Content-Type: application/json" \
        -d '{
          "documents": [
            {"text": "First document...", "fidelity": "balanced"},
            {"text": "Second document...", "query": "neural networks"},
            {"text": "Third document...", "fidelity": "outline"}
          ]
        }'

Error responses

400Empty documents list, more than 50 documents, or invalid fidelity in any document

401Missing or invalid Bearer token

Fidelity Advisor#

POST/v1/recommend

Analyse a document and recommend the optimal fidelity level. Considers document size and (optionally) the target model's context window. Use this to automatically pick the right compression level before calling /compress.

AuthBearer token required

Fidelity rules: <500 tokens → detailed, 500 to 2000 → balanced, 2000 to 10000 → outline, >10000 → abstract. If the compressed output would exceed 70% of the target model's context window, fidelity is automatically stepped up.

Request body

{
        "text": string,           // required — document to analyse
        "model": string|null,     // optional — target model (e.g. "claude-sonnet-4-6")
        "context_window": number|null  // optional — override context window size in tokens
      }

Response

{
        "recommended_fidelity": string,  // e.g. "balanced"
        "estimated_ratio": number,       // fraction of tokens kept (0.0–1.0)
        "estimated_output_tokens": number,
        "original_tokens": number,
        "reasoning": string              // human-readable explanation
      }

curl -X POST https://api.gotcontext.ai/v1/recommend \
        -H "Authorization: Bearer gc_your_key_here" \
        -H "Content-Type: application/json" \
        -d '{
          "text": "Your long document...",
          "model": "claude-sonnet-4-6"
        }'

Where to next

Quickstart

Connect your MCP client and run your first compression in under two minutes.

Recipes

Copy-paste tool sequences for the workflows you'll run most.

Troubleshooting

Symptom-to-fix for the errors people actually hit.

Glossary

Plain-language definitions for skeleton, fidelity, profiles, and the rest.