API Keys#

Create and manage API keys programmatically. Keys are prefixed gc_ and stored as HMAC-SHA256 hashes. The raw key is returned once on creation and cannot be retrieved again.

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

curl -X POST https://api.gotcontext.ai/v1/keys \
        -H "Authorization: Bearer YOUR_CLERK_JWT" \
        -H "Content-Type: application/json" \
        -d '{"name": "Production server"}'

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

curl https://api.gotcontext.ai/v1/keys \
        -H "Authorization: Bearer YOUR_CLERK_JWT"

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

curl -X DELETE https://api.gotcontext.ai/v1/keys/YOUR_KEY_ID \
        -H "Authorization: Bearer YOUR_CLERK_JWT"

Billing#

Billing is handled by Polar. The checkout and portal endpoints return redirect URLs. Do not call these from server-side code without a user session.

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

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

curl -X POST https://api.gotcontext.ai/v1/billing/checkout \
        -H "Authorization: Bearer YOUR_CLERK_JWT" \
        -H "Content-Type: application/json" \
        -d '{"plan": "pro"}'

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

curl -X POST https://api.gotcontext.ai/v1/billing/portal \
        -H "Authorization: Bearer YOUR_CLERK_JWT"

CLI Output Compressor (git diff, pytest, npm)#

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

curl -X POST https://api.gotcontext.ai/v1/filter-cli \
        -H "Authorization: Bearer gc_your_key_here" \
        -H "Content-Type: application/json" \
        -d '{
          "output": "diff --git a/src/main.py b/src/main.py\n...",
          "command_hint": "git_diff"
        }'

Lifetime Token Savings (account)#

{
        "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
        // Pricing basis: Opus 4.7 input rates ($5/MTok), valued at compression-time.
        // See /pricing for current rates. No model-specific breakdown is returned here.
      }

curl https://api.gotcontext.ai/v1/savings \
        -H "Authorization: Bearer gc_your_key_here"

Per-Account Semantic-Cache Similarity Thresholdv1.4.0#

The semantic-cache uses cosine similarity to match near-duplicate requests. Research (Portkey + Tianpan, April 2026) shows correct-hit and incorrect-hit similarity distributions overlap between ~0.85 and ~0.92, so a single global threshold is wrong for every non-median workload. Two endpoints let each tenant tune their own cutoff.

— no body —

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

curl https://api.gotcontext.ai/v1/settings/semantic-cache-threshold \
        -H "Authorization: Bearer gc_your_key_here"

{ "threshold": 0.92 }

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

curl -X PUT https://api.gotcontext.ai/v1/settings/semantic-cache-threshold \
        -H "Authorization: Bearer gc_your_key_here" \
        -H "Content-Type: application/json" \
        -d '{"threshold": 0.92}'

Cache-Hit Source Breakdown (exact vs semantic)v1.4.0#

GET /v1/usage/by-cache responses now include a by_source object that splits the cache hits by which mechanism matched: the request-hash fastpath (exact) vs. the embedding-distance fallback (semantic). The invariant exact_hits + semantic_hits == semantic_cache.hitsholds across the response window.

{
        "period_days": 30,
        "semantic_cache": { "hits": 15, "misses": 35, "hit_rate": 0.30, … },
        "by_source": {
          "exact_hits": 12,
          "semantic_hits": 3,
          "misses": 35
        },
        …
      }

Dashboards that rendered only the combined hitscounter previously hid which half of the cache was doing the work. The breakdown lets operators see whether a workload is benefiting from fingerprinting (exact) or from embedding-based near-duplicate matching (semantic), and tune the per-tenant threshold (above) accordingly.

Email Deliverabilityv1.28.0#

gotcontext sends transactional emails for account events: welcome, team invites, API key expiry warnings, per-project budget alerts, and usage digests. v1.28.0 adds automatic suppression when a delivery fails permanently.

When Resend reports a hard bounce or spam complaint against your address, POST /webhooks/resend receives the event (Svix-verified), sets users.email_opt_out = true for that address, and stops all subsequent sends. This prevents repeated delivery to an address that has rejected mail, which protects sender reputation for every account on the platform.

What triggers suppression:

• Hard bounce: the destination mail server permanently rejected the address (user does not exist, domain does not accept mail). Resend event type: email.bounced with bounce_type: permanent.
• Spam complaint: the recipient marked the email as spam. Resend event type: email.complained.

Soft bounces (temporary failures, full inbox) do not trigger suppression.

Re-enabling notifications: if your address was suppressed in error (mis-delivered bounce report, overly aggressive spam filter), email support@gotcontext.ai to clear the opt-out flag. There is no self-serve toggle in the dashboard yet. Tracked for a future settings release.

Manual opt-out is available at GET /v1/unsubscribe?token=<signed-token>. Every transactional email includes a signed unsubscribe link in its footer. Visiting it sets email_opt_out = true for that user without requiring authentication.

Where to next