API Reference

{
  "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")
}

{
  "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
  }
}

{
  "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"
}

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

{
  "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)
}

{
  "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.)
}

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

{
  "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
  }
}

{
  "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
}

{
  "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
}

{
  "name": string  // required — human-readable label (1–100 chars)
}

{
  "key": string,       // full raw key — shown ONCE, store securely
  "key_id": string,    // 16-char hex ID for management
  "name": string,
  "created_at": string // ISO 8601 UTC
}

{
  "keys": [
    {
      "key_id": string,
      "name": string,
      "masked_key": string,    // e.g. "gc_****ab12"
      "created_at": string,    // ISO 8601 UTC
      "last_used": string|null,
      "status": "active" | "revoked"
    }
  ]
}

{
  "success": true,
  "key_id": string
}

{
  "period": string,            // "YYYY-MM", e.g. "2026-04"
  "compressions_used": number,
  "compressions_limit": number, // 1000 (free) or 50000 (pro)
  "pct_used": number,          // 0.0–100.0
  "tokens_in": number,         // total original tokens this month
  "tokens_saved": number,      // total tokens eliminated this month
  "resets_at": string          // ISO 8601 UTC, midnight 1st of next month
}

{
  "plan": "pro"   // currently the only valid value
}

{
  "checkout_url": string  // redirect the user to this URL
}

{
  "portal_url": string  // redirect the user to this URL
}

{
  "output": string,        // required — raw CLI output to compress (min 1 char)
  "command_hint": string|null // optional — hint: "git_diff", "test_output", etc.
                              //            auto-detected if omitted
}

{
  "filtered": string,      // compressed CLI output
  "original_chars": number,
  "filtered_chars": number,
  "savings_pct": number,   // e.g. 92.3
  "detected_type": string|null // e.g. "git_diff", "pytest"
}

{
  "total_compressions": number,
  "total_tokens_in": number,
  "total_tokens_saved": number,
  "savings_pct": number,              // e.g. 87.2
  "estimated_cost_saved_usd": number  // e.g. 12.45
}

{
  "text": string,      // required — prompt or document text to audit (min 1 char)
  "provider": string   // optional — "anthropic" | "openai" | "google"
                       //            default: "anthropic"
}

{
  "provider": string,
  "cache_friendly": boolean,
  "score": number,                // 0.0 - 1.0 cacheability score
  "recommendations": [string],    // actionable suggestions
  "estimated_savings_pct": number // estimated cache hit savings
}

{
  "text": string,            // required — text to check against budget (min 1 char)
  "context_window": number,  // optional — target context window in tokens
                             //            default: 200000
  "model": string            // optional — target model for cost estimation
                             //            default: "claude-opus-4"
}

{
  "estimated_tokens": number,
  "context_window": number,
  "pct_used": number,       // e.g. 42.5
  "status": string,         // "OK" | "WARNING" | "CRITICAL"
  "recommendation": string  // human-readable guidance
}

— no body —

{
  "threshold": 0.95,
  "source": "global"   // "user" | "global"
}

{ "threshold": 0.92 }

{
  "threshold": 0.92,
  "source": "user"
}

{
  "original_text": string,       // required — original uncompressed text (min 1 char)
  "compressed_text": string,     // required — compressed output to check (min 1 char)
  "check_hallucination": boolean, // optional — check for hallucinated content
                                  //            default: true
  "check_blind_spots": boolean   // optional — check for lost critical info
                                  //            default: true
}

{
  "issues_found": number,
  "issues": [
    {
      "type": string,        // "hallucination" or "blind_spot"
      "severity": string,    // "low", "medium", or "high"
      "description": string,
      "location": string|null
    }
  ],
  "quality_score": number   // 0.0 - 1.0 (1.0 = no issues found)
}

{
  "name": string,          // required — project name (1-100 chars)
  "description": string|null // optional — project description
}

{
  "id": string,
  "name": string,
  "description": string|null,
  "created_at": string,
  "stats": { "compressions": 0, "tokens_saved": 0 }
}

{
  "projects": [
    {
      "id": string,
      "name": string,
      "description": string|null,
      "created_at": string,
      "stats": {
        "compressions": number,
        "tokens_saved": number
      }
    }
  ]
}

{
  "id": string,
  "name": string,
  "description": string|null,
  "created_at": string,
  "updated_at": string,
  "stats": {
    "compressions": number,
    "tokens_saved": number,
    "avg_savings_pct": number
  }
}

{
  "name": string|null,        // optional — new name
  "description": string|null  // optional — new description
}

{
  "id": string,
  "name": string,
  "description": string|null,
  "updated_at": string
}

{
  "success": true,
  "id": string
}

{
  "documents": [           // required — 1 to 500 items
    {
      "text": string,      // required
      "fidelity": string,  // optional, default "balanced"
      "query": string|null // optional
    }
  ],
  "project_id": string|null, // optional — associate with a project
  "webhook_url": string|null // optional — POST results on completion
}

{
  "job_id": string,
  "status": "queued",
  "documents_count": number,
  "created_at": string
}

{
  "jobs": [
    {
      "job_id": string,
      "status": "queued" | "processing" | "completed" | "failed",
      "documents_count": number,
      "completed_count": number,
      "created_at": string,
      "completed_at": string|null
    }
  ]
}

{
  "job_id": string,
  "status": "queued" | "processing" | "completed" | "failed",
  "documents_count": number,
  "completed_count": number,
  "failed_count": number,
  "created_at": string,
  "completed_at": string|null,
  "progress_pct": number   // 0.0 - 100.0
}

{
  "job_id": string,
  "results": [
    {
      "compressed": string,
      "original_tokens": number,
      "compressed_tokens": number,
      "savings_pct": number,
      "error": string|null
    }
  ],
  "summary": {
    "total_documents": number,
    "successful": number,
    "failed": number,
    "total_tokens_saved": number,
    "avg_savings_pct": number
  }
}

{
  "period": string,           // "YYYY-MM"
  "total_compressions": number,
  "total_tokens_saved": number,
  "projects": [
    {
      "project_id": string,
      "project_name": string,
      "compressions": number,
      "tokens_saved": number,
      "avg_savings_pct": number
    }
  ]
}

{
  "granularity": "daily" | "weekly",
  "data": [
    {
      "date": string,          // "YYYY-MM-DD"
      "compressions": number,
      "tokens_saved": number,
      "avg_savings_pct": number
    }
  ]
}

Content-Type: text/csv

date,project,compressions,tokens_in,tokens_saved,savings_pct
2026-04-01,backend-docs,142,284000,248000,87.3
2026-04-01,frontend-app,89,178000,151300,85.0
...