PAIRL Gateway Docs

Quick Start

Get up and running in three steps — no SDK, no refactoring.

# pip install anthropic
client = Anthropic(
    base_url="https://api.pairl.dev/v1/proxy/anthropic",
    api_key="sk-ant-...",           # your Anthropic key — unchanged
    default_headers={
        "Authorization": "Bearer pk_live_...",  # your PAIRL key
    }
)

# pip install openai
client = OpenAI(
    base_url="https://api.pairl.dev/v1/proxy/openai",
    api_key="pk_live_...",          # your PAIRL key goes here for OpenAI SDK
    default_headers={
        "X-Provider-Key": "sk-...",  # your OpenAI key
    }
)

# pip install requests
response = requests.post(
    "https://api.pairl.dev/v1/proxy/google/v1beta/models/gemini-2.5-flash:generateContent",
    headers={
        "Authorization": "Bearer pk_live_...",  # your PAIRL key
        "X-Provider-Key": "AIza...",           # your Google API key
        "Content-Type": "application/json",
    },
    json={
        "contents": [{"role": "user", "parts": [{"text": "Hello!"}]}],
        "generationConfig": {"maxOutputTokens": 1024},
    }
)

curl https://api.pairl.dev/v1/proxy/anthropic/v1/messages \
  -H "Authorization: Bearer pk_live_..." \
  -H "X-Provider-Key: sk-ant-..." \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-opus-4-20250514","max_tokens":1024,"messages":[{"role":"user","content":"Hello!"}]}'

curl https://api.pairl.dev/v1/proxy/openai/v1/chat/completions \
  -H "Authorization: Bearer pk_live_..." \
  -H "X-Provider-Key: sk-..." \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hello!"}]}'

curl https://api.pairl.dev/v1/proxy/google/v1beta/models/gemini-2.5-flash:generateContent \
  -H "Authorization: Bearer pk_live_..." \
  -H "X-Provider-Key: AIza..." \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"role":"user","parts":[{"text":"Hello!"}]}],"generationConfig":{"maxOutputTokens":1024}}'

X-PAIRL-Savings-Tokens: 3840
X-PAIRL-Savings-USD: 0.01152
X-PAIRL-Fee-USD: 0.00346
X-PAIRL-Degraded: false

Authentication

Every request to the PAIRL Gateway requires a PAIRL API key passed as a Bearer token.

Authorization: Bearer pk_live_...

Manage your keys at console.pairl.dev → Settings → API Keys. Keys can be created, listed, and revoked at any time.

Compression Modes

Control compression per request using the X-PAIRL-Mode header.

X-PAIRL-Mode: auto

Streaming

Streaming works exactly as it does without the gateway. Set stream: true as usual: the request is compressed, and the model's response is streamed straight back to your client over SSE, token by token. No client changes are needed — an agent loop that already streams keeps streaming.

{ "model": "…", "messages": [ … ], "stream": true }

Tool-Use Compression v1.2

PAIRL v1.2 adds native compression for agentic and tool-use conversations — the highest-volume context in Claude Code, Cursor, and similar workflows. Instead of passing raw tool-call/result chains through unchanged, the gateway compresses them into four compact record types.

New Record Types

Example: compressed 20-turn session

upd{t=proxy_fix,s=t,l=2,m=+,a=i} @rid=a1
#fact task="fix SSE header stripping" @rid=f1
#fact status=completed @rid=f2
#think summary="need to find proxy implementation" @rid=t01
#call tool=Grep pattern="handleProxy" path="/src/" @rid=c01
#ret  call=c01 status=ok matches=3 files="proxy.ts:161,proxy.ts:234,app.ts:558" @rid=r01
#call tool=Read file="/src/proxy.ts" @rid=c02
#ret  call=c02 status=ok lines=450 sig="proxy handler with SSE support" @rid=r02
#think summary="SSE headers stripped by content-encoding logic" @rid=t02
#edit file="/src/proxy.ts" changes=2 summary="fixed SSE header stripping" @rid=d01
#call tool=Bash cmd="npm test" @rid=c03
#ret  call=c03 status=ok summary="42 passed, 0 failed" exit=0 @rid=r03
#cost val=0.03 cur=USD model=claude-opus-4 @rid=k1

Recency window

The last W tool interactions (default W=3) are preserved verbatim so the model retains full detail for its most recent context. Older interactions are compressed to #call/#ret records automatically.

Columnar Record Blocks v1.5

When several records of the same type share a key schema, repeating every key= on each line is pure overhead. A columnar block declares the keys once in a header and lists the values positionally — one row per record.

