# Serving HTTP profiles

All TCP and Unix listeners expose the same catalog and HTTP endpoints.
Inference requests select a registered deployment through the `model` field
in JSON or multipart form data. Names come from
[model documents](model-documents.md), not checkpoint filenames or an inferred
architecture. An absent model returns 404.

The text, image, embedding, speech and transcription profiles use familiar
OpenAI response shapes, but are not the entire OpenAI API. Supported fields are
explicit; unsupported execution options reject rather than being silently
ignored. The server has no built-in authentication or TLS termination.

## Request framing

Request bodies accept either `Content-Length` or HTTP/1.1
`Transfer-Encoding: chunked`. Supplying both rejects. Chunked transfer is decoded
incrementally into the same bounded request body; the complete request is
validated before routing. `--request_body_bytes` bounds decoded body bytes,
independently of bounded HTTP/chunk framing and multipart metadata. This permits
upload clients that do not know the body length in advance; it does not turn an
inference endpoint into a continuing microphone-input session.

Multipart fields retain their names, ordering and binary contents through
request ownership. Consumers use those parsed fields without interpreting MIME
boundaries again. Part order does not control routing. Unsupported transfer
encodings, ambiguous framing and malformed/truncated multipart bodies reject.
`Expect: 100-continue` is unsupported; upload examples explicitly clear that
header.

## Discovery and administration

| Method and path | Input or result |
| --- | --- |
| `GET /healthz`, `GET /readyz` | Server availability: `{"status":"ready"}`. |
| `GET /v1/models` | Prepared deployments not being removed, with input/output modalities and a `loom` capability object. |
| `GET /v1/status` | Every registration, progress/errors, admission, scheduler state and shared server resources. |
| `POST /v1/models/register` | Complete model document, optionally with uploaded source files; HTTP 202 accepts registration intent. |
| `POST /v1/models/drain`, `POST /v1/models/undrain` | `{"model":"name"}`; HTTP 200 acknowledges the gate change. |
| `POST /v1/models/unregister` | `{"model":"name","mode":"drain"}`; mode may instead be `"abort"`; HTTP 202 accepts removal. |
| `POST /v1/models/activate`, `POST /v1/models/deactivate` | `{"model":"name","component":"primary"}`; HTTP 202 accepts a residency operation on a healthy drained registration. |
| `POST /v1/models/pin`, `POST /v1/models/unpin` | Same component selector; HTTP 200 changes parameter eviction policy. |
| `GET /v1/models/variants` | Native executable inventory or one candidate's retained compilation diagnostics. |
| `POST /v1/models/variants` | Stage native providers against a ready base without selecting them. |
| `POST /v1/models/variants/select` | Select a ready candidate with expected-current protection. |
| `POST /v1/models/variants/remove` | Remove an unused terminal candidate. |
| `POST /v1/devices/trim` | `{"device":0,"target_bytes":0}`; HTTP 200 schedules eligible reclamation and returns current resource accounting. |
| `GET /metrics` | Prometheus text counters and ownership gauges. |
| `GET /logz`, `GET /logz/stream` | Bounded JSONL polling or SSE with independent cursors. |
| `GET /v1/requests`, `GET /v1/sessions` | Bounded live owner inspection; sessions require a retained-text service. |

Prepared but drained or weight-evicted models remain discoverable.
`created` is the registration timestamp; `owned_by` is `"local"`.
`loom.kind`, optional `loom.endpoint`, and `loom.tokenize` describe the deployment
role, HTTP inference route, and loaded tokenizer. Native-only activity models
omit `loom.endpoint`; HTTP inference requests to them return 404. Management and
tokenizer utilities remain available according to their normal capabilities.
Text also reports configured `context_length` and
`limits.max_output_tokens`, not training context or total cache-pool capacity.
`loom.input_tokens:true` advertises exact prepared-chat input counting.
Capabilities do not establish learned quality or support for every optional field.

Residency controls default to `component:"primary"`. A text deployment with an
image-input component also accepts `component:"image"`; an image-generation
deployment's normal computation is still `primary`. An undeclared component
returns 404; an invalid selector returns 400. Drain and unregister apply to the
whole registration and do not accept a component selector.

