Chat completions

The proxy exposes an OpenAI-shaped chat endpoint for SDK drop-in compatibility. After auth, agent verification, rate limits, and request normalization, the proxy forwards to the configured LLM provider (mock or live).

Endpoint

Decision records: ADR-0012 (normalization), ADR-0035 (Idempotency-Key). Path org_id on org-scoped probes must match the token org.

Required headers

Optional headers

Idempotency behavior

• Missing header: unchanged — every request calls the provider.
• Hit (same key + fingerprint): replay stored HTTP status and body; no provider call; no second session checkpoint / trace.
• Conflict (same key, different body): 409 with IDEMPOTENCY_KEY_REUSE.
• In progress: 409 with IDEMPOTENCY_IN_PROGRESS — retry after a short backoff.
• Transient upstream errors (429 / 5xx): pending claim is released so the same key can retry.
• Streaming: stream=true with Idempotency-Key → 400 VALIDATION_ERROR (non-streaming only in this milestone).
• Redis down / timeout: fail-open — request proceeds without dedupe (billing risk under Redis outage).
• The key is not forwarded to OpenAI.

Request body (parsed fields)

Per ADR-0012, the proxy decodes OpenAI-shaped JSON and ignores unknown top-level keys:

After successful parse, the proxy logs metadata only (org_id, request_id, model, message_count, stream) — never message content.

Response

Successful non-streaming completions return the upstream OpenAI-shaped JSON with status from the provider. Response headers include X-Request-ID, X-Trace-ID, and X-Response-Time per ADR-0013. Session sticky header X-IBEX-Session-ID may be set when session lifecycle is enabled.

Mapped provider failures use the stable error envelope (PROVIDER_TIMEOUT, RATE_LIMITED, etc.).

Try it locally

IDEM_KEY="$(uuidgen)"
BODY='{"model":"gpt-4o","messages":[{"role":"user","content":"hello"}]}'
curl -s -w "\nHTTP %{http_code}\n" \
  -X POST http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer ${IBEX_DEV_TOKEN}" \
  -H "X-IBEX-Agent-ID: ${IBEX_DEV_AGENT_ID}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ${IDEM_KEY}" \
  -d "${BODY}"
# Retry with the same key + body to verify replay (no second upstream completion):
curl -s -w "\nHTTP %{http_code}\n" \
  -X POST http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer ${IBEX_DEV_TOKEN}" \
  -H "X-IBEX-Agent-ID: ${IBEX_DEV_AGENT_ID}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ${IDEM_KEY}" \
  -d "${BODY}"

With IBEX_LLM_MODE=mock, expect HTTP 200 and an OpenAI-shaped JSON body. The second request reuses the same Idempotency-Key and body so replay can be verified without a second upstream completion.

Related

• HTTP route inventory — all implemented proxy paths
• Sessions — sticky X-IBEX-Session-ID
• Quickstart — five-minute local path
• Authentication — header requirements
• ADR-0035 — Idempotency-Key design