Documentation

The pool API is OpenAI-compatible.

Base URL https://api.providers.policate.marcllort.com/v1. If your client speaks OpenAI, it already speaks Policate Pool.

Quickstart

Create an account, add credits, and generate a pool_live_ key. Then point any OpenAI-compatible client at the pool.

bash

export OPENAI_BASE_URL="https://api.providers.policate.marcllort.com/v1"
export OPENAI_API_KEY="pool_live_xxxxx"

curl "$OPENAI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "qwen2.5-coder-32b", "messages": [{"role":"user","content":"Hello"}]}'

The same base URL works with any OpenAI SDK — no code changes beyond the two environment variables:

python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.providers.policate.marcllort.com/v1",
    api_key="pool_live_xxxxx",
)

resp = client.chat.completions.create(
    model="qwen2.5-coder-32b",
    messages=[{"role": "user", "content": "Write tests for this"}],
)
print(resp.choices[0].message.content)

Authentication

All authenticated endpoints require a Bearer token in the Authorization header. Create a token in the developer portal — the raw pool_live_ key is shown once and stored only as a hash.

http

Authorization: Bearer pool_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Endpoints

POST/v1/chat/completionsauth required

OpenAI-compatible chat completions. Supports streaming via "stream": true. The pool routes to the best available provider; if all are busy it falls back to Policate’s own Bedrock connection at pool prices — you always get a response.

bash

curl "$OPENAI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer pool_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen2.5-coder-32b",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": false
  }'

POST/v1/tokensauth required

Create a new pool API key. The raw token is returned once — store it securely.

bash

curl "$OPENAI_BASE_URL/tokens" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"displayName": "production-key"}'

GET/v1/pool/statuspublic

Public pool health — active providers, models available, average latency, and fallback rate. No auth required.

json

{
  "activeProviders": 147,
  "modelsAvailable": 12,
  "avgLatencyP95Ms": 1240,
  "fallbackRate": 0.02,
  "byModel": [
    { "modelSlug": "qwen2.5-coder-32b", "providerCount": 23, "avgLatencyP95Ms": 1100 }
  ]
}

Models

GET/v1/modelspublic

Returns the public model directory — aggregated active providers per model, with pricing and average trust scores. No auth required.

json

[
  {
    "slug": "qwen2.5-coder-32b",
    "displayName": "Qwen 2.5 Coder 32B",
    "family": "qwen",
    "parameterCount": "32B",
    "contextWindow": 32768,
    "useCases": ["coding"],
    "providerCount": 23,
    "minPricePer1mTokensUsd": 0.74,
    "avgTrustScore": 91
  }
]

Errors

Errors follow the OpenAI-style envelope with a stable code and a human-readable message.

json

{
  "error": {
    "code": "insufficient_credits",
    "message": "Credit balance is below the minimum required for this request."
  }
}

401unauthorizedInvalid or missing token.

402insufficient_creditsTop up your balance.

429rate_limit_exceededToo many requests — back off.

503no_capacityAll providers busy — retry shortly.

Rate limits

Limits are enforced per API key and scale with your credit balance and account standing. When you exceed a window the API returns 429 rate_limit_exceeded with a Retry-After header. Budget caps are enforced independently in real time, so a single key can never overspend its balance.

600

Default RPM

60 / 10s

Burst

per key

Budget cap