Verbose vs. columnar

#evid claim="LLM costs decreased 60% in 2025" src=s1 conf=0.85
#evid claim="Multi-agent adoption rose 300%" src=s2 conf=0.90
#evid claim="Transformer alternatives showing promise" src=s3 conf=0.70

# ↓ same data, columnar
#evid[claim,src,conf]
"LLM costs decreased 60% in 2025" s1 0.85
"Multi-agent adoption rose 300%" s2 0.90
"Transformer alternatives showing promise" s3 0.70

Rules

• A field containing spaces or special characters must be "quoted"; each row must have exactly as many fields as the header has columns.
• The block ends at the next line starting with # or a blank line.
• Applies to fixed-schema records (#evid, #quota, #cost, tool records). Not used for #fact/#ref, whose key is itself data.

Extractive Quotes v1.6

Compressed history now quotes your conversation instead of retelling it. Each turn is carried as word-for-word excerpts of what was actually said — [...] marks omitted text. Nothing between the quotes is written by a model.

What it looks like

#u1
#req content="API latency spiked to 800ms P99 after the Redis upgrade. [...] connection pool exhaustion starting at 14:32 UTC." @rid=q1
#a2
#rpt content="Redis 7.2 lowered the default from 10000 to 4096. [...] stuck in CLOSE_WAIT you could hit the limit." @rid=q2

Reading compressed history

• An unmarked #req (user turn) or #rpt (assistant turn) is a quote — its wording is evidence of what was said.
• A record marked mode=cond is a labeled summary — useful, but a retelling, and always recognizable as one.
• Short turns are always carried in full, uncut.

Response Headers

Every proxied response includes these headers so you can observe the impact of each request.

Supported Providers

PAIRL supports Anthropic, OpenAI, and Google. Route to any of them by changing the provider segment of the proxy URL.

Endpoint compatibility

OpenAI — Responses API

The GPT-5.6 family requires the Responses API (/v1/responses) for tool calling with reasoning enabled — /v1/chat/completions rejects that combination. PAIRL supports it natively: same base URL, keep the /responses path. The gateway compresses the input and preserves tools, instructions and reasoning settings — no client changes beyond pointing the base URL at PAIRL.

curl https://api.pairl.dev/v1/proxy/openai/v1/responses \
  -H "Authorization: Bearer pk_live_..." \
  -H "X-Provider-Key: sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6",
    "instructions": "You are a helpful assistant.",
    "input": [{"role": "user", "content": "Hello!"}]
  }'

With the OpenAI SDK, keep base_url=".../v1/proxy/openai" and call client.responses.create(...) exactly as you would against OpenAI directly.

Google — API format

The Google provider uses the native Gemini REST API format. Pass your Google API key via X-Provider-Key and your PAIRL key as Authorization: Bearer.

curl https://api.pairl.dev/v1/proxy/google/v1beta/models/gemini-2.5-flash:generateContent \
  -H "Authorization: Bearer pk_live_..." \
  -H "X-Provider-Key: AIza..." \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"role": "user", "parts": [{"text": "Hello!"}]}],
    "generationConfig": {"maxOutputTokens": 1024}
  }'

Supported models include gemini-2.5-pro, gemini-2.5-flash, gemini-2.0-flash, and gemini-2.0-flash-lite.

Proxy Endpoint

POST https://api.pairl.dev/v1/proxy/{provider}/{path}

Request Headers

Usage API

Query your token savings and cost data programmatically. All endpoints require a key with usage:read scope.

GET /v1/usage/summary?from=2026-02-01&to=2026-02-28

GET /v1/usage/export?from=2026-02-01&to=2026-02-28&format=csv
GET /v1/usage/export?from=2026-02-01&to=2026-02-28&format=json

Billing API

Check your credit balance, view transaction history, and purchase credit top-ups programmatically.

{ "package_id": "credits_50" }

Config API

Adjust gateway behaviour for your account without redeployment.

How Billing Works

PAIRL uses a savings-share model. You pay your AI provider directly (BYOK). PAIRL charges only a fraction of the savings it delivers on each request.

Credits

PAIRL fees are deducted from a prepaid credit balance. Top up at any time from the dashboard or via the Billing API.

Privacy

PAIRL is designed with privacy-by-default. Your prompts and completions are never stored.

What is stored

• + Request ID, timestamp, and API key ID
• + Provider and model name
• + Token counts (original and compressed)
• + Savings amount and PAIRL fee
• + Degraded flag and compression mode used

What is never stored

• − The content of your prompts or messages
• − Model completions or responses
• − Your provider API keys

Known Limitations