[Operation](workflows/operate-model-server.md) specifies asynchronous control
completion, conflict and overload behavior. [Observation](workflows/observe-model-server.md)
specifies model selection, cursors, SSE resume and inspection pagination.

### Native executable variants

A prepared service supporting native updates reports
`loom.variants:{"selected":12,"count":2}` in model discovery and status.
Text, sequence, image, embedding and decision services enable this capability through
nonzero `variant_capacity`. Disabled or custom services without the capability
return 501. A registration must have a healthy prepared service; drained
admission is permitted, removal is not.

`GET /v1/models/variants` requires `X-Loom-Model: scout` and an empty body.
It returns `object:"list"`, `model`, `selected`, `count`, `offset`, `data` and
`next_offset`. Optional `X-Loom-Offset` selects a zero-based index; each page
contains at most 64 entries in creation order. This is live inventory, not a
stable snapshot across concurrent removals. Instead, `X-Loom-Variant: 13`
selects one full record, including compilation diagnostics. The variant and
offset headers are mutually exclusive.

Staging accepts:

```json
{"model":"scout","base":12,"base_directory":"/srv/models/scout/candidate","sources":["config.loom","advance.loombc"],"wait":true}
```

`base` identifies a ready choice in this registration. It asserts that the
new providers preserve its resource contract; it does not merge in the base's
providers. `sources` supplies the complete native provider set. With a JSON
request, relative paths require an absolute `base_directory`; otherwise paths
must be absolute. Files are read by server-side compilation workers. A multipart
request instead supplies an immutable source package, described below.
`prepare`, `control` and other model fields reject.

Omitted or true `wait` completes the HTTP request after JIT with 200 for ready
or 422 for failed compilation. False returns 202 after accepting construction.
Both responses contain `selected` and `variant`. A variant record contains
`object:"variant"`, `id`, `base`, `phase` (`compiling`, `ready` or `failed`) and
`users` (explicit consumer references). Terminal failures retain an `error`
with code/message. Detailed records also include available `compilation`
evidence. Staging never changes the preferred choice, including when JIT fails.

Selection accepts `{"model":"scout","variant":13,"expected":12}`. The request
completes at the service's safe execution boundary and returns
`{"selected":13}`. A stale expected ID, pending selection, compiling/failed
candidate or candidate from another registration rejects without switching.
Selection failure leaves the previous preference intact. Query inventory after
an error or interrupted connection to inspect the actual preference.

Execution replacement preserves preparation/control VM programs, stage
declarations and specialization values, parameter placement, and retained state.
It can replace command programs and their reachable kernels, or direct-dispatch
implementations including resident pipelines. It does not rerun weight
preparation. Text selects between retired epochs; embedding and decision
services select outside their active cohort; image services finish the whole
image and CPU encoder before selection. Prepared but unsubmitted work may use
the new execution because its request/result layout is unchanged. Image command
part counts and transient requirements may change without relinking the control
VM. Changing preserved model contracts requires a new registration.

Removal accepts `{"model":"scout","variant":12}` and returns `{"removed":12}`.
Compiling or consumer-retained entries cannot be removed. Missing entries return
404; conflicts return 409; exhausted pool or management-observation credit
returns 429. Unknown, duplicate or wrongly typed fields return 400.

IDs never recycle within the server process, including after unregister/register.
They are not persistent identifiers across restarts. Compilation results remain
until explicit removal or model retirement. Disconnect withdraws the reader,
not accepted compilation or selection. Unregister withdraws waiting compilation
readers with 410 while still joining the compiler's actual model ownership.

### Uploaded source packages

Registration and native staging also accept `multipart/form-data`: exactly one
`request` part contains the same JSON as the corresponding endpoint, and repeated
`file` parts carry programs and metadata. Each file's `filename` is a
case-sensitive UTF-8 path inside the package, not a server filesystem
destination. The request filename defaults to
`request.json`; its directory is the base for relative source references.

For a local `candidate.json` containing
`{"model":"scout","base":12,"sources":["config.loom","advance.loombc"]}`:

```bash
curl --fail-with-body -H 'Expect:' \
  http://127.0.0.1:8080/v1/models/variants \
  -F