API Documentation

Introduction

Prompt Crunch sits between your application and the LLM provider. Long conversational requests are optimized to remove redundant history before being forwarded; cached, short, and coding-agent requests pass through untouched. You get back the exact same response your model would normally produce, billed for fewer input tokens. It is built for conversational products: chat apps, tutoring bots, coaching apps, long-session support.

The core product is API-compatible with both Anthropic and OpenAI. If you already have code that calls anthropic.messages.create() or openai.chat.completions.create(), you only need to change the base URL and add one header. That's it.

Quickstart

Three steps to start saving on your API bill:

1. Sign up and copy your Prompt Crunch API key (format: pc_live_...) - it is shown once at signup. Lost it? Use "Generate new key" in your dashboard to generate a fresh one
2. Change your SDK's base_url to https://api.promptcrunch.dev
3. Add the X-PromptCrunch-Key header to every request

import anthropic

client = anthropic.Anthropic(
    api_key="your-anthropic-key",
    base_url="https://api.promptcrunch.dev",
    default_headers={
        "X-PromptCrunch-Key": "pc_live_...",
    },
)

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.content[0].text)

from openai import OpenAI

client = OpenAI(
    api_key="your-openai-key",
    base_url="https://api.promptcrunch.dev/v1",
    default_headers={
        "X-PromptCrunch-Key": "pc_live_...",
    },
)

response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)

# Anthropic Messages API
curl https://api.promptcrunch.dev/v1/messages \
  -H "x-api-key: your-anthropic-key" \
  -H "X-PromptCrunch-Key: pc_live_..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Authentication

Every request to Prompt Crunch needs two API keys:

Base URL

Prompt Crunch exposes three endpoints that mirror Anthropic and OpenAI exactly. Point your SDK's base URL at whichever matches your provider:

# Anthropic SDK
base_url = "https://api.promptcrunch.dev"

# OpenAI SDK (note the /v1 suffix, mirrors openai.com)
base_url = "https://api.promptcrunch.dev/v1"

Anthropic Messages

curl https://api.promptcrunch.dev/v1/messages \
  -H "x-api-key: sk-ant-..." \
  -H "X-PromptCrunch-Key: pc_live_..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 2048,
    "system": "You are a senior engineer.",
    "messages": [
      {"role": "user", "content": "Explain consistent hashing."}
    ]
  }'

{
  "id": "msg_01Wn7EE8WV4ehpNSXssYudKh",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-4-6",
  "content": [
    {"type": "text", "text": "Consistent hashing is a..."}
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 489,
    "output_tokens": 362
  },
  "_promptcrunch": {
    "status": "passthrough",
    "original_tokens": 506,
    "tokens_saved": 0,
    "savings_pct": 0,
    "credit_remaining_usd": 13.47
  }
}

OpenAI Chat Completions

curl https://api.promptcrunch.dev/v1/chat/completions \
  -H "Authorization: Bearer sk-..." \
  -H "X-PromptCrunch-Key: pc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is a Merkle tree?"}
    ],
    "max_completion_tokens": 4096
  }'

{
  "id": "chatcmpl-AbCdEf...",
  "object": "chat.completion",
  "created": 1712345678,
  "model": "gpt-5.5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "A Merkle tree is a..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 111,
    "completion_tokens": 453,
    "total_tokens": 564
  },
  "_promptcrunch": {
    "status": "passthrough",
    "original_tokens": 138,
    "tokens_saved": 0,
    "savings_pct": 0
  }
}

OpenAI Responses API

curl https://api.promptcrunch.dev/v1/responses \
  -H "Authorization: Bearer sk-..." \
  -H "X-PromptCrunch-Key: pc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5-pro",
    "input": "Explain how Raft consensus works."
  }'

Streaming

Pass stream: true in your request body. Your existing SDK code doesn't need any modifications.

import anthropic

client = anthropic.Anthropic(
    api_key="sk-ant-...",
    base_url="https://api.promptcrunch.dev",
    default_headers={"X-PromptCrunch-Key": "pc_live_..."},
)

