API Documentation

Overview

Every call to /distill follows the same pattern:

1. Authenticate with an API key
2. POST a messages array with a strategy ID
3. Receive the distilled messages array + metadata
4. Drop the output into your next LLM call

contextspa never touches your downstream LLM. It transforms context and gets out of the way.

Authentication

All requests (except GET /strategies) require an API key sent as a Bearer token:

Authorization: Bearer csp_<your-api-key>

API keys are prefixed csp_. Keys are shown once on creation — store them securely. If lost, generate a new one from your account page.

Quickstart

curl -X POST https://contextspa.com/api/distill \
  -H "Authorization: Bearer csp_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "How do I reverse a linked list?"},
      {"role": "assistant", "content": "You can reverse a linked list iteratively by..."}
    ],
    "strategy_id": "technical_dense"
  }'

GET /health

Liveness and dependency check. Always returns HTTP 200 — inspect the body for degraded state. No authentication required.

Response (200)

{
  "status": "ok",
  "version": "0.1.0",
  "checks": {
    "storage_reachable": true,
    "gemini_key_present": true,
    "stripe_key_present": true
  }
}

When storage_reachable is false, the API will fail on any call that reads or writes user data. The status field will be "degraded".

POST /distill

Transform a messages array using a named strategy. This is the core endpoint.

Request body

* Provide either messages or text — at least one is required.

Example request

{
  "messages": [
    {"role": "user", "content": "..."},
    {"role": "assistant", "content": "..."}
  ],
  "strategy_id": "technical_dense",
  "inject": "preserve all mentions of variable authToken exactly as written"
}

Response (200)

{
  "messages": [
    {"role": "user", "content": "..."},
    {"role": "assistant", "content": "..."}
  ],
  "metadata": {
    "strategy_id": "technical_dense",
    "strategy_version": "1.0.0",
    "provider": "gemini-flash",
    "tokens_in": 4200,
    "tokens_out": 610,
    "compression_ratio": 0.145,
    "inject_used": true,
    "call_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Error responses

GET /strategies

List all available strategies. No authentication required.

Response (200)

{
  "strategies": [
    {
      "id": "summarize",
      "name": "Aggressive Summarize",
      "description": "Reduces conversation to decisions, outcomes, and open questions.",
      "tier": "builtin",
      "version": "1.0.0"
    },
    {
      "id": "technical_dense",
      "name": "Technical Dense",
      "description": "Preserves all code, errors, and decisions. Strips conversational filler.",
      "tier": "builtin",
      "version": "1.0.0"
    },
    {
      "id": "extract_decisions",
      "name": "Extract Decisions",
      "description": "Extracts only explicit decisions and their rationale.",
      "tier": "builtin",
      "version": "1.0.0"
    }
  ]
}

GET /strategies/{id}

Get the full config for a single strategy, including its system prompt. No authentication required.

Response (200)

Full strategy object — see Strategy schema below.

Error responses

POST /feedback

Submit a quality rating for a distillation result. Use the call_id from the /distill response metadata.

Request body

Reason categories

Response (204 No Content)

No response body on success.

GET /balance

Get the authenticated user's current credit balance and tier.

Response (200)

{
  "user_id": "...",
  "pricing_tier": "standard",
  "balance_usd": 8.42
}

POST /balance/topup

Initiate a Stripe checkout session to deposit credits.

Request body

Response (200)

{"checkout_url": "https://checkout.stripe.com/..."}

Redirect the user to checkout_url to complete payment. Credits are added after Stripe confirms the payment via webhook.

Strategies

A strategy is a named, versioned JSON config that defines how a messages array is transformed. Strategies are declarative — they contain a system prompt and metadata, not executable code.

Built-in strategies

Strategy schema (key fields)

Community strategy submissions are coming soon. Full schema reference: docs/STRATEGIES.md.

Inject

The optional inject field appends a short instruction to the strategy's system prompt for a single call. Use it when you need a one-off override without creating a new strategy.

"inject": "preserve all mentions of variable authToken exactly as written"

Limits: Max 400 characters. Logged to telemetry. Phrases like "ignore previous instructions" are rejected with HTTP 400.

The inject is appended after the strategy's system prompt with a clear separator. It cannot override the core transformation rules, only extend them.

Errors

All error responses use standard HTTP status codes with a JSON body:

{"detail": "Strategy not found: my_strategy_id"}

The 402 response includes an additional field:

{"detail": "Insufficient credits", "topup_url": "https://contextspa.com/billing"}

Pricing

contextspa uses a prepay credit model. Deposit credits, spend them per call.

Each call costs a platform fee plus token cost × provider rate. Minimum deposit: $5.00. Full pricing details published at first paying customer.

Use GET /balance to check your balance. Use POST /balance/topup to deposit.