Compression#
POST
/v1/compressCompress 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.
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-codeAST-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.
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/structuralStructural 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.
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-compressCompress 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.
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/recommendAnalyse 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.
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.