Build against editable routing presets, not provider route trivia.

CPEN follows the OpenRouter integration pattern: one base URL, OpenAI-compatible chat requests, stable model aliases, credits, and route metadata in every response. This page covers authentication, routing budgets, endpoints, and copy-paste examples.

Base URLhttps://cpenrouter.space/v1

Quickstart

Drop-in OpenAI SDK swap

Point your existing OpenAI client at CPEN. Keep messages and streaming flags; add a routing block when you need price control.

curlPOST /v1/chat/completions

curl https://cpenrouter.space/v1/chat/completions \
  -H "authorization: Bearer cpen_live_..." \
  -H "content-type: application/json" \
  -d '{
    "model": "cpen/middle",
    "messages": [{"role": "user", "content": "summarize this row"}],
    "routing": {
      "currency": "USD",
      "min_total_per_1m": "0.05",
      "max_total_per_1m": "0.30",
      "rpm_cap": 60,
      "strategy": "balanced",
      "continuity_mode": "stay_within_cap"
    }
  }'

OpenAI SDK (Node / Python)https://cpenrouter.space/v1

const client = new OpenAI({
  baseURL: "https://cpenrouter.space/v1",
  apiKey: process.env.CPEN_API_KEY
});

await client.chat.completions.create({
  model: "cpen/middle",
  messages: [{ role: "user", content: row }],
  routing: {
    currency: "USD",
    min_total_per_1m: "0.05",
    max_total_per_1m: "0.30",
    rpm_cap: 60,
    strategy: "balanced"
  }
});

Intelligence tiers

Public model aliases stay stable as provider offers change. Pick a tier, set a USD ceiling, and CPEN selects a live route inside the cap.

Alias	Level	Use case	USD / 1M	Status
cpen/low	Low	Bulk cleanup, simple rewrites, tagging, low-risk automation.	$0.02 – $0.20	available
cpen/middle	Middle	Extraction, classification, support chat, app assistants.	$0.05 – $0.35	available
cpen/high	High	Reasoning-heavy tasks, high-value generation, important decisions.	$0.20 – $1.00	planned

Authentication

OAuth signup grants the launch credit path. Paid API calls use cpen_live API keys issued from the account dashboard.

Authorization: Bearer cpen_live_...

Price caps

Caps are declared in USD. CPEN rejects the request when no live preset route fits the cap.

"routing": {
  "currency": "USD",
  "max_input_per_1m": "0.03",
  "max_output_per_1m": "0.15"
}

Displayed price

Public API responses and UI tables show the customer-facing USD price. Route selection uses the input and output caps you send.

visible_input_price <= max_input_per_1m
visible_output_price <= max_output_per_1m

Guest playground

Try route selection without an account at 2 RPM. Signed-in users issue cpen_live keys from the account dashboard.

Playground: /playground
Auth header: Authorization: Bearer cpen_live_...

Routing budget

Every chat and extraction request accepts an optional routing object. Caps are evaluated in USD per 1M tokens before dispatch.

Field	Type	Description
`currency`	string	Must be USD. Other currencies are rejected.
`max_input_per_1m`	decimal	Maximum input price per 1M tokens.
`max_output_per_1m`	decimal	Maximum output price per 1M tokens.
`max_total_per_1m`	decimal	Shortcut cap on combined input + output per 1M.
`min_total_per_1m`	decimal	Optional floor when you want a quality floor.
`rpm_cap`	integer	Per-key requests-per-minute ceiling for the call.
`strategy`	enum	cheapest \| balanced \| continuity
`continuity_mode`	enum	stay_within_cap \| temporary_escalation
`allow_temporary_high_price`	boolean	Allows one-shot escalation above cap when continuity is prioritized.

HTTP endpoints

All JSON APIs live under the same base URL. Authenticated routes require a cpen_live API key.

Method	Path	Purpose
POST	`/v1/chat/completions`	OpenAI-compatible chat with route metadata.
POST	`/v1/extractions`	Structured JSON extraction with schema validation.
GET	`/v1/status/routes`	Tier availability, candidate counts, and cheapest live route.
GET	`/v1/billing/status`	Credit packs and checkout provider state.
GET	`/health`	Liveness probe for load balancers.

Route metadata in responses

Successful chat completions include cpen_status and cpen_route. Log route_id and nested route prices for audit trails instead of provider offer names.

{
  "id": "chatcmpl_...",
  "object": "chat.completion",
  "model": "cpen/middle",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "..." },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 42, "completion_tokens": 18, "total_tokens": 60 },
  "cpen_status": "completed",
  "cpen_route": {
    "alias": "cpen/middle",
    "task": "chat",
    "route_id": "route_mid_01",
    "intelligence_level": "middle",
    "model_family": "gpt-mini-or-flash-class",
    "input_per_1m": "0.04",
    "output_per_1m": "0.24",
    "currency": "USD",
    "input_usd_per_1m": "0.04",
    "output_usd_per_1m": "0.24",
    "estimated_cost_usd_per_1m": "0.18",
    "cpen_fee_rate": "0",
    "estimated_total_usd_per_1m": "0.18",
    "rpm_cap": 60,
    "strategy": "balanced",
    "continuity_mode": "stay_within_cap",
    "escalation_allowed": false,
    "reason": "Selected the cheapest live middle-tier route inside the declared cap."
  }
}

Common errors

Status	Meaning
401	Missing or invalid API key.
402	No live route fits the declared USD cap.
429	RPM cap exceeded for the key or guest playground.
503	Route service unavailable or tier in outage.

{
  "detail": "No route available under budget"
}

Extraction request

Send natural language plus a JSON Schema. CPEN routes the call like chat, returns parsed JSON in output, and attaches the same route metadata.

POST /v1/extractions
{
  "model": "cpen/middle",
  "input": "Alice paid 12.50 USD for a notebook.",
  "schema": {
    "type": "object",
    "properties": {
      "buyer": { "type": "string" },
      "amount_usd": { "type": "number" }
    }
  },
  "routing": {
    "currency": "USD",
    "min_total_per_1m": "0.05",
    "max_total_per_1m": "0.30",
    "rpm_cap": 60,
    "strategy": "balanced",
    "continuity_mode": "stay_within_cap"
  }
}