with client.messages.stream(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Tell me a story."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

from openai import OpenAI

client = OpenAI(
    api_key="sk-...",
    base_url="https://api.promptcrunch.dev/v1",
    default_headers={"X-PromptCrunch-Key": "pc_live_..."},
)

stream = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Tell me a story."}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

curl https://api.promptcrunch.dev/v1/messages \
  -H "x-api-key: sk-ant-..." \
  -H "X-PromptCrunch-Key: pc_live_..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -N \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "stream": true,
    "messages": [{"role": "user", "content": "Tell me a story."}]
  }'

Response metadata

Every non-streaming response includes a _promptcrunch object appended to the JSON. This tells you what Prompt Crunch did with your request.

"_promptcrunch": {
  "status": "optimized",
  "original_tokens": 12796,
  "tokens_saved": 8362,
  "savings_pct": 65.3,
  "prompt_score": {"score": 8, "reason": "Clear and specific"},
  "credit_remaining_usd": 13.47
}

Response headers

Every response carries the same metadata on response headers, prefixed with x-promptcrunch-. Use these when you can't or don't want to parse the JSON body.

Bypass optimization

Sometimes you want to skip optimization entirely: short prompts, A/B testing, or debugging. Pass the bypass header:

"X-PromptCrunch-Bypass": "true"

The request passes straight through to the provider with no optimization and no processing overhead.

Automatic passthrough

Prompt Crunch is designed to be never worse than calling your provider directly. Some requests are deliberately forwarded untouched, with _promptcrunch.status: "passthrough":

Concise output mode Beta

Output tokens cost roughly 5x input tokens, and most models answer longer than many products need. Send the header X-PromptCrunch-Output: concise on /v1/messages or /v1/chat/completions and we append a short, fixed terse-output instruction to your system prompt. The model itself writes less: typically 20-50% fewer output tokens on prose answers.

What this deliberately is not: we do not rewrite, truncate, or re-expand responses with another model, and streaming is untouched. The instruction is a single stable constant, so it cannot churn your prompt-cache prefix between turns (an existing cached prefix re-warms once, then stays stable). It changes your product's voice, which is why it is opt-in and will stay opt-in.

Test it against your own quality bar before enabling in production. Turning the header on or off mid-conversation changes the prompt, which resets optimization checkpoints for that conversation.

Response cache Beta

For workloads that see the same request more than once (FAQ bots, tutoring drills, canned flows), send X-PromptCrunch-Cache: true and identical requests are served from our cache at $0 provider cost. The cached response is byte-identical to what the provider returned the first time.

The cache key covers your full request (model, messages, and parameters), scoped to your account, so a cache hit only ever happens on a genuinely identical repeat. Default TTL is 1 hour; pass an integer instead of true to set seconds (for example X-PromptCrunch-Cache: 300), capped at 24 hours. Non-streaming requests only. A served hit carries X-PromptCrunch-Cache: hit and _promptcrunch.status: "cache_hit".

Off by default, because caching a response only makes sense when your request is deterministic and a stale-for-up-to-TTL answer is acceptable. Do not enable it on requests whose answer depends on the current time or on per-request randomness.

Zero-retention mode

By default, Prompt Crunch holds a small encrypted optimization state in memory for up to one hour so repeat conversations don't reprocess from scratch. For teams handling regulated data, you can flip on zero-retention mode in your dashboard. When enabled:

• No conversation content is cached on our servers, not even encrypted
• Every request is independently optimized
• For incremental optimization across turns, you pass a client state blob yourself

Client state blob

In zero-retention mode (or any time you want stateless incremental optimization), you can echo back a compact, encrypted state blob between turns. The blob is gzipped then AES-256-GCM encrypted with a per-account key, so it's authenticated (invalid or tampered blobs are safely ignored and the request is reprocessed from scratch) and contains no readable conversation data.

How it works

