OpenAI-compatible HTTP reference

Use this reference when your server already speaks an OpenAI-style HTTP contract. For an adoption walkthrough, use the integration tutorial.

Endpoints

Method and path	Purpose
`GET /v1/models`	Return the fixed `kestrel` compatibility model
`POST /v1/chat/completions`	Submit chat-completion shaped input
`POST /v1/responses`	Submit responses-shaped input

Authentication

Send the configured runner token from trusted server code. It may authenticate to a remote runner service or to the local HTTP bridge exposed by kestrel web:

http

Authorization: Bearer <runner-service-token>
Content-Type: application/json

Do not expose this token to browser code. Resolve the authenticated user, tenant, and session in your application server before forwarding the request.

Request and response shapes

Chat Completions and Responses requests follow their compatible HTTP shapes after server-side validation. The Kestrel terminal result remains the canonical source for committed assistant text and structured output; compatibility responses are a mapping, not a second runtime contract.

Model identifiers

The compatibility layer accepts only kestrel. /v1/models lists that canonical model; it does not enumerate arbitrary CLI or runner profiles. Unknown model IDs are rejected.

Streaming

Streaming responses use server-sent events. A client disconnect must cancel the exact upstream run rather than leaving anonymous work active. The terminal event remains the source for the final result.

Terminal and error mapping

Compatible success, validation, authentication, provider, cancellation, waiting, and terminal failure map into the closest supported HTTP response. OpenAI-style clients cannot express every Kestrel recovery, approval, Mission Control, evaluation, or budget state; use the native Protocol/SDK when the application needs those contracts.

Kestrel metadata

Compatible runner responses include session, run, thread, and model headers. Preserve them when your application needs replay, support, or observability.

The Next.js route helpers separately generate x-kestrel-request-id and x-kestrel-correlation-id for application-route correlation. Those headers do not come from the runner's OpenAI compatibility layer.

Compatibility limitations

This surface preserves existing OpenAI-style clients, not 0.7 Kestrel wire compatibility. It exposes the canonical kestrel model and a subset of native control. Runtime, server, and compatibility adapter must follow their declared exact dependency contracts; compatible packages do not need equal semantic versions.