Getting Started

Introduction Authentication Error Codes Rate Limits

Core — ZPL Engine

POST /compute GET /sweep

AI Filter

POST /ai/chat POST /ai/proxy POST /ai/analyze

API Keys

GET /api-keys POST /api-keys DELETE /api-keys/{id}

Account

GET /auth/me GET /usage/stats

Billing

POST /billing/checkout POST /billing/topup GET /billing/topups POST /billing/cancel POST /billing/portal

ZPL API Reference

Complete reference for all Zero Point Logic endpoints. Use the ZPL engine to generate mathematically balanced sequences, or the AI filter to analyze and rebalance text responses for neutrality.

Base URL: https://zpl-backend.onrender.com
Authentication HOW TO AUTHENTICATE
Two authentication methods:

1. API Key — add header X-Api-Key: zpl_your_key_here to every request. Best for server-to-server.

2. JWT Token — add header Authorization: Bearer your_jwt_token. Used after login from web app.

Anonymous — /compute and /sweep work without auth for N≤9 (free tier demo).
JavaScript
Python
cURL
// API Key authentication const response = await fetch('https://zpl-backend.onrender.com/compute', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Api-Key': 'zpl_your_api_key_here' }, body: JSON.stringify({ bias: 0.5, N: 9, samples: 1000 }) });
Error Codes HTTP STATUS CODES
200OK — request successful
201Created — resource created successfully
400Bad Request — invalid parameters
401Unauthorized — missing or invalid token/key
403Forbidden — plan does not allow this action
404Not Found — resource does not exist
429Too Many Requests — rate limit or monthly limit reached
502Bad Gateway — upstream provider (AI) error
503Service Unavailable — feature not configured
All errors return JSON: {"detail": "Error message here"}
Rate Limits PLAN LIMITS
Plan/compute + /sweep/ai/chat (Groq)/ai/proxy (own key)
AnonymousN≤9 only——
Free1,000 / month50 / month—
Basic50,000 / month500 / month100 / month
Pro500,000 / month5,000 / month1,000 / month
EnterpriseUnlimitedUnlimitedUnlimited
ZPL Engine CORE ENDPOINTS
POST /compute Generate ZPL-balanced sequence Anonymous N≤9

Takes a bias value and generates a sequence of N numbers corrected to perfect equilibrium by the ZPL engine.

ParameterTypeDescription
bias*floatInput bias value between 0.0 and 1.0
NoptintSequence size. One of: 3, 9, 16, 25, 32, 64. Default: 9
samplesoptintNumber of iterations (100–50000). Default: 1000
Request
Response
POST /compute Content-Type: application/json X-Api-Key: zpl_your_key { "bias": 0.3, "N": 9, "samples": 1000 }
GET /sweep Sweep bias range, returns AIN scores Anonymous N≤9

Runs ZPL across a range of bias values (0.0 to 1.0) and returns AIN scores for each step. Useful for visualizations and analysis.

ParameterTypeDescription
NoptintSequence size. Default: 9
samplesoptintIterations per step. Default: 500
stepsoptintHow many bias values to test (5–50). Default: 20
GET /sweep?N=9&samples=500&steps=20 X-Api-Key: zpl_your_key
AI Filter BIAS-NEUTRAL AI
POST /ai/chat ZPL AI Chat — uses server Groq key JWT / API Key

Chat with Groq-hosted AI (Llama, Qwen, Mixtral) filtered through ZPL. No user API key needed — uses ZPL's server key. Every response includes an AIN neutrality score.

