API Reference

PolyPortia exposes an OpenAI-compatible REST API at https://polyportia.arachnida-apps.com/v1/. Authenticate with a personal API key from the API Keys page.

Authentication

Pass your API key as a Bearer token in the Authorization header.

Authorization: Bearer pp_xxxxxxxxxxxxxxxxxxxx

Chat completions

Fully compatible with OpenAI's POST /v1/chat/completions. The model field accepts any name listed in GET /v1/models — including councils (e.g. triad).

curl https://polyportia.arachnida-apps.com/v1/chat/completions \
  -H "Authorization: Bearer pp_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "fast",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Streaming

Set "stream": true for Server-Sent Events (SSE). Compatible with the OpenAI streaming protocol including data: [DONE] termination.

curl https://polyportia.arachnida-apps.com/v1/chat/completions \
  -H "Authorization: Bearer pp_your_key" \
  -H "Content-Type: application/json" \
  --no-buffer \
  -d '{
    "model": "balanced",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": true
  }'

Models

List available models and councils.

curl https://polyportia.arachnida-apps.com/v1/models \
  -H "Authorization: Bearer pp_your_key"

PolyPortia extensions

Include a polyportia object in your request for advanced controls:

{
  "model": "fast",
  "messages": [...],
  "polyportia": {
    "budget_usd": 0.05,
    "include_cost": true,
    "retry": { "max_retries": 3 }
  }
}

Response headers

Every response includes PolyPortia metadata headers:

X-PolyPortia-Trace-ID:           trace-abc123
X-PolyPortia-Cost-USD:           0.000000
X-PolyPortia-Cost-Predicted-USD: 0.000000