API Reference

The Policate Pool API is OpenAI-compatible. Base URL: https://api.providers.policate.marcllort.com/v1

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.

http
Authorization: Bearer pool_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

POST /v1/chat/completions

OpenAI-compatible chat completions endpoint. Supports streaming via "stream": true.

bash
curl https://api.providers.policate.marcllort.com/v1/chat/completions \
  -H "Authorization: Bearer pool_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen2.5-coder-7b",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": false
  }'

The pool routes your request to the best available provider for the requested model. If all providers are busy, the request falls back to Policate's own Bedrock connection at pool prices — you always get a response.

GET /v1/models

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

bash
curl https://api.providers.policate.marcllort.com/v1/models

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

GET /v1/pool/status

Public pool health — active provider count, models, average latency. No auth required.

bash
curl https://api.providers.policate.marcllort.com/v1/pool/status

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

POST /v1/tokens

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

bash
curl https://api.providers.policate.marcllort.com/v1/tokens \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"displayName": "production-key"}'

Error format

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

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

401unauthorized — invalid or missing token

402insufficient_credits — top up your balance

429rate_limit_exceeded — too many requests

503no_capacity — all providers busy, retry shortly