ParameterTypeDescription
messages*arrayArray of {role, content} objects. Roles: user, assistant, system
modeloptstringGroq model ID. Default: llama-3.1-8b-instant
zpl_optionsoptobject{"filter_mode": "analyze|rebalance|strict"}
Filter modes:
• analyze — return response + AIN score, no changes
• rebalance — if AIN < 0.4, retry with neutralizing prompt
• strict — retry up to 3x until AIN > 0.7
JavaScript
Python
Response
const res = await fetch('https://zpl-backend.onrender.com/ai/chat', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Api-Key': 'zpl_your_key' }, body: JSON.stringify({ messages: [{ role: 'user', content: 'Is AI dangerous?' }], model: 'llama-3.3-70b-versatile', zpl_options: { filter_mode: 'rebalance' } }) }); const data = await res.json(); console.log(data.response); // AI answer console.log(data.zpl_filter.ain_score); // 0.0 – 1.0
POST /ai/analyze Analyze any text for bias — no AI call JWT / API Key

Run ZPL bias analysis on any text. Returns AIN score, bias direction, and word ratios. No AI provider needed.

ParameterTypeDescription
text*stringText to analyze. Max 10,000 characters.
POST /ai/analyze X-Api-Key: zpl_your_key { "text": "Electric cars are completely useless and a total scam." }
POST /ai/proxy Proxy to OpenAI / Anthropic / Groq with ZPL filter Basic+ plan

Forward messages to any AI provider using your own API key, filtered through ZPL. The user's key is never stored or logged.

ParameterTypeDescription
provider*stringOne of: openai, anthropic, groq
user_api_key*stringYour API key for the chosen provider
messages*arrayArray of {role, content} message objects
modeloptstringModel ID for the chosen provider
zpl_optionsoptobject{"filter_mode": "analyze|rebalance|strict"}
API Keys KEY MANAGEMENT
GET /api-keys List all your API keys JWT required
GET /api-keys Authorization: Bearer your_jwt_token
POST /api-keys Create a new API key JWT required
Important: The full API key is only returned once at creation. Store it securely — it cannot be retrieved again.
ParameterTypeDescription
nameoptstringLabel for this key. Default: "Default Key"
POST /api-keys Authorization: Bearer your_jwt_token Content-Type: application/json { "name": "My Game Server" } // Response: { "id": 42, "name": "My Game Server", "key": "zpl_abc123...", // SAVE THIS — shown once only "key_prefix": "zpl_abc1", "created_at": "2026-03-29T..." }
DELETE /api-keys/{key_id} Revoke an API key JWT required
DELETE /api-keys/42 Authorization: Bearer your_jwt_token
Account USER ENDPOINTS
GET /auth/me Get current user info and plan JWT required
GET /auth/me Authorization: Bearer your_jwt_token // Response: { "id": 1, "email": "you@example.com", "name": "Your Name", "plan": "free", "is_active": true }
GET /usage/stats Get your usage statistics JWT / API Key
GET /usage/stats X-Api-Key: zpl_your_key
Billing SUBSCRIPTION & TOP-UPS
POST /billing/checkout Create a Stripe checkout session JWT required
POST /billing/checkout Authorization: Bearer your_jwt_token Content-Type: application/json { "plan": "pro" // basic | pro | gamepro | studio | enterprise | enterprise_xl } // Response: { "checkout_url": "https://checkout.stripe.com/pay/cs_..." }
POST /billing/topup Buy a one-time compute top-up JWT required
POST /billing/topup Authorization: Bearer your_jwt_token Content-Type: application/json { "topup": "topup_10k" // topup_10k (€4.99) → +10K compute, +200 AI calls // topup_25k (€9.99) → +25K compute, +500 AI calls // topup_50k (€17.99) → +50K compute, +1K AI calls // topup_100k (€29.99)→ +100K compute, +2K AI calls // topup_500k (€99.99)→ +500K compute, +10K AI calls // topup_2m (€349.99) → +2M compute, +40K AI calls } // Response: { "checkout_url": "https://checkout.stripe.com/pay/cs_..." }
GET /billing/topups List available top-up packages JWT required
GET /billing/topups Authorization: Bearer your_jwt_token // Response: list of available top-up packs for your plan [ { "id": "topup_10k", "compute": 10000, "ai_calls": 200, "price_eur": 4.99 }, { "id": "topup_25k", "compute": 25000, "ai_calls": 500, "price_eur": 9.99 } ]
POST /billing/cancel Cancel current subscription JWT required
POST /billing/cancel Authorization: Bearer your_jwt_token // Cancels at end of current billing period. // Response: { "status": "cancelled", "effective": "end_of_period" }
POST /billing/portal Open Stripe customer portal JWT required
POST /billing/portal Authorization: Bearer your_jwt_token // Response: { "portal_url": "https://billing.stripe.com/session/..." }