API reference
OpenAI-compatible endpoints and the optional tagging headers.
Endpoints
OpenAI-compatible. Built and tested; base URL https://api.parezen.com/v1 goes live once provider-key protection is confirmed. Providers in the first wave: OpenAI, Anthropic, Google Gemini, Mistral, xAI and DeepSeek, on your own keys.
- POST /chat/completions: chat, with stream: true for server-sent events. Models are catalogue ids (openai/gpt-4.1) or the provider's own name (gpt-4.1). A model Parezen cannot price is refused.
- GET /models: the catalogue models whose provider key you have connected.
- POST /embeddings, POST /audio/transcriptions, POST /audio/speech, POST /images/generations and POST /videos would use the same OpenAI-compatible shape for embeddings, speech-to-text, speech, images and video. This site does not proxy those calls and does not call a provider.
- POST /tasks/{traceId}/outcome records whether the task succeeded. Planned for months 3–4.
Outcome
curl -X POST https://api.parezen.com/v1/tasks/trace_example/outcome \
-H "Authorization: Bearer $PAREZEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"succeeded": true}'
Headers
All tagging headers are optional. None of them change routing unless a switched-on policy references the route.
| Header | Meaning | Example |
|---|---|---|
| X-Parezen-Route | Policy route id | support-reply |
| X-Parezen-Task | Outcome tag | ticket_resolved |
| X-Parezen-Agent | Agent id | support-agent |
| X-Parezen-Workflow | Workflow id | ticket-flow |
| X-Parezen-Trace | Groups one agent run | trace_example |
| X-Parezen-Cache: off | Skip the response cache for this request | off |
Project and environment come from the pz_ key, not a header.
Response headers
- x-request-id: req_…, the id in your request logs.
- x-parezen-model: the model that served the request. It differs from the one you asked for only when a policy switched it.
- x-parezen-cache: hit, miss or off.
Errors
Errors use OpenAI's body, { "error": { "message", "type", "code" } }, so the SDK raises them as usual.
- 401 invalid_api_key: unknown or revoked pz_ key.
- 429 rate_limited: over the key's requests or tokens per minute, with retry-after.
- 403 budget_hard_stop and 403 kill_switch: a hard stop holds. Do not retry these straight to the provider.
- 400 model_not_allowed and 400 provider_not_connected: fix the request or connect the provider key.
- 502 provider_error and 504 upstream_timeout: the provider failed after any fallbacks the policy allows.