1. Make your first request. The response includes _promptcrunch.state, a short opaque string.
2. Store it client-side.
3. On your next request, send it back via the X-PromptCrunch-State header.
4. Prompt Crunch picks up where you left off.

# Turn 1: no state yet
resp = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=conversation,
)
state = resp.model_extra.get("_promptcrunch", {}).get("state")

# Turn 2+: pass the state back
client = anthropic.Anthropic(
    api_key="sk-ant-...",
    base_url="https://api.promptcrunch.dev",
    default_headers={
        "X-PromptCrunch-Key": "pc_live_...",
        "X-PromptCrunch-State": state,
    },
)
resp = client.messages.create(...)

# Turn 1: no state yet
resp = client.chat.completions.create(
    model="gpt-5.5",
    messages=conversation,
)
state = resp.model_extra.get("_promptcrunch", {}).get("state")

# Turn 2+: pass the state back
client = OpenAI(
    api_key="sk-...",
    base_url="https://api.promptcrunch.dev/v1",
    default_headers={
        "X-PromptCrunch-Key": "pc_live_...",
        "X-PromptCrunch-State": state,
    },
)
resp = client.chat.completions.create(...)

# Turn 1: capture the state from the response
STATE=$(curl -s https://api.promptcrunch.dev/v1/messages \
  -H "x-api-key: sk-ant-..." \
  -H "X-PromptCrunch-Key: pc_live_..." \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"claude-sonnet-4-6","max_tokens":1024,"messages":[...]}' \
  | jq -r '._promptcrunch.state')

# Turn 2+: send it back via header
curl https://api.promptcrunch.dev/v1/messages \
  -H "x-api-key: sk-ant-..." \
  -H "X-PromptCrunch-Key: pc_live_..." \
  -H "X-PromptCrunch-State: $STATE" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"claude-sonnet-4-6","max_tokens":1024,"messages":[...]}'

Get account Auth

curl https://api.promptcrunch.dev/api/me \
  -H "X-PromptCrunch-Key: pc_live_..."

{
  "user": {
    "id": 42,
    "email": "[email protected]",
    "name": "Jane Doe",
    "plan_status": "trial",
    "trial_credit_usd": 5.00,
    "trial_used_usd": 0.53,
    "trial_credit_remaining_usd": 4.47,
    "zero_retention": false
  },
  "stats": {
    "total_requests": 874,
    "total_tokens_saved": 10800000,
    "savings_percentage": 62.3
  },
  "billing": {
    "gross_savings_usd": 27.80
  }
}

Usage history Auth

Warnings

Every proxy response carries a _promptcrunch.warnings array with any actionable signals about your account. Warnings are non-blocking: your request still succeeds, but we flag things you probably want to know about (like running low on credit).

Where warnings appear

• JSON body: _promptcrunch.warnings with full list of code, message, and action URL
• Response headers: X-PromptCrunch-Warning (primary code) and X-PromptCrunch-Warning-Message (human-readable text)
• Dashboard: a persistent banner at the top of your dashboard
• Email: billing warnings are sent by email, rate-limited to once per 24 hours per type

Warning codes

Example response with a warning

{
  "id": "msg_01...",
  "type": "message",
  "content": [{"type": "text", "text": "..."}],
  "_promptcrunch": {
    "status": "optimized",
    "original_tokens": 12796,
    "tokens_saved": 8362,
    "savings_pct": 65.3,
    "credit_remaining_usd": 0.47,
    "warnings": [
      {
        "code": "credit_low",
        "message": "Credit low: $0.47 remaining. Top up to keep optimization running.",
        "severity": "warning",
        "action_url": "https://promptcrunch.dev/my#billing"
      }
    ]
  }
}

Example client code

A quick pattern for handling warnings in your client:

def call_with_warnings(messages):
    resp = client.messages.create(model="...", messages=messages)
    meta = resp.model_extra.get("_promptcrunch", {})
    for warning in meta.get("warnings", []):
        logger.warning(f"Prompt Crunch: {warning['code']} - {warning['message']}")
        if warning["code"] == "credit_exhausted":
            alert_ops_team("LLM proxy credit exhausted")
    return resp

