API reference
Responses
OpenAI Responses subset on POST /v1/responses with capability gating and non-streaming semantics.
POST /v1/responses exposes a bounded Responses API contract. It is a separate route with its own parser and capability gate; it is not a chat-completions alias.
Implemented Ledger class: shipped-local
Verified 2026-10-21
Endpoint
Required headers
| Header | Required | Notes |
|---|---|---|
Authorization: Bearer <pat> | Yes | Must carry ProxyChatCompletion |
X-IBEX-Agent-ID | Yes | Active agent in the token organization |
Content-Type: application/json | Yes | JSON only |
Admission and capability checks
The route runs:
body limit → content type → auth → agent verify → policy mutation → rate limit → budget
→ parse Responses → provider routing → capability gate → provider dispatch
The capability gate rejects a request when:
- The provider/model is unknown or has no verified manifest entry.
- A requested capability is not verified for that model.
stream=trueis requested.
stream=true is currently rejected because streaming Responses is not implemented. Use /v1/chat/completions for streaming.
Errors
| HTTP | Code | Meaning |
|---|---|---|
| 400 | INVALID_REQUEST | The Responses body could not be parsed |
| 422 | CAPABILITY_UNSUPPORTED | The provider/model cannot perform the requested operation, including streaming |
| 503 | CAPABILITY_UNKNOWN | Capability evidence is missing, stale, or unverified |
| 502 | PROVIDER_UNAVAILABLE | The upstream Responses call failed |
| 429 | RATE_LIMITED | Org or upstream limit |
| 402 | BUDGET_EXCEEDED | Hard-cap admission denied |
| 503 | BUDGET_UNAVAILABLE | Admission hold could not be reserved |
All errors use the stable envelope.
Usage accounting
Successful responses with complete usage are written as usage facts through the billing writer. Missing, overflowing, or incomplete usage is logged as pending accounting rather than silently treated as zero.
The Responses usage path is locally implemented. Reconciliation, hosted delivery, and invoice-grade completeness remain provisional.
Example
curl -s -w "\nHTTP %{http_code}\n" \
-X POST http://localhost:8080/v1/responses \
-H "Authorization: Bearer ${IBEX_DEV_TOKEN}" \
-H "X-IBEX-Agent-ID: ${IBEX_DEV_AGENT_ID}" \
-H "Content-Type: application/json" \
-d '{"model":"gpt-4o","input":"hello"}'
A mock-mode provider can return a local response for a registered model. A live provider must advertise the capability before the request is dispatched.
Limits
- No streaming.
- No guarantee that every provider exposes every Responses field.
- Chat and Responses have separate semantics even when they share admission middleware.
- A mount is not a hosted availability guarantee.