Skip to main content
Skip to main content
Sign InGet free API key
Get free API key →

Projects#

RequiresPro, Team, orEnterprise plan.

Organize compression workloads into projects. Each project tracks its own usage stats, making it easy to attribute token savings across teams or applications.

POST/v1/projects

Create a compression project.

AuthBearer token required (Pro / Team / Enterprise)

Request body

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

Response

{
        "id": string,
        "name": string,
        "description": string|null,
        "created_at": string,
        "stats": { "compressions": 0, "tokens_saved": 0 }
      }
curl -X POST https://api.gotcontext.ai/v1/projects \
        -H "Authorization: Bearer gc_your_key_here" \
        -H "Content-Type: application/json" \
        -d '{"name": "backend-docs", "description": "API documentation compression"}'

Error responses

403Requires Pro, Team, or Enterprise plan
422Missing or invalid name
GET/v1/projects

List all projects for the authenticated user.

AuthBearer token required (Pro / Team / Enterprise)

Response

{
        "projects": [
          {
            "id": string,
            "name": string,
            "description": string|null,
            "created_at": string,
            "stats": {
              "compressions": number,
              "tokens_saved": number
            }
          }
        ]
      }
curl https://api.gotcontext.ai/v1/projects \
        -H "Authorization: Bearer gc_your_key_here"
GET/v1/projects/{id}

Get project detail with usage statistics.

AuthBearer token required (Pro / Team / Enterprise)

Response

{
        "id": string,
        "name": string,
        "description": string|null,
        "created_at": string,
        "updated_at": string,
        "stats": {
          "compressions": number,
          "tokens_saved": number,
          "avg_savings_pct": number
        }
      }
curl https://api.gotcontext.ai/v1/projects/YOUR_PROJECT_ID \
        -H "Authorization: Bearer gc_your_key_here"

Error responses

404Project not found
PUT/v1/projects/{id}

Update a project's name or description.

AuthBearer token required (Pro / Team / Enterprise)

Request body

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

Response

{
        "id": string,
        "name": string,
        "description": string|null,
        "updated_at": string
      }
curl -X PUT https://api.gotcontext.ai/v1/projects/YOUR_PROJECT_ID \
        -H "Authorization: Bearer gc_your_key_here" \
        -H "Content-Type: application/json" \
        -d '{"name": "backend-docs-v2"}'

Error responses

404Project not found
403Requires Pro, Team, or Enterprise plan
DELETE/v1/projects/{id}

Delete a project. Compression history is retained but unlinked.

AuthBearer token required (Pro / Team / Enterprise)

Response

{
        "success": true,
        "id": string
      }
curl -X DELETE https://api.gotcontext.ai/v1/projects/YOUR_PROJECT_ID \
        -H "Authorization: Bearer gc_your_key_here"

Error responses

404Project not found
403Requires Pro, Team, or Enterprise plan

Batch Queue#

RequiresTeam orEnterprise plan.

Submit large compression jobs asynchronously. The batch queue processes documents in the background and returns results when complete, ideal for bulk ingestion pipelines.

POST/v1/batch-queue

Submit an async batch compression job. Returns 202 Accepted with a job ID for polling.

AuthBearer token required (Team / Enterprise)

Request body

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

Response

{
        "job_id": string,
        "status": "queued",
        "documents_count": number,
        "created_at": string
      }
curl -X POST https://api.gotcontext.ai/v1/batch-queue \
        -H "Authorization: Bearer gc_your_key_here" \
        -H "Content-Type: application/json" \
        -d '{
          "documents": [
            {"text": "First document..."},
            {"text": "Second document...", "fidelity": "outline"}
          ]
        }'

Error responses

403Requires Team or Enterprise plan
400Empty documents list or more than 500 items
GET/v1/batch-queue

List batch jobs for the authenticated user.

AuthBearer token required (Team / Enterprise)

Response

{
        "jobs": [
          {
            "job_id": string,
            "status": "queued" | "processing" | "completed" | "failed",
            "documents_count": number,
            "completed_count": number,
            "created_at": string,
            "completed_at": string|null
          }
        ]
      }
curl https://api.gotcontext.ai/v1/batch-queue \
        -H "Authorization: Bearer gc_your_key_here"
GET/v1/batch-queue/{id}

Get job status and progress.

AuthBearer token required (Team / Enterprise)

Response

{
        "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
      }
curl https://api.gotcontext.ai/v1/batch-queue/YOUR_JOB_ID \
        -H "Authorization: Bearer gc_your_key_here"

Error responses

404Job not found
GET/v1/batch-queue/{id}/results

Retrieve completed batch results. Only available when status is 'completed'.

AuthBearer token required (Team / Enterprise)

