Breeze

Breeze exposes a small FastAPI backend. Protected endpoints require an X-API-Key header matching your configured API_KEY.

You usually do not call this directly

In a normal install the Next.js routes proxy the backend for you and add the key. See using it through Next.js.

Endpoints at a glance

Method	Path	Auth	Rate limit	Purpose
`GET`	`/`	none	none	Service status.
`GET`	`/health`	none	none	Liveness check.
`POST`	`/completion`	`X-API-Key`	10/minute	Stream an LLM reply.
`POST`	`/summarize`	`X-API-Key`	20/minute	Create a conversation title.

Headers

Header	Required	Description
`X-API-Key`	Protected endpoints	The shared service secret (`API_KEY`).
`Content-Type`	`POST`	`application/json`.
`X-User-Id`	optional	Langfuse user attribution.
`X-Session-Id`	optional	Langfuse session attribution.

Message throughout is { role: 'user' | 'assistant', content: string }.

`POST /completion`

Streams a reply as NDJSON (application/x-ndjson), one StreamEvent per line.

Request body

Prop

Type

Request

{
  "message": "Hello!",
  "thinking": false,
  "history": [{ "role": "user", "content": "Hi" }],
  "web_search": true,
  "images": [],
  "genui": "auto"
}

Stream events

Each NDJSON line is one StreamEvent.

lib/types/stream.ts

{ type: 'text' | 'reasoning' | 'done' | 'error', content: string }

Type	Content
`text`	A chunk of the reply text.
`reasoning`	A chunk of reasoning output.
`done`	The stream is complete.
`error`	An error message.

Widgets do not arrive as their own event

A generative UI spec rides inside text as a fenced ```breeze-ui block. There is no widget event type to handle. See Generative UI.

Example

curl -N -X POST http://localhost:8000/completion \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello!", "thinking": false}'

The backend picks the answer model after the acquire pass, so it follows whether a search actually ran; priority is images > thinking > evidence > default. The mapping is in the Architecture guide.

`POST /summarize`

Generates a conversation title from its messages. The title is a short phrase, four words or fewer.

Prop

Type

{ "history": [{ "role": "user", "content": "Hi" }] }

Status endpoints

Both are unauthenticated by design, so a load balancer can probe them. See Security.

Using it through Next.js

In a normal install you never call FastAPI directly. These routes proxy it, adding X-API-Key and forwarding X-User-Id and X-Session-Id for you:

Next.js route	Proxies
`/api/chat`	`POST /completion`
`/api/conversations/:id/summarize`	`POST /summarize`
`/api/health`	`GET /health`

/api/chat streams the NDJSON body straight through. On an upstream error it emits a single error event rather than failing the request, so the client's stream parser always sees a well-formed line.

API Reference