Chat completions (Phase 1 stub)

The proxy exposes an OpenAI-shaped chat endpoint for SDK drop-in compatibility. Phase 1 parses and validates the request, runs auth and agent verification, applies rate limits, then stops with 501 Not Implemented — no upstream LLM call is made.

Endpoint

POST/v1/chat/completions

OpenAI-compatible chat completions. Gateway alias: POST /proxy/v1/chat/completions (same handler).

Decision record: ADR-0012. Quickstart also probes org-scoped paths — path org_id must match the token org.

Required headers

Parameter	Type	Description
`Authorization`Required	`string`	Bearer PAT issued by auth service.
`X-IBEX-Agent-ID`Required	`string (uuid)`	Calling agent; must belong to the token organization.
`Content-Type`Required	`string`	Must be application/json (charset suffix allowed).

Request body (parsed fields)

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

Parameter	Type	Description
`model`Required	`string`	Model identifier (validated in ADR-0013; max 256 chars).
`messages`Required	`array`	Objects with role and content strings; max 1000 messages.
`stream`	`boolean`	Optional OpenAI fields (temperature, max_tokens) also parsed.

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

Phase 1 response

501 Not Implemented (success path)

JSON

{
  "error": {
    "code": "PROVIDER_NOT_CONFIGURED",
    "message": "No LLM provider is configured for this request",
    "request_id": "019abc…",
    "timestamp": "2026-06-14T12:00:00.000Z"
  }
}

Response headers include X-Request-ID, X-Trace-ID, and X-Response-Time per ADR-0013.

Try it locally

bash

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" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"hello"}]}'

Expected: HTTP 501 and "PROVIDER_NOT_CONFIGURED".

Auth + agent verify

ValidateToken and ValidateAgent over gRPC before body handling completes.

Parse + validate JSON

OpenAI-shaped body normalized per ADR-0012/0013.

501 stub

No upstream LLM call — PROVIDER_NOT_CONFIGURED until Phase 2.

Quickstart — five-minute local path
Authentication — header requirements

Was this page helpful?

Parameter

Type

Description

AuthorizationRequired

string

Bearer PAT issued by auth service.

X-IBEX-Agent-IDRequired

string (uuid)

Calling agent; must belong to the token organization.

Content-TypeRequired

string

Must be application/json (charset suffix allowed).

Request body (parsed fields)

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

Parameter	Type	Description
`model`Required	`string`	Model identifier (validated in ADR-0013; max 256 chars).
`messages`Required	`array`	Objects with role and content strings; max 1000 messages.
`stream`	`boolean`	Optional OpenAI fields (temperature, max_tokens) also parsed.

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

Phase 1 response

JSON

{
  "error": {
    "code": "PROVIDER_NOT_CONFIGURED",
    "message": "No LLM provider is configured for this request",
    "request_id": "019abc…",
    "timestamp": "2026-06-14T12:00:00.000Z"
  }
}

Response headers include X-Request-ID, X-Trace-ID, and X-Response-Time per ADR-0013.

Try it locally

bash

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" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"hello"}]}'

Expected: HTTP 501 and "PROVIDER_NOT_CONFIGURED".

Auth + agent verify

ValidateToken and ValidateAgent over gRPC before body handling completes.

Parse + validate JSON

OpenAI-shaped body normalized per ADR-0012/0013.

501 stub

No upstream LLM call — PROVIDER_NOT_CONFIGURED until Phase 2.