Response

{
        "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
        }
      }
curl https://api.gotcontext.ai/v1/batch-queue/YOUR_JOB_ID/results \
        -H "Authorization: Bearer gc_your_key_here"

Error responses

404Job not found
409Job not yet completed

Analytics#

RequiresTeam orEnterprise plan.

Detailed analytics for compression usage across projects. View per-project breakdowns, track trends over time, and export data for reporting.

GET/v1/analytics/summary

Per-project usage breakdown for the current billing period.

AuthBearer token required (Team / Enterprise)

Response

{
        "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
          }
        ]
      }
curl https://api.gotcontext.ai/v1/analytics/summary \
        -H "Authorization: Bearer gc_your_key_here"

Error responses

403Requires Team or Enterprise plan
GET/v1/analytics/export

Export analytics data as CSV for the specified date range.

AuthBearer token required (Team / Enterprise)

Response

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
      ...
curl "https://api.gotcontext.ai/v1/analytics/export?start=2026-04-01&end=2026-04-14" \
        -H "Authorization: Bearer gc_your_key_here" \
        -o analytics.csv

Error responses

403Requires Team or Enterprise plan
400Invalid date range or missing parameters

Usage#

GET/v1/usage

Monthly compression statistics for the authenticated user. Returns compression counts, token totals, plan limit, and the next reset timestamp.

AuthBearer token required

Response

{
        "period": string,                // "YYYY-MM", e.g. "2026-04"
        "compressions_used": number,
        "compressions_limit": number,    // varies by plan — see plan field
        "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": string,                  // free | pro | team | enterprise
        "rate_limit_per_minute": number  // varies by plan
      }
curl https://api.gotcontext.ai/v1/usage \
        -H "Authorization: Bearer gc_your_key_here"

Rate Limits#

PlanRate limitMonthly compressions
Free10 requests / minute1,000 / month
Pro100 requests / minute50,000 / month
Team100 requests / minute100,000 / month
EnterpriseCustom500,000+ / month
Limits reset monthly · handle 429s
Monthly limits reset at midnight UTC on the 1st of each month. Check GET /v1/usage for your current consumption. When you hit the rate limit, the API responds with HTTP 429 and a Retry-After header. Back off for that many seconds before retrying.

Prompt-Cache Friendliness Score#

POST/v1/audit-cache

Audit how cache-friendly a prompt is for a specific AI provider. Returns a cacheability score, whether the prompt is cache-friendly, actionable recommendations to improve cache hit rates, and estimated savings.

AuthBearer token required
Use this to optimise prompts for provider-specific caching (e.g. Anthropic prompt caching). Higher scores mean better cache utilisation and lower costs.

Request body

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

Response

{
        "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
      }
curl -X POST https://api.gotcontext.ai/v1/audit-cache \
        -H "Authorization: Bearer gc_your_key_here" \
        -H "Content-Type: application/json" \
        -d '{
          "text": "You are a helpful assistant that...",
          "provider": "anthropic"
        }'

Error responses

422Missing or empty text field
401Missing or invalid Bearer token
503Cache audit service not available

Context-Window Utilization Check#

POST/v1/check-budget

Check how much of a model's context window a text would consume. Returns token estimates, percentage used, a status indicator (OK / WARNING / CRITICAL), and a recommendation on whether to compress.

AuthBearer token required
Status thresholds: OK (< 50% used), WARNING (50-80%), CRITICAL (> 80%). Use before sending large documents to an AI model to decide whether compression is needed.

Request body

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

Response

{
        "estimated_tokens": number,
        "context_window": number,
        "pct_used": number,       // e.g. 42.5
        "status": string,         // "OK" | "WARNING" | "CRITICAL"
        "recommendation": string  // human-readable guidance
      }
curl -X POST https://api.gotcontext.ai/v1/check-budget \
        -H "Authorization: Bearer gc_your_key_here" \
        -H "Content-Type: application/json" \
        -d '{
          "text": "Your long document or codebase...",
          "context_window": 200000,
          "model": "claude-opus-4"
        }'

Error responses

422Missing or empty text field
401Missing or invalid Bearer token
503Budget check service not available

Semantic Cache#

Beyond compression we operate a per-account semantic cache: an embedding-similarity index of the last 100 baseline calls. When a new prompt is close enough to a cached one, we return the prior compressed result instead of re-running the pipeline. Additional reduction; not metered against compression quota.

The cache warms up over the first ~100 baseline calls. Typical hit rates after week 1 land in the 15 to 25% range. The per-tenant similarity threshold is tunable via POST /v1/settings/semantic-cache-threshold (Team and Enterprise). Hit telemetry shows up at Billing → Cache-Adjusted Savings.

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.