Status codes

Prompt Crunch uses conventional HTTP status codes. Any status code returned by the upstream provider is passed back to you unchanged, along with the provider's original error body.

Error handling

If our optimization pipeline fails for any reason, we never drop your request. We forward your original, unmodified messages to the provider and return the response as normal, with _promptcrunch.status: "error". You'll miss the savings on that one request, but your application keeps working.

Errors from the upstream provider are passed back verbatim. If Anthropic returns a 429 rate-limit error, you'll see the exact Anthropic error body with HTTP 429.

{
  "detail": "Invalid or inactive Prompt Crunch API key"
}

Rate limits

Prompt Crunch applies its own per-user rate limits on top of whatever limits your provider enforces:

Need higher limits? Get in touch.

Coding agents (Claude Code, Codex)

Plainly: coding-agent traffic mostly passes through Prompt Crunch untouched. In our benchmarks, Claude Code and Codex sessions saved 0-7%. The conversation is almost entirely code, file contents, and tool output, which Prompt Crunch preserves verbatim, and provider prompt caching already covers the repeated system prompt. Prompt Crunch's job on this traffic is to stay out of the way, and it does: caching breakpoints, tools, and streaming are forwarded intact.

If coding agents are your main workload, you don't need Prompt Crunch. The setup below is here for completeness, for mixed workloads where the same key also serves conversational traffic.

Requirements

• Your Anthropic API key (the one billed for Claude Code's calls today)
• Your Prompt Crunch API key (pc_live_...) - copied at signup, or generate a fresh one via "Generate new key" in the dashboard
• Claude Code 1.0 or newer

Setup

Open ~/.claude/settings.json (create it if missing) and add the env block. Claude Code reads these on every launch and applies them to every request:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.promptcrunch.dev",
    "ANTHROPIC_API_KEY": "sk-ant-...",
    "ANTHROPIC_CUSTOM_HEADERS": "X-PromptCrunch-Key: pc_live_...\nx-promptcrunch-response: minimal"
  }
}

Restart Claude Code. From this point every request flows through Prompt Crunch; you'll see requests appear on your dashboard, mostly with status passthrough. That is the expected behavior for this workload.

What Prompt Crunch does to Claude Code traffic

• Preserves prompt caching. Requests that include cache_control breakpoints (Claude Code does, on its system prompt) pass through entirely untouched so cache hits stay cheap. We never strip or move breakpoints.
• Forwards tools verbatim. Your tools array, tool_choice, and tool_use / tool_result ID chains pass through byte-for-byte.
• Streams transparently. SSE chunks from Anthropic are forwarded as-is; we don't buffer, parse, or re-emit.
• Compacts long history. When a conversation grows past the cached prefix and into uncached territory (the part of your prompt that's actually expensive on every turn), we summarize it before forwarding.

Verifying it works

After you restart Claude Code, run any command and check the response headers (Claude Code logs them at debug level):

# In a terminal
ANTHROPIC_LOG=info claude

# In Claude Code, run any prompt. Look for:
# x-promptcrunch-status: passthrough | optimized
# x-promptcrunch-original-tokens: 14821
# x-promptcrunch-saved: 8240

Or just open the dashboard after a session. Every Claude Code request shows up in the request log with the model, status, and tokens saved.

Limitations

Troubleshooting

Supported models

Prompt Crunch is model-agnostic. Any model accessible via the Anthropic or OpenAI APIs works. Below are the models we've benchmarked and explicitly tuned for:

Anthropic

• claude-opus-4-6-*: best quality, highest savings
• claude-sonnet-4-6-*: recommended for most workloads
• claude-haiku-4-5-*: fastest, lowest cost per token

OpenAI

• gpt-5.5, gpt-5.5-thinking, gpt-5.5-pro, gpt-5-mini
• gpt-5.2, gpt-5.2-codex
• gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-4
• o3, o4-mini (reasoning models)