Reference

API reference

lmgw's own HTTP API: the inference plane (OpenAI-, Anthropic- and llama.cpp-compatible, plus MCP), the device (Chat) API paired clients use, the agent run API agents use, and the dashboard that configures the gateway.

Generated from the OpenAPI document of lmgw 0.6.0. The dashboard's own pages, the /ui redirects and the agents' app and MCP proxies are not part of it.

  • openapi.json: the complete document of this page, the dashboard API, Chat API, Knowledge, labs and ops included.
  • openapi-v1.json: the developer document (/v1/openapi.json): the inference routes, the device Chat API and the agent run API. The one to feed a client generator.

Base URLs and keys

ClientBase URL
OpenAI SDKs and toolshttp://127.0.0.1:8787/v1
Anthropic SDKs, Claude Code (ANTHROPIC_BASE_URL)http://127.0.0.1:8787
Realtime voice sessionsws://127.0.0.1:8787/v1/realtime
MCP clientshttp://127.0.0.1:8787/mcp

127.0.0.1:8787 is lmgw's default address; Settings → Network & access changes it. The Anthropic SDKs want the bare address because they add /v1/messages themselves.

/v1 and /mcp accept requests without a key until Require gateway API keys on /v1 is on. From then on, send a key from Usage → Keys & budgets as Authorization: Bearer <key>, or as x-api-key: <key> the way Anthropic clients do. A key can be limited to some aliases and tools, and carry a budget and rate limits.

Errors come in the shape of the protocol you called: OpenAI's on the OpenAI routes, Anthropic's on /v1/messages. A local model paused by the GPU hold answers 503 with the code gpu_hold, unless it has a fallback, which then answers instead and is named in x-lmgw-fallback.

This page covers every route, grouped as the document groups them. Inference is what any key reaches; the Chat API needs a paired device, with its certificate on the device listener; the Dashboard API and Ops belong to the owner (the dashboard's session or an owner key), and Agent runtime to an agent container's own token. Each operation names its capability and who holds it. Developers who only build on lmgw can download the smaller developer document, which leaves the owner's plane out. How the inference routes behave against the official SDKs, model by model, is on the API compatibility page.

lmgw headers

lmgw adds these to the protocols it speaks. A client that ignores them works unchanged.

HeaderSent inMeaning
x-lmgw-backgroundrequeston|off: run this one request as background work, for speculative or prefetching clients. On a local model it uses the model only when that disturbs nobody: it joins the model if it is loaded and no foreground request is waiting for room, or starts it into free GPU memory (evicting only idle background-started models), and never evicts, waits for or climbs a model foreground work uses. Otherwise the model's configured fallback answers (x-lmgw-fallback, x-lmgw-fallback-reason: background), or the request is refused with 503 gpu_deferred: retry later. Foreground work never interrupts a background request that has started; close the request to cancel it. On a candidate alias it makes the alias walk as a background alias. A cloud model and a model running on the CPU are unaffected. Absent or off: an ordinary request. Any other value is a 400.
x-lmgw-candidateresponseOn a candidate alias, the id of the local model that answered (or refused) the request. Never sent next to x-lmgw-fallback. The body's model field still names the requested alias.
x-lmgw-count-approximateresponseOn the token counters, why the number is not exactly what the backend would count for this request; a comma-separated list. flattened: the request's structure was counted as plain text, so chat template, tool-definition and per-message overhead are not included and the real prompt is larger. tokenizer_guess: the backend's tokenizer is unknown, so the count uses tiktoken o200k_base. media_bound: images are counted at the model's per-image upper bound. media_omitted: image or audio parts are not in the number. message_framing: on /v1/count_tokens, the backend counts messages, so the text was counted as one user message, framing included. tools_omitted: on /v1/responses/input_tokens, the mcp tools' definitions (listed from their servers when a run starts) are not in the number. pending_calls_omitted: on /v1/responses/input_tokens, the stored response being continued is waiting on calls, whose results are not in the number. Absent when the count is exact.
x-lmgw-fallbackresponseThe model or alias that answered instead of the one requested: the last hop of its chain of fallbacks (each model and alias has its own, and a fallback can have one in turn); the answer still names the requested model. On the chat routes, a fallback whose capabilities say it cannot see receives the request's images as text placeholders, and x-lmgw-images-omitted gives the count.
x-lmgw-fallback-chainresponseEvery hop a fallback-served answer was handed to, in order, each with the reason it was handed on, as an RFC 8941 list: "m2";reason=hold, "cloud";reason=hold. Sent on every answer a fallback served, next to x-lmgw-fallback (the last name) and x-lmgw-fallback-reason (the last reason), so a client reads one header whatever the chain's length. A name that cannot be an sf-string (a byte outside 0x20–0x7E) is left empty, the reason kept. A streamed /v1/responses run names the hops of its first turn only: its headers left with the first event.
x-lmgw-fallback-reasonresponseWhy x-lmgw-fallback answered (the last hop's reason; x-lmgw-fallback-chain has every hop's); always sent next to it. hold: the GPU hold pauses local models. benchmark: a benchmark run has the GPU to itself until it ends. external_vram: GPU memory used outside lmgw by another program left too little room to load the model, so the fallback answered at once instead of waiting. background: a background job's model could not load without disturbing foreground work (any request that is not background traffic: a background candidate alias's, or one sent with x-lmgw-background: on). unavailable: a candidate alias's primary cannot be used at all (missing, disabled, or lacking a capability the alias enables) and none of its other models is loaded. quota: the upstream answered that its account's quota is exhausted (insufficient_quota), or lmgw remembers it so until its next check; nothing was charged for the refused attempt. unreachable: the upstream could not be connected to, so nothing reached it. disabled: the model or alias asked for is disabled, or its upstream is. gpu_setup: the local model could not start on the graphics card, and lmgw's machine check names why (the card, its driver, or the piece that lets models use it, not ready on the computer lmgw runs on); while that check still describes the machine, the fallback answers without a start being tried. engine_download: the engine the local model runs in is not on the computer yet, and downloading it failed or cannot be done.
x-lmgw-images-omittedresponseSent next to x-lmgw-fallback: the number of the request's images that went to the answering fallback as text placeholders because its capabilities say it cannot see ('[image/png image, N base64 bytes — omitted: the answering model cannot see images]'). The model reads the placeholder; the client reads this count. On /v1/responses it counts the images the run opened with. Absent when every image was sent, and on a route the client named itself, which always gets its images.
x-lmgw-max-tokens-clampedresponseThe max_tokens value lmgw lowered the request's cap to, because the n_predict of a ladder rung, or of a guarded shared-KV-pool model, is a ceiling every request on it must respect. Absent when nothing was lowered: a missing max_tokens is filled, not clamped, and a value already under the ceiling is kept exactly.
x-lmgw-max-tokens-defaultedresponseThe max_tokens value lmgw chose because the request set none and the route (an Anthropic upstream) requires one: the catalog's published maximum when streaming, 4096 when not streaming (the provider refuses non-streamed requests that could run too long).
x-lmgw-max-tokens-raisedresponseThe max_tokens value lmgw raised the request's cap to, because the requested thinking budget would not fit underneath it.
x-lmgw-params-ignoredresponseComma-separated list of the request's sampling parameters (top_k, min_p, repeat_penalty, presence_penalty, frequency_penalty, seed) the answering model's provider does not take, so lmgw did not send them: the OpenAI platform takes no top_k, min_p or repeat_penalty; Anthropic none of the six but top_k; Gemini no min_p, repeat_penalty or penalties. llama.cpp and OpenAI-compatible providers are sent all of them. Also context_management and compaction, a /v1/messages request's Anthropic context management and on-demand compaction, which only an Anthropic model's route takes (both sent on as written), and thinking.display, which goes only to an Anthropic model, beside a thinking type that takes it (adaptive or enabled). Also content.<type>, a /v1/messages request's content block lmgw does not model (redacted_thinking, a type newer than lmgw), which only an Anthropic model's route is sent, and answer.<type>, such a block in an Anthropic model's whole answer, which a Chat Completions or Responses client is not given (a streamed answer's headers leave before it). On an Anthropic model's route, content.thinking and content.<type> name a thinking or other Anthropic block lmgw recorded from an answer at another provider's address (a stored /v1/responses chain), which this provider cannot read and is not sent. answer.citations and content.citations name an Anthropic text block's citations, which only a /v1/messages client and an Anthropic model's route are given (citations lmgw recorded from an answer only at that provider's address, and a citation with no text not at all). Request fields lmgw does not model are sent as they came and never listed. Absent when every parameter was sent.
x-lmgw-params-refusedresponseComma-separated list of the request's sampling parameters the answering model refused, which lmgw left out of the send (stop is not left out; its refusal reaches the client). A 400 whose words refuse exactly one parameter the request carried (Anthropic 'temperature is deprecated for this model.', OpenAI 'Unsupported parameter: 'temperature' is not supported with this model.' or 'Unsupported value: 'temperature' does not support 0 with this model.') is retried once without exactly that parameter, the refused attempt logged with a note naming it, and when the retry answers the parameter is left out of that model's later requests too, each saying so here. Nothing is left out without a refusal on record. On a streamed /v1/responses run the header names what was on record when the stream opened. Absent when every parameter was sent.
x-lmgw-reasoningrequeston|off: per-request thinking switch; it wins over body fields. On a cloud model, off goes out in the form the model takes: no reasoning control where the model has none, its lowest level where it cannot stop (x-lmgw-reasoning-ignored then lists enabled), thinking type between_tools on an Anthropic model whose catalog says it takes that type and not disabled. An off never ends in an error: a refused one is retried with what the refusal names and, failing that, with no reasoning control, so a model that cannot run without reasoning answers with its default reasoning. Accepted on /v1/chat/completions, /v1/messages, /v1/messages/count_tokens, /v1/responses and /v1/responses/input_tokens.
x-lmgw-reasoning-budgetrequestInteger thinking-token budget; 0 turns reasoning off. Expressible on llama.cpp, Gemini and budget-style Anthropic models only. Accepted on /v1/chat/completions, /v1/messages, /v1/messages/count_tokens, /v1/responses and /v1/responses/input_tokens.
x-lmgw-reasoning-effortrequestAn effort level (see capabilities.reasoning.levels of the model); 'none' turns reasoning off. Accepted on /v1/chat/completions, /v1/messages, /v1/messages/count_tokens, /v1/responses and /v1/responses/input_tokens.
x-lmgw-reasoning-ignoredresponseComma-separated list of the reasoning controls (enabled, effort, budget) the route could not express. enabled is also listed when an off went out as no control or as the model's lowest level, either because the model cannot take the off itself or because the provider refused every form of off and the model answered with its default reasoning. An off sent to an Anthropic model as thinking type between_tools (its own lowest setting, when it takes no disabled) is not listed. between_tools: a /v1/messages request's thinking type between_tools went to a model of another provider as that provider's off. Absent when every control was applied.
x-lmgw-runrequestThe job id of the live agent run to attribute this request's cost, tokens and call count to. Only an agent token may attribute, and only to its own runs. An id that names no live run, a run that belongs to another agent, or a caller without an agent token is ignored with a log line and never refused.
x-lmgw-rungresponseOn a ladder model, the rung that answered (or refused) the request, as '<k>/<n>; ctx=<per-slot context>; gguf=<weights file>', counted from 1 (the gguf part is left off when the file name cannot be a header value). A request whose prompt plus max output does not fit the running rung makes the model climb to the smallest rung that fits before it answers. On /v1/responses it names the rung running when the run opened; a unary answer one of whose turns the fallback answered carries x-lmgw-fallback instead, and a stream's headers are sent before its turns run. Absent on models without a ladder and on responses a fallback answered.
x-lmgw-sample-rateresponseOn a streamed POST /v1/audio/speech (stream_format sse or audio) to a local audio model, the sample rate of its PCM16 in Hz; the stream has no header of its own. lmgw learns it from the model's last WAV answer (it is also capabilities.speech.sample_rate) and omits it until the model has answered one since lmgw started.
x-lmgw-speechresponseOn POST /v1/audio/speech (and on /v1/tasks/run and /v1/tasks/stream, for their chars part), what lmgw changed in the request so the model understands it; a '; '-separated list. voice=options.voice_id: a voice the model ships, which this family (MagpieTTS) reads from options.voice_id. voice=preset->options.voice_id: the same for a preset's voice id. voice=<name>: a shipped voice sent in the model's own spelling. language=<asked>-><sent>: the language in the model's own vocabulary, e.g. de->german for Qwen3-TTS, en->en-us for Kokoro. instructions=options.instruct: instructions moved to where the family reads them. instructions=also:options.instruct or instructions=also:options.instruction: the model's default request options describe the voice under that other key, which the engine would merge in beside the request's and refuse as conflicting, so the request's text went there too and replaces the default. instructions=dropped: the model reads none (capabilities.speech.instructions is none). tags=mapped:<n>,stripped:<n>: inline tags in input were rewritten into the model's spelling, or removed so they are never read out. chars=replaced:<U+XXXX/...>,dropped:<U+XXXX/...>: characters of input the model's engine has no entry for in its package's vocabulary (Supertonic refuses the whole request over one), replaced by an equivalent it has (a typographic quote by a plain one, a dash by -) or removed (an emoji). Each list names at most 64 codepoints and then ends in +<n> more; lmgw's log has the full list. An input left with nothing to say is 400 empty_input, which carries the header too. The voice, language and chars parts apply to local audio models only. Absent when the request went as it came; input changes only for its inline tags and those characters.
x-lmgw-voices-sourceresponseOn GET /v1/audio/voices, where the list came from. config: a local audio model answered from lmgw's own catalog (its presets, the voices its package ships, its embeddings and the voice library) without being started. engine: the model's own server answered, either a remote upstream or a local container with ?probe=engine, which starts the container if it is down.

Inference

OpenAI-compatible

post/v1/audio/alignments

Align audio to text

Capability inference, open to: agent, device, key, owner

Forced alignment against a task: "align" row — lmgw's own route, multipart/form-data only. Every family answers the same shape: the words with their seconds, samples where known, and their character span in the submitted text; a model whose answer has no word timings lmgw can read is a 502 naming its family.

Also takes x-lmgw-background, x-lmgw-run (see lmgw headers).

Request body required

multipart/form-data: AudioAlignmentsRequest

Fields of AudioAlignmentsRequest
filerequired string (binary)
language string
modelrequired string
textrequired string

Responses

StatusDescription
200 OK.
application/json AudioAlignment
Fields of AudioAlignment
language string | null The language as the model reported it (en, de; the model's own
spelling). Absent when the model says none.

A model may report the language it assumes rather than the one it was
asked to align in: CrisperWhisper's aligner answers its default, en,
to any language (checked 2026-10-22 with de, german and none).
sample_rate integer | null The rate, in Hz, the start_sample and end_sample of the words
count in: the model's own figure when its answer states one, else
derived from the words' seconds and samples (they are what the
samples count in, even where the engine resampled the clip), else the
uploaded WAV's header. Absent when none of the three works; the
seconds are always there.
textrequired string The transcript as the client submitted it (the multipart text
field), not what the model echoes. char_start and char_end of the
words index into this string.
timing AudioTiming | null How long the engine took, as it reports it (audio.cpp's timing
object, which both aligners send). Absent when the answer has none.
wordsrequired array of AlignedWord The words in the order the model answered them, which is the
transcript's order.

Headers: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
default Error.
application/json OpenAiError

Headers: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
post/v1/audio/speech

Generate speech

Capability inference, open to: agent, device, key, owner

OpenAI's TTS shape plus audio.cpp's own request options, forwarded verbatim (model rewritten); a row's configured voice presets apply on top.

Also takes x-lmgw-background, x-lmgw-run (see lmgw headers).

Request body required

application/json: AudioSpeechRequest

Fields of AudioSpeechRequest
inputrequired string The text. A local model whose engine refuses a character its package lacks (Supertonic) is sent an equivalent it has in its place, or nothing; the x-lmgw-speech response header names each one. An input left with nothing to say (a lone emoji) is 400 empty_input, refused before any model is started.
instructions string A speaking style, or the description a voice-design model builds its voice from (required there: 400 instructions_required without one, unless the row has a default). Dropped for a model that reads none: capabilities.speech.instructions says which, and the x-lmgw-speech response header says when.
language string An ISO 639-1 code or BCP-47 tag; a local model gets it in its own vocabulary.
modelrequired string
response_format string
speed number
stream_format string Streams PCM16 (with response_format pcm) as speech.audio.delta events (sse) or as raw chunked PCM (audio). A local model streams only when its row runs in streaming mode; an offline row is 400 streaming_unsupported before anything starts (capabilities.speech.streaming says which). The x-lmgw-sample-rate response header states the PCM's rate. One of sse, audio.
voice string A row's own voice preset id, when it defines any (GET /v1/audio/voices). A voice-library clip with no transcript, for a model that cannot clone one without, is 400 voice_needs_transcript before anything starts (lmgw.needs_transcript in the voice list); send reference_text, or transcribe the clip in the dashboard's Audio lab. A local model whose audio.cpp image lacks eSpeak NG is 400 audio_image_lacks_espeak.

Responses

StatusDescription
200 OK.
audio/aac string (binary)
audio/flac string (binary)
audio/mpeg string (binary)
audio/ogg string (binary)
audio/opus string (binary)
audio/pcm string (binary)
audio/wav string (binary)

Headers: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason, x-lmgw-sample-rate, x-lmgw-speech
default Error.
application/json OpenAiError

Headers: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason, x-lmgw-sample-rate, x-lmgw-speech
post/v1/audio/transcriptions

Transcribe audio

Capability inference, open to: agent, device, key, owner

multipart/form-data upload (also accepts application/json); byte-level passthrough to an OpenAI-protocol upstream only.

Also takes x-lmgw-background, x-lmgw-run (see lmgw headers).

Request body required

multipart/form-data: AudioTranscriptionsRequest

Fields of AudioTranscriptionsRequest
filerequired string (binary)
language string
modelrequired string
prompt string
response_format string
temperature number

Responses

StatusDescription
200 OK.
application/json AudioTranscription
Fields of AudioTranscription
textrequired string

Headers: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
default Error.
application/json OpenAiError

Headers: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
post/v1/audio/transcriptions/details

Transcribe audio with detail

Capability inference, open to: agent, device, key, owner

The same request as /v1/audio/transcriptions, with the transcript detail arrays (words, segments, speaker turns) the plain route leaves out — an lmgw route, not an OpenAI one.

Also takes x-lmgw-background, x-lmgw-run (see lmgw headers).

Request body required

multipart/form-data: AudioTranscriptionsRequest

Fields of AudioTranscriptionsRequest
filerequired string (binary)
language string
modelrequired string
prompt string
response_format string
temperature number

Responses

StatusDescription
200 OK.
application/json AudioTranscriptionDetails
Fields of AudioTranscriptionDetails
segments array of object
speaker_turns array of object
textrequired string
words array of object

Headers: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
default Error.
application/json OpenAiError

Headers: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
get/v1/audio/voices

List a model's voices

Capability inference, open to: agent, device, key, owner

Every voice name a TTS model answers to — lmgw's own route. A local audio model is answered from lmgw's catalog (presets, the voices its package ships, its embeddings, the voice library) without starting it; ?probe=engine asks its own server instead, starting it if it is down. A remote model is asked.

Parameters

NameInDescription
modelquery string
probequery string | null

Also takes x-lmgw-background, x-lmgw-run (see lmgw headers).

Responses

StatusDescription
200 OK.
application/json AudioVoices
Fields of AudioVoices
lmgw object Only on a local audio model answered from lmgw's catalog (x-lmgw-voices-source: config).
defaultrequired string | null What speaks when a request names no voice.
engine_askedrequired boolean
entriesrequired array of object
idrequired string
kindrequired string One of preset, library, native, embedding.
sendrequired string Where lmgw puts the name in the engine's request; clients always send it as voice. One of voice, options.voice_id.
transcript boolean A library clip's transcript is recorded.
heldrequired boolean The GPU hold (or a benchmark run) holds the card and the model has no fallback: the list stands, its speech is refused (503 gpu_hold) until the hold is released.
missingrequired array of string Voices the spec names whose file the package lacks.
needs_transcriptrequired boolean The model cannot clone a library clip without its transcript: speech with an entry whose transcript is false is refused (400 voice_needs_transcript) until it has one (the dashboard's Audio lab, Transcribe).
sourcerequired string One of config.
voicesrequired array of string Every name the model answers to as voice, sorted; for a probe of the engine or of a remote upstream, as that source sent it.

Headers: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason, x-lmgw-voices-source
default Error.
application/json OpenAiError

Headers: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason, x-lmgw-voices-source
post/v1/chat/completions

Create a chat completion

Capability inference, open to: agent, device, key, owner

The chat-completions API, plus lmgw's own reasoning controls and chat_template_kwargs passthrough. model may be an alias, a local model id, a candidate alias, or an exposed upstream's prefix/… id. An anthropic-beta header is forwarded when the route is an Anthropic upstream.

Also takes x-lmgw-reasoning, x-lmgw-reasoning-effort, x-lmgw-reasoning-budget, x-lmgw-background, x-lmgw-run (see lmgw headers).

Request body required

application/json: ChatCompletionRequest

Fields of ChatCompletionRequest
chat_template_kwargs object Only enable_thinking is read (llama-server's own template toggle, distinct from the protocol-neutral reasoning controls above); every key is forwarded verbatim.
frequency_penalty number
json_schema object llama.cpp's own top-level schema; without a response_format, or next to a {type:text} one, it is read as response_format {type:json_schema} and sent in that spelling. Next to a grammar it is 400 bad_request, as llama-server refuses the pair.
max_completion_tokens integer Wins over max_tokens when both are sent.
max_tokens integer
messagesrequired array of object
content any A string, or an array of parts: {type:text,text}, {type:image_url,image_url:{url}} (a plain URL or a data: URI), {type:input_audio,input_audio:{data,format}} (data: URI, or raw base64 with format required). A tool message keeps only its text, as OpenAI defines it; any other part is dropped with a WARN naming it.
name string role: tool only. Forwarded as the tool result's name.
reasoning_content string role: assistant only. Replayed as the leading reasoning part (also accepted spelled 'reasoning', as OpenRouter spells it; DeepSeek and llama.cpp use reasoning_content).
rolerequired string system and developer are both treated as a system message; tool and function are both treated as a tool-result message. One of system, developer, user, assistant, tool, function.
tool_call_id string role: tool only.
tool_calls array of object role: assistant only: [{id, type:function, function:{name, arguments: <JSON string>}}]. Send each id back as lmgw gave it: a Gemini model's call id carries the model's thought signature, which Gemini 3 refuses a replayed call without. Such ids run to hundreds of characters; echo them exactly, and do not send them to another provider directly (lmgw strips the signature there).
modelrequired string An alias, a local model id, a candidate alias, or 'prefix/…' to pass through to an exposed upstream.
presence_penalty number
reasoning object lmgw extension, OpenRouter's shape: {effort, max_tokens, enabled, exclude}. Read for the reasoning tier and forwarded verbatim.
reasoning_budget_tokens integer lmgw extension: a thinking-token budget (also x-lmgw-reasoning-budget). Forwarded verbatim alongside thinking_budget_tokens — whichever spelling a llama-server version reads.
reasoning_effort string lmgw extension: an effort level, or 'none' for off — one spelling of the reasoning control (also x-lmgw-reasoning-effort, and reasoning.effort below); the header wins when both are sent.
response_format object {type:text} | {type:json_object} | {type:json_schema, json_schema:{name, description, schema, strict}} — translated for every upstream: Anthropic output_config.format (json_schema only; json_object is refused with response_format_unsupported), Gemini responseMimeType + responseJsonSchema. A type the model's capabilities.structured_output flag says false is refused before any upstream call (400 response_format_unsupported, param response_format); a schema the upstream rejects is 400 invalid_json_schema with its message. Another type goes verbatim to OpenAI-compatible upstreams. Keys lmgw does not model, on the object and on json_schema, reach OpenAI-compatible and llama.cpp upstreams as sent.
seed integer
service_tier string OpenAI's processing tier (auto, default, flex, priority, fast, scale, ultrafast), forwarded as sent; on an OpenAI platform row lmgw sends auto when it is unset, and prices the answer at the tier the answer reports. A request by a caller with a budget (its key's, or the gateway's) on a cloud model with no price on file for what it is billed in is refused before the send: 403 budget_unpriced, naming the model and the missing price. A flex request needs a flex price: no other tier's price bounds a flex answer's spend, which is cheaper.
stop any A string, or an array of strings.
stream boolean Default false.
stream_options object With stream: true, include_usage ends the stream with a chunk whose choices is [] and that carries usage; every other chunk then has usage: null. Without it no chunk carries usage. Not forwarded: lmgw asks the upstream for usage itself, for its request log.
include_usage boolean Default false.
temperature number
thinking_budget_tokens integer Same as reasoning_budget_tokens; both are read and both stay in the forwarded body.
tool_choice any "auto" | "none" | "required" | {type:function,function:{name}}.
tools array of object
functionrequired object
description string
namerequired string
parameters object
typerequired string One of function.
top_k integer Not part of the OpenAI API, but accepted; llama.cpp supports it.
top_p number
Example
{
  "messages": [
    {
      "content": "Say hello in one short sentence.",
      "role": "user"
    }
  ],
  "model": "<pick a model>"
}

Responses

StatusDescription
200 OK.
application/json ChatCompletion
Fields of ChatCompletion
choicesrequired array of object
finish_reasonrequired string | null
indexrequired integer
logprobs null Always null: lmgw relays no log probabilities yet. Present because OpenAI's schema requires the field.
messagerequired object
contentrequired string | null
reasoning_content string
rolerequired string One of assistant.
tool_calls array of object
createdrequired integer
idrequired string
modelrequired string
objectrequired string One of chat.completion.
usagerequired object
completion_tokensrequired integer
completion_tokens_details object Present only when the upstream reported reasoning tokens.
reasoning_tokensrequired integer
prompt_tokensrequired integer
prompt_tokens_details object Present only when the upstream reported prompt-cache counts, and each field only when reported: cached_tokens read from the cache, cache_write_tokens written to it. Both are part of prompt_tokens.
cache_write_tokens integer
cached_tokens integer
total_tokensrequired integer
text/event-stream string
1 event types

chunk

One of 2 shapes
ChatCompletionChunk
Fields of ChatCompletionChunk
choicesrequired array of object
deltarequired object
content string | null
reasoning_content string
role string One of assistant.
tool_calls array of object
finish_reasonrequired string | null
indexrequired integer
createdrequired integer
idrequired string
modelrequired string
objectrequired string One of chat.completion.chunk.
usage object | null Only with stream_options.include_usage: null on every frame but the last, whose choices is [] and which carries the request's usage.
completion_tokensrequired integer
completion_tokens_details object Present only when the upstream reported reasoning tokens.
reasoning_tokensrequired integer
prompt_tokensrequired integer
prompt_tokens_details object Present only when the upstream reported prompt-cache counts, and each field only when reported: cached_tokens read from the cache, cache_write_tokens written to it. Both are part of prompt_tokens.
cache_write_tokens integer
cached_tokens integer
total_tokensrequired integer
ChatCompletionStreamError
Fields of ChatCompletionStreamError
errorrequired object
coderequired string One of upstream.
messagerequired string
typerequired string One of api_error.

Headers: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason, x-lmgw-images-omitted, x-lmgw-max-tokens-clamped, x-lmgw-max-tokens-defaulted, x-lmgw-max-tokens-raised, x-lmgw-params-ignored, x-lmgw-params-refused, x-lmgw-reasoning-ignored, x-lmgw-rung
default Error.
application/json OpenAiError
post/v1/completions

Create a legacy text completion

Capability inference, open to: agent, device, key, owner

The legacy text-completions shape. Refuses a non-OpenAI-protocol upstream with 400 rather than sending it a request its own API cannot answer. A missing model is a 400 (missing 'model'), as on every other ingress.

Also takes x-lmgw-background, x-lmgw-run (see lmgw headers).

Request body required

application/json: CompletionRequest

Fields of CompletionRequest
max_completion_tokens integer
max_tokens integer
modelrequired string
n_predict integer llama.cpp spelling of max_tokens; folded into it for local models with a guard or a ladder.
promptrequired any A string, an array of strings, an array of token ids, or a mix of both.
response_format object As on /v1/chat/completions. llama.cpp's own /v1/completions reads no response_format, so for a llama.cpp row it is sent as the top-level json_schema that route reads; a type with no such spelling is 400 response_format_unsupported, and a JSON type next to a grammar 400 bad_request, with nothing sent.
stream boolean Default false.
Example
{
  "model": "<pick a model>",
  "prompt": "Once upon a time"
}

Responses

StatusDescription
200 OK.
application/json TextCompletion
Fields of TextCompletion
choicesrequired array of object
createdrequired integer
idrequired string
modelrequired string
objectrequired string One of text_completion.
usage object
text/event-stream string
1 event types

chunk


Headers: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason, x-lmgw-max-tokens-clamped, x-lmgw-rung
default Error.
application/json OpenAiError
post/v1/embeddings

Create embeddings

Capability inference, open to: agent, device, key, owner

dimensions is forwarded in the upstream's own spelling, and a route that ignores it (llama-server) is a 400, not full-length vectors. encoding_format base64 is encoded by the gateway for every upstream.

Also takes x-lmgw-background, x-lmgw-run (see lmgw headers).

Request body required

application/json: EmbeddingsRequest

Fields of EmbeddingsRequest
dimensions integer Forwarded (Gemini: outputDimensionality). A route that answers with another length — llama-server has no such parameter — is refused with 400 rather than served full-length vectors.
encoding_format string Encoded by the gateway, whatever the upstream: base64 is the little-endian float32 bytes, as OpenAI serves it. One of float, base64.
inputrequired any A string, or an array of strings. Token-id arrays are refused with 400: an alias can route to a model with another tokenizer.
modelrequired string
Example
{
  "input": "lmgw is a gateway.",
  "model": "<pick a model>"
}

Responses

StatusDescription
200 OK.
application/json EmbeddingsResponse
Fields of EmbeddingsResponse
datarequired array of object
embeddingrequired array of number | string Floats, or a base64 string when encoding_format was base64.
indexrequired integer
objectrequired string One of embedding.
modelrequired string
objectrequired string One of list.
usagerequired object
prompt_tokensrequired integer What the model reported; 0 when it reported nothing.
total_tokensrequired integer The same number: embedding generates nothing.

Headers: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
default Error.
application/json OpenAiError

Headers: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
post/v1/images/edits

Edit an image

Capability inference, open to: agent, device, key, owner

multipart/form-data upload; refused unless the resolved row's edit pipeline flag is set.

Also takes x-lmgw-background, x-lmgw-run (see lmgw headers).

Request body required

multipart/form-data: ImageEditsRequest

Fields of ImageEditsRequest
imagerequired array of string (binary) One or more image files. lmgw relays every multipart field named image verbatim, with no cardinality check of its own.
mask string (binary)
modelrequired string
n integer
promptrequired string
size string

Responses

StatusDescription
200 OK.
application/json ImageGenerationsResponse
Fields of ImageGenerationsResponse
createdrequired integer
datarequired array of any | any
b64_json string
revised_prompt string
url string

Headers: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
default Error.
application/json OpenAiError

Headers: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
post/v1/images/generations

Generate an image

Capability inference, open to: agent, device, key, owner

OpenAI's images shape; sd.cpp CLI arguments may ride along in a trailing <sd_cpp_extra_args>{…}</sd_cpp_extra_args> block on prompt (the dashboard's Image lab builds this block and is the reference for its contents). Answers base64 only (b64_json), never a URL.

Also takes x-lmgw-background, x-lmgw-run (see lmgw headers).

Request body required

application/json: ImageGenerationsRequest

Fields of ImageGenerationsRequest
modelrequired string
n integer
output_compression integer
output_format string
promptrequired string May carry a trailing <sd_cpp_extra_args>{…}</sd_cpp_extra_args> block of raw sd.cpp CLI arguments; the dashboard's Image lab builds this block and is the reference for its contents.
size string
Example
{
  "model": "<pick a model>",
  "n": 1,
  "prompt": "A red bicycle in a park."
}

Responses

StatusDescription
200 OK.
application/json ImageGenerationsResponse
Fields of ImageGenerationsResponse
createdrequired integer
datarequired array of any | any
b64_json string
revised_prompt string
url string

Headers: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
default Error.
application/json OpenAiError

Headers: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
get/v1/models

List models

Capability inference, open to: agent, device, key, owner

Aggregates enabled aliases, public local models and expose-all upstream catalogs. Served OpenAI-shaped unless the caller sends anthropic-version, in which case the Anthropic SDK's own shape. This document names the OpenAI error dialect as default; an Anthropic-dialect caller gets an Anthropic-shaped error body in practice.

Also takes x-lmgw-run (see lmgw headers).

Responses

StatusDescription
200 OK.
application/json ModelList
ModelList: 2 shapes
object
Fields
datarequired array of OpenAiModel
lmgwrequired object
endpointsrequired object Every path listed here exists in this API and carries the capability its own operation documents.
anthropicrequired array of string
openairequired array of string
otherrequired array of string
headersrequired object
notesrequired array of string
versionrequired string
objectrequired string One of list.
object
Fields
datarequired array of AnthropicModel
first_id null
has_morerequired boolean One of false.
last_id null
lmgwrequired object
endpointsrequired object Every path listed here exists in this API and carries the capability its own operation documents.
anthropicrequired array of string
openairequired array of string
otherrequired array of string
headersrequired object
notesrequired array of string
versionrequired string
default Error.
application/json OpenAiError
get/v1/models/{id}

Retrieve a model

Capability inference, open to: agent, device, key, owner

The id may contain '/' (a passthrough id carries its upstream prefix and the provider's own slashes), hence the wildcard path parameter. Same dual-dialect note as GET /v1/models.

Parameters

NameInDescription
idrequiredpath string

Also takes x-lmgw-run (see lmgw headers).

Responses

StatusDescription
200 OK.
application/json ModelById
ModelById: 2 shapes
OpenAiModel
Fields of OpenAiModel
capabilities ModelCapabilities
context_length integer
createdrequired integer Stable for the life of the gateway process rather than the time of each request; the catalog's own timestamp when it has one.
idrequired string
max_output_tokens integer
notes array of string
objectrequired string One of model.
owned_byrequired string
pricing object
completionrequired string
promptrequired string USD per prompt token, as a decimal string; "0" for a local model.
AnthropicModel
Fields of AnthropicModel
capabilities AnthropicModelCapabilities
context_window integer
created_atrequired string (date-time)
display_namerequired string
idrequired string
lifecyclerequired string Always active: a model lmgw lists is one it serves. One of active.
max_input_tokens integer Alias of context_window, under the name the Anthropic SDK types it by.
max_output_tokens integer
max_tokens integer Alias of max_output_tokens.
notes array of string
pricing object
completionrequired string
promptrequired string USD per prompt token, as a decimal string; "0" for a local model.
typerequired string One of model.
default Error.
application/json OpenAiError
get/v1/realtime

Open a realtime voice session

Capability inference, open to: agent, device, key, owner

OpenAI's GA Realtime protocol over a WebSocket (ws://<host>/v1/realtime), answered by a cascade of this gateway's own aliases: voice activity and end-of-turn detection inside lmgw (Silero VAD; Smart Turn for semantic_vad), speech to text with realtime.asr_alias, the chat model, and text to speech with realtime.tts_alias — local models first, any of them a cloud alias if so configured (Settings → Realtime, which also shows what the cascade holds on the GPU). model is resolved in this order: a realtime.model_map name, an OpenAI Realtime name (gpt-realtime*, never taken as an alias), which realtime.default_model answers, or a chat alias; it may be left out and named in the first session.update instead. What a name resolved to is echoed in session.lmgw.resolved. Implemented: conversation sessions (session.type realtime) with audio or text output, PCM16 at 24 kHz in and out, server_vad, semantic_vad and manual turns, barge-in with a word check, session.update, input_audio_buffer.append/commit/clear, conversation.item.create/retrieve/truncate/delete, response.create and response.cancel, client-side function tools, and MCP tools the gateway runs itself on a session not bound to a Chat thread. An MCP session tool {"type": "mcp", "server_label"} names one of this gateway's own MCP servers (by its tool prefix or name) or a built-in toolset (docs, kb, and lmgw for an owner credential or a device allowed lmgw's admin tools, while the self-admin tools are on), resolved as on /v1/responses under the key's tool scope; GET /v1/mcp/servers lists the labels a caller may use and GET /v1/mcp/servers/{label} one label's tools. server_url, connector_id, headers, authorization and server_description are accepted and never used: lmgw dials no URL a client names, and echoes authorization and header values as [redacted]. allowed_tools takes a name list or {tool_names}; read_only and a require_approval that would gate a tool are refused (approvals are not built here yet: leave it out or send "never"); one entry per server_label. The session lists a label's tools as an mcp_list_tools item (mcp_list_tools.in_progress, then .completed or .failed — a failed label also gets an error with code mcp_list_tools_failed saying why, and a later session.update naming it lists it again), and a response waits for the listings in flight. A model's call to one of those tools is an mcp_call item (server_label, name — the server's own tool name — arguments, output, error, always present), streamed as response.mcp_call_arguments.delta and .done, then run by the gateway before response.done (response.mcp_call.in_progress, then .completed with the output or .failed with a tool_execution_error). The call ends the response: the client sends response.create for the answer, as OpenAI's Realtime API has it (@openai/agents does so by itself, once per response). A cancel or barge-in abandons a running call, which then fails saying it may or may not have run. A response's tools may narrow to a label the session has listed, and tool_choice takes {"type": "mcp", "server_label"} with an optional name. A client may replay mcp_call items as history; mcp_list_tools and the approval items are refused. Each call writes a realtime-tool usage row. Refused with an error naming what is missing: transcription sessions, G.711 formats, output_audio_buffer.clear (a WebRTC call's) and an input_audio item without its transcript. Accepted and echoed but not applied: noise_reduction, and truncation (lmgw.resolved.truncation says "disabled"; an overflow is an error). WebRTC is served at POST /v1/realtime/calls. Not served at all: the sideband connection to a call (call_id, refused with 400 sideband_unsupported rather than opening an unrelated session), SIP, ephemeral client secrets, live partial transcripts and out-of-band responses. Credentials as on every /v1 route; a browser, which cannot set headers on a WebSocket, may offer its key as the subprotocol openai-insecure-api-key.<key> alongside realtime — accepted on this route only. A paired device's key is refused before the upgrade with 401 device_key_unknown when it matches no device (pair it again), 401 device_disabled while the device is disabled, and 401 key_expired past its expiry date, as on every Chat route. A beta client (OpenAI-Beta: realtime=v1) is refused with 400 beta_protocol_unsupported, and with Require API key off an anonymous upgrade from another page's Origin is refused with 403. Chat models list this route in their capabilities.endpoints on GET /v1/models once an ASR and a TTS alias are configured, and /v1/realtime/calls beside it while the WebRTC UDP socket of the listener asked is bound. The TTS gets lmgw's speech instructions — session.lmgw.speech_instructions, a response.create's response.lmgw.speech_instructions, else realtime.speech_instructions — as a style, or as the description a voice-design (vdes) model designs its voice from; session.lmgw.resolved.speech says what is in effect, and the transcript leaves out the inline tags ([laughter]) the voice renders. Markdown a voice cannot read is not spoken: fenced code blocks and tables (lines that start with |, from one that ends with | or is followed by a delimiter row) are skipped — the transcript leaves them out, and the model's history keeps them. On a style or passthrough TTS that renders no tags (Qwen3 CustomVoice, Auk, MOSS-TTS; a cloud TTS only when its alias's capabilities.speech override declares instructions 'style'), the tags that open a sentence, or a part of one spoken on its own, are a delivery cue instead ([laughing]): sent after the style as the instructions until that sentence ends, best effort, never read out (resolved.speech.cues). A voice mode binds a session to a Chat thread with chat_thread=<id> (negative for a temporary chat): the chat capability only — the dashboard's cookie, an owner key or a paired device's key; refused before the upgrade, in the OpenAI error shape ({"error": {code, message, type, param}}) and checked in this order, with 403 chat_thread_not_allowed, 400 owned_by_thread beside model, 404 chat_thread_not_found (also an Admin Chat thread a device names, and a thread with the self-admin toolset a device not allowed lmgw's admin tools names: for that device they do not exist), 409 chat_thread_admin for an Admin Chat thread the owner names (no voice mode there), and, with takeover=never, 409 chat_thread_bound while another session is bound to the thread ("voice is in use on device 'phone'"; nothing is taken over), whose error.held_by names the holder as the Chat feed's voice.bound.by does ("device 'phone'", "the dashboard") so a client shows it without reading the message; no other refusal carries held_by. A session bound with the same key, or one that is already ending (after its 1001, a revocation or its close, while it writes its last turns), does not count: takeover=never takes it over, so a client's rebind after a restart or a dropped link is not refused in its own name. A device binds as its key: the thread's chat, speech-to-text and text-to-speech aliases pass its scope and budget before the upgrade (refused as an unbound session's aliases are, 403 key_scope or key_budget; the speech aliases' missing price, budget_unpriced, too), while the chat alias's price check comes at the first turn, as an error event, not before the upgrade; every model call of the session is checked and counted against it as an unbound session's, and each refusal writes its request row. session.created then names the thread in session.lmgw.resolved.chat_thread ({id, title, temporary, admin_tools}) and its turn mode in session.lmgw.turn_mode (below), and the connect warm loads the thread's chat, speech-to-text and text-to-speech models as one group, which may evict idle models as the requests it announces would, whatever realtime.warm_on_connect says (that setting is for unbound sessions). chat_folder=<id> binds an ongoing folder's current thread instead, decided by the rules of POST /chat/api/folders/{id}/current and bound in one step under the folder's lock, so no other client moves the folder in between: the current thread, or a new one from the folder's defaults when there is none, when it is out of the caller's reach, when it idled past the folder's idle minutes, or with new=true unless it has no message yet; a new thread is recorded as folder.current on the Chat feed with its reason, and the thread bound is reported in session.lmgw.resolved.chat_thread as for chat_thread. It is refused beside chat_thread (400 invalid_value) and model (400 owned_by_thread), new without chat_folder and takeover with neither parameter are 400 invalid_value, then come 404 chat_folder_not_found (a folder the caller cannot see), 409 not_ongoing and 409 folder_no_model, then the thread's own refusals, checked on the thread the decision picks before a new one is made. takeover=ask is a WebRTC call's and 400 invalid_value here. A bound session carries session.lmgw.turn_mode, automatic or push_to_talk, resolved from the thread's turn detection at the bind (push_to_talk there is push_to_talk, anything else automatic), and lmgw sets audio.input.turn_detection to match: the thread's rule (server_vad or semantic_vad, semantic_vad where it names none) in automatic mode, null in push_to_talk; session.created echoes both. A session.update naming turn_mode switches it and gets the turn detection it implies (the mode in effect named again leaves the detection as it is); one that also names audio.input.turn_detection must agree with it (null with push_to_talk, a rule with automatic), as an echo of the whole session does, else invalid_value; turn detection named alone still works and turn_mode follows it. A change of the thread's turn detection applies at the next bind. An unbound session has no turn_mode, and refuses one with invalid_value. The thread then owns the chat model, prompt, tools, speech models, voice, speech style, language, seed and conversation: a session.update that changes one of them, a response.create that overrides one, and conversation.item.create or .delete are refused with owned_by_thread (an echoed value is accepted). Each response is the thread's own chat turn — its model, prompt with the spoken-style instructions after it, sampling, attachments, knowledge bases and MCP tools, which never become function_call items — written to the thread's history: the user turn with how it was spoken, the reply cut to what was heard (the unheard rest kept beside it, a reply nobody heard deleted unless it ran tools), never over a turn another window started meanwhile. Code blocks and tables are announced rather than skipped silently ("Code block, rust.", "Table."; in the thread's language for en, de, fr, es and it), and the dashboard's read-aloud of a reply speaks the same way. No audio is stored: a spoken turn is kept as text. With chat_voice_audio_input on (Settings, or the thread's voice.audio_input), a turn whose answering model takes audio input — the thread's chat model, or the fallback a GPU hold, a benchmark run, an outside-VRAM verdict or a candidate alias hands it to, wherever it runs — goes to it as audio at the commit, while the speech-to-text model transcribes it beside (a model that does not take audio input, one whose capabilities lmgw cannot read, or one lmgw cannot send audio to, such as an Anthropic upstream, is refused it before anything is sent, and the turn goes again as its transcript); the reply is held until the transcript is in, then plays (a thread with no speech-to-text model that resolves always goes as its transcript: only the transcript tells words from noise). A turn that came back without words ends the response quietly as response.done {cancelled, reason no_words}, with no error and nothing written; a failed transcription of a turn the model heard (it answered from the audio) plays the reply and marks the user message (voice.transcript_error) instead of sending transcription.failed, while one no model heard yet, or a turn never transcribed at all (no speech-to-text model, the key's policy, the session's end), is said as with the setting off and ends the response quietly as response.done {cancelled, reason transcription_failed}. A new turn cuts a held reply whatever interrupt_response says, and a held reply's tools run only once its user message is written (a turn that came back without words runs none). A model's server that refuses the audio gets the transcript once, and the session's later turns to that model go as text when the refusal names the audio or the transcript retry answered (a server that went away under the audio is not retried, and its later turns go as text too). One session per thread: a second bind takes the thread over, and the older session gets error chat_thread_taken_over and the close 4000, both naming who bound it ("voice mode moved to device 'phone'", "… to the dashboard") — unless the second bind gives takeover=never, which a client uses for its own automatic rebinds so it never takes the voice from another device; a user's explicit choice to talk binds without it. A bound session — and no other — also sends lmgw's own events: lmgw.chat.frame ({response_id, event, data}: the chat turn's frames verbatim — turn, retrieval, delta, reasoning, tool, usage, stats, stop, state, error, done; a tool frame's ready and result carry call_id, server_label and ui_resource (the namespaced MCP Apps UI resource the tool links to, for resources/read on /mcp; null when none), ready needs_approval, and result structured_content (the MCP result's structuredContent; null when none) and content (its content blocks as the server sent them), and approval the waiting call's approval_request_id, server_label, name, arguments and call_id (the id its ready frame carried); reasoning is shown, stored with the reply and never spoken, and done's reasoning_note says in a sentence when the model reasoned although the turn asked for reasoning off — a voice turn does unless the thread sets reasoning; no off ends in an error — and its images_note when a fallback that cannot see answered and got the turn's images as placeholders), lmgw.chat.user ({message_id, content, voice (a MessageVoice), response_id}: response_id when that response heard the turn as audio, whose user message is written once the turn is transcribed, after the reply may have started — the page puts it before that reply), lmgw.chat.input ({response_id, input: audio or transcript, why}: how a response's turns reach the chat model and why the transcript, sent at each launch, when an audio attempt was refused, and when a llama-server that went away under the audio sends the session's later turns to it as text; never with chat_voice_audio_input off), lmgw.chat.reply (the ChatReply type: {message_id, content, unheard, voice (a MessageVoice)}, {message_id, removed: true} or {message_id, skipped, voice}: the reply as stored once its response ended, cut to what lmgw knew was heard; a conversation.item.truncate that arrives after that cuts it again at the position the client heard, and sends a second lmgw.chat.reply for the same message_id, which replaces the first), lmgw.model.state ({stage, alias, state, ms, …}: the connect warm's and each turn's model loading), lmgw.chat.thread ({chat_thread: {id, title, temporary, admin_tools}}: the thread as a response re-read it, when that differs from session.lmgw.resolved.chat_thread — a title the first spoken turn named, the admin tools switched on or off) and lmgw.response.timing (a VoiceTiming, flat: {response_id, message_id, end_of_turn_ms, asr_ms, first_token_ms, reasoning_ms, first_clause_ms, first_audio_ms, total_ms, to_first_audio_ms, cold, models: {asr, chat, tts}, input, input_why, transcript_wait_ms}: the timing log line as data, each stage measured from the one before, reasoning_ms the part of first_token_ms the model reasoned (absent when it did not), cold naming the stages that loaded, input whether the chat model heard the turn as audio or read its transcript, input_why why the transcript, transcript_wait_ms how long the first output was held for the transcript (the three absent with chat_voice_audio_input off, transcript_wait_ms on the transcript path), each model with the alias that answered when a fallback did, first_clause: "announcement" when the first clause said was one; sent once the reply is written, message_id null when nothing was saved, and stored with the reply), lmgw.approval.decided ({approval_request_id, approve, by}: a call whose mcp_approval_request item the session showed was decided by another client, by naming who as the feed names authors; approve false and by null for one whose reply was edited or deleted) and lmgw.task.done ({thread_id, message_id, id, task_id, server_label, tool, status, by}: a late MCP task result entered the thread as message message_id of role tool — the feed's task.done facts; it enters only while no turn of the thread runs, so one that ended during a response is said once that response's turn ended; one said while a response runs entered at that response's start, and that response answers it). Three more lmgw events belong to a WebRTC call bound to a Chat thread and are never sent or read on this WebSocket, whose closes say the same with their codes: lmgw.session.bind_pending ({held_by}: under takeover=ask the thread was held when the call's channel opened; no session runs until the client sends lmgw.session.take_over ({}) to take it, the holder ends and the call binds by itself, or the wait of one realtime.ping_interval_s runs out; a holder that changes brings another), and lmgw.session.closed ({kind, by, message}: the bound call's last event, kind one of taken_over, revoked, out_of_reach, shutting_down, closed and thread_bound, by the new binder, the holder or who hung up and otherwise null, message the sentence a WebSocket close's reason carries, led by the revocation token for revoked). by and held_by name a client as voice.bound.by does. lmgw starts no response for a result: the client's own response.create with no new words and no turn the client committed before it, while the thread holds results no reply answered (said in this session, or there before the bind), is a continuation that answers them, as POST /chat/api/threads/{id}/answer does (turn detection's automatic response to a turn without words stays empty_turn, and so does a push-to-talk commit of silence and its response.create; a continuation a cough cut before any of it was heard runs again after the cough) — it never cancels a turn of the thread (response.done failed with turn_running while one runs), and is empty_turn when a turn of another window answered the results meanwhile. A bound turn's call that waits for an approval (the thread's require_approval) is OpenAI's mcp_approval_request item (conversation.item.added and .done; its id is the approval id; OpenAI's shape, so no call id: the lmgw.chat.frame relaying the turn's approval frame, sent right after the item, carries call_id beside the same approval_request_id) and its response ends; the client answers with conversation.item.create of {type: mcp_approval_response, approval_request_id, approve, reason?} — the one item a bound session takes — then response.create, and that response resumes the thread's turn as POST /chat/api/threads/{id}/approvals does, the session's principal the approver: the approved calls run and the answer comes in that one response. A refusal of the answers fails the response with the route's code (approval_missing, approval_not_found, approval_decided, approval_starter_unavailable, approval_moved_on, approval_out_of_scope, key_rate). A committed turn with words is a new message, which declines what waits: a response that answers one runs as ever. Keep a spoken answer out of the session (transcribe it with POST /chat/api/threads/{id}/transcribe). A refusal mid-session is an error event; its codes: owned_by_thread (a client event changing what the thread owns), empty_turn (a response that would answer no turn and no job result), turn_running (a continuation while a turn of the thread runs), superseded and not_saved (another turn took the thread, or the reply could not be saved; its speech stops), chat_thread_not_found and chat_thread_admin, tts_not_configured, voice_not_configured, voice_not_found, instructions_required, voice_needs_transcript and speech_unavailable (the thread's speech, judged per response after response.created), chat_history_write_failed (the store refused the spoken turn; its words lead the next user message), and chat_thread_taken_over before the takeover's close. A session opened with a key ends when the key is revoked — disabled, rotated or deleted on the Keys page, or past its expires_at — with the close 4003 (any key's session, a device's or not). Its reason starts with a token saying what to do, then a colon and the sentence: device_disabled (a paired device was disabled), key_expired (a paired device's key expired), key_unknown (a paired device's key was replaced or deleted: pair it again), certificate_expired (a paired device's client certificate passed its notAfter: pair it again) or revoked (any other kind of key), e.g. "device_disabled: device 'desktop' was disabled"; reconnecting with the same key is refused. A device's session bound to a thread that leaves the device's reach — the self-admin toolset attached to it, or what the device's admin tools may do set to off — closes with 4004 and the neutral reason "chat thread <id> is out of reach for this key": the key is still good, and a client asks for its current thread again. Another client binding the thread closes the session with 4000. Every session closes with 1001 ("lmgw is stopping or restarting") when the gateway stops or restarts.

Parameters

NameInDescription
call_idquery string | null
chat_folderquery integer | null
chat_threadquery integer | null
modelquery string | null
newquery boolean | null
takeoverquery Takeover | null

Also takes x-lmgw-run (see lmgw headers).

Responses

StatusDescription
101 Switching Protocols: the connection is now a WebSocket. Each frame is one JSON text event of OpenAI's GA Realtime protocol: client events in, server events (each with a server-minted event_id) out. session.created arrives first.
Headers: Sec-WebSocket-Protocol
426 Upgrade Required: the request carried no WebSocket upgrade headers.
application/json OpenAiError
default Error, before the upgrade.
application/json OpenAiError
post/v1/realtime/calls

Start a realtime call (WebRTC)

Capability inference, open to: agent, device, key, owner. Changes state.

OpenAI's WebRTC transport for the Realtime API. The client POSTs its SDP offer — audio with Opus, and the data channel oai-events created before createOffer — as application/sdp, or as multipart/form-data with the part sdp and an optional session part: a JSON object, the session as session.update takes it. The answer is 201 Created with the SDP answer (application/sdp: ICE-lite, one UDP host candidate — the local address this POST arrived on, on the WebRTC UDP port: realtime.webrtc_port, by default the HTTP port's number, or on the device listener its own port — Opus only, with RED when the offer carries it) and Location: /v1/realtime/calls/{call_id}, the call's id rtc_ and 24 hex digits. Behind it runs the session GET /v1/realtime runs — the same cascade, binding and policy — its events as JSON text on oai-events and its audio on RTP. lmgw's audio is one Opus stream for the call's whole life, a frame every 20 ms (realtime.webrtc_output_kbps, capped by the offer's maxaveragebitrate; DTX only when the offer's Opus format says usedtx=1; in-band FEC following the client's receiver reports), silence between answers; the client's audio is heard from its first frame after DTLS connects, what it sent before oai-events opened included, and an input_audio_buffer.commit takes the frames captured up to realtime.webrtc_commit_window_ms after it arrived. oai-events carries no audio: no response.output_audio.delta, input_audio_buffer.append is answered invalid_event, and session.lmgw.output_lead_ms is 0. Every call hears OpenAI's output_audio_buffer.started ({response_id}) with an answer's first frame, and .stopped right after the response.done of one that played out, or .cleared after the response.done of one that was cut (a barge-in, a cancel, a clear, a stop); output_audio_buffer.clear cancels the answer whose audio plays and is silent with none. An event over the client's max-message-size (or realtime.max_message_mb below it) arrives on an unbound call with its largest fields emptied, each followed by an error event_too_large naming the field's path. A call bound to a Chat thread also hears lmgw.output_audio.starved ({response_id, starved}) when an answer's audio runs dry and when it comes again, and may report its playout with lmgw.output_audio.playout ({playout_ntp_ms?, jitter_buffer_ms?}), which the answer's end follows; it stops with lmgw.response.stop ({playout_ntp_ms?}: the open response, the one owed and a held response.create cancelled, heard cut at the client's playout position when it sends one and what was sent otherwise, as on an audio-only call, where libwebrtc does not fill estimatedPlayoutTimestamp (calls design Q5); nothing with nothing open); an event over the limit travels both ways as lmgw.event.part ({id, index, count, data}, back to back, id the event's event_id), joined by the receiver, a client's up to realtime.max_message_mb. An unbound call answers these lmgw events invalid_event. The session starts when oai-events opens: session.created, then the session part applied as the session's first update (session.updated, or an error as for any update; on a call bound to a Chat thread it may change only what a bound session's client owns). Credentials, model resolution and the key's scope, budget and concurrency slot are /v1/realtime's — the slot held from this POST until the call ends — the subprotocol key aside; with Require API key off, an anonymous call from another page's Origin is refused with 403 cross_origin_refused. The query is /v1/realtime's: model, chat_thread or chat_folder with new, and takeover. A call bound to a Chat thread or folder only checks at this POST — nothing is bound and no thread is made — and binds when oai-events opens, checking again: takeover left out takes the thread over (its holder closes as taken over); never ends the call with lmgw.session.closed {kind: thread_bound, by} when the thread is held then, and is the 409 chat_thread_bound, the holder in error.held_by, when it is held at this POST; ask, this route's own, makes the call wait with lmgw.session.bind_pending ({held_by}): the client's lmgw.session.take_over ({}) takes the thread, a holder that ends lets the call bind by itself, a third client taking the thread brings another bind_pending, every other event meanwhile is answered with error bind_pending and the audio is discarded, and one realtime.ping_interval_s after the latest bind_pending the call ends with thread_bound (no bound at 0). A take_over that crosses the bind is ignored. A bound call's last event before lmgw ends it is lmgw.session.closed ({kind, by, message}: kind taken_over, revoked, out_of_reach, shutting_down, closed or thread_bound; by the new binder, the holder or who hung up, else null; message the sentence a WebSocket close's reason carries, led by the revocation token for revoked). A refusal when oai-events opens is that event — out_of_reach for a thread or folder out of the caller's reach, revoked for a key revoked since this POST, closed after an error carrying the refusal's code otherwise. by and held_by name a client as the Chat feed's voice.bound.by does. An unbound call sends no lmgw event and closes with nothing in band, as OpenAI's do. A call whose ICE, DTLS or data channel never comes up ends one realtime.ping_interval_s after its answer, binding nothing. Refused before the answer: 400 invalid_value (the query, a parameter rule, or a session part that is no JSON object or is over realtime.max_message_mb, which bounds a session event on either transport), 400 bad_request (a multipart body that does not parse), 400 sideband_unsupported (call_id), 400 owned_by_thread, 400 missing_sdp (a multipart body without sdp), 400 invalid_sdp (the offer does not parse; the reason quoted), 400 unsupported_offer (no Opus audio, or no data channel), 400 beta_protocol_unsupported, 403 cross_origin_refused, the bind's refusals (403 chat_thread_not_allowed, 404 chat_thread_not_found and chat_folder_not_found, 409 not_ongoing, folder_no_model, chat_thread_admin and chat_thread_bound), the key's 401, 403 and 429, 413 over max_body_mb, 415 unsupported_media_type, and 503 webrtc_unavailable when realtime.webrtc_enabled was off at lmgw's start, or the listener's UDP sockets failed to bind or are not bound (the message names the setting or the error), and, with a Retry-After header, while the device listener's group moves with it or when the POST's connection belongs to an earlier start of it. The device listener's UDP sockets follow its addresses and port: a change of the device listener ends its calls, a bound call's last event lmgw.session.closed {kind: shutting_down}, and leaves the plain listener's running. Not served: the sideband WebSocket, SIP's accept, reject and refer, and ephemeral client secrets.

Parameters

NameInDescription
call_idquery string | null
chat_folderquery integer | null
chat_threadquery integer | null
modelquery string | null
newquery boolean | null
takeoverquery Takeover | null

Also takes x-lmgw-run (see lmgw headers).

Request body required

application/sdp: string

multipart/form-data: object

sdprequired string The SDP offer (application/sdp): audio with Opus, and the data
channel oai-events, created before createOffer.
session object The session (application/json): a JSON object, the session as
session.update takes it — OpenAI's GA session object. Not checked
before the answer: the session applies it as its first update, right
after session.created and before any event of the client's, and
answers it as any update, session.updated or an error. On a call
bound to a Chat thread only what the client owns applies (turn
detection or lmgw.turn_mode, lmgw.half_duplex, lmgw.echo_tail_ms).

Responses

StatusDescription
201 Created.
application/sdp string

Headers: Location
default Error.
application/json OpenAiError
post/v1/realtime/calls/{call_id}/hangup

Hang up a realtime call

Capability inference, open to: agent, device, key, owner. Changes state.

Ends a call: its session ends as if the client had closed it, a bound call's last event being lmgw.session.closed {kind: closed, by} naming who hung up. Answered 200 with an empty body once the call has let go — its Chat thread's binding marked as ending and its concurrency slot back — so a call posted right after it is neither refused (takeover=never) nor left pending (takeover=ask) by the call it ended. A call whose session or bind has not let go 10 s after the hangup (the bound a stopping server gives its sessions) is closed by force and answered 200 then; its binding is marked as ending only once its session notices, so a takeover=never call right after such a 200 may still be refused by it for that moment. A call that has let go but still waits for its last events' delivery (closing) is closed at once, without them, and answered 200. Takes no concurrency slot and counts no request, so a key at its limit can still hang up. Allowed for the key that made the call and for the owner; anyone else, and a call that has ended, gets 404 call_not_found.

Parameters

NameInDescription
call_idrequiredpath string

Also takes x-lmgw-run (see lmgw headers).

Responses

StatusDescription
200 OK.
default Error.
application/json OpenAiError
post/v1/responses

Create a response

Capability inference, open to: agent, device, key, owner. Changes state.

lmgw's own Responses API implementation; llama-server has none. MCP tools run server-side on lmgw's registered MCP servers. An upstream that implements the Responses API itself (the OpenAI platform, a compatible row flagged for it) gets the body as sent, hosted tools, item references and truncation:"auto" included, unless only lmgw's loop can serve the request; the loop refuses those rather than approximating them. background:true is refused on every path. An anthropic-beta header is forwarded when the route is an Anthropic upstream.

Also takes x-lmgw-reasoning, x-lmgw-reasoning-effort, x-lmgw-reasoning-budget, x-lmgw-background, x-lmgw-run (see lmgw headers).

Request body required

application/json: ResponsesRequest

Fields of ResponsesRequest
background boolean true is refused on every path: a background response finishes after its answer has left, so lmgw could never record what it spent or hold it to a budget.
include array of string
input any A string (one user turn), or an array of items.
instructions string Becomes the leading system message; an explicit empty string drops it on a chained call.
max_output_tokens integer
max_tool_calls integer
metadata any Echoed back verbatim on the response object.
modelrequired string
parallel_tool_calls boolean Default true.
previous_response_id string Continues a stored response: its conversation, tool calls and results included, goes ahead of this call's input, and mcp_approval_response items settle the calls it stopped at. 400 while the gateway's response store is switched off; 404 when no stored response has this id (it was evicted, or created with storing off). On an upstream that implements the Responses API itself, an id lmgw holds continues in lmgw's own loop and any other id goes to the upstream with the body; with mcp tools lmgw serves, such an id is a 400, since neither side can serve both.
reasoning object The one reasoning control this dialect reads: reasoning.effort.
effort string
service_tier string OpenAI's processing tier (auto, default, flex, priority, fast, scale, ultrafast), forwarded as sent; on an OpenAI platform row lmgw sends auto when it is unset, and prices the answer at the tier the answer reports. A request by a caller with a budget (its key's, or the gateway's) on a cloud model with no price on file for what it is billed in is refused before the send: 403 budget_unpriced, naming the model and the missing price. A flex request needs a flex price: no other tier's price bounds a flex answer's spend, which is cheaper.
store boolean Whether lmgw keeps this response, so a later call can continue it with previous_response_id (default true). Storing also needs the gateway's response store, which is on by default: a request can turn storing off, never on. The response object's store says whether this response was kept, so a client can see up front whether previous_response_id will work. On an upstream that implements the Responses API itself the body goes there as sent, and storing is the provider's.
stream boolean Default false.
temperature number
text object text.format (json_schema, json_object, text) is the structured output every upstream gets in its own spelling, as on /v1/chat/completions; a native Responses upstream gets the body as sent. Its refusals are 400 response_format_unsupported / invalid_json_schema with param text.format.
tool_choice any "auto" | "none" | "required" | {type:function,name} everywhere; any other form the upstream's API defines ({type:web_search_preview}, {type:allowed_tools,…}, {type:mcp,server_label}, …) goes natively to an upstream that implements the Responses API itself and is refused by lmgw's own loop.
tools array of object | object | object function tools the loop hands back to the client; mcp tools run server-side on lmgw's own registered MCP servers, and keep the request in lmgw's own loop on an upstream that implements the Responses API itself (an mcp label lmgw does not serve goes there with the body). Hosted tools (web_search, file_search, code_interpreter, image_generation, computer_use_preview, …) go natively to such an upstream, which runs them, and are refused by lmgw's own loop.
top_k integer
top_p number
truncation string "auto" goes natively to an upstream that implements the Responses API itself; lmgw's own loop refuses it, since it never silently drops conversation history.
Example
{
  "input": "Say hello in one short sentence.",
  "model": "<pick a model>"
}

Responses

StatusDescription
200 OK.
application/json Response
Fields of Response
access_programs null Always null; present because OpenAI's schema requires the field.
created_atrequired integer
errorrequired object | null
idrequired string
incomplete_detailsrequired object | null
reasonrequired string
modelrequired string
objectrequired string One of response.
outputrequired array of object Items are loosely typed here. An output_text part of a message item carries logprobs: []: lmgw relays no log probabilities yet; OpenAI's schema requires the field.
statusrequired string One of queued, in_progress, completed, incomplete, failed, cancelled.
store boolean Whether lmgw stored this response, so a later request can continue from it with previous_response_id. Sent by lmgw's own translation; a verbatim upstream body may leave it out.
usage object | null
input_tokensrequired integer
input_tokens_detailsrequired object Tokens read from and written to the prompt cache, both part of input_tokens; 0 when the upstream reported none (cache_write_tokens is lmgw's own addition and absent from a verbatim upstream body).
cache_write_tokens integer
cached_tokensrequired integer
output_tokensrequired integer
output_tokens_detailsrequired object
reasoning_tokensrequired integer
total_tokensrequired integer
text/event-stream string
1 event types

response


Headers: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason, x-lmgw-images-omitted, x-lmgw-max-tokens-clamped, x-lmgw-max-tokens-defaulted, x-lmgw-max-tokens-raised, x-lmgw-params-ignored, x-lmgw-params-refused, x-lmgw-reasoning-ignored, x-lmgw-rung
default Error.
application/json OpenAiError
post/v1/responses/input_tokens

Count a response's input tokens

Capability inference, open to: agent, device, key, owner

The OpenAI SDKs' responses.input_tokens.count(): the body a Responses create would send (input, instructions, function tools, a previous_response_id's stored conversation in front), counted on the route the model resolves to as the other counters count — exact on an Anthropic upstream (the Messages body the send would render, on Anthropic's own counter), a Gemini upstream and a local llama.cpp chat row; otherwise flattened, which x-lmgw-count-approximate says. mcp tools' definitions are not counted yet (tools_omitted), and what only an upstream's own Responses API serves is refused by name. Enforces the key's alias scope like every other counter; no budget applies.

Also takes x-lmgw-reasoning, x-lmgw-reasoning-effort, x-lmgw-reasoning-budget, x-lmgw-background, x-lmgw-run (see lmgw headers).

Request body required

application/json: ResponsesRequest

Fields of ResponsesRequest
background boolean true is refused on every path: a background response finishes after its answer has left, so lmgw could never record what it spent or hold it to a budget.
include array of string
input any A string (one user turn), or an array of items.
instructions string Becomes the leading system message; an explicit empty string drops it on a chained call.
max_output_tokens integer
max_tool_calls integer
metadata any Echoed back verbatim on the response object.
modelrequired string
parallel_tool_calls boolean Default true.
previous_response_id string Continues a stored response: its conversation, tool calls and results included, goes ahead of this call's input, and mcp_approval_response items settle the calls it stopped at. 400 while the gateway's response store is switched off; 404 when no stored response has this id (it was evicted, or created with storing off). On an upstream that implements the Responses API itself, an id lmgw holds continues in lmgw's own loop and any other id goes to the upstream with the body; with mcp tools lmgw serves, such an id is a 400, since neither side can serve both.
reasoning object The one reasoning control this dialect reads: reasoning.effort.
effort string
service_tier string OpenAI's processing tier (auto, default, flex, priority, fast, scale, ultrafast), forwarded as sent; on an OpenAI platform row lmgw sends auto when it is unset, and prices the answer at the tier the answer reports. A request by a caller with a budget (its key's, or the gateway's) on a cloud model with no price on file for what it is billed in is refused before the send: 403 budget_unpriced, naming the model and the missing price. A flex request needs a flex price: no other tier's price bounds a flex answer's spend, which is cheaper.
store boolean Whether lmgw keeps this response, so a later call can continue it with previous_response_id (default true). Storing also needs the gateway's response store, which is on by default: a request can turn storing off, never on. The response object's store says whether this response was kept, so a client can see up front whether previous_response_id will work. On an upstream that implements the Responses API itself the body goes there as sent, and storing is the provider's.
stream boolean Default false.
temperature number
text object text.format (json_schema, json_object, text) is the structured output every upstream gets in its own spelling, as on /v1/chat/completions; a native Responses upstream gets the body as sent. Its refusals are 400 response_format_unsupported / invalid_json_schema with param text.format.
tool_choice any "auto" | "none" | "required" | {type:function,name} everywhere; any other form the upstream's API defines ({type:web_search_preview}, {type:allowed_tools,…}, {type:mcp,server_label}, …) goes natively to an upstream that implements the Responses API itself and is refused by lmgw's own loop.
tools array of object | object | object function tools the loop hands back to the client; mcp tools run server-side on lmgw's own registered MCP servers, and keep the request in lmgw's own loop on an upstream that implements the Responses API itself (an mcp label lmgw does not serve goes there with the body). Hosted tools (web_search, file_search, code_interpreter, image_generation, computer_use_preview, …) go natively to such an upstream, which runs them, and are refused by lmgw's own loop.
top_k integer
top_p number
truncation string "auto" goes natively to an upstream that implements the Responses API itself; lmgw's own loop refuses it, since it never silently drops conversation history.
Example
{
  "input": "Say hello in one short sentence.",
  "model": "<pick a model>"
}

Responses

StatusDescription
200 OK.
application/json ResponseInputTokens
Fields of ResponseInputTokens
input_tokensrequired integer
objectrequired string One of response.input_tokens.

Headers: x-lmgw-candidate, x-lmgw-count-approximate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
default Error.
application/json OpenAiError

Headers: x-lmgw-candidate, x-lmgw-count-approximate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
delete/v1/responses/{id}

Delete a response

Capability inference, open to: agent, device, key, owner. Changes state.

Deletes a stored response, or has the upstream that made a native one delete it. Read as GET is: another key's response is a 404.

Parameters

NameInDescription
idrequiredpath string

Also takes x-lmgw-run (see lmgw headers).

Responses

StatusDescription
200 OK.
application/json ResponseDeleted
Fields of ResponseDeleted
deletedrequired boolean One of true.
idrequired string
objectrequired string One of response.
default Error.
application/json OpenAiError
get/v1/responses/{id}

Retrieve a response

Capability inference, open to: agent, device, key, owner

A stored response, exactly as it was served. It is present only when lmgw stored it — the creating call left store on (the default) while the gateway's response store was on — and only until retention evicts its conversation as a whole: by default 168 hours after the conversation's last activity, or once it falls outside the 500 most recently active conversations. A response an upstream that implements the Responses API made itself (created with store left on) is fetched from that upstream, query string included, and relayed as it answers, for as long as the same retention keeps lmgw's record of it. A client key reads only the responses it made, an owner key every one; another key's response is a 404 like an unknown id. 404 otherwise.

Parameters

NameInDescription
idrequiredpath string

Also takes x-lmgw-run (see lmgw headers).

Responses

StatusDescription
200 OK.
application/json Response
Fields of Response
access_programs null Always null; present because OpenAI's schema requires the field.
created_atrequired integer
errorrequired object | null
idrequired string
incomplete_detailsrequired object | null
reasonrequired string
modelrequired string
objectrequired string One of response.
outputrequired array of object Items are loosely typed here. An output_text part of a message item carries logprobs: []: lmgw relays no log probabilities yet; OpenAI's schema requires the field.
statusrequired string One of queued, in_progress, completed, incomplete, failed, cancelled.
store boolean Whether lmgw stored this response, so a later request can continue from it with previous_response_id. Sent by lmgw's own translation; a verbatim upstream body may leave it out.
usage object | null
input_tokensrequired integer
input_tokens_detailsrequired object Tokens read from and written to the prompt cache, both part of input_tokens; 0 when the upstream reported none (cache_write_tokens is lmgw's own addition and absent from a verbatim upstream body).
cache_write_tokens integer
cached_tokensrequired integer
output_tokensrequired integer
output_tokens_detailsrequired object
reasoning_tokensrequired integer
total_tokensrequired integer
default Error.
application/json OpenAiError
get/v1/responses/{id}/input_items

List a response's input items

Capability inference, open to: agent, device, key, owner

This turn's input array as it was sent, for a stored response; for a native one, the upstream's answer with the query string forwarded. Read as GET is.

Parameters

NameInDescription
idrequiredpath string

Also takes x-lmgw-run (see lmgw headers).

Responses

StatusDescription
200 OK.
application/json ResponseInputItems
Fields of ResponseInputItems
datarequired array of object
objectrequired string One of list.
default Error.
application/json OpenAiError

Anthropic-compatible

post/v1/messages

Create a message

Capability inference, open to: agent, device, key, owner

The Anthropic Messages API. A server tool (no input_schema) is refused with 400. A content block lmgw does not model (redacted_thinking, the provider's own tool blocks, a type newer than lmgw) goes between client and an Anthropic upstream as written, whole and streamed, where it stood; any other upstream is sent none of it (x-lmgw-params-ignored: content.<type>), and a Chat Completions or Responses client is given none (a whole answer's x-lmgw-params-ignored: answer.<type>). Thinking blocks keep their signature. A block without a type is refused with 400. A missing max_tokens is filled in rather than refused (x-lmgw-max-tokens-defaulted). anthropic-beta reaches an Anthropic upstream as one header, merged with the upstream row's own; other protocols have no equivalent and are sent none. context_management and the top-level compaction go to an Anthropic upstream as written and its answer's context_management comes back; any other upstream is sent neither, and x-lmgw-params-ignored names them. A compaction block (in the answer, streamed, or sent back in messages) goes between client and an Anthropic upstream as Anthropic wrote it, with stop_reason compaction and usage.iterations; any other upstream is sent the summary as text where the block stood and nothing before it, as Anthropic itself drops that history. thinking: {type: between_tools} and thinking.display go to an Anthropic upstream as written; elsewhere the off is that provider's own (x-lmgw-reasoning-ignored: between_tools) and display is named in x-lmgw-params-ignored. An unknown thinking type is refused with 400.

Parameters

NameInDescription
anthropic-versionheader string The Anthropic SDK's protocol version header. lmgw does not validate its value or vary its behaviour on it; egress to a real Anthropic upstream sends its own.

Also takes x-lmgw-reasoning, x-lmgw-reasoning-effort, x-lmgw-reasoning-budget, x-lmgw-background, x-lmgw-run (see lmgw headers).

Request body required

application/json: AnthropicMessagesRequest

Fields of AnthropicMessagesRequest
compaction object Anthropic's on-demand compaction ({type: summarize}; send its beta flag in anthropic-beta). To an Anthropic model it goes as written, and the compaction block Anthropic answers with comes back as it wrote it (stop_reason compaction). Every other model's provider has no equivalent: it is left out and named in x-lmgw-params-ignored. A model's capabilities.context_editing.compaction says which types it takes.
context_management object Anthropic's context management ({edits: [...]}; send its beta flag in anthropic-beta). To an Anthropic model it goes as written, and Anthropic answers for it; a compaction edit (compact_…) included, whose compaction block comes back as Anthropic wrote it. Every other model's provider has no equivalent: it is left out and named in x-lmgw-params-ignored. A model's capabilities.context_editing on GET /v1/models says what it takes.
max_tokens integer
messagesrequired array of object
contentrequired any A string, or an array of blocks: {type:text,text}, {type:image,source:{type:base64,media_type,data} | {type:url,url}}, {type:tool_use,id,name,input} (the id as lmgw gave it: a Gemini model's carries its thought signature and runs to hundreds of characters; echo it exactly, and do not send it to another provider directly), {type:tool_result,tool_use_id,content,is_error}, {type:thinking,thinking,signature} (replayed; unsigned when lmgw itself produced it). Every other block type (redacted_thinking, the provider's own tool blocks, a type newer than lmgw) goes to an Anthropic upstream as written; any other upstream is sent none of it, and x-lmgw-params-ignored names it as content.<type>. A block without a type is refused with 400. A custom tool without input_schema (a server tool) is refused with 400.
rolerequired string One of user, assistant.
modelrequired string
output_config object lmgw reads output_config.effort as the same reasoning tier x-lmgw-reasoning-effort sets, and output_config.format ({type:json_schema, schema}; the deprecated top-level output_format too) as the structured output every upstream gets in its own spelling. Its refusals are 400 invalid_request_error with the upstream's message. To an OpenAI model the schema goes with strict: true (this format guarantees the schema), so OpenAI's strict-mode rules apply — every property in required, additionalProperties false — and a schema that breaks them comes back as OpenAI's invalid_json_schema refusal, its message kept.
effort string
format object
stop_sequences array of string
stream boolean Default false.
system any A string, or an array of {type:text,text} blocks, joined with blank lines.
temperature number
thinking object {type:enabled,budget_tokens} | {type:disabled} | {type:adaptive} (enabled, no budget — "think as much as judged necessary") | {type:between_tools} (no up-front thinking: an off that goes to an Anthropic model as written; every other model gets its own off, and x-lmgw-reasoning-ignored names between_tools). Any other type is refused with 400. display goes to an Anthropic model inside adaptive and enabled; beside an off, and to every other model, it is left out and x-lmgw-params-ignored names thinking.display.
tool_choice any {type:auto|any|none|tool} (tool also carries name).
tools array of object Custom tools only (input_schema required); a server tool (web_search, computer use, …) is refused with 400.
description string
input_schemarequired object
namerequired string
top_k integer
top_p number
Example
{
  "max_tokens": 256,
  "messages": [
    {
      "content": "Say hello in one short sentence.",
      "role": "user"
    }
  ],
  "model": "<pick a model>"
}

Responses

StatusDescription
200 OK.
application/json AnthropicMessage
Fields of AnthropicMessage
contentrequired array of object
context_management object The context management an Anthropic model applied ({applied_edits: [...]}), as Anthropic reported it; a stream carries it on its closing message_delta. Absent from every other model's answer.
idrequired string
modelrequired string
rolerequired string One of assistant.
stop_reasonrequired string | null
stop_sequencerequired null
typerequired string One of message.
usagerequired object
cache_creation_input_tokens integer Present only when the upstream reported cache writes.
cache_read_input_tokens integer Present only when the upstream reported a cache read.
input_tokensrequired integer
iterations array of object An Anthropic model's per-iteration usage, as it reported it (a compaction entry for a compaction it ran, which the top-level counts leave out). Present only when the upstream reported it.
output_tokensrequired integer
text/event-stream string
1 event types

message


Headers: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason, x-lmgw-images-omitted, x-lmgw-max-tokens-clamped, x-lmgw-max-tokens-defaulted, x-lmgw-max-tokens-raised, x-lmgw-params-ignored, x-lmgw-params-refused, x-lmgw-reasoning-ignored, x-lmgw-rung
default Error.
application/json AnthropicError
post/v1/messages/count_tokens

Count tokens for a message

Capability inference, open to: agent, device, key, owner

The Anthropic SDKs' messages.count_tokens(): on an Anthropic-protocol upstream, the client body is sent through verbatim (only model replaced, and a Gemini thought signature in a tool id dropped), with its anthropic-beta flags, so server tools and new fields count exactly; Anthropic's context_management answer (original_input_tokens) comes back beside input_tokens. x-lmgw-count-approximate explains any other route's approximation. Enforces the key's alias scope like every other counter (a refusal is a logged 403 key_scope, a success is not logged); no budget applies, the key's or the gateway's, since a count costs nothing.

Parameters

NameInDescription
anthropic-versionheader string The Anthropic SDK's protocol version header. lmgw does not validate its value or vary its behaviour on it; egress to a real Anthropic upstream sends its own.

Also takes x-lmgw-reasoning, x-lmgw-reasoning-effort, x-lmgw-reasoning-budget, x-lmgw-background, x-lmgw-run (see lmgw headers).

Request body required

application/json: AnthropicCountTokensRequest

Fields of AnthropicCountTokensRequest
messagesrequired array of object
contentrequired any A string, or an array of blocks: {type:text,text}, {type:image,source:{type:base64,media_type,data} | {type:url,url}}, {type:tool_use,id,name,input} (the id as lmgw gave it: a Gemini model's carries its thought signature and runs to hundreds of characters; echo it exactly, and do not send it to another provider directly), {type:tool_result,tool_use_id,content,is_error}, {type:thinking,thinking,signature} (replayed; unsigned when lmgw itself produced it). Every other block type (redacted_thinking, the provider's own tool blocks, a type newer than lmgw) goes to an Anthropic upstream as written; any other upstream is sent none of it, and x-lmgw-params-ignored names it as content.<type>. A block without a type is refused with 400. A custom tool without input_schema (a server tool) is refused with 400.
rolerequired string One of user, assistant.
modelrequired string
output_config object
system any A string, or an array of {type:text,text} blocks.
thinking object
tool_choice any {type:auto|any|none|tool}.
tools array of object
description string
input_schemarequired object
namerequired string
Example
{
  "messages": [
    {
      "content": "Say hello in one short sentence.",
      "role": "user"
    }
  ],
  "model": "<pick a model>"
}

Responses

StatusDescription
200 OK.
application/json AnthropicCountTokensResponse
Fields of AnthropicCountTokensResponse
context_management object Anthropic's own count of the input before the request's context edits ({original_input_tokens}), as it reported it. Only on an Anthropic model's count of a request with context_management.
input_tokensrequired integer

Headers: x-lmgw-candidate, x-lmgw-count-approximate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
default Error.
application/json AnthropicError

Headers: x-lmgw-candidate, x-lmgw-count-approximate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason

llama.cpp-compatible

post/tokenize

Tokenize text

Capability inference, open to: agent, device, key, owner

llama.cpp's own /tokenize, for llama.cpp clients: the client object is forwarded to the backend's own /tokenize with model rewritten, and the answer — token ids, or {id,piece} with with_pieces — comes back verbatim, the backend's own errors included (but an upstream 401/403 is a 502: that is lmgw's credential). The body is read as JSON whatever its Content-Type, as llama-server reads it. 501 not_supported_error on any backend that is not a real llama-server: an id from a tokenizer the backend does not run would be a hidden approximation. Enforces the key's alias scope (a logged 403 key_scope); no budget applies. Errors are llama.cpp-shaped, except the shared /v1 layers' own: the gate's 401, 403 and 429, and the 413 for a declared Content-Length over max_body_mb, which are OpenAI-shaped.

Also takes x-lmgw-background, x-lmgw-run (see lmgw headers).

Request body required

application/json: TokenizeRequest

Fields of TokenizeRequest
add_special boolean Default false.
content any A string, or a mixed array of strings and token ids.
modelrequired string Required: llama-server's router mode has no other way to pick a backend. A missing model is a 400 naming GET /v1/models.
parse_special boolean Default true.
with_pieces boolean Default false.
Example
{
  "content": "Hello, world!",
  "model": "<pick a model>"
}

Responses

StatusDescription
200 OK.
application/json TokenizeResponse
Fields of TokenizeResponse
tokensrequired any An array of integer token ids, or — with_pieces — an array of {id, piece} (piece a string, or a byte array when it is not valid UTF-8).

Headers: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
default Error.
application/json LlamaCppError

Headers: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
post/v1/systemone

Ask a decision model

Capability inference, open to: agent, device, key, owner

TypeSafe's System One API as llama.cpp serves it: a state and a map of typed questions (choice, score, noul), answered with calibrated probabilities and no generated text. The client object is forwarded with only model rewritten, members in the order sent (a choice question's criteria order is its option order), and the answer comes back verbatim, its model included: the id that answered upstream, not the name asked for (x-lmgw-fallback names a fallback alias). The body is read as JSON whatever its Content-Type. Routes to a local decision model (an aux row of kind decision) or to an openai_compatible or llama_cpp upstream whose catalog does not rule the model out; any other model is 501 not_supported_error before a container starts. A local row whose image predates the route is a 501 too, once its container is up and answers the route 404. The upstream's own errors are relayed as sent (llama.cpp's 500 for a prompt over the ubatch included), except a 401/403, which is lmgw's credential and a 502. The key's alias scope and budgets apply; the row is priced from lmgw's own price rows, input tokens and, where the price row charges them, output tokens (Jev's does not). Errors lmgw answers itself are llama.cpp-shaped, except the shared /v1 layers' own: the gate's 401, 403 and 429, and the 413 for a declared Content-Length over max_body_mb, which are OpenAI-shaped.

Also takes x-lmgw-background, x-lmgw-run (see lmgw headers).

Request body required

application/json: object

files array | null llama.cpp's extension: files as data URLs (images is its alias).
images array | null llama.cpp's extension: images as data URLs, for a model started with a
projector and a type that reads images (501 otherwise). An alias of
files. TypeSafe takes text only.
modelrequired string Required: lmgw routes by it, as TypeSafe requires it and llama-server's
router mode needs it. Rewritten to the route's upstream model on the
way out; nothing else is.
questionsrequired object The questions, keyed by ids the caller picks; the answers come back
under the same keys.
staterequired any What the questions are about: a string, or an object or array (a chat
log, a record), which llama.cpp gives the model as JSON text. null
only for the types that take none (LiquidAI's d1 models); llama.cpp
refuses it on the others.
Example
{
  "model": "<pick a model>",
  "questions": {
    "department": {
      "criteria": {
        "billing": "payments, invoices, refunds, plan charges",
        "sales": "new purchases, upgrades, quotes",
        "technical": "bugs, outages, errors in the product",
        "unsure": null
      },
      "instructions": "Which team should handle this ticket?",
      "type": "choice"
    },
    "mood": {
      "instructions": "The customer is upset.",
      "type": "noul"
    },
    "urgency": {
      "criteria": [
        "not urgent",
        "normal",
        "urgent",
        "critical"
      ],
      "instructions": "How urgent is this ticket?",
      "type": "score"
    }
  },
  "state": "Hi, my invoice from last month charged me twice for the Pro plan. Can you refund one of the charges?"
}

Responses

StatusDescription
200 OK.
application/json SystemOneResponse
Fields of SystemOneResponse
answersrequired object One answer per question, under the question's key.
id string | null OpenRouter's extension: the generation's id.
modelrequired string
provider string | null OpenRouter's extension: the provider that answered.
usagerequired SystemOneUsage

Headers: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
default Error.
application/json LlamaCppError

Headers: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason

lmgw extensions

post/v1/count_tokens

Count tokens (universal)

Capability inference, open to: agent, device, key, owner

lmgw's own universal token counter: routed by model exactly like the chat endpoints, so counting on a cold local model starts its container. x-lmgw-count-approximate explains tokenizer_guess (an OpenAI-protocol upstream tiktoken cannot identify) and message_framing (an Anthropic/Gemini upstream counts messages, so the text went as one user turn).

Also takes x-lmgw-background, x-lmgw-run (see lmgw headers).

Request body required

application/json: CountTokensRequest

Fields of CountTokensRequest
inputrequired string
modelrequired string
Example
{
  "input": "How many tokens is this?",
  "model": "<pick a model>"
}

Responses

StatusDescription
200 OK.
application/json CountTokensResponse
Fields of CountTokensResponse
modelrequired string
tokensrequired integer

Headers: x-lmgw-candidate, x-lmgw-count-approximate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
default Error.
application/json OpenAiError

Headers: x-lmgw-candidate, x-lmgw-count-approximate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
get/v1/openapi.json

Get the inference-plane OpenAPI description

Capability inference, open to: agent, device, key, owner

This description, filtered to the inference plane.

Also takes x-lmgw-run (see lmgw headers).

Responses

StatusDescription
200 OK.
application/json object
default Error.
application/json OpenAiError
post/v1/rerank

Rerank documents

Capability inference, open to: agent, device, key, owner

Jina and TEI request shapes both work (documents or texts); an embedding-only row is refused. Answers Jina's results shape either way.

Also takes x-lmgw-background, x-lmgw-run (see lmgw headers).

Request body required

application/json: RerankRequest

Fields of RerankRequest
documents array of string Jina's spelling.
modelrequired string
queryrequired string
texts array of string TEI's spelling — either works; an embedding-only row is refused.
top_n integer
Example
{
  "documents": [
    "An LLM gateway.",
    "A city in France."
  ],
  "model": "<pick a model>",
  "query": "What is lmgw?"
}

Responses

StatusDescription
200 OK.
application/json RerankResponse
Fields of RerankResponse
modelrequired string The model as the request named it.
objectrequired string One of list.
resultsrequired array of object
indexrequired integer The document's position in the request.
relevance_scorerequired number
usagerequired object
prompt_tokensrequired integer What the model reported; 0 when it reported nothing.
total_tokensrequired integer The same number: reranking generates nothing.

Headers: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
default Error.
application/json OpenAiError

Headers: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
post/v1/tasks/run

Run a generic task

Capability inference, open to: agent, device, key, owner

audio.cpp's own generic task route; request is relayed to the backend untouched, but for its text on a local model whose engine refuses a character its package lacks (Supertonic): that is fitted as speech's input is (x-lmgw-speech says how), and a text left with nothing to say is 400 empty_input.

Also takes x-lmgw-background, x-lmgw-run (see lmgw headers).

Request body required

application/json: TaskRequest

Fields of TaskRequest
modelrequired string
requestrequired object Relayed to audio.cpp's generic task endpoint untouched; its shape is the task's own and is not modeled here.

Responses

StatusDescription
200 OK.
application/json object

Headers: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason, x-lmgw-speech
default Error.
application/json OpenAiError

Headers: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason, x-lmgw-speech
post/v1/tasks/stream

Run a generic task (streaming)

Capability inference, open to: agent, device, key, owner

The streaming-mode sibling of /v1/tasks/run.

Also takes x-lmgw-background, x-lmgw-run (see lmgw headers).

Request body required

application/json: TaskRequest

Fields of TaskRequest
modelrequired string
requestrequired object Relayed to audio.cpp's generic task endpoint untouched; its shape is the task's own and is not modeled here.

Responses

StatusDescription
200 OK.
application/json object

Headers: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason, x-lmgw-speech
default Error.
application/json OpenAiError

Headers: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason, x-lmgw-speech

MCP

delete/mcp

End an MCP session

Capability inference, open to: agent, device, key, owner. Changes state.

Ends a session.

Parameters

NameInDescription
Acceptheader string MCP Streamable HTTP requires the client accept both JSON and server-sent events.

Also takes x-lmgw-run (see lmgw headers).

Responses

StatusDescription
204 No content.
default Error.
application/json JsonRpcError
get/mcp

Open the MCP notification stream

Capability inference, open to: agent, device, key, owner

Opens the server→client notification stream for a valid session (a session-less GET is 400/404): pushes notifications/tools/list_changed and notifications/resources/list_changed when the aggregate's composition changes, and notifications/resources/list_changed when a server says its resources changed. The stream ends, without a frame (MCP has no notification for it), when the API key that opened it is disabled, rotated, deleted or expires.

Parameters

NameInDescription
Acceptheader string MCP Streamable HTTP requires the client accept both JSON and server-sent events.

Also takes x-lmgw-run (see lmgw headers).

Responses

StatusDescription
200 An event stream.
text/event-stream string
1 event types

notification

default Error.
application/json JsonRpcError
post/mcp

Call the aggregate MCP endpoint

Capability inference, open to: agent, device, key, owner. Changes state.

MCP Streamable HTTP: single JSON-RPC request/notification/response per POST, no batching. initialize negotiates MCP-Protocol-Version and assigns Mcp-Session-Id, which every later request on the session must carry; a notification answers 202 with no body. tools/list and tools/call reach the registered southbound MCP servers' tools, namespaced <prefix>__. resources/list, resources/templates/list (one page; a cursor is -32602) and resources/read pass their resources through, a prefixed server's URIs namespaced before the authority (ui://weather/card from prefix p is ui://p__weather/card) — in tools' _meta.ui.resourceUri and in tool results' resource links too; a read of a URI no server has, or of a server the caller's tool scope does not reach, is -32002. initialize advertises resources {listChanged} and the MCP Apps extension io.modelcontextprotocol/ui (mimeTypes [text/html;profile=mcp-app]); every tool is listed with its _meta, and app-only ones (_meta.ui.visibility without "model") only to a session whose initialize declared that extension. Every tool of a registered server also carries _meta["lmgw/server"] {label, name, tool}: the server's label (its tool prefix, else its name), its name, and the tool's name as the server lists it — so a host routes a view's call of its server's tool to the listed name, also one a name collision moved to <server name>__<tool> or the owner renamed; lmgw sets it, replacing anything the server put there.

Parameters

NameInDescription
Acceptheader string MCP Streamable HTTP requires the client accept both JSON and server-sent events.

Also takes x-lmgw-run (see lmgw headers).

Request body required

application/json: JsonRpcRequest

Fields of JsonRpcRequest
id any Absent on a notification (e.g. notifications/initialized); string or number otherwise.
jsonrpcrequired string One of 2.0.
methodrequired string e.g. initialize, ping, tools/list, tools/call, resources/list, resources/templates/list, resources/read, notifications/initialized.
params object
Example
{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "initialize",
  "params": {
    "capabilities": {},
    "clientInfo": {
      "name": "example-client",
      "version": "0.1.0"
    },
    "protocolVersion": "2025-11-25"
  }
}

Responses

StatusDescription
200 OK.
application/json JsonRpcResponse
Fields of JsonRpcResponse
idrequired any
jsonrpcrequired string One of 2.0.
resultrequired object
default Error.
application/json JsonRpcError
delete/mcp/admin

End a self-admin MCP session

Capability inference, open to: agent, device, key, owner. Changes state.

As DELETE /mcp, on the self-admin plane's own session.

Parameters

NameInDescription
Acceptheader string MCP Streamable HTTP requires the client accept both JSON and server-sent events.

Also takes x-lmgw-run (see lmgw headers).

Responses

StatusDescription
204 No content.
default Error.
application/json JsonRpcError
get/mcp/admin

Open the self-admin MCP notification stream

Capability inference, open to: agent, device, key, owner

As GET /mcp, on the self-admin plane's own session.

Parameters

NameInDescription
Acceptheader string MCP Streamable HTTP requires the client accept both JSON and server-sent events.

Also takes x-lmgw-run (see lmgw headers).

Responses

StatusDescription
200 An event stream.
text/event-stream string
1 event types

notification

default Error.
application/json JsonRpcError
post/mcp/admin

Call the self-admin MCP endpoint

Capability admin, open to: owner. Changes state.

The self-admin plane: the built-in lmgw__* tools and nothing else, a much narrower grant than /mcp, gated on an owner credential rather than any gateway key. Also accepts the x-lmgw-admin-token header as a third bearer spelling (adminToken security scheme), which is how MCP client configs that dial this plane authenticate.

Parameters

NameInDescription
Acceptheader string MCP Streamable HTTP requires the client accept both JSON and server-sent events.

Request body required

application/json: JsonRpcRequest

Fields of JsonRpcRequest
id any Absent on a notification (e.g. notifications/initialized); string or number otherwise.
jsonrpcrequired string One of 2.0.
methodrequired string e.g. initialize, ping, tools/list, tools/call, resources/list, resources/templates/list, resources/read, notifications/initialized.
params object
Example
{
  "id": 2,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "lmgw__status"
  }
}

Responses

StatusDescription
200 OK.
application/json JsonRpcResponse
Fields of JsonRpcResponse
idrequired any
jsonrpcrequired string One of 2.0.
resultrequired object
default Error.
application/json JsonRpcError
get/mcp/host

Host a device's MCP tools

Capability chat, open to: device, owner

A paired device offers its own MCP server over this WebSocket, and lmgw lists its tools under the device's hosting label (<label>__<tool>) while the link is open, as it lists a registered server's. Needs a device key with a hosting grant (403 host_not_granted otherwise) and no Origin header (403 cross_origin_refused: a browser page never hosts tools). Every tools/call lmgw forwards carries _meta with lmgw/caller ({kind: owner | gateway | device | key | agent, name}: who the call runs as), lmgw/approval (null, or {decision: approved, by}) and lmgw/timeout_ms (the row's timeout_ms, when lmgw stops waiting). lmgw sends notifications/cancelled {requestId, reason} for every call it stops waiting on: at the timeout, when its caller stops waiting, and before it closes the link. Tasks (MCP 2025-11-25): a tool whose execution.taskSupport is required, on a device that declares capabilities.tasks.requests.tools.call, is called with task: {} and _meta lmgw/task ({delivery: thread | wait, thread_id}); lmgw/timeout_ms then bounds the wait for the CreateTaskResult only. lmgw follows the task with tasks/get at its pollInterval (else mcp.task_poll_interval_s), acts on notifications/tasks/status, fetches tasks/result, and sends tasks/cancel (never notifications/cancelled) for a task; a link drop ends no task, and -32602 for its id ends it abandoned. A device's notifications/tools/list_changed makes lmgw list again. Sampling requests are refused -32601. Pings every mcp.host_ping_interval_s seconds; a missed pong closes 1011 naming the setting. A frame or message over mcp.host_max_frame_mb / mcp.host_max_message_mb closes 1009 naming the setting; a binary frame, a batch or text that is no JSON-RPC message closes 1002. A second link of the same device takes over: the older one closes 4000 ("another connection of device '<name>' took over"). The key's revocation closes 4003 with the realtime session's token and sentence (device_disabled, key_expired, key_unknown); the hosting grant cleared or the row switched off closes 1000; a stopping gateway closes 1001. Who may call the hosted tools: the owner, the gateway's own runs, the device itself, keys and devices whose policy's device_tools grants the label (their tool scope then filtering its tools as any server's), and agents whose manifest names it — never an anonymous caller, and never a key through its tool scope alone.

Responses

StatusDescription
101 Switching Protocols: the connection is now a WebSocket. Each frame is one JSON-RPC 2.0 message as text, no batches. The roles are reversed at the message level: lmgw is the MCP client and the device the server. lmgw sends initialize, the device answers, lmgw sends notifications/initialized and pages through tools/list.
426 Upgrade Required: the request carried no WebSocket upgrade headers.
application/json ApiError
default Error, before the upgrade.
application/json ApiError
get/v1/mcp/servers

List the MCP labels

Capability inference, open to: agent, device, key, owner

The labels this caller may put into a {"type": "mcp", "server_label"} tool on /v1/realtime or /v1/responses, for a tool picker. Connects nothing: read from the configuration under the caller's tool scope — enabled servers only, and the lmgw self-admin toolset only for an owner credential or a device allowed lmgw's admin tools, while the self-admin tools are on.

Also takes x-lmgw-run (see lmgw headers).

Responses

StatusDescription
200 OK.
application/json McpServerList
Fields of McpServerList
datarequired array of object
descriptionrequired string A toolset's purpose; "" for a server.
kindrequired string builtin: lmgw's own toolsets (lmgw, for owner credentials only; docs; kb); server: a registered MCP server; agent: a service agent's tools. One of builtin, server, agent.
namerequired string A server's configured name; a toolset's label.
objectrequired string One of mcp.server.
server_labelrequired string What goes into a {"type": "mcp", "server_label"} tool on /v1/realtime or /v1/responses: a built-in toolset's label, a registered server's tool prefix, else its name.
objectrequired string One of list.
default Error.
application/json OpenAiError
get/v1/mcp/servers/{label}

List one MCP label's tools

Capability inference, open to: agent, device, key, owner

One label's tools, exactly as a /v1/realtime session's mcp_list_tools item lists them (the server's own tool names, description always a string), under the caller's tool scope and the per-tool switches. Connects that one server if it is not up (up to the lazy-list budget). 404 for a label this caller may not use, naming the available ones; 502 when the server cannot be listed.

Parameters

NameInDescription
labelrequiredpath string

Also takes x-lmgw-run (see lmgw headers).

Responses

StatusDescription
200 OK.
application/json McpServerDetail
Fields of McpServerDetail
descriptionrequired string A toolset's purpose; "" for a server.
kindrequired string builtin: lmgw's own toolsets (lmgw, for owner credentials only; docs; kb); server: a registered MCP server; agent: a service agent's tools. One of builtin, server, agent.
namerequired string A server's configured name; a toolset's label.
objectrequired string One of mcp.server.
server_labelrequired string What goes into a {"type": "mcp", "server_label"} tool on /v1/realtime or /v1/responses: a built-in toolset's label, a registered server's tool prefix, else its name.
toolsrequired array of object
descriptionrequired string "" when the server gave none.
input_schemarequired object
namerequired string The server's own name for the tool: its exposed name minus the <prefix>__ namespace.
default Error.
application/json OpenAiError

Gateway

API description

get/api/connect

Get connection info

Capability admin, open to: owner

Every reachable base URL, whether a key is required, the models a client can already see, and the expose-all upstream prefixes — the connect panel a fresh client reads to configure itself.

Responses

StatusDescription
200 OK.
application/json ConnectInfo
Fields of ConnectInfo
auth_enabledrequired boolean
basesrequired array of BaseUrl Every URL that reaches the gateway (wildcard binds expand to
loopback + LAN addresses).
catalog_prefixesrequired array of string Prefixes of enabled expose_all upstreams whose catalogs pass
through dynamically (rendered as ghost entries, not copyable names).
device_portrequired integer | null The device listener's port (devices.port, else the HTTP port plus
one): what "this computer" pairs on, https://127.0.0.1:<port>.
null when none can be derived (device link design §3.1).
device_urlsrequired array of DeviceUrl The URLs the pairing form proposes for another device (device link
design §3.1, §3.2): the addresses a device can count on, the stable
LAN and WireGuard ones first, each with its interface. Empty when
the machine has none, or no port can be derived.
modelsrequired array of ConnectModel Statically known client-facing model names.
default Error.
application/json ApiError
get/api/openapi.json

Get the full OpenAPI description

Capability admin, open to: owner

This description, generated rather than hand-maintained.

Responses

StatusDescription
200 OK.
application/json object
default Error.
application/json ApiError
get/api/version

Get the gateway version

Capability public, open to: agent, anonymous, device, key, owner

The one /api read a page may do before it has a session: the dashboard's footer and its login view print this.

Responses

StatusDescription
200 OK.
application/json VersionInfo
Fields of VersionInfo
versionrequired string
default Error.
application/json ApiError

Dashboard API

Session

delete/api/session

Sign out

Capability public, open to: agent, anonymous, device, key, owner. Changes state.

Clears the session cookie. Same-origin only; never refused, whatever the session resolves to. The key itself is untouched.

Responses

StatusDescription
204 No content.
default Error.
application/json ApiError
get/api/session

Read the current session

Capability public, open to: agent, anonymous, device, key, owner

The current principal, as the dashboard's load check reads it. Never a 401, whatever credential (or none) the request carried: it answers the question "am I logged in", and a refusal would make the answer indistinguishable from a gateway that is down.

Responses

StatusDescription
200 OK.
application/json SessionView
Fields of SessionView
authenticatedrequired boolean
kindrequired string key, agent, owner or device (a paired device) — empty when
nobody is signed in. Present and empty rather than absent, so the
response has one shape.
namerequired string The name of the API key in use (owner:dashboard for the dashboard's
own), empty when nobody is signed in.
default Error.
application/json ApiError
post/api/session

Sign in

Capability public, open to: agent, anonymous, device, key, owner. Changes state.

The paste fallback, and how the dashboard re-logs itself after rotating owner:dashboard. A token that matches no enabled owner row is 401 login_invalid, not session_required. Same-origin only.

Request body required

application/json: object

tokenrequired string

Responses

StatusDescription
204 No content.
default Error.
application/json ApiError
get/api/session/login

Log in via a link

Capability public, open to: agent, anonymous, device, key, owner

The desktop app's window opens here with ?nonce=; a browser opens it with ?token= (the owner key, in the "dashboard login" link lmgw logs at startup). Either match sets the session cookie and redirects to /; anything else redirects to /?login=invalid with no cookie. Same-origin only.

Parameters

NameInDescription
noncequery string | null
tokenquery string | null

Responses

StatusDescription
302 Redirect.
default Error.
application/json ApiError

Status & live feed

get/api/events

Open the live event stream

Capability admin, open to: owner

The live feed the dashboard opens once and keeps: stats, jobs, runtime, vram, mcp, updates and chat frames on connect (and machine, once the machine check has a result), then request/stats/mcp/jobs/vram/runtime/updates frames as they change, a machine frame with the machine check's summary whenever its last result changes (a run, the settings judged again, a local model's start on the graphics card that failed because of the computer), a keys frame when a key's state moves without a request (a device's connection opened or closed, a key disabled, rotated or deleted), and a chat frame naming the threads, folders and messages any writer changed in the Chat (a device, an owner key, this or another dashboard window, the sweep): read them again. The first change of a burst waits a fixed 200 ms for the rest, then one read names everything changed up to it, so a stream sends at most one chat frame per 200 ms plus that read (but for one its keep-alive read finds). The chat frame on connect is a resync: read everything shown again, since frames are not replayed across a reconnect. Never closes on its own.

Responses

StatusDescription
200 An event stream.
text/event-stream string
10 event types

chat ChatChanged
Something in the Chat changed: the chat frame of /api/events. The
frame names what changed and the dashboard reads it again; it carries no
rendering of its own.

It covers every writer: the dashboard (this window or another), a paired
device, an owner key, the self-admin tools and the gateway's own sweep.
/api/events is the owner's, so every thread is named, Admin Chat
included. Temporary chats are never named: they live in the memory of
the gateway, outside the change feed.

- **On connect** the stream sends one with resync: true: what a client
read before it connected may be stale, so it reads everything it shows
again. A reconnect is a connect, so frames missed while the stream was
down are covered by that one.
- **Bursts are coalesced**: the first change of a burst waits a fixed
200 ms (not a setting) for the rest, then the stream reads what changed
once and sends one frame naming everything changed up to that read. A
frame therefore comes 200 ms plus one read of the change feed after the
first change it names, and a stream sends at most one frame per 200 ms,
except one its keep-alive read finds (chat_feed_keepalive_s, a write
that did not wake the feed). An id is named once however often it
changed in a frame. A client that reads frames more slowly than they
come may merge them (merge): a frame is a delta, never a
state.

foldersrequired array of integer (int64) The folders created, changed (name, defaults, ongoing, retention) or
deleted, and those whose current thread moved, ascending.
messagesrequired array of integer (int64) The threads whose messages changed, ascending: a message added (a
user turn, typed or spoken, as it is stored; a reply as it is saved),
edited, continued, cut to what was heard, or deleted. A reply still
being generated is not named until it is saved.
resyncrequired boolean What changed is not known: read everything shown again. Sent on
connect, and when the stream could not tell what changed.
threadsrequired array of integer (int64) The threads whose row changed, ascending: created (a rollover's new
current thread too), renamed, settings, pinned, archived or
restored, moved between folders, hidden from devices, or deleted.

jobs Array_of_JobRow

keys KeysChanged
A key's state moved without a request landing: the keys frame of
/api/events. A device's connection opened or closed — its online state
and last_seen_at — or a key was disabled, rotated or deleted. The Keys
page refetches its list on it, instead of polling.

key_idrequired integer (int64) The api_keys.id it is about.
whatrequired string link (a device's connection opened or closed), disabled,
rotated or deleted; a device's pairing (device link design §9.3):
token (a pairing token minted or ended), enrolled (a device sent
its key: the row's code and peer address are in its pairing),
confirmed, contested (a used token came back with another key);
or resync (with key_id 0) when the event stream could not deliver
every frame: refetch the keys. transfer (device transfers design
§11.1, key_id the sender's) is no change of a key: a transfer's
state moved, or an upload wrote (at most once a second) — refetch the
transfers, not the keys.

machine MachineSummary
The verdict alone, in GET /api/status and the machine frame of
/api/events.

checked_atrequired string
failed_startrequired MachineFailedStart | null MachineCheck::failed_start.
headlinerequired string
verdictrequired MachineVerdict

mcp Array_of_McpStatus

request RequestRow
One request's summary — the request SSE frame and the
row shape of GET /api/logs (log rows additionally carry mcp_tool and
pricing).

audio_in_msrequired integer | null What the request processed besides tokens, each only when it was
measured or the provider reported it: input audio in milliseconds,
input characters as sent, generated images. None = not measured,
which is not the same as zero — render a dash.
cache_write_tokensrequired integer | null
cached_in_tokensrequired integer | null The cache subsets of prompt_tokens, when the provider reported them —
without these a row that cost 8x its neighbour looks identical to it.
None = the provider said nothing, which is not the same as zero.
chars_inrequired integer | null
classrequired string chat | aux | audio | tool.
client_keyrequired string | null Name of the gateway API key that made the call (never the key itself);
absent when auth is disabled or the call was made in-process.
completion_tokensrequired integer | null
cost_microrequired integer | null Currency micro-units. None = **unpriced**, which is not the same as
free — render a dash, never a 0.
degradedrequired string | null What the request's content lost on its way to a model that lacks a
capability: "fallback 'x' lacks vision: 3 images sent as
placeholders", "'m' lacks audio: transcript sent", several joined by
"; ". None = nothing was degraded.
egress_protorequired string | null
error_kindrequired string | null
error_msgrequired string | null
fallback_reasonrequired string | null Why a fallback answered instead of the requested local model: hold
(the GPU hold), external_vram (VRAM outside lmgw's control was
short), background (a background candidate alias), unavailable
(a candidate alias with no model it may use), benchmark, quota,
unreachable, disabled, gpu_setup (the graphics card is not
ready on this computer) or engine_download (a local model's engine
could not be downloaded). None = no fallback; the fallback itself
is upstream_name / upstream_model.
images_outrequired integer | null
ingress_protorequired string
key_idrequired integer | null api_keys.id behind client_key — the id is what a key filter matches
on, and a name match breaks the moment a key is renamed.
log_idrequired integer (int64)
max_tokens_clampedrequired integer | null max_tokens lmgw lowered a client-set value to, on a ladder rung or a
guarded unified-KV pool. None = not clamped — either the row is unguarded, or the
client's value already fit.
mcp_toolrequired string | null MCP tool name for ingress_proto = "mcp" rows; absent on SSE frames.
price_noterequired string | null Why the row's cost is what it is, when that is not plain: "served at
service tier flex; no flex price on file for 'm', a standard one is",
"stream ended before the upstream reported usage". None otherwise.
pricingrequired RowPricing | null How the row was priced: the rates it recorded when it was written,
so each priced part can be shown as quantity × rate even after the
price has changed. On GET /api/logs rows only; absent on SSE
frames, which carry the cost and the quantities alone.
prompt_tokensrequired integer | null **Total** input for the call, cache included.
requested_aliasrequired string
rungrequired integer | null The rung a ladder row answered from — or, for a refusal, the rung it
was judged on — 1-based. None for a row without
a ladder, and for a request its fallback answered.
service_tierrequired string | null The service_tier an OpenAI platform answer reported, verbatim
(default, flex, priority, …): the tier the row is priced at.
None on every other upstream, and when the answer named none.
statusrequired integer (uint16)
streamedrequired boolean
total_msrequired integer | null
tsrequired string
ttfb_msrequired integer | null
upstream_modelrequired string | null
upstream_namerequired string | null

runtime Array_of_RuntimeStatus

stats StatsView
Aggregate request statistics — the stats SSE frame.

active_requestsrequired integer (int64)
completion_tokensrequired integer (uint64)
err_last_minuterequired integer (uint64)
prompt_tokensrequired integer (uint64)
req_last_minuterequired integer (uint64)
tok_srequired number (double) Output tokens per second across every in-flight stream, over a short
trailing window; 0.0 when nothing is streaming. Approximate for
upstreams that pack several tokens into one SSE chunk — show it with a
"~". default so an older gateway's frame still decodes.
total_errorsrequired integer (uint64)
total_requestsrequired integer (uint64)

updates UpdatesSummary
The live updates frame on /api/events: sent when a dashboard
connects, and again whenever a check ends, a run finishes, a build is
saved, promoted or verified, an image is pulled, or a model row starts or
stops running an image — so the Engines badge is current without the
page polling anything.

builds_with_updatesrequired integer (uint32) Builds whose update status has has_update true.
checked_atrequired string | null When the last full check (every build and image) ended; None before
the first one.
images_with_updatesrequired integer (uint32) Registry images a model row runs (its own image, or its class's
default while it has none) whose registry update has
update_available true. A class default no row follows is checked
too, and its update is on the Engines page, but it is not counted
here.

vram VramStatus
GET /api/vram and the vram SSE frame — measured figures and
estimated ones are separate fields on
purpose: the UI must be able to say which is which.

activerequired boolean Whether admission is actually arbitrating; false is explained by
inactive_reason.
benchmarkrequired VramBenchmark | null The benchmark run holding the card, if one does: no local model is admitted until it ends.
capacity_bytesrequired integer (uint64)
devicesrequired array of VramDevice
downloadingrequired array of VramWaiter Starts whose model's engine image is still downloading (machine-check
design §5), oldest first: each phase is downloading with the bytes
so far. They hold no place in queue and nothing on the card; once
its download is done a start is admitted like any other, and enters
queue if it has to wait for room. Absent from an older gateway's
frame.
drainingrequired array of string Resident model ids that are busy or still starting while hold is
active — visible continuously, not only in the one-shot hold_set
response. Empty whenever hold is not active.
enabledrequired boolean
estimated_resident_bytesrequired integer (uint64)
external_trigger_activerequired boolean Whether the outside-VRAM fallback can fire right now.
external_trigger_reasonrequired string | null Why it cannot, when it cannot (the switch, admission, the hold, no
telemetry, an unattributable lmgw model).
free_bytesrequired integer | null
free_measuredrequired boolean False when free_bytes was derived from the estimate rather than read
from the driver.
headroom_bytesrequired integer (uint64)
hold_activerequired boolean The hold.active setting — hold is a switch on
the resolve/start paths, orthogonal to enabled/active above.
inactive_reasonrequired string | null
kept_freerequired VramKeptFree What free_bytes was lowered by on top of the memory in use, by
reason. With a measured free figure, free_bytes is the capacity's
measured free memory — the devices' free memory, or with
vram.budget_mb the budget less the devices' used memory — less
these (never below zero). The devices' total less their used and free
memory is in neither: memory the probe reports as not available
(NVML: the driver's own reserve; an AMD APU: GTT the host's RAM
cannot back).
kv_poolsrequired array of VramKvPool The token ledger of every guarded unified-KV chat model with a request
in flight or waiting — vram::VramView's
kv_pools. Absent from an older gateway's frame, hence the default.
lmgw_share_bytesrequired integer | null lmgw's own share of the pooled devices' used memory, measured per
process. None when it
cannot be measured — see external_trigger_reason.
noterequired string
outside_share_bytesrequired integer | null Used memory that is not lmgw's — games, the desktop, other apps.
None exactly when lmgw_share_bytes is.
queuerequired array of VramWaiter
residentrequired array of VramResident
telemetryrequired string Where the measured numbers come from, verbatim.
telemetry_okrequired boolean
default Error.
application/json ApiError
get/api/jobs

List background jobs

Capability admin, open to: owner

Poll half of the jobs feed; the SSE jobs frame on /api/events is the push half.

Parameters

NameInDescription
activequery boolean | null
kindquery string | null
limitquery integer | null

Responses

StatusDescription
200 OK.
application/json JobsView
Fields of JobsView
jobsrequired array of JobRow
default Error.
application/json ApiError
get/api/logs

List recent requests

Capability admin, open to: owner

A page of the request log, filterable by alias, upstream, key, error kind and class — the same row shape the request SSE frame carries, so the live feed and pagination share one type.

Parameters

NameInDescription
aliasquery string | null
alias_qquery string | null
before_idquery integer | null
classquery string | null
error_kindquery string | null
errors_onlyquery string | null
key_idquery integer | null
limitquery integer | null
upstreamquery string | null
upstream_qquery string | null

Responses

StatusDescription
200 OK.
application/json LogsResponse
Fields of LogsResponse
logsrequired array of RequestRow
default Error.
application/json ApiError
get/api/status

Get gateway status

Capability admin, open to: owner

Gateway health in one call: uptime, live request stats, the per-model container runtime, the GPU ledger, southbound MCP connections, and config-object counts.

Responses

StatusDescription
200 OK.
application/json GatewayStatus
Fields of GatewayStatus
auth_enabledrequired boolean
bind_addrrequired string
candidate_aliases array of CandidateAliasStatus One entry per candidate alias, by name. Absent while none is
configured, so an install without any reads as it did before the key
existed: no empty array, no key at all.
countsrequired ObjectCounts
devicesrequired DevicesStatus The device link: lmgw's device CA and the server certificates issued
from it (device link design §9.2).
machine MachineSummary The machine check's verdict (machine-check design §4.1): whether this
computer can run local models. Absent until the check at boot has
finished; POST /api/op/machine_check has the whole check.
mcp_serversrequired array of McpStatus
requestsrequired RequestStats
runtimerequired array of RuntimeStatus One row per model lmgw believes is running (a container is per model, not per class).
self_adminrequired AdminLevel The gateway's self-admin level: what the lmgw__* tools may do.
upstreams_out_of_quotarequired array of UpstreamQuotaStatus The upstreams lmgw remembers out of quota (openai egress design
§14.6); empty while none is.
uptime_secondsrequired integer (uint64)
versionrequired string
vramrequired VramStatus The GPU those containers share: what is resident, what it is measured
to cost, and anything queued behind it. Reported even when admission
is inactive; inactive_reason says why.
webrtcrequired WebRtcStatus The UDP listener for WebRTC calls: its socket groups, one per HTTP
listener (realtime calls design §9).
default Error.
application/json ApiError
get/api/vram

Get the GPU ledger

Capability admin, open to: owner

The GPU ledger and the admission queue, freshly measured, and the starts waiting for their engine image's download (downloading, with its bytes) — the same object the vram SSE frame carries, so a page can fetch once and then follow the stream.

Responses

StatusDescription
200 OK.
application/json VramStatus
Fields of VramStatus
activerequired boolean Whether admission is actually arbitrating; false is explained by
inactive_reason.
benchmarkrequired VramBenchmark | null The benchmark run holding the card, if one does: no local model is admitted until it ends.
capacity_bytesrequired integer (uint64)
devicesrequired array of VramDevice
downloadingrequired array of VramWaiter Starts whose model's engine image is still downloading (machine-check
design §5), oldest first: each phase is downloading with the bytes
so far. They hold no place in queue and nothing on the card; once
its download is done a start is admitted like any other, and enters
queue if it has to wait for room. Absent from an older gateway's
frame.
drainingrequired array of string Resident model ids that are busy or still starting while hold is
active — visible continuously, not only in the one-shot hold_set
response. Empty whenever hold is not active.
enabledrequired boolean
estimated_resident_bytesrequired integer (uint64)
external_trigger_activerequired boolean Whether the outside-VRAM fallback can fire right now.
external_trigger_reasonrequired string | null Why it cannot, when it cannot (the switch, admission, the hold, no
telemetry, an unattributable lmgw model).
free_bytesrequired integer | null
free_measuredrequired boolean False when free_bytes was derived from the estimate rather than read
from the driver.
headroom_bytesrequired integer (uint64)
hold_activerequired boolean The hold.active setting — hold is a switch on
the resolve/start paths, orthogonal to enabled/active above.
inactive_reasonrequired string | null
kept_freerequired VramKeptFree What free_bytes was lowered by on top of the memory in use, by
reason. With a measured free figure, free_bytes is the capacity's
measured free memory — the devices' free memory, or with
vram.budget_mb the budget less the devices' used memory — less
these (never below zero). The devices' total less their used and free
memory is in neither: memory the probe reports as not available
(NVML: the driver's own reserve; an AMD APU: GTT the host's RAM
cannot back).
kv_poolsrequired array of VramKvPool The token ledger of every guarded unified-KV chat model with a request
in flight or waiting — vram::VramView's
kv_pools. Absent from an older gateway's frame, hence the default.
lmgw_share_bytesrequired integer | null lmgw's own share of the pooled devices' used memory, measured per
process. None when it
cannot be measured — see external_trigger_reason.
noterequired string
outside_share_bytesrequired integer | null Used memory that is not lmgw's — games, the desktop, other apps.
None exactly when lmgw_share_bytes is.
queuerequired array of VramWaiter
residentrequired array of VramResident
telemetryrequired string Where the measured numbers come from, verbatim.
telemetry_okrequired boolean
default Error.
application/json ApiError

Models

get/api/gguf-files

List GGUF files on disk

Capability admin, open to: owner

GGUF files under a class's models dir, matched against an optional search string.

Parameters

NameInDescription
searchquery string | null
targetquery string | null

Responses

StatusDescription
200 OK.
application/json GgufFiles
Fields of GgufFiles
filesrequired array of GgufFile
models_dirrequired string
default Error.
application/json ApiError
get/api/ladder-rung-plan

Plan a ladder's rungs

Capability admin, open to: owner

The ladder editor's per-rung footprint table: every rung shares cache types, projector and drafter with the base row.

Parameters

NameInDescription
cache_type_kquery string | null
cache_type_vquery string | null
ctx_sizerequiredquery integer (int64)
draft_gguf_pathquery string | null
gguf_pathrequiredquery string
mmproj_pathquery string | null
n_gpu_layersquery integer | null

Responses

StatusDescription
200 OK.
application/json RungPlan
Fields of RungPlan
footprintrequired RungFootprint
has_mtp_layersrequired boolean Whether the GGUF header carries MTP tensors.
trained_contextrequired integer | null The weights' trained context (<arch>.context_length): llama-server
caps every slot there, and a rung whose per-slot context
is above it is refused. None when the header does not say.
default Error.
application/json ApiError
get/api/llama-flags

Preview a model's llama-server flags

Capability admin, open to: owner

The llama-server flags a model (or a search over models) would start with — the same read lmgw__llama_flags answers.

Parameters

NameInDescription
modelquery string | null
searchquery string | null

Responses

StatusDescription
200 OK.
application/json LlamaFlags
Fields of LlamaFlags
allowed_valuesrequired object For flags that take a fixed set of values, the values, keyed by flag.
flag_countrequired integer (uint) How many flags the image has before the search filter.
flagsrequired array of string The flags matching the search (all of them without one).
imagerequired string The image whose --help was read.
noterequired string Why the vocabulary is per image.
removedrequired array of string Flags the image removed or renamed away.
default Error.
application/json ApiError
get/api/local-model

Get a local model's definition

Capability admin, open to: owner

One local model's full definition, by id or model_id. Row ids are per table, so pass target together with id; without target a model_id is searched in the chat table first, then aux, image and audio. target narrows the lookup to one table. The answer's class field says which of the four shapes it is.

Parameters

NameInDescription
idquery integer | null
model_idquery string | null
targetquery string | null

Responses

StatusDescription
200 OK.
application/json
One of 4 shapes
LocalModelDetail
Fields of LocalModelDetail
advisoriesrequired array of string Configuration that loads and serves but misbehaves under some input
(a large image, say). Apart from problems because the model starts.
capabilities_overriderequired any An alias's capabilities override for the derived /v1/models capability facts: a JSON
object with optional keys capabilities, max_output_tokens, notes. None = no
override.
command_linerequired string The exact podman run … command line this model renders to;
the published host port is a placeholder, since it is allocated per
start.
downloaded_fromrequired DownloadedFrom | null The download this file came from, when the downloader fetched it.
draft_presentrequired boolean | null
enabledrequired boolean
extra_argsrequired array of string One entry per llama-server argument (round-trips with the patch field).
extra_run_argsrequired array | null Per-model podman run args override, one entry per argument (round-trips
with the patch field); None inherits the chat class settings'
extra_run_args.
fallbackrequired string | null The one fallback (openai egress design §14.2); None = none.
fit_noterequired FitNote | null The note of a context fitted to the graphics card (find-a-model
design D26): Get it's or "Fit again"'s; None when the row's
context isn't a fit's shorter one.
gguf_pathrequired string
gguf_presentrequired boolean
idrequired integer (int64)
idle_secondsrequired integer (int64)
imagerequired string | null Per-model container image override;
None inherits the chat class settings' image.
ladderrequired array of Rung Ladder rungs above the base; empty = not a ladder. The editor's ladder table reads
it.
licencerequired ModelLicence | null The licence the GGUF header states; null when it states none.
mmproj_presentrequired boolean | null
model_idrequired string
paramsrequired LlamaParams
problemsrequired array of string Static findings; empty means "nothing obviously wrong", not "loads".
publicrequired boolean
rungsrequired array | null Every rung's own command line, per-slot context and switchover;
null on a row that is not a ladder.
sourcerequired string hf | manual.
warm_startrequired boolean Start this model's own container at app launch.
A llama-server chat model.
AuxModelDetail
Fields of AuxModelDetail
backendrequired string | null cpu runs the row on the CPU; null runs it on the GPU.
batch_sizerequired integer | null --batch-size; null takes llama-server's default.
command_linerequired string The podman run … command line this model renders to.
ctx_sizerequired integer | null
downloaded_fromrequired DownloadedFrom | null
enabledrequired boolean
endpointrequired string The route that serves it: /v1/embeddings, /v1/rerank or
/v1/systemone.
extra_argsrequired array of string One entry per llama-server option (round-trips with the patch field).
extra_run_argsrequired array | null podman run args override, one entry per argument; null inherits.
fallbackrequired string | null The one fallback (openai egress design §14.2), as written; null =
none.
fit_noterequired FitNote | null The note of a context fitted to the graphics card (find-a-model
design D26): Get it's or "Fit again"'s; None when the row's
context isn't a fit's shorter one.
gguf_pathrequired string
gguf_presentrequired boolean
idrequired integer (int64)
idle_secondsrequired integer (int64)
imagerequired string | null Container image override; null inherits the aux class's.
kindrequired string embed, rerank or decision.
licencerequired ModelLicence | null The licence the GGUF header states; null when it states none.
mmproj_pathrequired string | null A projector (--mmproj), relative to the aux models dir.
model_idrequired string
poolingrequired string | null
problemsrequired array of string Static findings; empty is not proof it loads.
public_namerequired string The name clients call it by, with the aux prefix.
sourcerequired string hf or manual.
threadsrequired integer | null --threads; null renders none on the GPU, and on the CPU this
machine's physical cores (the logical CPU count where the core
topology cannot be read) unless the row's extra args name a count.
threads_in_effectrequired integer | null The thread count its container starts with: threads, else a count
the extra args name, else on the CPU this machine's cores. Null when
nothing names one (a GPU row: llama-server picks) or the args' value
is not a number.
threads_sourcerequired AuxThreadsSource Where threads_in_effect comes from.
ubatch_sizerequired integer | null --ubatch-size; null takes llama-server's default.
warm_startrequired boolean
An embedding, rerank or decision model.
ImageModelDetail
Fields of ImageModelDetail
argsrequired object Runtime and default-generation flags.
capabilities_overriderequiredany
command_linerequired string
editrequired boolean
enabledrequired boolean
endpointsrequired array of string The routes that serve it.
extra_run_argsrequired array | null podman run args override, one entry per argument; null inherits.
fallbackrequired string | null The one fallback (openai egress design §14.2), as written; null =
none.
filesrequired object Flag key to path under the image models dir.
files_presentrequired object For each key of files, whether the file (or directory) exists.
idrequired integer (int64)
idle_secondsrequired integer (int64)
imagerequired string | null
model_idrequired string
modesrequired array of string
peakrequired string peak_extra_bytes in a sentence.
peak_extra_bytesrequired integer | null Bytes one generation was measured to need above idle residency;
null until one has run.
peak_learned_atrequired string | null
problemsrequired array of string
public_namerequired string The name clients call it by, with the image prefix.
warm_startrequired boolean
A stable-diffusion.cpp pipeline.
AudioModelDetail
Fields of AudioModelDetail
backendrequired string | null cpu when the row is switched to the CPU; null inherits the class.
busy_timeout_msrequired integer | null
config_idrequired string | null
default_request_optionsrequired object
default_voice_presetrequiredany
effective_extra_run_argsrequired array of string The podman run args in effect, one entry per argument.
effective_imagerequired string The image the container starts from (the row's, else the class's).
enabledrequired boolean
extra_run_argsrequired array | null podman run args override, one entry per argument; null inherits.
fallbackrequired string | null The one fallback (openai egress design §14.2), as written; null =
none.
familyrequired string The audio.cpp model-loader family.
idrequired integer (int64)
imagerequired string | null Container image override; null inherits the audio class's.
lazyrequired boolean | null
load_optionsrequired object
moderequired string
model_idrequired string
model_spec_overriderequired string | null
next_steprequired string How to prove the model works.
pathrequired string The model directory, relative to the audio models dir.
path_presentrequired boolean Whether that path exists.
problemsrequired array of string
public_namerequired string The name clients call it by, with the audio prefix.
residencyrequired LearnedResidency | null What the container was measured to hold on the GPU.
residency_charged_bytesrequired integer | null The learned residency admission charges, when it belongs to the
current configuration.
residency_noterequired string What the row is charged on the GPU, in a sentence.
runningrequired AudioRunning | null The container's state, when one is running.
runs_onrequired string gpu or cpu.
server_jsonrequired any The server.json entry this row renders to.
session_optionsrequired object
taskrequired string
threadsrequired integer | null
threads_in_effectrequired integer (int64)
threads_sourcerequired string row, class, cores or logical_cpus.
voice_presetsrequired object
warm_startrequired boolean
weight_idrequired string | null
An audio.cpp model.
default Error.
application/json ApiError
get/api/local-model-check

Check a local model's config

Capability admin, open to: owner

Checks a local model's config without starting it (missing files, a port already in use, and the like) — the same read lmgw__local_model_check answers.

Parameters

NameInDescription
model_idquery string | null
targetquery string | null

Responses

StatusDescription
200 OK.
application/json LocalModelCheck
Fields of LocalModelCheck
brokenrequired integer (uint) How many of models have problems (ok false).
checkedrequired integer (uint) How many models were looked at (all classes asked for).
modelsrequired array of ModelCheck Models with something to report, or the one asked for by name.
noterequired string What the check does and does not prove.
with_advisoriesrequired integer (uint) How many carry advisories; those never count as broken.
default Error.
application/json ApiError
get/api/local-model-plan

Plan a local model's parameters

Capability admin, open to: owner

A complete, ready-to-apply local-model parameter set derived from a GGUF file's own metadata, with a rationale for each value — the editor's wizard read, and the same one lmgw__local_model_plan answers. A file on disk is named by path; a file on Hugging Face by repo and file, planned from its header before anything is downloaded (1 to 16 MiB read a file). A chat or aux plan carries its source and its fit on the graphics card, against the whole card and beside what runs on it now; an image plan (target=image) carries neither yet.

Parameters

NameInDescription
filequery string | null
pathquery string | null
repoquery string | null
targetquery string | null

Responses

StatusDescription
200 OK.
application/json PlanResult
Fields of PlanResult
configured_asrequired array of ConfiguredAs The rows of the planned class already serving this GGUF, each with how
it differs from the plan. A row's comparison is the plan's own: it
knows what the plan's raw params do not (a tuning the row may take
further, a projector its args already name, placement left to the
owner), so an editor refills a saved row from change, not params.
fitrequired PlanFit | null The planned file's fit on the card, by both measures (find-a-model
design §3.1); None for an image plan, whose fit on the card isn't
measured yet.
model_idrequired string
next_steprequired string
paramsrequired object
rationalerequired object
sourcerequired PlanSource Where the plan's input came from: the disk, or the hub before any
download (find-a-model design §2.3). An image plan (target=image)
has no source in its answer: it is always from the disk.
warningsrequired array of string
default Error.
application/json ApiError
get/api/model-inspect

Inspect a GGUF file

Capability admin, open to: owner

Reads a GGUF file's metadata, optionally probing it — the same read lmgw__model_inspect answers.

Parameters

NameInDescription
pathrequiredquery string
targetquery string | null

Responses

StatusDescription
200 OK.
application/json ModelInspect
Fields of ModelInspect
architecturerequired string | null
aux_kindrequired string | null For an aux file: embed, rerank or decision.
block_countrequired integer | null
context_lengthrequired integer | null The model's trained context, in tokens.
file_sizerequired string file_size_bytes for a person to read.
file_size_bytesrequired integer (uint64)
full_attention_intervalrequired integer | null
has_audio_encoderrequired boolean | null
has_chat_templaterequired boolean
has_classifier_headrequired boolean A classification head, as a cross-encoder reranker has.
has_mtp_layersrequired boolean
has_vision_encoderrequired boolean | null
head_countrequired integer | null
head_count_kvrequired integer | null
head_count_kv_per_layerrequired array | null Per-layer KV heads, on models whose layers differ.
licencerequired ModelLicence | null The licence the header states; null when it states none.
namerequired string | null
pathrequired string The path under the class's models dir.
pooling_typerequired string | null none, mean, cls, last or rank; set on encoders.
projector_typerequired string | null On a projector file: its type.
quantrequired string | null
rolerequired string weights, mmproj (a projector), drafter or unknown.
serve_asrequired string Which class serves this file, from its header rather than its
directory: chat or aux.
signalsrequired TemplateSignals | null Text heuristics over the chat template; null without a template.
size_labelrequired string | null
sliding_windowrequired integer | null
sliding_window_patternrequired integer | null
sliding_window_pattern_is_arrayrequired boolean sliding_window_pattern counts layers described, not a stride.
suggested_spec_typerequired string | null The spec_type the file calls for when it is a drafter or carries
MTP layers.
targetrequired string The models dir class the path was resolved in: chat or aux.
vision_block_countrequired integer | null
vram_estimaterequired VramEstimate
default Error.
application/json ApiError
get/api/models/full

List every configured model

Capability admin, open to: owner

Every configured model, all five kinds, plus candidate aliases and expose-all passthrough upstreams — the Models page's one read.

Responses

StatusDescription
200 OK.
application/json ModelsFull
Fields of ModelsFull
aliasesrequired array of AliasView
audiorequired array of AudioModelView
auxrequired array of AuxModelView
candidate_aliasesrequired array of CandidateAliasView Candidate aliases. Defaulted, like
image, so a UI bundle newer than the gateway it is talking to still
parses the payload.
imagerequired array of ImageModelView The stable-diffusion.cpp class. Defaulted
rather than required, so a UI bundle newer than the gateway it is
talking to still parses the payload.
localrequired array of LocalModelView
passthroughrequired array of PassthroughUpstream Enabled expose_all upstreams: (upstream name, request prefix).
default Error.
application/json ApiError
get/api/wiring

Get the model wiring diagram

Capability admin, open to: owner

The signal path per model, composed server-side: which upstream, which container, which fallback — shared verbatim with the Wiring page.

Responses

StatusDescription
200 OK.
application/json WiringView
Fields of WiringView
base_urlrequired string Gateway base URL without /v1.
localsrequired array of LocalChain
models_dirrequired string Chat models dir, empty when unset — then nothing can be scanned.
models_dir_missingrequired boolean
orphansrequired array of OrphanGguf GGUFs on disk no local model references (as weights, projector or
drafter).
upstreamsrequired array of UpstreamChain Remote upstreams only (llama-server-kind ones are the local chains).
default Error.
application/json ApiError

Upstreams

get/api/upstream-models

List an upstream's live models

Capability admin, open to: owner

One upstream's live model catalog, cached server-side for a short TTL — a round trip to the upstream, so it is its own read rather than part of the upstreams list.

Parameters

NameInDescription
idrequiredquery integer (int64)

Responses

StatusDescription
200 OK.
application/json UpstreamModelsResponse
Fields of UpstreamModelsResponse
entriesrequired array of UpstreamModelEntry The same models, with what the catalog states about each. Defaulted,
so a gateway older than the field still parses (ids only).
modelsrequired array of string
default Error.
application/json ApiError
get/api/upstreams

List upstreams

Capability admin, open to: owner

Every configured upstream, secrets redacted to has_api_key and extra header values shown as <set>.

Responses

StatusDescription
200 OK.
application/json UpstreamsResponse
Fields of UpstreamsResponse
upstreamsrequired array of UpstreamView
default Error.
application/json ApiError

MCP servers & tools

get/api/mcp-servers

List registered MCP servers

Capability admin, open to: owner

Every registered southbound MCP server, its connection state, its exposed tools and how many MCP tasks it runs for Chat threads now (open_tasks).

Responses

StatusDescription
200 OK.
application/json McpServersResponse
Fields of McpServersResponse
mcp_serversrequired array of McpServerView
default Error.
application/json ApiError
get/api/mcp-servers/{id}/tools

List one MCP server's tools

Capability admin, open to: owner

One server's exposed tools — what a Chat thread's MCP picker offers.

Parameters

NameInDescription
idrequiredpath integer

Responses

StatusDescription
200 OK.
application/json McpServerToolsResponse
Fields of McpServerToolsResponse
toolsrequired array of McpToolView
default Error.
application/json ApiError
get/api/tools

List the tool inventory

Capability admin, open to: owner

The whole northbound tool surface: the built-in toolsets and every registered server's tools, each with its source and why it is or is not offered.

Responses

StatusDescription
200 OK.
application/json ToolInventory
Fields of ToolInventory
sourcesrequired array of ToolSourceView Group headers. A source with tool_count: 0 is still here, carrying the
reason it contributes nothing.
toolsrequired array of ToolEntryView
default Error.
application/json ApiError

Downloads

get/api/audio/catalog

Get the audio.cpp spec catalog

Capability admin, open to: owner

audio.cpp's own spec catalog, from the cached snapshot only — an absent fetched_at means "never fetched here"; a page load never waits on GitHub.

Responses

StatusDescription
200 OK.
application/json AudioCatalog
Fields of AudioCatalog
familiesrequired array of AudioFamily Families with an installed package or a served model come first.
fetched_at string RFC3339 fetch time of the snapshot; absent when nothing is cached yet.
warnings array of string What the last refresh could not do — a spec file that did not load, a
package repo Hugging Face could not list (offline, rate-limited,
gated) — or that it has not checked the package files yet. Stays until
the next refresh. Absent when there are none.
default Error.
application/json ApiError
get/api/hf/downloads

List downloads

Capability admin, open to: owner

The download queue and history. No filter returns every row ever recorded; a poller passes the ids its queueing call returned.

Parameters

NameInDescription
activequery boolean | null
idsquery string | null

Responses

StatusDescription
200 OK.
application/json DownloadsView
Fields of DownloadsView
downloadsrequired array of DownloadRow
default Error.
application/json ApiError
get/api/hf/repo

List a Hugging Face repo's files

Capability admin, open to: owner

A Hugging Face repo's files, classified into weights, mmproj projector and speculative drafter candidates. With fit=true each weights file of the chat or aux class also gets its fit on this computer's graphics card, and the answer names the recommended file (find-a-model design §3.3); that reads file headers from Hugging Face, 1 to 16 MiB each, and header_bytes_read says how much. fit=unless_metered reads nothing on a metered connection: every mark is then by size, and metered says why. The card and what holds for every file are said once, in card and fit_notes.

Parameters

NameInDescription
fitquery RepoFit | null
reporequiredquery string
searchquery string | null
targetquery string | null

Responses

StatusDescription
200 OK.
application/json RepoFiles
Fields of RepoFiles
cardrequired CardMeasure | null With fit: the card the marks were measured against, one reading for
every file; None without one (D9), when every mark is no_card. A
file's own fit.card is left out where it is this one.
filesrequired array of RepoFile
fit_notesrequired array of string With fit: what holds for the whole list, each a sentence, said
here once rather than in every file's notes: the GPU hold's line,
admission off, what other programs use not being known, where the
estimates came from, why the header reads stopped, why no file was
measured (no card to measure against, a class whose files aren't
measured).
header_bytes_readrequired integer (uint64) With fit: the file header bytes this answer received from Hugging
Face, every file's, a read that failed after it began included; a
header lmgw had read before adds nothing (D123).
meteredrequired string | null With fit=unless_metered on a metered connection (D123): why no
header was read. Every mark is then by size and nothing is
recommended; fit=true reads the headers.
noterequired string How to read role and what to do with the list, for a person or an
agent. It differs by target: the image classes' roles are filename
heuristics and a pipeline spans several repos, the others name the
weights file to hand to hf_add, which fetches its companions. When
files is empty (nothing in the repo matched) it says so plainly
instead.
picksrequired RepoPicks | null With fit: the pick by each measure, with its "Why this file" line.
recommendedrequired string | null With fit (find-a-model design §3.2, D120): the file this list
recommends, the pick beside what runs on the graphics card now, else
the whole card's. None without fit, or when no file qualifies.
reporequired string
targetrequired string Which class's file kinds and role vocabulary were listed. Empty on a
response from before the image class existed; chat then.
default Error.
application/json ApiError

Settings

get/api/settings-full

Get every setting

Capability admin, open to: owner

Every dashboard-editable setting: bind address, self-admin mode + token, secrets (masked), and all three class definitions. Deliberately broader than what the settings_set self-admin tool exposes.

Responses

StatusDescription
200 OK.
application/json SettingsFull
Fields of SettingsFull
agent_origin_suffixrequired string The DNS suffix a service agent's UI is served under,
default localhost: http://<id>.<agent_origin_suffix>:<bind port>/.
agent_origin_suffix_warningrequired string | null Why the **stored** suffix shadows the gateway, when it does. It is validated on write, but
bind_addr, this machine's host
name and its search domains are the other side of that rule and move
without it: this is the same sentence the boot log carries, so a
gateway that started shadowing says so where the setting is read rather
than only where it was typed. None on a gateway that shadows nothing.
agent_script_imagerequired string The stock image a manifest's script step runs in, default
docker.io/library/node:24-alpine.
api_keysrequired array of ApiKeyRow
audiorequired AudioSettings
auth_enabledrequired boolean
aux_routerrequired AuxRouterSettings
bind_addrrequired string
build_update_check_hoursrequired integer (uint32) How often the build update check runs, in hours. 0 = off.
builds_dirrequired string | null Where container builds keep their git mirrors, per-run worktrees and
logs, as configured. None = the default, which
builds_dir_effective spells out.
builds_dir_effectiverequired string The directory builds actually use: builds_dir, else
<data_dir>/builds (a dev instance: ~/.cache/lmgw-dev/builds).
builds_dir_warningrequired string | null Why builds would refuse to run in builds_dir_effective (it is on
tmpfs, i.e. RAM); None when they would not.
chat_archive_daysrequired integer (int64) Archive a Chat thread this many days after its last activity; 0
disables auto-archive. Reversible: a pin, a restore or a message sent
into the thread brings it back.
chat_feed_keepalive_max_srequired integer (uint32) The longest keep-alive a feed may ask for itself (?keepalive_s=),
in seconds (1 to chat_feed::MAX_KEEPALIVE_S).
chat_feed_keepalive_srequired integer (uint32) Seconds between the Chat feed's keep-alive comments (1 to
chat_feed_keepalive_max_s).
chat_feed_live_bufferrequired integer (uint32) Live Chat feed events held for a slow client before it gets a fresh
state instead (≥ 1).
chat_feed_page_sizerequired integer (uint32) Records the Chat feed reads per query while a client catches up
(≥ 1).
chat_feed_retention_daysrequired integer (int64) Days the Chat change feed keeps its records; 0 = all.
chat_kb_budget_tokensrequired integer (uint32) Tokens of knowledge-base excerpts one Chat turn may carry (> 0).
chat_media_defaultsrequired MediaDefaults The image and audio tools' default models (GET
/chat/api/media/defaults
lists the choices and says which no longer
resolve); an absent field is no default. A folder and a thread can
override each.
chat_pdf_moderequired string How a text PDF attached in Chat starts out: text | images | ask.
chat_profilerequired integer | null The personality profile new Chat threads start with
(GET /chat/api/profiles); null for none ("Default").
chat_purge_daysrequired integer (int64) Delete an archived, unpinned Chat thread this many days after it was
archived; 0 keeps archived threads forever.
chat_read_aloudrequired boolean Read Chat replies aloud as they stream.
chat_speech_stylerequired string The Chat's speech instructions; empty = realtime.speech_instructions.
chat_stt_aliasrequired string The Chat's speech-to-text alias — dictation, realtime mode and audio
attachments; empty = realtime.asr_alias.
chat_system_promptrequired string The system prompt new Chat threads start with, as in force: the
configured prompt, or the built-in one when none was written.
chat_system_prompt_builtinrequired string The built-in default, which saving chat_system_prompt as this text
returns to.
chat_tts_aliasrequired string The Chat's text-to-speech alias; empty = realtime.tts_alias.
chat_turn_detectionrequired string semantic_vad | server_vad | push_to_talk.
chat_voicerequired string The Chat's voice, chosen for the Chat's text-to-speech model; empty =
none named, so realtime's chain decides (realtime.default_voice,
then the model's default). A thread that speaks with another model
does not take it.
chat_voice_audio_inputrequired string off | on: whether a voice turn goes to the chat model as audio
when the model that answers it takes audio input, wherever it runs
(experimental).
chat_voice_languagerequired string The language the user speaks (ISO 639-1), what the speech-to-text
model is told; empty = none.
chat_voice_language_notesrequired array of LanguageNote Where the Chat's own speech models (as saved) do not take their
language as set — an ASR that detects chat_voice_language itself, a
voice that cannot speak the reply language; empty without a language.
chat_voice_reply_languagerequired string The language replies are in (ISO 639-1): the model answers in it
and the voice speaks it; empty = chat_voice_language.
container_prefixrequired string Podman container name prefix for the per-model container runtime:
<container_prefix>-<class>-
<slug>-<hash6>
.
currencyrequired string The label every amount on the Usage page is shown under. One currency,
no conversion — changing it relabels, it never converts.
data_dirrequired string
devicesrequired DevicesSettings The device listener and the bounds of its trust (Settings → Network
& access → Devices, device link design §9.1).
docs_embed_batchrequired integer (uint32) Texts per embedding call during ingest and re-embed.
docs_fetch_delay_msrequired integer (uint64) Politeness pause between two fetches to the same host, ms.
docs_ingest_reply_tokensrequired integer (uint32) Room reserved for one extraction reply.
docs_rerank_modelrequired string Alias the rerank stage calls; empty = the aux router's single enabled
rerank model, and the search trace names the reason when there is none.
docs_searchrequired DocsSearchDefaults The stage defaults a request that overrides nothing starts from.
forge_tokensrequired object Forge API tokens by host. Values are always the
<set> placeholder — a token never round-trips.
global_budget_microrequired integer (int64) Spend ceiling across every key, in currency micro-units. 0 = none.
global_budget_periodrequired string day | month | total.
has_hf_tokenrequired boolean
has_update_tokenrequired boolean
holdrequired HoldSettingsDto The manual GPU hold — orthogonal to vram
above: a switch on the resolve/start paths, not a capacity policy.
host_cpurequired HostCpu This machine's CPUs, read once (a derived fact, never settable): the
thread count an audio row switched to the CPU runs with when it names
none.
imagerequired ImageSettings The stable-diffusion.cpp class.
jobs_max_rowsrequired integer (int64)
jobs_retention_daysrequired integer (int64)
local_reference_aliasrequired string Alias whose price answers the local-vs-cloud counterfactual; empty =
the panel says no reference is configured.
max_body_mbrequired integer (uint32)
mcprequired HostSettings The device MCP host link's limits (client-apps design §5.1).
quota_recheck_secondsrequired integer (uint64) Seconds before an upstream remembered out of quota is asked again,
when its answer carried no Retry-After; until then a model with a
fallback on it answers with the fallback.
realtimerequired RealtimeSettings GET /v1/realtime, spoken conversations.
responses_max_chainsrequired integer (int64)
responses_max_tool_callsrequired integer (uint32)
responses_retention_hoursrequired integer (int64)
responses_storerequired boolean
responses_timeout_secondsrequired integer (uint64)
retention_daysrequired integer (int64)
retention_max_rowsrequired integer (int64)
routerrequired RouterSettings
sampling_aliasrequired string
self_adminrequired AdminLevel The gateway's self-admin level: what the lmgw__* tools may do, for
every caller, a paired device's own level capped by it.
update_check_enabledrequired boolean
usage_retention_monthsrequired integer (int64) Keep hourly usage rollups this many months; 0 = forever.
versionrequired string
vramrequired VramSettingsDto GPU admission control.
default Error.
application/json ApiError

Stored responses

get/api/responses

List stored response chains

Capability admin, open to: owner

Every stored /v1/responses conversation chain, most recent first, capped at 200.

Responses

StatusDescription
200 OK.
application/json ResponsesIndex
Fields of ResponsesIndex
cappedrequired boolean True when more chains exist than the 200 shown.
chainsrequired array of ChainRow
max_chainsrequired integer (int64)
retention_hoursrequired integer (int64)
rulesrequired string The eviction rules in one sentence.
store_enabledrequired boolean
total_chainsrequired integer (int64)
total_responsesrequired integer (int64)
default Error.
application/json ApiError
get/api/responses/chain

Get a response chain

Capability admin, open to: owner

One conversation chain's stored responses, each with its outline, text, pending tool calls and full body.

Parameters

NameInDescription
idrequiredquery string

Responses

StatusDescription
200 OK.
application/json ChainDetail
Fields of ChainDetail
chain_idrequired string
responsesrequired array of ResponseItem
default Error.
application/json ApiError

Usage

get/api/usage/errors

Get usage errors by kind

Capability admin, open to: owner

Refusals and errors over a time range, grouped by error kind.

Parameters

NameInDescription
aliasquery string | null
bucketquery string | null
classquery string | null
fromquery string | null
key_idquery integer | null
toquery string | null
tzquery integer | null

Responses

StatusDescription
200 OK.
application/json UsageErrorsResponse
Fields of UsageErrorsResponse
bucketsrequired array of string
kindsrequired array of ErrorKindSeries One entry per distinct kind, ordered by total descending.
retention_daysrequired integer (int64) How far back the raw rows actually go — the honest x-axis of this card.
default Error.
application/json ApiError
get/api/usage/export.csv

Export usage as CSV

Capability admin, open to: owner

The same usage rows as GET /api/usage/series, as a CSV download — one row per (bucket, key, alias, upstream, class, outcome).

Parameters

NameInDescription
aliasquery string | null
classquery string | null
fromquery string | null
key_idquery integer | null
toquery string | null
tzquery integer | null
upstream_idquery integer | null

Responses

StatusDescription
200 OK.
text/csv string (binary)
default Error.
application/json ApiError
get/api/usage/heat

Get a usage heatmap

Capability admin, open to: owner

Cost by hour-of-day × day-of-week, for the usage heatmap.

Parameters

NameInDescription
aliasquery string | null
classquery string | null
fromquery string | null
key_idquery integer | null
toquery string | null
tzquery integer | null
upstream_idquery integer | null

Responses

StatusDescription
200 OK.
application/json UsageHeatResponse
Fields of UsageHeatResponse
cellsrequired array of HeatCell
maxrequired integer (int64)
default Error.
application/json ApiError
get/api/usage/keys

List keys with their usage

Capability admin, open to: owner

Every gateway key with its lifetime and recent spend, scope and last-used time.

Responses

StatusDescription
200 OK.
application/json KeysResponse
Fields of KeysResponse
auth_enabledrequired boolean *Require API key* (Settings → Network & access): off, an anonymous
/v1 call is served — what the Devices card warns of, since a
device's scope and budget then bound only its own key.
currencyrequired string
global_budget_microrequired integer (int64) The global budget and what has gone against it this period.
global_budget_periodrequired string day | month | total — what "this period" means, so a projection
to the period's end can aim at the right horizon instead of assuming a
calendar month.
global_spent_microrequired integer (int64) What the global budget counts this period, the budget floors of
unpriced requests included, as KeyRow::spent_micro counts them.
global_spent_unknown_requestsrequired integer (int64) The unpriced requests of the period, those whose floor
global_spent_micro includes too, as
KeyRow::spent_unknown_requests counts them.
keysrequired array of KeyRow
default Error.
application/json ApiError
get/api/usage/local

Get the local/cloud usage split

Capability admin, open to: owner

The local/cloud spend split and the counterfactual: what the same local traffic would have cost against the configured reference alias.

Parameters

NameInDescription
aliasquery string | null
classquery string | null
fromquery string | null
key_idquery integer | null
toquery string | null
tzquery integer | null

Responses

StatusDescription
200 OK.
application/json UsageLocalResponse
Fields of UsageLocalResponse
cloud_tokensrequired integer (int64)
counterfactual_microrequired integer | null What the local tokens **would** have cost at reference_alias's price.
Not a saving — nobody would have run all of it there.
None when no reference alias is configured, which the page must say
rather than quietly picking one.
currencyrequired string
decode_tok_srequired number | null Throughput and cache facts for the local models in the window.
draft_acceptancerequired number | null
kv_reuserequired number | null
local_tokensrequired integer (int64)
reference_aliasrequired string | null
default Error.
application/json ApiError
get/api/usage/prices

List prices

Capability admin, open to: owner

Every price row, plus the models seen in traffic that have none — the Prices tab's one read.

Responses

StatusDescription
200 OK.
application/json PricesResponse
Fields of PricesResponse
currencyrequired string
pricesrequired array of PriceRowView
unpriced_hosted_toolsrequired array of UnpricedHostedTool Every model whose native answers ran a hosted tool that bills beyond
its tokens, busiest first: unpriced, since lmgw has no price unit for
those fees yet.
unpriced_modelsrequired array of UnpricedModel Every model the gateway serves that no price sheet covers — **including
the passthrough models an expose_all upstream serves**, which are the
ones a deployment with no configured aliases actually uses. Ordered by the
requests each has already spent unpriced.
unpriced_tiersrequired array of UnpricedTier Every model that answered at an OpenAI service tier it has no price
row for, busiest first: that traffic is unpriced until one is entered.
default Error.
application/json ApiError
get/api/usage/series

Get a usage time series

Capability admin, open to: owner

Cost and token series over a time range, bucketed and grouped by class, alias, key or upstream. Series past limit (default 6, the chart's colour slots) fold into a server-side "other" tail.

Parameters

NameInDescription
aliasquery string | null
bucketquery string | null
classquery string | null
fromquery string | null
group_byquery string | null
key_idquery integer | null
limitquery integer | null
toquery string | null
tzquery integer | null
upstream_idquery integer | null

Responses

StatusDescription
200 OK.
application/json UsageSeriesResponse
Fields of UsageSeriesResponse
bucketsrequired array of string Every bucket label in the window, in order, including empty ones — a
chart that silently drops quiet days draws a lie about its own x-axis.
cellsrequired array of UsageCell
currencyrequired string
latencyrequired array of LatencyPoint The same four percentiles **per bucket**, aligned with buckets, so a
latency chart plots a real p50/p95 line rather than a mean. Dividing the
rollup's sums would give a mean, and one 30-second outlier drags a mean
four times above the typical request.
p50_total_msrequired number | null p50 / p95 of total latency and TTFB over the window, in ms. None where
the window holds no successful request: an empty window has no p95, and
0 would draw a gateway that got infinitely fast.
p50_ttfb_msrequired number | null
p95_total_msrequired number | null
p95_ttfb_msrequired number | null
previousrequired UsageCell | null Totals over the immediately preceding window of the same length, for the
tiles' "vs previous" delta. None when that window predates the data.
seriesrequired array of SeriesMeta
totalsrequired UsageCell
units_since string When this install started recording the billable quantities
(audio_in_ms, chars_in, images_out), RFC 3339 UTC. A bucket
before it reads 0 because nothing was recorded, not because nothing
was processed: show such a bucket as not recorded rather than as
zero.

Absent when the bookkeeping holds no such row.
default Error.
application/json ApiError
get/api/usage/top

Get top usage by dimension

Capability admin, open to: owner

The ranked rows for one dimension (alias, key, upstream, model) over a time range, by cost then tokens.

Parameters

NameInDescription
aliasquery string | null
classquery string | null
dimquery string | null
fromquery string | null
key_idquery integer | null
limitquery integer | null
toquery string | null
tzquery integer | null
upstream_idquery integer | null

Responses

StatusDescription
200 OK.
application/json UsageTopResponse
Fields of UsageTopResponse
currencyrequired string
rowsrequired array of UsageCell
seriesrequired array of SeriesMeta
default Error.
application/json ApiError

Doc corpora

get/api/docs/chunks

List a document's chunks

Capability admin, open to: owner

One document's chunks, verbatim payload included, for the corpus browser's leaf view.

Parameters

NameInDescription
document_idrequiredquery integer (int64)

Responses

StatusDescription
200 OK.
application/json ChunksResponse
Fields of ChunksResponse
chunksrequired array of ChunkRow
default Error.
application/json ApiError
get/api/docs/corpora

List doc corpora

Capability admin, open to: owner

Every doc corpus with its badges and sources, plus the pending doc-request count and the resolved rerank model.

Responses

StatusDescription
200 OK.
application/json DocsOverview
Fields of DocsOverview
corporarequired array of CorpusView
pending_requestsrequired integer (uint64) Pending docs__request rows — the tab badge.
rerank_modelrequired string | null Alias the rerank stage would call; null when there is none.
schema_versionrequired integer (int64)
default Error.
application/json ApiError
post/api/docs/corpora

Create a doc corpus

Capability admin, open to: owner. Changes state.

Creates a corpus, resolving and pinning its embed and ingest models before the row exists. start: true queues the ingest job immediately.

Request body required

application/json: object

embed_modelrequired string Model alias to embed with. Probed now, and the *resolved* identity is
what the corpus pins.
ingest_modelrequired string Model alias that will drive extraction. Validated now so the wizard
fails at the form rather than in the job.
libraryrequired string
sources array of NewSource
start boolean Queue the ingest job immediately. Default false.
versionrequired string

Responses

StatusDescription
200 OK.
application/json CorpusCreated
Fields of CorpusCreated
corpusrequired CorpusView
job_idrequired integer | null The ingest job queued with the corpus; null when start was not
asked for (the corpus is then empty until an ingest is started).
okrequired boolean Always true; a refusal is an error answer instead.
default Error.
application/json ApiError
get/api/docs/corpora/{id}

Get a corpus

Capability admin, open to: owner

One corpus's row, documents, golden queries and eval history (limit caps the eval history; 0 or absent is the whole run). 404 not_found for a corpus id nothing has.

Parameters

NameInDescription
idrequiredpath integer
limitquery integer | null

Responses

StatusDescription
200 OK.
application/json CorpusDetail
Fields of CorpusDetail
corpusrequired CorpusView
documentsrequired array of DocumentRow
eval_runsrequired array of EvalRunRow
golden_queriesrequired array of GoldenQueryRow
default Error.
application/json ApiError
post/api/docs/corpora/{id}/delete

Delete a corpus

Capability admin, open to: owner. Changes state.

Deletes a corpus and everything ingested into it. 404 not_found for a corpus id nothing has.

Parameters

NameInDescription
idrequiredpath integer

Responses

StatusDescription
200 OK.
application/json MessageAck
Fields of MessageAck
messagerequired string What was done, for a person to read.
okrequired boolean Always true; a failure is an error answer instead.
default Error.
application/json ApiError
get/api/docs/corpora/{id}/documents

List a corpus's documents

Capability admin, open to: owner

Every document crawled into this corpus. 404 not_found for a corpus id nothing has.

Parameters

NameInDescription
idrequiredpath integer

Responses

StatusDescription
200 OK.
application/json DocumentsResponse
Fields of DocumentsResponse
documentsrequired array of DocumentRow
default Error.
application/json ApiError
post/api/docs/corpora/{id}/ingest

Start an ingest job

Capability admin, open to: owner. Changes state.

Queues (or reports already-running) the ingest job for this corpus's configured sources. 404 not_found for a corpus id nothing has.

Parameters

NameInDescription
idrequiredpath integer

Responses

StatusDescription
200 OK.
application/json DocsJobStarted
Fields of DocsJobStarted
already_runningrequired boolean true when a job of that kind for the corpus was already in flight:
job_id is that one's.
job_idrequired integer (int64)
okrequired boolean Always true; a refusal is an error answer instead.
default Error.
application/json ApiError
post/api/docs/corpora/{id}/re-embed

Start a re-embed job

Capability admin, open to: owner. Changes state.

Queues (or reports already-running) a re-embed job: fills in missing vectors, or moves the pin onto a new embed_model. 404 not_found for a corpus id nothing has.

Parameters

NameInDescription
idrequiredpath integer

Request body required

application/json: object

embed_model string | null Move the pin onto this alias. Omitted only fills in missing vectors. Default null.

Responses

StatusDescription
200 OK.
application/json DocsJobStarted
Fields of DocsJobStarted
already_runningrequired boolean true when a job of that kind for the corpus was already in flight:
job_id is that one's.
job_idrequired integer (int64)
okrequired boolean Always true; a refusal is an error answer instead.
default Error.
application/json ApiError
get/api/docs/eval

List eval runs

Capability admin, open to: owner

One corpus's eval-run history, most recent first (limit caps it; 0 or absent is the whole history — a score is read as a trend). 404 not_found for a corpus id nothing has.

Parameters

NameInDescription
corpus_idrequiredquery integer (int64)
limitquery integer | null

Responses

StatusDescription
200 OK.
application/json EvalHistory
Fields of EvalHistory
eval_runsrequired array of EvalRunRow
default Error.
application/json ApiError
post/api/docs/eval

Start an eval run

Capability admin, open to: owner. Changes state.

Queues (or reports already-running) an eval run over the corpus's golden queries at the given hit@k depth. 404 not_found for a corpus id nothing has.

Request body required

application/json: object

corpus_idrequired integer (int64)
k integer | null hit@k depth; absent takes the configured default. Default null.
params any Stage overrides to measure under; absent measures under the defaults
docs__query itself runs with. Default null.

Responses

StatusDescription
200 OK.
application/json DocsJobStarted
Fields of DocsJobStarted
already_runningrequired boolean true when a job of that kind for the corpus was already in flight:
job_id is that one's.
job_idrequired integer (int64)
okrequired boolean Always true; a refusal is an error answer instead.
default Error.
application/json ApiError
get/api/docs/export

Export corpora as a SQLite file

Capability admin, open to: owner

The corpus store as a plain SQLite file — one corpus with ?corpus_id=, or the whole file. The file can be copied to another machine as is. 404 not_found for a corpus id nothing has.

Parameters

NameInDescription
corpus_idquery integer | null

Responses

StatusDescription
200 OK.
application/vnd.sqlite3 string (binary)
default Error.
application/json ApiError
get/api/docs/export/manifest

Preview a corpus export's manifest

Capability admin, open to: owner

What a GET /api/docs/export download would contain, without transferring the file — the half a UI shows before committing, and the half an import re-derives to check against. 404 not_found for a corpus id nothing has.

Parameters

NameInDescription
corpus_idquery integer | null

Responses

StatusDescription
200 OK.
application/json ExportManifest
Fields of ExportManifest
byte_sizerequired integer (uint64)
corporarequired array of ManifestCorpus
exported_atrequired string
schema_versionrequired integer (int64)
default Error.
application/json ApiError
get/api/docs/golden

List golden queries

Capability admin, open to: owner

One corpus's golden queries — the hand- or candidate-curated set its eval runs are scored against. 404 not_found for a corpus id nothing has.

Parameters

NameInDescription
corpus_idrequiredquery integer (int64)
limitquery integer | null

Responses

StatusDescription
200 OK.
application/json GoldenResponse
Fields of GoldenResponse
golden_queriesrequired array of GoldenQueryRow
default Error.
application/json ApiError
post/api/docs/golden

Create or edit a golden query

Capability admin, open to: owner. Changes state.

Creates or edits (id present) a golden query. Expected chunk ids are validated against the corpus before they are stored. 404 not_found for a corpus id nothing has.

Request body required

application/json: object

corpus_id integer | null Default null.
expected_chunk_ids array of string Default [].
id integer | null Present = edit that query; absent = create one. Default null.
origin string | null manual (default) or synthetic — a curated candidate keeps saying
where it came from. Default null.
queryrequired string

Responses

StatusDescription
200 OK.
application/json GoldenSaved
Fields of GoldenSaved
idrequired integer (int64) The golden query's id: the edited one, or the one just created.
okrequired boolean Always true; a failure is an error answer instead.
default Error.
application/json ApiError
get/api/docs/golden/candidates

List golden-query candidates

Capability admin, open to: owner

The synthetic golden-query curation queue, with the chunks each candidate was written from alongside it. status is pending, accepted or rejected (empty for all), anything else is a 400. 404 not_found for a corpus id nothing has.

Parameters

NameInDescription
corpus_idrequiredquery integer (int64)
statusquery string | null

Responses

StatusDescription
200 OK.
application/json GoldenCandidatesResponse
Fields of GoldenCandidatesResponse
candidatesrequired array of GoldenCandidateRow
chunksrequired object
default Error.
application/json ApiError
post/api/docs/golden/candidates/{id}/accept

Accept a golden-query candidate

Capability admin, open to: owner. Changes state.

Promotes a candidate to a real golden query, keeping origin: synthetic. A decision is made once — a candidate not pending is refused.

Parameters

NameInDescription
idrequiredpath integer

Request body required

application/json: object

expected_chunk_ids array | null The expectation as edited before accepting; absent keeps the chunk the
candidate was written from. Default null.
query string | null The query as edited before accepting; absent accepts it as proposed. Default null.

Responses

StatusDescription
200 OK.
application/json GoldenSaved
Fields of GoldenSaved
idrequired integer (int64) The golden query's id: the edited one, or the one just created.
okrequired boolean Always true; a failure is an error answer instead.
default Error.
application/json ApiError
post/api/docs/golden/candidates/{id}/reject

Reject a golden-query candidate

Capability admin, open to: owner. Changes state.

Discards a candidate; the row stays rejected rather than being deleted, so a later generation run does not propose the same question again.

Parameters

NameInDescription
idrequiredpath integer

Responses

StatusDescription
200 OK.
application/json Ack
Fields of Ack
okrequired boolean Always true; a failure is an error answer instead.
default Error.
application/json ApiError
post/api/docs/golden/generate

Generate golden-query candidates

Capability admin, open to: owner. Changes state.

Queues a run that samples chunks and asks the corpus's pinned ingest model to write candidate golden queries from them — the queue is the only path from a candidate to a real golden query. 404 not_found for a corpus id nothing has.

Request body required

application/json: object

corpus_idrequired integer (int64)
per_chunk integer | null Questions to ask for per sampled chunk. Absent means one. Default null.
sample integer | null Chunks to sample. Absent or 0 samples every chunk in the corpus — the
run is as big as the corpus unless a smaller sample is asked for. Default null.

Responses

StatusDescription
200 OK.
application/json DocsJobStarted
Fields of DocsJobStarted
already_runningrequired boolean true when a job of that kind for the corpus was already in flight:
job_id is that one's.
job_idrequired integer (int64)
okrequired boolean Always true; a refusal is an error answer instead.
default Error.
application/json ApiError
post/api/docs/golden/{id}/delete

Delete a golden query

Capability admin, open to: owner. Changes state.

Deletes one golden query.

Parameters

NameInDescription
idrequiredpath integer

Responses

StatusDescription
200 OK.
application/json Ack
Fields of Ack
okrequired boolean Always true; a failure is an error answer instead.
default Error.
application/json ApiError
post/api/docs/import

Import corpora from a SQLite file

Capability admin, open to: owner. Changes state.

Imports a corpus SQLite file (from GET /api/docs/export). validate_only runs every check and writes nothing; replace overwrites an existing library@version. Both checks happen before anything is written.

Parameters

NameInDescription
replacequery boolean
validate_onlyquery boolean

Request body required

application/vnd.sqlite3: string (binary)

Responses

StatusDescription
200 OK.
application/json ImportReport
Fields of ImportReport
dry_runrequired boolean
file_schema_versionrequired integer (int64)
importedrequired array of ImportedCorpus
schema_versionrequired integer (int64)
default Error.
application/json ApiError
get/api/docs/requests

List doc requests

Capability admin, open to: owner

The doc-request queue: libraries an agent asked for that this gateway has no corpus for yet. status is pending, fulfilled or dismissed (empty for all), anything else is a 400.

Parameters

NameInDescription
statusquery string | null

Responses

StatusDescription
200 OK.
application/json DocRequestsResponse
Fields of DocRequestsResponse
requestsrequired array of DocRequestRow
default Error.
application/json ApiError
post/api/docs/requests/{id}/status

Set a doc request's status

Capability admin, open to: owner. Changes state.

Dismisses a doc request, or puts a dismissed one back to pending. fulfilled is set only by a matching ingest completing, never by hand.

Parameters

NameInDescription
idrequiredpath integer

Request body required

application/json: object

statusrequired string dismissed to clear it, pending to put it back.

Responses

StatusDescription
200 OK.
application/json Ack
Fields of Ack
okrequired boolean Always true; a failure is an error answer instead.
default Error.
application/json ApiError
post/api/docs/search

Search a corpus

Capability admin, open to: owner

Runs a retrieval search against one corpus with the same stage pipeline docs__query uses, answering both the trace and the rendered markdown a client would receive. 404 not_found for a corpus id nothing has. (A corpus named by library@version that does not exist is a 404 too.)

Request body required

application/json: object

budget_tokens integer | null Convenience override, same precedence as the MCP tool's. Default null.
corpus string | null Default null.
corpus_id integer | null Either the numeric row id or library@version. Default null.
params any Partial overrides of the search stage settings; anything absent keeps
the configured default. Default null.
queryrequired string

Responses

StatusDescription
200 OK.
application/json DocsSearchResponse
Fields of DocsSearchResponse
corpus_idrequired string
hitsrequired array of SearchHit
markdownrequired string
statusrequired CorpusStatusView
tracerequired SearchTraceView
urlsrequired object Chunk id → source document URL, for the deep links.
default Error.
application/json ApiError

Knowledge bases

Named collections of your own documents: create a base, upload files, follow the background job that reads and embeds them, view a file's text and search across bases. Uploading and changing a base's model or chunk size start jobs (kinds kb_ingest and kb_reembed, key kb:<id>) that answer at once; watch them on the jobs routes and the event stream.

get/api/knowledge/bases

List knowledge bases

Capability admin, open to: owner

Every base with its counts, its pinned embedding model, whether that model still resolves on this gateway, the live job (or the last one that ran) and notes: one sentence each on what needs attention (files waiting with no job running, chunks without a vector, a chunk size above what the embedding model takes).

Responses

StatusDescription
200 OK.
application/json KnowledgeBaseList
Fields of KnowledgeBaseList
basesrequired array of KnowledgeBase
default Error.
application/json ApiError
post/api/knowledge/bases

Create a knowledge base

Capability admin, open to: owner. Changes state.

Creates an empty base and pins it to the embedding model embed_alias resolves to; the alias is probed once to learn the vector length, so the model must be reachable. The pin outlives the alias: a different model is a settings change that re-embeds. Chunk size defaults to 512 tokens with 64 overlap. 400 op_failed names the reason: an empty name, a name already used, an alias that is not an embedding (or rerank, or vision) model, a chunk size above what the embedding model takes per input, or an unreachable model.

Request body required

application/json: object

chunk_overlap integer | null Overlap between chunks in tokens; 64 when absent. Default null.
chunk_tokens integer | null Chunk size in tokens; 512 when absent. Default null.
description string | null Default null.
embed_aliasrequired string The embedding model alias. The base is pinned to the model it
resolves to; the alias is probed once to learn the vector length.
mcp_visible boolean | null Whether the kb__* tools on /mcp may search the base; true when
absent. Default null.
namerequired string Unique across the bases.
rerank_alias string | null A rerank model alias; none: no rerank stage. Default null.
vision_alias string | null A vision model alias that reads text-less PDF pages; none: they are
skipped and counted. Default null.

Responses

StatusDescription
200 OK.
application/json KnowledgeBase
Fields of KnowledgeBase
chunk_overlaprequired integer (int64)
chunk_tokensrequired integer (int64)
countsrequired KnowledgeCounts
created_atrequired string
descriptionrequired string
embed_aliasrequired string The embedding model alias the base was created with.
embed_contextrequired integer | null The embedding model's context in tokens, when the gateway knows it.
embed_dimsrequired integer (int64) The vector length of the pinned model.
embed_identityrequired string upstream/model (Nd): the pin as one line.
embed_input_limitrequired integer | null What one embedding input may hold, min(context, ubatch) for a local
model; chunk_tokens (heading path included) is checked against it.
embed_input_limit_sourcerequired string One sentence: where embed_input_limit comes from.
embed_modelrequired string The embedding model the base is pinned to.
embed_resolvablerequired boolean Whether a model on this gateway still resolves to the pin. When not,
searches fall back to keywords and new files cannot be embedded.
embed_tokenizerrequired string What counts the tokens: model, tiktoken or tiktoken_guess.
embed_upstreamrequired string The upstream the alias resolved to when the base was pinned.
idrequired integer (int64)
jobrequired JobRow | null The live job on the base, or the last one that ran.
mcp_visiblerequired boolean Whether the kb__* tools on /mcp may search this base.
namerequired string Unique across the bases.
notesrequired array of string One sentence each: what a person should know about the base now.
rerank_aliasrequired string Empty: no rerank stage.
resident_bytesrequired integer (int64) What the base's vectors cost resident in memory: embedded chunks x
dimensions x 2.
statusrequired string ready or re_embed_required (the vectors no longer match the pinned
model; Resume fills them in). One of ready, re_embed_required.
updated_atrequired string
vectors_revrequired integer (int64) Moves on every chunk write.
vision_aliasrequired string Empty: text-less PDF pages are skipped and counted.
default Error.
application/json ApiError
get/api/knowledge/bases/{id}

Get a knowledge base

Capability admin, open to: owner

One base, as in the list, and its files. 400 op_failed for a base that does not exist.

Parameters

NameInDescription
idrequiredpath integer

Responses

StatusDescription
200 OK.
application/json KnowledgeBaseDetail
Fields of KnowledgeBaseDetail
baserequired KnowledgeBase
filesrequired array of KnowledgeFile
default Error.
application/json ApiError
post/api/knowledge/bases/{id}/cancel

Cancel a base's running job

Capability admin, open to: owner. Changes state.

Asks the base's running ingest or re-embed to stop; the job finishes its current step and ends as canceled. Files not yet read stay pending, vectors already written stay, and Resume continues from there. 400 op_failed when no job is running on the base.

Parameters

NameInDescription
idrequiredpath integer

Responses

StatusDescription
200 OK.
application/json CancelResult
Fields of CancelResult
jobrequired integer (int64) The job that was asked to stop.
messagerequired string
default Error.
application/json ApiError
post/api/knowledge/bases/{id}/delete

Delete a knowledge base

Capability admin, open to: owner. Changes state.

Deletes the base with its files, chunks and vectors, and the stored originals nothing else uses. A job running on the base is cancelled first. Threads that referenced the base keep their stored citations; they lose the base from later retrievals.

Parameters

NameInDescription
idrequiredpath integer

Responses

StatusDescription
200 OK.
application/json KnowledgeBaseDeleted
Fields of KnowledgeBaseDeleted
chunksrequired integer (int64) Chunks the base held.
deletedrequired integer (int64)
filesrequired integer (int64) Files the base held.
namerequired string
default Error.
application/json ApiError
get/api/knowledge/bases/{id}/files

List a base's files

Capability admin, open to: owner

The files of the base, with their ingest status (pending, ingesting, ready, failed), chunk counts and, for a failed one, the reason.

Parameters

NameInDescription
idrequiredpath integer

Responses

StatusDescription
200 OK.
application/json KnowledgeFileList
Fields of KnowledgeFileList
filesrequired array of KnowledgeFile
default Error.
application/json ApiError
post/api/knowledge/bases/{id}/files

Upload files into a base

Capability admin, open to: owner. Changes state.

multipart/form-data, one part per file (the part's file name is the stored name, reduced to its last path component). The whole request is bounded by the max_body_mb setting (0 is unbounded): 413 body_limit naming it, for a declared or a streamed body. Each file's kind is sniffed from its bytes, never its name: images and audio are refused, as is an empty file. The answer has one item per part: added, replaced (the name existed with other bytes, or its ingest had failed; the file is queued again), unchanged (same name, same bytes), duplicate (same bytes under another name) or refused with the reason. A refused file does not fail the request. Added and replaced files are queued and the ingest job is started or joined: job is its id (null when nothing was queued). Ingestion — reading, chunking, embedding, a vision model for text-less PDF pages — runs in that job; observe it as for Resume. 400 no_files for a request without any part, 400 bad_request for a malformed multipart body.

Parameters

NameInDescription
idrequiredpath integer

Request body required

multipart/form-data: KnowledgeUploadRequest

Fields of KnowledgeUploadRequest
file string (binary) One file; send as many parts as there are files. The part's field name does not matter, its file name names the file.

Responses

StatusDescription
200 OK.
application/json UploadResult
Fields of UploadResult
itemsrequired array of UploadItem One per part, in order.
jobrequired integer | null The ingest job the upload started or joined; null when nothing was
queued.
default Error.
application/json ApiError
post/api/knowledge/bases/{id}/resume

Resume a base's pending work

Capability admin, open to: owner. Changes state.

Starts the one job the base needs, or joins the one already running: a re-embed (kb_reembed) when chunks lack a vector or the base is marked re_embed_required, otherwise an ingest (kb_ingest) of the pending files. The route only starts the job and answers at once with its id in job; measuring the stored chunks against the model, re-chunking what does not fit and embedding all run in the job. When the last re-embed was refused as larger than the model's input, the files holding the oversized chunks are marked pending and an ingest (kb_ingest) re-chunks them instead: kind is kb_ingest, and rechunk says why. A base with nothing waiting answers job: null and a message. Observe progress with the job: GET /api/jobs lists it (key kb:{id}), the jobs frames of GET /api/events stream it, and the base's own job field keeps the last outcome. A file that failed is not retried here; re-ingest it.

Parameters

NameInDescription
idrequiredpath integer

Responses

StatusDescription
200 OK.
application/json ResumeResult
Fields of ResumeResult
already_running boolean Present when Resume joined a running job (true) or started the
plain ingest of the pending files (false); absent for a re-embed or
re-chunk it started.
jobrequired integer | null The job now running (or already running); null when the base has
nothing waiting.
kind string kb_ingest or kb_reembed; absent when no job was started.
message string
rechunk string Present when the files holding oversized chunks are re-chunked first:
why.
default Error.
application/json ApiError
post/api/knowledge/bases/{id}/settings

Change a base's settings

Capability admin, open to: owner. Changes state.

Every field is optional; an empty rerank_alias or vision_alias clears it. A different embed_alias re-pins the base and starts a re-embed job (reembed_job); a changed chunk_tokens or chunk_overlap sends every file back to pending (rechunk_files) and starts an ingest job (ingest_job). Both are background jobs: search keeps serving the old chunks until the new ones are in. A model or chunk-size change while a job runs on the base is refused (400 op_failed naming the job): wait for it or cancel it first. Other refusals as for create.

Parameters

NameInDescription
idrequiredpath integer

Request body required

application/json: object

chunk_overlap integer | null Default null.
chunk_tokens integer | null A change re-chunks every file (a background job). Default null.
description string | null Default null.
embed_alias string | null A different model re-pins the base and re-embeds every chunk (a
background job). Default null.
mcp_visible boolean | null Default null.
name string | null Default null.
rerank_alias string | null Default null.
vision_alias string | null Default null.

Responses

StatusDescription
200 OK.
application/json KnowledgeBaseEdited
Fields of KnowledgeBaseEdited
ingest_jobrequired integer | null The re-ingest a chunk-size change started.
kbrequired KnowledgeBase
rechunk_filesrequired integer (uint64) Files a chunk-size change sent back to pending. A model change
decides inside its job which files to re-chunk; the job's stage and
detail say which.
reembed_jobrequired integer | null The re-embed a model change started.
default Error.
application/json ApiError
post/api/knowledge/files/{id}/delete

Delete a file

Capability admin, open to: owner. Changes state.

Deletes the file with its chunks and vectors, and its stored original unless another file shares the bytes. 400 op_failed for a file being ingested right now (cancel the base's job first) or one that does not exist.

Parameters

NameInDescription
idrequiredpath integer

Responses

StatusDescription
200 OK.
application/json KnowledgeFileDeleted
Fields of KnowledgeFileDeleted
chunksrequired integer (int64) Chunks the file held.
deletedrequired integer (int64)
namerequired string
default Error.
application/json ApiError
get/api/knowledge/files/{id}/original

Download a file's original

Capability admin, open to: owner

The uploaded bytes, with the media type they were sniffed as and Content-Disposition: attachment under the file's name (an ASCII fallback plus the RFC 5987 filename*). 404 not_found for a file that does not exist or whose original is gone from disk.

Parameters

NameInDescription
idrequiredpath integer

Responses

StatusDescription
200 OK.
*/* string (binary)
default Error.
application/json ApiError
post/api/knowledge/files/{id}/reingest

Ingest a file again

Capability admin, open to: owner. Changes state.

Marks the file pending and starts (or joins) the base's ingest job, whose id is job. Use it after the base gained a vision model, or for a failed file whose cause is fixed. The file's earlier chunks stay searchable until the new ones are in. 400 op_failed for a file being ingested right now.

Parameters

NameInDescription
idrequiredpath integer

Responses

StatusDescription
200 OK.
application/json KnowledgeFileRequeued
Fields of KnowledgeFileRequeued
filerequired integer (int64)
jobrequired integer | null The ingest job that will read it, started or joined.
default Error.
application/json ApiError
get/api/knowledge/files/{id}/text

Read a file's extracted text

Capability admin, open to: owner

The source viewer: the file's extracted text (null until it has been ingested once), every chunk's byte range in that text, and the chunk named by chunk as highlight. A citation whose chunk id a later re-ingest renamed is found again by the span_start, span_end and sha the citation stored, and notice says so (or that the file changed since). 400 op_failed for a file that does not exist.

Parameters

NameInDescription
idrequiredpath integer
chunkquery string | null
shaquery string | null
span_endquery integer | null
span_startquery integer | null

Responses

StatusDescription
200 OK.
application/json KnowledgeSource
Fields of KnowledgeSource
chunksrequired array of ChunkSpan Every chunk's span, in file order.
filerequired KnowledgeFile
highlightrequired ChunkSpan | null The cited chunk (or the one found by the citation's position).
kb_namerequired string
notice string Said when the highlight is not the cited chunk itself: it was found by
the citation's stored position because the chunk id no longer exists.
textrequired string | null The extracted text; null until the file has been ingested once.
default Error.
application/json ApiError
post/api/knowledge/search

Search knowledge bases

Capability admin, open to: owner

The search playground: hybrid keyword and vector search with fusion and, where the base names a reranker, reranking, over the bases in kb_ids (none given: every base, whether or not it is visible to the kb__* tools). The answer has the excerpts with their scores and positions, notes for what was not searched or not fully (a base still ingesting, chunks without a vector, a model that no longer resolves), and traces, one per embedding and rerank model pair, with what each stage saw and how long it took. budget_tokens bounds the excerpts' token total; params overrides the search stages. Searching embeds the query, which costs a model call. A search that cannot use a model says so in notes instead of failing. 400 op_failed for an unknown params key.

Request body required

application/json: object

budget_tokens integer | null Token budget for the excerpts; 0 or absent: none (the search's own
limit decides). Default null.
kb_ids array of integer (int64) The bases to search; omitted or empty searches every base. Default [].
params object | null Stage overrides on top of the configured search defaults. Any subset of
the keys below; an unknown key is a 400 op_failed naming the valid ones. Default null.
budget_tokens integer | null Token budget.
fts_weights object BM25 column weights: payload, heading_path, derived_title, derived_summary.
k_fts integer Candidates from keyword search.
k_rerank integer How many fused candidates the reranker scores.
k_vec integer Candidates from vector search.
limit integer Excerpts returned at most.
rerank boolean Whether the rerank stage runs.
rrf_k number Reciprocal-rank-fusion constant.
queryrequired string

Responses

StatusDescription
200 OK.
application/json KnowledgeSearchResult
Fields of KnowledgeSearchResult
droppedrequired integer (uint) Excerpts that ranked but did not fit the budget.
excerptsrequired array of KnowledgeExcerpt
msrequired number (double) How long the search took.
notesrequired array of string Why something was not searched, or not fully; one sentence each.
searchedrequired array of string The bases that were searched, by name.
tokensrequired integer (uint) Tokens the excerpts use.
tracesrequired array of SearchTraceView One per search (per embedding and rerank model pair): what each stage
saw.
default Error.
application/json ApiError

Audio lab

The dashboard's audio playground: the audio models and their voices, the library of reference clips a voice-cloning model reads (upload, preview, transcripts, delete), and the synthesis, transcription, alignment and generic-task routes that run a request through the same handlers as /v1/audio/* and /v1/tasks/*.

post/audio-lab/api/alignments

Align audio to text

Capability admin, open to: owner

POST /v1/audio/alignments, dispatched in the gateway (see /audio-lab/api/speech): forced alignment for a model whose task is align, multipart upload only. The body size is not limited. With group=<id> (a group POST /audio-lab/api/groups made for this route) the call is kept in the lab store as that group's run: the request as sent (an upload as a summary, its files the group's input artifacts; a part without a filename is a text field only when it has no type of its own but text and is UTF-8), and the answer as it streams to the client, recorded before its last byte arrives. Speech that succeeded is an output artifact, written to its file as it streams; a task's base64 audio (audio, named_audio_outputs[].audio, an event's audio) is an output artifact each, lab-artifact:<id> in its place in the kept text; any other answer is its text. A client that stops reading leaves the run as far as it got, error code stopped; one that goes while the run is being written does not take it. The group is in flight from the claim to the run. A group that is not the Audio lab's is a 404, one made for another route a 400 wrong_route, a request naming another model than the group's (or none) a 400 wrong_model naming both, one answered or being answered a 409 cell_answered, each before anything is sent. Every failure is the /v1 route's OpenAI envelope, relayed as it came.

Parameters

NameInDescription
groupquery integer | null

Request body required

multipart/form-data: AudioAlignmentsRequest

Fields of AudioAlignmentsRequest
filerequired string (binary)
language string
modelrequired string
textrequired string

Responses

StatusDescription
200 OK.
application/json AudioAlignment
Fields of AudioAlignment
language string | null The language as the model reported it (en, de; the model's own
spelling). Absent when the model says none.

A model may report the language it assumes rather than the one it was
asked to align in: CrisperWhisper's aligner answers its default, en,
to any language (checked 2026-10-22 with de, german and none).
sample_rate integer | null The rate, in Hz, the start_sample and end_sample of the words
count in: the model's own figure when its answer states one, else
derived from the words' seconds and samples (they are what the
samples count in, even where the engine resampled the clip), else the
uploaded WAV's header. Absent when none of the three works; the
seconds are always there.
textrequired string The transcript as the client submitted it (the multipart text
field), not what the model echoes. char_start and char_end of the
words index into this string.
timing AudioTiming | null How long the engine took, as it reports it (audio.cpp's timing
object, which both aligners send). Absent when the answer has none.
wordsrequired array of AlignedWord The words in the order the model answered them, which is the
transcript's order.
default Error.
application/json OpenAiError
post/audio-lab/api/groups

Keep a group for a hand-off

Capability admin, open to: owner. Changes state.

Makes a kept group of one cell in the Audio lab's history, before its request is sent: the model, the route it asks and the page's whole form (every panel, the speech settings, the PCM format a stream is assembled with), so a re-opened group puts the form back as it was. Answers the group with no run; the request goes to that route's hand-off with group=<id>, which records it as the run, so the hand-off's body stays the /v1 route's own. 400 for a blank model, 422 for a body that is not an AudioAsk (both answered {error}), 500 when the store cannot keep it. The body size is not limited.

Request body required

application/json: object

formrequired AudioLabForm
modelrequired string The alias the request names.
routerequired AudioRoute

Responses

StatusDescription
200 OK.
application/json LabGroupView
Fields of LabGroupView
artifactsrequired array of LabArtifactView The group's inputs, in order.
created_atrequired string
formrequired any The lab's form as the lab held it (the Decision lab's
DecisionForm), with its media as the group's input artifacts.
idrequired integer (int64)
in_flightrequired boolean A cell of it is being answered now: its request is out and its run
not in yet. A group with no run that is not in flight was stopped.
Deleting a group in flight is the 409 in_flight.
itemrequired LabBatchItem | null The set run it is an item of; null for a group of the history.
labrequired LabKind
overriderequired string | null The request override, as typed (its image data URLs as
lab-artifact:<id>), when one was in effect.
planrequired array of LabCell The cells, in run order. A group with fewer runs than cells was
stopped.
runsrequired array of LabRunView The runs so far, in cell order.
titlerequired string Derived once from the form: the state's first line, a prompt.
default Error.
application/json LabError
get/audio-lab/api/models

List the audio models

Capability admin, open to: owner

The enabled audio models with what a form needs to shape itself: task decides text-to-speech, speech-to-text or another audio.cpp task, mode whether streaming is offered. GET /v1/models flattens every upstream to a few fields and cannot say this. The audio containers' state rides along so a client can say "not running" before a request fails, as does where the voice library lives (voices_dir on the host, container_voices_dir in the container) and whether the audio class's voice directory is that library.

Responses

StatusDescription
200 OK.
application/json AudioLabModels
Fields of AudioLabModels
container_voices_dirrequired string The same directory as the model container sees it: what goes into a
request's voice_ref.
modelsrequired array of AudioLabModel The enabled audio models.
runtimerequired array of RuntimeStatus One row per running or starting audio container, so a client can say
"not running" before a request fails. Matched to a model by model_id.
voice_library_activerequired boolean Whether the audio class's voice directory is this library. When it is,
a clip's name (without extension) is also a voice every text-to-speech
model answers to; when not, a clip is only a voice_ref path.
voices_dirrequired string | null The voice library's directory on the gateway's host; null while no
audio models directory is set.
default Error.
application/json LabError
get/audio-lab/api/refs

List the voice library

Capability admin, open to: owner

The reference clips stored in the voice library (the voices folder of the audio models directory), by file name, each with the path the model container sees (server_path: what a request's voice_ref takes), the voice name it answers to once the audio class's voice directory is this library, and its transcript. Without an audio models directory the answer is a 200 with no clips and an error saying so.

Responses

StatusDescription
200 OK.
application/json ClipList
Fields of ClipList
clipsrequired array of Clip The library's clips by file name; empty without an audio models
directory.
error string Present, with a 200, when no audio models directory is configured.
default Error.
application/json LabError
post/audio-lab/api/refs

Upload reference clips

Capability admin, open to: owner. Changes state.

Stores one or more clips in the voice library, each written whole or not at all. audio.cpp takes a clone's reference as a path on the server rather than an upload, which is what the library is for: a stored clip reads in the container as /models/voices/<name>. A transcript field with exactly one file is written to the library's transcript index. Otherwise, when the audio settings name a transcription model, each clip is transcribed with it: transcribed has an entry per clip, either who wrote the transcript or why none was written; the upload stands either way. 400 for a bad file name, a malformed body, no file field or an audio models directory that is not configured; 500 when the disk refuses. A gateway started from a development build whose audio models directory is the installed app's refuses the write (400, code dev_shared_models_dir). The body size is not limited.

Request body required

multipart/form-data: AudioLabUploadRequest

Fields of AudioLabUploadRequest
filerequired string (binary) A clip; send as many file parts as there are clips. A part's file name names the clip: letters, digits, space, '.', '_' and '-', not starting with '.' (anything else is a 400). A clip with the name of a stored one replaces it.
transcript string What the clip says. Applied only when the upload holds exactly one file; blank is ignored.

Responses

StatusDescription
200 OK.
application/json ClipsUploaded
Fields of ClipsUploaded
clipsrequired array of Clip The library after the upload.
savedrequired array of string The file names stored, in upload order.
transcribedrequired array of ClipTranscription One entry per stored clip when no transcript was typed for it and the
audio settings name a transcription model; empty otherwise.
default Error.
application/json LabError
get/audio-lab/api/refs/{name}

Read a reference clip

Capability admin, open to: owner

The stored clip's bytes, with the content type its extension implies, for a player, and Accept-Ranges: bytes. One Range (bytes=a-b, bytes=a- or bytes=-n) answers 206 with Content-Range; the answer carries an ETag made from the file (inode, length, modification time) and X-Content-Type-Options: nosniff and Content-Security-Policy: sandbox; If-Range with that ETag applies the range, any other If-Range serves the whole clip, and so does a Range lmgw does not read; a Range on an empty clip serves it whole (200); 416 range_not_satisfiable (Content-Range: bytes */size, a {code, message} body) for a range that names no byte of it. 400 "invalid clip" for a name that is not a plain file name, 404 for a clip that is not there; both answer {error}.

Parameters

NameInDescription
namerequiredpath string

Responses

StatusDescription
200 OK.
application/octet-stream string (binary)
audio/aac string (binary)
audio/flac string (binary)
audio/mpeg string (binary)
audio/ogg string (binary)
audio/wav string (binary)
default Error.
application/json LabError
post/audio-lab/api/refs/{name}/delete

Delete a reference clip

Capability admin, open to: owner. Changes state.

Deletes the clip and its transcript line; a transcript left behind would attach itself to the next clip uploaded under the name. Answers the library after the change. 400 "invalid clip" for a name that is not a plain file name; 500 when the file cannot be removed (a clip that is not there included). A development gateway whose audio models directory is the installed app's refuses (400, code dev_shared_models_dir).

Parameters

NameInDescription
namerequiredpath string

Responses

StatusDescription
200 OK.
application/json ClipsAck
Fields of ClipsAck
clipsrequired array of Clip The library after the change.
okrequired boolean Always true; a refusal is an error answer instead.
default Error.
application/json LabError
post/audio-lab/api/refs/{name}/text

Set a clip's transcript

Capability admin, open to: owner. Changes state.

Sets, or with an empty string drops, the clip's line in the library's transcript index. This is what makes a library clip a voice and not just a path: when the audio class's voice directory is the library, a request with "voice": "<name>" clones the clip and the engine reads this line as the reference text the caller did not send. A cloning model without one reads the target text in an unconditioned voice. 404 for a clip that is not there; 400 "invalid clip" for a bad name; 422 when the body is not JSON of the shape {transcript: string} (answered {error} with the reason). A development gateway whose audio models directory is the installed app's refuses (400, code dev_shared_models_dir).

Parameters

NameInDescription
namerequiredpath string

Request body required

application/json: object

transcript string The clip's transcript. A newline is stored as a space; empty drops the
clip's transcript. Default "".

Responses

StatusDescription
200 OK.
application/json ClipsAck
Fields of ClipsAck
clipsrequired array of Clip The library after the change.
okrequired boolean Always true; a refusal is an error answer instead.
default Error.
application/json LabError
post/audio-lab/api/refs/{name}/transcribe

Transcribe a reference clip

Capability admin, open to: owner. Changes state.

Has a speech-to-text model write the clip's transcript, replacing one it had. The body is optional; one whose alias is not a string is a 422 (answered {error} with the reason), not a silent fall back to another model. name is the file name or the voice name. The model is the body's alias, else the audio settings' clip-transcription model; with neither the answer is a 400 saying so. The model may be local or a cloud alias, and a configured fallback answers as for any request when the GPU hold or an outside process keeps the model off the card: transcript_source, answered_by, fallback_reason and message say who wrote it. 400 also when the alias is no speech-to-text model, the clip is unreadable, the model heard no speech, or it failed. Unlike the dashboard's bulk operation (voice_transcribe) this is one clip.

Parameters

NameInDescription
namerequiredpath string

Request body

application/json: object

alias string | null The speech-to-text alias to use. Blank or absent: the audio settings'
transcription model. Default null.

Responses

StatusDescription
200 OK.
application/json ClipTranscribed
Fields of ClipTranscribed
answered_byrequired string | null The fallback alias that answered in place of the one asked, else null.
byrequired string Who wrote it, in a sentence.
cliprequired string The clip as asked (a file name or a voice name).
clipsrequired array of Clip The library after the change.
fallback_reasonrequired string | null Why the fallback answered (hold, external_vram, ...), else null.
messagerequired string A sentence saying who transcribed it, a fallback that answered named
as one.
okrequired boolean Always true; a refusal is an error answer instead.
transcriptrequired string The transcript recorded: one line, replacing the clip's earlier one.
transcript_sourcerequired string asr:<model>: the model the transcript came from. When a fallback
answered, that model's name.
default Error.
application/json LabError
post/audio-lab/api/speech

Synthesize speech

Capability admin, open to: owner

POST /v1/audio/speech, dispatched in the gateway: the same handler, so alias resolution, the model rewrite, error normalization and logging are the route's own and the call appears in the request log. Only the gateway's key check and the HTTP hop are skipped; the call is the dashboard's and is not budgeted or scoped to a key. The request and the answer are the /v1 route's, relayed verbatim: a WAV or other audio body, or with stream_format an event stream or chunked PCM, and an error in the OpenAI envelope. The body size is not limited. With group=<id> (a group POST /audio-lab/api/groups made for this route) the call is kept in the lab store as that group's run: the request as sent (an upload as a summary, its files the group's input artifacts; a part without a filename is a text field only when it has no type of its own but text and is UTF-8), and the answer as it streams to the client, recorded before its last byte arrives. Speech that succeeded is an output artifact, written to its file as it streams; a task's base64 audio (audio, named_audio_outputs[].audio, an event's audio) is an output artifact each, lab-artifact:<id> in its place in the kept text; any other answer is its text. A client that stops reading leaves the run as far as it got, error code stopped; one that goes while the run is being written does not take it. The group is in flight from the claim to the run. A group that is not the Audio lab's is a 404, one made for another route a 400 wrong_route, a request naming another model than the group's (or none) a 400 wrong_model naming both, one answered or being answered a 409 cell_answered, each before anything is sent. Every failure is the /v1 route's OpenAI envelope, relayed as it came.

Parameters

NameInDescription
groupquery integer | null

Request body required

application/json: AudioSpeechRequest

Fields of AudioSpeechRequest
inputrequired string The text. A local model whose engine refuses a character its package lacks (Supertonic) is sent an equivalent it has in its place, or nothing; the x-lmgw-speech response header names each one. An input left with nothing to say (a lone emoji) is 400 empty_input, refused before any model is started.
instructions string A speaking style, or the description a voice-design model builds its voice from (required there: 400 instructions_required without one, unless the row has a default). Dropped for a model that reads none: capabilities.speech.instructions says which, and the x-lmgw-speech response header says when.
language string An ISO 639-1 code or BCP-47 tag; a local model gets it in its own vocabulary.
modelrequired string
response_format string
speed number
stream_format string Streams PCM16 (with response_format pcm) as speech.audio.delta events (sse) or as raw chunked PCM (audio). A local model streams only when its row runs in streaming mode; an offline row is 400 streaming_unsupported before anything starts (capabilities.speech.streaming says which). The x-lmgw-sample-rate response header states the PCM's rate. One of sse, audio.
voice string A row's own voice preset id, when it defines any (GET /v1/audio/voices). A voice-library clip with no transcript, for a model that cannot clone one without, is 400 voice_needs_transcript before anything starts (lmgw.needs_transcript in the voice list); send reference_text, or transcribe the clip in the dashboard's Audio lab. A local model whose audio.cpp image lacks eSpeak NG is 400 audio_image_lacks_espeak.

Responses

StatusDescription
200 OK.
audio/aac string (binary)
audio/flac string (binary)
audio/mpeg string (binary)
audio/ogg string (binary)
audio/opus string (binary)
audio/pcm string (binary)
audio/wav string (binary)
default Error.
application/json OpenAiError
post/audio-lab/api/tasks/run

Run a generic task

Capability admin, open to: owner

POST /v1/tasks/run, dispatched in the gateway (see /audio-lab/api/speech): audio.cpp's generic task route, the way to reach the tasks with no OpenAI shape. stream=1 sends it to /v1/tasks/stream instead, which a streaming-mode model answers with its buffered event list. The answer is the task's own JSON, relayed. The body size is not limited. With group=<id> (a group POST /audio-lab/api/groups made for this route) the call is kept in the lab store as that group's run: the request as sent (an upload as a summary, its files the group's input artifacts; a part without a filename is a text field only when it has no type of its own but text and is UTF-8), and the answer as it streams to the client, recorded before its last byte arrives. Speech that succeeded is an output artifact, written to its file as it streams; a task's base64 audio (audio, named_audio_outputs[].audio, an event's audio) is an output artifact each, lab-artifact:<id> in its place in the kept text; any other answer is its text. A client that stops reading leaves the run as far as it got, error code stopped; one that goes while the run is being written does not take it. The group is in flight from the claim to the run. A group that is not the Audio lab's is a 404, one made for another route a 400 wrong_route, a request naming another model than the group's (or none) a 400 wrong_model naming both, one answered or being answered a 409 cell_answered, each before anything is sent. Every failure is the /v1 route's OpenAI envelope, relayed as it came.

Parameters

NameInDescription
groupquery integer | null
streamquery string | null

Request body required

application/json: TaskRequest

Fields of TaskRequest
modelrequired string
requestrequired object Relayed to audio.cpp's generic task endpoint untouched; its shape is the task's own and is not modeled here.

Responses

StatusDescription
200 OK.
application/json object
default Error.
application/json OpenAiError
post/audio-lab/api/transcriptions

Transcribe audio

Capability admin, open to: owner

POST /v1/audio/transcriptions, dispatched in the gateway (see /audio-lab/api/speech for what that means), with both of that route's request shapes: a multipart upload, or JSON naming a clip on the model server by path. details=1 sends the request to /v1/audio/transcriptions/details instead, which also answers with the word timings, segments and speaker turns the model produced; the lab is where to find out whether a model produces any. The body size is not limited. With group=<id> (a group POST /audio-lab/api/groups made for this route) the call is kept in the lab store as that group's run: the request as sent (an upload as a summary, its files the group's input artifacts; a part without a filename is a text field only when it has no type of its own but text and is UTF-8), and the answer as it streams to the client, recorded before its last byte arrives. Speech that succeeded is an output artifact, written to its file as it streams; a task's base64 audio (audio, named_audio_outputs[].audio, an event's audio) is an output artifact each, lab-artifact:<id> in its place in the kept text; any other answer is its text. A client that stops reading leaves the run as far as it got, error code stopped; one that goes while the run is being written does not take it. The group is in flight from the claim to the run. A group that is not the Audio lab's is a 404, one made for another route a 400 wrong_route, a request naming another model than the group's (or none) a 400 wrong_model naming both, one answered or being answered a 409 cell_answered, each before anything is sent. Every failure is the /v1 route's OpenAI envelope, relayed as it came.

Parameters

NameInDescription
detailsquery string | null
groupquery integer | null

Request body required

multipart/form-data: AudioTranscriptionsRequest

Fields of AudioTranscriptionsRequest
filerequired string (binary)
language string
modelrequired string
prompt string
response_format string
temperature number

Responses

StatusDescription
200 OK.
application/json
One of 2 shapes
AudioTranscription
Fields of AudioTranscription
textrequired string
AudioTranscriptionDetails
Fields of AudioTranscriptionDetails
segments array of object
speaker_turns array of object
textrequired string
words array of object
default Error.
application/json OpenAiError
get/audio-lab/api/voices

List a model's voices

Capability admin, open to: owner

The voices of a text-to-speech model, for a voice picker, read the moment a model is selected. A local model is answered from the gateway's own catalog (what GET /v1/audio/voices answers by default): its presets, the voices its package ships, the embeddings of its folder and the voice library's clips, each with a kind, the default voice, the shipped voices its package lacks on disk (missing) and held. Nothing is ever started or claimed, so this works while the model is not running and under the GPU hold. When the model's container is already up, the names only its own server reports (a row whose extra_run_args mount another voice directory) are added as engine entries. Under the GPU hold the catalog is still answered with held: true; when the gate would send a request to a fallback alias, fallback names it and its provider is not asked for a list. A remote model is asked. An empty list is normal: the model carries no cached voice ids and wants a reference clip. Failures are /v1/audio/voices' own OpenAI envelope.

Parameters

NameInDescription
modelrequiredquery string

Responses

StatusDescription
200 OK.
application/json LabVoices
Fields of LabVoices
default string What speaks when a request names no voice.
engine_askedrequired boolean Whether a running container was also asked for names the catalog
lacks. Nothing is ever started for it.
fallback string The fallback alias that would answer a request now, when the gate
re-routes this model to one (see held). The list is still the
model's own catalog; the fallback's provider is never asked for it.
heldrequired boolean The GPU hold (or a benchmark, or another program's VRAM) keeps this
model from speaking right now; the list is still answered. A request
now is refused, or answered by fallback.
missingrequired array of string Voices the model's package names but lacks on disk; the Audio
catalog's Download on the package fetches them.
needs_transcriptrequired boolean Whether this model refuses a library clip without a recorded
transcript.
sourcerequired LabVoicesSource Where the list was read: lmgw's catalog, or a remote upstream.
voicesrequired array of LabVoice Every voice name the model answers to, sorted by id.
default Error.
application/json OpenAiError

Image lab

The dashboard's image playground: the models that can draw, and the generate and edit routes that turn a form into a /v1/images/* request and run it through the same handlers.

post/image-lab/api/groups

Keep a generation's form as a group

Capability admin, open to: owner. Changes state.

The dashboard's structured form, checked to build the exact /v1/images/generations body and kept in the lab store as a group of one cell (variant generate), answered with no run yet: nothing is sent. The page then runs it (/image-lab/api/groups/{id}/run), so it holds the group, in flight, before the request goes out. The form's fields are the strings the inputs hold (an empty one says nothing about that setting); everything the OpenAI route does not read goes into sd.cpp's <sd_cpp_extra_args> block appended to the prompt. A form that is no request at all (no prompt, no model, a malformed number, only half of the size, a prompt carrying sd.cpp's own delimiters) is a 400 with code image_lab_form; a store that cannot keep the group a 500 with code lab_store. The body size is not limited.

Request body required

application/json: object

cfg_scale string Default "".
height string Default "".
loras array of ImageLoraRowInput Default [].
model string The public alias — image/<id> for a local row, the alias for a cloud
one. Rewritten to the concrete upstream id by the route itself. Default "".
n string Default "".
negative_prompt string Default "".
output_compression string Default "".
output_format string Default "".
prompt string Default "".
sampler string Default "".
scheduler string Default "".
seed string Blank says nothing (sd-server's own default is a fixed 42); -1 is its
spelling for "random each run". Default "".
steps string Default "".
width string Default "".

Responses

StatusDescription
200 OK.
application/json LabGroupView
Fields of LabGroupView
artifactsrequired array of LabArtifactView The group's inputs, in order.
created_atrequired string
formrequired any The lab's form as the lab held it (the Decision lab's
DecisionForm), with its media as the group's input artifacts.
idrequired integer (int64)
in_flightrequired boolean A cell of it is being answered now: its request is out and its run
not in yet. A group with no run that is not in flight was stopped.
Deleting a group in flight is the 409 in_flight.
itemrequired LabBatchItem | null The set run it is an item of; null for a group of the history.
labrequired LabKind
overriderequired string | null The request override, as typed (its image data URLs as
lab-artifact:<id>), when one was in effect.
planrequired array of LabCell The cells, in run order. A group with fewer runs than cells was
stopped.
runsrequired array of LabRunView The runs so far, in cell order.
titlerequired string Derived once from the form: the state's first line, a prompt.
default Error.
application/json OpenAiError
post/image-lab/api/groups/edit

Keep an edit's form and pictures as a group

Capability admin, open to: owner. Changes state.

As /image-lab/api/groups, for an edit (variant edit): the form and the pictures as parts of one multipart upload (form as JSON, image, optionally mask). The picture and the mask are the group's input artifacts; the form may name kept ones instead of uploading them (image, mask: {id, name}, a picture the store keeps, sent under the kept file's own name). A missing form or picture, a ref the store does not keep, a ref to an artifact that is no picture (its type named), a form that is no edit and a malformed upload are the same 400 as for a generation. Nothing is sent. The body size is not limited.

Request body required

multipart/form-data: ImageLabEditRequest

Fields of ImageLabEditRequest
formrequired string The form as a JSON string: the ImageGenForm the generate route takes as its body, with optionally image and mask naming kept pictures ({id, name}, an artifact the lab store keeps) in place of an upload.
image string (binary) The picture to edit; stands in for the form's image ref. One of the two is required.
mask string (binary) An optional mask.

Responses

StatusDescription
200 OK.
application/json LabGroupView
Fields of LabGroupView
artifactsrequired array of LabArtifactView The group's inputs, in order.
created_atrequired string
formrequired any The lab's form as the lab held it (the Decision lab's
DecisionForm), with its media as the group's input artifacts.
idrequired integer (int64)
in_flightrequired boolean A cell of it is being answered now: its request is out and its run
not in yet. A group with no run that is not in flight was stopped.
Deleting a group in flight is the 409 in_flight.
itemrequired LabBatchItem | null The set run it is an item of; null for a group of the history.
labrequired LabKind
overriderequired string | null The request override, as typed (its image data URLs as
lab-artifact:<id>), when one was in effect.
planrequired array of LabCell The cells, in run order. A group with fewer runs than cells was
stopped.
runsrequired array of LabRunView The runs so far, in cell order.
titlerequired string Derived once from the form: the state's first line, a prompt.
default Error.
application/json OpenAiError
post/image-lab/api/groups/{id}/run

Run a kept group

Capability admin, open to: owner. Changes state.

The group's one cell: claimed (the group is in flight until its run is in), its request built from the stored form (an edit's multipart from its kept picture and mask, model among the fields) and handed to /v1/images/generations' or /v1/images/edits' handler in the gateway: the same guards, GPU hold, admission, model rewrite and logging, and the call appears in the request log. The answer is 200 whatever the route said: the group, its run inside with the request as request (a generation's body as sent; an edit's text fields as sent and each file part by name, file name, content type, size and kept file lab-artifact:<id>), the route's status, code and message, its x-lmgw-* headers (a hold fallback names itself there) and its answer as text, each b64_json picture replaced by lab-artifact:<id>, the output artifact /labs/api/artifacts/{id} serves. The answer is kept even when the client goes away once the route has answered; a client that goes away before leaves the group with no run. store_error says why a run was not kept (a full disk, the group deleted meanwhile): it is then there with no id, its pictures inline. No body. 404 not_found for a group that is not the Image lab's, 409 cell_answered for one that has its run or is being answered (a re-ask is a new group), 500 cell_unbuilt for a stored form that no longer builds a request, 404 file_missing for a kept picture whose file is gone.

Parameters

NameInDescription
idrequiredpath integer

Responses

StatusDescription
200 OK.
application/json ImageLabAnswer
Fields of ImageLabAnswer
grouprequired LabGroupView The group, its one run inside. A run the store could not keep is
there with no id and its pictures still inline as b64_json.
store_errorrequired string | null Why the run was not kept (a full disk, a lock held too long). The
answer is the route's all the same.
default Error.
application/json OpenAiError
get/image-lab/api/models

List the image models

Capability admin, open to: owner

Everything that can answer an image request, with what the form needs to shape itself: the enabled local image/<id> rows and every cloud alias whose upstream catalog says it generates images, exactly as GET /v1/models publishes them (edit says whether the model serves /v1/images/edits). A local row also carries the flags its container is started with, which are the form's size, step and CFG defaults (the lab invents none), its container's state, and, once the container has been probed, the capabilities it reported: the sampler and scheduler lists, the real size bounds and the LoRAs on disk. hold says the GPU hold is on.

Responses

StatusDescription
200 OK.
application/json ImageLabModels
Fields of ImageLabModels
holdrequired boolean The GPU hold is on: local image models are paused.
modelsrequired array of ImageLabModel
models_dirrequired string The image models directory on the gateway's host.
default Error.
application/json ApiError

Decision lab

The dashboard's System One playground: the models that answer /v1/systemone with their header facts and token limits, the token gauge, and Ask, which stores a group (models × variants) whose cells run one at a time through the same handler as /v1/systemone and are kept in the lab store.

get/decision-lab/api/batches

List the set runs

Capability admin, open to: owner

Every set run, newest first: the set as run, the model, the file's name, the mapping, the concurrency and the progress (done items with a run of total, failed runs that are no 2xx, unreadable 2xx runs that do not read as an answer to every question, labelled items). status is running while its job runs (job_id the live job), done once every item has a run, canceled, interrupted when its job ended with items left (a gateway restart marks the job failed with job_error interrupted by shutdown; lmgw refusing an item before asking the model, such as the GPU hold, admission or the container's start, ends the job failed with that reason and leaves the item without a run; a pruned job row reads the same), or not_started. The job is found by its key, the newest row of it. cancel_requested is true while the job running it was already asked to cancel: the next Cancel aborts the calls in flight.

Responses

StatusDescription
200 OK.
application/json BatchList
Fields of BatchList
batchesrequired array of BatchView
default Error.
application/json ApiError
post/decision-lab/api/batches

Start a set run

Capability admin, open to: owner. Changes state.

Runs a question set over every row of a CSV or JSONL file as a job (kind lab_batch, key lab-batch:<id>, one live job per run). The set is a saved one (preset_id, whose body becomes the run's snapshot and takes "Use as threshold") or one sent whole (set), not both; model blank asks the set's default model. The mapping names the state column (sent as text, or as JSON in json mode), optionally a key column whose value each item keeps and both exports carry, and per question the column of its expected answer: an option's name (choice); yes, no, true, false, 1 or 0, any case (noul); a level's exact text or its index from 0 (score), as the whole column reads: texts when every value is a level's text, indices when every value is an index, and refused when both fit with different meanings or the column mixes them, until score_labels says which; an empty value is no label. Every problem refuses the whole file, none is dropped: a 400 bad_input naming each row, line, column and value. The run and its items (each a lab group of one cell, its form the set with the item's state, its labels kept as the option's name, the level's index or yes and no) are written in several short write transactions, the run not ready (not run, listed or counted) until the last; a boot deletes one a crash left half written. Then the job answers the items through the same path as a lab cell, concurrency at once (1 when absent; admission and the model's slots are the only other bound). 400 bad_request for a set that does not check or a concurrency of 0, 404 not_found for a preset the lab does not have or a model that answers no /v1/systemone, 409 batch_deleted when a Clear took the run while it was written. The body size is not limited.

Request body required

application/json: object

concurrency integer | null How many items are asked at once; absent, 1. Admission and the
model's slots are the only other bound. Default null.
format BatchFormat Default "csv".
mapping BatchMappingInput Default {"key":null,"labels":{},"score_labels":{},"state":"","state_mode":"text"}.
model string The model to ask; blank asks the set's default model. Default "".
preset_id integer | null A saved set to run (its body is the run's snapshot, and "Use as
threshold" writes into it). Default null.
set QuestionSetInput | null An unsaved set to run instead: one of the two. Default null.
source_name string The file's name, kept as the run's source. Default "".
text string The file's text. Default "".

Responses

StatusDescription
200 OK.
application/json BatchView
Fields of BatchView
cancel_requestedrequired boolean A Cancel already went to the job that runs it now: the next Cancel
aborts the calls in flight (their answers are not kept). False when
no job runs it.
concurrencyrequired integer (uint32)
created_atrequired string
donerequired integer (uint64) Items with a run, whatever it answered: the progress.
failedrequired integer (uint64) Of those, the runs the route did not answer with a 2xx.
idrequired integer (int64)
job_errorrequired string | null That job's error when it failed (interrupted by shutdown after a
restart).
job_idrequired integer | null The last job that ran it (no longer listed once pruned): the live
one while it runs.
labrequired LabKind
labelledrequired integer (uint64) Items with at least one expected answer.
mappingrequired BatchMapping
modelrequired string
preset_idrequired integer | null The saved set it ran; null for an unsaved set, or one deleted
since.
preset_namerequired string | null The saved set's name, when it is still there.
setrequired QuestionSet The set as run: later edits of the saved set do not change it.
source_namerequired string The uploaded file's name.
statusrequired BatchStatus
totalrequired integer (uint64) Items in all.
unreadablerequired integer (uint64) Of those, the 2xx runs that do not read as an answer to every
question of the set (the metrics count them per question as
unreadable).
default Error.
application/json ApiError
post/decision-lab/api/batches/from-agent

Save an agent run as a labelled set

Capability admin, open to: owner. Changes state.

Copies a batch agent's finished apply run (job_id, required, not queued or running) into a set run that is not run yet (status not_started, no job; Resume runs it). The labels are the rows the apply job received, the checked rows with the reviewer's edits: each item's state is the prompt the row's classify call sent (as text), its expected answer the row's output field, its key the row's id (source name agent run <job id> of <agent id>, mapping state prompt, key id). Answered in skipped, with the reason: a row the model was never asked about (its fetch failed, or it has no id: no state), and a row whose call failed with its output still the fallback (no answer, no label). The set is the one stamped on the rows (each row's set: the question set that classified it), or preset_id as an explicit override; rows of several sets, or stamped rows beside rows the model call classified, are a 400 mixed_sets naming each set's rows. Its question of the output field must be a choice, and its default model asks; each item's form, and the run's set, is the set restricted to that question, the request the agent sends. set_changed says the set was edited since its rows were classified. A label that is no option of that question refuses the save, a 400 bad_input naming each row and value (add the option to the set). 400 bad_request for a run that is no apply run, an agent whose output is no single field, rows no set classified without preset_id, a set that does not check, has no such question, asks it as another type or names no model, or a run none of whose rows has an answer or a label; 422 for a body without job_id; 404 not_found for an agent run, agent or preset that is not there, or a model that answers no /v1/systemone; 409 run_live while the run applies, 409 batch_deleted when a Clear took the run while it was written.

Request body required

application/json: object

job_idrequired integer (int64) The apply job whose received rows are the labels. Required.
preset_id integer | null An explicit override: the question set the run is of, whatever set
classified the rows. Absent, the set stamped on the rows
(AgentRowSet), which must be one set. Default null.

Responses

StatusDescription
200 OK.
application/json BatchFromAgentSaved
Fields of BatchFromAgentSaved
batchrequired BatchView The new set run, not_started; preset_name names its set.
set_changedrequired boolean The set was edited since its rows were classified (a row's stamp
names an older updated_at): the set run asks the set as it is now.
skippedrequired array of BatchFromAgentSkipped The rows that are no item, each with why.
default Error.
application/json ApiError
post/decision-lab/api/batches/preview

Preview a set run's file

Capability admin, open to: owner

Reads text as format (csv: RFC 4180 with a header row; jsonl: one JSON object per line, its columns its top-level keys in the order first met) and answers the columns (each with json: every non-empty value is a JSON object or array, which the state's json mode fits), the number of rows and the first sample rows (20 when absent). With a mapping and the set's questions, every row is checked as a start checks it and problems lists each refusal with its row, line, column and value: a mapping that names no state column or a column with an empty name (a column whose header is empty cannot be mapped), a mapped column the file lacks or names twice, an empty state, a state that is no JSON in json mode, a label that is no answer of its question, a score's label column that reads both as level texts and as indices with different meanings or mixes the two (set score_labels). Each problem's kind says which of these it is (file, mapping, state, label, score_labels_needed) and question the question it is about, so a client can act on a problem without reading its message. Without a mapping, problems holds the file's own (a line that does not read). Nothing is stored; the body size is not limited.

Request body required

application/json: object

format BatchFormat Default "csv".
mapping BatchMappingInput | null When given, every row is checked against it and problems lists
each refusal. Default null.
questions array of QuestionDraftInput The set's questions, which mapping's labels are checked against. Default [].
sample integer | null How many rows to answer from the top; absent, PREVIEW_ROWS. Default null.
text string The file's text, as read by the page. Default "".

Responses

StatusDescription
200 OK.
application/json BatchPreviewed
Fields of BatchPreviewed
columnsrequired array of BatchColumn In the file's order (a CSV's header; the keys of a JSONL file in the
order first met).
problemsrequired array of BatchProblem Each problem: the file's own, and with a mapping every row's.
rowsrequired integer (uint64) Every row the file holds.
samplerequired array of array of string The first rows, each a value per column in columns' order; a JSONL
row without a key, or with null, has an empty value there.
default Error.
application/json ApiError
get/decision-lab/api/batches/{id}

Read a set run

Capability admin, open to: owner

One set run as in the list. 404 not_found for a run that is not there.

Parameters

NameInDescription
idrequiredpath integer

Responses

StatusDescription
200 OK.
application/json BatchView
Fields of BatchView
cancel_requestedrequired boolean A Cancel already went to the job that runs it now: the next Cancel
aborts the calls in flight (their answers are not kept). False when
no job runs it.
concurrencyrequired integer (uint32)
created_atrequired string
donerequired integer (uint64) Items with a run, whatever it answered: the progress.
failedrequired integer (uint64) Of those, the runs the route did not answer with a 2xx.
idrequired integer (int64)
job_errorrequired string | null That job's error when it failed (interrupted by shutdown after a
restart).
job_idrequired integer | null The last job that ran it (no longer listed once pruned): the live
one while it runs.
labrequired LabKind
labelledrequired integer (uint64) Items with at least one expected answer.
mappingrequired BatchMapping
modelrequired string
preset_idrequired integer | null The saved set it ran; null for an unsaved set, or one deleted
since.
preset_namerequired string | null The saved set's name, when it is still there.
setrequired QuestionSet The set as run: later edits of the saved set do not change it.
source_namerequired string The uploaded file's name.
statusrequired BatchStatus
totalrequired integer (uint64) Items in all.
unreadablerequired integer (uint64) Of those, the 2xx runs that do not read as an answer to every
question of the set (the metrics count them per question as
unreadable).
default Error.
application/json ApiError
post/decision-lab/api/batches/{id}/cancel

Cancel a set run

Capability admin, open to: owner. Changes state.

Asks the run's job to stop: no new item is taken, the calls in flight finish and are kept, then the run reads canceled and Resume runs the rest. A second Cancel while the job still runs drops the calls in flight (a call may hang): the request log keeps their 499 rows as for any client gone, and their items stay without a run. Answers the run, whose cancel_requested says the next Cancel aborts. 404 not_found for a run that is not there, 409 batch_not_running when no job runs it.

Parameters

NameInDescription
idrequiredpath integer

Responses

StatusDescription
200 OK.
application/json BatchView
Fields of BatchView
cancel_requestedrequired boolean A Cancel already went to the job that runs it now: the next Cancel
aborts the calls in flight (their answers are not kept). False when
no job runs it.
concurrencyrequired integer (uint32)
created_atrequired string
donerequired integer (uint64) Items with a run, whatever it answered: the progress.
failedrequired integer (uint64) Of those, the runs the route did not answer with a 2xx.
idrequired integer (int64)
job_errorrequired string | null That job's error when it failed (interrupted by shutdown after a
restart).
job_idrequired integer | null The last job that ran it (no longer listed once pruned): the live
one while it runs.
labrequired LabKind
labelledrequired integer (uint64) Items with at least one expected answer.
mappingrequired BatchMapping
modelrequired string
preset_idrequired integer | null The saved set it ran; null for an unsaved set, or one deleted
since.
preset_namerequired string | null The saved set's name, when it is still there.
setrequired QuestionSet The set as run: later edits of the saved set do not change it.
source_namerequired string The uploaded file's name.
statusrequired BatchStatus
totalrequired integer (uint64) Items in all.
unreadablerequired integer (uint64) Of those, the 2xx runs that do not read as an answer to every
question of the set (the metrics count them per question as
unreadable).
default Error.
application/json ApiError
post/decision-lab/api/batches/{id}/delete

Delete a set run

Capability admin, open to: owner. Changes state.

Stops a running job and drops its calls in flight (499 rows in the request log, as for any client gone), then deletes the run, its items, their runs and artifact rows, and the files no other row names. The saved set it ran stays. Answers the lab's usage after it. 404 not_found for a run that is not there.

Parameters

NameInDescription
idrequiredpath integer

Responses

StatusDescription
200 OK.
application/json LabUsage
Fields of LabUsage
artifact_bytesrequired integer (uint64) The size of the distinct files the lab's rows name.
artifact_filesrequired integer (uint64) The distinct files those rows name.
artifactsrequired integer (uint64) Artifact rows: each input of a group and output of a run.
batchesrequired integer (uint64) The set runs; their items are among groups.
groupsrequired integer (uint64) Every group: the history's and the set runs' items.
labrequired LabKind
orphan_bytesrequired integer (uint64)
orphan_filesrequired integer (uint64) Files in the artifacts directory that no row of any lab names (left
by a crash between a write and its commit); removable with
POST /labs/api/{lab}/orphans/delete.
runsrequired integer (uint64)
text_bytesrequired integer (uint64) The stored text: each group's title, form, plan, override and
expected answers, each run's request, response and headers, each set
run's set and mapping, in bytes.
default Error.
application/json ApiError
get/decision-lab/api/batches/{id}/items

Read a set run's items

Capability admin, open to: owner

One page of the run's items in file order, each a lab group with its item (the run, its index and its expected answers) and its run once answered. after takes the items after that index (the next page), limit the page's size (absent, every item left: the server sets no maximum). total counts every item; next_after is the cursor of the next page, the page's last index, null when no item follows. 404 not_found for a run that is not there.

Parameters

NameInDescription
idrequiredpath integer
afterquery integer | null
limitquery integer | null

Responses

StatusDescription
200 OK.
application/json BatchItemPage
Fields of BatchItemPage
itemsrequired array of LabGroupView
next_afterrequired integer | null The next page's cursor: this page's last item_ix, to send as
after; null when no item follows.
totalrequired integer (uint64) Items in all.
default Error.
application/json ApiError
get/decision-lab/api/batches/{id}/metrics

Read a set run's metrics

Capability admin, open to: owner

Computed from the stored runs, per question of the set as run (question one of them): items, answered, failed (a run that is no 2xx), unreadable (a 2xx without a readable answer of the question's type), labelled and scored (answered and labelled) counts; accuracy, the winner (choice), P(yes) at or above 0.5 (noul) or the nearest level (score) equal to the label, and for a score the mean absolute distance in levels between its expected level and the label; the confusion matrix, labels by predictions in classes order (the options, the levels' indices, yes and no); the reliability diagram of the labelled answers over bins equal-width bins of the predicted probability (the winner's, the nearest level's, P(yes) for noul), only the bins that hold an answer, each with its index, edges (index / bins to (index + 1) / bins, the values an answer is placed by), count, mean prediction and observed, the rate of the winner or level being right (for noul, of the label being yes); 10 bins when absent, at least 1, no maximum (a 400 bad_request for 0), any number costing what the answers do; and the full threshold curve, a point per distinct confidence (certainty max(p, 1 − p) for noul) with the answered items at or above it, their share of all answered, the labelled among them and how many of those are right. 404 not_found for a run or question that is not there.

Parameters

NameInDescription
idrequiredpath integer
binsquery integer | null
questionquery string | null

Responses

StatusDescription
200 OK.
application/json BatchMetrics
Fields of BatchMetrics
batch_idrequired integer (int64)
binsrequired integer (uint32)
questionsrequired array of QuestionMetrics In the set's order.
default Error.
application/json ApiError
post/decision-lab/api/batches/{id}/resume

Resume a set run

Capability admin, open to: owner. Changes state.

A new job for the items that have no run, after a cancel, a restart, a refusal or a failure, at concurrency when given (kept as the run's), else the run's. With retry_failed the items whose run failed (no 2xx) are asked again too, each new run replacing the failed one. Answers the run. 404 not_found for a run that is not there, 409 batch_running while a job runs it, 409 batch_done when every item has a run (and, with retry_failed, none failed), 400 bad_request for a concurrency of 0.

Parameters

NameInDescription
idrequiredpath integer

Request body

application/json: object

concurrency integer | null A new concurrency for the run; absent, the one it had. Default null.
retry_failed boolean Ask the items whose run failed (no 2xx) again too: each failed run is
replaced by the new one. False when absent. Default false.

Responses

StatusDescription
200 OK.
application/json BatchView
Fields of BatchView
cancel_requestedrequired boolean A Cancel already went to the job that runs it now: the next Cancel
aborts the calls in flight (their answers are not kept). False when
no job runs it.
concurrencyrequired integer (uint32)
created_atrequired string
donerequired integer (uint64) Items with a run, whatever it answered: the progress.
failedrequired integer (uint64) Of those, the runs the route did not answer with a 2xx.
idrequired integer (int64)
job_errorrequired string | null That job's error when it failed (interrupted by shutdown after a
restart).
job_idrequired integer | null The last job that ran it (no longer listed once pruned): the live
one while it runs.
labrequired LabKind
labelledrequired integer (uint64) Items with at least one expected answer.
mappingrequired BatchMapping
modelrequired string
preset_idrequired integer | null The saved set it ran; null for an unsaved set, or one deleted
since.
preset_namerequired string | null The saved set's name, when it is still there.
setrequired QuestionSet The set as run: later edits of the saved set do not change it.
source_namerequired string The uploaded file's name.
statusrequired BatchStatus
totalrequired integer (uint64) Items in all.
unreadablerequired integer (uint64) Of those, the 2xx runs that do not read as an answer to every
question of the set (the metrics count them per question as
unreadable).
default Error.
application/json ApiError
post/decision-lab/api/batches/{id}/threshold

Use as threshold

Capability admin, open to: owner. Changes state.

Measures the cut at value for question on this run (coverage of the answered items, accuracy and count of the labelled ones at or above it) and writes the value with that measurement into the saved set the run ran. Answers the set. 400 bad_request for a value outside 0 to 1, 404 not_found for a run or question that is not there, 409 set_deleted when the run ran an unsaved set or the set is deleted, 409 set_changed when the set's question differs from the one the run asked (or the set changed while measuring), 409 no_labels when no labelled answer lies at or above the cut. The body size is not limited.

Parameters

NameInDescription
idrequiredpath integer

Request body required

application/json: object

question string The question's id. Default "".
value number (double) The cut, from 0 to 1. Default 0.0.

Responses

StatusDescription
200 OK.
application/json LabPresetView
Fields of LabPresetView
created_atrequired string
idrequired integer (int64)
labrequired LabKind
namerequired string
updated_atrequired string
default Error.
application/json ApiError
post/decision-lab/api/count

Count a form's tokens

Capability admin, open to: owner

Counts the form on model's resolved route, in the gateway, as /v1/count_tokens counts: the state, each question (its instructions and its options, levels or criteria) and each choice question's options alone, and sets the estimates (the state plus the largest question, or the largest option span) against the model's limits; over is a warning, nothing is refused. The numbers are approximate: approx always holds flattened (llama.cpp's template wraps the pieces), media_omitted with images, tokenizer_guess where a cloud model has no counter of its own. What is judged is the route the count would hit, after the hold's swap: a held row with a cloud fallback is counted there (answered_by names it), and a local model that is not ready is counted only with load, which starts its container; without it not_counted says so, as it does for a count that failed. A count that starts a model writes a request log row, a cheap one none. 404 not_found for a model that answers no /v1/systemone; the body size is not limited.

Request body required

application/json: object

form DecisionForm Default {"images":[],"questions":[],"state":"","state_mode":"text"}.
load boolean Count even when that starts a container: a local model the count
would hit (after the hold's swap) that is not ready is otherwise not
counted (not_counted says so). Default false.
model string Default "".

Responses

StatusDescription
200 OK.
application/json DecisionCounted
Fields of DecisionCounted
answered_byrequired string | null The fallback that counted instead (x-lmgw-fallback).
approxrequired array of string Why the numbers are approximate: always flattened (llama.cpp's
template wraps the pieces and is not counted), media_omitted with
images, tokenizer_guess on a cloud model without a counter of its
own.
estimatesrequired array of DecisionEstimate
modelrequired string
not_countedrequired string | null Why nothing was counted ("decide/kev-4b is not loaded", or the
count's own failure); everything below but answered_by is empty
then.
questionsrequired array of QuestionTokens
staterequired integer | null The state's tokens.
default Error.
application/json ApiError
post/decision-lab/api/groups

Ask: store a group and its plan

Capability admin, open to: owner. Changes state.

Stores what one Ask will run and answers the group with its plan and no runs yet; the page then posts its cells one at a time. The plan is the models × (as_written, then each of variants), models outer: no_descriptions sends every choice description as null and no noul criteria, reversed each choice question's options in reverse. The form is checked first (a state, valid JSON in json mode, at least one question, unique ids, a choice with unique named options, a score with 2 to 10 levels: a 400 bad_request naming the field). An override is sent instead of the form, with only model rewritten per model; its only check is that it is a JSON object, and a perturbation with an override is a 400 (perturbations rewrite the form). The form's images (data URLs, or artifact ids of a re-opened form) and the override's data URLs are stored as the group's input artifacts and named by id in the stored form and override. The body size is not limited.

Request body required

application/json: object

form DecisionForm Default {"images":[],"questions":[],"state":"","state_mode":"text"}.
models array of string The head model first, then the compared ones. Default [].
override string | null The request override, as typed: sent instead of the form, with only
model rewritten per model. Default null.
variants array of Variant The checked perturbations; every model is also asked as written,
first. Default [].

Responses

StatusDescription
200 OK.
application/json LabGroupView
Fields of LabGroupView
artifactsrequired array of LabArtifactView The group's inputs, in order.
created_atrequired string
formrequired any The lab's form as the lab held it (the Decision lab's
DecisionForm), with its media as the group's input artifacts.
idrequired integer (int64)
in_flightrequired boolean A cell of it is being answered now: its request is out and its run
not in yet. A group with no run that is not in flight was stopped.
Deleting a group in flight is the 409 in_flight.
itemrequired LabBatchItem | null The set run it is an item of; null for a group of the history.
labrequired LabKind
overriderequired string | null The request override, as typed (its image data URLs as
lab-artifact:<id>), when one was in effect.
planrequired array of LabCell The cells, in run order. A group with fewer runs than cells was
stopped.
runsrequired array of LabRunView The runs so far, in cell order.
titlerequired string Derived once from the form: the state's first line, a prompt.
default Error.
application/json ApiError
post/decision-lab/api/groups/{id}/cells/{cell}

Run one cell

Capability admin, open to: owner. Changes state.

Builds the cell's request (DecisionForm's body, or the override with model rewritten, its images as data URLs), hands it to /v1/systemone's handler in the gateway — the hold, admission, fallbacks and the systemone request log row are real; only auth and the HTTP hop are skipped, and max_body_mb still bounds the bytes — and records the run. It answers 200 whatever the route said: the run carries http_status, error_code (the envelope's lmgw_code, else its code or type), error_message, the response verbatim, answered_by (x-lmgw-fallback, else the model asked) with fallback_reason, and the stored request with each image as lab-artifact:<id>. When the store cannot keep the run, the answer is the route's all the same: the run has no id and store_error says why. No body. 404 not_found for a group or cell that is not there, 409 cell_answered for a cell that has a run or is being answered, without a dispatch (a re-ask is a new group).

Parameters

NameInDescription
idrequiredpath integer
cellrequiredpath integer

Responses

StatusDescription
200 OK.
application/json LabCellResult
Fields of LabCellResult
runrequired LabRunView
store_errorrequired string | null Why the run was not kept (a full disk, a lock held too long). The
answer is the route's all the same.
default Error.
application/json ApiError
get/decision-lab/api/models

List the decision models

Capability admin, open to: owner

Every model that answers /v1/systemone, as GET /v1/models publishes it: the local decide/* rows and every cloud alias or catalog entry of task decision. A local row also carries facts: from its GGUF header the decision type, decision.max_head_tokens and the shape (non_causal, causal_head, label_logits); from the row the ctx_size, the ubatch and batch in effect with their source (llama.cpp lowers the ubatch to the batch, embedding mode the batch to the ubatch), CPU or GPU and the thread count; from its running container's /props n_ctx_slot. state is its container's (null: not running), held whether the GPU hold pauses it now and fallback the model or alias that answers for it then. reads_images is the running server's vision, else an image among its input modalities. limits says what a request must fit in how many tokens: the ubatch for a non-causal type, the option span and the context for a causal type with a head, the context for a label-logits type, the catalog's context for a cloud model. No per-type option limit is given: llama.cpp's 400 names it. price names what prices a request to it, as the gateway's own lookup does for its primary route: local (free whatever rows exist), else per unit the one row that prices that unit (the alias's manual row, the alias's catalog row, the upstream model's manual row, then its catalog row; a row without a usable rate is none), empty when no row covers it and Usage records its cost as unknown; unresolved says why a name has no one route. currency is the rows'.

Responses

StatusDescription
200 OK.
application/json DecisionLabModels
Fields of DecisionLabModels
currencyrequired string The currency of every price row (the gateway's setting).
holdrequired boolean The GPU hold is on.
modelsrequired array of DecisionLabModel
default Error.
application/json ApiError

Voices lab

The dashboard's voice sample generator: fixed voices for the cloning text-to-speech models. A text-to-speech model renders rounds of candidates of a phonetically rich sentence; the chosen one is saved to the voice library with its exact transcript and how it was made, and a cloning model can speak a test line with it.

post/voice-lab/api/clone-check

Speak a test line with a sample

Capability admin, open to: owner

Has a cloning text-to-speech model say a short line (the body's, else the language's check line) with a saved sample as its reference, through the same handler as POST /v1/audio/speech, whose answer is relayed as it came: the audio, x-lmgw-fallback when a fallback answered, or the route's OpenAI error envelope. With the class's voice directory on the library the sample is named as voice, as a realtime session names it; otherwise it goes as a voice_ref path with its transcript as reference_text. The check's own refusals (no alias, no line, no such sample) use the same envelope.

Request body required

application/json: object

aliasrequired string The cloning text-to-speech alias.
language string | null Default null.
samplerequired string The sample: its voice name (anna) or file name (anna.wav).
text string | null What to say; absent or blank: the language's check line. Default null.

Responses

StatusDescription
200 OK.
application/octet-stream string (binary)
audio/aac string (binary)
audio/flac string (binary)
audio/mpeg string (binary)
audio/ogg string (binary)
audio/wav string (binary)
default Error.
application/json OpenAiError
get/voice-lab/api/model

What a text-to-speech model takes

Capability admin, open to: owner

What the Voices lab's form offers for a text-to-speech alias, read from lmgw's own catalog and starting nothing: what a voice description does (none, a speaking style, the voice it designs, passed through) and whether the model needs one, whether it speaks a voice it is told, whether a seed reaches it, the languages it declares and what happens to the form's language, whether it clones a voice-library clip (for the cloning check), whether the GPU hold pauses it now and which alias answers in its place, and the licence its package states. A cloud alias's facts come from its capabilities.speech override; lmgw sends it no seed and no language. 400 for a blank alias or a language that is no language code, 404 for an unknown alias, 501 for one that is no OpenAI-shaped audio route (openai, openai_compatible or llama_cpp).

Parameters

NameInDescription
aliasrequiredquery string
languagequery string | null
voicequery string | null

Responses

StatusDescription
200 OK.
application/json VoiceModelFacts
Fields of VoiceModelFacts
aliasrequired string
clone_noterequired string | null Why it would not, or how, in a sentence.
clonesrequired boolean The model clones a voice-library clip (the cloning check's pick).
default_voicerequired string | null What speaks when no voice is named, when lmgw knows.
descriptionrequired VoiceDescriptionMode What a voice description does.
description_defaultrequired boolean The row has a default description of its own, which a request
without one gets.
description_requiredrequired boolean The model speaks only with a description, and the row has no
default one.
fallbackrequired string | null The alias that answers in its place now, when one does.
heldrequired boolean The GPU hold (or a benchmark's lease) pauses the row now.
language_noterequired string | null What happens to the asked language, when it does not reach the model
as set ("does not speak German (de) — not sent").
languagesrequired array of string ISO 639-1 codes the model declares it speaks; empty when it declares
none.
licencerequired ModelLicence | null The licence the row's package states, when it states one.
Information only: never a filter.
localrequired boolean An lmgw audio row (row names it); otherwise a cloud alias.
reads_seedrequired boolean A seed reaches the model: each candidate is drawn from its own.
false for a cloud model (lmgw sends it none) and for an engine that
takes none.
rowrequired VoiceRow | null
row_pins_seedrequired boolean The row pins a seed of its own (its default request options): the
candidates' seeds are sent, and what the engine does with both is
its own.
takes_voicerequired boolean The model speaks a voice it is told (a preset, a shipped voice, a
library clip); false for one that designs its voice instead.
default Error.
application/json ApiError
get/voice-lab/api/rounds

List the kept rounds

Capability admin, open to: owner

Every round kept under <data_dir>/voice-lab/rounds, newest first, with their candidates and what their audio takes on disk. Rounds stay until they are discarded; samples saved from them are copies and stay in the library.

Responses

StatusDescription
200 OK.
application/json VoiceRounds
Fields of VoiceRounds
bytesrequired integer (uint64) What the rounds' audio takes on disk.
dirrequired string Where they are kept.
roundsrequired array of VoiceRound
default Error.
application/json ApiError
post/voice-lab/api/rounds

Render a round of candidates

Capability admin, open to: owner. Changes state.

The voice_generate op as a route: the alias is opened once and says the text as count candidates (4 when absent, no cap), each with its own seed where the engine reads one; a configured fallback answers as for any request, and the round names who answered. The answer is the round as kept, each candidate with its seed, length and the path that plays it. Failures before the first candidate are the speech route's (the GPU hold with no fallback 503 gpu_hold, a voice-design model without a description 400 instructions_required, the engine's own error) with their status and code; a failure after it ends the round there (stopped). A caller that goes away (the request aborted, an MCP client hanging up) stops the round: the candidate in flight ends, the round keeps what it made with stopped set, and its request_logs row is a 200 canceled. The body size is not limited.

Request body required

application/json: object

aliasrequired string The text-to-speech alias, local or cloud.
count integer | null How many candidates; 4 when absent. Rendered one after the other. Default null.
description string | null The voice description (or speaking style) for a model that reads one. Default null.
language string | null ISO 639-1 code: picks the sentence, and is sent to a local row that
takes a language, in its own spelling. Default null.
seed integer | null The first candidate's seed; the next get seed + 1, seed + 2, …
Absent: a random seed per candidate. Default null.
text string | null What every candidate says. Absent or blank: the language's sentence
(the owner's saved one, else the built-in one). Default null.
voice string | null The voice for a model that speaks a voice it is told. Default null.

Responses

StatusDescription
200 OK.
application/json VoiceRound
Fields of VoiceRound
aliasrequired string The alias asked.
answered_byrequired string The alias that answered: alias, or the fallback the GPU hold (or a
busy card) handed the round to.
askedrequired integer (uint32) How many candidates were asked for.
candidatesrequired array of VoiceCandidate
created_atrequired string RFC 3339, UTC.
descriptionrequired string | null
fallback_reasonrequired string | null Why a fallback answered (hold, external_vram, …).
idrequired string The round's id, its directory's name.
languagerequired string | null
language_noterequired string | null What happened to the language when it did not reach the model as
set.
licencerequired ModelLicence | null The licence the answering row's package states, when it states one.
rowrequired VoiceRow | null The lmgw audio row behind the answering route, if it is one.
seeds_sentrequired boolean Each candidate's seed reached the model.
sent_textrequired string | null What the engine was sent instead, when lmgw's speech shaping changed
it (inline tags or characters the engine cannot say): what the
candidates say, and the transcript a saved sample gets.
shapingrequired string | null What lmgw's speech shaping changed in the request
(x-lmgw-speech's words), when it changed anything.
stoppedrequired string | null Why the round ended before asked candidates: the first failure,
or a stop (the page left, Stop, the round discarded).
textrequired string What every candidate was asked to say.
upstreamrequired string The upstream that answered.
upstream_modelrequired string The model name it was sent.
voicerequired string | null
default Error.
application/json ApiError
post/voice-lab/api/rounds/clear

Discard every round

Capability admin, open to: owner. Changes state.

Deletes every kept round and its candidates' audio, and every directory under the rounds' that is no readable round (counted in bytes). A round still rendering is stopped and waited for first. Saved samples are copies in the voice library and stay. Answers the (empty) list.

Responses

StatusDescription
200 OK.
application/json VoiceRounds
Fields of VoiceRounds
bytesrequired integer (uint64) What the rounds' audio takes on disk.
dirrequired string Where they are kept.
roundsrequired array of VoiceRound
default Error.
application/json ApiError
get/voice-lab/api/rounds/{id}/candidates/{n}

Play a candidate

Capability admin, open to: owner

The candidate's audio as the model answered it (a WAV for every local model), with its content type and Accept-Ranges: bytes. One Range (bytes=a-b, bytes=a- or bytes=-n) answers 206 with Content-Range; the answer carries an ETag made from the file (inode, length, modification time), and If-Range with it applies the range, any other If-Range serves the whole file, and so does a Range lmgw does not read; 416 range_not_satisfiable (Content-Range: bytes */size) for a range that names no byte of it. 404 for a round or candidate that is not there.

Parameters

NameInDescription
idrequiredpath string
nrequiredpath integer

Responses

StatusDescription
200 OK.
application/octet-stream string (binary)
audio/aac string (binary)
audio/flac string (binary)
audio/mpeg string (binary)
audio/ogg string (binary)
audio/wav string (binary)
default Error.
application/json ApiError
post/voice-lab/api/rounds/{id}/delete

Discard a round

Capability admin, open to: owner. Changes state.

Deletes the round and its candidates' audio; answers the rounds left. A round still rendering is stopped and waited for first, so nothing it writes after brings it back. 404 for a round that is not there, 400 for an id that is no round id.

Parameters

NameInDescription
idrequiredpath string

Responses

StatusDescription
200 OK.
application/json VoiceRounds
Fields of VoiceRounds
bytesrequired integer (uint64) What the rounds' audio takes on disk.
dirrequired string Where they are kept.
roundsrequired array of VoiceRound
default Error.
application/json ApiError
get/voice-lab/api/samples

List the voice library with how each sample was made

Capability admin, open to: owner

The voice library's clips (the Audio lab's), each with the Voices lab's record of how it was made when it made it: alias, the model that answered, description, voice, seed, text, language, dates and licence. provenance_current is false for a clip replaced since (its SHA-256 no longer matches). Without an audio models directory the answer is a 200 with no samples and an error saying so; a samples.json lmgw cannot read leaves every record out and records_error says why.

Responses

StatusDescription
200 OK.
application/json VoiceSamples
Fields of VoiceSamples
errorrequired string | null Why there is no library (no audio models directory).
library_activerequired boolean The class's voice directory is this library: a clip's name is a
voice on every cloning model.
records_errorrequired string | null Why no sample shows its record: the records' file (samples.json)
is there and cannot be read. lmgw never writes over it; saving a
sample is refused until it is fixed or moved.
samplesrequired array of VoiceSample
default Error.
application/json ApiError
post/voice-lab/api/samples

Save a candidate as a sample

Capability admin, open to: owner. Changes state.

The voice_sample_save op as a route: the candidate goes to the voice library as <name>.wav, leading and trailing silence cut and loudness untouched, with the text the engine was sent as its transcript, and how it was made is recorded. 409 name_taken when the library has an audio clip of that name and overwrite is not set (nothing is written); 409 unreadable_file when samples.json is no JSON lmgw can read (nothing is written); 404 for a round or candidate that is not there; 400 for a bad name or no audio models directory. A development gateway whose audio models directory is the installed app's refuses (400, code dev_shared_models_dir).

Request body required

application/json: object

candidaterequired integer (uint32) The candidate's number in it, from 1.
namerequired string The voice name it is saved under: what a request's voice names.
Letters, digits, space, ., _ and -; a trailing .wav is
dropped.
overwrite boolean Replace a sample or clip of that name. Without it, a taken name is
refused (409 name_taken) and nothing is written. Default false.
roundrequired string The round's id.

Responses

StatusDescription
200 OK.
application/json VoiceSampleSaved
Fields of VoiceSampleSaved
cliprequired string The clip's file name in the library (anna.wav).
library_activerequired boolean The class's voice directory is this library, so voice names the
clip on every cloning model; otherwise it is reachable as a
voice_ref path only.
messagerequired string The outcome in a sentence.
okrequired boolean
provenancerequired VoiceProvenance
replacedrequired array of string The library files it replaced (with overwrite).
transcriptrequired string The transcript recorded for it.
voicerequired string The voice name a request uses (anna).
default Error.
application/json ApiError
get/voice-lab/api/sentences

List the sentence per language

Capability admin, open to: owner

The sentence a round's candidates say, per language: the built-in one (the first two sentences of "The North Wind and the Sun", a phonetically rich passage) and the owner's saved one when there is one, which is what text holds then; and the line the cloning check says. A language the table lacks is listed once the owner saved a sentence for it.

Responses

StatusDescription
200 OK.
application/json VoiceSentences
Fields of VoiceSentences
errorrequired string | null Why the owner's saved sentences are not in the list: their file
(sentences.json) is there and cannot be read. lmgw never writes
over it; saving a sentence is refused until it is fixed or moved.
languagesrequired array of VoiceSentence
default Error.
application/json ApiError
post/voice-lab/api/sentences

Save the owner's sentence for a language

Capability admin, open to: owner. Changes state.

Saves the sentence for the language, kept across restarts (<data_dir>/voice-lab/sentences.json), so it is the prefill from now on; an empty text drops it and the built-in sentence is the prefill again. Answers the whole table. 400 for a language that is no language code; 409 unreadable_file when sentences.json is there and is no JSON lmgw can read (it is never written over: nothing is saved until it is fixed or moved).

Request body required

application/json: object

languagerequired string ISO 639-1 code (de).
textrequired string

Responses

StatusDescription
200 OK.
application/json VoiceSentences
Fields of VoiceSentences
errorrequired string | null Why the owner's saved sentences are not in the list: their file
(sentences.json) is there and cannot be read. lmgw never writes
over it; saving a sentence is refused until it is fixed or moved.
languagesrequired array of VoiceSentence
default Error.
application/json ApiError

Lab store

What the labs keep, one store for all three: each lab's history of groups (one click: the form, the plan, the override) and runs (one dispatch: the request and answer as the texts that went and came), the artifact files they name, the size it all takes, deleting a group or a whole lab, and the JSONL, zip or CSV export. Nothing is deleted by age or count.

get/labs/api/artifacts/{id}

Read an artifact's bytes

Capability admin, open to: owner

The file as stored, streamed from lmgw's disk, with the media type sniffed from its bytes, X-Content-Type-Options: nosniff and Content-Security-Policy: sandbox, so a file opened in a browser runs nothing; Accept-Ranges: bytes and ETag "sha256:<hex>". One Range (bytes=a-b, bytes=a- or bytes=-n) answers 206 with Content-Range, as a media player resumes or seeks; If-Range with the ETag applies it, any other If-Range serves the whole file, and so does a Range lmgw does not read (several ranges, another unit). 416 range_not_satisfiable, with Content-Range: bytes */size, for a range that names no byte of the file. 404 not_found for an artifact that is not there, 404 file_missing when its row is there and its file is not.

Parameters

NameInDescription
idrequiredpath integer

Responses

StatusDescription
200 OK.
*/* string (binary)
default Error.
application/json ApiError
post/labs/api/{lab}/clear

Clear a lab

Capability admin, open to: owner. Changes state.

Deletes every group and set run of the lab as their deletes do (a running set run's job drops its calls in flight first), then the files no remaining row names. Answers the lab's usage after it, which then counts nothing. The lab's presets stay. Nothing is deleted by age or count otherwise: the lab store has no retention rule.

Parameters

NameInDescription
labrequiredpath string

Responses

StatusDescription
200 OK.
application/json LabUsage
Fields of LabUsage
artifact_bytesrequired integer (uint64) The size of the distinct files the lab's rows name.
artifact_filesrequired integer (uint64) The distinct files those rows name.
artifactsrequired integer (uint64) Artifact rows: each input of a group and output of a run.
batchesrequired integer (uint64) The set runs; their items are among groups.
groupsrequired integer (uint64) Every group: the history's and the set runs' items.
labrequired LabKind
orphan_bytesrequired integer (uint64)
orphan_filesrequired integer (uint64) Files in the artifacts directory that no row of any lab names (left
by a crash between a write and its commit); removable with
POST /labs/api/{lab}/orphans/delete.
runsrequired integer (uint64)
text_bytesrequired integer (uint64) The stored text: each group's title, form, plan, override and
expected answers, each run's request, response and headers, each set
run's set and mapping, in bytes.
default Error.
application/json ApiError
get/labs/api/{lab}/export

Export a lab

Capability admin, open to: owner

The scope as one file with Content-Disposition: attachment (lmgw-lab-{lab}-{date}, with -group-{id}, -batch-{id} or -{model} for a scope) and Cache-Control: no-store. No scope is the whole lab, the history and every set run's items; group one group (404 not_found when the lab has none by that id); batch one set run's items in file order (404 not_found likewise); model, from and to (RFC 3339, to exclusive; another spelling is a 400 bad_request) a filter. format=jsonl, the default, is lossless: one lmgw.lab.v1 line per group, oldest first, its runs inside with request and response as the exact texts and a set run's item with its item (its expected answers among it), application/x-ndjson; when the scope has artifacts the file is a zip of that JSONL and artifacts/<sha256>.<ext>, and each artifact's href is its path inside the zip (a file missing from the data dir is named in a MISSING.txt). format=csv is the lab's flat table, text/csv: the Decision lab's has a row per run and question (group_id, batch_id, item_ix, item_key, run_id, created_at, model_asked, answered_by, upstream_model, variant, http_status, error_message, latency_ms, input_tokens, question_id, question_type, answer, expected, correct, confidence, probabilities, state), a failed run of the history one row with the question columns empty. A set run's item names its run, its index in the file and its key (the three are empty for the history), and has a row per question of its set whatever its run answered: expected its label for the question, correct whether the answer matches it (true or false), empty without a label and, for correct, when the run failed or did not answer the question readably. The Image and Audio labs' tables have a row per run (group_id, run_id, created_at, endpoint, model_asked, answered_by, fallback_reason, http_status, error_code, error_message, latency_ms, response_type), then the Image lab's prompt, negative_prompt, size, n, steps, seed, output_format, images, image_bytes and artifact_ids, the Audio lab's task, input, voice, language, text (a transcription's), files, file_bytes and artifact_ids; a group with no run has no row. format=files, the Image and Audio labs' only (the Decision lab makes no files: 400 bad_request), is the files the runs made, to keep and play: each named <group id, six digits>-<model>-<voice or task>-<first words of the text>.<ext>, lower case, anything but letters, digits, . and _ a dash, a run with several outputs adding each one's id or place, a name taken twice -2, -3; a picture or an audio file as kept, a streamed or raw PCM speech answer as a WAV (the form's PCM format, the x-lmgw-sample-rate it was answered with winning), a transcription's or a task's text answer as a .txt. group naming a group whose runs made one file answers that file as it is, typed as it is; anything else is a zip (lmgw-lab-{lab}…zip) of the files, oldest group first, and manifest.jsonl, one lmgw.lab.files.v1 line (LabFilesManifestLine) per file: its name, kind (output, wav, transcript), group, run, time, route, model asked and answering, task, voice, the text it was given, the request's parameters as sent, type, size, its artifact and the group's inputs, which the zip does not carry (the JSONL export does). A file missing from the data dir is named in a MISSING.txt and has missing true. As large as the scope is, and not capped.

Parameters

NameInDescription
labrequiredpath string
batchquery integer | null
formatquery LabExportFormat
fromquery string | null
groupquery integer | null
modelquery string | null
toquery string | null

Responses

StatusDescription
200 OK.
application/x-ndjson LabExportLine
Fields of LabExportLine
formatrequired string Always lmgw.lab.v1.
grouprequired LabGroupView
labrequired LabKind
application/zip string (binary)
audio/* string (binary)
image/* string (binary)
text/csv; charset=utf-8 string (binary)
text/plain; charset=utf-8 string (binary)
default Error.
application/json ApiError
get/labs/api/{lab}/groups

Read a lab's history

Capability admin, open to: owner

One page of what the lab kept, newest first: each group (one click: the form, the plan of cells, the override) with its runs in cell order and its artifacts. A set run's items are not the history's: they are read by their run. {lab} is decision, image or audio; any other is a 404 not_found. before takes the groups older than that id (the next page), limit the page's size (absent, every group left: the server sets no maximum), model only the groups whose plan asks that model. total counts every group the filter takes, older those older than the page's last. in_flight says a cell of the group is being answered now; a group with fewer runs than cells that is not in flight was stopped. A run's request and response are the texts that went and came, never re-serialized; an image sent as a data URL is lab-artifact:<id> in the stored request, and an artifact's href is where its bytes are.

Parameters

NameInDescription
labrequiredpath string
beforequery integer | null
limitquery integer | null
modelquery string | null

Responses

StatusDescription
200 OK.
application/json LabGroupPage
Fields of LabGroupPage
groupsrequired array of LabGroupView Newest first.
olderrequired integer (uint64) The groups the filter matches that are older than this page's last.
totalrequired integer (uint64) Every group the filter matches, this page's included.
default Error.
application/json ApiError
get/labs/api/{lab}/groups/{id}

Read one group

Capability admin, open to: owner

One group with its runs and artifacts, as in the history; a set run's item too, with its item. 404 not_found for a lab that is none, or a group that is not there or is another lab's.

Parameters

NameInDescription
labrequiredpath string
idrequiredpath integer

Responses

StatusDescription
200 OK.
application/json LabGroupView
Fields of LabGroupView
artifactsrequired array of LabArtifactView The group's inputs, in order.
created_atrequired string
formrequired any The lab's form as the lab held it (the Decision lab's
DecisionForm), with its media as the group's input artifacts.
idrequired integer (int64)
in_flightrequired boolean A cell of it is being answered now: its request is out and its run
not in yet. A group with no run that is not in flight was stopped.
Deleting a group in flight is the 409 in_flight.
itemrequired LabBatchItem | null The set run it is an item of; null for a group of the history.
labrequired LabKind
overriderequired string | null The request override, as typed (its image data URLs as
lab-artifact:<id>), when one was in effect.
planrequired array of LabCell The cells, in run order. A group with fewer runs than cells was
stopped.
runsrequired array of LabRunView The runs so far, in cell order.
titlerequired string Derived once from the form: the state's first line, a prompt.
default Error.
application/json ApiError
post/labs/api/{lab}/groups/{id}/delete

Delete a group

Capability admin, open to: owner. Changes state.

Deletes the group, its runs and its artifact rows, then the files no other row names. Answers the lab's usage after it. 404 not_found for a group that is not there or is another lab's, 409 batch_item for a set run's item, which goes with its run, 409 in_flight for a group whose run is on its way (stop it, or delete it once its run is in; Clear is not refused, and a run that lands after it is answered as not kept).

Parameters

NameInDescription
labrequiredpath string
idrequiredpath integer

Responses

StatusDescription
200 OK.
application/json LabUsage
Fields of LabUsage
artifact_bytesrequired integer (uint64) The size of the distinct files the lab's rows name.
artifact_filesrequired integer (uint64) The distinct files those rows name.
artifactsrequired integer (uint64) Artifact rows: each input of a group and output of a run.
batchesrequired integer (uint64) The set runs; their items are among groups.
groupsrequired integer (uint64) Every group: the history's and the set runs' items.
labrequired LabKind
orphan_bytesrequired integer (uint64)
orphan_filesrequired integer (uint64) Files in the artifacts directory that no row of any lab names (left
by a crash between a write and its commit); removable with
POST /labs/api/{lab}/orphans/delete.
runsrequired integer (uint64)
text_bytesrequired integer (uint64) The stored text: each group's title, form, plan, override and
expected answers, each run's request, response and headers, each set
run's set and mapping, in bytes.
default Error.
application/json ApiError
post/labs/api/{lab}/orphans/delete

Remove the orphan files

Capability admin, open to: owner. Changes state.

Removes every file in the artifacts directory that no row of any lab names, and answers the lab's usage after it. Nothing removes them on its own.

Parameters

NameInDescription
labrequiredpath string

Responses

StatusDescription
200 OK.
application/json LabUsage
Fields of LabUsage
artifact_bytesrequired integer (uint64) The size of the distinct files the lab's rows name.
artifact_filesrequired integer (uint64) The distinct files those rows name.
artifactsrequired integer (uint64) Artifact rows: each input of a group and output of a run.
batchesrequired integer (uint64) The set runs; their items are among groups.
groupsrequired integer (uint64) Every group: the history's and the set runs' items.
labrequired LabKind
orphan_bytesrequired integer (uint64)
orphan_filesrequired integer (uint64) Files in the artifacts directory that no row of any lab names (left
by a crash between a write and its commit); removable with
POST /labs/api/{lab}/orphans/delete.
runsrequired integer (uint64)
text_bytesrequired integer (uint64) The stored text: each group's title, form, plan, override and
expected answers, each run's request, response and headers, each set
run's set and mapping, in bytes.
default Error.
application/json ApiError
get/labs/api/{lab}/presets

List a lab's presets

Capability admin, open to: owner

The lab's presets by name, of kind only when given: each its name, its kind and its body, the kind's type (a question_set is the Decision lab's questions, the model it picks and a threshold per question with where it was measured). 404 not_found for a lab that is none.

Parameters

NameInDescription
labrequiredpath string
kindquery LabPresetKind | null

Responses

StatusDescription
200 OK.
application/json LabPresetList
Fields of LabPresetList
presetsrequired array of LabPresetView
default Error.
application/json ApiError
post/labs/api/{lab}/presets

Save a preset

Capability admin, open to: owner. Changes state.

Saves a named preset and answers it. 400 bad_request for a kind of another lab, a blank name or a body that does not check (a question set's questions as the form's: ids, options, levels; each threshold naming one of its questions, between 0 and 1); 409 name_taken when the lab has a preset of that kind by that name. The body size is not limited.

Parameters

NameInDescription
labrequiredpath string

Request body required

application/json: object | object | object

namerequired string Unique among the lab's presets of its kind.

Responses

StatusDescription
200 OK.
application/json LabPresetView
Fields of LabPresetView
created_atrequired string
idrequired integer (int64)
labrequired LabKind
namerequired string
updated_atrequired string
default Error.
application/json ApiError
get/labs/api/{lab}/presets/{id}

Read a preset

Capability admin, open to: owner

One preset. 404 not_found for one that is not there or is another lab's.

Parameters

NameInDescription
labrequiredpath string
idrequiredpath integer

Responses

StatusDescription
200 OK.
application/json LabPresetView
Fields of LabPresetView
created_atrequired string
idrequired integer (int64)
labrequired LabKind
namerequired string
updated_atrequired string
default Error.
application/json ApiError
post/labs/api/{lab}/presets/{id}

Update a preset

Capability admin, open to: owner. Changes state.

Rewrites the preset whole, as a save checks it, and answers it, if it is still the one read: updated_at is the preset's as read, and 409 set_changed answers when it moved since (another edit, a threshold written; every write moves it). A question set's question the update changes (its type, options or levels, its text) loses its threshold's measurement, the value staying, not measured. The set runs that ran it keep their snapshot. 404 not_found for one that is not there, 400 bad_request and 409 name_taken as for a save. The body size is not limited.

Parameters

NameInDescription
labrequiredpath string
idrequiredpath integer

Request body required

application/json: object | object | object

namerequired string Unique among the lab's presets of its kind.
updated_atrequired string The preset's updated_at as read: when it has moved since (another
edit, a threshold written), the update is a 409 set_changed.

Responses

StatusDescription
200 OK.
application/json LabPresetView
Fields of LabPresetView
created_atrequired string
idrequired integer (int64)
labrequired LabKind
namerequired string
updated_atrequired string
default Error.
application/json ApiError
post/labs/api/{lab}/presets/{id}/delete

Delete a preset

Capability admin, open to: owner. Changes state.

Deletes the preset and answers the lab's presets after it. The set runs that ran it keep their snapshot and their results. 404 not_found for one that is not there or is another lab's.

Parameters

NameInDescription
labrequiredpath string
idrequiredpath integer

Responses

StatusDescription
200 OK.
application/json LabPresetList
Fields of LabPresetList
presetsrequired array of LabPresetView
default Error.
application/json ApiError
get/labs/api/{lab}/usage

Read what a lab keeps

Capability admin, open to: owner

The counts of the lab's groups (the history's and the set runs' items), set runs, runs and artifact rows, the distinct files those rows name, the stored text's size (titles, forms, plans, overrides, expected answers, requests, responses and headers, the set runs' sets and mappings, in bytes) and the files' size. orphan_files and orphan_bytes count the artifacts directory's files that no row of any lab names, left by a crash between a write and its commit or a commit and its unlink.

Parameters

NameInDescription
labrequiredpath string

Responses

StatusDescription
200 OK.
application/json LabUsage
Fields of LabUsage
artifact_bytesrequired integer (uint64) The size of the distinct files the lab's rows name.
artifact_filesrequired integer (uint64) The distinct files those rows name.
artifactsrequired integer (uint64) Artifact rows: each input of a group and output of a run.
batchesrequired integer (uint64) The set runs; their items are among groups.
groupsrequired integer (uint64) Every group: the history's and the set runs' items.
labrequired LabKind
orphan_bytesrequired integer (uint64)
orphan_filesrequired integer (uint64) Files in the artifacts directory that no row of any lab names (left
by a crash between a write and its commit); removable with
POST /labs/api/{lab}/orphans/delete.
runsrequired integer (uint64)
text_bytesrequired integer (uint64) The stored text: each group's title, form, plan, override and
expected answers, each run's request, response and headers, each set
run's set and mapping, in bytes.
default Error.
application/json ApiError

Agents

get/api/agents

List agents

Capability admin, open to: owner

Every agent in the catalog, with its warnings, requirements and last-run summary.

Responses

StatusDescription
200 OK.
application/json array of AgentCard
Fields of AgentCard
apprequired boolean This agent declares run.service, so it serves an app of its own — the card's
app chip, and a link to the App tab.
descriptionrequired string
effective_modelrequired string
enabledrequired boolean
errorrequired string | null Set when the stored manifest could not be read at all — a row written
by a newer build. The card still lists, saying why, rather than the
whole catalog failing.
idrequired string
kindrequired string The manifest's run.kind: chat, batch or container. Empty for a
row whose stored manifest could not be read (error says why).
labelsrequired array of string The tool labels this agent attaches, in manifest order.
last_runrequired AgentRunSummary | null
model_aliasrequired string The manifest's model alias, template and all — usually
{{config.model}}, in which case effective_model says what the
stored config resolves it to.
namerequired string
requiresrequired array of AgentRequirement
requires_okrequired boolean Every label resolves and every narrowed tool name is currently listed.
sourcerequired string builtin, imported or authored.
threadsrequired integer (int64) Threads a chat agent has opened.
versionrequired string Free text from the manifest, informational.
warningsrequired array of AgentWarning Warnings that are not tool gaps.
default Error.
application/json ApiError
post/api/agents/import

Import an agent

Capability admin, open to: owner. Changes state.

Imports an agent from an exported manifest file (paste uses this same route). replace overwrites an id that already exists; validate_only runs the checks and reports without writing.

Parameters

NameInDescription
replacequery string | null
validate_onlyquery string | null

Request body required

application/json: string (binary)

Responses

StatusDescription
200 OK.
application/json AgentImportReport
Fields of AgentImportReport
config_unboundrequired array of string Mount slots this agent has and nothing has bound: an
export never carries a host path, so an imported agent arrives with its
directory and file fields empty and the importer says which folder.
dropped_configrequired array of string Stored config keys the **new** manifest no longer declares, removed with
the manifest that declared them (the same rule applies to every replace). Keeping them
would leave a row that fails validation
on every run and cannot be fixed from its own config form.
idrequired string
okrequired boolean
replacedrequired boolean An existing agent was overwritten (replace=1), keeping its config.
requiresrequired array of AgentRequirement
validate_onlyrequired boolean validate_only=1: the same report, nothing written.
warningsrequired array of string A missing server label or tool: the agent is saved, Start is disabled.
default Error.
application/json ApiError
get/api/agents/{id}/export

Export an agent

Capability admin, open to: owner

Downloads the agent as <id>.agent.json: its manifest plus an envelope (export time, lmgw version, portability, the names of the secret and folder fields left out, and — with include_config=1 — the non-secret config values). A secret never leaves; the file imports back unchanged.

Parameters

NameInDescription
idrequiredpath string
include_configquery string | null

Responses

StatusDescription
200 OK.
application/json AgentExport
Fields of AgentExport
config_omitted array of string The secret config fields left out, so the receiver knows what to
fill in. Absent when there are none.
config_unbound array of string The folder and file slots left out: they are paths on the exporting
machine, so the receiver chooses its own. Absent when there are none.
config_values object The non-secret config values; only with include_config=1.
exported_atrequired string RFC 3339 time of the export.
lmgw_versionrequired string The lmgw version that wrote the file.
portabilityrequired AgentPortability Whether the file runs on another machine as it is, and what the
receiver would have to do if not.
default Error.
application/json ApiError

Device API

Chat

The Chat API a client app uses as a paired device (the chat capability), with its client certificate on the device listener: the threads and folders it follows, an ongoing conversation's current thread, and the change feed that keeps them current. Every route here refuses a device with 401 device_key_unknown once its key opens no device (it was replaced or deleted: pair the device again), 403 device_unconfirmed until the owner confirms its enrolment, 401 device_disabled while the device is disabled, 401 device_certificate_expired past its certificate's notAfter, and 401 key_expired past its expiry date. What is open when that happens ends: the feed with revoked, a turn's stream with an error event whose code is revoked. Both carry kind, what to do: device_disabled and key_expired wait for the gateway's side, key_unknown and certificate_expired mean pair the device again, and revoked is any other kind of key's revocation.

get/chat/api/attachments/{id}

Read an attachment's bytes

Capability chat, open to: device, owner

The stored file as uploaded, with the media type the bytes were sniffed as (image/png, application/pdf, audio/wav, ...); a text file is served as text/plain; charset=utf-8. The answer carries X-Content-Type-Options: nosniff and Content-Security-Policy: sandbox, so a file opened in a browser cannot run anything, and Accept-Ranges: bytes. One Range (bytes=a-b, bytes=a- or bytes=-n) answers 206 with Content-Range, as a media player resumes or seeks; a Range lmgw does not read (several ranges, another unit), or any If-Range, serves the whole file. 416 range_not_satisfiable, with Content-Range: bytes */size, for a range that names no byte of the file. 404 not_found for an attachment that is not there or not the caller's.

Parameters

NameInDescription
idrequiredpath integer

Responses

StatusDescription
200 OK.
*/* string (binary)
default Error.
application/json ApiError
post/chat/api/attachments/{id}/delete

Delete a draft attachment

Capability chat, open to: device, owner. Changes state.

Removes an attachment that was not sent yet. 404 not_found for one that is not there or not the caller's; 409 attachment_sent once it was sent with a message (it belongs to that message then).

Parameters

NameInDescription
idrequiredpath integer

Responses

StatusDescription
200 OK.
application/json Ack
Fields of Ack
okrequired boolean Always true; a failure is an error answer instead.
default Error.
application/json ApiError
post/chat/api/attachments/{id}/media

Run an image card's action

Capability chat, open to: device, owner. Changes state.

Runs one action on a picture of a thread, directly — no chat model is called: reroll draws it again with the same prompt and settings and a new seed (an edit is made again from the picture it started from), vary makes a variation of it on a model without instruction edits and edit changes it by an instruction on a model with them (prompt defaults to the picture's own, strength to its own for vary), upscale runs an ESRGAN upscaler (upscaler: a file stem of the image models dir's upscalers/, the server's first one when omitted; repeats 1 to 4) on a local image model — a resident one that can upscale, preferring the one that made the picture, else that one, else the smallest. The model rows are the caller's. The answer is SSE: action first (call_id act-<boot>-<n>, unique across restarts, the action, the model, the source attachment), progress frames while it runs (lossy: a newer one supersedes an older), then done with the stored picture's attachment metadata and a sentence about it, or error. The picture is stored as an attachment of the thread with source action, bound to the source's message, its meta.media naming parent; it is not shown to the thread's model, nor named to it by att:N, unless the user attaches it (a copy as an upload). The action goes on when the stream is closed; a key that is revoked stops it and ends the stream with an error frame (code revoked), a gateway that stops ends the stream with code gateway_stopping; a thread deleted or kept as a stored chat while it runs stops it, its error code thread_gone, and nothing of it is kept. An upscale whose result would exceed the chosen image model's max_upscale_width/height is refused with too_large, naming the numbers. Refused before any frame: 404 not_found for an attachment that is not there or not the caller's, 422 not_an_image, 409 not_sent for a picture of no message yet (a draft, a reply still being written), 422 no_model, model_unavailable, not_rerollable, source_missing, wrong_action, prompt_required, no_upscaler, no_image_model, unknown_upscaler or bad_request for what the picture or the body lacks.

Parameters

NameInDescription
idrequiredpath integer

Request body required

application/json: object

actionrequired MediaAction
prompt string vary and edit: the prompt, the source's own when omitted.
repeats integer (uint32) upscale: how many times to run it, 1 to 4 (sd-server's bound).
strength number (double) vary: how far to move from the picture, 0 to 1; the source's own
when omitted, else the row's default.
upscaler string upscale: the upscaler's name (a file stem of the image models dir's
upscalers/); the server's first compatible one when omitted.

Responses

StatusDescription
200 An event stream.
text/event-stream string
4 event types

action MediaActionStarted
The action stream's first frame (event: action): the id the action
runs under — what its progress frames carry as call_id, and what the
media cancel route takes — and the model it runs on.

actionrequired string reroll, vary, edit or upscale.
call_idrequired string act-<boot>-<n>: <boot> 32 random bits (eight hex digits) drawn
once per gateway process, <n> a counter, so a later process repeats
an id only if it draws the same bits.
model string The model the action runs on (image/z-image-turbo); absent for an
upscale, whose row the gateway picks when it runs (its done names
it).
sourcerequired integer (int64) The attachment the action started from.

done MediaActionDone
The action's last frame on success (event: done): the picture it made,
stored as the thread's attachment (source = "action", bound to the
source's message, meta.media.parent the source), and a sentence about
it.

attachmentrequired AttachmentMeta
call_idrequired string
textrequired string What happened, in words: Made image att:58 (1024x1024) with ….

error ErrorFrame
error: something went wrong; the stream goes on to done. code is
what a client branches on (gpu_hold, context_length_exceeded,
vram_queue_timeout, not_saved, superseded, ...); a failure that has
none sends only the message. A stream whose key was disabled, rotated,
deleted or expired, or whose gateway stops, ends with a last error
frame instead of done: revoked (with kind) or gateway_stopping.
An MCP label the thread or its folder attached that offers the turn no
tools gets one frame each, with server_label and a LabelCode
(tool_unreachable, tool_offline, tool_disabled, tool_unknown,
tool_failed), and the turn goes on without it.

code string
kind RevokeKind What a client does about a revoked frame, the token a realtime
session's 4003 close starts its reason with (key_unknown means pair
the device again). Sent with revoked only.
messagerequired string
server_label string The MCP label the frame is about, as the thread or folder attached
it; sent with a LabelCode only.

progress ToolProgressFrame
The progress event of a tool frame: a running image or audio call's
stage, step and latest preview. Lossy: a reader that falls behind misses
some (the next one supersedes them), and they are not in the change
feed.

call_idrequired string The call's id, as its ready frame carries it.
cancel CancelKind What a cancel would do now, while an image job runs; absent before
the job exists (a cancel then just stops the wait) and for audio.
done_bytes integer (uint64) downloading: compressed bytes downloaded so far.
elapsed_msrequired integer (uint64) Since the call started.
free_bytes integer (uint64) waiting_for_room: the memory free when it was last measured.
image string downloading: the image reference being downloaded.
model string The model the phase is about: the one being unloaded for
unloading, the call's own otherwise.
needs_bytes integer (uint64) waiting_for_room: the memory the model needs, headroom included.
pass integer (uint32) The sampling pass (a batch item, a high- or low-noise stage, a hires
pass); a new pass starts its steps again.
phaserequired MediaPhase | null
preview string The latest preview as the image server drew it: base64, PNG. Its
pixel size depends on the row's preview mode (a quick sketch is the
latent's size, an eighth of the picture's side on the spike's
pipeline).
queue_position integer (uint32) queued: the job's place in the image server's queue.
size_note string downloading: why the size is not known, when it is not ("size not
known — …").
step integer (uint32)
total_bytes integer (uint64) downloading: the download's whole size; absent when it is not
known.
total_steps integer (uint32)
default Error.
application/json ApiError
post/chat/api/attachments/{id}/mode

Choose how a PDF is sent

Capability chat, open to: device, owner. Changes state.

Sets how a PDF whose every page has text goes to the model: mode text sends the extracted text, images sends the pages as images. Drafts only. 400 bad_request for another mode, 404 not_found for an attachment that is not there or not the caller's, 409 attachment_sent once it was sent, 422 mode_not_applicable for any file but a text-class PDF (scanned and hybrid ones, and every other kind, are sent automatically).

Parameters

NameInDescription
idrequiredpath integer

Request body required

application/json: object

moderequired string text sends the PDF's extracted text, images its pages as
images. One of text, images.

Responses

StatusDescription
200 OK.
application/json ModeSet
Fields of ModeSet
idrequired integer (int64) The attachment.
moderequired string The mode now set, text or images.
okrequired boolean Always true; a refusal is an error answer instead.
default Error.
application/json ApiError
get/chat/api/attachments/{id}/text

Read what the model reads of an attachment

Capability chat, open to: device, owner

A text file as it is, a PDF's or office file's extracted text, or an audio file's transcript, as text/plain; charset=utf-8, with X-Content-Type-Options: nosniff and Content-Security-Policy: sandbox. 404 not_found for an attachment that is not there or not the caller's, and 404 no_text for an image, or an audio file with no transcript yet.

Parameters

NameInDescription
idrequiredpath integer

Responses

StatusDescription
200 OK.
text/plain; charset=utf-8 string (binary)
default Error.
application/json ApiError
post/chat/api/attachments/{id}/transcribe

Transcribe an audio draft again

Capability chat, open to: device, owner. Changes state.

Runs the speech-to-text call again for an audio draft, after it failed at upload or once a model is set, and answers the attachment's new meta (the transcript's alias and token estimate in place of transcript_error). The body is empty. 404 not_found for an attachment that is not there or not the caller's, 409 attachment_sent once it was sent, 422 not_audio for any other kind, 422 stt_not_set when no speech-to-text model is set for the thread, 422 transcription_failed with the call's own message.

Parameters

NameInDescription
idrequiredpath integer

Responses

StatusDescription
200 OK.
application/json Transcribed
Fields of Transcribed
idrequired integer (int64) The attachment.
metarequired AttachmentFacts The attachment's meta now, the transcript's alias and token
estimate in place of the earlier transcript_error. The same object
as AttachmentMeta::meta.
okrequired boolean Always true; a refusal is an error answer instead.
default Error.
application/json ApiError
get/chat/api/export

Export every chat

Capability chat, open to: device, owner

A zip with one file per stored thread, in the format asked for (md or json, as for one thread), a directory per folder named after it, and a README.txt. archived=0 takes the active threads, 1 the archived ones, all (the default) both; another value is a 400 bad_request, as is a format other than md, markdown or json. The answer carries Content-Disposition: attachment (lmgw-chats-{date}.zip), Content-Length and Cache-Control: no-store; it is as large as the Chat is and not capped. Temporary threads are not part of a zip. A device key's zip leaves out Admin Chat threads.

Parameters

NameInDescription
archivedquery string
formatquery string

Responses

StatusDescription
200 OK.
application/zip string (binary)
default Error.
application/json ApiError
get/chat/api/feed

Follow the Chat's changes

Capability chat, open to: device, owner

One SSE stream per client. hello first: the epoch, the cursor the stream continues from, the keep-alive interval and the retention, who the feed is for, the hold, the turns and voice sessions live now, and open_approvals: every call still waiting for a decision at that cursor in a thread the reader may see (a thread's last reply's open calls), each as approval.requested renders it. For a device, hello also carries its own facts: urls (its row's lmgw URLs, https, in the owner's order: replace the stored list with them), cert ({not_after, notice_after}, RFC 3339 UTC, the dates of its certificate: show the notice from them) and dashboard_url (where the dashboard is, as a URL derived from bind_addr: sent to a device paired as this computer, and to any other only when bind_addr is not loopback; null otherwise). A device's feed also sets TCP_USER_TIMEOUT on its connection to its keep-alive, so a keep-alive a vanished device never acknowledges ends the stream within one more interval. Then stored events (thread.*, folder.*, folder.current, message.*, profile.*, approval.*, task.*, device.revoked), each with an id: that is its cursor "<epoch>:<seq>:<tag>" (opaque: hand it back as it came), rendered as the thread or folder is when it is delivered (message.added and message.updated carry the thread's id, its title now (thread_title) and the messages the change wrote, whole, as GET /chat/api/threads/{id} lists them now — a user message as stored, a reply once saved (never while it streams), a task result entering the thread, an edit, a continue, a resumed turn, a spoken reply cut to what was heard or annotated, a stored retrieval, a call a reply waits on decided — so a client shows the message or a notification without a fetch; a message gone by delivery is left out, and an event whose messages or thread are all gone is not sent; message.deleted names the ids that went (a delete, the cut of an edit's resend or a regenerate, a spoken reply nobody heard); a thread deleted whole is thread.deleted alone; a profile.* event names the profile's id and name as its write left them; every reader receives it, devices included; approval.requested and approval.decided name a call a turn waits on and its decision, with the call's call_id as the turn's ready, approval and result frames carry it, rendered from the reply (approval.requested with the thread's title now, thread_title, so a client shows it or a notification without a fetch), and are not delivered once the reply is gone (approval.requested neither once its call is decided: the decision follows); task.started names an MCP task a turn's tool call started, task.done its result entering the thread as a message of role tool, both as their write left them; device.revoked names a paired device whose key was deleted, as {kind: device, name}, so a client running work it started (a host of its MCP tasks) may cancel that work — the owner receives every one, a device only one about a device the feed showed it changes of, or that started a task it hosts that was still running; a disable, a rotate or an expiry is no delete and says nothing); and live events (turn.*, voice.*, hold, state, caught_up), which have no id. caught_up {cursor} comes once per stream, when every stored event up to the cursor hello named has been delivered (or passed as not for this reader): right after hello, and the resync and profile list a cursor may owe, when there was nothing to catch up, else right after the catch-up's last event. The approval.* events before it are already reflected in hello.open_approvals; from caught_up on, approval.requested adds to that set and approval.decided removes from it, as does the deletion of its thread or its reply. Every state carries open_approvals again, read when it is sent, and replaces that set, matched by approval_request_id (null when lmgw could not read it for a state sent for another reason: keep the set you have; one sent because the set moved ends the stream instead, and the reconnect's hello carries it); the feed sends one after any move of what a device may see, after a thread or folder came into a device's reach (its *.created), and after a resync that passed records — before caught_up when the retention pruned past a stream still catching up, so caught_up hands over the true set. Open the feed first, then load the list: a turn in hello may name a thread whose thread.created follows in the catch-up. Resume with ?since=<cursor> or Last-Event-ID (which wins: a browser reconnects with the URL it opened). A cursor the feed cannot honour — another database's, one whose event is not the one the gateway holds at that number now (its data restored from an older copy), older than the retention, newer than the newest — gets resync with the reason, then events from now; so does a stream still catching up when the retention prunes past it, and one at an event that cannot be read after a few attempts. Every resync is followed by the whole profile list again, as profile.created events without an id. A client that reads live events slower than they happen, past the live buffer, gets state instead of the events it missed. Keep-alive comments every keepalive_s seconds: the stream's own when the request asks for one (?keepalive_s=, from 1 to chat_feed_keepalive_max_s, Settings → Chat → Change feed → Longest keep-alive, default 900; outside that a 400 bad_request naming the bound and the setting), else the gateway's chat_feed_keepalive_s; hello.keepalive_s says which. Only the comments follow it: stored events are never held back by a long one. One may carry an id: and no data, which only moves the cursor. When the key is disabled, rotated, deleted or expires, revoked and the end. When the gateway shuts down, the stream ends without an event: reconnect with the last cursor once it is back. A device key never receives an event about an Admin Chat thread, nor about a folder a device deleted while it held threads the device could not see (until it is shown to devices again); and about a thread or folder with the self-admin toolset (lmgw) attached only while what the device's admin tools may do is above off (hello.self_admin: its level capped by the gateway's self-admin level). The gaps that leaves in the sequence are expected, and a thread in a folder the device does not see is in no folder for it. When a thread or folder leaves a device's reach (the toolset attached), the device receives its deletion, and a fresh state when that changed what is live for it; when it comes back (the toolset taken off, the folder shown again), its creation, and the same. When what the device's admin tools may do moves above off (its own level raised, or the gateway's self-admin level raised from off), the threads and folders with the toolset arrive as thread.created and folder.created (and its threads in such a folder as thread.updated), then a fresh state; when it moves to off, they go as thread.deleted and folder.deleted, in a delete's order, then a fresh state. state carries self_admin, what the device's admin tools may do now (its level capped by the gateway's self-admin level), and follows every change of the device's level and every change of the gateway's that moves it, so a connected device learns there that it changed. A device that resumes from a cursor older than a change above off or back gets resync at that point instead, and nothing about those threads and folders that it may not see now, or that was written while it could not see them: reload what you show.

Parameters

NameInDescription
keepalive_squery integer | null
sincequery string | null

Responses

StatusDescription
200 An event stream.
text/event-stream string
29 event types

approval.decided ApprovalDecided
approval.decided: a waiting call was decided — approved or declined
by a client, or declined because a new message came
(chat_approvals::MOVED_ON).

approval_request_idrequired string
approverequired boolean Whether the call was approved — and, once that is known, could run:
false with not_run for one approved whose turn could not
start.
byrequired string | null Who decided, as every author is named ("the dashboard", "device
'phone'").
call_id string The call's id, as approval.requested has it. Absent from an lmgw
before 2026-10-09.
message_idrequired integer (int64)
not_run boolean Approved, but the turn that was to run it could not start (its
reply moved on, its starter went, its slot was refused), so it never
ran and its result says so. Recorded as a second approval.decided
for the call; both render this.
thread_idrequired integer (int64)

approval.requested ApprovalRequested
approval.requested: a turn in the thread stopped on a call that waits
for an approval (client-apps design §6.5). Rendered from the reply's
pending state at delivery; a reply gone by then (deleted, regenerated),
or a call decided by then (its approval.decided follows),
is not delivered. With thread_title, server_label, name and
arguments a client shows it, or a notification, without a fetch. Also
the shape of Hello::open_approvals' entries.

approval_request_idrequired string
argumentsrequired string A JSON string.
call_id string The call's id, as the turn's ready, approval and result frames
carry it. Absent from an lmgw before 2026-10-09.
message_idrequired integer (int64) The reply that waits.
namerequired string The tool's own name, as chat_approvals::ApprovalRequest.
server_labelrequired string
thread_idrequired integer (int64)
thread_titlerequired string The thread's title at delivery (in hello, at the head it read).

caught_up CaughtUp
caught_up: the stream has delivered, or passed as not for this reader,
every stored event up to the head it opened at (Hello::cursor when
the client gave no cursor). Live, so no id:; sent once per stream: right
after hello (and the resync and profile list a cursor may owe) when
there was nothing to catch up, else right after the catch-up's last
event. From here on every approval.* changes Hello::open_approvals.

cursorrequired string Where the stream stands now ("<epoch>:<seq>:<tag>"): a client may
resume from it, as from a keep-alive's id:.

device.revoked DeviceRevoked
device.revoked: a paired device's key was deleted, so the device is
gone for good; a client that runs work it started — a host of MCP tasks
whose lmgw/caller named it — may cancel that work now (MCP Tasks
design §4.1; client-apps design §2.2). Its tasks' results still enter
their threads as they end.

Received by the dashboard and admin keys; by a device the feed showed
the deleted device's changes to (a stored event it may see carries the
deleted device's by), and by a device hosting a task the deleted
device started that was still running. No other device hears of it: it
names no device the reader was not shown.

Only a delete is said: a disabled or expired key can be enabled or
renewed again, and its tasks wait meanwhile; a rotated one keeps its
row and pairs again under its name; a cleared hosting grant ends the
device's own hosted tasks, each said by its task.done (abandoned).

byrequired string | null Who deleted it ("the dashboard").
devicerequired FeedPrincipal The deleted device, as Hello::principal names a device (kind
device, its paired name) and as lmgw/caller names it on a
forwarded call; FeedPrincipal::by is the by its changes
carried.

folder.created
The folder as GET /chat/api/folders lists it now (its counts as the reader may see them), with by beside its fields; or, when the folder is gone by the time the event is delivered, {folder_id, deleted: true, by}. deleted tells the two apart.

One of 2 shapes
any
any

folder.current FolderCurrent
folder.current: an ongoing folder's current thread moved.

byrequired string | null
folder_idrequired integer (int64)
previous_thread_idrequired integer | null
reasonrequired string Why it moved. To a new thread: first (the folder had none the
reader can reach), gone (its thread could no longer be continued
in it; only the dashboard and admin keys read this reason for a new
thread), idle (no message for the folder's idle minutes) or
requested (a client asked for a new thread, or created one in the
folder). To none: gone (the thread was deleted, moved out of the
folder or archived) or not_ongoing (the folder stopped being an
ongoing conversation).
thread_idrequired integer | null The current thread now; null when the folder has none any more.

folder.deleted FolderGone
folder.deleted, and folder.created / folder.updated for a folder
that is gone by the time the event is delivered.

byrequired string | null
deletedrequired boolean
folder_idrequired integer (int64)

folder.updated
The folder as GET /chat/api/folders lists it now (its counts as the reader may see them), with by beside its fields; or, when the folder is gone by the time the event is delivered, {folder_id, deleted: true, by}. deleted tells the two apart.

One of 2 shapes
any
any

hello Hello
The feed's first event.

certrequired HelloCert | null The dates of the certificate the device connected with (§5.3); null
on a feed that is not a device's.
cursorrequired string Where the stream continues from: the cursor the client resumed with,
or the newest record when it gave none (or one the feed answers with
resync).
dashboard_urlrequired string | null Where the dashboard is, for a client that offers to open it: the
plain listener's address as a URL (http://127.0.0.1:8001/), derived
from bind_addr. Sent to a device paired as "this computer"
(local_only) and to every other device when bind_addr is not
loopback, since a loopback address reaches nothing from another host.
null otherwise, and on a feed that is not a device's.
epochrequired string This database's epoch.
holdrequired FeedHold
hosts_labelrequired string | null The label a device may host MCP tools under; null without a
hosting grant, and on a feed that is not a device's.
keepalive_srequired integer (uint32) Seconds between keep-alive comments, fixed for this stream: the
keepalive_s the request asked for, else the gateway's
chat_feed_keepalive_s. A client derives its dead-link timeout from
it. Stored events are never held back for it: the stream reads the
table at the gateway's own interval whatever this one is.
open_approvalsrequired array of ApprovalRequested Every call still waiting for a decision at cursor, in the
threads this reader may see, oldest reply first and each reply's
calls in the model's order, as approval.requested renders it (the
thread's title as it was then). Read with the head, so it is the open
set there: the approval.* events of the catch-up up to caught_up
are already reflected in it; after caught_up, approval.requested
adds to it and approval.decided removes from it, as does the
thread's deletion or its reply's, and every state replaces it
(LiveState::open_approvals). A waiting call is one of the
thread's last message: a reply a later message followed waits no
more (a new message declines its calls).
principalrequired FeedPrincipal
retention_daysrequired integer (int64) How many days the feed keeps its records (chat_feed_retention_days,
0 = all): a client away longer gets a resync.
self_adminrequired AdminLevel What this device's admin tools may do now: off, read_only (read
lmgw's configuration and state) or full (also change it) — the
level set on the device, capped by the gateway's own self-admin
level. Above off the device sees the threads and folders that
carry the self-admin toolset (lmgw), and at full it may attach it
and change them; at read_only it reads them and sends to them only;
at off it sees none of them. When this value moves above off or back while
the feed is open, whether the device's level or the gateway's moved
it, those threads and folders arrive (*.created) or go
(*.deleted) in order. A state with this value follows any change
of the device's level, and any change of the gateway's that moves
this value. When this value moved above off or back within what a
resumed feed catches up, the feed sends resync at that point
instead: reload what you show. off on a feed that is not a
device's.
turnsrequired array of LiveTurn The turns running now.
urlsrequired array of string A device's lmgw URLs as its row holds them now: https base URLs in
the owner's order (device link design §7.2). The device replaces its
list with them (lmgw-client's refresh_urls). Empty on a feed that
is not a device's.
voicerequired array of LiveVoice The realtime sessions bound now.

hold FeedHold
The GPU hold: whether local models are paused. A held model answers with
its own fallback, where one is set (each thread's model says which). The
hold event and part of Hello.

activerequired boolean The owner's GPU hold is on: models on the graphics card are paused.
benchmarkrequired boolean A benchmark run holds the graphics card: every local model waits
until it ends, one on the CPU too, or answers with its fallback
(chat-plane design D6).

message.added MessagesChanged
message.added and message.updated: messages of a thread were written
(client-apps design §2.2). Added: a user message as it is stored (typed,
dictated or spoken in a bound session), a reply as it is saved, a late
MCP task result entering the thread (role tool). Updated in place: an
edit, a continue, a resumed turn saved onto its reply, a spoken reply
cut to what was heard or annotated with how it was spoken, a user
message's retrieval stored, a call the reply waits on decided (or
declined by a new message, or closed as not run). A reply still being
generated is in no event until it is saved: its tokens are the send
stream's.

Rendered at delivery, so a catch-up never replays a stale copy: each
message as GET /chat/api/threads/{id} lists it now, whole, so a client
shows it, or a notification, without a fetch. A message gone by then is
left out (its message.deleted follows), and an event whose messages
are all gone, or whose thread is, is not delivered. Two events may carry
the same state of a message: apply them by id.

byrequired string | null Who wrote them: the sender of a user message, the starter of the
turn whose reply it is, the client that edited one or decided a call,
the client whose voice session cut or annotated a spoken reply (that
session's, even after another client took the thread over); null
for the gateway's own (a task result entering the thread, a call
closed as not run).
messagesrequired array of Message The messages written, oldest first, each as the thread lists it now.
thread_idrequired integer (int64)
thread_titlerequired string The thread's title at delivery, so a notification names the
conversation without a fetch.

message.deleted MessagesDeleted
message.deleted: messages of a thread were deleted (client-apps design
§2.2): one by itself, every one after a point (an edit's resend, a
regenerate), or a spoken reply nobody heard. Their attachments went with
them. A thread deleted whole says so with thread.deleted alone.

byrequired string | null Who deleted them; null for the gateway's own.
message_idsrequired array of integer (int64) The messages that went, ascending.
thread_idrequired integer (int64)

message.updated MessagesChanged
message.added and message.updated: messages of a thread were written
(client-apps design §2.2). Added: a user message as it is stored (typed,
dictated or spoken in a bound session), a reply as it is saved, a late
MCP task result entering the thread (role tool). Updated in place: an
edit, a continue, a resumed turn saved onto its reply, a spoken reply
cut to what was heard or annotated with how it was spoken, a user
message's retrieval stored, a call the reply waits on decided (or
declined by a new message, or closed as not run). A reply still being
generated is in no event until it is saved: its tokens are the send
stream's.

Rendered at delivery, so a catch-up never replays a stale copy: each
message as GET /chat/api/threads/{id} lists it now, whole, so a client
shows it, or a notification, without a fetch. A message gone by then is
left out (its message.deleted follows), and an event whose messages
are all gone, or whose thread is, is not delivered. Two events may carry
the same state of a message: apply them by id.

byrequired string | null Who wrote them: the sender of a user message, the starter of the
turn whose reply it is, the client that edited one or decided a call,
the client whose voice session cut or annotated a spoken reply (that
session's, even after another client took the thread over); null
for the gateway's own (a task result entering the thread, a call
closed as not run).
messagesrequired array of Message The messages written, oldest first, each as the thread lists it now.
thread_idrequired integer (int64)
thread_titlerequired string The thread's title at delivery, so a notification names the
conversation without a fetch.

profile.created FeedProfile
profile.created, profile.updated and profile.deleted: a
personality profile (GET /chat/api/profiles) was created, changed or
deleted, named as that write left it. Every reader receives them,
devices included. After a resync the feed sends the whole list again
as profile.created events (with no id:), so a client that keeps the
names (a menu of profiles) has them again without a request.

byrequired string | null Who made the change; null for the gateway's own, and on the list
repeated after a resync.
idrequired integer (int64) The profile's id.
namerequired string

profile.deleted FeedProfile
profile.created, profile.updated and profile.deleted: a
personality profile (GET /chat/api/profiles) was created, changed or
deleted, named as that write left it. Every reader receives them,
devices included. After a resync the feed sends the whole list again
as profile.created events (with no id:), so a client that keeps the
names (a menu of profiles) has them again without a request.

byrequired string | null Who made the change; null for the gateway's own, and on the list
repeated after a resync.
idrequired integer (int64) The profile's id.
namerequired string

profile.updated FeedProfile
profile.created, profile.updated and profile.deleted: a
personality profile (GET /chat/api/profiles) was created, changed or
deleted, named as that write left it. Every reader receives them,
devices included. After a resync the feed sends the whole list again
as profile.created events (with no id:), so a client that keeps the
names (a menu of profiles) has them again without a request.

byrequired string | null Who made the change; null for the gateway's own, and on the list
repeated after a resync.
idrequired integer (int64) The profile's id.
namerequired string

resync Resync
resync: the cursor cannot be honoured; reload what you show. The
stream continues from now.

reasonrequired string

revoked Revoked
revoked: the key was disabled, rotated, deleted or expired; the stream
ends after it.

kindrequired RevokeKind What a client does about it, the token a realtime session's 4003
close starts its reason with: key_unknown means pair the device
again. Every event this gateway sends carries it. An event without it
(an older gateway's) is of an unknown kind, as a close reason without
a token is: tell the user the sentence in message.
messagerequired string The reason in a sentence: "device 'phone' was rotated — pair it
again".
reasonrequired string disabled, rotated, deleted or expired.

state LiveState
state: Hello's live part again. Sent when the stream could not
keep a client's live events in order — it read slower than they
happened past chat_feed_live_buffer, or the buffer was resized — and
to a device when what it may see or do changed: a thread it reaches took
or lost the self-admin toolset, its own admin-tools level moved, or the
gateway's self-admin level moved what its admin tools may do. Also after
a resync that passed records (the retention pruned past a stream still
catching up, which gets it before caught_up; a change that could not be
read, after caught_up), and to a device after a thread or folder came
into its reach after caught_up (its *.created), so the open
approvals in it arrive.
Stored events are never lost; reason says what happened and names the
setting.

holdrequired FeedHold
open_approvalsrequired array | null The calls waiting for a decision as they are when this state is
sent, in the threads this reader may see now, as
Hello::open_approvals lists them: they replace the set a client
keeps. Read at sending, which may be a little past the stream's
cursor: match by approval_request_id, and an approval.* event
that follows changes nothing it already says. null when lmgw
could not read them for a state sent for another reason (a lag, a
resize, a refresh of what is live; said in its log): keep the set
you have. A state sent because the set may have moved never says
null: lmgw ends the stream instead, and the reconnect's hello
carries the set.
reasonrequired string | null
self_adminrequired AdminLevel Hello::self_admin as it is now: a device learns here that what
its admin tools may do moved while the feed is open.
turnsrequired array of LiveTurn
voicerequired array of LiveVoice

task.done TaskDone
task.done: a task's result entered the thread as message message_id
(role tool). by names who cancelled it, for a cancel lmgw sent;
null otherwise.

byrequired string | null
idrequired integer (int64)
message_idrequired integer (int64) The result row.
server_labelrequired string
statusrequired string completed, failed, cancelled or abandoned. One of completed, failed, cancelled, abandoned.
task_idrequired string
thread_idrequired integer (int64)
toolrequired string

task.started TaskStarted
task.started: a tool call of a turn in the thread became an MCP task
(MCP Tasks design §4.1); its result enters the thread later. Named as
the write left it, so it renders after the task is gone.

byrequired string | null Who started the turn that called it.
idrequired integer (int64) lmgw's id of the task (the cancel route's {task}).
server_labelrequired string
task_idrequired string The server's id of the task.
thread_idrequired integer (int64)
toolrequired string The name the model called.

thread.created
The thread as GET /chat/api/threads lists it now, with by beside its fields; or, when the thread is gone by the time the event is delivered, {thread_id, deleted: true, by}. deleted tells the two apart.

One of 2 shapes
any
any

thread.deleted ThreadGone
thread.deleted, and thread.created / thread.updated for a thread
that is gone by the time the event is delivered.

byrequired string | null Who made the change; null for the gateway's own (the sweep).
deletedrequired boolean
thread_idrequired integer (int64)

thread.updated
The thread as GET /chat/api/threads lists it now, with by beside its fields; or, when the thread is gone by the time the event is delivered, {thread_id, deleted: true, by}. deleted tells the two apart.

One of 2 shapes
any
any

transfer.updated Transfer
A transfer, as every route and transfer.updated answer it.

app_idrequired string The app id the offer names; the receiver declared it at pairing.
created_atrequired string RFC 3339 UTC.
end_reasonrequired string | null Why it ended, a sentence for people ("not delivered within 7 days of
the offer", "canceled by device 'phone'"), naming no setting and no
raw time; null while in progress and once delivered. state is
what a client acts on.
ended_atrequired string | null When it ended (RFC 3339 UTC); null while in progress.
expires_atrequired string When it expires unless delivered first (RFC 3339 UTC):
devices.transfer_expiry_days after the offer.
filenamerequired string The receiver's name for the file.
fromrequired TransferParty
idrequired string Opaque: 32 random lowercase hex digits.
kindrequired string The app's own word for what the file is.
receivedrequired integer (uint64) Bytes lmgw holds: the resume point while uploading (the next
upload's range starts here), size from ready on, and how far it
got for one that ended before.
sha256required string The file's sha256, 64 lowercase hex digits; checked when the last
byte arrives.
sizerequired integer (uint64) The file's size in bytes.
staterequired TransferState
titlerequired string What the card and the receiver show; may be empty.
torequired TransferParty

turn.done TurnDone
turn.done: how a turn ended.

coderequired string | null The code of the last error the turn reported (superseded,
gpu_hold, not_saved, …); null when it reported none.
message_idrequired integer | null The reply row it saved or continued; null when it saved none.
savedrequired boolean
thread_idrequired integer (int64)

turn.started TurnStarted
turn.started.

byrequired string
thread_idrequired integer (int64)
voicerequired boolean A bound realtime session's voice turn.

voice.bound VoiceBound
voice.bound: a realtime session bound to the thread.

byrequired string
thread_idrequired integer (int64)

voice.ended VoiceEnded
voice.ended: a bound session let its thread go.

byrequired string Who had bound the session that ended.
reasonrequired string closed, taken_over, thread_gone (its thread was deleted while
it was bound; a device's feed does not receive this event for a
deleted thread, only its thread.deleted, as for a thread taken out
of its reach) or revoked (the binder's key was revoked, or the
thread was taken out of the binding device's reach).
taken_over_byrequired string | null Who took it over, for taken_over.
thread_idrequired integer (int64)
default Error.
application/json ApiError
get/chat/api/folders

List the Chat's folders

Capability chat, open to: device, owner

Every folder in the list's order: its defaults (what a new thread in it starts with), whether it is one ongoing conversation and which thread is current, its own retention, and its thread counts as the caller may see them. Folder names need not be unique, so a client that looks its folder up by name keeps the id it found.

Responses

StatusDescription
200 OK.
application/json FolderList
Fields of FolderList
foldersrequired array of Folder In the list's order.
default Error.
application/json ApiError
post/chat/api/folders

Create a folder

Capability chat, open to: device, owner. Changes state.

A new folder, last in the list, answered as the list carries it. ongoing marks it as one ongoing conversation, which needs a model in its defaults: without one the answer is a 400 naming defaults.model_alias. A device key writes only within its own scopes: a tool server or knowledge base its tool scope does not reach is a 403 tool_label_out_of_scope, an alias outside its alias scope a 403 key_scope, and the self-admin toolset (lmgw) is its to attach only when its admin tools are full: below that the answer is a 403 chat_toolset_needs_full, or tool_label_out_of_scope when they are off. A device key only tightens require_approval: a rule that gates fewer calls than the stored one or the owner's last (its floor, which a removed entry keeps) is a 403 approval_loosen_refused, naming the label and the tool; a turn runs each server under the strictest of its entries and that floor. For every caller, two mcp_tools entries that name one server (its tool prefix and its name) or a require_approval of another shape than OpenAI's are a 400 bad_request where the write changed the entry; labels are stored trimmed. A device key cannot set archive_days or purge_days (403 forbidden, naming the fields): a folder's own retention is set from the dashboard.

Request body required

application/json: object

archive_days integer | null Days without activity before one of its threads is archived; absent
for the Chat's setting, 0 never. A device key cannot set it (403
forbidden): a folder's own retention is set from the dashboard.
defaults ThreadDefaultsInput | null
namerequired string
ongoing OngoingInput | null Marks the folder as one ongoing conversation; its defaults must then
name a model.
purge_days integer | null Days after archiving before one of its threads is deleted; absent
for the Chat's setting, 0 never. A device key cannot set it, as
archive_days.

Responses

StatusDescription
200 OK.
application/json Folder
Fields of Folder
archive_daysrequired integer | null Days without activity before one of its threads is archived; null
for the Chat's setting, 0 never. Set from the dashboard: a device
key cannot change it.
created_atrequired string
defaultsrequired ThreadDefaults
devices_hiddenrequired boolean Set when a device deleted this folder while it held threads that
device could not see: the folder stays for them, hidden from every
device, until it is shown to devices again from the dashboard. Always
false for a device key, which never sees such a folder.
idrequired integer (int64)
namerequired string Folder names need not be unique.
ongoingrequired FolderOngoing | null null for a folder that is not one ongoing conversation.
purge_daysrequired integer | null Days after archiving before one of its threads is deleted; null
for the Chat's setting, 0 never. Set from the dashboard: a device
key cannot change it.
sortrequired integer (int64) The folder's place in the list.
threads_activerequired integer (int64)
threads_archivedrequired integer (int64)
updated_atrequired string
default Error.
application/json ApiError
post/chat/api/folders/{id}

Change a folder

Capability chat, open to: device, owner. Changes state.

A patch: a field left out is unchanged. Answers the folder as the list carries it, with applied: for an ongoing-conversation folder whose defaults changed (and apply_to_current not false), the current thread and the settings that reached it, otherwise null. The folder's other threads are never touched. defaults replaces the defaults whole; defaults_patch changes the fields it names (null unsets one) so a client never writes back what another changed meanwhile; both together are a 400 bad_request. ongoing needs a model in the defaults. What reaches the current thread passes the checks of a thread settings write, and a field the thread refuses fails the whole patch. A device key's default mcp_tools pass its tool scope, as on a folder create; it cannot set archive_days or purge_days, nor devices_hidden (403 forbidden). devices_hidden: false shows a folder to devices again that a device's delete hid from them; true is a 400. A folder the caller cannot see is a 404 not_found.

Parameters

NameInDescription
idrequiredpath integer

Request body required

application/json: object

apply_to_current boolean For an ongoing folder: also apply the defaults' changes to its
current thread. Default true.
archive_days integer | null The folder's own retention in days before an inactive thread is
archived; null goes back to the Chat's setting, 0 never. A device
key cannot set it (403 forbidden).
defaults ThreadDefaultsInput | null Replaces the folder's defaults whole ({} clears them). Not beside
defaults_patch.
defaults_patch ThreadDefaultsInput | null Changes the defaults field by field instead: each field given
replaces the stored one (null unsets it), the others stay as
stored, so a save of the fields one client changed never writes back
what another changed meanwhile. voice is laid field by field the
same way (voice: null unsets the whole voice). Not beside
defaults.
devices_hidden boolean | null false shows a folder that a device's delete hid from devices to
them again; the owner's alone. true is refused (400): a device's
delete is what hides a folder.
name string | null The new name; names need not be unique.
ongoing OngoingInput | null An object marks the folder as one ongoing conversation (or changes
its idle minutes; its defaults must name a model); null ends that.
purge_days integer | null Days after archiving before a thread is deleted; as archive_days.
sort integer | null The folder's place in the list.

Responses

StatusDescription
200 OK.
application/json FolderPatched
Fields of FolderPatched
appliedrequired AppliedToCurrent | null For an ongoing folder whose defaults changed: the current thread
and the settings that reached it; null otherwise.
archive_daysrequired integer | null Days without activity before one of its threads is archived; null
for the Chat's setting, 0 never. Set from the dashboard: a device
key cannot change it.
created_atrequired string
defaultsrequired ThreadDefaults
devices_hiddenrequired boolean Set when a device deleted this folder while it held threads that
device could not see: the folder stays for them, hidden from every
device, until it is shown to devices again from the dashboard. Always
false for a device key, which never sees such a folder.
idrequired integer (int64)
namerequired string Folder names need not be unique.
ongoingrequired FolderOngoing | null null for a folder that is not one ongoing conversation.
purge_daysrequired integer | null Days after archiving before one of its threads is deleted; null
for the Chat's setting, 0 never. Set from the dashboard: a device
key cannot change it.
sortrequired integer (int64) The folder's place in the list.
threads_activerequired integer (int64)
threads_archivedrequired integer (int64)
updated_atrequired string
default Error.
application/json ApiError
post/chat/api/folders/{id}/current

Get an ongoing conversation's current thread

Capability chat, open to: device, owner. Changes state.

The thread every client of an ongoing-conversation folder continues in. A new one starts when the folder has none the caller can reach (first), when no message came for the folder's idle minutes while no turn runs there (idle), or on new: true (requested) — except that a current thread with no message yet is answered instead, so no empty threads pile up. The body may be left out: it is new: false. A new thread starts from the folder's defaults, and every client hears of it as the feed's folder.current. Two clients asking at once get the same thread. A folder that is not an ongoing conversation is a 409 not_ongoing, one whose defaults name no model a 409 folder_no_model, and one the caller may not see a 404.

Parameters

NameInDescription
idrequiredpath integer

Request body

application/json: object

new boolean Start a new thread now. A current thread without any message is
answered instead, so no empty threads pile up. Default false.

Responses

StatusDescription
200 OK.
application/json CurrentThread
Fields of CurrentThread
noterequired string | null The same in a sentence that names the folder setting behind it (the
idle minutes, for idle); null when this call did not start it.
reasonrequired CurrentReason | null Why this call started it; null when it did not.
rolled_overrequired boolean Whether this call started it.
threadrequired Thread The current thread, as GET /chat/api/threads/{id} answers its
thread.
default Error.
application/json ApiError
post/chat/api/folders/{id}/delete

Delete a folder

Capability chat, open to: device, owner. Changes state.

threads: keep leaves the folder's threads in no folder, threads: delete deletes them with it; there is no default for destroying conversations. A device key's delete touches only the threads it can see: a folder that also holds Admin Chat or self-admin threads it cannot reach stays for them, hidden from every device from then on, and the answer is the same ok. A folder the caller cannot see is a 404 not_found.

Parameters

NameInDescription
idrequiredpath integer

Request body required

application/json: object

threadsrequired ThreadsFate

Responses

StatusDescription
200 OK.
application/json Ack
Fields of Ack
okrequired boolean Always true; a failure is an error answer instead.
default Error.
application/json ApiError
get/chat/api/folders/{id}/export

Export a folder

Capability chat, open to: device, owner

A zip with one file per stored thread of the folder, in the format asked for (md or json, as for one thread), and a README.txt. archived=0 takes the active threads, 1 the archived ones, all (the default) both; another value is a 400 bad_request, as is a format other than md, markdown or json. The answer carries Content-Disposition: attachment (lmgw-folder-{name}-{date}.zip), Content-Length and Cache-Control: no-store; it is as large as the folder is and not capped. Temporary threads are not part of a zip. A device key's zip leaves out Admin Chat threads; a folder that is not there, or not the caller's to see, is a 404 not_found.

Parameters

NameInDescription
idrequiredpath integer
archivedquery string
formatquery string

Responses

StatusDescription
200 OK.
application/zip string (binary)
default Error.
application/json ApiError
get/chat/api/knowledge/bases

List the knowledge bases a thread may search

Capability chat, open to: device, owner

Every knowledge base with its file counts and whether its embedding model still resolves (without one a search is by keyword only), for a thread's Knowledge section and the composer's # picker. A thread's bases are its own choice, so a base's MCP visibility does not narrow the list. A device key reads the bases only with kb__search within its tool scope, the tool a thread's base is searched with: without it the answer is 403 tool_label_out_of_scope, naming the tool and no base.

Responses

StatusDescription
200 OK.
application/json ChatKnowledgeBases
Fields of ChatKnowledgeBases
basesrequired array of ChatKnowledgeBase
default Error.
application/json ApiError
get/chat/api/knowledge/files/{id}/original

Download a knowledge file's original

Capability chat, open to: device, owner

The uploaded bytes, with the media type they were sniffed as and Content-Disposition: attachment under the file's name (an ASCII fallback plus the RFC 5987 filename*). The owner's: a device key is refused (403 forbidden, said before the file is looked up), since the original carries more than any kb tool hands out; it reads the extracted text. 404 not_found for a file that does not exist or whose original is gone from disk.

Parameters

NameInDescription
idrequiredpath integer

Responses

StatusDescription
200 OK.
*/* string (binary)
default Error.
application/json ApiError
get/chat/api/knowledge/files/{id}/text

Read a knowledge file's extracted text

Capability chat, open to: device, owner

The source viewer a citation opens: the file's extracted text (null until it has been ingested once), every chunk's byte range in it, and the chunk named by chunk as highlight; a citation whose chunk id a re-ingest renamed is found again by its stored span_start, span_end and sha, and notice says so. The file is described by what the viewer shows (name, kind, status, pages), without its ingest record; original says whether the caller may download the original. A device key reads it only with kb__search and kb__read within its tool scope and kb__read switched on by the owner (403 tool_label_out_of_scope otherwise, said before the file is looked up). 400 op_failed for a file that does not exist.

Parameters

NameInDescription
idrequiredpath integer
chunkquery string | null
shaquery string | null
span_endquery integer | null
span_startquery integer | null

Responses

StatusDescription
200 OK.
application/json ChatKnowledgeSource
Fields of ChatKnowledgeSource
chunksrequired array of ChunkSpan Every chunk's span, in file order.
filerequired ChatKnowledgeFile
highlightrequired ChunkSpan | null The cited chunk (or the one found by the citation's position).
kb_namerequired string The base the file is in.
notice string Said when the highlight is not the cited chunk itself: it was found by
the citation's stored position because the chunk id no longer exists.
originalrequired boolean Whether this caller may download the file's original
(GET /chat/api/knowledge/files/{id}/original): the owner may, a
device key not yet.
textrequired string | null The extracted text; null until the file has been ingested once.
default Error.
application/json ApiError
get/chat/api/media/defaults

The image and audio tools' default models

Capability chat, open to: device, owner

Which model image__generate, image__edit, audio__speak and audio__transcribe use when a call leaves out model, and the voice audio__speak uses when it leaves out voice. Three levels, the narrowest that says something winning: a thread's own (its settings' media_defaults), its folder's (the folder defaults' media_defaults, read at each turn rather than copied), Settings → Chat's (chat_media_defaults). In a thread or a folder an absent field inherits and an empty one is no default. The answer has Settings' always, ?folder=<id> adds a folder's and ?thread=<id> a thread's and its folder's; inherited is what the narrowest level asked takes from above it, resolved what a call uses now, and choices every model each tool's model enum offers this caller (a device key's alias scope narrows it), with a label and each speech row's voices. A stored default that no longer resolves — its model switched off or deleted, an alias that lost the route, a model outside the caller's key scope, a voice its model does not have — is listed under unavailable with the reason and is no default: the tool requires model again, and no other model is put in its place. A folder or thread the caller does not reach is 404 not_found.

Parameters

NameInDescription
folderquery integer | null
threadquery integer | null

Responses

StatusDescription
200 OK.
application/json MediaDefaultsView
Fields of MediaDefaultsView
choicesrequired MediaChoices What each tool can use, for the caller.
folder MediaDefaults | null The folder's own, when a folder (or a thread in one) was asked for.
inheritedrequired MediaDefaults What the narrowest level asked for takes from the levels above it,
as stored there (a name that no longer resolves included; see
unavailable). For Settings itself, nothing.
resolvedrequired MediaDefaults What a call that leaves the argument out uses now at the narrowest
level asked for: a field absent here has no default, and the tool
requires the argument.
settingsrequired MediaDefaults Settings → Chat's defaults, as stored.
thread MediaDefaults | null The thread's own, when a thread was asked for.
unavailablerequired array of MediaUnavailable Every stored name in the levels above that does not resolve, with
the reason. Never replaced by another model: it is no default until
it is picked again or the model comes back.
default Error.
application/json ApiError
get/chat/api/profiles

List the personality profiles

Capability chat, open to: device, owner

Every personality profile in name order — how a thread's model talks, in text and in voice: a persona, a length rule, example exchanges, the voice turn's block, reasoning on or off, and the speech voice — each with used_by (the threads and folders that use it, as far as the caller may see them), and default_profile_id, the profile new threads start with (null: none). "Default" is no profile: a thread with profile_id null. A thread picks one with its settings' profile_id, a folder with its defaults' profile_id. The feed's profile.created, profile.updated and profile.deleted keep this list current.

Responses

StatusDescription
200 OK.
application/json ProfileList
Fields of ProfileList
default_profile_idrequired integer | null The profile new threads start with (Settings → Chat), null for
none.
profilesrequired array of Profile In name order.
default Error.
application/json ApiError
post/chat/api/profiles

Create a personality profile

Capability chat, open to: device, owner. Changes state.

A new profile from a name and any content fields (an absent one is unset), answered as the list carries it; or {builtin: "concise"} alone, which creates that built-in profile again after it was deleted (409 profile_builtin_exists while it exists). A name is unique in any case (409 profile_name_taken) and never "default" (400 profile_name_reserved). An example's sides must not be empty. No length or count is bounded; the request's body limit is. A voice.tts_alias must name a text-to-speech model. A device key may list, create, change, reset and delete profiles; a voice.tts_alias it writes must be within its alias scope (403 key_scope), unless the profile already had it. A profile that Admin Chat or the self-admin toolset uses (a thread, or a folder's defaults) is changed, reset or deleted by a device only while the device may use lmgw's admin tools with writes, its own level and the gateway's (403 profile_in_admin_use, which counts the use and names no thread).

Request body required

application/json: object

builtin string | null
examples array of Example Default [].
length_rule string Default "".
name string | null
persona string Default "".
reasoning Reasoning | null Default null.
voice ProfileVoiceInput Default {"speech_style":null,"tts_alias":null,"voice":null}.
voice_block string | null Default null.

Responses

StatusDescription
200 OK.
application/json Profile
Fields of Profile
builtinrequired string | null The built-in profile this row is (concise); null for one of the
owner's own. Read only.
created_atrequired string
examplesrequired array of Example Static example exchanges, in order.
follows_builtinrequired array of string The fields a built-in row takes from the built-in text, so they
follow its improvements. Read only.
idrequired integer (int64)
length_rulerequired string How long replies are; empty for none.
namerequired string Unique in any case; never default.
personarequired string Who the model is and how it sounds; empty for none. When set, it
takes the thread's system prompt's place.
reasoningrequired Reasoning | null Reasoning on or off; null inherits.
updated_atrequired string
used_byrequired UsedBy
voicerequired ProfileVoice
voice_blockrequired string | null The voice turn's block: null for the generic one, "" for none, a
text to use as it is.
default Error.
application/json ApiError
post/chat/api/profiles/preview

Preview an unsaved profile

Capability chat, open to: device, owner. Changes state.

The system messages an unsaved draft assembles to, as a send builds them: the static part (persona or thread prompt, length rule, examples), a text turn's and a voice turn's (with the voice block, the language and the tag hint of the text-to-speech model the draft resolves to). thread_id assembles as that thread would, the draft in place of its own profile; without it, an empty chat thread with Settings' defaults. With model, the three are counted on that alias through the universal token counter (as POST /v1/count_tokens counts), with its approximation flags; counting on a local model loads it. Nothing is stored. A draft is checked as a create's content is (an example's empty side is 400 bad_request).

Request body required

application/json: object

model string | null Count the tokens on this alias; absent: no count. Default null.
profile ProfileDraft Default {"examples":[],"length_rule":"","persona":"","reasoning":null,"voice":{"speech_style":null,"tts_alias":null,"voice":null},"voice_block":null}.
thread_id integer | null Assemble as this thread would, with the draft in place of its own
profile; absent: an empty thread with Settings' defaults. Default null.

Responses

StatusDescription
200 OK.
application/json PreviewAnswer
Fields of PreviewAnswer
staticrequired string The part that does not depend on the turn: persona or thread prompt,
length rule, examples.
text_turnrequired string
tokensrequired PreviewTokens | null
voice_turnrequired string
default Error.
application/json ApiError
post/chat/api/profiles/speak

Speak a sample with an unsaved profile

Capability chat, open to: device, owner. Changes state.

Says text with the voice the draft resolves to (its text-to-speech model, voice and speech style, after the thread's own, before the Chat's settings), through the read-aloud's pipeline, and answers one WAV (PCM16 mono, 24 kHz). Refused before any audio as the Chat's read-aloud refuses, in flat JSON: tts_not_configured, voice_not_found, voice_not_configured, instructions_required; a voice that fails while it speaks is 502 with its code. It writes one text-to-speech row; a thread's seed is used, none is drawn into it.

Request body required

application/json: object

profile ProfileDraft Default {"examples":[],"length_rule":"","persona":"","reasoning":null,"voice":{"speech_style":null,"tts_alias":null,"voice":null},"voice_block":null}.
text string Default "".
thread_id integer | null Default null.

Responses

StatusDescription
200 OK.
audio/wav string (binary)
default Error.
application/json ApiError
post/chat/api/profiles/test

Test an unsaved profile

Capability chat, open to: device, owner. Changes state.

One model call on model with the system message the draft assembles to (a text turn's, or with voice: true a voice turn's) and text as the user's message: no history, no max_tokens, no tools. The answer carries the system message sent, the reply, its reasoning, the reasoning note, the usage, first_token_ms and reasoning_ms, total_ms, and answered_by when a fallback answered. It writes the call's request row (a device's call is its key's) and stores nothing else. The model's refusals answer with their status and code.

Request body required

application/json: object

model string Default "".
profile ProfileDraft Default {"examples":[],"length_rule":"","persona":"","reasoning":null,"voice":{"speech_style":null,"tts_alias":null,"voice":null},"voice_block":null}.
text string The user's message. Default "".
thread_id integer | null Default null.
voice boolean Assemble a voice turn rather than a text turn. Default false.

Responses

StatusDescription
200 OK.
application/json TestAnswer
Fields of TestAnswer
answered_byrequired string | null The alias that answered, when it was not the one asked (a fallback).
first_token_msrequired integer | null
reasoningrequired string The reply's reasoning; empty when it did not reason.
reasoning_msrequired integer | null
reasoning_noterequired string | null Why reasoning was or was not asked as it was, in a sentence.
replyrequired string
systemrequired string The system message that was sent.
total_msrequired integer (uint64)
usagerequired TestUsage
default Error.
application/json ApiError
get/chat/api/profiles/{id}

Get a personality profile

Capability chat, open to: device, owner

The profile as the list carries it; 404 not_found when there is none.

Parameters

NameInDescription
idrequiredpath integer

Responses

StatusDescription
200 OK.
application/json Profile
Fields of Profile
builtinrequired string | null The built-in profile this row is (concise); null for one of the
owner's own. Read only.
created_atrequired string
examplesrequired array of Example Static example exchanges, in order.
follows_builtinrequired array of string The fields a built-in row takes from the built-in text, so they
follow its improvements. Read only.
idrequired integer (int64)
length_rulerequired string How long replies are; empty for none.
namerequired string Unique in any case; never default.
personarequired string Who the model is and how it sounds; empty for none. When set, it
takes the thread's system prompt's place.
reasoningrequired Reasoning | null Reasoning on or off; null inherits.
updated_atrequired string
used_byrequired UsedBy
voicerequired ProfileVoice
voice_blockrequired string | null The voice turn's block: null for the generic one, "" for none, a
text to use as it is.
default Error.
application/json ApiError
post/chat/api/profiles/{id}

Change a personality profile

Capability chat, open to: device, owner. Changes state.

The fields to change: an absent field stays, null unsets it, voice is replaced whole. On a built-in profile a field written with the built-in text follows the built-in again (follows_builtin). The change applies from the next turn of every thread using the profile, a bound voice session's included. The same refusals as a create. A device key may list, create, change, reset and delete profiles; a voice.tts_alias it writes must be within its alias scope (403 key_scope), unless the profile already had it. A profile that Admin Chat or the self-admin toolset uses (a thread, or a folder's defaults) is changed, reset or deleted by a device only while the device may use lmgw's admin tools with writes, its own level and the gateway's (403 profile_in_admin_use, which counts the use and names no thread).

Parameters

NameInDescription
idrequiredpath integer

Request body required

application/json: object

examples array | null
length_rule string | null
name string | null
persona string | null
reasoning Reasoning | null
voice ProfileVoiceInput | null The whole voice object; null unsets all three.
voice_block string | null

Responses

StatusDescription
200 OK.
application/json Profile
Fields of Profile
builtinrequired string | null The built-in profile this row is (concise); null for one of the
owner's own. Read only.
created_atrequired string
examplesrequired array of Example Static example exchanges, in order.
follows_builtinrequired array of string The fields a built-in row takes from the built-in text, so they
follow its improvements. Read only.
idrequired integer (int64)
length_rulerequired string How long replies are; empty for none.
namerequired string Unique in any case; never default.
personarequired string Who the model is and how it sounds; empty for none. When set, it
takes the thread's system prompt's place.
reasoningrequired Reasoning | null Reasoning on or off; null inherits.
updated_atrequired string
used_byrequired UsedBy
voicerequired ProfileVoice
voice_blockrequired string | null The voice turn's block: null for the generic one, "" for none, a
text to use as it is.
default Error.
application/json ApiError
post/chat/api/profiles/{id}/delete

Delete a personality profile

Capability chat, open to: device, owner. Changes state.

Deletes the profile and, in the same transaction, sets every thread using it to none, removes it from every folder's defaults, and empties the profile new threads start with when it was that one. The answer says what was cleared (threads and folders as far as the caller may see them). A built-in profile can be created again afterwards. A device key may list, create, change, reset and delete profiles; a voice.tts_alias it writes must be within its alias scope (403 key_scope), unless the profile already had it. A profile that Admin Chat or the self-admin toolset uses (a thread, or a folder's defaults) is changed, reset or deleted by a device only while the device may use lmgw's admin tools with writes, its own level and the gateway's (403 profile_in_admin_use, which counts the use and names no thread).

Parameters

NameInDescription
idrequiredpath integer

Responses

StatusDescription
200 OK.
application/json ProfileDeleted
Fields of ProfileDeleted
default_clearedrequired boolean Whether it was the profile new threads start with (Settings → Chat),
which is now none.
deletedrequired integer (int64) The deleted profile's id.
folders_clearedrequired array of FolderRef Folders whose defaults named it and no longer do.
threads_clearedrequired integer (int64) Threads that used it and now use none.
default Error.
application/json ApiError
post/chat/api/profiles/{id}/reset

Reset a built-in profile

Capability chat, open to: device, owner. Changes state.

Resets a built-in profile to its built-in texts: every content field follows the built-in again (follows_builtin lists them all), so later improvements to it apply, and the voice is unset. The name stays. 400 profile_not_builtin for one of the owner's own profiles, 404 not_found when there is none. Recorded as profile.updated in the feed. A device key may list, create, change, reset and delete profiles; a voice.tts_alias it writes must be within its alias scope (403 key_scope), unless the profile already had it. A profile that Admin Chat or the self-admin toolset uses (a thread, or a folder's defaults) is changed, reset or deleted by a device only while the device may use lmgw's admin tools with writes, its own level and the gateway's (403 profile_in_admin_use, which counts the use and names no thread).

Parameters

NameInDescription
idrequiredpath integer

Responses

StatusDescription
200 OK.
application/json Profile
Fields of Profile
builtinrequired string | null The built-in profile this row is (concise); null for one of the
owner's own. Read only.
created_atrequired string
examplesrequired array of Example Static example exchanges, in order.
follows_builtinrequired array of string The fields a built-in row takes from the built-in text, so they
follow its improvements. Read only.
idrequired integer (int64)
length_rulerequired string How long replies are; empty for none.
namerequired string Unique in any case; never default.
personarequired string Who the model is and how it sounds; empty for none. When set, it
takes the thread's system prompt's place.
reasoningrequired Reasoning | null Reasoning on or off; null inherits.
updated_atrequired string
used_byrequired UsedBy
voicerequired ProfileVoice
voice_blockrequired string | null The voice turn's block: null for the generic one, "" for none, a
text to use as it is.
default Error.
application/json ApiError
get/chat/api/settings

Read the settings the Chat uses

Capability chat, open to: device, owner

The gateway settings a Chat client reads, and only those: the knowledge excerpt budget a thread without its own uses, the global archive and purge days an ongoing folder's empty fields fall back to, the Chat's and the realtime voice's text-to-speech alias (a thread inherits the first that is not empty), the largest request body (a dictation's recording is one), the seconds between two reads of an MCP task's status, and a realtime session's pre-roll and ping interval. No secret is among them, and every caller reads the same values. They change only through Settings, and a client reads them again when it needs them.

Responses

StatusDescription
200 OK.
application/json ChatSettings
Fields of ChatSettings
archive_daysrequired integer (int64) Days after its last activity a thread is archived; 0: never. A
folder's own retention overrides it.
kb_budget_tokensrequired integer (uint32) Tokens of knowledge-base excerpts a turn carries when its thread sets
no budget of its own (Settings → Chat → Knowledge budget).
max_body_mbrequired integer (uint32) The largest request body the gateway reads, in MiB; 0: no bound.
A dictation's recording is one such body.
purge_daysrequired integer (int64) Days after it was archived a thread is deleted; 0: never. A
folder's own retention overrides it.
realtime_ping_interval_srequired integer (uint32) Seconds between the gateway's pings on a realtime session.
realtime_prefix_padding_msrequired integer (uint32) The audio a realtime session keeps from before speech starts, in
milliseconds: push-to-talk's pre-roll.
realtime_tts_aliasrequired string The realtime voice's text-to-speech alias.
task_poll_interval_srequired integer (uint32) Seconds between two reads of an MCP task's status (Settings → MCP);
0: none is set.
tts_aliasrequired string The Chat's text-to-speech alias; empty: realtime_tts_alias
is the one a thread inherits.
default Error.
application/json ApiError
get/chat/api/threads

List the Chat's threads

Capability chat, open to: device, owner

The stored threads, pinned first and then the most recently active; the temporary threads in a list of their own; how many threads are archived; and every folder with its thread counts. ?archived=1 lists the archived threads instead, the most recently archived first, and ?archived=all both. A device key's lists and counts leave out every Admin Chat thread, and every thread that carries the self-admin toolset (lmgw) unless the device may use lmgw's admin tools. Open the change feed first, then load this list: the feed's thread.* and folder.* events keep it current from then on.

Parameters

NameInDescription
archivedquery string

Responses

StatusDescription
200 OK.
application/json ThreadList
Fields of ThreadList
archived_countrequired integer (int64) How many threads are archived, whichever list was asked for.
foldersrequired array of Folder Every folder, as GET /chat/api/folders lists them.
temporaryrequired array of ThreadRow Temporary threads, the most recently active first.
threadsrequired array of ThreadRow Stored threads: pinned first, then the most recently active; with
?archived=1 the archived ones, the most recently archived first.
default Error.
application/json ApiError
post/chat/api/threads

Create a thread

Capability chat, open to: device, owner. Changes state.

A new thread, answered as the thread list carries it, with voice_resolved. A plain chat thread starts from the Chat's default system prompt and personality profile; an Admin Chat thread (kind: admin) has its built-in prompt. temporary: true creates a temporary thread kept in memory only, with a negative id; it is a chat thread whatever kind says. folder_id starts the thread from that folder's defaults laid over the Chat's own, and in an ongoing-conversation folder it becomes the current thread. A temporary thread in a folder is a 400 bad_request; a folder the caller cannot see a 404 not_found. A device key cannot create an Admin Chat thread (403 forbidden), and the model alias must be within its alias scope (403 key_scope).

Request body required

application/json: object

folder_id integer | null Create the thread in this folder, starting from the folder's
defaults laid over the Chat's own. Default null.
kind string chat (the default) or admin, a thread that drives the gateway's
own configuration (not for a device key: 403 forbidden). Default "".
model_alias string The alias the thread's turns go to. In a folder, the folder's
defaults may name the model instead. Default "".
temporary boolean A temporary chat: kept in memory only, with a negative id, and gone
at the gateway's next start unless it is kept
(POST /chat/api/threads/{id}/persist). Always a chat thread,
whatever kind says, and not with folder_id. Default false.

Responses

StatusDescription
200 OK.
application/json Thread
Fields of Thread
agent_idrequired string | null The agent the thread was opened from, if any.
archived_atrequired string | null When the thread was archived; null while it is active.
continue ContinueState Whether the last reply can be continued. Present where the thread
is read whole, as POST /chat/api/folders/{id}/current answers it.
created_atrequired string
folder_idrequired integer | null The folder the thread is in; null for none.
frequency_penaltyrequired number | null
idrequired integer (int64) Negative for a temporary thread.
kb_budget_tokensrequired integer | null The retrieval budget of auto mode in tokens; null for the Chat's
setting.
kb_idsrequired array of integer (int64) Knowledge bases the thread searches, by id.
kb_moderequired KbMode
kindrequired string chat, or admin for a thread that drives the gateway's own
configuration (never listed for a device key).
last_message_atrequired integer | null When its newest message was written, in unix seconds; null for a
thread without messages. An ongoing folder's idle rollover is
measured from it: a client that shows when the conversation moves
on reads it here rather than timing the turns it saw.
max_tokensrequired integer | null
mcp_toolsrequired array of ThreadMcp The tool servers the thread's turns use; empty for a plain chat. A
thread with lmgw (the self-admin toolset) among them is listed for a
device key only when the device may use lmgw's admin tools.
media_defaultsrequired MediaDefaults The thread's own default models of the image and audio tools; an
absent field inherits its folder's, then Settings → Chat's, and an
empty one is no default (GET /chat/api/media/defaults says what
they resolve to).
min_prequired number | null
model_aliasrequired string The alias the thread's turns go to.
pinnedrequired boolean Pinned threads are listed first and are never archived or deleted
by the sweep.
presence_penaltyrequired number | null
profile_idrequired integer | null The personality profile the thread talks with
(GET /chat/api/profiles); null for none ("Default").
purge_atrequired string | null When an archived thread will be deleted; null while it is active,
pinned, or when deleting is switched off.
reasoning_budgetrequired integer | null
reasoning_effortrequired string | null
reasoning_enabledrequired boolean | null Reasoning overrides sent with every turn; null leaves the route's
default.
repeat_penaltyrequired number | null
seedrequired integer | null
stoprequired array of string Stop sequences; empty leaves the route's default.
system_promptrequired string
temperaturerequired number | null Sampling overrides sent with every turn; null leaves the route's
default.
temporaryrequired boolean The thread lives in memory only and is gone at the gateway's next
start unless it is kept.
titlerequired string
top_krequired integer | null
top_prequired number | null
updated_atrequired string Moves with every change to the thread and every new message.
voicerequired ThreadVoice
voice_resolvedrequired VoiceResolved What the thread's voice resolves to now, field by field with the
level each value comes from (the thread, the Chat's settings, the
realtime settings): the speech-to-text and text-to-speech stages
(asr, tts: alias, whether it runs on this machine, what answers
for it while the GPU is held), voice, speech_style, language,
reply_language, read_aloud, turn_detection, audio_input,
seed, the problems that block a voice feature now, and
realtime: whether voice mode can bind the thread.
default Error.
application/json ApiError
get/chat/api/threads/rows

Read some of the thread list's rows

Capability chat, open to: device, owner

The rows of the threads named in ids (comma-separated, as 3,7), each exactly as GET /chat/api/threads lists it, active or archived, in the active list's order. For a client that follows the change feed and wants only the rows its message.* events named, instead of the whole list: a message written moved its thread's updated_at and last_message_at and nothing else the list shows, so read these rows and sort the list again. Only stored threads are answered: a temporary id, one that is not there and one out of the caller's reach are left out, so a missing row is never an error. There is no cap on ids beyond the 64 KiB a request line may be (about 9,000 ids; more is a 414, and the whole list is then the read to fall back to). A part of ids that is not a number is a 400 bad_request. A device key's answer leaves out the threads it may not see, as its list does.

Parameters

NameInDescription
idsquery string

Responses

StatusDescription
200 OK.
application/json ThreadRows
Fields of ThreadRows
threadsrequired array of ThreadRow The rows found, each as GET /chat/api/threads lists it, in the
active list's order.
default Error.
application/json ApiError
get/chat/api/threads/{id}

Read a thread whole

Capability chat, open to: device, owner

The thread with its settings, voice_resolved and continue (whether its last reply can be continued), every message oldest first, each with its attachments, the draft attachments that wait for the next message, and the thread's MCP tasks still running or waiting to enter it. A message of a gated turn lists the calls it still waits on as pending_approvals; POST /chat/api/threads/{id}/approvals decides them. A thread that is not there, or not the caller's to see, is a 404 not_found; a read that failed a 500 internal, never an empty history. Read the thread again on every change the feed reports.

Parameters

NameInDescription
idrequiredpath integer

Responses

StatusDescription
200 OK.
application/json ThreadDetail
Fields of ThreadDetail
draft_attachmentsrequired array of AttachmentMeta Files attached to the next message, not sent yet.
messagesrequired array of Message Every message, oldest first.
tasksrequired array of ThreadTask The thread's MCP tasks still running, and the results waiting to
enter it.
threadrequired Thread The thread with voice_resolved and continue: whether its last
reply can be continued.
default Error.
application/json ApiError
post/chat/api/threads/{id}/answer

Answer a thread's job results

Capability chat, open to: device, owner. Changes state.

A tool whose MCP server runs it as a task (its execution.taskSupport is required) answers the turn at once: its result frame's output is started, job <task_id> and carries task {id, task_id, server_label}, and the turn goes on. lmgw follows the task; when it ends, its result enters the thread as a message of role tool with task {task_id, server_label, tool, status: completed | failed | cancelled | abandoned, ended_by}, its content the result as text — only while no turn of the thread runs (a turn that runs takes it in when it ends; one that starts, before it reads the history), and not while the thread's last reply waits for approvals or for the turn that runs the calls decided on it. The feed records task.started and task.done. Every later turn sees it as a call of lmgw__job_result and its result, in chronological order: where it is stored among the thread's messages, so a message sent after it follows it; an edit or a regenerate keeps it, and the reply after it answers it again. lmgw starts no turn for a result: this route asks for one, a continuation with no new user message, streaming the frames a send streams; a send answers it too. It needs a result nothing answered yet (a result row with no reply after it, or one waiting to enter the thread), else 409 nothing_to_answer; while a turn of the thread runs it is 409 turn_running (that turn's end lets the results in, and its reply may answer them). It runs on the thread's alias with its configured fallbacks, as every turn does. The body may be empty; speak reads the answer aloud as a send's does. GET /chat/api/threads/{id} lists the thread's tasks still running or waiting to enter it as tasks (ThreadTask: id, task_id, server_label, tool, status, status_message, ttl_ms, started_at, by, waiting_for). A temporary thread's calls wait for their task instead, within the server's timeout_ms.

Parameters

NameInDescription
idrequiredpath integer

Request body required

application/json: object

speak boolean Read the answer aloud as it streams, as a send's speak. Default false.

Responses

StatusDescription
200 An event stream.
text/event-stream string
14 event types

delta TextFrame
delta (a piece of the answer) and reasoning (a piece of the model's
reasoning, kept apart from the answer).

textrequired string

done DoneFrame
done: the turn's last frame. aborted is true when the turn ended
early (refused, stopped, failed before it said anything); a turn that
saved nothing says only that, with no message_id.

abortedrequired boolean
answered_by string | null The alias that answered in its place (a fallback, a candidate
alias's pick), when one did.
completion_tokens integer | null
images_note string A fallback that cannot see answered and got the images as
placeholders: who, in a sentence. Only when it did.
message_id integer (int64) The reply the turn saved or appended to; 0 when it saved none.
model string The thread's model alias.
pending_approvals array of ApprovalRequest The calls the turn stopped on and waits for a decision about; only
when there are some.
prompt_tokens integer | null
reasoning_ignored array of string The thread's reasoning and sampling overrides this route did not send.
reasoning_note string | null The model reasoned although off was asked, in a sentence.
saved boolean Whether the reply is stored. false: its bubble is not a row, and no
action on it can work.
timings Timings | null The authoritative final timings of a local model; null for a cloud
upstream.
total_ms integer (int64)
ttfb_ms integer | null Milliseconds to the first byte of the upstream's answer.

error ErrorFrame
error: something went wrong; the stream goes on to done. code is
what a client branches on (gpu_hold, context_length_exceeded,
vram_queue_timeout, not_saved, superseded, ...); a failure that has
none sends only the message. A stream whose key was disabled, rotated,
deleted or expired, or whose gateway stops, ends with a last error
frame instead of done: revoked (with kind) or gateway_stopping.
An MCP label the thread or its folder attached that offers the turn no
tools gets one frame each, with server_label and a LabelCode
(tool_unreachable, tool_offline, tool_disabled, tool_unknown,
tool_failed), and the turn goes on without it.

code string
kind RevokeKind What a client does about a revoked frame, the token a realtime
session's 4003 close starts its reason with (key_unknown means pair
the device again). Sent with revoked only.
messagerequired string
server_label string The MCP label the frame is about, as the thread or folder attached
it; sent with a LabelCode only.

reasoning TextFrame
delta (a piece of the answer) and reasoning (a piece of the model's
reasoning, kept apart from the answer).

textrequired string

retrieval RetrievalFrame
retrieval: what the knowledge bases found for the user message, before
the model answers.

budget_tokensrequired integer (uint64) The budget the retrieval ran with.
droppedrequired integer (uint64) Excerpts that ranked but did not fit the budget.
excerptsrequired array of ContextExcerpt
kb_idsrequired array of integer (int64) The bases asked for: the thread's and the message's, as they were
then.
message_idrequired integer (int64) The user message the retrieval belongs to.
msrequired number (double) How long the retrieval took.
notesrequired array of string Why something was not searched, or not fully: one sentence each.
queryrequired string What was searched for.
reusedrequired boolean The message's stored retrieval was used again instead of searching.
searchedrequired array of string The bases that were searched, by name.
tokensrequired integer (uint64) Tokens the excerpts use, heading paths included.

speech SpeechFrame
speech: one clause as said, with its audio.

pcmrequired string The clause's audio, base64 of PCM16 little-endian, 24 kHz, mono.
seqrequired integer (uint64) Counts from 0.
textrequired string

speech_done SpeechDone
speech_done: the read-aloud ended, whole or stopped.

audio_msrequired integer (uint64) Length of the audio sent.
charsrequired integer (uint64) Characters spoken.
first_audio_msrequired integer | null From the request's start to the first speech frame; null when
nothing was spoken.
stoppedrequired boolean Stopped (POST .../speech/stop, or the reader went away) before the
text ended.
ttsrequired string
tts_answered_byrequired string | null

speech_error SpeechError
speech_error: the read-aloud cannot speak or failed; it ends the
speech. Codes: tts_not_configured, voice_not_found,
voice_not_configured, instructions_required, a device key's own
refusals, or the failure's kind.

coderequired string
messagerequired string

state ModelState
A voice stage's model state: a chat stream's state frame and a bound
realtime session's lmgw.model.state event.
Read leniently: a field a client does not know of is ignored, a missing
one is empty. Written as the gateway sends it: ms always, the other
optional facts only when the state has them.

aliasrequired string
answered_by string fallback: the alias that answers in its place.
capacity_bytes integer (uint64) skipped with does_not_fit: what the group could have together,
in bytes.
cause string held: gpu_hold or benchmark.
done_bytes integer (uint64) downloading: compressed bytes downloaded so far.
image string downloading: the image the model runs in, being downloaded before
its first start (machine-check design §5). A client says the
download in plain words; the reference is a detail.
message string The sentence a client shows.
msrequired integer | null How long the load took, for ready.
needed_bytes integer (uint64) skipped with does_not_fit: what the stage's group needs on the
card, in bytes.
reason string skipped: full, does_not_fit or cannot_speak.
size_note string downloading: why the size is not known, when it is not.
stagerequired string asr, chat or tts.
staterequired string loading, downloading, ready, held, fallback, skipped or
failed.
total_bytes integer (uint64) downloading: the download's whole size; absent while it is not
known.

stats Timings
Server-measured prefill and decode timings of a local model: the stats
frame (live per token while it streams) and the done frame's final
timings.

cache_n integer (uint64) Prompt tokens served from the KV cache.
draft_n integer (uint64) Draft tokens proposed (speculative or MTP decoding).
draft_n_accepted integer (uint64) Draft tokens accepted.
predicted_ms number (double) Milliseconds spent generating; absent when llama.cpp gave no finite number.
predicted_nrequired integer (uint64) Tokens generated so far.
predicted_per_second number (double) Tokens generated per second; absent when llama.cpp gave no finite number.
prompt_ms number (double) Milliseconds spent on the prompt; absent when llama.cpp gave no finite number.
prompt_nrequired integer (uint64) Prompt tokens actually processed this turn (the cache excluded).
prompt_per_second number (double) Prompt tokens processed per second; absent when llama.cpp gave no finite number.

stop StopFrame
stop: why the model stopped, in OpenAI's words (stop, length,
tool_calls, ...).

reasonrequired string

tool ToolFrame
tool: a tool call of the turn, told apart by event. start and
args while the model writes the call; ready when its arguments are
complete (a call that waits for an approval says needs_approval);
approval for a call that waits for a decision
(POST /chat/api/threads/{id}/approvals); result when it has run. A
result's task says which MCP task a call started: its output is then
started, job <task_id>, and the result enters the thread later.
progress while an image or audio tool runs: its stage, step and latest
preview (ToolProgressFrame), lossy and not in the change feed; a
result's attachments are the files the call stored in the thread.

One of 6 shapes
ToolStartFrame
Fields of ToolStartFrame
id string The model's id of the call; only a turn without tools says it.
indexrequired integer (uint) The call's position in its turn.
namerequired string The tool's exposed name.
ToolArgsFrame
Fields of ToolArgsFrame
fragmentrequired string
indexrequired integer (uint)
ToolReadyFrame
Fields of ToolReadyFrame
argumentsrequired any The call's arguments.
call_idrequired string | null The call's id, as its result frame carries it.
indexrequired integer (uint) The call's position in its turn.
namerequired string The tool's exposed name, as the model called it.
needs_approvalrequired boolean | null The call waits for an approval and does not run now: an approval
frame follows. false for a call that runs (a resumed turn's decided
calls included). Absent from an lmgw before 2026-10-09.
server_labelrequired string | null The label the tool came from; null for a client's own function.
ui_resourcerequired string | null The UI resource the tool links to, as on the result frame.
ApprovalRequest
Fields of ApprovalRequest
approval_request_idrequired string The id a decision quotes (mcpr_…), unique in the gateway.
argumentsrequired string The arguments as the model wrote them: a JSON string.
call_id string The call's id, as its ready and result frames carry it
(mcp_apps::ToolReadyFrame::call_id). Absent from an lmgw
before 2026-10-09, and from an ApprovalRequest read off a bound
session's mcp_approval_request item (OpenAI's shape has none):
there the lmgw.chat.frame relaying the approval frame has it.
namerequired string The tool's own name: the name the model called, without its
label's <prefix>__.
server_labelrequired string The thread's label the tool came from.
ToolResultFrame
Fields of ToolResultFrame
attachments array of AttachmentMeta The files the call stored in the thread — an image or audio tool's
pictures and recordings in a Chat turn — so a page shows them
without reading the thread again. Their bytes are at
GET /chat/api/attachments/{id}; content names them as
lmgw:attachment/N resources. Empty for every other call.
call_idrequired string | null The call's id, as its ready frame carries it.
contentrequired array | null The MCP result's content blocks as the server sent them (resource
URIs namespaced as /mcp sends them; images in full — no bound of
lmgw's own, a device's result is bounded by mcp.host_max_message_mb
on its link); a tool lmgw runs itself, or a call that never reached
a server, says its result in the same shape. Absent from an lmgw
before 2026-10-09: output as one text block then.
indexrequired integer (uint) The call's position in its turn.
is_errorrequired boolean
msrequired integer (uint64)
namerequired string The tool's exposed name (<prefix>__<tool>).
outputrequired string The result as text.
server_labelrequired string | null The label the tool came from: a server's tool prefix (else its
name), or a built-in toolset's (lmgw, docs, kb).
structured_contentrequired any The MCP result's structuredContent, for the view. The model was
given it only when content is empty.
task ResultTask For a call that started an MCP task: which. Absent otherwise.
ui_resourcerequired string | null The UI resource the tool links to (_meta.ui.resourceUri),
namespaced as /mcp serves it: resources/read it there.
ToolProgressFrame
Fields of ToolProgressFrame
call_idrequired string The call's id, as its ready frame carries it.
cancel CancelKind What a cancel would do now, while an image job runs; absent before
the job exists (a cancel then just stops the wait) and for audio.
done_bytes integer (uint64) downloading: compressed bytes downloaded so far.
elapsed_msrequired integer (uint64) Since the call started.
free_bytes integer (uint64) waiting_for_room: the memory free when it was last measured.
image string downloading: the image reference being downloaded.
model string The model the phase is about: the one being unloaded for
unloading, the call's own otherwise.
needs_bytes integer (uint64) waiting_for_room: the memory the model needs, headroom included.
pass integer (uint32) The sampling pass (a batch item, a high- or low-noise stage, a hires
pass); a new pass starts its steps again.
phaserequired MediaPhase | null
preview string The latest preview as the image server drew it: base64, PNG. Its
pixel size depends on the row's preview mode (a quick sketch is the
latent's size, an eighth of the picture's side on the spike's
pipeline).
queue_position integer (uint32) queued: the job's place in the image server's queue.
size_note string downloading: why the size is not known, when it is not ("size not
known — …").
step integer (uint32)
total_bytes integer (uint64) downloading: the download's whole size; absent when it is not
known.
total_steps integer (uint32)

usage UsageFrame
usage: the tokens the model reported for the turn so far.

completion_tokensrequired integer | null
prompt_tokensrequired integer | null

voice VoiceFrame
voice (speech): the read-aloud's route is open.

ttsrequired string The text-to-speech alias.
tts_answered_byrequired string | null The alias that answers in the TTS alias's place (a fallback).
voicerequired string | null The voice every clause is sent with.
default Error.
application/json ApiError
post/chat/api/threads/{id}/approvals

Decide the calls a turn waits on

Capability chat, open to: device, owner. Changes state.

A thread's MCP tools may wait for an approval (the thread's mcp_tools entry's require_approval: "never", "always" or {always: {tool_names}, never: {tool_names}}, as OpenAI's; any other shape, read_only included, is refused, and a device key may only tighten it, 403 approval_loosen_refused). A turn that calls one stops: it streams a tool frame {event: approval, approval_request_id, server_label, name, arguments, call_id} for each waiting call (call_id the id the call's ready and result frames carry) and done {pending_approvals}, and saves its reply with them; the other calls of that model turn wait with them. The thread's messages list them as the reply's pending_approvals, and the feed records approval.requested, each with the call_id. This route takes a verdict for every waiting call and resumes the turn as a continuation, streaming the frames a send streams (delta, reasoning, tool, usage, stop, error, done): the declined calls are answered "The user declined this tool call: <reason>", the approved ones and the calls that waited with them run, and the model answers; what it adds is appended to the same reply. The resumed turn runs as the principal that started it — its scope, key policy and attribution — whoever approves. The approver is on each approved call's request row (approved_by), in the feed's approval.decided, and in _meta["lmgw/approval"] {decision: approved, by: {kind, name}} of a call forwarded to a device-hosted server; a call nobody approved carries null there. The first decision wins: a call decided already is 409 approval_decided, naming who decided. A body that is not JSON is 400 bad_request, JSON of another shape 422 bad_request. A waiting call without a verdict is 400 approval_missing, naming each; an id nothing waits under 404 approval_not_found; a starter whose key is gone or disabled 409 approval_starter_unavailable, naming it (nothing is decided then; nor when the starter's key is at its concurrency limit, its 429 key_rate); a reply that is no longer the thread's last message 409 approval_moved_on. A device approves only within its own reach: a call its key's tool scope does not admit, or one of lmgw's admin tools unless its own admin tools may do everything (full, capped by the gateway's level), is 403 approval_out_of_scope, naming each, and nothing of the request is decided; declining is open to any client that sees the thread. A decided turn that never starts closes its calls as not run, and the feed's approval.decided says approve: false, not_run: true for an approved one. A new message in the thread declines whatever still waits, "the user moved on without deciding", so every call is answered. speak reads the resumed reply aloud as a send's does.

Parameters

NameInDescription
idrequiredpath integer

Request body required

application/json: object

decisionsrequired array of ApprovalDecision
speak boolean Read the resumed reply aloud as it streams, as a send's speak.

Responses

StatusDescription
200 An event stream.
text/event-stream string
14 event types

delta TextFrame
delta (a piece of the answer) and reasoning (a piece of the model's
reasoning, kept apart from the answer).

textrequired string

done DoneFrame
done: the turn's last frame. aborted is true when the turn ended
early (refused, stopped, failed before it said anything); a turn that
saved nothing says only that, with no message_id.

abortedrequired boolean
answered_by string | null The alias that answered in its place (a fallback, a candidate
alias's pick), when one did.
completion_tokens integer | null
images_note string A fallback that cannot see answered and got the images as
placeholders: who, in a sentence. Only when it did.
message_id integer (int64) The reply the turn saved or appended to; 0 when it saved none.
model string The thread's model alias.
pending_approvals array of ApprovalRequest The calls the turn stopped on and waits for a decision about; only
when there are some.
prompt_tokens integer | null
reasoning_ignored array of string The thread's reasoning and sampling overrides this route did not send.
reasoning_note string | null The model reasoned although off was asked, in a sentence.
saved boolean Whether the reply is stored. false: its bubble is not a row, and no
action on it can work.
timings Timings | null The authoritative final timings of a local model; null for a cloud
upstream.
total_ms integer (int64)
ttfb_ms integer | null Milliseconds to the first byte of the upstream's answer.

error ErrorFrame
error: something went wrong; the stream goes on to done. code is
what a client branches on (gpu_hold, context_length_exceeded,
vram_queue_timeout, not_saved, superseded, ...); a failure that has
none sends only the message. A stream whose key was disabled, rotated,
deleted or expired, or whose gateway stops, ends with a last error
frame instead of done: revoked (with kind) or gateway_stopping.
An MCP label the thread or its folder attached that offers the turn no
tools gets one frame each, with server_label and a LabelCode
(tool_unreachable, tool_offline, tool_disabled, tool_unknown,
tool_failed), and the turn goes on without it.

code string
kind RevokeKind What a client does about a revoked frame, the token a realtime
session's 4003 close starts its reason with (key_unknown means pair
the device again). Sent with revoked only.
messagerequired string
server_label string The MCP label the frame is about, as the thread or folder attached
it; sent with a LabelCode only.

reasoning TextFrame
delta (a piece of the answer) and reasoning (a piece of the model's
reasoning, kept apart from the answer).

textrequired string

retrieval RetrievalFrame
retrieval: what the knowledge bases found for the user message, before
the model answers.

budget_tokensrequired integer (uint64) The budget the retrieval ran with.
droppedrequired integer (uint64) Excerpts that ranked but did not fit the budget.
excerptsrequired array of ContextExcerpt
kb_idsrequired array of integer (int64) The bases asked for: the thread's and the message's, as they were
then.
message_idrequired integer (int64) The user message the retrieval belongs to.
msrequired number (double) How long the retrieval took.
notesrequired array of string Why something was not searched, or not fully: one sentence each.
queryrequired string What was searched for.
reusedrequired boolean The message's stored retrieval was used again instead of searching.
searchedrequired array of string The bases that were searched, by name.
tokensrequired integer (uint64) Tokens the excerpts use, heading paths included.

speech SpeechFrame
speech: one clause as said, with its audio.

pcmrequired string The clause's audio, base64 of PCM16 little-endian, 24 kHz, mono.
seqrequired integer (uint64) Counts from 0.
textrequired string

speech_done SpeechDone
speech_done: the read-aloud ended, whole or stopped.

audio_msrequired integer (uint64) Length of the audio sent.
charsrequired integer (uint64) Characters spoken.
first_audio_msrequired integer | null From the request's start to the first speech frame; null when
nothing was spoken.
stoppedrequired boolean Stopped (POST .../speech/stop, or the reader went away) before the
text ended.
ttsrequired string
tts_answered_byrequired string | null

speech_error SpeechError
speech_error: the read-aloud cannot speak or failed; it ends the
speech. Codes: tts_not_configured, voice_not_found,
voice_not_configured, instructions_required, a device key's own
refusals, or the failure's kind.

coderequired string
messagerequired string

state ModelState
A voice stage's model state: a chat stream's state frame and a bound
realtime session's lmgw.model.state event.
Read leniently: a field a client does not know of is ignored, a missing
one is empty. Written as the gateway sends it: ms always, the other
optional facts only when the state has them.

aliasrequired string
answered_by string fallback: the alias that answers in its place.
capacity_bytes integer (uint64) skipped with does_not_fit: what the group could have together,
in bytes.
cause string held: gpu_hold or benchmark.
done_bytes integer (uint64) downloading: compressed bytes downloaded so far.
image string downloading: the image the model runs in, being downloaded before
its first start (machine-check design §5). A client says the
download in plain words; the reference is a detail.
message string The sentence a client shows.
msrequired integer | null How long the load took, for ready.
needed_bytes integer (uint64) skipped with does_not_fit: what the stage's group needs on the
card, in bytes.
reason string skipped: full, does_not_fit or cannot_speak.
size_note string downloading: why the size is not known, when it is not.
stagerequired string asr, chat or tts.
staterequired string loading, downloading, ready, held, fallback, skipped or
failed.
total_bytes integer (uint64) downloading: the download's whole size; absent while it is not
known.

stats Timings
Server-measured prefill and decode timings of a local model: the stats
frame (live per token while it streams) and the done frame's final
timings.

cache_n integer (uint64) Prompt tokens served from the KV cache.
draft_n integer (uint64) Draft tokens proposed (speculative or MTP decoding).
draft_n_accepted integer (uint64) Draft tokens accepted.
predicted_ms number (double) Milliseconds spent generating; absent when llama.cpp gave no finite number.
predicted_nrequired integer (uint64) Tokens generated so far.
predicted_per_second number (double) Tokens generated per second; absent when llama.cpp gave no finite number.
prompt_ms number (double) Milliseconds spent on the prompt; absent when llama.cpp gave no finite number.
prompt_nrequired integer (uint64) Prompt tokens actually processed this turn (the cache excluded).
prompt_per_second number (double) Prompt tokens processed per second; absent when llama.cpp gave no finite number.

stop StopFrame
stop: why the model stopped, in OpenAI's words (stop, length,
tool_calls, ...).

reasonrequired string

tool ToolFrame
tool: a tool call of the turn, told apart by event. start and
args while the model writes the call; ready when its arguments are
complete (a call that waits for an approval says needs_approval);
approval for a call that waits for a decision
(POST /chat/api/threads/{id}/approvals); result when it has run. A
result's task says which MCP task a call started: its output is then
started, job <task_id>, and the result enters the thread later.
progress while an image or audio tool runs: its stage, step and latest
preview (ToolProgressFrame), lossy and not in the change feed; a
result's attachments are the files the call stored in the thread.

One of 6 shapes
ToolStartFrame
Fields of ToolStartFrame
id string The model's id of the call; only a turn without tools says it.
indexrequired integer (uint) The call's position in its turn.
namerequired string The tool's exposed name.
ToolArgsFrame
Fields of ToolArgsFrame
fragmentrequired string
indexrequired integer (uint)
ToolReadyFrame
Fields of ToolReadyFrame
argumentsrequired any The call's arguments.
call_idrequired string | null The call's id, as its result frame carries it.
indexrequired integer (uint) The call's position in its turn.
namerequired string The tool's exposed name, as the model called it.
needs_approvalrequired boolean | null The call waits for an approval and does not run now: an approval
frame follows. false for a call that runs (a resumed turn's decided
calls included). Absent from an lmgw before 2026-10-09.
server_labelrequired string | null The label the tool came from; null for a client's own function.
ui_resourcerequired string | null The UI resource the tool links to, as on the result frame.
ApprovalRequest
Fields of ApprovalRequest
approval_request_idrequired string The id a decision quotes (mcpr_…), unique in the gateway.
argumentsrequired string The arguments as the model wrote them: a JSON string.
call_id string The call's id, as its ready and result frames carry it
(mcp_apps::ToolReadyFrame::call_id). Absent from an lmgw
before 2026-10-09, and from an ApprovalRequest read off a bound
session's mcp_approval_request item (OpenAI's shape has none):
there the lmgw.chat.frame relaying the approval frame has it.
namerequired string The tool's own name: the name the model called, without its
label's <prefix>__.
server_labelrequired string The thread's label the tool came from.
ToolResultFrame
Fields of ToolResultFrame
attachments array of AttachmentMeta The files the call stored in the thread — an image or audio tool's
pictures and recordings in a Chat turn — so a page shows them
without reading the thread again. Their bytes are at
GET /chat/api/attachments/{id}; content names them as
lmgw:attachment/N resources. Empty for every other call.
call_idrequired string | null The call's id, as its ready frame carries it.
contentrequired array | null The MCP result's content blocks as the server sent them (resource
URIs namespaced as /mcp sends them; images in full — no bound of
lmgw's own, a device's result is bounded by mcp.host_max_message_mb
on its link); a tool lmgw runs itself, or a call that never reached
a server, says its result in the same shape. Absent from an lmgw
before 2026-10-09: output as one text block then.
indexrequired integer (uint) The call's position in its turn.
is_errorrequired boolean
msrequired integer (uint64)
namerequired string The tool's exposed name (<prefix>__<tool>).
outputrequired string The result as text.
server_labelrequired string | null The label the tool came from: a server's tool prefix (else its
name), or a built-in toolset's (lmgw, docs, kb).
structured_contentrequired any The MCP result's structuredContent, for the view. The model was
given it only when content is empty.
task ResultTask For a call that started an MCP task: which. Absent otherwise.
ui_resourcerequired string | null The UI resource the tool links to (_meta.ui.resourceUri),
namespaced as /mcp serves it: resources/read it there.
ToolProgressFrame
Fields of ToolProgressFrame
call_idrequired string The call's id, as its ready frame carries it.
cancel CancelKind What a cancel would do now, while an image job runs; absent before
the job exists (a cancel then just stops the wait) and for audio.
done_bytes integer (uint64) downloading: compressed bytes downloaded so far.
elapsed_msrequired integer (uint64) Since the call started.
free_bytes integer (uint64) waiting_for_room: the memory free when it was last measured.
image string downloading: the image reference being downloaded.
model string The model the phase is about: the one being unloaded for
unloading, the call's own otherwise.
needs_bytes integer (uint64) waiting_for_room: the memory the model needs, headroom included.
pass integer (uint32) The sampling pass (a batch item, a high- or low-noise stage, a hires
pass); a new pass starts its steps again.
phaserequired MediaPhase | null
preview string The latest preview as the image server drew it: base64, PNG. Its
pixel size depends on the row's preview mode (a quick sketch is the
latent's size, an eighth of the picture's side on the spike's
pipeline).
queue_position integer (uint32) queued: the job's place in the image server's queue.
size_note string downloading: why the size is not known, when it is not ("size not
known — …").
step integer (uint32)
total_bytes integer (uint64) downloading: the download's whole size; absent when it is not
known.
total_steps integer (uint32)

usage UsageFrame
usage: the tokens the model reported for the turn so far.

completion_tokensrequired integer | null
prompt_tokensrequired integer | null

voice VoiceFrame
voice (speech): the read-aloud's route is open.

ttsrequired string The text-to-speech alias.
tts_answered_byrequired string | null The alias that answers in the TTS alias's place (a fallback).
voicerequired string | null The voice every clause is sent with.
default Error.
application/json ApiError
post/chat/api/threads/{id}/archive

Archive or restore a thread

Capability chat, open to: device, owner. Changes state.

archived: true archives the thread by hand; false restores it. Answers the thread as the list carries it. A temporary thread is discarded, not archived: 409 temporary_thread. A thread the caller cannot reach is a 404 not_found.

Parameters

NameInDescription
idrequiredpath integer

Request body required

application/json: object

archivedrequired boolean Archive (true) the thread by hand, or restore it.

Responses

StatusDescription
200 OK.
application/json Thread
Fields of Thread
agent_idrequired string | null The agent the thread was opened from, if any.
archived_atrequired string | null When the thread was archived; null while it is active.
continue ContinueState Whether the last reply can be continued. Present where the thread
is read whole, as POST /chat/api/folders/{id}/current answers it.
created_atrequired string
folder_idrequired integer | null The folder the thread is in; null for none.
frequency_penaltyrequired number | null
idrequired integer (int64) Negative for a temporary thread.
kb_budget_tokensrequired integer | null The retrieval budget of auto mode in tokens; null for the Chat's
setting.
kb_idsrequired array of integer (int64) Knowledge bases the thread searches, by id.
kb_moderequired KbMode
kindrequired string chat, or admin for a thread that drives the gateway's own
configuration (never listed for a device key).
last_message_atrequired integer | null When its newest message was written, in unix seconds; null for a
thread without messages. An ongoing folder's idle rollover is
measured from it: a client that shows when the conversation moves
on reads it here rather than timing the turns it saw.
max_tokensrequired integer | null
mcp_toolsrequired array of ThreadMcp The tool servers the thread's turns use; empty for a plain chat. A
thread with lmgw (the self-admin toolset) among them is listed for a
device key only when the device may use lmgw's admin tools.
media_defaultsrequired MediaDefaults The thread's own default models of the image and audio tools; an
absent field inherits its folder's, then Settings → Chat's, and an
empty one is no default (GET /chat/api/media/defaults says what
they resolve to).
min_prequired number | null
model_aliasrequired string The alias the thread's turns go to.
pinnedrequired boolean Pinned threads are listed first and are never archived or deleted
by the sweep.
presence_penaltyrequired number | null
profile_idrequired integer | null The personality profile the thread talks with
(GET /chat/api/profiles); null for none ("Default").
purge_atrequired string | null When an archived thread will be deleted; null while it is active,
pinned, or when deleting is switched off.
reasoning_budgetrequired integer | null
reasoning_effortrequired string | null
reasoning_enabledrequired boolean | null Reasoning overrides sent with every turn; null leaves the route's
default.
repeat_penaltyrequired number | null
seedrequired integer | null
stoprequired array of string Stop sequences; empty leaves the route's default.
system_promptrequired string
temperaturerequired number | null Sampling overrides sent with every turn; null leaves the route's
default.
temporaryrequired boolean The thread lives in memory only and is gone at the gateway's next
start unless it is kept.
titlerequired string
top_krequired integer | null
top_prequired number | null
updated_atrequired string Moves with every change to the thread and every new message.
voicerequired ThreadVoice
voice_resolvedrequired VoiceResolved What the thread's voice resolves to now, field by field with the
level each value comes from (the thread, the Chat's settings, the
realtime settings): the speech-to-text and text-to-speech stages
(asr, tts: alias, whether it runs on this machine, what answers
for it while the GPU is held), voice, speech_style, language,
reply_language, read_aloud, turn_detection, audio_input,
seed, the problems that block a voice feature now, and
realtime: whether voice mode can bind the thread.
default Error.
application/json ApiError
post/chat/api/threads/{id}/attachments

Upload an attachment

Capability chat, open to: device, owner. Changes state.

The body is the file's bytes, not multipart; ?name= is its name. The kind is sniffed from the bytes (image, text, pdf, office, audio), never taken from the name or the Content-Type. The file is stored as a draft of the thread, to be sent with the next message (attachments of POST /chat/api/threads/{id}/send), and answered as its metadata, with blockers and hints saying what the thread's current model cannot take. A PDF is read at upload (text-class, scanned or hybrid in meta.class; a text-class one starts with the Chat's PDF mode, or none to ask), an office file likewise, and an audio file is transcribed at once when its model cannot hear it and a speech-to-text model is set (a failure is meta.transcript_error, not a refusal). The body is bounded by max_body_mb (413 body_limit naming it, for a declared or a chunked body). 400 empty_attachment for an empty file, 404 not_found for a thread that is not there or not the caller's, 415 unsupported_attachment for bytes of no supported kind, 422 extract_failed (the file could not be read) or tool_missing (the PDF reader is not installed).

Parameters

NameInDescription
idrequiredpath integer
namerequiredquery string

Request body required

application/octet-stream: string (binary)

Responses

StatusDescription
200 OK.
application/json AttachmentMeta
Fields of AttachmentMeta
blockers array of string For a draft: why it cannot be sent to the thread's current model.
call_id string The tool call that made a tool file, or the card action that made
an action file (its act-<boot>-<n> id, the one its stream's
frames carried); absent for an upload.
extracted_tokensrequired integer | null The extracted text's token estimate; null when there is none.
hints array of string For a draft: what it becomes on the way, sent all the same (an image
as a placeholder, a PDF's pages as its text) under a fallback that
cannot see.
idrequired integer (int64)
kindrequired string image, pdf, text, audio, ... as the upload was classified.
metarequired AttachmentFacts What extraction found: pages, text-less pages, class, sheets,
transcript alias or error, tokens. {} for an image.
mimerequired string
moderequired string | null A text-class PDF's choice, text or images; null when it does
not apply or is not chosen yet.
namerequired string
sizerequired integer (int64) Size in bytes.
sourcerequired string Where the file came from: upload (the user sent it), tool (an
image or audio tool of a turn made it) or action (an image card's
action made it). One of upload, tool, action.
default Error.
application/json ApiError
post/chat/api/threads/{id}/continue

Continue the thread's last reply

Capability chat, open to: device, owner. Changes state.

The model continues the thread's last reply (an assistant prefill) and streams the continuation only: the delta frames are what is added, done's message_id is the continued reply, and the stored reply's text and reasoning grow by what came (its token counts become this call's). The body is optional (a body that is not JSON is 400 bad_request, JSON of another shape 422 bad_request); with speak the continuation is read aloud as it streams, from the clause the reply broke off in. 409 continue_unavailable when the thread's continue state says no (its reason is the message): there is no reply yet, the last message is not a reply, the reply ran tools, or the thread's model cannot take a prefill. The same code answers a reply that stopped being the last message meanwhile. A route the request is re-routed to that cannot take a prefill is refused in the stream, with an error frame. 404 not_found, and a device key's own refusals. The frames are those of a send, without the turn frame.

Parameters

NameInDescription
idrequiredpath integer

Request body

application/json: object

speak boolean Read the answer aloud as it streams.

Responses

StatusDescription
200 An event stream.
text/event-stream string
14 event types

delta TextFrame
delta (a piece of the answer) and reasoning (a piece of the model's
reasoning, kept apart from the answer).

textrequired string

done DoneFrame
done: the turn's last frame. aborted is true when the turn ended
early (refused, stopped, failed before it said anything); a turn that
saved nothing says only that, with no message_id.

abortedrequired boolean
answered_by string | null The alias that answered in its place (a fallback, a candidate
alias's pick), when one did.
completion_tokens integer | null
images_note string A fallback that cannot see answered and got the images as
placeholders: who, in a sentence. Only when it did.
message_id integer (int64) The reply the turn saved or appended to; 0 when it saved none.
model string The thread's model alias.
pending_approvals array of ApprovalRequest The calls the turn stopped on and waits for a decision about; only
when there are some.
prompt_tokens integer | null
reasoning_ignored array of string The thread's reasoning and sampling overrides this route did not send.
reasoning_note string | null The model reasoned although off was asked, in a sentence.
saved boolean Whether the reply is stored. false: its bubble is not a row, and no
action on it can work.
timings Timings | null The authoritative final timings of a local model; null for a cloud
upstream.
total_ms integer (int64)
ttfb_ms integer | null Milliseconds to the first byte of the upstream's answer.

error ErrorFrame
error: something went wrong; the stream goes on to done. code is
what a client branches on (gpu_hold, context_length_exceeded,
vram_queue_timeout, not_saved, superseded, ...); a failure that has
none sends only the message. A stream whose key was disabled, rotated,
deleted or expired, or whose gateway stops, ends with a last error
frame instead of done: revoked (with kind) or gateway_stopping.
An MCP label the thread or its folder attached that offers the turn no
tools gets one frame each, with server_label and a LabelCode
(tool_unreachable, tool_offline, tool_disabled, tool_unknown,
tool_failed), and the turn goes on without it.

code string
kind RevokeKind What a client does about a revoked frame, the token a realtime
session's 4003 close starts its reason with (key_unknown means pair
the device again). Sent with revoked only.
messagerequired string
server_label string The MCP label the frame is about, as the thread or folder attached
it; sent with a LabelCode only.

reasoning TextFrame
delta (a piece of the answer) and reasoning (a piece of the model's
reasoning, kept apart from the answer).

textrequired string

retrieval RetrievalFrame
retrieval: what the knowledge bases found for the user message, before
the model answers.

budget_tokensrequired integer (uint64) The budget the retrieval ran with.
droppedrequired integer (uint64) Excerpts that ranked but did not fit the budget.
excerptsrequired array of ContextExcerpt
kb_idsrequired array of integer (int64) The bases asked for: the thread's and the message's, as they were
then.
message_idrequired integer (int64) The user message the retrieval belongs to.
msrequired number (double) How long the retrieval took.
notesrequired array of string Why something was not searched, or not fully: one sentence each.
queryrequired string What was searched for.
reusedrequired boolean The message's stored retrieval was used again instead of searching.
searchedrequired array of string The bases that were searched, by name.
tokensrequired integer (uint64) Tokens the excerpts use, heading paths included.

speech SpeechFrame
speech: one clause as said, with its audio.

pcmrequired string The clause's audio, base64 of PCM16 little-endian, 24 kHz, mono.
seqrequired integer (uint64) Counts from 0.
textrequired string

speech_done SpeechDone
speech_done: the read-aloud ended, whole or stopped.

audio_msrequired integer (uint64) Length of the audio sent.
charsrequired integer (uint64) Characters spoken.
first_audio_msrequired integer | null From the request's start to the first speech frame; null when
nothing was spoken.
stoppedrequired boolean Stopped (POST .../speech/stop, or the reader went away) before the
text ended.
ttsrequired string
tts_answered_byrequired string | null

speech_error SpeechError
speech_error: the read-aloud cannot speak or failed; it ends the
speech. Codes: tts_not_configured, voice_not_found,
voice_not_configured, instructions_required, a device key's own
refusals, or the failure's kind.

coderequired string
messagerequired string

state ModelState
A voice stage's model state: a chat stream's state frame and a bound
realtime session's lmgw.model.state event.
Read leniently: a field a client does not know of is ignored, a missing
one is empty. Written as the gateway sends it: ms always, the other
optional facts only when the state has them.

aliasrequired string
answered_by string fallback: the alias that answers in its place.
capacity_bytes integer (uint64) skipped with does_not_fit: what the group could have together,
in bytes.
cause string held: gpu_hold or benchmark.
done_bytes integer (uint64) downloading: compressed bytes downloaded so far.
image string downloading: the image the model runs in, being downloaded before
its first start (machine-check design §5). A client says the
download in plain words; the reference is a detail.
message string The sentence a client shows.
msrequired integer | null How long the load took, for ready.
needed_bytes integer (uint64) skipped with does_not_fit: what the stage's group needs on the
card, in bytes.
reason string skipped: full, does_not_fit or cannot_speak.
size_note string downloading: why the size is not known, when it is not.
stagerequired string asr, chat or tts.
staterequired string loading, downloading, ready, held, fallback, skipped or
failed.
total_bytes integer (uint64) downloading: the download's whole size; absent while it is not
known.

stats Timings
Server-measured prefill and decode timings of a local model: the stats
frame (live per token while it streams) and the done frame's final
timings.

cache_n integer (uint64) Prompt tokens served from the KV cache.
draft_n integer (uint64) Draft tokens proposed (speculative or MTP decoding).
draft_n_accepted integer (uint64) Draft tokens accepted.
predicted_ms number (double) Milliseconds spent generating; absent when llama.cpp gave no finite number.
predicted_nrequired integer (uint64) Tokens generated so far.
predicted_per_second number (double) Tokens generated per second; absent when llama.cpp gave no finite number.
prompt_ms number (double) Milliseconds spent on the prompt; absent when llama.cpp gave no finite number.
prompt_nrequired integer (uint64) Prompt tokens actually processed this turn (the cache excluded).
prompt_per_second number (double) Prompt tokens processed per second; absent when llama.cpp gave no finite number.

stop StopFrame
stop: why the model stopped, in OpenAI's words (stop, length,
tool_calls, ...).

reasonrequired string

tool ToolFrame
tool: a tool call of the turn, told apart by event. start and
args while the model writes the call; ready when its arguments are
complete (a call that waits for an approval says needs_approval);
approval for a call that waits for a decision
(POST /chat/api/threads/{id}/approvals); result when it has run. A
result's task says which MCP task a call started: its output is then
started, job <task_id>, and the result enters the thread later.
progress while an image or audio tool runs: its stage, step and latest
preview (ToolProgressFrame), lossy and not in the change feed; a
result's attachments are the files the call stored in the thread.

One of 6 shapes
ToolStartFrame
Fields of ToolStartFrame
id string The model's id of the call; only a turn without tools says it.
indexrequired integer (uint) The call's position in its turn.
namerequired string The tool's exposed name.
ToolArgsFrame
Fields of ToolArgsFrame
fragmentrequired string
indexrequired integer (uint)
ToolReadyFrame
Fields of ToolReadyFrame
argumentsrequired any The call's arguments.
call_idrequired string | null The call's id, as its result frame carries it.
indexrequired integer (uint) The call's position in its turn.
namerequired string The tool's exposed name, as the model called it.
needs_approvalrequired boolean | null The call waits for an approval and does not run now: an approval
frame follows. false for a call that runs (a resumed turn's decided
calls included). Absent from an lmgw before 2026-10-09.
server_labelrequired string | null The label the tool came from; null for a client's own function.
ui_resourcerequired string | null The UI resource the tool links to, as on the result frame.
ApprovalRequest
Fields of ApprovalRequest
approval_request_idrequired string The id a decision quotes (mcpr_…), unique in the gateway.
argumentsrequired string The arguments as the model wrote them: a JSON string.
call_id string The call's id, as its ready and result frames carry it
(mcp_apps::ToolReadyFrame::call_id). Absent from an lmgw
before 2026-10-09, and from an ApprovalRequest read off a bound
session's mcp_approval_request item (OpenAI's shape has none):
there the lmgw.chat.frame relaying the approval frame has it.
namerequired string The tool's own name: the name the model called, without its
label's <prefix>__.
server_labelrequired string The thread's label the tool came from.
ToolResultFrame
Fields of ToolResultFrame
attachments array of AttachmentMeta The files the call stored in the thread — an image or audio tool's
pictures and recordings in a Chat turn — so a page shows them
without reading the thread again. Their bytes are at
GET /chat/api/attachments/{id}; content names them as
lmgw:attachment/N resources. Empty for every other call.
call_idrequired string | null The call's id, as its ready frame carries it.
contentrequired array | null The MCP result's content blocks as the server sent them (resource
URIs namespaced as /mcp sends them; images in full — no bound of
lmgw's own, a device's result is bounded by mcp.host_max_message_mb
on its link); a tool lmgw runs itself, or a call that never reached
a server, says its result in the same shape. Absent from an lmgw
before 2026-10-09: output as one text block then.
indexrequired integer (uint) The call's position in its turn.
is_errorrequired boolean
msrequired integer (uint64)
namerequired string The tool's exposed name (<prefix>__<tool>).
outputrequired string The result as text.
server_labelrequired string | null The label the tool came from: a server's tool prefix (else its
name), or a built-in toolset's (lmgw, docs, kb).
structured_contentrequired any The MCP result's structuredContent, for the view. The model was
given it only when content is empty.
task ResultTask For a call that started an MCP task: which. Absent otherwise.
ui_resourcerequired string | null The UI resource the tool links to (_meta.ui.resourceUri),
namespaced as /mcp serves it: resources/read it there.
ToolProgressFrame
Fields of ToolProgressFrame
call_idrequired string The call's id, as its ready frame carries it.
cancel CancelKind What a cancel would do now, while an image job runs; absent before
the job exists (a cancel then just stops the wait) and for audio.
done_bytes integer (uint64) downloading: compressed bytes downloaded so far.
elapsed_msrequired integer (uint64) Since the call started.
free_bytes integer (uint64) waiting_for_room: the memory free when it was last measured.
image string downloading: the image reference being downloaded.
model string The model the phase is about: the one being unloaded for
unloading, the call's own otherwise.
needs_bytes integer (uint64) waiting_for_room: the memory the model needs, headroom included.
pass integer (uint32) The sampling pass (a batch item, a high- or low-noise stage, a hires
pass); a new pass starts its steps again.
phaserequired MediaPhase | null
preview string The latest preview as the image server drew it: base64, PNG. Its
pixel size depends on the row's preview mode (a quick sketch is the
latent's size, an eighth of the picture's side on the spike's
pipeline).
queue_position integer (uint32) queued: the job's place in the image server's queue.
size_note string downloading: why the size is not known, when it is not ("size not
known — …").
step integer (uint32)
total_bytes integer (uint64) downloading: the download's whole size; absent when it is not
known.
total_steps integer (uint32)

usage UsageFrame
usage: the tokens the model reported for the turn so far.

completion_tokensrequired integer | null
prompt_tokensrequired integer | null

voice VoiceFrame
voice (speech): the read-aloud's route is open.

ttsrequired string The text-to-speech alias.
tts_answered_byrequired string | null The alias that answers in the TTS alias's place (a fallback).
voicerequired string | null The voice every clause is sent with.
default Error.
application/json ApiError
post/chat/api/threads/{id}/delete

Delete a thread

Capability chat, open to: device, owner. Changes state.

Deletes the thread with its messages and attachments. The owner's delete of a thread that is not there still answers ok; a device key's delete of a thread it cannot reach (gone, or Admin Chat) is a 404 not_found.

Parameters

NameInDescription
idrequiredpath integer

Responses

StatusDescription
200 OK.
application/json Ack
Fields of Ack
okrequired boolean Always true; a failure is an error answer instead.
default Error.
application/json ApiError
get/chat/api/threads/{id}/export

Export a thread

Capability chat, open to: device, owner

The thread as one file. format=md (the default) is a readable Markdown transcript, text/markdown; charset=utf-8, with its attachments listed by name; format=json is the lossless lmgw.chat.v1 file, application/json, with every thread column, every message, and each attachment's metadata, extracted text and base64 bytes (the format field of the file says lmgw.chat.v1). The answer carries Content-Disposition: attachment with a file name lmgw-chat-{id}-{title}.md or .json (a temporary thread's id reads temp{n}) and Cache-Control: no-store. A temporary thread is exported from memory. A format other than md, markdown or json is a 400 bad_request; a thread that is not there, or not the caller's to see, is a 404 not_found.

Parameters

NameInDescription
idrequiredpath integer
archivedquery string
formatquery string

Responses

StatusDescription
200 OK.
application/json ChatExport
Fields of ChatExport
draft_attachmentsrequired array of ExportAttachment The attachments not yet sent with a message.
exported_atrequired string When the file was written (RFC 3339, UTC).
folder ExportRef The thread's folder; absent when it is in none.
formatrequired string Always lmgw.chat.v1.
messagesrequired array of ExportMessage Oldest first.
profilerequired ExportRef | null The thread's personality profile; null for none.
threadrequired ExportThread
text/markdown; charset=utf-8 string (binary)
default Error.
application/json ApiError
post/chat/api/threads/{id}/media/{call_id}/cancel

Cancel a running picture or recording

Capability chat, open to: device, owner. Changes state.

Stops the image or audio tool call {call_id} (the call_id of its tool frames) of the turn that runs in the thread, as the turn's Stop stops it, without stopping the turn: the call's result tells the model the picture was not made, and the turn goes on. It also stops a card action of the thread (POST /chat/api/attachments/{id}/media), named by the act-<boot>-<n> id of its stream's action frame; the action's stream then ends with an error frame and nothing is stored. A running image job is cancelled by what its image server can do, which the call's last progress frame named as cancel and the answer repeats: native, the server's own cancel (the model stays loaded); restart, the server cannot stop a running picture and this call is the model's only request, so lmgw stops its container and the next picture loads it again; abandon, another request uses the model, so the call stops waiting and the picture finishes in the background and is thrown away. An upscale has no job: restart or abandon by the same rule, an abandoned one holding its claim until the image server is done. No cancel in the answer: no job ran yet (the call was loading its model or waiting for room, and stops waiting), or an audio call. The body is ignored. A thread the caller does not reach is 404 not_found; a call that is not running, 404 not_running.

Parameters

NameInDescription
idrequiredpath integer
call_idrequiredpath string

Responses

StatusDescription
200 OK.
application/json MediaCancelled
Fields of MediaCancelled
cancel CancelKind What the cancel does to the running image job; absent when no job
runs yet (the call was still loading its model or waiting for room,
and stops waiting) and for an audio call.
okrequired boolean
default Error.
application/json ApiError
post/chat/api/threads/{id}/messages/{mid}/delete

Delete a message

Capability chat, open to: device, owner. Changes state.

Deletes that one message with its attachments; nothing after it moves. A device key below full admin level changes no message of a thread with lmgw's admin tools (403 chat_toolset_needs_full). A thread or message that is not there is a 404 not_found.

Parameters

NameInDescription
idrequiredpath integer
midrequiredpath integer

Responses

StatusDescription
200 OK.
application/json Ack
Fields of Ack
okrequired boolean Always true; a failure is an error answer instead.
default Error.
application/json ApiError
post/chat/api/threads/{id}/messages/{mid}/edit

Edit a message

Capability chat, open to: device, owner. Changes state.

What the answer is depends on the message. A reply is rewritten in place and nothing is sent: its reasoning, token counts and tool record are cleared, since they no longer describe the text, and so are a spoken reply's unheard rest and timing; the answer is JSON, ok and the message as the thread lists it. A user message is rewritten in place (its attachments stay bound), every later message is deleted, and it is answered again: the answer is the event stream of a send, opening with a turn frame. An empty text is a 400 empty_message unless the message carries files. Its stored knowledge retrieval goes with the old text, so auto mode searches again; kb_refs, when sent, replaces its # picks. A dictated message whose text changed becomes a typed one. Everything that can refuse happens before anything is written. Any other role is a 400 bad_request. A device key below full admin level edits no message of a thread with lmgw's admin tools (403 chat_toolset_needs_full); its kb_refs pass its tool scope. A thread or message that is not there is a 404 not_found.

Parameters

NameInDescription
idrequiredpath integer
midrequiredpath integer

Request body required

application/json: object

contentrequired string The new text.
kb_refs array | null A user message's knowledge bases for itself (#), replacing the
ones it had; absent keeps them. Ignored for a reply.
origin string | null A user message's new origin (origin of a send): where the user
writes the edit from. Absent, or blank, keeps the one it had.
Ignored for a reply.
speak boolean Read the new answer aloud as it streams. Ignored for a reply, which
is not answered again.

Responses

StatusDescription
200 OK.
application/json ReplyEdited
Fields of ReplyEdited
messagerequired Message The reply as GET /chat/api/threads/{id} lists it.
okrequired boolean Always true.
text/event-stream string
15 event types

delta TextFrame
delta (a piece of the answer) and reasoning (a piece of the model's
reasoning, kept apart from the answer).

textrequired string

done DoneFrame
done: the turn's last frame. aborted is true when the turn ended
early (refused, stopped, failed before it said anything); a turn that
saved nothing says only that, with no message_id.

abortedrequired boolean
answered_by string | null The alias that answered in its place (a fallback, a candidate
alias's pick), when one did.
completion_tokens integer | null
images_note string A fallback that cannot see answered and got the images as
placeholders: who, in a sentence. Only when it did.
message_id integer (int64) The reply the turn saved or appended to; 0 when it saved none.
model string The thread's model alias.
pending_approvals array of ApprovalRequest The calls the turn stopped on and waits for a decision about; only
when there are some.
prompt_tokens integer | null
reasoning_ignored array of string The thread's reasoning and sampling overrides this route did not send.
reasoning_note string | null The model reasoned although off was asked, in a sentence.
saved boolean Whether the reply is stored. false: its bubble is not a row, and no
action on it can work.
timings Timings | null The authoritative final timings of a local model; null for a cloud
upstream.
total_ms integer (int64)
ttfb_ms integer | null Milliseconds to the first byte of the upstream's answer.

error ErrorFrame
error: something went wrong; the stream goes on to done. code is
what a client branches on (gpu_hold, context_length_exceeded,
vram_queue_timeout, not_saved, superseded, ...); a failure that has
none sends only the message. A stream whose key was disabled, rotated,
deleted or expired, or whose gateway stops, ends with a last error
frame instead of done: revoked (with kind) or gateway_stopping.
An MCP label the thread or its folder attached that offers the turn no
tools gets one frame each, with server_label and a LabelCode
(tool_unreachable, tool_offline, tool_disabled, tool_unknown,
tool_failed), and the turn goes on without it.

code string
kind RevokeKind What a client does about a revoked frame, the token a realtime
session's 4003 close starts its reason with (key_unknown means pair
the device again). Sent with revoked only.
messagerequired string
server_label string The MCP label the frame is about, as the thread or folder attached
it; sent with a LabelCode only.

reasoning TextFrame
delta (a piece of the answer) and reasoning (a piece of the model's
reasoning, kept apart from the answer).

textrequired string

retrieval RetrievalFrame
retrieval: what the knowledge bases found for the user message, before
the model answers.

budget_tokensrequired integer (uint64) The budget the retrieval ran with.
droppedrequired integer (uint64) Excerpts that ranked but did not fit the budget.
excerptsrequired array of ContextExcerpt
kb_idsrequired array of integer (int64) The bases asked for: the thread's and the message's, as they were
then.
message_idrequired integer (int64) The user message the retrieval belongs to.
msrequired number (double) How long the retrieval took.
notesrequired array of string Why something was not searched, or not fully: one sentence each.
queryrequired string What was searched for.
reusedrequired boolean The message's stored retrieval was used again instead of searching.
searchedrequired array of string The bases that were searched, by name.
tokensrequired integer (uint64) Tokens the excerpts use, heading paths included.

speech SpeechFrame
speech: one clause as said, with its audio.

pcmrequired string The clause's audio, base64 of PCM16 little-endian, 24 kHz, mono.
seqrequired integer (uint64) Counts from 0.
textrequired string

speech_done SpeechDone
speech_done: the read-aloud ended, whole or stopped.

audio_msrequired integer (uint64) Length of the audio sent.
charsrequired integer (uint64) Characters spoken.
first_audio_msrequired integer | null From the request's start to the first speech frame; null when
nothing was spoken.
stoppedrequired boolean Stopped (POST .../speech/stop, or the reader went away) before the
text ended.
ttsrequired string
tts_answered_byrequired string | null

speech_error SpeechError
speech_error: the read-aloud cannot speak or failed; it ends the
speech. Codes: tts_not_configured, voice_not_found,
voice_not_configured, instructions_required, a device key's own
refusals, or the failure's kind.

coderequired string
messagerequired string

state ModelState
A voice stage's model state: a chat stream's state frame and a bound
realtime session's lmgw.model.state event.
Read leniently: a field a client does not know of is ignored, a missing
one is empty. Written as the gateway sends it: ms always, the other
optional facts only when the state has them.

aliasrequired string
answered_by string fallback: the alias that answers in its place.
capacity_bytes integer (uint64) skipped with does_not_fit: what the group could have together,
in bytes.
cause string held: gpu_hold or benchmark.
done_bytes integer (uint64) downloading: compressed bytes downloaded so far.
image string downloading: the image the model runs in, being downloaded before
its first start (machine-check design §5). A client says the
download in plain words; the reference is a detail.
message string The sentence a client shows.
msrequired integer | null How long the load took, for ready.
needed_bytes integer (uint64) skipped with does_not_fit: what the stage's group needs on the
card, in bytes.
reason string skipped: full, does_not_fit or cannot_speak.
size_note string downloading: why the size is not known, when it is not.
stagerequired string asr, chat or tts.
staterequired string loading, downloading, ready, held, fallback, skipped or
failed.
total_bytes integer (uint64) downloading: the download's whole size; absent while it is not
known.

stats Timings
Server-measured prefill and decode timings of a local model: the stats
frame (live per token while it streams) and the done frame's final
timings.

cache_n integer (uint64) Prompt tokens served from the KV cache.
draft_n integer (uint64) Draft tokens proposed (speculative or MTP decoding).
draft_n_accepted integer (uint64) Draft tokens accepted.
predicted_ms number (double) Milliseconds spent generating; absent when llama.cpp gave no finite number.
predicted_nrequired integer (uint64) Tokens generated so far.
predicted_per_second number (double) Tokens generated per second; absent when llama.cpp gave no finite number.
prompt_ms number (double) Milliseconds spent on the prompt; absent when llama.cpp gave no finite number.
prompt_nrequired integer (uint64) Prompt tokens actually processed this turn (the cache excluded).
prompt_per_second number (double) Prompt tokens processed per second; absent when llama.cpp gave no finite number.

stop StopFrame
stop: why the model stopped, in OpenAI's words (stop, length,
tool_calls, ...).

reasonrequired string

tool ToolFrame
tool: a tool call of the turn, told apart by event. start and
args while the model writes the call; ready when its arguments are
complete (a call that waits for an approval says needs_approval);
approval for a call that waits for a decision
(POST /chat/api/threads/{id}/approvals); result when it has run. A
result's task says which MCP task a call started: its output is then
started, job <task_id>, and the result enters the thread later.
progress while an image or audio tool runs: its stage, step and latest
preview (ToolProgressFrame), lossy and not in the change feed; a
result's attachments are the files the call stored in the thread.

One of 6 shapes
ToolStartFrame
Fields of ToolStartFrame
id string The model's id of the call; only a turn without tools says it.
indexrequired integer (uint) The call's position in its turn.
namerequired string The tool's exposed name.
ToolArgsFrame
Fields of ToolArgsFrame
fragmentrequired string
indexrequired integer (uint)
ToolReadyFrame
Fields of ToolReadyFrame
argumentsrequired any The call's arguments.
call_idrequired string | null The call's id, as its result frame carries it.
indexrequired integer (uint) The call's position in its turn.
namerequired string The tool's exposed name, as the model called it.
needs_approvalrequired boolean | null The call waits for an approval and does not run now: an approval
frame follows. false for a call that runs (a resumed turn's decided
calls included). Absent from an lmgw before 2026-10-09.
server_labelrequired string | null The label the tool came from; null for a client's own function.
ui_resourcerequired string | null The UI resource the tool links to, as on the result frame.
ApprovalRequest
Fields of ApprovalRequest
approval_request_idrequired string The id a decision quotes (mcpr_…), unique in the gateway.
argumentsrequired string The arguments as the model wrote them: a JSON string.
call_id string The call's id, as its ready and result frames carry it
(mcp_apps::ToolReadyFrame::call_id). Absent from an lmgw
before 2026-10-09, and from an ApprovalRequest read off a bound
session's mcp_approval_request item (OpenAI's shape has none):
there the lmgw.chat.frame relaying the approval frame has it.
namerequired string The tool's own name: the name the model called, without its
label's <prefix>__.
server_labelrequired string The thread's label the tool came from.
ToolResultFrame
Fields of ToolResultFrame
attachments array of AttachmentMeta The files the call stored in the thread — an image or audio tool's
pictures and recordings in a Chat turn — so a page shows them
without reading the thread again. Their bytes are at
GET /chat/api/attachments/{id}; content names them as
lmgw:attachment/N resources. Empty for every other call.
call_idrequired string | null The call's id, as its ready frame carries it.
contentrequired array | null The MCP result's content blocks as the server sent them (resource
URIs namespaced as /mcp sends them; images in full — no bound of
lmgw's own, a device's result is bounded by mcp.host_max_message_mb
on its link); a tool lmgw runs itself, or a call that never reached
a server, says its result in the same shape. Absent from an lmgw
before 2026-10-09: output as one text block then.
indexrequired integer (uint) The call's position in its turn.
is_errorrequired boolean
msrequired integer (uint64)
namerequired string The tool's exposed name (<prefix>__<tool>).
outputrequired string The result as text.
server_labelrequired string | null The label the tool came from: a server's tool prefix (else its
name), or a built-in toolset's (lmgw, docs, kb).
structured_contentrequired any The MCP result's structuredContent, for the view. The model was
given it only when content is empty.
task ResultTask For a call that started an MCP task: which. Absent otherwise.
ui_resourcerequired string | null The UI resource the tool links to (_meta.ui.resourceUri),
namespaced as /mcp serves it: resources/read it there.
ToolProgressFrame
Fields of ToolProgressFrame
call_idrequired string The call's id, as its ready frame carries it.
cancel CancelKind What a cancel would do now, while an image job runs; absent before
the job exists (a cancel then just stops the wait) and for audio.
done_bytes integer (uint64) downloading: compressed bytes downloaded so far.
elapsed_msrequired integer (uint64) Since the call started.
free_bytes integer (uint64) waiting_for_room: the memory free when it was last measured.
image string downloading: the image reference being downloaded.
model string The model the phase is about: the one being unloaded for
unloading, the call's own otherwise.
needs_bytes integer (uint64) waiting_for_room: the memory the model needs, headroom included.
pass integer (uint32) The sampling pass (a batch item, a high- or low-noise stage, a hires
pass); a new pass starts its steps again.
phaserequired MediaPhase | null
preview string The latest preview as the image server drew it: base64, PNG. Its
pixel size depends on the row's preview mode (a quick sketch is the
latent's size, an eighth of the picture's side on the spike's
pipeline).
queue_position integer (uint32) queued: the job's place in the image server's queue.
size_note string downloading: why the size is not known, when it is not ("size not
known — …").
step integer (uint32)
total_bytes integer (uint64) downloading: the download's whole size; absent when it is not
known.
total_steps integer (uint32)

turn TurnStarted
turn: the first frame of a turn that wrote a user message (a send, an
edit of a user message).

user_message_idrequired integer (int64) The user message the answer follows.

usage UsageFrame
usage: the tokens the model reported for the turn so far.

completion_tokensrequired integer | null
prompt_tokensrequired integer | null

voice VoiceFrame
voice (speech): the read-aloud's route is open.

ttsrequired string The text-to-speech alias.
tts_answered_byrequired string | null The alias that answers in the TTS alias's place (a fallback).
voicerequired string | null The voice every clause is sent with.
default Error.
application/json ApiError
post/chat/api/threads/{id}/messages/{mid}/regenerate

Answer a message again

Capability chat, open to: device, owner. Changes state.

Cuts the thread at the message and streams a new answer. On a reply, it and every later message are deleted and the model answers the history before it, which has to end with a user message (or a job's result): 409 nothing_to_answer otherwise, and nothing is deleted. On a user message, every later message is deleted, it is answered again, and the stream opens with a turn frame carrying its id. Any other role is 400 bad_request; 404 not_found for a thread or message that is not there; a device key below full admin level changes no message of a thread with lmgw's admin tools (403 chat_toolset_needs_full). The model's capabilities are read before anything is cut. The body is optional (a body that is not JSON is 400 bad_request, JSON of another shape 422 bad_request); with speak the answer is read aloud as it streams. The frames are those of a send.

Parameters

NameInDescription
idrequiredpath integer
midrequiredpath integer

Request body

application/json: object

speak boolean Read the answer aloud as it streams.

Responses

StatusDescription
200 An event stream.
text/event-stream string
15 event types

delta TextFrame
delta (a piece of the answer) and reasoning (a piece of the model's
reasoning, kept apart from the answer).

textrequired string

done DoneFrame
done: the turn's last frame. aborted is true when the turn ended
early (refused, stopped, failed before it said anything); a turn that
saved nothing says only that, with no message_id.

abortedrequired boolean
answered_by string | null The alias that answered in its place (a fallback, a candidate
alias's pick), when one did.
completion_tokens integer | null
images_note string A fallback that cannot see answered and got the images as
placeholders: who, in a sentence. Only when it did.
message_id integer (int64) The reply the turn saved or appended to; 0 when it saved none.
model string The thread's model alias.
pending_approvals array of ApprovalRequest The calls the turn stopped on and waits for a decision about; only
when there are some.
prompt_tokens integer | null
reasoning_ignored array of string The thread's reasoning and sampling overrides this route did not send.
reasoning_note string | null The model reasoned although off was asked, in a sentence.
saved boolean Whether the reply is stored. false: its bubble is not a row, and no
action on it can work.
timings Timings | null The authoritative final timings of a local model; null for a cloud
upstream.
total_ms integer (int64)
ttfb_ms integer | null Milliseconds to the first byte of the upstream's answer.

error ErrorFrame
error: something went wrong; the stream goes on to done. code is
what a client branches on (gpu_hold, context_length_exceeded,
vram_queue_timeout, not_saved, superseded, ...); a failure that has
none sends only the message. A stream whose key was disabled, rotated,
deleted or expired, or whose gateway stops, ends with a last error
frame instead of done: revoked (with kind) or gateway_stopping.
An MCP label the thread or its folder attached that offers the turn no
tools gets one frame each, with server_label and a LabelCode
(tool_unreachable, tool_offline, tool_disabled, tool_unknown,
tool_failed), and the turn goes on without it.

code string
kind RevokeKind What a client does about a revoked frame, the token a realtime
session's 4003 close starts its reason with (key_unknown means pair
the device again). Sent with revoked only.
messagerequired string
server_label string The MCP label the frame is about, as the thread or folder attached
it; sent with a LabelCode only.

reasoning TextFrame
delta (a piece of the answer) and reasoning (a piece of the model's
reasoning, kept apart from the answer).

textrequired string

retrieval RetrievalFrame
retrieval: what the knowledge bases found for the user message, before
the model answers.

budget_tokensrequired integer (uint64) The budget the retrieval ran with.
droppedrequired integer (uint64) Excerpts that ranked but did not fit the budget.
excerptsrequired array of ContextExcerpt
kb_idsrequired array of integer (int64) The bases asked for: the thread's and the message's, as they were
then.
message_idrequired integer (int64) The user message the retrieval belongs to.
msrequired number (double) How long the retrieval took.
notesrequired array of string Why something was not searched, or not fully: one sentence each.
queryrequired string What was searched for.
reusedrequired boolean The message's stored retrieval was used again instead of searching.
searchedrequired array of string The bases that were searched, by name.
tokensrequired integer (uint64) Tokens the excerpts use, heading paths included.

speech SpeechFrame
speech: one clause as said, with its audio.

pcmrequired string The clause's audio, base64 of PCM16 little-endian, 24 kHz, mono.
seqrequired integer (uint64) Counts from 0.
textrequired string

speech_done SpeechDone
speech_done: the read-aloud ended, whole or stopped.

audio_msrequired integer (uint64) Length of the audio sent.
charsrequired integer (uint64) Characters spoken.
first_audio_msrequired integer | null From the request's start to the first speech frame; null when
nothing was spoken.
stoppedrequired boolean Stopped (POST .../speech/stop, or the reader went away) before the
text ended.
ttsrequired string
tts_answered_byrequired string | null

speech_error SpeechError
speech_error: the read-aloud cannot speak or failed; it ends the
speech. Codes: tts_not_configured, voice_not_found,
voice_not_configured, instructions_required, a device key's own
refusals, or the failure's kind.

coderequired string
messagerequired string

state ModelState
A voice stage's model state: a chat stream's state frame and a bound
realtime session's lmgw.model.state event.
Read leniently: a field a client does not know of is ignored, a missing
one is empty. Written as the gateway sends it: ms always, the other
optional facts only when the state has them.

aliasrequired string
answered_by string fallback: the alias that answers in its place.
capacity_bytes integer (uint64) skipped with does_not_fit: what the group could have together,
in bytes.
cause string held: gpu_hold or benchmark.
done_bytes integer (uint64) downloading: compressed bytes downloaded so far.
image string downloading: the image the model runs in, being downloaded before
its first start (machine-check design §5). A client says the
download in plain words; the reference is a detail.
message string The sentence a client shows.
msrequired integer | null How long the load took, for ready.
needed_bytes integer (uint64) skipped with does_not_fit: what the stage's group needs on the
card, in bytes.
reason string skipped: full, does_not_fit or cannot_speak.
size_note string downloading: why the size is not known, when it is not.
stagerequired string asr, chat or tts.
staterequired string loading, downloading, ready, held, fallback, skipped or
failed.
total_bytes integer (uint64) downloading: the download's whole size; absent while it is not
known.

stats Timings
Server-measured prefill and decode timings of a local model: the stats
frame (live per token while it streams) and the done frame's final
timings.

cache_n integer (uint64) Prompt tokens served from the KV cache.
draft_n integer (uint64) Draft tokens proposed (speculative or MTP decoding).
draft_n_accepted integer (uint64) Draft tokens accepted.
predicted_ms number (double) Milliseconds spent generating; absent when llama.cpp gave no finite number.
predicted_nrequired integer (uint64) Tokens generated so far.
predicted_per_second number (double) Tokens generated per second; absent when llama.cpp gave no finite number.
prompt_ms number (double) Milliseconds spent on the prompt; absent when llama.cpp gave no finite number.
prompt_nrequired integer (uint64) Prompt tokens actually processed this turn (the cache excluded).
prompt_per_second number (double) Prompt tokens processed per second; absent when llama.cpp gave no finite number.

stop StopFrame
stop: why the model stopped, in OpenAI's words (stop, length,
tool_calls, ...).

reasonrequired string

tool ToolFrame
tool: a tool call of the turn, told apart by event. start and
args while the model writes the call; ready when its arguments are
complete (a call that waits for an approval says needs_approval);
approval for a call that waits for a decision
(POST /chat/api/threads/{id}/approvals); result when it has run. A
result's task says which MCP task a call started: its output is then
started, job <task_id>, and the result enters the thread later.
progress while an image or audio tool runs: its stage, step and latest
preview (ToolProgressFrame), lossy and not in the change feed; a
result's attachments are the files the call stored in the thread.

One of 6 shapes
ToolStartFrame
Fields of ToolStartFrame
id string The model's id of the call; only a turn without tools says it.
indexrequired integer (uint) The call's position in its turn.
namerequired string The tool's exposed name.
ToolArgsFrame
Fields of ToolArgsFrame
fragmentrequired string
indexrequired integer (uint)
ToolReadyFrame
Fields of ToolReadyFrame
argumentsrequired any The call's arguments.
call_idrequired string | null The call's id, as its result frame carries it.
indexrequired integer (uint) The call's position in its turn.
namerequired string The tool's exposed name, as the model called it.
needs_approvalrequired boolean | null The call waits for an approval and does not run now: an approval
frame follows. false for a call that runs (a resumed turn's decided
calls included). Absent from an lmgw before 2026-10-09.
server_labelrequired string | null The label the tool came from; null for a client's own function.
ui_resourcerequired string | null The UI resource the tool links to, as on the result frame.
ApprovalRequest
Fields of ApprovalRequest
approval_request_idrequired string The id a decision quotes (mcpr_…), unique in the gateway.
argumentsrequired string The arguments as the model wrote them: a JSON string.
call_id string The call's id, as its ready and result frames carry it
(mcp_apps::ToolReadyFrame::call_id). Absent from an lmgw
before 2026-10-09, and from an ApprovalRequest read off a bound
session's mcp_approval_request item (OpenAI's shape has none):
there the lmgw.chat.frame relaying the approval frame has it.
namerequired string The tool's own name: the name the model called, without its
label's <prefix>__.
server_labelrequired string The thread's label the tool came from.
ToolResultFrame
Fields of ToolResultFrame
attachments array of AttachmentMeta The files the call stored in the thread — an image or audio tool's
pictures and recordings in a Chat turn — so a page shows them
without reading the thread again. Their bytes are at
GET /chat/api/attachments/{id}; content names them as
lmgw:attachment/N resources. Empty for every other call.
call_idrequired string | null The call's id, as its ready frame carries it.
contentrequired array | null The MCP result's content blocks as the server sent them (resource
URIs namespaced as /mcp sends them; images in full — no bound of
lmgw's own, a device's result is bounded by mcp.host_max_message_mb
on its link); a tool lmgw runs itself, or a call that never reached
a server, says its result in the same shape. Absent from an lmgw
before 2026-10-09: output as one text block then.
indexrequired integer (uint) The call's position in its turn.
is_errorrequired boolean
msrequired integer (uint64)
namerequired string The tool's exposed name (<prefix>__<tool>).
outputrequired string The result as text.
server_labelrequired string | null The label the tool came from: a server's tool prefix (else its
name), or a built-in toolset's (lmgw, docs, kb).
structured_contentrequired any The MCP result's structuredContent, for the view. The model was
given it only when content is empty.
task ResultTask For a call that started an MCP task: which. Absent otherwise.
ui_resourcerequired string | null The UI resource the tool links to (_meta.ui.resourceUri),
namespaced as /mcp serves it: resources/read it there.
ToolProgressFrame
Fields of ToolProgressFrame
call_idrequired string The call's id, as its ready frame carries it.
cancel CancelKind What a cancel would do now, while an image job runs; absent before
the job exists (a cancel then just stops the wait) and for audio.
done_bytes integer (uint64) downloading: compressed bytes downloaded so far.
elapsed_msrequired integer (uint64) Since the call started.
free_bytes integer (uint64) waiting_for_room: the memory free when it was last measured.
image string downloading: the image reference being downloaded.
model string The model the phase is about: the one being unloaded for
unloading, the call's own otherwise.
needs_bytes integer (uint64) waiting_for_room: the memory the model needs, headroom included.
pass integer (uint32) The sampling pass (a batch item, a high- or low-noise stage, a hires
pass); a new pass starts its steps again.
phaserequired MediaPhase | null
preview string The latest preview as the image server drew it: base64, PNG. Its
pixel size depends on the row's preview mode (a quick sketch is the
latent's size, an eighth of the picture's side on the spike's
pipeline).
queue_position integer (uint32) queued: the job's place in the image server's queue.
size_note string downloading: why the size is not known, when it is not ("size not
known — …").
step integer (uint32)
total_bytes integer (uint64) downloading: the download's whole size; absent when it is not
known.
total_steps integer (uint32)

turn TurnStarted
turn: the first frame of a turn that wrote a user message (a send, an
edit of a user message).

user_message_idrequired integer (int64) The user message the answer follows.

usage UsageFrame
usage: the tokens the model reported for the turn so far.

completion_tokensrequired integer | null
prompt_tokensrequired integer | null

voice VoiceFrame
voice (speech): the read-aloud's route is open.

ttsrequired string The text-to-speech alias.
tts_answered_byrequired string | null The alias that answers in the TTS alias's place (a fallback).
voicerequired string | null The voice every clause is sent with.
default Error.
application/json ApiError
post/chat/api/threads/{id}/messages/{mid}/speak

Read a stored reply aloud

Capability chat, open to: device, owner. Changes state.

Reads the reply as it is shown (its content, then a spoken reply's unheard rest) with the thread's text-to-speech model and voice, and streams the audio as it is made: state while the speech model is not resident (loading, then ready, fallback, held or failed), voice once its route is open, a speech frame per clause (seq counting from 0, the text said, pcm: base64 PCM16 little-endian, 24 kHz, mono) and speech_done with the totals. A thread that cannot speak (no speech model, no such voice, a voice that needs instructions) and a voice that fails mid-way end with a speech_error frame (codes tts_not_configured, voice_not_found, voice_not_configured, instructions_required, or the failure's kind). One speech row is written per call. Closing the stream stops the synthesis at its next step; POST /chat/api/threads/{id}/speech/stop stops every read-aloud of the thread. A device or owner key that is disabled, rotated, deleted or expired while it streams, and a gateway that stops, end the stream with a last error frame (code revoked, with kind, or gateway_stopping). Refused before any frame: 404 not_found (thread or message), 400 bad_request (the message is not a reply), 400 empty_message (a reply with no text).

Parameters

NameInDescription
idrequiredpath integer
midrequiredpath integer

Responses

StatusDescription
200 An event stream.
text/event-stream string
6 event types

error ErrorFrame
error: something went wrong; the stream goes on to done. code is
what a client branches on (gpu_hold, context_length_exceeded,
vram_queue_timeout, not_saved, superseded, ...); a failure that has
none sends only the message. A stream whose key was disabled, rotated,
deleted or expired, or whose gateway stops, ends with a last error
frame instead of done: revoked (with kind) or gateway_stopping.
An MCP label the thread or its folder attached that offers the turn no
tools gets one frame each, with server_label and a LabelCode
(tool_unreachable, tool_offline, tool_disabled, tool_unknown,
tool_failed), and the turn goes on without it.

code string
kind RevokeKind What a client does about a revoked frame, the token a realtime
session's 4003 close starts its reason with (key_unknown means pair
the device again). Sent with revoked only.
messagerequired string
server_label string The MCP label the frame is about, as the thread or folder attached
it; sent with a LabelCode only.

speech SpeechFrame
speech: one clause as said, with its audio.

pcmrequired string The clause's audio, base64 of PCM16 little-endian, 24 kHz, mono.
seqrequired integer (uint64) Counts from 0.
textrequired string

speech_done SpeechDone
speech_done: the read-aloud ended, whole or stopped.

audio_msrequired integer (uint64) Length of the audio sent.
charsrequired integer (uint64) Characters spoken.
first_audio_msrequired integer | null From the request's start to the first speech frame; null when
nothing was spoken.
stoppedrequired boolean Stopped (POST .../speech/stop, or the reader went away) before the
text ended.
ttsrequired string
tts_answered_byrequired string | null

speech_error SpeechError
speech_error: the read-aloud cannot speak or failed; it ends the
speech. Codes: tts_not_configured, voice_not_found,
voice_not_configured, instructions_required, a device key's own
refusals, or the failure's kind.

coderequired string
messagerequired string

state ModelState
A voice stage's model state: a chat stream's state frame and a bound
realtime session's lmgw.model.state event.
Read leniently: a field a client does not know of is ignored, a missing
one is empty. Written as the gateway sends it: ms always, the other
optional facts only when the state has them.

aliasrequired string
answered_by string fallback: the alias that answers in its place.
capacity_bytes integer (uint64) skipped with does_not_fit: what the group could have together,
in bytes.
cause string held: gpu_hold or benchmark.
done_bytes integer (uint64) downloading: compressed bytes downloaded so far.
image string downloading: the image the model runs in, being downloaded before
its first start (machine-check design §5). A client says the
download in plain words; the reference is a detail.
message string The sentence a client shows.
msrequired integer | null How long the load took, for ready.
needed_bytes integer (uint64) skipped with does_not_fit: what the stage's group needs on the
card, in bytes.
reason string skipped: full, does_not_fit or cannot_speak.
size_note string downloading: why the size is not known, when it is not.
stagerequired string asr, chat or tts.
staterequired string loading, downloading, ready, held, fallback, skipped or
failed.
total_bytes integer (uint64) downloading: the download's whole size; absent while it is not
known.

voice VoiceFrame
voice (speech): the read-aloud's route is open.

ttsrequired string The text-to-speech alias.
tts_answered_byrequired string | null The alias that answers in the TTS alias's place (a fallback).
voicerequired string | null The voice every clause is sent with.
default Error.
application/json ApiError
post/chat/api/threads/{id}/move

Move a thread into a folder

Capability chat, open to: device, owner. Changes state.

Moves the thread into the folder, or out of any folder with folder_id: null, and answers the thread as the list carries it. The change reaches every client as a thread.updated event. A temporary thread has no folder until it is kept: 409 temporary_thread. A thread or folder the caller cannot reach is a 404 not_found.

Parameters

NameInDescription
idrequiredpath integer

Request body required

application/json: object

folder_id integer | null The target folder; null takes the thread out of any folder.

Responses

StatusDescription
200 OK.
application/json Thread
Fields of Thread
agent_idrequired string | null The agent the thread was opened from, if any.
archived_atrequired string | null When the thread was archived; null while it is active.
continue ContinueState Whether the last reply can be continued. Present where the thread
is read whole, as POST /chat/api/folders/{id}/current answers it.
created_atrequired string
folder_idrequired integer | null The folder the thread is in; null for none.
frequency_penaltyrequired number | null
idrequired integer (int64) Negative for a temporary thread.
kb_budget_tokensrequired integer | null The retrieval budget of auto mode in tokens; null for the Chat's
setting.
kb_idsrequired array of integer (int64) Knowledge bases the thread searches, by id.
kb_moderequired KbMode
kindrequired string chat, or admin for a thread that drives the gateway's own
configuration (never listed for a device key).
last_message_atrequired integer | null When its newest message was written, in unix seconds; null for a
thread without messages. An ongoing folder's idle rollover is
measured from it: a client that shows when the conversation moves
on reads it here rather than timing the turns it saw.
max_tokensrequired integer | null
mcp_toolsrequired array of ThreadMcp The tool servers the thread's turns use; empty for a plain chat. A
thread with lmgw (the self-admin toolset) among them is listed for a
device key only when the device may use lmgw's admin tools.
media_defaultsrequired MediaDefaults The thread's own default models of the image and audio tools; an
absent field inherits its folder's, then Settings → Chat's, and an
empty one is no default (GET /chat/api/media/defaults says what
they resolve to).
min_prequired number | null
model_aliasrequired string The alias the thread's turns go to.
pinnedrequired boolean Pinned threads are listed first and are never archived or deleted
by the sweep.
presence_penaltyrequired number | null
profile_idrequired integer | null The personality profile the thread talks with
(GET /chat/api/profiles); null for none ("Default").
purge_atrequired string | null When an archived thread will be deleted; null while it is active,
pinned, or when deleting is switched off.
reasoning_budgetrequired integer | null
reasoning_effortrequired string | null
reasoning_enabledrequired boolean | null Reasoning overrides sent with every turn; null leaves the route's
default.
repeat_penaltyrequired number | null
seedrequired integer | null
stoprequired array of string Stop sequences; empty leaves the route's default.
system_promptrequired string
temperaturerequired number | null Sampling overrides sent with every turn; null leaves the route's
default.
temporaryrequired boolean The thread lives in memory only and is gone at the gateway's next
start unless it is kept.
titlerequired string
top_krequired integer | null
top_prequired number | null
updated_atrequired string Moves with every change to the thread and every new message.
voicerequired ThreadVoice
voice_resolvedrequired VoiceResolved What the thread's voice resolves to now, field by field with the
level each value comes from (the thread, the Chat's settings, the
realtime settings): the speech-to-text and text-to-speech stages
(asr, tts: alias, whether it runs on this machine, what answers
for it while the GPU is held), voice, speech_style, language,
reply_language, read_aloud, turn_detection, audio_input,
seed, the problems that block a voice feature now, and
realtime: whether voice mode can bind the thread.
default Error.
application/json ApiError
post/chat/api/threads/{id}/persist

Keep a temporary thread

Capability chat, open to: device, owner. Changes state.

Writes a temporary thread (messages, attachments, settings) to the database as an ordinary thread and drops it from memory. Answers the stored thread and its new, positive id; the temporary id is gone. A thread that is already stored is a 409 not_temporary; a keep of the same thread already running a 409 keep_in_progress; a keep while a realtime voice session is bound to the thread a 409 voice_session_active. An unknown temporary thread is a 404 not_found.

Parameters

NameInDescription
idrequiredpath integer

Responses

StatusDescription
200 OK.
application/json ThreadKept
Fields of ThreadKept
idrequired integer (int64) The stored thread's new, positive id.
threadrequired Thread The stored thread.
default Error.
application/json ApiError
post/chat/api/threads/{id}/pin

Pin or unpin a thread

Capability chat, open to: device, owner. Changes state.

Pinned threads are listed first and are never archived or deleted by the retention sweep. Pinning an archived thread also restores it. Answers the thread as the list carries it. A temporary thread has nothing to pin until it is kept: 409 temporary_thread. A thread the caller cannot reach is a 404 not_found.

Parameters

NameInDescription
idrequiredpath integer

Request body required

application/json: object

pinnedrequired boolean Pin (true) or unpin the thread. Pinning an archived thread also
restores it.

Responses

StatusDescription
200 OK.
application/json Thread
Fields of Thread
agent_idrequired string | null The agent the thread was opened from, if any.
archived_atrequired string | null When the thread was archived; null while it is active.
continue ContinueState Whether the last reply can be continued. Present where the thread
is read whole, as POST /chat/api/folders/{id}/current answers it.
created_atrequired string
folder_idrequired integer | null The folder the thread is in; null for none.
frequency_penaltyrequired number | null
idrequired integer (int64) Negative for a temporary thread.
kb_budget_tokensrequired integer | null The retrieval budget of auto mode in tokens; null for the Chat's
setting.
kb_idsrequired array of integer (int64) Knowledge bases the thread searches, by id.
kb_moderequired KbMode
kindrequired string chat, or admin for a thread that drives the gateway's own
configuration (never listed for a device key).
last_message_atrequired integer | null When its newest message was written, in unix seconds; null for a
thread without messages. An ongoing folder's idle rollover is
measured from it: a client that shows when the conversation moves
on reads it here rather than timing the turns it saw.
max_tokensrequired integer | null
mcp_toolsrequired array of ThreadMcp The tool servers the thread's turns use; empty for a plain chat. A
thread with lmgw (the self-admin toolset) among them is listed for a
device key only when the device may use lmgw's admin tools.
media_defaultsrequired MediaDefaults The thread's own default models of the image and audio tools; an
absent field inherits its folder's, then Settings → Chat's, and an
empty one is no default (GET /chat/api/media/defaults says what
they resolve to).
min_prequired number | null
model_aliasrequired string The alias the thread's turns go to.
pinnedrequired boolean Pinned threads are listed first and are never archived or deleted
by the sweep.
presence_penaltyrequired number | null
profile_idrequired integer | null The personality profile the thread talks with
(GET /chat/api/profiles); null for none ("Default").
purge_atrequired string | null When an archived thread will be deleted; null while it is active,
pinned, or when deleting is switched off.
reasoning_budgetrequired integer | null
reasoning_effortrequired string | null
reasoning_enabledrequired boolean | null Reasoning overrides sent with every turn; null leaves the route's
default.
repeat_penaltyrequired number | null
seedrequired integer | null
stoprequired array of string Stop sequences; empty leaves the route's default.
system_promptrequired string
temperaturerequired number | null Sampling overrides sent with every turn; null leaves the route's
default.
temporaryrequired boolean The thread lives in memory only and is gone at the gateway's next
start unless it is kept.
titlerequired string
top_krequired integer | null
top_prequired number | null
updated_atrequired string Moves with every change to the thread and every new message.
voicerequired ThreadVoice
voice_resolvedrequired VoiceResolved What the thread's voice resolves to now, field by field with the
level each value comes from (the thread, the Chat's settings, the
realtime settings): the speech-to-text and text-to-speech stages
(asr, tts: alias, whether it runs on this machine, what answers
for it while the GPU is held), voice, speech_style, language,
reply_language, read_aloud, turn_detection, audio_input,
seed, the problems that block a voice feature now, and
realtime: whether voice mode can bind the thread.
default Error.
application/json ApiError
post/chat/api/threads/{id}/send

Send a message and stream the answer

Capability chat, open to: device, owner. Changes state.

Writes the user message (with the draft attachments it binds and the knowledge bases it picks) and streams the model's answer. The message is stored before the model is called, so a client that goes away has still recorded what it asked; an untitled thread is titled from it. content may be empty when attachments are bound. A dictated message names its origin in voice (via: dictation); with speak, the reply is read aloud as it streams and the stream also carries voice, speech, speech_done and speech_error frames (the speech frames' audio is base64 PCM16, 24 kHz, mono). The first frame is turn with the user message's id. Refused before anything is written: 400 empty_message (no text and no attachment), 400 bad_request (a knowledge base that does not exist), 400 attachment_not_draft (an id that is no draft of the thread), 400 model_no_vision (a new image and a model that cannot see), 422 attachment_blocked (a file the thread's model cannot take, named), 404 not_found and a device key's own refusals (its scope, its budget). A body that is not JSON is 400 bad_request, JSON of another shape (an unknown or mistyped field, voice included) 422 bad_request, and a voice.via other than dictation (realtime, say) 400 bad_request. 409 attachment_not_draft: a concurrent send took a draft first. A turn that fails after the stream began says so in an error frame. The answer is a server-sent event stream; every frame's data is JSON of the type its event name has below. state: a model stage loading, held, falling back or failing (the thread's model); retrieval: what the knowledge bases found for the user message, before the model answers; delta: a piece of the answer; reasoning: a piece of the model's reasoning; tool: a tool call of the turn, by its event (start, args, ready, approval, result); usage: the token counts so far; stop: why the model stopped; stats: a local model's timings; error: a failure, the stream goes on to done — one per MCP label the thread or its folder attached that offers the turn no tools, with its server_label and a code (tool_unreachable: a paired device's tools the caller is not granted, or a server its tool scope keeps out; tool_offline; tool_disabled; tool_unknown; tool_failed), the turn going on without it, as a plain chat turn when every such label is an offline or ungranted device's; done: the end, naming the reply it saved and its token counts, and pending_approvals when it stopped on calls that wait for a decision. A turn that is refused before it says anything streams error and done {aborted: true}. A client that closes the stream stops the turn; the partial reply is saved.

Parameters

NameInDescription
idrequiredpath integer

Request body required

application/json: object

attachments array of integer (int64) Draft attachment ids this message binds, in the order the files are
read in; a repeated id counts once.
contentrequired string The message's text; may be empty when attachments is not (a message
can be just a file).
kb_refs array of integer (int64) Knowledge bases picked for this message alone, on top of the thread's
own.
origin string | null Where the user writes from, in one sentence the client words (a
browser sidebar: "Typed in Kai's sidebar in Firefox, beside the tab
“Example” (https://example.org/)."). Stored on the user message and
put before its text in the model's input on every turn, marked as
what the client says rather than the user's words; the thread reads
it back as the message's origin. Absent, or blank: the message
says nothing of where it was written.
speak boolean Read the reply aloud as it streams: the stream then carries the
speech frames too.
voice DictatedVoice | null How a dictated message was dictated, stored on the user message.

Responses

StatusDescription
200 An event stream.
text/event-stream string
15 event types

delta TextFrame
delta (a piece of the answer) and reasoning (a piece of the model's
reasoning, kept apart from the answer).

textrequired string

done DoneFrame
done: the turn's last frame. aborted is true when the turn ended
early (refused, stopped, failed before it said anything); a turn that
saved nothing says only that, with no message_id.

abortedrequired boolean
answered_by string | null The alias that answered in its place (a fallback, a candidate
alias's pick), when one did.
completion_tokens integer | null
images_note string A fallback that cannot see answered and got the images as
placeholders: who, in a sentence. Only when it did.
message_id integer (int64) The reply the turn saved or appended to; 0 when it saved none.
model string The thread's model alias.
pending_approvals array of ApprovalRequest The calls the turn stopped on and waits for a decision about; only
when there are some.
prompt_tokens integer | null
reasoning_ignored array of string The thread's reasoning and sampling overrides this route did not send.
reasoning_note string | null The model reasoned although off was asked, in a sentence.
saved boolean Whether the reply is stored. false: its bubble is not a row, and no
action on it can work.
timings Timings | null The authoritative final timings of a local model; null for a cloud
upstream.
total_ms integer (int64)
ttfb_ms integer | null Milliseconds to the first byte of the upstream's answer.

error ErrorFrame
error: something went wrong; the stream goes on to done. code is
what a client branches on (gpu_hold, context_length_exceeded,
vram_queue_timeout, not_saved, superseded, ...); a failure that has
none sends only the message. A stream whose key was disabled, rotated,
deleted or expired, or whose gateway stops, ends with a last error
frame instead of done: revoked (with kind) or gateway_stopping.
An MCP label the thread or its folder attached that offers the turn no
tools gets one frame each, with server_label and a LabelCode
(tool_unreachable, tool_offline, tool_disabled, tool_unknown,
tool_failed), and the turn goes on without it.

code string
kind RevokeKind What a client does about a revoked frame, the token a realtime
session's 4003 close starts its reason with (key_unknown means pair
the device again). Sent with revoked only.
messagerequired string
server_label string The MCP label the frame is about, as the thread or folder attached
it; sent with a LabelCode only.

reasoning TextFrame
delta (a piece of the answer) and reasoning (a piece of the model's
reasoning, kept apart from the answer).

textrequired string

retrieval RetrievalFrame
retrieval: what the knowledge bases found for the user message, before
the model answers.

budget_tokensrequired integer (uint64) The budget the retrieval ran with.
droppedrequired integer (uint64) Excerpts that ranked but did not fit the budget.
excerptsrequired array of ContextExcerpt
kb_idsrequired array of integer (int64) The bases asked for: the thread's and the message's, as they were
then.
message_idrequired integer (int64) The user message the retrieval belongs to.
msrequired number (double) How long the retrieval took.
notesrequired array of string Why something was not searched, or not fully: one sentence each.
queryrequired string What was searched for.
reusedrequired boolean The message's stored retrieval was used again instead of searching.
searchedrequired array of string The bases that were searched, by name.
tokensrequired integer (uint64) Tokens the excerpts use, heading paths included.

speech SpeechFrame
speech: one clause as said, with its audio.

pcmrequired string The clause's audio, base64 of PCM16 little-endian, 24 kHz, mono.
seqrequired integer (uint64) Counts from 0.
textrequired string

speech_done SpeechDone
speech_done: the read-aloud ended, whole or stopped.

audio_msrequired integer (uint64) Length of the audio sent.
charsrequired integer (uint64) Characters spoken.
first_audio_msrequired integer | null From the request's start to the first speech frame; null when
nothing was spoken.
stoppedrequired boolean Stopped (POST .../speech/stop, or the reader went away) before the
text ended.
ttsrequired string
tts_answered_byrequired string | null

speech_error SpeechError
speech_error: the read-aloud cannot speak or failed; it ends the
speech. Codes: tts_not_configured, voice_not_found,
voice_not_configured, instructions_required, a device key's own
refusals, or the failure's kind.

coderequired string
messagerequired string

state ModelState
A voice stage's model state: a chat stream's state frame and a bound
realtime session's lmgw.model.state event.
Read leniently: a field a client does not know of is ignored, a missing
one is empty. Written as the gateway sends it: ms always, the other
optional facts only when the state has them.

aliasrequired string
answered_by string fallback: the alias that answers in its place.
capacity_bytes integer (uint64) skipped with does_not_fit: what the group could have together,
in bytes.
cause string held: gpu_hold or benchmark.
done_bytes integer (uint64) downloading: compressed bytes downloaded so far.
image string downloading: the image the model runs in, being downloaded before
its first start (machine-check design §5). A client says the
download in plain words; the reference is a detail.
message string The sentence a client shows.
msrequired integer | null How long the load took, for ready.
needed_bytes integer (uint64) skipped with does_not_fit: what the stage's group needs on the
card, in bytes.
reason string skipped: full, does_not_fit or cannot_speak.
size_note string downloading: why the size is not known, when it is not.
stagerequired string asr, chat or tts.
staterequired string loading, downloading, ready, held, fallback, skipped or
failed.
total_bytes integer (uint64) downloading: the download's whole size; absent while it is not
known.

stats Timings
Server-measured prefill and decode timings of a local model: the stats
frame (live per token while it streams) and the done frame's final
timings.

cache_n integer (uint64) Prompt tokens served from the KV cache.
draft_n integer (uint64) Draft tokens proposed (speculative or MTP decoding).
draft_n_accepted integer (uint64) Draft tokens accepted.
predicted_ms number (double) Milliseconds spent generating; absent when llama.cpp gave no finite number.
predicted_nrequired integer (uint64) Tokens generated so far.
predicted_per_second number (double) Tokens generated per second; absent when llama.cpp gave no finite number.
prompt_ms number (double) Milliseconds spent on the prompt; absent when llama.cpp gave no finite number.
prompt_nrequired integer (uint64) Prompt tokens actually processed this turn (the cache excluded).
prompt_per_second number (double) Prompt tokens processed per second; absent when llama.cpp gave no finite number.

stop StopFrame
stop: why the model stopped, in OpenAI's words (stop, length,
tool_calls, ...).

reasonrequired string

tool ToolFrame
tool: a tool call of the turn, told apart by event. start and
args while the model writes the call; ready when its arguments are
complete (a call that waits for an approval says needs_approval);
approval for a call that waits for a decision
(POST /chat/api/threads/{id}/approvals); result when it has run. A
result's task says which MCP task a call started: its output is then
started, job <task_id>, and the result enters the thread later.
progress while an image or audio tool runs: its stage, step and latest
preview (ToolProgressFrame), lossy and not in the change feed; a
result's attachments are the files the call stored in the thread.

One of 6 shapes
ToolStartFrame
Fields of ToolStartFrame
id string The model's id of the call; only a turn without tools says it.
indexrequired integer (uint) The call's position in its turn.
namerequired string The tool's exposed name.
ToolArgsFrame
Fields of ToolArgsFrame
fragmentrequired string
indexrequired integer (uint)
ToolReadyFrame
Fields of ToolReadyFrame
argumentsrequired any The call's arguments.
call_idrequired string | null The call's id, as its result frame carries it.
indexrequired integer (uint) The call's position in its turn.
namerequired string The tool's exposed name, as the model called it.
needs_approvalrequired boolean | null The call waits for an approval and does not run now: an approval
frame follows. false for a call that runs (a resumed turn's decided
calls included). Absent from an lmgw before 2026-10-09.
server_labelrequired string | null The label the tool came from; null for a client's own function.
ui_resourcerequired string | null The UI resource the tool links to, as on the result frame.
ApprovalRequest
Fields of ApprovalRequest
approval_request_idrequired string The id a decision quotes (mcpr_…), unique in the gateway.
argumentsrequired string The arguments as the model wrote them: a JSON string.
call_id string The call's id, as its ready and result frames carry it
(mcp_apps::ToolReadyFrame::call_id). Absent from an lmgw
before 2026-10-09, and from an ApprovalRequest read off a bound
session's mcp_approval_request item (OpenAI's shape has none):
there the lmgw.chat.frame relaying the approval frame has it.
namerequired string The tool's own name: the name the model called, without its
label's <prefix>__.
server_labelrequired string The thread's label the tool came from.
ToolResultFrame
Fields of ToolResultFrame
attachments array of AttachmentMeta The files the call stored in the thread — an image or audio tool's
pictures and recordings in a Chat turn — so a page shows them
without reading the thread again. Their bytes are at
GET /chat/api/attachments/{id}; content names them as
lmgw:attachment/N resources. Empty for every other call.
call_idrequired string | null The call's id, as its ready frame carries it.
contentrequired array | null The MCP result's content blocks as the server sent them (resource
URIs namespaced as /mcp sends them; images in full — no bound of
lmgw's own, a device's result is bounded by mcp.host_max_message_mb
on its link); a tool lmgw runs itself, or a call that never reached
a server, says its result in the same shape. Absent from an lmgw
before 2026-10-09: output as one text block then.
indexrequired integer (uint) The call's position in its turn.
is_errorrequired boolean
msrequired integer (uint64)
namerequired string The tool's exposed name (<prefix>__<tool>).
outputrequired string The result as text.
server_labelrequired string | null The label the tool came from: a server's tool prefix (else its
name), or a built-in toolset's (lmgw, docs, kb).
structured_contentrequired any The MCP result's structuredContent, for the view. The model was
given it only when content is empty.
task ResultTask For a call that started an MCP task: which. Absent otherwise.
ui_resourcerequired string | null The UI resource the tool links to (_meta.ui.resourceUri),
namespaced as /mcp serves it: resources/read it there.
ToolProgressFrame
Fields of ToolProgressFrame
call_idrequired string The call's id, as its ready frame carries it.
cancel CancelKind What a cancel would do now, while an image job runs; absent before
the job exists (a cancel then just stops the wait) and for audio.
done_bytes integer (uint64) downloading: compressed bytes downloaded so far.
elapsed_msrequired integer (uint64) Since the call started.
free_bytes integer (uint64) waiting_for_room: the memory free when it was last measured.
image string downloading: the image reference being downloaded.
model string The model the phase is about: the one being unloaded for
unloading, the call's own otherwise.
needs_bytes integer (uint64) waiting_for_room: the memory the model needs, headroom included.
pass integer (uint32) The sampling pass (a batch item, a high- or low-noise stage, a hires
pass); a new pass starts its steps again.
phaserequired MediaPhase | null
preview string The latest preview as the image server drew it: base64, PNG. Its
pixel size depends on the row's preview mode (a quick sketch is the
latent's size, an eighth of the picture's side on the spike's
pipeline).
queue_position integer (uint32) queued: the job's place in the image server's queue.
size_note string downloading: why the size is not known, when it is not ("size not
known — …").
step integer (uint32)
total_bytes integer (uint64) downloading: the download's whole size; absent when it is not
known.
total_steps integer (uint32)

turn TurnStarted
turn: the first frame of a turn that wrote a user message (a send, an
edit of a user message).

user_message_idrequired integer (int64) The user message the answer follows.

usage UsageFrame
usage: the tokens the model reported for the turn so far.

completion_tokensrequired integer | null
prompt_tokensrequired integer | null

voice VoiceFrame
voice (speech): the read-aloud's route is open.

ttsrequired string The text-to-speech alias.
tts_answered_byrequired string | null The alias that answers in the TTS alias's place (a fallback).
voicerequired string | null The voice every clause is sent with.
default Error.
application/json ApiError
post/chat/api/threads/{id}/settings

Change a thread's settings

Capability chat, open to: device, owner. Changes state.

A patch: a field left out stays as it is, and for the settings that can be unset, null clears it back to the route's default. Settings that contradict each other (the reasoning and sampling overrides, the knowledge settings, a voice alias that cannot do what it is for) are a 400 bad_request and nothing is written; an unknown profile_id is a 400 unknown_profile. The answer re-judges continue under the new settings, and carries the voice as stored and what it resolves to now. A device key's mcp_tools and knowledge bases pass its tool scope first (403 tool_label_out_of_scope), its model and voice aliases its alias scope (403 key_scope); a device below full admin level changes no setting of a thread with lmgw's admin tools (403 chat_toolset_needs_full). A thread that is gone is a 404 not_found.

Parameters

NameInDescription
idrequiredpath integer

Request body required

application/json: object

frequency_penalty number | null
kb_budget_tokens integer | null The retrieval budget of auto mode in tokens; null takes the
Chat's setting.
kb_ids array | null The thread's knowledge bases, as a whole selection ([] clears it).
kb_mode string | null auto or tool: how the bases reach the model.
max_tokens integer | null
mcp_tools array | null The tool servers the thread uses, as a whole list ([] detaches
all). A device key's labels pass its tool scope first.
media_defaults MediaDefaults | null The image and audio tools' default models, as a whole object ({}
inherits everything): a field names a model of the tool's model
enum ("" for none), or the voice. A name the tool cannot use for
this caller is a 400 bad_request; one the thread already holds
passes, so a model switched off since does not block other changes.
min_p number | null
model_alias string | null The alias the thread's turns go to.
presence_penalty number | null
profile_id integer | null The personality profile, an id from GET /chat/api/profiles; null
for none. An unknown id is a 400 unknown_profile.
reasoning_budget integer | null
reasoning_effort string | null
reasoning_enabled boolean | null Reasoning overrides sent with every turn; null clears one.
repeat_penalty number | null
seed integer | null
stop array | null The whole list of stop sequences; [] clears it.
system_prompt string | null
temperature number | null Sampling overrides sent with every turn: a number sets one, null
clears it.
top_k integer | null
top_p number | null
voice ThreadVoice | null The thread's voice overrides as a whole object; null clears them.
An unknown key or value is a 400 bad_request.

Responses

StatusDescription
200 OK.
application/json SettingsAck
Fields of SettingsAck
continuerequired ContinueState Whether the last reply can be continued under the new settings (a
model switch or a reasoning toggle changes it).
okrequired boolean Always true.
voicerequired ThreadVoice The thread's own voice settings as stored now.
voice_resolvedrequired VoiceResolved What the voice resolves to now, as voice_resolved of
GET /chat/api/threads/{id}: asr and tts (alias, whether it runs
on this machine, what answers for it while the GPU is held), voice,
speech_style, language, reply_language, language_notes,
read_aloud, turn_detection, audio_input, seed, the problems
that block a voice feature now, and realtime.
default Error.
application/json ApiError
post/chat/api/threads/{id}/speech/stop

Stop a thread's read-aloud

Capability chat, open to: device, owner. Changes state.

Stops the thread's running read-alouds (a message spoken on request, or a reply read aloud as it streams); stopped counts them, 0 when nothing was playing. A thread the caller cannot reach is a 404 not_found.

Parameters

NameInDescription
idrequiredpath integer

Responses

StatusDescription
200 OK.
application/json SpeechStopped
Fields of SpeechStopped
okrequired boolean Always true.
stoppedrequired integer (uint64) How many read-alouds of the thread were running and are stopped; 0
when none ran.
default Error.
application/json ApiError
get/chat/api/threads/{id}/tasks

List a thread's jobs

Capability chat, open to: device, owner

The thread's MCP tasks still running or waiting to enter it, oldest first, as GET /chat/api/threads/{id} lists them as tasks (ThreadTask), without the history: the Chat page's strip re-reads them at mcp.task_poll_interval_s. A thread the caller does not reach is 404 not_found, as everywhere in Chat; a temporary thread has none (an empty list).

Parameters

NameInDescription
idrequiredpath integer

Responses

StatusDescription
200 OK.
application/json array of ThreadTask
Fields of ThreadTask
byrequired string | null Who started it ("the dashboard", "device 'phone'").
idrequired integer (int64) lmgw's id of the task: the cancel route's {task}.
server_labelrequired string
started_atrequired string When it started (UTC, YYYY-MM-DD HH:MM:SS).
statusrequired string working or input_required while it runs; completed, failed,
cancelled or abandoned once it ended. One of working, input_required, completed, failed, cancelled, abandoned.
status_messagerequired string | null The server's last word on it, when it gave one.
task_idrequired string The server's id of the task.
toolrequired string The name the model called.
ttl_msrequired integer | null How long the server keeps it, as it stated; null when it stated
none.
waiting_forrequired string | null What it waits for, when it waits: a device that is not connected
(its tasks are asked about again when it links), a turn of the
thread that runs (a result enters the thread once it ended), or the
decision on the calls the thread's last reply waits on.
default Error.
application/json ApiError
post/chat/api/threads/{id}/tasks/{task}/cancel

Cancel a thread's job

Capability chat, open to: device, owner. Changes state.

Cancels task {task} (ThreadTask.id, the feed's task.started id) of the thread: lmgw sends tasks/cancel. The answer is the task as the cancel left it, whether its result is in the thread now, and what happened: the server cancelled it (its result says cancelled by <who>), it finished before the cancel (its real result), or the server was not connected (it ends cancelled at once and the server is told when it connects), or the server was asked and has not ended it yet (it is followed until it says it ended). The body is ignored. A thread the caller does not reach is 404 not_found; a task of another thread, or one whose result entered the thread already (it is gone then), 404 task_not_found; one that ended and whose result waits to enter the thread 409 task_ended; a server that does not declare tasks.cancel 409 task_cancel_unsupported, one that answers the cancel with an error 502 task_cancel_refused — the task goes on in both. Deleting the thread cancels its running tasks too.

Parameters

NameInDescription
idrequiredpath integer
taskrequiredpath integer

Responses

StatusDescription
200 OK.
application/json TaskCancelled
Fields of TaskCancelled
deliveredrequired boolean Its result is in the thread now (a message of role tool); false
while it waits for a turn that runs, or while the server has not
ended the task yet.
noterequired string What happened, in a sentence.
taskrequired ThreadTask The task as the cancel left it.
default Error.
application/json ApiError
post/chat/api/threads/{id}/title

Rename a thread

Capability chat, open to: device, owner. Changes state.

Sets the thread's title, trimmed, and answers the thread as the list carries it. The change reaches every client as a thread.updated event. A thread named this way keeps its title: the first send names only a thread still called "New chat". An empty title is a 400 bad_request. A temporary thread has no stored title to set until it is kept: 409 temporary_thread. A thread the caller cannot reach is a 404 not_found.

Parameters

NameInDescription
idrequiredpath integer

Request body required

application/json: object

titlerequired string The new title. Trimmed; empty after that is a 400. A thread named
this way is never named again by its first send.

Responses

StatusDescription
200 OK.
application/json Thread
Fields of Thread
agent_idrequired string | null The agent the thread was opened from, if any.
archived_atrequired string | null When the thread was archived; null while it is active.
continue ContinueState Whether the last reply can be continued. Present where the thread
is read whole, as POST /chat/api/folders/{id}/current answers it.
created_atrequired string
folder_idrequired integer | null The folder the thread is in; null for none.
frequency_penaltyrequired number | null
idrequired integer (int64) Negative for a temporary thread.
kb_budget_tokensrequired integer | null The retrieval budget of auto mode in tokens; null for the Chat's
setting.
kb_idsrequired array of integer (int64) Knowledge bases the thread searches, by id.
kb_moderequired KbMode
kindrequired string chat, or admin for a thread that drives the gateway's own
configuration (never listed for a device key).
last_message_atrequired integer | null When its newest message was written, in unix seconds; null for a
thread without messages. An ongoing folder's idle rollover is
measured from it: a client that shows when the conversation moves
on reads it here rather than timing the turns it saw.
max_tokensrequired integer | null
mcp_toolsrequired array of ThreadMcp The tool servers the thread's turns use; empty for a plain chat. A
thread with lmgw (the self-admin toolset) among them is listed for a
device key only when the device may use lmgw's admin tools.
media_defaultsrequired MediaDefaults The thread's own default models of the image and audio tools; an
absent field inherits its folder's, then Settings → Chat's, and an
empty one is no default (GET /chat/api/media/defaults says what
they resolve to).
min_prequired number | null
model_aliasrequired string The alias the thread's turns go to.
pinnedrequired boolean Pinned threads are listed first and are never archived or deleted
by the sweep.
presence_penaltyrequired number | null
profile_idrequired integer | null The personality profile the thread talks with
(GET /chat/api/profiles); null for none ("Default").
purge_atrequired string | null When an archived thread will be deleted; null while it is active,
pinned, or when deleting is switched off.
reasoning_budgetrequired integer | null
reasoning_effortrequired string | null
reasoning_enabledrequired boolean | null Reasoning overrides sent with every turn; null leaves the route's
default.
repeat_penaltyrequired number | null
seedrequired integer | null
stoprequired array of string Stop sequences; empty leaves the route's default.
system_promptrequired string
temperaturerequired number | null Sampling overrides sent with every turn; null leaves the route's
default.
temporaryrequired boolean The thread lives in memory only and is gone at the gateway's next
start unless it is kept.
titlerequired string
top_krequired integer | null
top_prequired number | null
updated_atrequired string Moves with every change to the thread and every new message.
voicerequired ThreadVoice
voice_resolvedrequired VoiceResolved What the thread's voice resolves to now, field by field with the
level each value comes from (the thread, the Chat's settings, the
realtime settings): the speech-to-text and text-to-speech stages
(asr, tts: alias, whether it runs on this machine, what answers
for it while the GPU is held), voice, speech_style, language,
reply_language, read_aloud, turn_detection, audio_input,
seed, the problems that block a voice feature now, and
realtime: whether voice mode can bind the thread.
default Error.
application/json ApiError
post/chat/api/threads/{id}/transcribe

Transcribe a recording

Capability chat, open to: device, owner. Changes state.

The body is a recording, its container named by Content-Type: audio/wav (also audio/wave, audio/x-wav, audio/vnd.wave, none, application/octet-stream), audio/webm, audio/ogg (audio/opus), audio/mpeg (audio/mp3), audio/mp4 (audio/m4a, audio/x-m4a) or audio/flac (audio/x-flac); another is 415 unsupported_media_type. It is transcribed by the thread's speech-to-text model and written nowhere: dictation, and a spoken answer to an approval, which must stay out of the conversation (a new message declines a waiting call). The answer names the alias, the one that answered in its place (a GPU-hold or outside-VRAM fallback, also in x-lmgw-fallback), the call's time, the recording's length (WAV only) and the language heard. The body is bounded by max_body_mb (413 body_limit naming it). 400 empty_audio, 422 asr_not_configured, 503 gpu_hold, and a device key's own refusals. A failure of the transcription itself names the fallback that had the audio in x-lmgw-fallback: the audio may have left this machine although nothing came back.

Parameters

NameInDescription
idrequiredpath integer

Request body required

audio/wav: string (binary)

Responses

StatusDescription
200 OK.
application/json Dictation
Fields of Dictation
aliasrequired string The speech-to-text alias the thread resolves to.
asr_answered_byrequired string | null The alias that answered in its place (a GPU-hold or outside-VRAM
fallback); null when it answered itself.
asr_msrequired integer (uint64) The transcription call, admission included.
audio_msrequired integer | null The recording's length, from its WAV header; null for any other
container.
languagerequired string | null What the model says it heard, in its own spelling, else the language
the thread's user speaks; null when neither is known.
textrequired string

Headers: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
default Error.
application/json ApiError

Headers: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
post/chat/api/threads/{id}/voice/warm

Warm a thread's speech models

Capability chat, open to: device, owner. Changes state.

A press of the microphone (or the start of a call) warms the models the voice turn will use before the request it announces. stages names them (asr, tts, chat: the thread's own model), each once; they are the thread's resolved aliases, warmed as one group through the request admission, so the warm may evict idle models exactly as the request would, and a group that does not fit together is warmed without evicting. The stream sends one state frame per change of each stage (loading, then ready with the time it took, or held, fallback, skipped, failed), then done with no fields once every stage has settled. A device or owner key that is disabled, rotated, deleted or expired while it streams, and a gateway that stops, end the stream with an error frame (code revoked, with kind, or gateway_stopping) instead of done. Closing the stream drops what still waits for admission; a container start already in flight finishes. Refused before anything is warmed: 404 not_found, 400 bad_request (no stages, or an unknown name), 422 asr_not_configured or tts_not_configured (no alias for the stage at any level), and, for a device key, its own refusal (scope, budget) for a stage whose alias it may not use — nothing starts then.

Parameters

NameInDescription
idrequiredpath integer

Request body required

application/json: object

stagesrequired array of string The stages to warm, each named once and in this order: asr, tts
and chat (the thread's own model). Empty or an unknown name is
400 bad_request.

Responses

StatusDescription
200 An event stream.
text/event-stream string
3 event types

done WarmDone
done of a voice warm-up: every stage has settled. No fields.

error ErrorFrame
error: something went wrong; the stream goes on to done. code is
what a client branches on (gpu_hold, context_length_exceeded,
vram_queue_timeout, not_saved, superseded, ...); a failure that has
none sends only the message. A stream whose key was disabled, rotated,
deleted or expired, or whose gateway stops, ends with a last error
frame instead of done: revoked (with kind) or gateway_stopping.
An MCP label the thread or its folder attached that offers the turn no
tools gets one frame each, with server_label and a LabelCode
(tool_unreachable, tool_offline, tool_disabled, tool_unknown,
tool_failed), and the turn goes on without it.

code string
kind RevokeKind What a client does about a revoked frame, the token a realtime
session's 4003 close starts its reason with (key_unknown means pair
the device again). Sent with revoked only.
messagerequired string
server_label string The MCP label the frame is about, as the thread or folder attached
it; sent with a LabelCode only.

state ModelState
A voice stage's model state: a chat stream's state frame and a bound
realtime session's lmgw.model.state event.
Read leniently: a field a client does not know of is ignored, a missing
one is empty. Written as the gateway sends it: ms always, the other
optional facts only when the state has them.

aliasrequired string
answered_by string fallback: the alias that answers in its place.
capacity_bytes integer (uint64) skipped with does_not_fit: what the group could have together,
in bytes.
cause string held: gpu_hold or benchmark.
done_bytes integer (uint64) downloading: compressed bytes downloaded so far.
image string downloading: the image the model runs in, being downloaded before
its first start (machine-check design §5). A client says the
download in plain words; the reference is a detail.
message string The sentence a client shows.
msrequired integer | null How long the load took, for ready.
needed_bytes integer (uint64) skipped with does_not_fit: what the stage's group needs on the
card, in bytes.
reason string skipped: full, does_not_fit or cannot_speak.
size_note string downloading: why the size is not known, when it is not.
stagerequired string asr, chat or tts.
staterequired string loading, downloading, ready, held, fallback, skipped or
failed.
total_bytes integer (uint64) downloading: the download's whole size; absent while it is not
known.
default Error.
application/json ApiError
get/chat/api/tools

List the toolsets a thread may attach

Capability chat, open to: device, owner

For a thread's tool picker: lmgw's built-in toolsets first (lmgw, docs, kb, image, audio, in that order), each with its tools, then the registered MCP servers and service agents by label, each with its connection's status and how many of its tools, as last listed, the caller may tick. Connects nothing; GET /chat/api/tools/{label} lists a server's tools. Under the caller's tool scope: the owner is listed every built-in toolset, one that offers nothing now with the reason (status unavailable), and every enabled server; a device key is listed what GET /v1/mcp/servers lists it — the toolsets that offer it tools and the enabled servers its scope reaches — and the self-admin toolset (lmgw) only while its admin tools are at full, since below that a device uses the threads that carry it and attaches it to none. A tool the owner switched off is never listed or counted.

Responses

StatusDescription
200 OK.
application/json ChatToolList
Fields of ChatToolList
sourcesrequired array of ChatToolSource
default Error.
application/json ApiError
get/chat/api/tools/{label}

List one toolset's tools

Capability chat, open to: device, owner

The tools a thread attaching label alone gets, under their exposed names (the spelling a thread's allowed_tools and require_approval store), the owner's switched-off tools and those outside the caller's tool scope left out — the same resolution a turn runs. Connects that one server when it is not up, but starts no service agent: one whose app is not running is a 502 mcp_list_tools_failed saying so, and a turn that attaches it starts it. A label the caller may not attach (unknown, disabled, outside its scope, or lmgw for a device below full) is a 404 not_found in the resolver's words; a server that cannot be listed a 502 mcp_list_tools_failed.

Parameters

NameInDescription
labelrequiredpath string

Responses

StatusDescription
200 OK.
application/json ChatToolDetail
Fields of ChatToolDetail
server_labelrequired string
toolsrequired array of ChatTool
default Error.
application/json ApiError

Transfers

Files between paired devices of one app (device transfers design): a device offers a file to another device that declared the same app id at pairing, uploads it to lmgw in ranges it can resume, and the other device is offered it once every byte matched its sha256, downloads it with ranges and says it arrived; lmgw then deletes the bytes. The transfer capability: paired devices (on the device listener) send and receive; the owner lists every transfer and cancels any; a client key or an agent token is refused 403 transfer_device_only. A refusal is the flat {code, message}, with free_bytes, received or state where its code names one. JSON bodies are at most 16 KiB (16384 bytes), refused 413 body_too_large; the only bound on a file is the free space of lmgw's data directory. The Chat feed's transfer.updated says each offer, ready and end to the sender, to the receiver from ready on, and to the owner.

get/transfers/api/targets

Who this device can offer a file to

Capability transfer, open to: device, owner

A device's: its other devices that declared app_id at pairing and can receive now (enabled, confirmed, not past their key's expiry), never itself, each with whether it holds its Chat feed open (online) and when it was last seen; with free_bytes, the largest offer lmgw takes now (the free space of its data directory less what uploads in progress still need, the only size bound), and expiry_days, how long an offer made now lasts (devices.transfer_expiry_days). 400 bad_request for an app_id that is no lowercase reverse-DNS name; 403 transfer_device_only for the owner.

Parameters

NameInDescription
app_idrequiredquery string

Responses

StatusDescription
200 OK.
application/json Targets
Fields of Targets
expiry_daysrequired integer (uint32) Days an offer made now lasts (devices.transfer_expiry_days).
free_bytesrequired integer (uint64) The largest offer lmgw takes now, in bytes: the data directory's
free space less what the uploads in progress still need. The only
size bound there is.
targetsrequired array of Target The caller's other devices that declared the app id and can receive
now (enabled, confirmed, not expired); never the caller.
default Error.
application/json ApiError
get/transfers/api/transfers

List transfers

Capability transfer, open to: device, owner

Newest first, the ended ones included for chat_feed_retention_days after they ended. A device lists its outgoing ones (role=outgoing), the incoming ones it was offered (role=incoming, from ready on), or both; the owner every one, without role (400 bad_request with one). A receiver lists its pending offers at its start and follows the Chat feed's transfer.updated for the rest. stored_bytes is what the files of transfers in progress hold, free_bytes the largest offer lmgw takes now.

Parameters

NameInDescription
rolequery TransferRole | null

Responses

StatusDescription
200 OK.
application/json TransferList
Fields of TransferList
free_bytesrequired integer (uint64) The largest offer lmgw takes now (Targets::free_bytes).
stored_bytesrequired integer (uint64) Bytes the files of the transfers in progress hold on disk now.
transfersrequired array of Transfer Newest first, the ended ones included for as long as
chat_feed_retention_days keeps them.
default Error.
application/json ApiError
post/transfers/api/transfers

Offer a file to another device

Capability transfer, open to: device, owner. Changes state.

A device offers a file to to_device, a target for app_id: 201 Created with the transfer, uploading and nothing received; upload its bytes next. The receiver does not see it until every byte is there and matched sha256. It lasts devices.transfer_expiry_days (expires_at). 400 bad_request for a malformed field (kind required, filename without '/', '\' or control characters, size at least 1, sha256 64 lowercase hex digits), 403 transfer_device_only for the owner, 413 body_too_large over 16 KiB, 422 transfer_target_invalid when to_device is no target for app_id (the message says which part failed), 507 transfer_storage_full with free_bytes when size is above the space left for new offers. A sender disabled or deleted while its offer was read is answered as the device listener answers its next request: 401 device_disabled or 401 device_key_unknown.

Request body required

application/json: object

app_idrequired string The app id the receiver declared (APP_ID_RULE).
filenamerequired string The receiver's name for the file: no /, \, control or invisible
characters, not . or ...
kindrequired string The app's own word for what the file is (required; no control or
invisible characters).
sha256required string The file's sha256: 64 lowercase hex digits.
sizerequired integer (uint64) The file's size in bytes: at least 1, at most free_bytes.
title string What the card and the receiver show (may be empty). Default "".
to_devicerequired integer (int64) The receiver: a target's device_id for app_id.

Responses

StatusDescription
201 OK.
application/json Transfer
Fields of Transfer
app_idrequired string The app id the offer names; the receiver declared it at pairing.
created_atrequired string RFC 3339 UTC.
end_reasonrequired string | null Why it ended, a sentence for people ("not delivered within 7 days of
the offer", "canceled by device 'phone'"), naming no setting and no
raw time; null while in progress and once delivered. state is
what a client acts on.
ended_atrequired string | null When it ended (RFC 3339 UTC); null while in progress.
expires_atrequired string When it expires unless delivered first (RFC 3339 UTC):
devices.transfer_expiry_days after the offer.
filenamerequired string The receiver's name for the file.
fromrequired TransferParty
idrequired string Opaque: 32 random lowercase hex digits.
kindrequired string The app's own word for what the file is.
receivedrequired integer (uint64) Bytes lmgw holds: the resume point while uploading (the next
upload's range starts here), size from ready on, and how far it
got for one that ended before.
sha256required string The file's sha256, 64 lowercase hex digits; checked when the last
byte arrives.
sizerequired integer (uint64) The file's size in bytes.
staterequired TransferState
titlerequired string What the card and the receiver show; may be empty.
torequired TransferParty
409 Error, with this body rather than the default one.
application/json TransferRefusal
Fields of TransferRefusal
coderequired string
free_bytes integer (uint64) code::TRANSFER_STORAGE_FULL's: the space left for new offers.
messagerequired string
received integer (uint64) code::TRANSFER_OFFSET's: the resume point.
state TransferState code::TRANSFER_STATE's: the state the transfer is in.
507 Error, with this body rather than the default one.
application/json TransferRefusal
Fields of TransferRefusal
coderequired string
free_bytes integer (uint64) code::TRANSFER_STORAGE_FULL's: the space left for new offers.
messagerequired string
received integer (uint64) code::TRANSFER_OFFSET's: the resume point.
state TransferState code::TRANSFER_STATE's: the state the transfer is in.
default Error.
application/json ApiError
get/transfers/api/transfers/{id}

Read a transfer

Capability transfer, open to: device, owner

The transfer as it is now: while it uploads, received is the resume point (the bytes lmgw holds, which the next upload's range starts at). 404 transfer_not_found for no such transfer and for a device that is neither its sender nor its receiver (a receiver lists it and hears of it from ready on, and reads it by id from the offer on).

Parameters

NameInDescription
idrequiredpath string

Responses

StatusDescription
200 OK.
application/json Transfer
Fields of Transfer
app_idrequired string The app id the offer names; the receiver declared it at pairing.
created_atrequired string RFC 3339 UTC.
end_reasonrequired string | null Why it ended, a sentence for people ("not delivered within 7 days of
the offer", "canceled by device 'phone'"), naming no setting and no
raw time; null while in progress and once delivered. state is
what a client acts on.
ended_atrequired string | null When it ended (RFC 3339 UTC); null while in progress.
expires_atrequired string When it expires unless delivered first (RFC 3339 UTC):
devices.transfer_expiry_days after the offer.
filenamerequired string The receiver's name for the file.
fromrequired TransferParty
idrequired string Opaque: 32 random lowercase hex digits.
kindrequired string The app's own word for what the file is.
receivedrequired integer (uint64) Bytes lmgw holds: the resume point while uploading (the next
upload's range starts here), size from ready on, and how far it
got for one that ended before.
sha256required string The file's sha256, 64 lowercase hex digits; checked when the last
byte arrives.
sizerequired integer (uint64) The file's size in bytes.
staterequired TransferState
titlerequired string What the card and the receiver show; may be empty.
torequired TransferParty
default Error.
application/json ApiError
post/transfers/api/transfers/{id}/cancel

Cancel a transfer

Capability transfer, open to: device, owner. Changes state.

The sender's and the owner's, while the transfer is uploading or ready: it is canceled, an upload in progress stops (answered 409 transfer_state, canceled), a download in progress breaks off, lmgw deletes its bytes, and both devices hear it on the feed. 404 transfer_not_found for any other device; 409 transfer_state with state once it ended.

Parameters

NameInDescription
idrequiredpath string

Responses

StatusDescription
200 OK.
application/json Transfer
Fields of Transfer
app_idrequired string The app id the offer names; the receiver declared it at pairing.
created_atrequired string RFC 3339 UTC.
end_reasonrequired string | null Why it ended, a sentence for people ("not delivered within 7 days of
the offer", "canceled by device 'phone'"), naming no setting and no
raw time; null while in progress and once delivered. state is
what a client acts on.
ended_atrequired string | null When it ended (RFC 3339 UTC); null while in progress.
expires_atrequired string When it expires unless delivered first (RFC 3339 UTC):
devices.transfer_expiry_days after the offer.
filenamerequired string The receiver's name for the file.
fromrequired TransferParty
idrequired string Opaque: 32 random lowercase hex digits.
kindrequired string The app's own word for what the file is.
receivedrequired integer (uint64) Bytes lmgw holds: the resume point while uploading (the next
upload's range starts here), size from ready on, and how far it
got for one that ended before.
sha256required string The file's sha256, 64 lowercase hex digits; checked when the last
byte arrives.
sizerequired integer (uint64) The file's size in bytes.
staterequired TransferState
titlerequired string What the card and the receiver show; may be empty.
torequired TransferParty
default Error.
application/json ApiError
get/transfers/api/transfers/{id}/content

Download a transfer's bytes

Capability transfer, open to: device, owner

The receiver's, while the transfer is ready: the file, streamed from lmgw's disk, with Accept-Ranges: bytes, ETag "sha256:<hex>" and Content-Disposition naming its filename. One Range (bytes=a-b, bytes=a- or bytes=-n) answers 206 with Content-Range; If-Range with the ETag serves the range, with anything else the whole file. A Range lmgw does not read (another unit, several ranges, an invalid one) is ignored: the whole file, 200. 416 range_not_satisfiable, with Content-Range: bytes */size, for a range that names no byte of the file (it starts at or past the end, or asks the last 0 bytes). 404 transfer_not_found but for the receiver; 409 transfer_state with state when it is not ready. A transfer that ends while its bytes stream (a cancel, an expiry, a device's end) breaks the body off short of its length. HEAD answers the same head without the body. After its own hash check the receiver sends …/received.

Parameters

NameInDescription
idrequiredpath string

Responses

StatusDescription
200 OK.
application/octet-stream string (binary)
409 Error, with this body rather than the default one.
application/json TransferRefusal
Fields of TransferRefusal
coderequired string
free_bytes integer (uint64) code::TRANSFER_STORAGE_FULL's: the space left for new offers.
messagerequired string
received integer (uint64) code::TRANSFER_OFFSET's: the resume point.
state TransferState code::TRANSFER_STATE's: the state the transfer is in.
507 Error, with this body rather than the default one.
application/json TransferRefusal
Fields of TransferRefusal
coderequired string
free_bytes integer (uint64) code::TRANSFER_STORAGE_FULL's: the space left for new offers.
messagerequired string
received integer (uint64) code::TRANSFER_OFFSET's: the resume point.
state TransferState code::TRANSFER_STATE's: the state the transfer is in.
default Error.
application/json ApiError
put/transfers/api/transfers/{id}/content

Upload a transfer's bytes

Capability transfer, open to: device, owner. Changes state.

The sender's, while the transfer is uploading. Content-Range: bytes a-b/size is required, size the offer's and a the transfer's received; the body is the range's raw bytes (any Content-Type), streamed to lmgw's disk. Chunks are any size; a body that breaks off keeps every byte that arrived, so received (read the transfer) is where to go on. A newer upload of the same transfer stops one still being read. Answers {received, state}; the last byte has the file's sha256 checked: state ready (offered to the receiver), or 422 transfer_hash_mismatch, the transfer failed and its bytes deleted. When lmgw already holds every byte (the last range's answer was lost), any upload of it completes it the same, whatever range it names; Content-Range: bytes */size with no body is the form that asks only that: where the upload stands, and its completion when it is whole. 400 bad_request for a missing or malformed Content-Range, another total, a Content-Length that is not b-a+1, or a body shorter or longer than its range when that was not the last byte (what arrived of the range is kept); 404 transfer_not_found but for the sender; 409 transfer_offset with received when a is not it (or a newer upload stopped this one); 409 transfer_state with state once it is not uploading, also for an upload a cancel, an expiry or a device's end stopped (ready: it is done); 507 transfer_storage_full with free_bytes when the disk filled.

Parameters

NameInDescription
idrequiredpath string

Request body required

application/octet-stream: string (binary)

Responses

StatusDescription
200 OK.
application/json ContentReceived
Fields of ContentReceived
receivedrequired integer (uint64) Bytes lmgw holds now: where the next range starts.
staterequired TransferState uploading, or ready once the last byte arrived and matched.
409 Error, with this body rather than the default one.
application/json TransferRefusal
Fields of TransferRefusal
coderequired string
free_bytes integer (uint64) code::TRANSFER_STORAGE_FULL's: the space left for new offers.
messagerequired string
received integer (uint64) code::TRANSFER_OFFSET's: the resume point.
state TransferState code::TRANSFER_STATE's: the state the transfer is in.
507 Error, with this body rather than the default one.
application/json TransferRefusal
Fields of TransferRefusal
coderequired string
free_bytes integer (uint64) code::TRANSFER_STORAGE_FULL's: the space left for new offers.
messagerequired string
received integer (uint64) code::TRANSFER_OFFSET's: the resume point.
state TransferState code::TRANSFER_STATE's: the state the transfer is in.
default Error.
application/json ApiError
post/transfers/api/transfers/{id}/decline

Decline a transfer

Capability transfer, open to: device, owner. Changes state.

The receiver's: the transfer is declined and lmgw deletes its bytes; the sender hears it on the feed. 404 transfer_not_found but for the receiver; 409 transfer_state with state when it is not ready.

Parameters

NameInDescription
idrequiredpath string

Responses

StatusDescription
200 OK.
application/json Transfer
Fields of Transfer
app_idrequired string The app id the offer names; the receiver declared it at pairing.
created_atrequired string RFC 3339 UTC.
end_reasonrequired string | null Why it ended, a sentence for people ("not delivered within 7 days of
the offer", "canceled by device 'phone'"), naming no setting and no
raw time; null while in progress and once delivered. state is
what a client acts on.
ended_atrequired string | null When it ended (RFC 3339 UTC); null while in progress.
expires_atrequired string When it expires unless delivered first (RFC 3339 UTC):
devices.transfer_expiry_days after the offer.
filenamerequired string The receiver's name for the file.
fromrequired TransferParty
idrequired string Opaque: 32 random lowercase hex digits.
kindrequired string The app's own word for what the file is.
receivedrequired integer (uint64) Bytes lmgw holds: the resume point while uploading (the next
upload's range starts here), size from ready on, and how far it
got for one that ended before.
sha256required string The file's sha256, 64 lowercase hex digits; checked when the last
byte arrives.
sizerequired integer (uint64) The file's size in bytes.
staterequired TransferState
titlerequired string What the card and the receiver show; may be empty.
torequired TransferParty
default Error.
application/json ApiError
post/transfers/api/transfers/{id}/received

Say a transfer arrived

Capability transfer, open to: device, owner. Changes state.

The receiver's, after its own check of the bytes: the transfer is delivered and lmgw deletes its bytes; the sender hears it on the feed. 404 transfer_not_found but for the receiver; 409 transfer_state with state when it is not ready.

Parameters

NameInDescription
idrequiredpath string

Responses

StatusDescription
200 OK.
application/json Transfer
Fields of Transfer
app_idrequired string The app id the offer names; the receiver declared it at pairing.
created_atrequired string RFC 3339 UTC.
end_reasonrequired string | null Why it ended, a sentence for people ("not delivered within 7 days of
the offer", "canceled by device 'phone'"), naming no setting and no
raw time; null while in progress and once delivered. state is
what a client acts on.
ended_atrequired string | null When it ended (RFC 3339 UTC); null while in progress.
expires_atrequired string When it expires unless delivered first (RFC 3339 UTC):
devices.transfer_expiry_days after the offer.
filenamerequired string The receiver's name for the file.
fromrequired TransferParty
idrequired string Opaque: 32 random lowercase hex digits.
kindrequired string The app's own word for what the file is.
receivedrequired integer (uint64) Bytes lmgw holds: the resume point while uploading (the next
upload's range starts here), size from ready on, and how far it
got for one that ended before.
sha256required string The file's sha256, 64 lowercase hex digits; checked when the last
byte arrives.
sizerequired integer (uint64) The file's size in bytes.
staterequired TransferState
titlerequired string What the card and the receiver show; may be empty.
torequired TransferParty
default Error.
application/json ApiError

Devices

The device listener's own routes (device link design §4.6): served on the device listener only, over TLS 1.3, and the 404 an unknown path is on the plain listener. Their bodies are at most 16 KiB (16384 bytes), refused 413 body_too_large naming it, not max_body_mb. Every answer carries Connection: close.

post/devices/enrol

Enrol a device's key with a pairing token

Capability public, open to: agent, anonymous, device, key, owner. Changes state.

A device sends the pairing link's one-time token with its public key (an EC P-256 key as its DER SubjectPublicKeyInfo, standard base64) and the client it is, over TLS 1.3 pinned to the link's fp and without a client certificate (one presented anyway, and any credential header, is ignored: the token decides). It gets its certificate (clientAuth, for that key, valid devices.client_cert_days), lmgw's device CA, the dates, its URLs and the confirmation code of its key, 201 Created. Every request of the device is then refused 403 device_unconfirmed until the owner confirms that code on the Devices card. The same key presenting the same token again while it lives (devices.token_minutes from its minting, unless the owner ended it) gets the same answer; another key gets 410 pairing_token_used and the device is marked contested. Refusals: 400 bad_request (not this shape), 400 public_key_unsupported (not a canonical EC P-256 SubjectPublicKeyInfo), 401 pairing_token_unknown, 401 device_disabled (the token stays unused), 409 public_key_in_use (another device enrolled the key), 410 pairing_token_used, 410 pairing_token_expired (lapsed or ended; the message says which and names devices.token_minutes), 413 body_too_large (over 16 KiB), 429 pairing_rate_limited with Retry-After (failed enrolments from the address, an IPv6 address by its /64, past devices.enrol_refuse_per_min in a minute), 503 devices_ca_unavailable. Served on the device listener only: the plain listener answers it 404. While no token lives, the device listener's handshake requires a client certificate, so a device without one meets the TLS alert certificate_required instead (lmgw-client: this pairing link has ended).

Request body required

application/json: object

app_id string | null The app this install is, as a lowercase reverse-DNS name
(dev.example.storyplayer, transfer::APP_ID_RULE):
what other devices of the same app offer files to (device transfers
design §2). Optional; a device without one receives no transfer. A
malformed one is refused 400 bad_request before the token is used.
client string | null Free text naming the client, shown on the Devices card
("Kai mobile 0.1.0 (Android 16)"). Optional, and never trusted for
anything.
device_name string | null The device's own name, as its user chose it on the device ("Anna's
phone"): free text, shown on the Devices card beside the name the
owner gave the link (*added 2026-10-23*). Named device_name here,
as the card's field is, because the answer's device.name is the
owner's name for the link. Optional, and never trusted for anything.
public_keyrequired string The device's public key: standard base64 (RFC 4648 §4, padded) of its
DER SubjectPublicKeyInfo, an EC P-256 key.
tokenrequired string The link's token: lmgw-enrol- and 32 lowercase hex digits. Secret
until used.

Responses

StatusDescription
201 OK.
application/json Enrolment
Fields of Enrolment
ca_certificaterequired string lmgw's device CA certificate: standard base64 of its DER. Its
SubjectPublicKeyInfo hashes to the link's fp; a client keeps it only
then.
certificaterequired string The device's certificate: standard base64 of its DER. clientAuth
only, issued by the device CA for the key the body sent.
confirm_coderequired string The confirmation code (confirm_code): the device shows it, and
the owner confirms the same code on the Devices card (§3.5).
confirmedrequired boolean Whether the owner confirmed this enrolment already (an answer asked
again after the Confirm). Until then every request of the device is
refused 403 code::DEVICE_UNCONFIRMED.
devicerequired EnrolledDevice The device row the token belongs to.
not_afterrequired string When the certificate lapses (RFC 3339, UTC).
notice_afterrequired string From when the client says "this device's certificate lapses on
<date>; pair it again before then": the issue plus two thirds of the
validity (RFC 3339, UTC; §2.3).
urlsrequired array of string The device's lmgw URLs, https, in the owner's order (§3.1).
default Error.
application/json ApiError

Ops

Routing ops

post/api/op/alias_set

Create or update a model alias, including parameter overrides

Capability admin, open to: owner. Changes state.

Alias create/update including param overrides, which model_set does not carry (its tool-plane schema stays scalar-only). Overrides are replaced wholesale — the form always sends the complete set.

Request body required

application/json: object

action string Default "".
alias string | null Default null.
capabilities_override any An alias's capabilities override: the derived /v1/models capability
facts it replaces or extends. An empty *string* clears a stored
override; an absent field (or null) leaves the stored value as is. Default null.
clear string | null Field names to reset: fallback. Default null.
enabled boolean | null Default null.
fallback string | null The alias's one fallback (openai egress design §14.2), checked as
model_set checks it; clear: "fallback" removes it. Default null.
id integer | null Default null.
overrides any Default null.
upstream_id integer | null Default null.
upstream_model string | null Default null.

Responses

StatusDescription
200 OK.
application/json RowSaved
Fields of RowSaved
fallback_notes array of string A plain alias's write (model_set): what the save says about its fallback (openai egress design §14.2):
what a chat fallback lacks or adds, a type lmgw could not check, the
same upstream, the references a rename rewrote, the rows a delete
leaves without a working fallback. Absent when there is nothing to
say.
idrequired integer (int64) The row's id: the new row's for create.
messagerequired string What was done, for a person to read.
note string | null Something to warn about on a row that was saved all the same: an
openai upstream on a host that is not OpenAI's (UpstreamView::host_note).
Only the dashboard's upstream_set_full sets it; left out otherwise.
okrequired boolean Always true; a refusal is an error answer instead.
default Error.
application/json ApiError
post/api/op/candidate_alias_set

Create, update, delete, enable, disable or preview a candidate alias

Capability admin, open to: owner. Changes state.

The answer follows the action: preview answers CandidateAliasPreview (the draft's derivation and the models it could add, written nowhere), every other action CandidateAliasSaved.

Request body required

application/json: object

action string What to do. 'preview' validates and derives a draft (any of the fields below, over an existing row named by id/alias or a brand-new one) without saving it — the same response shape, plus 'addable' (local chat models not yet in candidates and which enabled facet each would drop) and an 'error' that never aborts the rest of the answer. Default "".
alias string | null The client-facing model name. On create this is the new alias; otherwise it selects the row (pass id as well to rename). Refused if it already names a plain alias or a local model of any class. Default null.
background boolean | null Scheduled/background traffic: never evicts a model foreground requests use, never waits, and may only start the primary into free VRAM or evict another idle background-owned entry. Default false. Default null.
candidates string | null Local chat model ids (lmgw__local_model_set rows, not aliases), one per line or comma-separated. The FIRST is the primary — the only one the alias ever starts; the rest are alternates in preference order, used only when already loaded. Every id must name an enabled local chat model. On update, absent leaves the stored list unchanged; it can never be saved empty — delete the alias instead. Default null.
capabilities_disabled string | null Facet names switched OFF, one per line or comma-separated: vision, audio, tool_calls, reasoning, structured_output. This is the FULL desired list of the alias's own switches, not a delta and never auto-filled — every facet not named here that every candidate currently supports ends up enabled, including one that becomes supported later (it turns on by itself unless named here). On create, nothing is refused: an unsupported facet is simply left off. On update, switching a facet back on (removing it from this list) or leaving an already-enabled facet unnamed while a candidate drops it is refused, naming the facet. Absent leaves the stored list unchanged; use clear=capabilities_disabled to reset it to empty (every common facet back on). Default null.
clear string | null Field names to reset to unset, comma-separated: capabilities_disabled, fallback, notes. Default null.
enabled boolean | null Whether the alias resolves. Default null.
fallback string | null The model or alias that answers when this one cannot: the GPU hold, VRAM outside lmgw, background traffic deferred, an unavailable candidate, an exhausted upstream quota, an unreachable upstream, or a disabled row. A local model id, a passthrough id or a plain alias of the same model type (a chat model; it answers for the whole alias, a candidate's own row fallback is never used through it. Without one, the alias refuses (503 gpu_hold under the hold, 503 gpu_deferred for a background request) rather than leave the machine); not a candidate alias. Chains are allowed; a loop is refused. clear: 'fallback' removes it. Default null.
id integer | null Candidate alias row id. Default null.
notes string | null Free-text notes. Default null.

Responses

StatusDescription
200 OK.
application/json
One of 2 shapes
CandidateAliasPreview
Fields of CandidateAliasPreview
addablerequired array of AddableCandidate Every enabled local chat model not yet a candidate, and which of the
enabled facets it would lack if added: the "add candidate" list's
filter.
advisoriesrequired array of string Worth flagging, but not an error.
common_facetsrequired array of string Facets every candidate currently supports.
context_lengthrequired integer | null Minimum across routable_candidates; null if any of them is unknown or nothing
is routable.
enabled_facetsrequired array of string The facets the draft would have enabled (wire facet names).
errorrequired string | null The first refusal a save of this draft would make, if any.
fallback_usablerequired boolean The alias fallback resolves and is not local.
max_output_tokensrequired integer | null Same rule as context_length.
okrequired boolean false when error is set.
problemsrequired array of string What is wrong with a candidate or the fallback, in prose.
routable_candidatesrequired array of string Candidates the gate may route to right now, in list order.
unsupported_byrequired object Facet wire name -> candidate ids that do not support it.
action: preview.
CandidateAliasSaved
Fields of CandidateAliasSaved
advisories array of string Worth flagging, but not an error: a candidate with --cache-ram 0, a
fallback that lacks an enabled facet.
common_facets array of string Facets every candidate currently supports: the ceiling a save may enable.
context_length integer | null Minimum across routable_candidates; null if any of them is unknown or nothing
is routable. Absent where the derived keys are.
enabled_facets array of string The stored enabled facet set (wire facet names).
fallback_notes array of string What the save says about the fallback (openai egress design §14.2):
what a chat fallback lacks or adds, a type lmgw could not check, the
same upstream, the references a rename rewrote, the rows a delete
leaves without a working fallback. Absent when there is nothing to
say.
fallback_usable boolean The alias fallback resolves and is not local.
idrequired integer (int64) The row's id.
max_output_tokens integer | null Same rule as context_length.
messagerequired string What was done, for a person to read.
okrequired boolean Always true; a refusal is an error answer instead.
problems array of string What is wrong with a candidate or the fallback, in prose.
routable_candidates array of string Candidates the gate may route to right now, in list order.
action: create, update, enable, disable or delete.
default Error.
application/json ApiError
post/api/op/model_set

Create, update, delete, enable or disable a model alias

Capability admin, open to: owner. Changes state.

Create, update, delete, enable or disable a model alias — the friendly name clients request, mapped onto an upstream and its real model id. Identify an existing alias by id or by its current alias name. This maps a name onto a REMOTE upstream; to configure a local llama.cpp GGUF use lmgw__local_model_set instead.

Request body required

application/json: object

action string What to do. Default "".
alias string | null The client-facing model name. On create this is the new alias; otherwise it selects the row (pass id as well to rename). Default null.
capabilities_override any Capability facts set on the row, merged over what lmgw derives for /v1/models: a JSON object with optional keys capabilities (deep-merged; e.g. {"input_modalities":["text","image"],"reasoning":{"kind":"levels","levels":["low","high"]}}), max_output_tokens, notes (appended). Use it only for facts the GGUF or the provider catalog does not state; the result is published with source "owner". Default null.
clear string | null Field names to reset to unset, comma-separated: 'capabilities_override', 'fallback'. Default null.
enabled boolean | null Whether the alias resolves. Default null.
fallback string | null The model or alias that answers when this one cannot: the GPU hold, VRAM outside lmgw, background traffic deferred, an unavailable candidate, an exhausted upstream quota, an unreachable upstream, or a disabled row. A local model id, a passthrough id or a plain alias of the same model type (what this alias's upstream model is: a chat model for a chat model, an embedder for an embedder); not a candidate alias. Chains are allowed; a loop is refused. clear: 'fallback' removes it. Default null.
id integer | null Alias row id. Default null.
upstream string | null Upstream to route to, by name or numeric id. Default null.
upstream_model string | null The real model id at the upstream, e.g. gpt-4o-mini. Default null.

Responses

StatusDescription
200 OK.
application/json RowSaved
Fields of RowSaved
fallback_notes array of string A plain alias's write (model_set): what the save says about its fallback (openai egress design §14.2):
what a chat fallback lacks or adds, a type lmgw could not check, the
same upstream, the references a rename rewrote, the rows a delete
leaves without a working fallback. Absent when there is nothing to
say.
idrequired integer (int64) The row's id: the new row's for create.
messagerequired string What was done, for a person to read.
note string | null Something to warn about on a row that was saved all the same: an
openai upstream on a host that is not OpenAI's (UpstreamView::host_note).
Only the dashboard's upstream_set_full sets it; left out otherwise.
okrequired boolean Always true; a refusal is an error answer instead.
default Error.
application/json ApiError
post/api/op/model_visibility

Hide or unhide models of an expose-all upstream's live catalog

Capability admin, open to: owner. Changes state.

Hide/unhide one or more models of an expose_all upstream's live catalog from /v1/models and the client-facing model list. The model itself is never configured here — it is whatever the upstream's catalog reports — so there is no id, only the (upstream_id, model_id) pair that names one entry of a live catalog.

Request body required

application/json: object

action string Default "".
model_id string | null Default null.
model_ids array | null Several entries of the same catalog at once ("hide the 17 shown"):
one transaction and one snapshot reload instead of 17 of each.
Combines with model_id. Default null.
upstream_id integer | null Default null.

Responses

StatusDescription
200 OK.
application/json ModelVisibilitySaved
Fields of ModelVisibilitySaved
countrequired integer (uint) How many distinct models the call named: model_id and model_ids
together, trimmed, empty entries and repeats dropped.
messagerequired string What was done, naming the model or how many, for a person to read.
okrequired boolean Always true; a refusal is an error answer instead.
default Error.
application/json ApiError
post/api/op/upstream_quota_clear

Forget that an upstream is out of quota

Capability admin, open to: owner. Changes state.

lmgw remembers an upstream that answered insufficient_quota (quota on /api/upstreams): until its next check, models and aliases on it that have a fallback answer with the fallback (openai egress design §14.6). This forgets it, so the next request goes to the upstream again: the Upstreams page's Check now.

Request body required

application/json: object

idrequired integer (int64) Upstream id, from lmgw__upstreams.

Responses

StatusDescription
200 OK.
application/json RowSaved
Fields of RowSaved
fallback_notes array of string A plain alias's write (model_set): what the save says about its fallback (openai egress design §14.2):
what a chat fallback lacks or adds, a type lmgw could not check, the
same upstream, the references a rename rewrote, the rows a delete
leaves without a working fallback. Absent when there is nothing to
say.
idrequired integer (int64) The row's id: the new row's for create.
messagerequired string What was done, for a person to read.
note string | null Something to warn about on a row that was saved all the same: an
openai upstream on a host that is not OpenAI's (UpstreamView::host_note).
Only the dashboard's upstream_set_full sets it; left out otherwise.
okrequired boolean Always true; a refusal is an error answer instead.
default Error.
application/json ApiError
post/api/op/upstream_set

Create, update, delete, enable or disable an upstream provider

Capability admin, open to: owner. Changes state.

Create, update, delete, enable or disable an upstream provider. Update is partial — pass only the fields to change, everything else is kept. Omit api_key on update to leave the stored key untouched. A call that moves base_url to another address (update, enable or disable) must pass the api_key for that address in the same call when the upstream holds one, or it is refused and nothing changes: a stored key is never sent to a host it was not given for. An upstream that sends extra headers moves on the dashboard only.

Request body required

application/json: object

action string What to do. Default "".
api_key string | null Provider API key. Write-only. Default null.
base_url string | null Base URL, e.g. https://api.openai.com/v1. Required on create. Moving it needs api_key in the same call when the upstream holds a key. Default null.
catalog_all_modalities boolean | null Ask the upstream's catalog for every output modality (GET …/models?output_modalities=all), so OpenRouter lists its decision, embedding, rerank, speech, transcription, image and video models as well as its chat models. Default true; only the catalog request of an 'openai_compatible' upstream of kind 'generic' carries it. Some endpoints refuse the parameter: Gemini's OpenAI-compatible one answers 400, so with this on its catalog fails, and the error names this option. Set it false for such an upstream. Default null.
enabled boolean | null Whether the upstream is usable. Default null.
expose_all boolean | null Pass the upstream's whole catalog through without per-model aliases. Default null.
expose_prefix string | null Namespace for passthrough models, e.g. 'groq' -> groq/<model>. Default null.
id integer | null Upstream id. Required for everything except create. Default null.
kind string | null Upstream flavour. Default 'generic'. 'llama_server' goes with protocol 'llama_cpp' (or 'anthropic', for llama-server's /v1/messages) and marks the upstream local and free; leave it out with 'llama_cpp'. 'audio_cpp' (an external audio.cpp server) goes with 'openai_compatible'. Protocol 'openai' is always 'generic'. Switching the protocol to openai, openai_compatible or gemini alone makes a llama_server 'generic', and switching it to openai alone makes an audio_cpp row 'generic'. Default null.
name string | null Display name, unique. Default null.
protocol string | null Wire protocol the upstream speaks. Required on create. 'openai' is the OpenAI platform only (api.openai.com or a regional *.api.openai.com host), always kind 'generic': lmgw sends it OpenAI's own dialect, and another host is accepted with a note. 'openai_compatible' is every other OpenAI-shaped provider (OpenRouter, Kilo, Groq, Gemini's OpenAI-compatible endpoint, vLLM, an external audio.cpp server). 'llama_cpp' is llama.cpp's own server (llama-server, ik_llama.cpp) and is always kind 'llama_server'; 'openai' or 'openai_compatible' with kind 'llama_server' is refused, use protocol 'llama_cpp'. Default null.
supports_responses boolean | null The upstream implements OpenAI's /v1/responses itself, so the gateway forwards that route verbatim instead of synthesizing it from /v1/chat/completions. 'openai_compatible' only; default false. Implied on 'openai' (the OpenAI platform forwards it without the flag), and refused on every other protocol: lmgw synthesizes /v1/responses there. Most local servers have no such endpoint. Default null.
timeout_ms integer | null Timeout in ms of every request to it: its sends and its catalog (models-list) reads wait that long for an answer, and a streamed answer may go that long without an event before lmgw ends it with an error (keep-alives count only before the answer shows and while the model thinks out of sight). 0 means no bound. Default 120000. Default null.

Responses

StatusDescription
200 OK.
application/json RowSaved
Fields of RowSaved
fallback_notes array of string A plain alias's write (model_set): what the save says about its fallback (openai egress design §14.2):
what a chat fallback lacks or adds, a type lmgw could not check, the
same upstream, the references a rename rewrote, the rows a delete
leaves without a working fallback. Absent when there is nothing to
say.
idrequired integer (int64) The row's id: the new row's for create.
messagerequired string What was done, for a person to read.
note string | null Something to warn about on a row that was saved all the same: an
openai upstream on a host that is not OpenAI's (UpstreamView::host_note).
Only the dashboard's upstream_set_full sets it; left out otherwise.
okrequired boolean Always true; a refusal is an error answer instead.
default Error.
application/json ApiError
post/api/op/upstream_set_full

Create or update an upstream provider, including extra headers

Capability admin, open to: owner. Changes state.

Upstream create/update including extra_headers, which the tool-plane patch omits. Secrets follow the house convention: an empty api_key keeps the stored one, and a header value of "<set>" round-trips to the stored value for that header name.

Request body required

application/json: object

action string Default "".
api_key string | null Default null.
base_url string | null Default null.
catalog_all_modalities boolean | null Ask the catalog for every output modality
(GET …/models?output_modalities=all). On unless turned off; only an
openai_compatible row of kind generic sends it. Default null.
enabled boolean | null Default null.
expose_all boolean | null Default null.
expose_prefix string | null Default null.
extra_headers array | null (name, value) pairs, replacing the stored set. A secret as a whole:
these are typically the provider's own auth headers. Default null.
id integer | null Default null.
kind string | null What the upstream is, tied to its protocol: openai is generic only;
openai_compatible is generic or audio_cpp (an external audio.cpp
server); llama_cpp is llama_server only; anthropic is generic or
llama_server; gemini is generic. A pairing outside this is refused. Default null.
name string | null Default null.
protocol string | null The API the upstream speaks. openai: the OpenAI platform (api.openai.com)
only. openai_compatible: every other OpenAI-shaped provider (OpenRouter,
vLLM, an external audio.cpp server…). anthropic: Anthropic's API.
gemini: Google's Gemini API. llama_cpp: llama.cpp's own server. Default null.
supports_responses boolean | null Forward /v1/responses natively instead of lmgw's own loop. Applies to
openai_compatible upstreams only; on any other protocol it is refused
when turned on and switched off when the row leaves openai_compatible. Default null.
timeout_ms integer | null Default null.

Responses

StatusDescription
200 OK.
application/json RowSaved
Fields of RowSaved
fallback_notes array of string A plain alias's write (model_set): what the save says about its fallback (openai egress design §14.2):
what a chat fallback lacks or adds, a type lmgw could not check, the
same upstream, the references a rename rewrote, the rows a delete
leaves without a working fallback. Absent when there is nothing to
say.
idrequired integer (int64) The row's id: the new row's for create.
messagerequired string What was done, for a person to read.
note string | null Something to warn about on a row that was saved all the same: an
openai upstream on a host that is not OpenAI's (UpstreamView::host_note).
Only the dashboard's upstream_set_full sets it; left out otherwise.
okrequired boolean Always true; a refusal is an error answer instead.
default Error.
application/json ApiError
post/api/op/upstream_test

Test connectivity to a configured upstream

Capability admin, open to: owner

Connect to one configured upstream now. It answers {ok: true} when the model list came back; a failed connection is an error answer with the upstream's own words.

Request body required

application/json: object

idrequired integer Upstream id, from /api/upstreams.

Responses

StatusDescription
200 OK.
application/json UpstreamTested
Fields of UpstreamTested
noterequired string | null The row's host_note (UpstreamView::host_note): it answered, and
it is an openai row on a host that is not OpenAI's.
okrequired boolean Always true; a failed test is an error answer instead.
default Error.
application/json ApiError

Model ops

post/api/op/audio_model_set

Create, update, delete, enable or disable an audio.cpp model

Capability admin, open to: owner. Changes state.

Audio model CRUD — the same shape as aux_model_set (sparse patch, unknown fields rejected, the snapshot reloaded after every write, apply stays a separate step), adapted to the wider audio.cpp field set (task, mode, load/session/request options, voice presets, and where the row runs: backend 'cpu' with its threads, which takes no VRAM and keeps serving under the GPU hold). The same function lmgw__audio_model_set calls.

Request body required

application/json: object

action string What to do. Default "".
backend string | null Where this row runs: 'cpu' runs it on the CPU — no VRAM charged, never evicted, not stopped by the GPU hold, no residency learned; its inherited run args lose the GPU passthrough. Omit to keep, name 'backend' in clear to inherit the audio class backend again. No other value: another GPU backend is the class setting. Default null.
busy_timeout_ms integer | null How long a request waits for the model while another one runs, in ms; 0 waits forever. Negative is refused. Name 'busy_timeout_ms' in clear to inherit again. Default null.
clear string | null Field names to reset, comma- or space-separated: 'lazy', 'busy_timeout_ms', 'backend', 'threads', 'extra_run_args', 'fallback', and on update 'residency' (forget the learned residency). A field named here is unset on create too, whatever value came with it. Default null.
config_id string | null Named config asset id, for a model directory holding several. Empty clears. Default null.
default_request_options object | null Request-option defaults applied to every call, as a JSON object (a JSON string here), e.g. '{"speed": 1.1}' — the family's 'request' options. A request that names one still wins. Default null.
default_voice_preset any The voice a request that names none gets: a preset name from voice_presets, or an inline preset as a JSON object string. Empty clears. Default null.
enabled boolean | null Serve this model (a disabled model has no container). Default null.
extra_run_args array | null 'podman run' args override, one argument per entry. Absent leaves it unchanged; name it in 'clear' to revert to the class default — which carries the GPU and SELinux flags, so override it only knowingly. An override with no args is never stored: it is the class default. A row on the CPU runs its own override as written; one that still passes a GPU is named in lmgw__local_model_get's problems. Default null.
fallback string | null The model or alias that answers when this one cannot: the GPU hold, VRAM outside lmgw, background traffic deferred, an unavailable candidate, an exhausted upstream quota, an unreachable upstream, or a disabled row. A local model id, a passthrough id or a plain alias of the same model type (a model of the same task: speech-to-text for asr, text-to-speech for tts. A row on the CPU is not stopped by the hold, so its fallback answers only for the other reasons); not a candidate alias. Chains are allowed; a loop is refused. clear: 'fallback' removes it. Default null.
family string | null audio.cpp model family, e.g. 'pocket_tts' or 'qwen3_asr' — the catalog's family id. Required on create. Default null.
id integer | null Audio model row id. Default null.
image string | null Podman image override for this model's own container. Empty clears back to the audio class image. Default null.
lazy boolean | null Load the model on its first request (true) or at container start (false). Omit to inherit the audio class setting; name 'lazy' in clear to go back to inheriting. Default null.
load_options object | null audio.cpp load options as a JSON object (written as a JSON string on this tool plane), e.g. '{"language": "de"}' — the family's 'load' options. Replaces the stored object; '{}' empties it. Default null.
mode string | null 'offline' (default: one buffered answer) or 'streaming' (the family streams its output as server-sent events). Default null.
model_id string | null Client-facing model id (the part after the audio prefix, so 'audio/<model_id>'). Required on create. Without id it selects the row to update, delete, enable or disable; WITH id, on update, it renames the row, and the old container is removed. Default null.
model_spec_override string | null A '<family>.json' spec (or a directory of them) relative to the audio models dir that replaces the image's built-in catalog for this row. Empty clears. Default null.
path string | null The model directory, RELATIVE to the audio models dir — a package's suggested_path, e.g. 'audio-cpp/audio.cpp-gguf/PocketTTS-GGUF/german'. Required on create. Default null.
session_options object | null audio.cpp session options as a JSON object (a JSON string here), e.g. '{"weight_type": "q8_0"}' — the family's 'session' options. Replaces the stored object; '{}' empties it. Default null.
task string | null What the model does: tts, asr, gen (music, sound), clon (voice cloning), vc, svc, s2s, sep (separation), vad, diar, align, vdes (voice design), spk, midi. A package's suggested_task. Required on create. Default null.
threads integer | null This row's thread count, 1 or more (no upper cap; above this machine's CPUs the save says so). Name 'threads' in clear for the default: this machine's physical cores for a row switched to the CPU (backend='cpu' on the row), the audio class's threads for every other row — one that inherits a class backend of cpu included. Several CPU rows busy at once each run their own pool, so split the cores between them. Default null.
voice_presets object | null Named voices as a JSON object (a JSON string here): name -> {"voice_id": "<shipped voice>"} or {"voice_ref": "/models/<clip>.wav"}, e.g. '{"alba": {"voice_id": "alba"}}'. Replaces the stored object. Default null.
warm_start boolean | null Start this model's container when lmgw launches. Default null.
weight_id string | null Named weights asset id, for a model directory holding several variants (e.g. 'q8_0'). Empty clears. Default null.

Responses

StatusDescription
200 OK.
application/json AudioModelSaved
Fields of AudioModelSaved
fallback_notes array of string What the save says about the fallback (openai egress design §14.2):
what a chat fallback lacks or adds, a type lmgw could not check, the
same upstream, the references a rename rewrote, the rows a delete
leaves without a working fallback. Absent when there is nothing to
say.
idrequired integer (int64) The row's id.
messagerequired string What was done, for a person to read.
okrequired boolean Always true; a refusal is an error answer instead.
residency_reset boolean update: whether the save reset the model's learned residency (the
owner named residency in clear and one was learned). Absent for
every other action.
default Error.
application/json ApiError
post/api/op/aux_model_set

Create, update, delete, enable or disable an aux (embedding, rerank or decision) model

Capability admin, open to: owner. Changes state.

Create, update, delete, enable or disable an AUX model: an embedding model (served on /v1/embeddings with --embeddings), a reranker (served on /v1/rerank with --reranking) or a decision model (a GGUF whose header declares decision.type, served on /v1/systemone). This is the class for models that answer without generating: encoders, whose header declares a pooling_type or a classifier head and which have no LM head, and decision models, causal ones included, which llama-server serves without a generation route. Neither can be a chat model. Aux models live in their own models directory (download with lmgw__hf_add target=aux, list with lmgw__gguf_files target=aux) and are exposed under their kind's prefix, both in lmgw__settings' aux_router: public_prefix for embedders and rerankers (usually 'embed/<model_id>'), decision_prefix for decision models (usually 'decide/<model_id>'); a row answers to its own prefix only. Get kind, pooling and ctx_size (and for a decision model ubatch_size, batch_size and backend) from lmgw__local_model_plan target=aux rather than guessing: the wrong pooling produces vectors that look fine and retrieve garbage. Update is partial: pass only what changes, and use 'clear' to unset a field. A model's own container starts on its first request; lmgw__local_model_test target=aux then proves it embeds, reranks or answers one System One question.

Request body required

application/json: object

action string What to do. Default "".
backend string | null 'cpu' runs the model on the CPU: --n-gpu-layers 0, the class's run args without the GPU passthrough, no VRAM charged, and it keeps serving while the GPU hold is on. Omit to keep the current value; an empty string (or 'backend' in clear) runs it on the GPU. Default null.
batch_size integer | null --batch-size, 1 or more; omit for llama-server's default. Default null.
clear string | null Field names to reset to unset, comma-separated: 'extra_args', 'extra_run_args', 'image', 'fallback', 'ctx_size', 'ubatch_size', 'batch_size', 'mmproj_path', 'backend', 'threads'. Default null.
ctx_size integer | null Context length (--ctx-size). Use the model's trained context from the plan; llama-server refuses a longer input with an error rather than truncating it. 'ctx_size' in clear takes llama-server's default. Default null.
enabled boolean | null Serve this model (a disabled model has no container). Default null.
extra_args array | null Escape hatch for llama-server flags with no field above, one argument per entry (['--flash-attn', 'on']). --embeddings, --reranking, --pooling, --ctx-size, --ubatch-size, --batch-size, --mmproj, --n-gpu-layers and --threads are rendered from the fields above; a copy here is ignored when its field is set. Default null.
extra_run_args array | null 'podman run' args override, one argument per entry. Absent leaves it unchanged; name it in 'clear' to revert to the class default. An override with no args is never stored: it is the class default. Default null.
fallback string | null The model or alias that answers when this one cannot: the GPU hold, VRAM outside lmgw, background traffic deferred, an unavailable candidate, an exhausted upstream quota, an unreachable upstream, or a disabled row. A local model id, a passthrough id or a plain alias of the same model type (an embedder for an embedder, a reranker for a reranker, a decision model that answers /v1/systemone for a decision row); not a candidate alias. Chains are allowed; a loop is refused. clear: 'fallback' removes it. Default null.
gguf_path string | null Weights GGUF, relative to the AUX models directory (e.g. 'Qwen/Qwen3-Embedding-4B-GGUF/Qwen3-Embedding-4B-Q4_K_M.gguf'). Required on create. Files in the chat models directory cannot be addressed — download into the aux dir with lmgw__hf_add target=aux. Default null.
id integer | null Aux model row id. Default null.
idle_seconds integer | null Seconds idle before the model unloads. 0 = never. Default 300. Default null.
image string | null Podman image override for this model's own container. Empty or absent leaves it unset; 'clear' reverts to the aux class image. Default null.
kind string | null 'embed' (default on create) serves /v1/embeddings; 'rerank' serves /v1/rerank; 'decision' serves /v1/systemone (no kind flag, no pooling). lmgw__model_inspect reports which a file is. Default null.
mmproj_path string | null A projector (--mmproj) relative to the AUX models directory, for a model that reads images (a vision-language embedder, an image-capable decision model). Use the one lmgw__local_model_plan finds beside the weights. Charged with the weights. Empty string clears. Default null.
model_id string | null Client-facing model id (the part after the aux prefix); also selects the row when id is omitted. Default null.
pooling string | null Pooling strategy (--pooling) for an embedding model. Use the value lmgw__local_model_plan reads from the GGUF header; omit to let llama-server pick the model's default. Never set on a rerank model (--reranking selects rank pooling itself, and a second pooling flag breaks it) or a decision model. Empty string clears. Default null.
threads integer | null --threads, 1 or more. Unset renders none on the GPU, and on the CPU this machine's physical cores (the logical CPU count where the core topology cannot be read) unless extra_args name a count. Default null.
ubatch_size integer | null --ubatch-size, 1 or more; omit for llama-server's default. An encoder whose input llama-server cannot split (any but a last-token embedder or a causal reranker) evaluates its whole input in one ubatch, so this bounds every input it answers; lmgw__local_model_plan sets it to the context there. Raise batch_size with it: llama.cpp lowers the ubatch to the batch. The VRAM ledger charges the compute buffer it grows. Default null.
warm_start boolean | null Start this model's container when lmgw launches. Default null.

Responses

StatusDescription
200 OK.
application/json AuxModelSaved
Fields of AuxModelSaved
fallback_notes array of string What the save says about the fallback (openai egress design §14.2):
what a chat fallback lacks or adds, a type lmgw could not check, the
same upstream, the references a rename rewrote, the rows a delete
leaves without a working fallback. Absent when there is nothing to
say.
idrequired integer (int64) The row's id.
messagerequired string What was done, for a person to read, with the next step.
okrequired boolean Always true; a refusal is an error answer instead.
public_name string create: the name clients request the model by. Absent for every
other action.
warnings array of string create, update: why the model may not load (empty when none fired).
Absent for delete.
default Error.
application/json ApiError
post/api/op/image_model_set

Create, update, delete, enable or disable an image (stable-diffusion.cpp) model

Capability admin, open to: owner. Changes state.

Create, update, delete, enable or disable an IMAGE model: a stable-diffusion.cpp pipeline served by sd-server on /v1/images/generations (and /v1/images/edits when the row is an edit pipeline). This is the class for diffusion models — they have no chat template and no embeddings, so they are neither a chat nor an aux row. The whole chain, and the short way round it: lmgw__image_recipes -> lmgw__image_recipe_add key=<key> (it queues every component and hands back a prefilled row) -> lmgw__hf_downloads ids=<the queued ids> until each says 'done' -> THIS TOOL with the returned row -> lmgw__local_model_test model_id=<id> target=image to prove it loads and draws. For a pipeline no recipe covers, download the files yourself with lmgw__hf_add target=image (one call per component — they live in different repos) and write 'files' by hand. The container starts on the first request; there is no separate apply for a model that has never run. 'files' is a map of flag key -> path RELATIVE to the image models directory, one 'key = value' per line: the key is sd-server's long flag with '-' written as '_' (model, diffusion_model, vae, clip_l, clip_g, t5xxl, llm, llm_vision, clip_vision, taesd, control_net, ip_adapter, photo_maker, upscale_model, high_noise_diffusion_model, tokenizer, lora_model_dir, hires_upscalers_dir, embd_dir, …). EXACTLY ONE of 'model' (an all-in-one checkpoint) and 'diffusion_model' (a standalone DiT) is required — everything else hangs off it. 'args' is the same shape for runtime and default-generation flags (type, offload_to_cpu, diffusion_fa, vae_tiling, cfg_scale, steps, sampling_method, width, height, …); a key with no value is a switch. Both maps are checked against the container image's own --help when the row is saved, so a wrong key is refused by name (with a suggestion) instead of failing at the first start — lmgw__llama_flags does the same job for the chat class. Per-request parameters are NOT row fields: steps, seed, negative prompt, sampler and LoRA reach a request through sd.cpp's own <sd_cpp_extra_args>{…}</sd_cpp_extra_args> block inside the prompt. What goes in 'args' are this row's DEFAULTS.

Request body required

application/json: object

action string What to do. Default "".
args KeyMap | null Runtime and default-generation flags, one 'key = value' per line — e.g. 'diffusion_fa' (a bare key is a switch) then 'cfg_scale = 1.0' then 'steps = 8' then 'offload_to_cpu'. Same replace-wholesale rule as 'files'. A JSON object is accepted too.
capabilities_override any An override of the derived /v1/models facts for this row, as a JSON object (keys: capabilities, max_output_tokens, notes). Empty clears it. Default null.
clear string | null Field names to reset to unset, comma-separated: 'args', 'modes', 'extra_run_args', 'image', 'fallback', 'capabilities_override', 'prompt_style', 'preview_mode'. Not 'files': a row with no files names no pipeline. Default null.
edit boolean | null This pipeline takes reference images (Kontext, Qwen-Image-Edit, Z-Image-Omni) and may serve /v1/images/edits. Load-bearing, not descriptive: sd-server does not refuse a reference-image request against a pipeline that cannot take one, it segfaults, so lmgw refuses that request itself for every row without this flag. Default null.
enabled boolean | null Serve this model (a disabled model has no container). Default null.
extra_run_args array | null 'podman run' args override, one argument per entry. Absent leaves it unchanged; name it in 'clear' to revert to the class default (an override with no args is never stored: it is the class default). The GPU device flags live here — sd-server links libcuda directly and will not even print its help without the card. Default null.
fallback string | null The model or alias that answers when this one cannot: the GPU hold, VRAM outside lmgw, background traffic deferred, an unavailable candidate, an exhausted upstream quota, an unreachable upstream, or a disabled row. A local model id, a passthrough id or a plain alias of the same model type (an image model); not a candidate alias. Chains are allowed; a loop is refused. clear: 'fallback' removes it. Default null.
files KeyMap | null The pipeline's files, one 'key = path' per line, each path relative to the image models directory — e.g. 'diffusion_model = Tongyi-MAI/Z-Image-Turbo/z-image-turbo-Q4_K.gguf' then 'vae = Comfy-Org/flux/ae.safetensors' then 'llm = Qwen/Qwen3-4B-Instruct-GGUF/Qwen3-4B-Q4_K_M.gguf'. Required on create. Replaces the stored map wholesale on update (send the whole set, not just the line that changed). A leading '/models/' — the spelling the rendered command line shows — is dropped for you. A JSON object is accepted too.
id integer | null Image model row id. Default null.
idle_seconds integer | null Seconds idle before the model unloads. 0 = never. Default 300. Worth keeping low: a loaded pipeline is 7-13 GiB of the card that nothing else can use. Default null.
image string | null Podman image override for this model's own container (the class default is stable-diffusion.cpp's master-cuda tag). Empty or absent leaves it unset; 'clear' reverts to the class image. Default null.
model_id string | null Client-facing model id (the part after the image prefix, so 'image/<model_id>'); also selects the row when id is omitted. Default null.
modes StrList | null What this pipeline does, comma-separated: 'img_gen' (the default when empty), or 'img_gen,vid_gen' for one that also makes video. This drives task and endpoints on /v1/models before the container has ever run; it is compared against what the running server reports and a mismatch becomes a warning, never a silent correction.
preview_mode string | null How the live preview of a running generation is drawn: 'none' (no preview, elapsed time only), 'proj' (a quick colour sketch, free), 'tae' (needs a TAE file in files, which then also decodes the final image at lower quality) or 'vae' (the row's VAE every step: slower, more memory). 'clear' goes back to the default: 'proj' where the build offers it. Default null.
prompt_style string | null How the chat model writes this row's prompts when it calls image__generate: 'natural' (plain sentences: FLUX, Z-Image, Qwen-Image), 'keywords' (short comma-separated phrases: SDXL) or 'tags' (booru-style tags: anime fine-tunes). 'clear' goes back to what the matching shipped recipe says. Default null.
warm_start boolean | null Start this model's container when lmgw launches. Default null.

Responses

StatusDescription
200 OK.
application/json ImageModelSaved
Fields of ImageModelSaved
command_line string create, update: the podman run line the saved row starts with (an
empty text when the row is not found). Absent for delete.
fallback_notes array of string What the save says about the fallback (openai egress design §14.2):
what a chat fallback lacks or adds, a type lmgw could not check, the
same upstream, the references a rename rewrote, the rows a delete
leaves without a working fallback. Absent when there is nothing to
say.
idrequired integer (int64) The row's id.
messagerequired string What was done, for a person to read, with the next step.
okrequired boolean Always true; a refusal is an error answer instead.
peak_reset boolean update: whether the save dropped the learned peak because the files or
a flag changed, so the figure no longer describes the pipeline. Absent
for every other action.
public_name string create: the name clients request the model by. Absent for every
other action.
warnings array of string create, update: why the model may not load (empty when none fired).
Absent for delete.
default Error.
application/json ApiError
post/api/op/local_model_set

Create, update, delete, enable, disable or duplicate a local chat model

Capability admin, open to: owner. Changes state.

Create, update, delete, enable, disable or duplicate a local llama.cpp CHAT model entry. Every llama-server parameter lmgw manages is settable here. Embedding, rerank and decision models are a different class with their own directory and tool — lmgw__aux_model_set — and must not be created here (a chat row serves none of /v1/embeddings, /v1/rerank and /v1/systemone). Prefer lmgw__local_model_plan to derive these values from the GGUF itself rather than guessing them. Update is partial: pass only what changes, and use 'clear' to unset a field. Duplicate clones the model named by id/ model_id under a fresh '<id>-copy' id (GGUF, params, args and flags carry over verbatim) — a quick way to try a different configuration (reasoning vs not, a different slot/context split) against the same weights. A model's own container starts automatically on its first request; if it might already be running under stale config, run lmgw__container model=<id> action=apply to recreate it explicitly. lmgw__local_model_test then confirms the model really loads (it starts the container itself, so it works either way).

Request body required

application/json: object

action string What to do. Default "".
batch_size integer | null Logical batch size (--batch-size). Default null.
cache_ram integer | null Host RAM in MiB for holding the prompt state of idle slots (--cache-ram), so returning to an earlier conversation skips reprocessing it. -1 = no limit, 0 = disabled; omit to keep llama.cpp's own default of 8192. Default null.
cache_type_k string | null KV cache K quantization (--cache-type-k). q8_0 roughly halves KV memory versus the f16 default. Default null.
cache_type_v string | null KV cache V quantization (--cache-type-v). Default null.
capabilities_override any Capability facts set on the row, merged over what lmgw derives for /v1/models: a JSON object with optional keys capabilities (deep-merged; e.g. {"input_modalities":["text","image"],"reasoning":{"kind":"levels","levels":["low","high"]}}), max_output_tokens, notes (appended). Use it only for facts the GGUF or the provider catalog does not state; the result is published with source "owner". Default null.
chat_template_file string | null Override the embedded template (--chat-template-file), relative to the models directory. Default null.
chat_template_kwargs string | null Further chat-template variables, as the JSON object string --chat-template-kwargs takes, e.g. '{"preserve_thinking":true}'. This is the only route to that flag — one in extra_args is ignored. A 'reasoning_effort' key here is folded into the field above, since both reach the same template variable. Default null.
clear string | null Field names to reset to unset, comma-separated (e.g. 'spec_type,draft_gguf_path'). Needed because omitting a field means 'leave unchanged'. 'fallback' removes the row's fallback. 'ladder' resets the row to not-a-ladder — the base's own gguf_path/ctx_size are untouched. Default null.
ctx_size integer | null Context length (--ctx-size). Use the model's real trained context from lmgw__model_inspect; do not pick a smaller round number defensively. Default null.
draft_gguf_path string | null Speculative drafter GGUF (--model-draft), relative to the models directory. Often shipped alongside the weights in the same repo. Default null.
enabled boolean | null Serve this model (a disabled model has no container). Default null.
extra_args array | null Escape hatch for llama-server flags with no field above, one argument per entry (e.g. ['--no-warmup'], ['--threads', '16']). Absent leaves them unchanged; an empty list clears them. Validated against the running build. A flag that HAS a field above is ignored here — use the field. Default null.
extra_run_args array | null podman run args override, one entry per argument. Absent leaves it
unchanged; an empty list is no override either, and clear reverts a
previously set override back to inheriting the class's
extra_run_args. An override is never stored as an empty list. Default null.
fallback string | null The model or alias that answers when this one cannot: the GPU hold, VRAM outside lmgw, background traffic deferred, an unavailable candidate, an exhausted upstream quota, an unreachable upstream, or a disabled row. A local model id, a passthrough id or a plain alias of the same model type (a chat model); not a candidate alias. Chains are allowed; a loop is refused. clear: 'fallback' removes it. Default null.
fit string | null Let llama-server shrink UNSET arguments to fit device memory (--fit). It never touches a value set here, so it cannot silently cap a context length you configured. Default null.
fit_ctx integer | null Floor on the context --fit may choose (--fit-ctx). Default null.
flash_attn string | null Flash attention (--flash-attn). Default null.
gguf_path string | null Weights GGUF, relative to the models directory (e.g. 'unsloth/Qwen3.5-9B-GGUF/Qwen3.5-9B-UD-Q4_K_XL.gguf'). Required on create. Prefer lmgw__hf_add to obtain one: it fetches the projector and drafter along with the weights, which this route cannot discover. lmgw__gguf_files lists what is already on disk. Default null.
id integer | null Local model row id. Default null.
idle_seconds integer | null Seconds idle before the model unloads and frees VRAM. 0 = never. Default null.
image string | null Podman image override for this model's own container. Empty (or
absent) leaves it unset; clear is what reverts a previously set
override back to inheriting the class image. Default null.
jinja boolean | null Use the chat template embedded in the GGUF (--jinja). Required for any model with a custom template, and for tool calling. Default null.
kv_unified boolean | null One shared KV pool across every slot instead of one pool per slot (--kv-unified true / --no-kv-unified false), so a single conversation can use the whole context instead of being capped to ctx_size / parallel. llama-server aborts every running request when a shared pool overflows, so lmgw refuses to save this as true with more than one effective slot unless n_predict is also set (it bounds the reservation the pool ledger guards the row with). Omit to leave llama-server's own default, which is unified exactly when parallel is also omitted. Default null.
kv_unified_per_slot integer | null Per-request context cap on a unified row, and — only when ctx_size is unset — how large the shared pool is sized (--kv-unified-per-slot, parallel x this). Meaningless on a split row (kv_unified effectively off), so it is refused there; must be positive. Default null.
ladder array | null Turn this row into a ladder: rungs above the base, given as a JSON array string, e.g. '[{"gguf_path":"top.gguf","ctx_size":65536}]' — each a GGUF and its own --ctx-size (gguf_path/ctx_size here stay the row's own, as rung 1). Every other field — template, sampling, projector, drafter, parallel, cache types — is shared by every rung. A request that outgrows the running rung makes the whole model climb to the smallest rung that fits, and it only comes back down when the container stops. Refused at save time unless: n_predict is set and positive (no rung can promise an answer fits without a max output ceiling); parallel is at least 1 with no effectively-unified KV cache (a shared pool has no per-slot guarantee); each rung's per-slot context (ctx_size / parallel) is strictly increasing, base included, exceeds n_predict (room for at least one prompt token) and stays at or below its own GGUF's trained context; every rung's GGUF shares the base's architecture and tokenizer, and — with a projector configured — its embedding width (the fit check counts identically whichever rung is running); spec_type draft-mtp needs either every rung's own GGUF to carry MTP layers or a drafter (draft_gguf_path); and, with a projector configured, its per-image token bound is known. Omitted or empty leaves the ladder unchanged, the same convention every optional field here follows; '[]' or clear: "ladder" is what turns the row back into a plain one. Default null.
min_p number | null Minimum probability (--min-p). Default null.
mmproj_path string | null Multimodal vision/audio projector GGUF (--mmproj), relative to the models directory exactly like gguf_path. Required for a multimodal model to see images; without it the model loads text-only. Default null.
model_id string | null Client-facing model id; also selects the row when id is omitted. Default null.
n_gpu_layers integer | null Layers to offload to the GPU (--n-gpu-layers). 999 = all. Default null.
n_predict integer | null Maximum tokens one response may generate (--n-predict). This is what /v1/models reports as max_output_tokens; omit for llama-server's unbounded default rather than guessing a cap. -1 = unbounded. Default null.
no_mmproj boolean | null Refuse to auto-load a projector sitting next to the weights (--no-mmproj). For the text-only twin of a multimodal repo. Default null.
parallel integer | null Concurrent request slots (--parallel). Splits the context. Default null.
presence_penalty number | null Presence penalty (--presence-penalty). Default null.
public boolean | null Routable by model id without a manual alias. Default null.
reasoning string | null Enable thinking (--reasoning). Default null.
reasoning_budget integer | null Thinking token budget (--reasoning-budget). -1 = unrestricted. Default null.
reasoning_effort string | null Default thinking depth (--reasoning-effort) for a model whose chat template reads a 'reasoning_effort' variable (Qwen3.8, GPT-OSS, …); a request that sets reasoning_effort still overrides it. Usual levels are minimal, low, medium, high, xhigh, max, and 'none' for templates that use it to skip thinking — but llama-server passes the value to the template unchecked, so the accepted set belongs to that template. Omit to leave the template's own default. Default null.
reasoning_format string | null How thinking output is parsed back out of the response (--reasoning-format). 'deepseek' puts it in message.reasoning_content. Default null.
reasoning_preserve boolean | null Keep the thinking trace of EVERY assistant turn in the history rather than only the last one (--reasoning-preserve). Honoured only by templates advertising 'supports_preserve_reasoning'; omit to leave the template's own default in place. Default null.
repeat_penalty number | null Repetition penalty (--repeat-penalty). Default null.
seed integer | null RNG seed (--seed). -1 = random. Default null.
spec_draft_n_max integer | null Tokens to draft per step (--spec-draft-n-max). Default null.
spec_draft_n_min integer | null Minimum drafted tokens (--spec-draft-n-min). Default null.
spec_draft_ngl string | null Drafter GPU layers (--spec-draft-ngl): a number, 'auto' or 'all'. Default null.
spec_type string | null Speculative decoding strategy (--spec-type). It MUST match the drafter: an MTP-heads GGUF is 'draft-mtp', a 'dflash'-architecture one is 'draft-dflash'. lmgw__model_inspect reports the right value for a given file. 'draft-mtp' without draft_gguf_path requires MTP layers inside the weights themselves, or the model will not load. Default null.
temp number | null Sampling temperature (--temp). Default null.
threads integer | null CPU threads (--threads). Default null.
top_k integer | null Top-k sampling (--top-k). Default null.
top_p number | null Nucleus sampling (--top-p). Default null.
ubatch_size integer | null Physical batch size (--ubatch-size). Default null.
warm_start boolean | null Start this model's own container at app launch, once the per-model
runtime exists. Default null.

Responses

StatusDescription
200 OK.
application/json LocalModelSaved
Fields of LocalModelSaved
advisories array of string create, update: saved and loadable, but misbehaving under some
input; kept apart from warnings, which are reasons it may not load.
Absent for delete and duplicate.
container_kept_previous_config boolean update: whether a container is still up on the configuration before
this change (mid-request, or a stop that failed), so a test now would
load that one. Absent for every other action.
fallback_notes array of string What the save says about the fallback (openai egress design §14.2):
what a chat fallback lacks or adds, a type lmgw could not check, the
same upstream, the references a rename rewrote, the rows a delete
leaves without a working fallback. Absent when there is nothing to
say.
idrequired integer (int64) The row's id: the new row's for create and duplicate.
messagerequired string What was done, for a person to read, with the next step.
okrequired boolean Always true; a refusal is an error answer instead.
warnings array of string create, update: why the model may not load, from the checks of the
save (empty when none fired). Absent for delete and duplicate.
default Error.
application/json ApiError
post/api/op/local_model_test

Load a configured local model and prove it does its job

Capability admin, open to: owner. Changes state.

Load a configured local model and prove it does its job: a chat model generates one token, an embedding model returns one vector (checked to be non-zero — an embedder misconfigured as a reranker answers with zeros), a reranker scores two documents, a decision model answers one System One choice question on /v1/systemone (its input tokens and answer come back), an image model draws one 256x256 four-step image and reports how many bytes came back. Works for chat, aux and image models alike; the probe is chosen by class and kind, so an encoder is never judged by token generation and a diffusion pipeline is never asked to chat. The image probe goes out on /v1/images/generations and never on /v1/images/edits — an edit sends a reference image, which a pipeline that cannot read one dies on rather than refusing. Starts the model's own container itself (through the same admission path a real request takes), so there is no separate 'apply first' step — reports the verbatim llama-server error and the relevant container log lines when it fails, plus a hint for the known failure modes. Loading a large model off disk can take minutes and occupies VRAM, which is why this counts as a mutating tool. For a chat model that loaded successfully, also compares the running build's /props chat_template_caps and modalities with what /v1/models derives statically for this row and lists disagreements — an empty list means the static derivation agrees with the running build; a null props means /props could not be read, which never fails the test. A chat row with a ladder tests every rung in turn instead of one: whatever is running is stopped first (refused, touching nothing, while it is still serving real requests), the base is loaded and probed, then each higher rung is climbed to and probed the same way, in order — a failure ends the run there, since nothing above a broken rung can be reached through it. The result's 'rungs' array reports each one: rung k/n, the GGUF, its context and per-slot context, how many seconds it took to become ready, and ok/error. Neither the opening nor the closing stop is forced, so a real request is never killed for this — but that means the closing stop can also be refused: an idle claim counts as 'still serving' too (a tool loop or an agent run sitting between turns), and reset_to_base: false then means the model is left up on the last rung this test reached, to be stopped by hand (or lmgw__container action=restart) rather than at the next request. Any real traffic already on the model when this runs waits out each rung's drain and reload along with it — several seconds per rung — and ends up moved to the same top rung, reprocessing its history on its next turn.

Request body required

application/json: object

model_idrequired string The local model id to load and test.
target string The model's class. Omit to find it by id; needed only when two classes share the same id. One of chat, aux, image.

Responses

StatusDescription
200 OK.
application/json
One of 5 shapes
LadderTest
Fields of LadderTest
classrequired string Always chat.
ladderrequired boolean Always true.
model_idrequired string
okrequired boolean Every tested rung passed.
reset_to_baserequired boolean The model was stopped again so the next request starts at the base;
false when other traffic kept it busy.
rungsrequired array of RungTest The rungs tested, in order; a failure ends the list.
top_rungrequired integer (uint) How many rungs the ladder has.
was_running_rungrequired integer | null The rung the model was on before the test, when it was running.
A ladder row, every rung tested in turn.
ImageTestPassed
Fields of ImageTestPassed
bytesrequired integer (uint) The first image's size in bytes.
classrequired string Always image.
endpointrequired string
latency_msrequired integer (uint64)
loadedrequired boolean Always true.
model_idrequired string
nrequired integer (uint) How many images came back.
noterequired string
okrequired boolean Always true.
output_formatrequired any What the server said it encoded; null when it says nothing.
proberequired string Always image_generation.
public_namerequired string
seedrequired integer (int64)
sizerequired string The probe's size, e.g. 256x256.
stepsrequired integer (uint32)
An image pipeline that drew.
ModelTestFailed
Fields of ModelTestFailed
classrequired string chat, aux or image. One of chat, aux, image.
code string The gateway's error code, when the model's start or the probe failed
with one of lmgw's own errors (gpu_setup when the model could not
start on the graphics card because of the computer,
vram_queue_timeout, …), as the /v1 routes answer it; absent when
the model answered with an error of its own, or with nothing usable.
container_logrequired array of string The lines of the model's container log that look like the reason.
endpoint string For an image model: the route the probe went to.
errorrequired string What went wrong.
hintrequired string What to try.
latency_msrequired integer (uint64)
loadedrequired boolean Always false.
model_idrequired string
okrequired boolean Always false.
proberequired string What was sent: generate, embed, rerank or image_generation.
public_name string For an image model: the name clients call it by.
A chat, aux or image model that did not load or did not answer.
any
any
default Error.
application/json ApiError
post/api/op/voice_generate

Render candidate voice samples with a text-to-speech model (the Voices lab)

Capability admin, open to: owner. Changes state.

One round of the Voices lab: the alias (any text-to-speech model, local or cloud) is opened once and says the same text as count candidates (4 when absent; no cap, rendered one after another), each with a seed of its own — consecutive from seed, else drawn — which reaches a local row whose engine reads one (seeds_sent). The text is text, else the language's sentence (the owner's saved one, else the built-in one). description is the voice description or speaking style (the speech route's instructions), voice the voice for a model that speaks one it is told; language goes to a local row that takes one. A configured fallback answers as for any request, and the round names who answered (answered_by, fallback_reason). The round is kept under <data_dir>/voice-lab/rounds until discarded; each candidate's url serves its audio. A failure after the first candidate ends the round there (stopped). The same function lmgw__voice_generate and POST /voice-lab/api/rounds call.

Request body required

application/json: object

aliasrequired string The text-to-speech model, e.g. 'audio/qwen3-voicedesign'.
count integer | null How many candidates, rendered one after another. Default 4. Default null.
description string | null The voice description (a voice-design model: 'a warm, calm female voice in her forties') or speaking style. Empty: none. Default null.
language string | null ISO 639-1 code (en, de): picks the sentence and is sent to a local model that takes a language. Default null.
seed integer | null The first candidate's seed; the next get seed+1, seed+2, … Empty: a random seed each. Default null.
text string | null What every candidate says. Empty: the sentence for language. Default null.
voice string | null The voice for a model that speaks one it is told. Empty: its default. Default null.
Example
{
  "alias": "audio/voicedesign",
  "count": 4,
  "description": "a warm, calm voice",
  "language": "en"
}

Responses

StatusDescription
200 OK.
application/json VoiceRound
Fields of VoiceRound
aliasrequired string The alias asked.
answered_byrequired string The alias that answered: alias, or the fallback the GPU hold (or a
busy card) handed the round to.
askedrequired integer (uint32) How many candidates were asked for.
candidatesrequired array of VoiceCandidate
created_atrequired string RFC 3339, UTC.
descriptionrequired string | null
fallback_reasonrequired string | null Why a fallback answered (hold, external_vram, …).
idrequired string The round's id, its directory's name.
languagerequired string | null
language_noterequired string | null What happened to the language when it did not reach the model as
set.
licencerequired ModelLicence | null The licence the answering row's package states, when it states one.
rowrequired VoiceRow | null The lmgw audio row behind the answering route, if it is one.
seeds_sentrequired boolean Each candidate's seed reached the model.
sent_textrequired string | null What the engine was sent instead, when lmgw's speech shaping changed
it (inline tags or characters the engine cannot say): what the
candidates say, and the transcript a saved sample gets.
shapingrequired string | null What lmgw's speech shaping changed in the request
(x-lmgw-speech's words), when it changed anything.
stoppedrequired string | null Why the round ended before asked candidates: the first failure,
or a stop (the page left, Stop, the round discarded).
textrequired string What every candidate was asked to say.
upstreamrequired string The upstream that answered.
upstream_modelrequired string The model name it was sent.
voicerequired string | null
default Error.
application/json ApiError
post/api/op/voice_sample_save

Save a Voices lab candidate to the voice library as a sample

Capability admin, open to: owner. Changes state.

Writes a round's candidate to the voice library (<audio models dir>/voices) as <name>.wav, its leading and trailing silence cut (loudness untouched), with the text it says as its transcript (the library's prompt_text) — so every cloning model can speak with it by name. How it was made (alias, the model that answered, description, voice, seed, text, language, dates, licence when known) is recorded beside it. A name the library already has is refused with name_taken and nothing is written, unless overwrite is true: then the clip of that name is replaced. The same function lmgw__voice_sample_save and POST /voice-lab/api/samples call.

Request body required

application/json: object

candidaterequired integer (uint32) The candidate's number in the round, from 1.
namerequired string The voice name: letters, digits, space, '.', '_' and '-'. A trailing .wav is dropped.
overwrite boolean Replace a sample of that name. Default false. Default false.
roundrequired string The round's id, from lmgw__voice_generate.
Example
{
  "candidate": 2,
  "name": "sample-voice",
  "round": "20260101-120000-000-abcdef"
}

Responses

StatusDescription
200 OK.
application/json VoiceSampleSaved
Fields of VoiceSampleSaved
cliprequired string The clip's file name in the library (anna.wav).
library_activerequired boolean The class's voice directory is this library, so voice names the
clip on every cloning model; otherwise it is reachable as a
voice_ref path only.
messagerequired string The outcome in a sentence.
okrequired boolean
provenancerequired VoiceProvenance
replacedrequired array of string The library files it replaced (with overwrite).
transcriptrequired string The transcript recorded for it.
voicerequired string The voice name a request uses (anna).
default Error.
application/json ApiError
post/api/op/voice_transcribe

Transcribe voice-library clips with a speech-to-text model

Capability admin, open to: owner. Changes state.

Writes a voice-library clip's transcript (the library's prompt_text, which audio.cpp hands a cloning model as reference_text when a request's voice names the clip): one clip (replaced if it had one), or every clip without one. The model is the alias given, else the setting audio.voice_transcribe_alias; it must be a speech-to-text (asr) model, wherever it runs, and so must the fallback a GPU hold or an outside-VRAM verdict hands the clip to (a configured fallback is always used; asr_required before anything is sent otherwise). The answer names the clips, their transcript lengths and the model that wrote each (a fallback named as one: answered_by, fallback_reason), not the text. The same function lmgw__voice_transcribe calls.

Request body required

application/json: object

alias string The speech-to-text model, e.g. 'audio/qwen3-asr'. Empty: the setting audio.voice_transcribe_alias.
clip string One clip: its file name (me.wav) or voice name (me). Empty: every clip without a transcript.
Example
{
  "alias": "audio/qwen3-asr"
}

Responses

StatusDescription
200 OK.
application/json VoiceTranscribed
Fields of VoiceTranscribed
already integer (uint) For the run over every untranscribed clip: how many already had a
transcript and were left alone. Absent when one clip was named.
failedrequired array of VoiceClipFailed The clips that could not be.
messagerequired string The outcome in a sentence.
okrequired boolean Always true; a clip that failed is listed in failed.
transcribedrequired array of TranscribedClip The clips transcribed, with who wrote each.
default Error.
application/json ApiError

Runtime ops

post/api/op/container

Control the per-model container runtime

Capability admin, open to: owner. Changes state.

Control the per-model container runtime: lmgw runs one podman container per loaded chat/aux/audio/image model, started on demand and stopped independently — there is no shared per-class container any more. Address one model with model=<id> (its class is found automatically from the local/aux/audio/image tables; pass target too only to disambiguate an id that exists in more than one class); address a whole group with target alone. 'start' on a model warms it (a no-op if it is already up); 'start' on a group only starts that group's warm_start-flagged models, never every configured one — starting an entire class at once can ask for more VRAM than the box has, so start any other model on demand with model=<id>. 'stop' refuses a model still serving requests unless override=true. 'restart' and 'apply' are the same operation on a single model (stop, then start with freshly rendered arguments — there is no drift concept, argv is always rendered fresh); on a group, 'apply' additionally reports the same pre-flight lmgw__local_model_check runs (missing files, spec_type mismatches) for every enabled model in scope, not only the running ones. 'logs' (model only) returns the container's recent output — with one container per model this is the only place a failed start is visible. 'status' shows, for a llama-server container, what it said about itself in GET /props at its start (llama_props: build_info, modalities, n_ctx_slot — null where the server did not say), or among its warnings why it could not.

Request body required

application/json: object

actionrequired string What to do. 'logs' requires 'model'. One of status, start, stop, restart, apply, logs.
model string Address one model by its id instead of a whole group.
override boolean Force a 'stop' that would otherwise be refused because the model is still serving requests.
tail integer Lines of container output 'logs' returns, from the end. Default 60.
target string Which group of models. Omit when 'model' is given. One of all, chat, aux, audio, image.

Responses

StatusDescription
200 OK.
application/json
One of 8 shapes
GroupApplied
Fields of GroupApplied
advisoriesrequired array of ContainerAdvisories
busyrequired array of ContainerBusy
errorsrequired array of ContainerFailure
heldrequired array of ContainerModel Stopped and not started again because the GPU hold is on.
messagerequired string
models_enabledrequired integer (uint)
models_with_advisoriesrequired integer (uint)
models_with_problemsrequired integer (uint)
noterequired string
okrequired boolean
problemsrequired array of ContainerProblems
recreatedrequired array of ContainerPort
targetrequired string
A group, action: apply.
GroupStarted
Fields of GroupStarted
already_runningrequired array of ContainerModel
errorsrequired array of ContainerFailure
heldrequired array of ContainerModel Left alone because the GPU hold is on.
noterequired string
okrequired boolean
startedrequired array of ContainerPort
targetrequired string
A group, action: start.
GroupRestarted
Fields of GroupRestarted
busyrequired array of ContainerBusy
errorsrequired array of ContainerFailure
heldrequired array of ContainerModel Left running untouched because the GPU hold would not let them start
again.
messagerequired string
okrequired boolean
restartedrequired array of ContainerPort
targetrequired string
A group, action: restart.
GroupStopped
Fields of GroupStopped
busyrequired array of ContainerBusy Still serving requests and left running; override forces them.
errorsrequired array of ContainerFailure
messagerequired string
okrequired boolean
stoppedrequired array of ContainerModel
targetrequired string
A group, action: stop.
GroupStatus
Fields of GroupStatus
okrequired boolean
runtimerequired array of RuntimeStatus The containers of the group.
targetrequired string The group asked about: all, chat, aux, audio or image.
vramrequired VramStatus The GPU ledger, whole even when one group was asked about.
A group, action: status.
ModelLogs
Fields of ModelLogs
classrequired string
containerrequired string The container's name.
logsrequired string The container's recent output.
model_idrequired string
okrequired boolean
tailrequired integer (uint) How many lines were asked for.
One model, action: logs.
ModelStatus
Fields of ModelStatus
classrequired string
enabledrequired boolean | null Null when no model with this id is configured.
enginerequired string The engine the class runs: llama-server, audio.cpp or sd-server.
idle_secondsrequired integer | null
imagerequired string | null The container image in effect.
model_idrequired string
okrequired boolean
runtimerequired RuntimeStatus | null The running container, or null when nothing has started this model.
warm_startrequired boolean | null
One model, action: status.
ModelDone
Fields of ModelDone
applied boolean apply only: whether the configuration was applied.
classrequired string
held boolean apply only: the GPU hold kept the container from starting again.
messagerequired string
model_idrequired string
okrequired boolean False when the model was still serving requests and was left
running, or could not be stopped under the hold.
port integer (uint16) The port, when the action left the container up.
running boolean apply only: whether the container is running afterwards.
One model, action: start, stop, restart or apply.
default Error.
application/json ApiError
post/api/op/hold_set

Engage or release the GPU hold

Capability admin, open to: owner. Changes state.

Engaging stops every idle local container (stopped), leaves the ones still working to the next reaper tick (draining), names the stops that failed (failed) and aborts a benchmark run in flight (benchmark_aborted, absent when none was). Asking for the state the hold is already in is not an error: nothing changes, and the answer reports the current state.

Request body required

application/json: object

activerequired boolean true engages the hold (and stops idle local containers); false releases it.

Responses

StatusDescription
200 OK.
application/json HoldSet
Fields of HoldSet
activerequired boolean Whether the hold is on now. A held model answers with its own
fallback, where one is set.
benchmark_aborted integer (int64) The id of the benchmark run that engaging the hold aborted. Absent
when no run was aborted: none was running, the hold was released, or it
was already as asked.
drainingrequired array of string The containers left running because they are still working, as
class/model; the next reaper tick stops them. When the hold was
already as asked this is the registry's own view of what is working.
failedrequired array of string The containers whose stop failed, as class/model: reason; they still
hold GPU memory.
kept_on_cpurequired array of string The containers on the CPU, left running: they use no VRAM.
messagerequired string What was done, for a person to read: the failures are in the sentence
as well as in failed.
okrequired boolean Always true; a refusal is an error answer instead.
stoppedrequired array of string The containers this call stopped, as class/model (empty when it
stopped none, and when the hold was released or already as asked).
default Error.
application/json ApiError
post/api/op/job_cancel

Cancel a running background job

Capability admin, open to: owner. Changes state.

Cancel a running background job (a download, a build run, an image pull, …) by its job id.

Request body required

application/json: object

idrequired integer The job id, from /api/jobs or the SSE jobs frame.

Responses

StatusDescription
200 OK.
application/json MessageAck
Fields of MessageAck
messagerequired string What was done, for a person to read.
okrequired boolean Always true; a failure is an error answer instead.
default Error.
application/json ApiError
post/api/op/machine_check

Check whether this computer can run local models

Capability admin, open to: owner

Whether this computer can run local models, item by item: the graphics card and its driver (the running kernel module against the driver libraries on disk, NVML read in a separate process), what lets models use the card (who owns /usr/bin/nvidia-ctk and whether lmgw could write its own CDI spec), the program that runs models (Podman), whether the model settings fit the card, free disk space and whether the engine images are downloaded. Each item has a plain sentence for the person, technical detail lines and a typed cause; the verdict is ready, needs_fix, needs_steps, needs_restart, needs_driver or cloud_only. When something can be done, the answer carries the plan: every step with the exact commands it runs as root, the full text of the files it writes, the same lines to type in a terminal, and how it is carried out (the app's button or instructions, and why). The fix itself runs only from lmgw's own app window on this computer, after the person confirms and types their password: explain the plan to them, but it cannot be run from here. When the model settings are for the other maker's card, the settings item carries an action instead: every field the switch to the settings for this card changes, as it is and as it would become, what it leaves, and the running models it stops; that switch needs no password and is the machine_settings_fit op (POST /api/op/machine_settings_fit, with confirm set to the listed changes), which is not a tool here. Without fresh this is the last result (the check runs at boot); fresh: true runs it now, joining a run already in progress that began after the call. It only reads, with the user's rights, and runs these programs: lmgw's own NVML probe (lmgw --machine-probe nvml, in a process of its own), rpm and rpmkeys queries, nvidia-ctk --version, one cache-only dnf repoquery for the toolkit's download sizes, and Podman's --version, --help, info and image exists for each engine image, and podman images; for an engine image that is not one of the engines' published images it reads its build label, or lists its ggml libraries in a throwaway container with no network and no device, to tell which card it is built for; for an engine image that is not downloaded yet it reads its registry manifest anonymously, for the download's size.

Request body required

application/json: object

fresh boolean Run the check now instead of answering the last result. Default false.

Responses

StatusDescription
200 OK.
application/json MachineCheck
Fields of MachineCheck
checked_atrequired string When it ran: UTC, YYYY-MM-DD HH:MM:SS.
failed_startrequired MachineFailedStart | null The last start of a local model on the graphics card that failed
because of this computer (the check named why), whoever asked for it:
a client, the Chat, a lab, the model's Test. None before one since
lmgw started. A surface that was told "Not now" asks again once this
is another failed start than the one it was told it beside
(machine-check design D171, D182).
headlinerequired string The verdict in one plain sentence.
itemsrequired array of MachineItem The items, in the order they are checked: graphics card and driver,
using the card for models, running models, model settings, room, the
download.
planrequired MachinePlan | null What can be done about it, when anything is to be done or offered.
verdictrequired MachineVerdict
default Error.
application/json ApiError
post/api/op/machine_settings_fit

Switch the model settings to the ones for this computer's graphics card

Capability admin, open to: owner. Changes state.

Switches each model class's image and extra podman run arguments (and the audio class's backend) to the values lmgw ships for the card fit names: amd_vulkan (llama.cpp's, audio.cpp's and stable-diffusion.cpp's Vulkan images, --device /dev/dri --group-add keep-groups --security-opt label=disable) or nvidia_cuda (lmgw's defaults). Only a class set for the other card is switched; one on the processor, one naming another CDI device and one giving models the render nodes with an image that is not lmgw's for AMD cards are left as they are (left says why). Run arguments, a class's and a model's own alike, keep every argument but the other card's flags, which are swapped for this card's (none for a model on the processor); arguments that would add the user's groups beside a group of their own are left, since Podman refuses the two together. A model's own image that is one of the engines' published images for the other card becomes this card's; either is cleared when it then equals its class's, so the model follows its class again. An image lmgw can tell is built for the other card by its build label or its libraries, and one it cannot tell, stay, named in left. Without confirm nothing is written and the answer lists what would change and the running models it concerns, as the machine check's settings item does (its action). confirm is that list of changes, as it was shown: the switch is worked out again under the settings lock and written only when it is the same list, the classes through the Settings page's own save and the models' settings in its transaction, all or nothing; otherwise nothing is written and the answer's outdated says what differs, with the switch as it is now to confirm again. After the write each running model it concerns is stopped (never forced: one answering a request keeps running with the settings from before, and the answer and the machine check say so until it stops), and the answer carries the machine check run again. Refused when this computer has no card of that maker. No password: it is an ordinary settings write.

Request body required

application/json: object

confirm array | null Write the switch: the changes of the offer being confirmed (the
settings item's action, or an answer without confirm), as they
were shown. The switch is worked out again from the settings as they
are when it is written; it is written only when that gives this same
list, and otherwise nothing is written and the answer carries the
list as it is now (outdated). Without it nothing is written, and
the answer says what the switch would change. Default null.
fitrequired SettingsFit Which card's settings to switch to.

Responses

StatusDescription
200 OK.
application/json MachineSettingsFit
Fields of MachineSettingsFit
appliedrequired boolean Whether the settings were written, or the answer only says what the
switch would change.
changesrequired array of SettingsFitChange Each field changed (or that would be), as it was and as it is. When
a confirmed list was outdated, the switch as it is now: confirm this
list to write it.
checkrequired MachineCheck | null The machine check after the write; None when nothing was written.
fitrequired SettingsFit
leftrequired array of SettingsFitLeft What was left as it is, and why.
notesrequired array of string The settings save's own notes.
outdatedrequired SettingsFitOutdated | null Set when confirm was not the switch as it is now, so nothing was
written: what differs.
runningrequired array of SettingsFitRunning The running models the switch concerns, and after a write what
happened to each.
sentencerequired string What was done, or would be, in plain sentences.
default Error.
application/json ApiError

Download ops

post/api/op/audio_catalog

Refresh the audio.cpp model catalog, or queue one package's download

Capability admin, open to: owner. Changes state.

The two catalog actions of the Audio lab, as one op: 'refresh' live-fetches audio.cpp's model_specs catalog, lists each package repo on Hugging Face once (which spec files are published — a package's unpublished_files), and persists the snapshot (the only network calls in this domain; a spec file or repo listing that fails is one of its warnings, not a failed refresh); 'download' queues the files one package lacks (family + package) through the shared Hugging Face download queue, target audio — every file for a package never downloaded, only the missing ones for one the spec grew since (the catalog's missing_files; 'complete install' in the Audio catalog). The same function lmgw__audio_catalog calls.

Request body required

application/json: object

actionrequired string 'refresh' live-fetches the audio.cpp model_specs catalog; 'download' queues the files one package lacks. One of refresh, download.
family string download only: the catalog family (e.g. 'kokoro').
package string download only: the package within that family.
Example
{
  "action": "download",
  "family": "kokoro",
  "package": "kokoro-82m"
}

Responses

StatusDescription
200 OK.
application/json
One of 2 shapes
AudioCatalogRefreshed
Fields of AudioCatalogRefreshed
familiesrequired integer (uint) How many model families the catalog holds.
fetched_atrequired string RFC 3339 time of the fetch.
messagerequired string The outcome in a sentence.
okrequired boolean Always true; a warning does not fail a refresh.
warningsrequired array of string What the refresh could not do (a spec file that did not load, a
package repository Hugging Face could not list).
action: refresh.
AudioCatalogInstall
Fields of AudioCatalogInstall
downloadsrequired array of QueuedDownload
enginerequired EngineDownload | null The audio class's image, when it is not on this machine or podman
could not say: the download fetches a missing one too, a
multi-gigabyte download of its own, and starts nothing
(EngineDownload). null when it is here.
familyrequired string
files_queuedrequired integer (uint32)
messagerequired string
okrequired boolean Always true.
packagerequired string
reporequired string
revisionrequired string The revision the files are fetched at: the commit the catalog pins
(under audio.catalog_revision = pinned), else main.
action: download.
default Error.
application/json ApiError
post/api/op/hf_add

Download a model from Hugging Face into a models directory

Capability admin, open to: owner. Changes state.

Download a model from Hugging Face into the models directory — the normal way to get a new model onto this gateway. Fetches the weights file you name (or pick by quantization) together with its multimodal projector and, for target=chat, its speculative drafter from the same directory, because a model usually needs all of them. Split GGUFs expand to every part automatically. Downloads run in the background: poll lmgw__hf_downloads with ids=<the queued ids>, then call lmgw__local_model_plan on the result. target=image downloads the stable-diffusion.cpp kinds (.safetensors, .ckpt, .pt, .pth as well as .gguf) into the image models dir and fetches no companions — an image pipeline's VAE and text encoders live in OTHER repos, so use lmgw__image_recipe_add to bring a whole family down in one call and this tool only for a single file a recipe does not cover. When the image the target class's models run in (its Settings → Runtimes Image) is not on this machine, this also starts its download, a multi-gigabyte image_pull job of its own that starts no model: 'engine' in the answer names the image and the job (the model's first start joins it rather than downloading again), or says why it could not begin or why podman could not say whether it is needed; 'engine' is null when the image is here.

Request body required

application/json: object

companions boolean Also fetch the projector beside the weights, and for target=chat the drafter (an aux row has none). Default true; set false to download only the file you named.
file string Exact path of the weights file within the repo. Omit to select by quant instead.
quant string Pick the weights file by quantization label instead of exact name, e.g. 'Q4_K_XL' or 'IQ4_XS'. See lmgw__hf_repo for what is offered.
reporequired string Repo id like 'unsloth/Qwen3.5-9B-GGUF' — owner/name only, not a full huggingface.co URL.
target string Which models directory to download into. Default 'chat'. Use 'aux' for embedding, rerank and decision models and 'image' for stable-diffusion.cpp pipeline files — a row can only address files in its own class's directory, and this is what keeps the file in the updater's view (lmgw__hf_set check_updates). One of chat, aux, audio, image.

Responses

StatusDescription
200 OK.
application/json HfAddResult
Fields of HfAddResult
companionsrequired array of HfCompanion The projector and the drafter queued beside the weights. Empty when
companions was off, when the repo has none beside that file, and for
the image target (a pipeline's components live in other repos).
dest_prefixrequired string repo/: the directory under the models dir that the repo's files land
in, with the trailing slash.
downloadsrequired array of QueuedDownload The tracked rows of the file asked for, the companions and every part
of a split GGUF, with the id each can be followed by in
GET /api/hf/downloads.
enginerequired EngineDownload | null The image target's models run in, when it is not on this machine
or podman could not say: the download fetches a missing one too, a
multi-gigabyte download of its own, and starts nothing
(EngineDownload). null when it is here.
files_queuedrequired integer (uint32) How many files went into the queue: the weights, the companions, and
every part of a split GGUF.
gguf_pathrequired string Relative GGUF path (repo/file) — feed to plan/create once done.
messagerequired string What was queued and what to do next, which depends on target.
okrequired boolean Always true; a refusal is an error answer instead.
reporequired string
targetrequired string The class whose models dir the files go to: chat | aux | audio |
image
(embed as asked is aux here).
warningsrequired array of string What to look out for in what was queued, one sentence each; empty when
nothing. Today: a shard of a sharded .safetensors is queued alone,
and stable-diffusion.cpp cannot reassemble shards.
weightsrequired string The weights file asked for: the file, or the one the quant named.
default Error.
application/json ApiError
post/api/op/hf_set

Re-fetch, cancel, untrack or check-updates on a tracked Hugging Face download

Capability admin, open to: owner. Changes state.

Manage tracked Hugging Face downloads: re-fetch one, cancel a running transfer, untrack and delete its file, or ETag-check every completed download against the hub for updates. An audio catalog file is checked and re-fetched at the revision audio.catalog_revision takes it at now: under 'pinned' the commit its audio.cpp spec pins today, else main. The answer follows the action: check_updates answers HfUpdatesChecked (how many finished downloads of the target class differ from the hub, and one sentence per file it could not ask about, in which case ok is false); redownload, cancel and delete answer a MessageAck.

Request body required

application/json: object

actionrequired string What to do. 'cancel' stops a transfer that is still running; the entry stays tracked and can be re-fetched with 'redownload'. One of redownload, cancel, delete, check_updates.
id integer Download row id from lmgw__hf_downloads. Required except for check_updates.
target string Which models directory check_updates scans. Default 'chat'. One of chat, aux, audio, image.

Responses

StatusDescription
200 OK.
application/json
One of 2 shapes
MessageAck
Fields of MessageAck
messagerequired string What was done, for a person to read.
okrequired boolean Always true; a failure is an error answer instead.
action: redownload | cancel | delete.
HfUpdatesChecked
Fields of HfUpdatesChecked
errorsrequired array of string One sentence per file the hub could not be asked about.
okrequired boolean false when a file could not be compared (errors is not empty); the
answer is still a success, for the files that could.
updates_availablerequired integer (uint64) How many finished downloads now differ from the hub's copy; each is
flagged update_available.
action: check_updates.
default Error.
application/json ApiError
post/api/op/image_recipe_add

Queue every missing component of one image recipe

Capability admin, open to: owner. Changes state.

Download every component of one shipped image pipeline and get back a PREFILLED ROW for it. The whole chain: lmgw__image_recipes to choose a key -> THIS TOOL -> lmgw__hf_downloads ids=<the queued ids> until every one says 'done' -> lmgw__image_model_set action=create with the returned 'row' (it is already in that tool's field names: model_id, files, args, modes, edit) -> lmgw__local_model_test model_id=<id> target=image. Components already on disk are skipped, not re-fetched — a VAE or text encoder shared with a pipeline you already have costs nothing. It does NOT create the row itself: the files are still transferring, and lmgw__image_model_set refuses a row whose files are not on disk, which is the check that keeps a broken row out of the table. Refuses cleanly when the image models directory is not configured, or when a component's repo is licence-gated and no Hugging Face token is set (naming the component). When the image class's image (Settings → Runtimes → Image → Image) is not on this machine, this also starts its download, a multi-gigabyte image_pull job of its own that starts no model; 'engine' in the answer names the image and the job, or says why it could not begin or why podman could not say whether it is needed, and is null when the image is here.

Request body required

application/json: object

diffusion_file string Pick a different quantization of the pipeline's diffusion model (or checkpoint) by exact filename — one of the 'alternatives' that recipe's primary component lists. Omit for the recipe's default. A name the recipe does not know is refused rather than ignored.
keyrequired string Recipe key from lmgw__image_recipes, e.g. 'z-image-turbo' or 'flux1-schnell'.

Responses

StatusDescription
200 OK.
application/json ImageRecipeAddResult
Fields of ImageRecipeAddResult
already_presentrequired array of string Components skipped because the file was already there.
already_queuedrequired array of string Components skipped because a download for them is already queued or
running — re-queueing one would flip its row back to queued under
the job that is downloading it.
display_namerequired string
downloadsrequired array of QueuedDownload
enginerequired EngineDownload | null The image class's image, when it is not on this machine or podman
could not say: the download fetches a missing one too, a
multi-gigabyte download of its own, and starts nothing
(EngineDownload). null when it is here.
files_queuedrequired integer (uint32) Components queued now (the ones that were not already on disk).
keyrequired string
messagerequired string
okrequired boolean
rowrequired ImageRecipeRow The image_model_set patch, ready to post once the downloads are done.
default Error.
application/json ApiError
post/api/op/image_recipes

List the image pipelines lmgw ships a recipe for

Capability admin, open to: owner

The image pipelines lmgw ships a recipe for — Z-Image-Turbo, FLUX.1 schnell/dev/Kontext, SDXL, Qwen-Image — and, for each, every file it needs: the Hugging Face repo, the exact filename, the size, whether the repo is licence-gated, the quantization alternatives, and whether that file is already on this box ('present') or downloading. START HERE for the image class. A stable-diffusion.cpp pipeline is NOT one weights file: it is a diffusion model (or an all-in-one checkpoint) plus a VAE plus one to three text encoders, and they live in DIFFERENT repos under different owners, so there is nothing lmgw__hf_repo can show you that describes a whole pipeline. Each recipe also carries the 'args' the family wants and a VRAM note — measured where a spike measured it, and the word 'unmeasured' where none did. Takes no arguments; the list is compiled in, so this makes no network call. Then: lmgw__image_recipe_add.

Request body required

application/json: object

Responses

StatusDescription
200 OK.
application/json ImageRecipes
Fields of ImageRecipes
hf_token_setrequired boolean A Hugging Face token is configured, so a gated component is reachable.
models_dirrequired string The image class's models dir; empty means the class is unconfigured and
nothing can be downloaded or found.
models_dir_missingrequired boolean True when models_dir is empty — the one refusal the UI can show
before the user clicks anything.
next_steprequired string What to call next, for a caller that has no dashboard (the tool plane's
rule: a result names the tool that follows it).
recipesrequired array of ImageRecipe
upscalersrequired ImageUpscalers The upscalers (chat-media-tools design §9): the shipped ESRGAN models
and the files the image models dir's upscalers/ holds.
default Error.
application/json ApiError
post/api/op/image_upscaler_add

Queue a shipped ESRGAN upscaler into the image models dir's upscalers/

Capability admin, open to: owner. Changes state.

Downloads one of the upscalers image_recipes lists under upscalers.shipped into upscalers/<file> of the image models dir — not the <owner>/<repo>/<file> layout of hf_add — because sd-server finds upscalers at the top level of that one directory, which every image row reads. A file already there or already downloading is not queued again. An image model's server sees the file from its next start; image__upscale and the Chat card's Upscale then offer it by its file stem. Refused when the image models dir is not configured.

Request body required

application/json: object

keyrequired string Upscaler key from upscalers.shipped, e.g. 'realesrgan-x4plus'.

Responses

StatusDescription
200 OK.
application/json ImageUpscalerAddResult
Fields of ImageUpscalerAddResult
already_presentrequired boolean
already_queuedrequired boolean
download QueuedDownload The download queued now; None when the file is already there or
already on its way.
keyrequired string
messagerequired string
okrequired boolean
default Error.
application/json ApiError
post/api/op/model_find

Find a model on Hugging Face by its name, sized to this computer's card

Capability admin, open to: owner

Finds a model by the name someone said ('qwen 3.6'), a Hugging Face address (a repo, a file, a download link, also inside pasted text) or owner/repo, and picks one model and one file of it that fits this computer's graphics card. Names are searched as typed, with no aliases: numbers are written as digits ('gemma 4', not 'gemma four'). It asks Hugging Face's model search twice (every repo, and GGUF repos, each the hub's first page by downloads); keeps the repos whose name has every query word; takes the originals, not uploads of them; ranks them by matched words, weights of their own, likes and downloads; and walks the top author's originals of the top one's kind to the first whose upload has a file that fits by its size (an upload by the maker first, gated ones last); when none fits, the card is the one closest to fitting (nothing_fits). It reads no file header, so the card's marks are by size ('fits_by_size'): lmgw__hf_repo with fit=true on the card's upload reads the header (1 to 16 MiB) and checks exactly. A search usually costs 3 to 8 Hugging Face requests: the two searches, two per model the walk reads (its uploads, a tree) plus one per gated or unanswered upload or further tree page, and the display name; lmgw sets no bound of its own, the hub's limit is the bound. hub_budget carries the hub's own RateLimit and RateLimit-Policy figures, near when fewer requests are left than this answer took; a limit used up before anything was found answers rate_limited with the seconds to the reset, and one used up partway keeps what was found, with a note. An address on another host, or a Hugging Face page that isn't a model's (not_a_model), is answered without asking anyone. A private repo's card has no share link. others, did_you_mean and the card's other_uploads are windows of 10 by default (each one's *_total and *_more say how many there are); the *_offset and *_count arguments ask for another window, which runs the same search again. next_cursor continues the search with the hub's next pages (answer 'more': the lists only).

Request body required

application/json: object

cursor string | null A previous answer's next_cursor: the search's next pages. Default null.
did_you_mean_count integer (uint32) How many entries of did_you_mean to answer with (default 10). Default 10.
did_you_mean_offset integer (uint32) The first entry of did_you_mean to answer with (default 0). Default 0.
other_uploads_count integer (uint32) How many entries of the card's other_uploads to answer with (default 10). Default 10.
other_uploads_offset integer (uint32) The first entry of the card's other_uploads to answer with (default 0). Default 0.
others_count integer (uint32) How many entries of others to answer with (default 10). Default 10.
others_offset integer (uint32) The first entry of others to answer with (default 0). Default 0.
query string A model's name as people say it ('qwen 3.6'), a Hugging Face address, or owner/repo. Default "".
Example
{
  "query": "qwen 3.6"
}

Responses

StatusDescription
200 OK.
application/json ModelFind
Fields of ModelFind
answerrequired FindAnswer
cardrequired ModelCard | null None: see answer.
did_you_meanrequired array of ModelChoice Partial matches (D13), by matched words: the window asked for.
did_you_mean_morerequired integer (uint32)
did_you_mean_totalrequired integer (uint32)
hub_budgetrequired HubBudget | null
next_cursorrequired string | null The search's next page, for cursor.
notesrequired array of string What the walk passed over and why, and what couldn't be read (the
fold).
othersrequired array of ModelChoice The other originals found, by rank (D15): the window the arguments
asked for (D142).
others_morerequired integer (uint32)
others_totalrequired integer (uint32) How many other originals the search found, and how many come after
others.
queryrequired string
sentencerequired string What the person reads for answer.
default Error.
application/json ApiError
post/api/op/model_fit_again

Fit a chat or aux model's context to the graphics card again

Capability admin, open to: owner. Changes state.

The model editor's "Fit again" (find-a-model design D26): the fit of the row's own parameters on the graphics card as it is now, searched up to the model's trained context, with the row itself left out of what is beside it. The measure is the one the row's fit note records, else beside what runs now. Without confirm nothing is written and the answer lists the changes a save makes: the context, and for an aux row an ubatch and a batch it ties to the context. confirm is that list as it was shown: the fit is taken again, and the list is saved when the context it sets still fits the card now and the row's parameters are still the ones it was made from; else nothing is written and outdated is true with the new changes. A save writes the row through its class's own update and renews the row's fit note (none when the whole trained context fits). Nothing is started. The note itself is on the row's read (fit_note).

Request body required

application/json: object

confirm array | null Save the changes the answer without it listed, as they were shown.
The fit is taken again first; when it gives other changes nothing
is written and the answer lists the new ones to confirm. Default null.
model_id string The row's id in its class (model_id, not the public name). Default "".
target string chat or aux. Default "".

Responses

StatusDescription
200 OK.
application/json ModelFitAgain
Fields of ModelFitAgain
changesrequired array of FitChange What a save changes; empty when the row is as the fit says.
fitrequired FileFit The fit of the row's own parameters on the card now, the row left
out of what is beside it (D55).
measurerequired FitMeasure The measure fitted to: the note's, else beside what runs (D120).
model_idrequired string
noterequired FitNote | null The row's note as it is now (after a save, the new one); None
when its context isn't a fit's shorter one.
outdatedrequired boolean The confirmed changes weren't the fit's any more: nothing was
written, and changes are the new ones.
savedrequired boolean The changes were written.
sentencerequired string What the person reads.
targetrequired string
default Error.
application/json ApiError
post/api/op/model_get

Get a model from Hugging Face and set it up, sized to the graphics card

Capability admin, open to: owner. Changes state.

Get a llama.cpp model from Hugging Face and set it up, sized to this machine's graphics card: the one call after choosing a file (lmgw__model_find, or lmgw__hf_repo with fit=true for the exact pick). It downloads the weights with the companions lmgw__hf_add would fetch (the one projector, and for chat the drafter; a file already downloaded isn't fetched again), then, in the background, plans the file on disk, fits it to the graphics card and creates the row: when the card fits a shorter conversation than the model's trained context, the row takes the largest that fits and keeps a note of the fit (an aux row is planned again at that context, its ubatch and batch with it). A row that already serves the file is the answer instead of a second one: then row_id is set, nothing is queued and there is no get. It never starts the model. The answer has the get_id (lmgw__model_get_status reads how it stands and, at the end, the row it made or why it stopped), the download ids for lmgw__hf_downloads, the model id and the name it will answer to, and the free-disk check (a warning, never a block). A second call for the same file joins the first. A failed get is started again by calling this again: it fetches only what isn't there yet. It survives a restart: the downloads go on from where they stopped and the setup follows.

Request body required

application/json: object

filerequired string Exact path of the weights file in the repo; for a split GGUF its first part.
measure string What the context is fitted to: 'beside' what runs on the card now (the default), or the 'whole_card' with nothing else on it. One of beside, whole_card.
model_id string The model's id. Absent: the repo's name in lower case without a trailing -GGUF. A name a row or an alias already holds on /v1 gets -2, -3 and so on; one an upstream passes through to its own models is refused, naming that upstream.
reporequired string Repo id like 'unsloth/Qwen3.5-9B-GGUF' — owner/name only.
target string The class to set it up in. Absent: the file's header decides (an embedder, a reranker or a decision model is aux, read from the header before the download, 1 to 16 MiB). One of chat, aux.

Responses

StatusDescription
200 OK.
application/json ModelGetStarted
Fields of ModelGetStarted
companionsrequired array of HfCompanion The projector (D121) and, for chat, the drafter.
diskrequired DiskRoom The free-disk check (D125).
downloadsrequired array of QueuedDownload Every file of the get with its download row, the weights' parts and
the companions alike; a file already on disk is listed with its row
as done and isn't fetched again.
enginerequired EngineDownload | null The image the class's models run in, when it isn't on this machine
(machine check §5); null when it is here.
filerequired string
get_idrequired integer | null The get (model_get_status reads it); None when a row already
serves the file.
job_idrequired integer | null The model_get job (kind model_get), on the jobs feed; None
when a row already serves the file (row_id).
joinedrequired boolean A get of this file was already under way, and this answer is that
one's: nothing new was queued.
measurerequired FitMeasure
messagerequired string
model_idrequired string The id the row will have (D28); the job may still suffix it when
another row takes the name before it is created, and
model_get_status then says the one it got.
public_namerequired string The name it will answer to on /v1 (D27): the chat class's public
name, or the aux prefix's.
reporequired string
row_idrequired integer | null A row of the class that already serves the file (D87), by its id in
its class's table: that row is the answer, nothing was queued and no
get runs. model_id and public_name are its own.
targetrequired string chat or aux.
default Error.
application/json ApiError
post/api/op/model_get_status

How a Get it stands, and the model it set up

Capability admin, open to: owner

One get by the get_id model_get answered (find-a-model design §6.2): its state (running, done, failed, canceled), a running get's stage (downloading, paused, setting up, ready) with each file that waits and why (waiting: metered, not_started, or other with the download's note) and its bytes so far, every file's download row, why a failed get stopped and what to do, and a finished get's result: the row it created or found, its context, the fit that context comes from and the note the row keeps. Reads only.

Request body required

application/json: object

get_id integer (int64) The get, as lmgw__model_get answered it. Default 0.

Responses

StatusDescription
200 OK.
application/json ModelGetStatus
Fields of ModelGetStatus
done_bytesrequired integer (uint64) The bytes of its files here so far, and their total when every
size is known (a running get's).
downloadsrequired array of QueuedDownload Every file of the get with its download row as it is now.
errorrequired string | null Why a failed get stopped, and what to do.
filerequired string
get_idrequired integer (int64)
job_idrequired integer | null The job that runs or ran it.
model_idrequired string The id the row has, or will have: settled again when it is created
(D28).
public_namerequired string The name it answers to on /v1.
reporequired string
resultrequired ModelGetDone | null A finished get's result.
row_idrequired integer | null The row it set up or found, in its class's table.
stagerequired ModelGetStage | null Where a running get is; None once it ended, or before its job
reported.
staterequired ModelGetState
targetrequired string chat or aux.
total_bytesrequired integer | null
waitingrequired array of GetWaiting Each file that waits with nothing transferring it, and why (a
running get's); empty when none waits.
default Error.
application/json ApiError

Settings ops

post/api/op/realtime_budget

Size the realtime voice cascade against the GPU

Capability admin, open to: owner

What the configured GET /v1/realtime cascade is expected to hold on the GPU, stage by stage — turn detection (CPU), the chat model, speech to text, the barge-in word check when it uses another model, text to speech — with their sum, the VRAM headroom, what lmgw may use (vram.budget_mb or the GPU's total) and what other programs hold now. Each figure is the one admission charges: a chat row's GGUF weights + KV cache + compute buffers, an audio row's learned residency or, before it has one, its on-disk size; a cloud stage holds nothing, and a stage with no figure is listed as unknown. An argument left out is the saved setting, so a draft can be sized before it is saved. Starts nothing.

Request body required

application/json: object

asr_alias string | null "" falls back to the Chat's transcription model, as a session does. Default null.
barge_in_check string | null words | duration; with duration there is no word check to size. Default null.
barge_in_check_alias string | null "" = the ASR alias. Default null.
default_model string | null Default null.
tts_alias string | null Default null.

Responses

StatusDescription
200 OK.
application/json RealtimeBudget
Fields of RealtimeBudget
capacity_bytesrequired integer | null What lmgw may plan against: vram.budget_mb, or the devices' real
total. None when admission has nothing to measure against.
capacity_sourcerequired string Where the capacity comes from, or why there is none.
headroom_bytesrequired integer (uint64) vram.headroom_mb: what admission keeps free above a model's
estimate when it starts one.
needed_bytesrequired integer (uint64) total_bytes + headroom_bytes: what the last of the cascade's models
to start needs free.
outside_bytesrequired integer | null GPU memory held now by programs lmgw cannot free (games, the
desktop), measured per process. None when it cannot be measured.
outside_noterequired string | null Why outside_bytes is missing, when it is.
stagesrequired array of RealtimeBudgetStage Turn detection, chat, ASR, the word check (when it uses another
model), TTS — in that order.
summaryrequired string The verdict in a sentence.
total_bytesrequired integer (uint64) The known figures summed, each local model once.
unknownrequired array of string The stages whose figure is unknown; while any is listed the total is
a lower bound.
verdictrequired string fits | tight (fits what lmgw may use, not beside what other
programs hold now) | too_large | unknown.
default Error.
application/json ApiError
post/api/op/settings_set

Change gateway settings

Capability admin, open to: owner. Changes state.

Change gateway settings. Pass only the fields to change. Never settable here, by any caller: the settings that decide who may reach lmgw and with what credential — auth_enabled, self_admin, bind_addr, agent_origin_suffix and devices (the device listener and how long a pairing token and a device's certificate live). They change on Settings in the dashboard; a call that names one is refused, naming it, and changes nothing. Also left to the dashboard: the HF/update/forge tokens and the builds directory.

Request body required

application/json: object

audio_catalog_revision string | null What an audio catalog download (lmgw__audio_catalog action=download) takes when the audio.cpp spec pins a package to a commit: 'pinned' (default) fetches every file of the package at that commit, the one the spec was tested with; 'latest' always takes main. A package the spec does not pin takes main either way. lmgw__hf_set check_updates and redownload follow the same rule for catalog files, at the pin the spec names now. A pin that cannot be fetched fails the download — lmgw never falls back to main on its own. Read back as audio.catalog_revision in lmgw__settings. Default null.
auth_enabled boolean | null Require a gateway API key on /v1/* and /mcp. Taken by this op only:
the lmgw__settings_set tool refuses it, as it refuses every setting
that decides who may reach lmgw. Default null.
build_update_check_hours integer | null How often lmgw checks whether a container build's branch or PRs have moved since its last verified run, in hours: 0 to 8760 (a year). 0 turns the periodic check off (a check on demand still works). Default 6. Default null.
chat_archive_days integer | null Archive a Chat thread this many days after its last activity (a new message or a settings change; pinning does not count). 0 disables auto-archive. Archiving is reversible: a pin, a restore, or sending into the thread brings it back. Default null.
chat_feed_keepalive_max_s integer | null The longest keep-alive, in seconds, a feed may ask for itself (GET /chat/api/feed?keepalive_s=, as a phone holding its feed in the background does), at least 1 and at most 32767 (about nine hours, the longest Linux accepts for a TCP keep-alive timer). A request past it is refused naming this setting. Between events a feed sends only its keep-alive, so this bounds how long a feed whose device vanished silently stays open. Applies to feeds opened after the change. Default null.
chat_feed_keepalive_s integer | null Seconds between the Chat feed's keep-alive comments, at least 1 and at most chat_feed_keepalive_max_s; said in the feed's hello as keepalive_s. A feed that asks for its own keeps that instead, and an open feed keeps the interval it opened with. Default null.
chat_feed_live_buffer integer | null Live Chat feed events (turn.*, voice.*, hold) held for a client that reads slower than they happen, at least 1 and at most 65536 (the buffer is allocated whole). One that falls further behind gets a fresh state frame naming this setting. Default null.
chat_feed_page_size integer | null Records the Chat feed reads per query while a client catches up, at least 1 and at most 10000. Bounds memory, not delivery: every record is sent. Default null.
chat_feed_retention_days integer | null Keep the Chat change feed's records (GET /chat/api/feed) this many days. 0 keeps every record. A client away longer resumes with a resync that names this setting. Default null.
chat_kb_budget_tokens integer | null Tokens of knowledge-base excerpts one Chat turn may carry; a thread can override it. Must be above 0 (default 4000). Default null.
chat_media_defaults MediaDefaults | null The image and audio tools' default models, as a JSON-encoded object with only the fields to change: generate, edit, speak, transcribe (each a name of that tool's model enum, as tools/list shows it) and voice (a voice of the default speech model). '' clears a field: no default, the calling model must pick. With a default, a call may leave out model (and voice) and the tool's description names the default. A Chat folder and a thread can override each field; /mcp, /v1/responses and agent runs use these. A default whose model is switched off or deleted later is no default (not replaced), and lmgw__settings reads it back as stored. Default null.
chat_pdf_mode string | null How a text PDF attached in Chat starts out: 'text' (the extracted text, default), 'images' (every page as an image; needs a vision model) or 'ask' (the chip starts unset and Send waits for a choice). Default null.
chat_profile ProfileChoice | null The personality profile a new Chat thread starts with: a profile id (lmgw__settings chat_profile says the one now; the Chat's GET /chat/api/profiles lists them), or '' for none ("Default", the default). A thread in a folder whose defaults name a profile takes that one instead; existing threads are not changed. An unknown id is refused. Deleting the profile empties this setting.
chat_purge_days integer | null Delete an archived, unpinned Chat thread this many days after it was archived. 0 keeps archived threads forever. The clock is when it was archived, not when it was last active, so a thread archived by hand gets the full period too. Default null.
chat_read_aloud boolean | null Read Chat replies aloud as they stream (default false): the page that sends a turn (send, edit, regenerate, continue) asks for its speech, which starts at the first clause while the text still streams. Tables and fenced code are not read; each is announced ('Code block, rust.', 'Table.'). A thread can override it; voice mode speaks on its own and ignores it. Default null.
chat_speech_style string | null The speech instructions the Chat's text-to-speech model gets (a speaking style, or a voice description for a voice-design model). '' = realtime.speech_instructions. Global like that setting, it stands back for a voice-design row that describes its own voice. A thread can override it, '' included (no style for that thread), and a thread's own style wins over the row's description. Default null.
chat_stt_alias string | null The Chat's speech-to-text alias: dictation, voice mode (a realtime session bound to the thread), and the transcript of an audio attachment when the thread's model takes no audio itself. Must be a model whose capability task is 'asr'. '' = realtime.asr_alias; realtime falls back the other way (a /v1/realtime session uses this alias while realtime.asr_alias is empty), so either one serves both. A thread's own override wins over both. With none of the three set the thread cannot transcribe: dictation and voice mode are refused (asr_not_configured), and an audio attachment its model cannot hear blocks Send. The audio goes where the alias routes, its GPU-hold fallback included; the model that answered is named. Default null.
chat_system_prompt string | null The system prompt a new Chat thread starts with; each thread keeps its own copy, so existing threads are not changed. {{model}} and {{date}} in a thread's prompt become its model alias and today's date when a message is sent. Passing the built-in text (see lmgw__settings chat_system_prompt while chat_system_prompt_is_builtin is true) returns to the built-in default; '' starts new threads with no system prompt. Default null.
chat_tts_alias string | null The Chat's text-to-speech alias, for read-aloud and voice mode. Must be a model whose capability task is 'tts' or 'vdes'. '' = realtime.tts_alias (realtime never falls back to this one). A thread can override it. It loads on first use (a speaker press, a turn read aloud, entering voice mode), never when a chat opens. Default null.
chat_turn_detection string | null How voice mode in the Chat detects the end of a turn: 'semantic_vad' (Silero VAD plus Smart Turn, default), 'server_vad' (silence only) or 'push_to_talk' (hold Space or the Talk button). It is the mode the panel starts in; the panel's Auto / Push to talk switch changes it for that session only (a thread at push_to_talk switched to Auto uses semantic_vad). A thread can override it. Default null.
chat_voice string | null The Chat's voice, a voice of its text-to-speech model (chat_tts_alias, else realtime.tts_alias). '' = none named: realtime's voice chain decides (realtime.default_voice, then the TTS row's default preset). Not checked on save: a name the model does not know fails the speech with voice_not_found. A thread can override it; a thread that speaks with another model than the Chat's does not take it. Each thread also keeps its own TTS seed, so a model that designs or draws its voice keeps one voice per thread. Default null.
chat_voice_audio_input string | null Whether a voice-mode turn goes to the chat model as audio: 'off' (default: the model reads the speech-to-text transcript) or 'on' (experimental). Under 'on' a turn goes as audio when the model that answers it — the thread's model, or the fallback a GPU hold, a benchmark run, an outside-VRAM verdict or a candidate alias's walk hands it to — is a chat model whose input_modalities include audio and lmgw can send it audio (OpenAI-compatible, llama.cpp and Gemini upstreams; not Anthropic), without a context guard (a ladder or a guarded shared KV pool), and the thread's knowledge bases are not in auto mode; otherwise it goes as the transcript, and the thread's voice_resolved.audio_input says why. A model whose capabilities lmgw cannot read counts as not taking audio: to make it hear, give its alias (or local row) a capabilities override with task chat and input_modalities text and audio — a passthrough model needs an alias for that. A configured fallback is always used, wherever it runs, and hears the turn when it takes audio. The speech-to-text model still transcribes every turn — with either value, so a cloud speech-to-text model still receives each turn's audio: the transcript is what is stored (no audio is), and the reply is held until it is in. Dictation stays on speech-to-text. A thread can override it. Default null.
chat_voice_language string | null The language the user speaks in the Chat, an ISO 639-1 code such as 'de' or 'en' (case folded; anything else is refused): the speech-to-text model is told it where it takes a language, and the prompt says the user speaks it. Replies are in chat_voice_reply_language, which falls back to this one. '' = none: the ASR detects, and without a reply language the reply follows the user's language; it does not fall back to a realtime setting. A thread can override it (voice.language). Default null.
chat_voice_reply_language string | null The language Chat replies are in, an ISO 639-1 code such as 'en' (case folded; anything else is refused): the model is asked to answer in it, and the text-to-speech model speaks it where it takes a language (a thread's voice_resolved.language_notes say where a model does not). '' = the language the user speaks (chat_voice_language), so one language set there drives both. Set both to speak one language and hear replies in another. It also picks the words read-aloud and voice mode announce a skipped code block or table with (en, de, fr, es, it; English otherwise). A thread can override it (voice.reply_language). Default null.
devices DevicesSettingsPatch | null Settings → Network & access → Devices: the device link's bounds (a
pairing token's lifetime, the certificates' validity, the
connection timeouts, the failed-enrolment rate), each refused by
name outside its range. Taken by this op only: like bind_addr, an
access setting the lmgw__settings_set tool refuses.
fallback_on_external boolean | null Fall back when VRAM outside lmgw's control is short (vram.fallback_on_external): when a local model does not fit because games, browsers or other apps hold GPU memory lmgw cannot free, its configured fallback answers at once instead of queueing. Contention between lmgw's own models still queues. On by default; turn off on shared-memory systems (APUs), where GPU memory is host RAM that grows and shrinks with everything else running. Default null.
max_body_mb integer | null Largest request body accepted on the JSON /v1 routes, in MiB. 0 = unlimited. Raise it when clients inline large base64 images or documents; over it they get a 413 with code 'body_limit'. Applies to the next request, no restart. /v1/audio/* and /v1/tasks/* are unbounded regardless. Default null.
quota_recheck_seconds integer | null Seconds before an upstream remembered out of quota is asked again, when its answer carried no Retry-After (at least 1). Until then a model with a fallback on it answers with the fallback. Default null.
realtime RealtimeSettingsPatch | null GET /v1/realtime's settings, as a JSON-encoded object with only the fields to change, named as lmgw__settings reports them under 'realtime' (its two default_instructions_* read-outs are not settable; lists and maps are replaced whole). The cascade: default_model (a chat alias), asr_alias (task asr; '' = the Chat's transcription model), tts_alias (task tts or vdes), default_voice, model_map and voice_map ({client name: alias or voice}). Speech: speech_instructions (the TTS's style, or a voice-design row's description, while a session sends none; '' = none), tag_hint (an audio response's prompt says what square brackets do: the sounds the TTS makes, or delivery cues such as [laughing] for a style or passthrough TTS that renders no tags, e.g. Qwen3 CustomVoice; a cloud TTS only when its alias declares capabilities.speech.instructions 'style'). default_instructions: the built-in text (default_instructions_builtin) returns to the built-in prompt, '' turns it off. Turn detection: threshold, prefix_padding_ms, silence_duration_ms, semantic_vad_engine ('smart_turn' | 'server_vad'), semantic_vad ({high|medium|low: {threshold, floor, max_wait_ms, silence_duration_ms}}, a row or field left out keeps its value), semantic_floor_window_ms. Barge-in: barge_in_min_ms, barge_in_guard_ms, post_interrupt_silence_ms, half_duplex, echo_tail_ms, barge_in_check ('words' | 'duration'), backchannel_words, barge_in_check_scripts, barge_in_check_timeout_ms, barge_in_check_alias (task asr; '' = the session's own). Output: output_lead_ms, synthesis_ahead_s, longest_pause_ms (0 = keep the engine's silences), warm_on_connect. Limits: max_message_mb, max_frame_mb (not both 0), ping_interval_s. WebRTC calls, both applied at the next start: webrtc_enabled, webrtc_port (null = the HTTP port's number, 0 = chosen by the OS); their audio, applied to the next call: webrtc_reorder_ms (0 = no wait, at most 40950), webrtc_commit_window_ms, webrtc_output_kbps (6 to 510). Refused, naming the field: an alias of the wrong task, a semantic_vad row that cannot run, an unknown script, a value out of its range. Example: '{"tts_alias": "audio/pocket-tts", "warm_on_connect": true}'.
retention_days integer | null Days of request logs to keep. 0 = forever. Default null.
retention_max_rows integer | null Hard row cap on the request log. 0 = unlimited. Default null.
sampling_alias string | null Default model alias answering MCP sampling requests. Default null.
update_check_enabled boolean | null Poll the package registry for new lmgw releases. Default null.

Responses

StatusDescription
200 OK.
application/json SettingsSaved
Fields of SettingsSaved
changedrequired array of string The settings the call wrote, in the order the op applies them, by the
patch's field names (retention_days, jobs_retention_days, …); a
section's field is named under it (realtime.asr_alias).
messagerequired string What was done, for a person to read; it says so when the rest of the
configuration could not be reloaded after the save.
okrequired boolean Always true; a refusal is an error answer instead.
default Error.
application/json ApiError
post/api/op/settings_set_full

Change gateway settings, including the fields the self-admin tool excludes

Capability admin, open to: owner. Changes state.

Sparse patch over the whole Settings struct — the dashboard's Settings page save, including the self-admin mode, the bind address, the HF/update/forge tokens, the builds directory and the four container classes' definitions, none of which the self-admin tool plane exposes. Secrets: a non-empty value replaces, an empty one keeps the stored value, and the matching clear_* flag erases it. A change of self_admin applies to every paired device at once, since it caps each device's own level: a device whose admin tools may now do more or less gets a state event on its change feed saying so, its realtime sessions that carry the lmgw label list it again, and a turn still running is refused its next write tool when the level was lowered. Set to off, every device stops seeing the Chat threads and folders that carry the self-admin toolset: its change feed receives them as deleted, its turns on them stop, and its realtime sessions bound to one close with 4004; raised from off, a device whose own level is above off receives them as created.

Request body required

application/json: object

agent_origin_suffix string | null The DNS suffix a service agent's UI is served under:
http://<id>.<agent_origin_suffix>:<bind port>/. Refused when it would
shadow a name the gateway itself answers on, and a **change** stops
every running app container. Default null.
agent_script_image string | null The stock image a manifest's script step runs in. Empty restores the shipped default rather than leaving a script
step with no image to run in. Default null.
audio AudioSettingsPatch | null
auth_enabled boolean | null Default null.
aux_router AuxRouterSettingsPatch | null
bind_addr string | null Default null.
build_update_check_hours integer | null Build update check interval in hours; 0 = off, at most 8760. Default null.
builds_dir string | null Where container builds keep their files. ""
clears it back to the default; otherwise an absolute path. Default null.
chat_archive_days integer | null Archive an idle Chat thread this many days after its last activity.
0 disables auto-archive. A folder's own archive_days overrides it
for the threads in that folder, and an ongoing conversation's current
thread is never archived. Default null.
chat_feed_keepalive_max_s integer | null The longest keep-alive a feed may ask for itself
(GET /chat/api/feed?keepalive_s=), from 1 to 32767 seconds (the longest Linux accepts for a TCP
keep-alive timer). Default null.
chat_feed_keepalive_s integer | null Seconds between the Chat feed's keep-alive comments, from 1 to
chat_feed_keepalive_max_s. Default null.
chat_feed_live_buffer integer | null Live events the Chat feed holds for a slow client before it sends it
a fresh state instead, from 1 to 65536. Default null.
chat_feed_page_size integer | null Records the Chat feed reads per query while a client catches up,
from 1 to 10000. Default null.
chat_feed_retention_days integer | null Keep the Chat change feed's records this many days; 0 keeps every
record. A client away longer resumes with a resync. Default null.
chat_kb_budget_tokens integer | null Tokens of knowledge-base excerpts one Chat turn may carry; above 0. Default null.
chat_media_defaults MediaDefaults | null The image and audio tools' default models: only the fields given
change, "" clears one. Each name must be one of its tool's
model choices (GET /chat/api/media/defaults). Default null.
chat_pdf_mode string | null How a text PDF attached in Chat starts out: text | images | ask. Default null.
chat_profile ProfileChoice | null The personality profile new Chat threads start with: a profile id,
or "" for none. An unknown id is refused.
chat_purge_days integer | null Delete an archived, unpinned Chat thread this many days after it was
archived. 0 keeps archived threads forever. A folder's own
purge_days overrides it for the threads in that folder. Default null.
chat_read_aloud boolean | null Read every Chat reply aloud as it streams; a thread can override it. Default null.
chat_speech_style string | null What the Chat's voice is told (a speaking style, or a voice-design
description); "" = realtime.speech_instructions. Default null.
chat_stt_alias string | null The Chat's speech-to-text alias; "" = realtime.asr_alias. Default null.
chat_system_prompt string | null The system prompt new Chat threads start with. The built-in text
returns to the built-in default (and follows it from then on); ""
starts new threads with no system prompt. Default null.
chat_tts_alias string | null The Chat's text-to-speech alias (task tts or vdes); "" =
realtime.tts_alias. Default null.
chat_turn_detection string | null How voice mode detects the end of a turn: semantic_vad |
server_vad | push_to_talk. Default null.
chat_voice string | null The Chat's voice, a voice of the Chat's text-to-speech model; "" =
none named, so realtime's chain decides (realtime.default_voice,
then the model's default). Default null.
chat_voice_audio_input string | null off | on: whether a voice turn goes to the chat model as audio
when the model that answers it takes audio input, wherever it runs
(experimental); a thread can override it. Default null.
chat_voice_language string | null The language the user speaks, an ISO 639-1 code the speech-to-text
model is told; "" = none. Default null.
chat_voice_reply_language string | null The language replies are in, an ISO 639-1 code: the model answers in
it and the text-to-speech model speaks it; "" = the spoken one. Default null.
clear_forge_tokens array | null Hosts whose forge token to erase. Default null.
clear_hf_token boolean | null Default null.
clear_update_token boolean | null Default null.
container_prefix string | null Podman container name prefix for the per-model container runtime. Default null.
currency string | null The label every amount on the Usage page is shown under. One currency,
no conversion. Default null.
devices DevicesSettingsPatch | null The device link's bounds (Settings → Network & access → Devices) —
the same patch the settings_set op takes, with the same checks.
docs_embed_batch integer | null Default null.
docs_fetch_delay_ms integer | null Default null.
docs_ingest_reply_tokens integer | null Default null.
docs_rerank_model string | null Default null.
docs_search DocsSearchPatch | null
forge_tokens object | null Forge tokens to set, by host. Secrets like
hf_token: a non-empty value replaces that host's token, an empty one
keeps it, and a host not named is untouched. Default null.
global_budget_micro integer | null Spend ceiling across every key, in currency micro-units. 0 = none. Default null.
global_budget_period string | null Default null.
hf_token string | null Default null.
image ImageSettingsPatch | null
jobs_max_rows integer | null Default null.
jobs_retention_days integer | null Default null.
local_reference_alias string | null Alias whose price answers the local/cloud counterfactual.
"" clears it back to "no reference configured". Default null.
max_body_mb integer | null Default null.
mcp McpSettingsPatch | null The device MCP host link's limits (Settings → MCP).
quota_recheck_seconds integer | null Seconds before an upstream remembered out of quota is asked again,
when its answer carried no Retry-After; at least 1. Default null.
realtime RealtimeSettingsPatch | null GET /v1/realtime's settings — the same patch
settings_set takes, with the same checks.
responses_max_chains integer | null Default null.
responses_max_tool_calls integer | null Default null.
responses_retention_hours integer | null Default null.
responses_store boolean | null Default null.
responses_timeout_seconds integer | null Default null.
retention_days integer | null Default null.
retention_max_rows integer | null Default null.
router RouterSettingsPatch | null
sampling_alias string | null Default null.
self_admin string | null Default null.
update_check_enabled boolean | null Default null.
update_token string | null Default null.
usage_retention_months integer | null Keep hourly usage rollups this many months. 0 = forever. Default null.
vram VramSettingsPatch | null

Responses

StatusDescription
200 OK.
application/json MessageAck
Fields of MessageAck
messagerequired string What was done, for a person to read.
okrequired boolean Always true; a failure is an error answer instead.
default Error.
application/json ApiError
post/api/op/update_check

Check whether a newer lmgw release is available

Capability admin, open to: owner

Poll the package registry now for a newer lmgw release than the one running, regardless of the periodic update-check setting.

Responses

StatusDescription
200 OK.
application/json MessageAck
Fields of MessageAck
messagerequired string What was done, for a person to read.
okrequired boolean Always true; a failure is an error answer instead.
default Error.
application/json ApiError

Tool ops

post/api/op/mcp_server_set

Create, update, delete, enable, disable or test a southbound MCP server

Capability admin, open to: owner. Changes state.

Every action answers the server's id and a sentence. test connects to the server and also answers how many tools it lists (tool_count); a server that cannot be reached is an error answer instead.

Request body required

application/json: object

action string What to do. 'test' connects once and reports the tool count. Default "".
allow_sampling boolean | null Let this server ask lmgw for LLM completions (MCP sampling). Default null.
args string | null Command arguments, one per line. Default null.
autostart boolean | null Connect at startup instead of on first use. Default null.
command string | null Executable for stdio transport (bare, or inside the container). Default null.
container_image string | null Podman image to run the stdio server isolated in. Recommended. Default null.
cwd string | null Working directory for a bare stdio subprocess. Default null.
enabled boolean | null Whether the server is aggregated at all. Default null.
env string | null Environment for the server process, KEY=VALUE one per line. Default null.
extra_run_args array | null Extra 'podman run' arguments, one per entry. Default null.
headers string | null HTTP headers for http/sse, 'Name: Value' one per line. Default null.
id integer | null MCP server id. Required except on create. Default null.
idle_seconds integer | null Disconnect after this many idle seconds. 0 = stay connected. Default null.
name string | null Display name. Default null.
sampling_alias string | null Model alias to answer this server's sampling requests with. Default null.
timeout_ms integer | null Timeout in ms for each tool call and for the connect handshake. Not bounded by it: the pull of a container image before the handshake, and the whole start of a stdio server without a container image (an npx or uvx command may install its package first). Default 60000. Default null.
tool_prefix string | null Namespace for this server's tools: prefix 'gh' exposes 'gh__search'. 'lmgw' is reserved. Default null.
transport string | null How to reach the server. Required on create. Default null.
url string | null Endpoint URL for http/sse transports. Moving it needs headers, as text, in the same call when the server holds any. Default null.

Responses

StatusDescription
200 OK.
application/json McpServerSaved
Fields of McpServerSaved
idrequired integer (int64) The row's id: the new row's for create.
messagerequired string What was done, for a person to read.
okrequired boolean Always true; a refusal is an error answer instead.
tool_count integer (uint64) test: how many tools the server listed. Absent for every other
action.
default Error.
application/json ApiError
post/api/op/tool_set

Enable or disable one discovered tool

Capability admin, open to: owner. Changes state.

Flip a tool's per-tool switch. Disabling requires the tool to be offered right now — a typo would otherwise persist a switch for a name that does not exist. Enabling never checks, which is how a stale row is cleared.

Request body required

application/json: object

enabledrequired boolean Whether the tool is offered to callers.
namerequired string The fully-qualified tool name (e.g. 'gh__search'), as /api/tools lists it.
Example
{
  "enabled": false,
  "name": "gh__search"
}

Responses

StatusDescription
200 OK.
application/json MessageAck
Fields of MessageAck
messagerequired string What was done, for a person to read.
okrequired boolean Always true; a failure is an error answer instead.
default Error.
application/json ApiError

Key ops

post/api/op/device_ca_rotate

Replace lmgw's device CA and reset every device

Capability admin, open to: owner. Changes state.

Replace lmgw's device CA: a new key under a new wrapping key and a new certificate replace tls/ca.key and tls/ca.crt, and the old key is not kept. Every enrolled device loses its key and certificate (its policy kept) and must be paired again with a new token; what each holds open closes at once, and every pairing token alive ends, since its link pins the old CA. The server certificates are issued anew. Answers DeviceCaRotated with the new fp and the devices reset.

Request body required

application/json: object

Responses

StatusDescription
200 OK.
application/json DeviceCaRotated
Fields of DeviceCaRotated
devices_resetrequired array of string The devices reset, by name without device:: each lost its key and
its certificate and waits for **New token…**.
fprequired string The new CA's pin: sha256: and the hex SHA-256 of its
SubjectPublicKeyInfo, what every new pairing link carries.
messagerequired string What was done, for a person to read.
okrequired boolean Always true; a refusal is an error answer instead.
default Error.
application/json ApiError
post/api/op/device_confirm

Confirm a device's enrolment

Capability admin, open to: owner. Changes state.

Confirm the key a device enrolled, after comparing the code the Keys list shows (pairing.confirm_code) with the one the device shows, and sending that code: the key waiting for the confirmation must have it, else 409 confirm_code_mismatch and nothing changes (a card showing an earlier enrolment confirms nothing). Until then every request of that key is refused 403 device_unconfirmed; from now on it is served. A key that waited beside one the device kept (a re-pair that kept the current key) replaces it: the kept key ends, and what it holds open closes. Answers DeviceConfirmed with the code confirmed and whether it replaced a kept key.

Request body required

application/json: object

confirm_coderequired string The code the device shows, compared with the Keys list's pairing.confirm_code: eight hex digits, e.g. 7F3A-91C2 (either case; the hyphen and spaces optional). The key waiting for the confirmation must have it, or nothing is confirmed (409 confirm_code_mismatch).
idrequired integer Device id, from the Keys table.
Example
{
  "confirm_code": "7F3A-91C2",
  "id": 12
}

Responses

StatusDescription
200 OK.
application/json DeviceConfirmed
Fields of DeviceConfirmed
confirm_coderequired string The confirmation code of the key confirmed, 7F3A-91C2: the one the
device shows, and the one the call sent.
idrequired integer (int64) The device row's api_keys.id.
messagerequired string What was done, for a person to read.
namerequired string device:<name>.
okrequired boolean Always true; a refusal is an error answer instead.
replacedrequired boolean Whether the confirmed key replaced one the device kept until now (a
re-pair that kept the current key, §5.2): the kept key ended, and
what it held open closed.
default Error.
application/json ApiError
post/api/op/device_token

Give a device a new pairing token (re-pair it)

Capability admin, open to: owner. Changes state.

A new one-time pairing token for a device row, replacing its earlier one; the row keeps its id, policy and history. end_current: true ends the key the device holds now (a lost or stolen device): what it holds open closes at once, as on a disable, and its requests are refused until the new token enrols. Left out or false, the current key works on: a new key the token enrols waits beside it for its own confirmation (device_confirm), which ends the current key (a new phone), and the same key enrolling again gets a fresh certificate and keeps its confirmation (a renewal before the old one lapses). A key that waited from an earlier token, and the contested mark, go with the new token. local_only and urls replace the row's, which a device paired before TLS has none of. Answers DevicePaired with the new link, as key_create does. Refused 409 device_listener_off while the device listener does not serve.

Request body required

application/json: object

end_current boolean End the device's current key now: its connections close and its requests are refused until the new token enrols (a lost or stolen device). Default false: the current key works until the new token's enrolment replaces it.
idrequired integer Device id, from the Keys table.
local_only boolean Replace the device's "this computer" flag; default: as it is.
urls array of string Device keys: the device's lmgw URLs, https base URLs of the device listener in the order the device tries them (a LAN or WireGuard address, or a name; IP addresses and names of letters, digits and hyphens, which every server certificate carries). Default: for this computer https://127.0.0.1:<device port>; for another device every network address of this machine on the device port.
Example
{
  "end_current": false,
  "id": 12
}

Responses

StatusDescription
200 OK.
application/json DevicePaired
Fields of DevicePaired
fprequired string sha256: and the hex SHA-256 of the device CA's SubjectPublicKeyInfo:
the link's fp, which the device's enrolment pins.
idrequired integer (int64) The device row's api_keys.id; a new token keeps it.
linkrequired string lmgw-pair:?v=2&name=…&url=…[&url=…]&fp=sha256:…&token=lmgw-enrol-…:
carries the one-time pairing token to the device. Secret while its
token lives: shown once, never logged.
local_onlyrequired boolean Paired as "this computer": the device reaches lmgw on a loopback
address only.
messagerequired string What was done, for a person to read: what the device does next, and
whether the device listener reaches it from where it is.
namerequired string device:<name>.
okrequired boolean Always true; a refusal is an error answer instead.
token_expires_atrequired string When the pairing token lapses (RFC 3339, UTC): devices.token_minutes
after it was minted.
urlsrequired array of string The device's lmgw URLs: https base URLs of the device listener, in
the owner's order, as the link carries them and enrolment answers
them.
default Error.
application/json ApiError
post/api/op/device_token_end

End a device's pairing token

Capability admin, open to: owner. Changes state.

End a device's pairing token while it lives (the QR card's close): its link pairs nothing any more, a used one included, whose own key can then no longer ask for its enrolment's answer again. Answers DeviceTokenEnded, ended false when no token was alive.

Request body required

application/json: object

idrequired integer Device id, from the Keys table.

Responses

StatusDescription
200 OK.
application/json DeviceTokenEnded
Fields of DeviceTokenEnded
endedrequired boolean Whether a token was alive and is ended now; false when none was
(never issued, lapsed, or ended already).
idrequired integer (int64) The device row's api_keys.id.
messagerequired string What was done, for a person to read.
namerequired string device:<name>.
okrequired boolean Always true; a refusal is an error answer instead.
default Error.
application/json ApiError
post/api/op/key_create

Create a client, owner or device API key

Capability admin, open to: owner. Changes state.

Create a new API key: a client key (default), an owner key or a device key. The plaintext is returned once for a client key; an owner key's plaintext stays retrievable with key_reveal for as long as the row exists. A client key may be created with its alias scope, MCP tool scope and device-tools grant already set (scope_mode, scope_patterns, tool_scope_mode, tool_scope_patterns, device_tools — the same fields and rules as key_set); an owner key refuses them. A device key (kind 'device', named device:<name>) pairs one client app: it is created with its whole policy — the scopes, the device-tools grant, budget, limits and expiry key_set takes — an optional hosts_label, an optional self_admin level (off by default), local_only (paired as this computer) and urls (its lmgw URLs on the device listener; proposed when left out). It holds no key yet: it answers DevicePaired {id, name, link, urls, local_only, token_expires_at, fp}, where link is lmgw-pair:?v=2&name=…&url=…&fp=…&token=…, carrying a one-time pairing token that lapses after devices.token_minutes. The device enrols its own key with it on POST /devices/enrol and is served once the owner confirms its code (device_confirm). Refused 409 device_listener_off while the device listener does not serve. A device holds the Chat API on top of a client key's inference, and nothing of the admin plane. A client or owner key answers KeyCreated ({id, name, key}).

Request body required

application/json: object

budget_micro integer Device keys: the budget in currency micro-units, 0 for none (the default).
budget_period string Device keys: the budget's period. Default 'month'. One of day, month, total.
concurrency_limit integer Device keys: concurrent requests, 0 for no limit.
device_tools array of string Client and device keys: the device-hosted labels whose tools the key reaches (e.g. ["kai"] for Kai desktop's tools), whatever tool_scope_mode says; the tool scope then filters which of those tools it sees, as it does any server's. Without it no key reaches another device's hosted tools, whatever its tool scope names. Any label a device could host is taken (letters, digits, '_' and '-', no '__', no trailing '_', none of lmgw's own namespaces), hosted now or not. Default none; refused for an owner key.
expires_at string Device keys: YYYY-MM-DD (the whole of that day) or an RFC3339 timestamp. At that moment the device's open connections end.
hosts_label string Device keys: the label (tool prefix) the device may host MCP tools under. Unique among the MCP servers' prefixes and names, and not one of lmgw's own namespaces.
kind string Default 'client'. One of client, owner, device.
local_only boolean Device keys: paired as "this computer" — the device reaches lmgw on a loopback address only. Default false.
namerequired string Display name for the new key. The server adds the kind's prefix: a device named desktop is listed as device:desktop.
note string Device keys: a free-text note.
rpm_limit integer Device keys: requests per minute, 0 for no limit.
scope_mode string Client and device keys: which model aliases the key may ask for. Default 'all'. One of all, allow, deny.
scope_patterns string Newline-delimited * globs over alias names, for scope_mode allow/deny.
self_admin string Device keys: the device's level of lmgw's admin tools. read_only reads lmgw's configuration and state; full also changes it, which includes registering programs that run on the gateway's machine as the lmgw user (an MCP server's command, containers, agents, builds). Above off the device sees and uses the Chat threads and folders that carry the self-admin toolset (lmgw), in text and in voice, and its tool scope takes in the lmgw label; the self-admin level in Settings caps what the tools may do, and Admin Chat stays hidden from every device. Below full (after that cap) it reads those threads and sends to them, but does not attach the toolset to a thread or folder, change such a thread's settings or messages, nor such a folder's defaults (403 chat_toolset_needs_full); at full it may. Default off. Refused for any other kind of key. One of off, read_only, full.
tool_scope_mode string Client and device keys: which MCP tools the key may see and call. Default 'all'. One of all, allow, deny.
tool_scope_patterns string Newline-delimited * globs over exposed tool names (e.g. docs__*, github__search), for tool_scope_mode allow/deny.
tpm_limit integer Device keys: tokens per minute, 0 for no limit.
urls array of string Device keys: the device's lmgw URLs, https base URLs of the device listener in the order the device tries them (a LAN or WireGuard address, or a name; IP addresses and names of letters, digits and hyphens, which every server certificate carries). Default: for this computer https://127.0.0.1:<device port>; for another device every network address of this machine on the device port.
Example
{
  "name": "ci-bot",
  "tool_scope_mode": "allow",
  "tool_scope_patterns": "docs__*"
}

Responses

StatusDescription
200 OK.
application/json
One of 2 shapes
KeyCreated
Fields of KeyCreated
idrequired integer (int64) The new key's api_keys.id.
keyrequired string The key. Secret. A client key's is shown here and nowhere else (only
its hash is stored); an owner key's stays readable with key_reveal.
messagerequired string What was done, for a person to read.
namerequired string The key's name; an owner key's carries the owner: prefix the server
writes.
okrequired boolean Always true; a refusal is an error answer instead.
kind: client (or key, or none) and kind: owner.
DevicePaired
Fields of DevicePaired
fprequired string sha256: and the hex SHA-256 of the device CA's SubjectPublicKeyInfo:
the link's fp, which the device's enrolment pins.
idrequired integer (int64) The device row's api_keys.id; a new token keeps it.
linkrequired string lmgw-pair:?v=2&name=…&url=…[&url=…]&fp=sha256:…&token=lmgw-enrol-…:
carries the one-time pairing token to the device. Secret while its
token lives: shown once, never logged.
local_onlyrequired boolean Paired as "this computer": the device reaches lmgw on a loopback
address only.
messagerequired string What was done, for a person to read: what the device does next, and
whether the device listener reaches it from where it is.
namerequired string device:<name>.
okrequired boolean Always true; a refusal is an error answer instead.
token_expires_atrequired string When the pairing token lapses (RFC 3339, UTC): devices.token_minutes
after it was minted.
urlsrequired array of string The device's lmgw URLs: https base URLs of the device listener, in
the owner's order, as the link carries them and enrolment answers
them.
kind: device.
default Error.
application/json ApiError
post/api/op/key_delete

Revoke an API key

Capability admin, open to: owner. Changes state.

Delete a key by id. Deleting the dashboard's own owner key is allowed and means "closed": the next start seeds it again, disabled, until it is enabled — the credential handed out until then is gone. Deleting a key ends what it holds open at once, as disabling it does.

Request body required

application/json: object

idrequired integer Key id, from the Keys table or /api/usage/keys.

Responses

StatusDescription
200 OK.
application/json MessageAck
Fields of MessageAck
messagerequired string What was done, for a person to read.
okrequired boolean Always true; a failure is an error answer instead.
default Error.
application/json ApiError
post/api/op/key_reveal

Show an owner key's stored plaintext

Capability admin, open to: owner

The stored plaintext of one owner-kind key. A client key is hashed and shown only once at creation, so there is nothing to reveal for it; a device authenticates with a key of its own that never leaves it (device_token pairs it again); an agent token is read from the agent's own page instead.

Request body required

application/json: object

idrequired integer Owner key id, from the Keys table.

Responses

StatusDescription
200 OK.
application/json KeySecret
Fields of KeySecret
idrequired integer (int64) The key's api_keys.id.
keyrequired string The key, in the clear. Secret.
messagerequired string What was done, for a person to read; after a rotation it also says when
the configuration could not be reloaded.
namerequired string The key's name.
okrequired boolean Always true; a refusal is an error answer instead.
default Error.
application/json ApiError
post/api/op/key_rotate

Mint a new plaintext for an owner key, invalidating the old one

Capability admin, open to: owner. Changes state.

Replace an owner key's hash and plaintext in one write, so the old value stops working the moment the new one is live. A disabled owner:self-admin key stays disabled after rotation — the plane stays closed. What the old value holds open ends at once, as on a disable: realtime sessions close with 4003, Chat streams end with an error frame whose code is revoked, the change feed with a revoked event, and /mcp notification streams end. A device row is refused: it holds no secret of lmgw's making, and pairs again with device_token. Answers KeySecret ({id, name, key}).

Request body required

application/json: object

idrequired integer Owner key id, from the Keys table.

Responses

StatusDescription
200 OK.
application/json KeySecret
Fields of KeySecret
idrequired integer (int64) The key's api_keys.id.
keyrequired string The key, in the clear. Secret.
messagerequired string What was done, for a person to read; after a rotation it also says when
the configuration could not be reloaded.
namerequired string The key's name.
okrequired boolean Always true; a refusal is an error answer instead.
default Error.
application/json ApiError
post/api/op/key_set

Change a key's policy — scope, budget, rate limits, expiry

Capability admin, open to: owner. Changes state.

The settable half of one key's policy. Sparse like every other patch: a field left out keeps the value the row already has. The other half of a key's policy is derived (an agent token's scope and enabled flag are written by lmgw from the agent's manifest and row) and is refused here rather than accepted and silently taken back by the next resync. A client or device key's device_tools names the device-hosted labels whose tools it reaches (e.g. ["kai"]), whatever its tool scope's mode, which then filters those tools as any server's; [] clears it, and a label no device hosts yet is taken. A device key also takes hosts_label ("" clears it), urls (its lmgw URLs, which every server certificate carries from the next connection on) and self_admin, its level of lmgw's admin tools: off, read_only or full, capped by the self-admin level in Settings; what the device sees follows the capped level. Raised above off (under a self-admin level above off), the device's change feed receives the threads and folders with the self-admin toolset as created; set to off, as deleted, its Chat turns on such a thread stop, and its realtime sessions bound to such a thread close with 4004. Lowered to read_only, a turn still running is refused its next write tool. On any change its change feed sends a state event with self_admin, what its admin tools may do now, and its realtime sessions that carry the lmgw label list it again. Disabling a key of any kind, or its expires_at passing, ends what it holds open at once: its realtime sessions close with 4003, its Chat streams end with an error frame whose code is revoked, its change feed with a revoked event, and its /mcp notification stream ends.

Request body required

application/json: object

budget_micro integer | null Default null.
budget_period string | null Default null.
concurrency_limit integer | null Default null.
device_tools array | null Client and device keys: the device-hosted labels whose tools the key
reaches (e.g. ["kai"] for Kai desktop's tools), whatever the tool
scope's mode; the tool scope then filters which of those tools it
sees, as it does any server's. Without it no key reaches another
device's hosted tools, whatever its tool scope says. Any label a
device could host is taken, hosted now or not; [] clears it. Default null.
enabled boolean | null Default null.
expires_at string | null YYYY-MM-DD — which means the **whole** of that day, the same reading
expiry enforcement applies — or an RFC3339 timestamp. "" clears it. Default null.
hosts_label string | null Device keys only: the label the device may host MCP tools under.
"" clears the grant. Default null.
id integer (int64) Default 0.
note string | null Default null.
rpm_limit integer | null Default null.
scope_mode string | null Default null.
scope_patterns string | null Default null.
self_admin AdminLevel | null Device keys only: the device's level of lmgw's admin tools — off,
read_only or full. Above off it uses the Chat threads and
folders with the self-admin toolset and the lmgw label in its tool
scope; what the tools may do is this level capped by the self-admin
level in Settings. Default null.
tool_scope_mode string | null The MCP tool scope: the same modes and glob syntax, over exposed tool
names. Default null.
tool_scope_patterns string | null Default null.
tpm_limit integer | null Default null.
urls array | null Device keys only: the device's lmgw URLs, https base URLs of the
device listener in the order the device tries them. Every server
certificate carries their hosts from the next connection on, and the
device reads the list at its next enrolment. Default null.

Responses

StatusDescription
200 OK.
application/json KeySaved
Fields of KeySaved
changedrequired array of string The fields the call changed (enabled, scope_mode, budget_micro,
…), in the order the op checks them; empty when every field sent
already read that way and nothing was written.
idrequired integer (int64) The key's api_keys.id.
messagerequired string What was done, for a person to read.
namerequired string The key's name.
okrequired boolean Always true; a refusal is an error answer instead.
default Error.
application/json ApiError

Usage & pricing ops

post/api/op/price_delete

Delete one price row

Capability admin, open to: owner. Changes state.

404 not_found for an id no price row has.

Request body required

application/json: object

idrequired integer Price row id, from lmgw__prices.

Responses

StatusDescription
200 OK.
application/json IdAck
Fields of IdAck
idrequired integer (int64) The row's id, as the call named it.
okrequired boolean Always true; a refusal is an error answer instead.
default Error.
application/json ApiError
post/api/op/price_set

Set a manual price for one alias or upstream model, in one billable unit

Capability admin, open to: owner. Changes state.

unit says what is counted: per_mtok (the default) takes price_in, price_out and the two cache rates, per 1M tokens; per_audio_minute, per_mchar, per_image and per_request take one price, per minute of input audio, per 1M input characters, per generated image and per answered request. A scope holds one row per unit, and a request costs the sum of every unit priced for it; a manual row wins over a catalog row of the same scope and unit. service_tier (default standard) is the OpenAI price tier the row is for: an OpenAI platform answer is priced with the rows of the tier it reported, and a tier with no row leaves it unpriced with a price_note, never priced at standard.

Request body required

application/json: object

note string Free-text note, e.g. where this number came from.
price number Every unit but per_mtok: its one rate — per_audio_minute per minute of input audio, per_mchar per 1M characters of input text, per_image per generated image, per_request per answered request.
price_cache_read number per_mtok only: cache-read price per 1M tokens. Omit to bill at price_in.
price_cache_write number per_mtok only: cache-write price per 1M tokens. Omit to bill at price_in.
price_in number per_mtok only: input price per 1M tokens.
price_out number per_mtok only: output price per 1M tokens.
scope_keyrequired string The alias name for scope_kind=alias, or '<upstream_id>:<upstream_model_id>' for scope_kind=upstream_model — /api/upstream-models lists existing scope_keys.
scope_kind string What scope_key names. Default 'alias'. One of alias, upstream_model.
service_tier string The OpenAI service tier the price is for. Default standard, the one tier every other provider has. An OpenAI platform answer is priced with the rows of the tier it reported (default is standard, priority is fast); a tier with no row leaves it unpriced, never priced at standard. Part of the row's key: a flex row stands beside the standard one. One of standard, flex, fast, ultrafast, scale.
unit string What the price counts. Default per_mtok (tokens). A row's unit is part of its key: setting another unit adds a row beside the existing one rather than changing it. One of per_mtok, per_audio_minute, per_mchar, per_image, per_request.
Example
{
  "price_in": 3.5,
  "price_out": 10.5,
  "scope_key": "my-alias",
  "scope_kind": "alias",
  "unit": "per_mtok"
}

Responses

StatusDescription
200 OK.
application/json PriceSaved
Fields of PriceSaved
okrequired boolean Always true; a refusal is an error answer instead.
scope_keyrequired string The alias name, or <upstream_id>:<upstream_model_id>; trimmed.
scope_kindrequired string alias or upstream_model: what the row prices.
service_tierrequired string The row's OpenAI service tier (standard when the call named none).
sourcerequired string Always manual: the op writes no other source.
unitrequired string The row's billable unit (per_mtok when the call named none).
default Error.
application/json ApiError
post/api/op/prices_sync

Re-sync every enabled upstream's advertised catalog prices

Capability admin, open to: owner. Changes state.

Re-read every enabled upstream's model catalog and upsert its advertised prices (source=catalog) into the price table: the token rates (unit per_mtok, per 1M tokens, cache read and write included) and, beside a usable token row, a per-request fee (unit per_request). A model that advertises no price gets no row — never a zero, which would read as an authoritative price and be wrong downward. Never touches a manual row (lmgw__price_set), which always wins over a catalog row for the same scope and unit. A catalog per_request row whose fee the catalog no longer publishes is removed. Takes effect immediately, no restart. Reports, per upstream and in total: rows written, rows_removed (those fee rows), models with no advertised price, and not_synced — each advertised price field lmgw has no unit for (image, web_search, …) with how many models publish it, counted rather than silently dropped.

Request body required

application/json: object

Responses

StatusDescription
200 OK.
application/json PriceSyncSummary
Fields of PriceSyncSummary
not_syncedrequired object The upstreams' not_synced, summed per field.
rows_removedrequired integer (uint) The upstreams' rows_removed, summed.
rows_writtenrequired integer (uint)
unpriced_modelsrequired integer (uint)
upstreamsrequired array of UpstreamPriceSync
default Error.
application/json ApiError

Stored-response ops

post/api/op/response_chain_delete

Delete every stored response of one conversation chain

Capability admin, open to: owner. Changes state.

Delete every stored response sharing one chain_id.

Request body required

application/json: object

chain_idrequired string The stored-response chain to delete, from /api/responses.

Responses

StatusDescription
200 OK.
application/json MessageAck
Fields of MessageAck
messagerequired string What was done, for a person to read.
okrequired boolean Always true; a failure is an error answer instead.
default Error.
application/json ApiError
post/api/op/responses_gc

Evict stored responses by the retention settings, or clear all of them

Capability admin, open to: owner. Changes state.

Evict stored responses now: 'rules' (default) applies the retention settings (responses_retention_hours, responses_max_chains); 'all' clears every stored response regardless of age.

Request body required

application/json: object

scope string 'rules' (default) evicts by the retention settings; 'all' clears every stored response. One of rules, all.
Example
{
  "scope": "rules"
}

Responses

StatusDescription
200 OK.
application/json MessageAck
Fields of MessageAck
messagerequired string What was done, for a person to read.
okrequired boolean Always true; a failure is an error answer instead.
default Error.
application/json ApiError

Backends & build ops

post/api/op/build_check_merge

Check whether a build's extras merge cleanly onto its ref, without building

Capability admin, open to: owner. Changes state.

Check whether a build's extras merge cleanly onto its ref, without building: fetches the ref and every extra into lmgw's git pool, merges them in order in a throwaway worktree with the same code a run uses, and reports per extra: merged, already_in_base, merged_upstream (the forge says the PR is merged, so it is skipped), squash_applied (no shared history — applied as a squash) or conflict (with the conflicting files). ok=true when nothing conflicts. Takes seconds on a warm pool; the first fetch of a large repository downloads it. Listed with the writes because it downloads repositories to disk and runs git on this machine.

Request body required

application/json: object

id integer | null The build to check (lmgw__builds). Default null.
spec BuildSpecInput | null Default null.

Responses

StatusDescription
200 OK.
application/json CheckMergeReport
Fields of CheckMergeReport
base_sharequired string
okrequired boolean true when every extra merged cleanly (no conflict step).
stepsrequired array of CheckMergeStep
default Error.
application/json ApiError
post/api/op/build_env

What the build editor needs when it opens

Capability admin, open to: owner

Responses

StatusDescription
200 OK.
application/json BuildEnv
Fields of BuildEnv
arch_autorequired array of string The host GPUs' unique compute_cap values, for an arch of "auto".
builds_dirrequired string
builds_dir_free_bytesrequired integer | null Free space on the filesystem of builds_dir (or of its nearest
existing ancestor), for the editor's "free disk next to the last run's
footprint" (a warning, never a block). None when it could not
be read.
builds_dir_warningrequired string | null Set when builds_dir is on tmpfs — a dev instance must move it
before it can run builds.
cuda_defaultrequired string DEFAULT_CUDA_VERSION: 13.0.0, prefilled unless the build
overrides it.
driver_cuda_maxrequired string | null The driver's max supported CUDA version, for the "asks for more than
the driver supports" warning.
git_okrequired boolean Whether a working git was found.
repo_presetsrequired array of RepoPreset
default Error.
application/json ApiError
post/api/op/build_get

One build's detail plus a page of its run history

Capability admin, open to: owner

One build's row plus a page of its runs, newest first. limit is the page size (absent means every run); before is an exclusive run-id cursor.

Request body required

application/json: object

before integer | null Default null.
id integer (int64) Default 0.
limit integer | null Default null.

Responses

StatusDescription
200 OK.
application/json BuildGetResponse
Fields of BuildGetResponse
morerequired boolean
runsrequired array of BuildRun
usage_error string As usage_error of the builds response, for view.used_by.
viewrequired BuildView
default Error.
application/json ApiError
post/api/op/build_promote

Move a build's moving tag to one of its runs ("Make current")

Capability admin, open to: owner. Changes state.

Request body required

application/json: object

run_id integer (int64) Default 0.

Responses

StatusDescription
200 OK.
application/json PromoteResponse
Fields of PromoteResponse
from_imagerequired string | null None when nothing held the moving tag before (a build's first
promotion).
moving_tagrequired string
to_imagerequired string
used_byrequired array of ImageUse
default Error.
application/json ApiError
post/api/op/build_resolve

Preview what an unsaved build spec resolves to, without building

Capability admin, open to: owner

What a spec resolves to right now — commits, tags — fetched but not built. The build editor's "Resolve" button.

Request body required

application/json: object

spec BuildSpecInput Default {"arch":null,"backend":"cuda","build_args":"","ccache":true,"ccache_max_size":"10G","cpus":null,"cuda_version":null,"dockerfile":null,"edits":null,"engine":"llama","extras":[],"forge":"plain","keep_layers":false,"keep_runs":null,"name":"","notes":"","ref":"","repo_url":"","slug":"","target":null}.

Responses

StatusDescription
200 OK.
application/json ResolvedPreview
Fields of ResolvedPreview
base_sharequired string
build_argsrequired array of array Extra --build-arg KEY=VALUE pairs, in order.
build_numberrequired integer | null rev-list --count <base> — llama engines only; None for
audio/sdcpp.
dockerfilerequired string
edit_outcomesrequired array of EditApplied How each of edits fared against the resolved Dockerfile, in the same
order — which matched and how often. Checked against the **base**'s
Dockerfile (a preview merges nothing), so an extra that changes the
Dockerfile can still move a run's result.
editsrequired array of BuildEdit The preset's edits for the resolved Dockerfile, or the build's own
explicit list — each already carries its role.
immutable_tagrequired string
moving_tagrequired string
profilerequired string The label of the matched Dockerfile profile.
targetrequired string
warningsrequired array of string E.g. the build asks for a newer CUDA than the driver supports.
default Error.
application/json ApiError
post/api/op/build_run

Start a build run

Capability admin, open to: owner. Changes state.

Start a run of a build: fetch its ref and extras, merge, podman build, verify the image on the GPU, and — when verification passes — move the build's moving tag to it. Returns job_id and run_id at once; the run takes minutes (a cold llama.cpp CUDA build about 6, a cached rebuild about 2). Follow it with lmgw__build_log run_id=<run_id> and lmgw__builds id=<build id> until live_job_id is null, then read the run's status. One run per machine builds at a time; a queued one shows phase 'waiting'. If the exact inputs were already built and verified, the run ends 'up_to_date' without building (rebuild=true builds anyway). Nothing running is restarted: models whose image names the moving tag (used_by on lmgw__builds) keep the old image until recreated with lmgw__container model=<id> action=apply — then lmgw__local_model_test proves the new build serves. Cancel from the dashboard's Jobs.

Request body required

application/json: object

id integer (int64) The build to run (lmgw__builds). Default 0.
rebuild boolean Build even when these exact inputs were already built and verified, pulling newer base images. Default false. Default false.

Responses

StatusDescription
200 OK.
application/json BuildRunStarted
Fields of BuildRunStarted
job_idrequired integer (int64)
run_idrequired integer (int64)
default Error.
application/json ApiError
post/api/op/build_run_log

Read a byte-offset or tail chunk of a run's log

Capability admin, open to: owner

A chunk of a run's log (at most 1 MiB per call), from a byte offset, or its last tail lines — not both. The reply's next_offset continues a following call.

Request body required

application/json: object

offset integer (uint64) Default 0.
run_id integer (int64) Default 0.
tail integer | null

Responses

StatusDescription
200 OK.
application/json RunLogChunk
Fields of RunLogChunk
donerequired boolean
next_offsetrequired integer (uint64)
textrequired string
default Error.
application/json ApiError
post/api/op/build_set

Create, update, delete or duplicate a container build definition

Capability admin, open to: owner. Changes state.

Create, update, delete or duplicate a container build — the definition of an engine image lmgw builds from git (see lmgw__builds). create: name a slug and either a preset (official = ggml-org/llama.cpp, ik = ik_llama.cpp, audio = audio.cpp, sdcpp = stable-diffusion.cpp; the list with their repos is 'repo_presets' in lmgw__builds) or engine + repo_url + ref; everything else has a working default (CUDA, the preset's CUDA version, arch auto-detected from this machine's GPUs, the preset's Dockerfile and edits, ccache on, keep every run). update is partial: pass only what changes. Empty strings mean 'auto' for cuda_version, arch, dockerfile, target and cpus. duplicate copies id under slug/name (default '<slug>-copy'); it is the quick way to get 'official-master' and 'official-master-pr16391' side by side. delete removes the definition (its run history stays) and, with delete_images=true, its images where nothing uses them — the answer lists what was removed and what was kept, and why. A run in progress blocks delete. Every field is checked and a refusal names it. Custom Dockerfile edits are dashboard-only. Building a PR runs that PR's build code on this machine (rootless podman, no GPU).

Request body required

application/json: object

action BuildSetAction What to do. Default "create".
delete_images boolean On delete: also remove this build's images that nothing uses. Default false. Default false.
id integer | null The build (lmgw__builds). Required except on create. Default null.
name string | null Display name. Default: the slug. On duplicate: the copy's name. Default null.
slug string | null The image tag: lowercase letters, digits, '.', '_', '-' (e.g. 'official-master'). Fixed once the build has a run. On duplicate: the copy's slug. Default null.
spec BuildSpecInput | null Default null.

Responses

StatusDescription
200 OK.
application/json BuildSetResponse
Fields of BuildSetResponse
buildrequired Build | null
keptrequired array of KeptImage
notesrequired array of string What a create / update saved without being able to check — today
a cpus podman (or the kernel's CPU list) could not be asked about,
which is then passed as set. Empty otherwise.
removed_cachesrequired array of string
removed_imagesrequired array of string
default Error.
application/json ApiError
post/api/op/build_updates_check

Check now whether a build's branch or PRs have moved

Capability admin, open to: owner

Ask the remotes now for one build (id), or every build and every registry image in use. A build with no succeeded or unverified run has nothing to compare with.

Request body required

application/json: object

id integer | null Default null.

Responses

StatusDescription
200 OK.
application/json BuildUpdatesResponse
Fields of BuildUpdatesResponse
updatesrequired array of BuildUpdateEntry
default Error.
application/json ApiError
post/api/op/build_verify

Re-run the GPU verify checks for a built-but-unverified run

Capability admin, open to: owner. Changes state.

Request body required

application/json: object

run_id integer (int64) Default 0.

Responses

StatusDescription
200 OK.
application/json VerifyReport
Fields of VerifyReport
devicesrequired array of string Devices the --list-devices (or engine equivalent) probe reported.
gpu_verifiedrequired boolean The device probe matched the build's backend (the success
pattern). false under GPU hold or a CUDA OOM while probing —
"not GPU-verified", not "broken".
help_okrequired boolean The --help probe parsed cleanly.
notesrequired array of string
default Error.
application/json ApiError
post/api/op/builds

List every container build, with its newest run and update badge

Capability admin, open to: owner

Container builds: lmgw can build its own llama.cpp / ik_llama.cpp / audio.cpp / stable-diffusion.cpp server images from git — a repository and ref, plus PRs or other branches merged on top — and tags each result 'localhost/lmgw-<engine-repo>:<slug>' (the MOVING tag, which follows the build's last verified run) and '…:<slug>-<base7>-<cfg6>' (immutable, one per run). Without id: every build with its newest run (last_run), the run its moving tag points at (current_run), the job id of a run in progress (live_job_id, null when idle) and who uses its moving tag (used_by: class defaults, model overrides, containers running or stopped) and its 'update' badge: null before the first update check (every build_update_check_hours; see lmgw__settings) or when it has no succeeded run to compare with, else {checked_at, reasons, ref_moved, extras, errors} — reasons like 'master +37 commits', 'master moved (abc1234 → def5678)', 'PR #1234 pushed', 'PR #1234 merged upstream and contained in your base — drop it' (only once the build's own base is proven to already hold the PR's merge or head commit; otherwise 'PR #1234 merged upstream at <date>; your base doesn't contain it yet — it's still merged into your build'), 'PR #1234 closed unmerged', 'definition changed since last run (ref)'; empty reasons = up to date as of checked_at; what could not be checked (a forge rate limit with its reset time) is in errors. An update is acted on with lmgw__build_run. Also 'repo_presets' — the repository presets (the id is what lmgw__build_set preset= takes). With id: that build and its runs, newest first, each with its status (running; succeeded; unverified = built but not GPU-checked, e.g. under the GPU hold; broken = a verify check failed; failed; canceled; up_to_date = those exact inputs were already built and verified), resolved commits, image, tags, size, verify result and error. Poll this with id after lmgw__build_run until live_job_id is null.

Responses

StatusDescription
200 OK.
application/json BuildsResponse
Fields of BuildsResponse
buildsrequired array of BuildView
usage_error string Set when who uses which image could not be determined (podman did not
answer). Every used_by is then empty **for that reason** — not
because nothing uses the image — and the page should say so.
default Error.
application/json ApiError
post/api/op/container_image_delete

Delete a local podman image by tag or id

Capability admin, open to: owner. Changes state.

Delete a local image by tag or ID (lmgw__container_images). A tag of an image that has other tags is only untagged; the last tag, or an ID, removes the image. While a class default, a model override or any container (running or stopped) uses it, it is refused with the users named and what force would do; show that to the user and pass force=true only once they confirm. Forced, every container on the image is stopped (a running model mid-request too) and removed first, and the class defaults / model overrides naming it are left naming a missing image (listed in still_named_by). Refused on a dev instance, which shares production's image store.

Request body required

application/json: object

force boolean Delete even though it is in use — only after the user confirmed the users the refusal named. Default false. Default false.
image string Image tag (repo:tag) or ID (at least 12 hex). Default "".

Responses

StatusDescription
200 OK.
application/json ContainerImageDeleteResponse
Fields of ContainerImageDeleteResponse
removedrequired array of string
removed_containersrequired array of string A forced delete: the containers it stopped and removed first.
still_named_byrequired array of ImageUse A forced delete: the class defaults and model overrides that still
name the image — now a missing one.
default Error.
application/json ApiError
post/api/op/container_image_pull

Pull a registry image's update as a background job

Capability admin, open to: owner. Changes state.

Request body required

application/json: object

image string Default "".

Responses

StatusDescription
200 OK.
application/json ContainerImagePullStarted
Fields of ContainerImagePullStarted
imagerequired string
job_idrequired integer (int64)
default Error.
application/json ApiError
post/api/op/container_image_pull_status

Read a pull job's progress or result

Capability admin, open to: owner

What a container_image_pull job is doing, or did — the Pull update panel's result and its "recreate N running containers" prompt. While it runs, detail.done_bytes of detail.total_bytes is the download so far (size_note says why the size is not known, when it is not). A model's first start pulls a missing image through the same job before its admission, so a start and this op's pull of one image are one download.

Request body required

application/json: object

job_id integer (int64) Default 0.

Responses

StatusDescription
200 OK.
application/json ContainerImagePullStatus
Fields of ContainerImagePullStatus
detailrequired ImagePullJobDetail | null The latest progress while it runs (podman's last line, the bytes so
far).
errorrequired string | null
imagerequired string The reference being (or that was) pulled.
job_idrequired integer (int64)
resultrequired ImagePullResult | null
statusrequired string queued | running | done | failed | canceled.
default Error.
application/json ApiError
post/api/op/container_image_tag

Add and/or remove one tag on a local image

Capability admin, open to: owner. Changes state.

Request body required

application/json: object

add string | null Default null.
image string Default "".
remove string | null Default null.

Responses

StatusDescription
200 OK.
application/json ContainerImageTagResponse
Fields of ContainerImageTagResponse
tagsrequired array of string
default Error.
application/json ApiError
post/api/op/container_images

List every local podman image of the three engines

Capability admin, open to: owner

Every local podman image of the three engines (llama.cpp and ik_llama.cpp, audio.cpp, stable-diffusion.cpp) — images lmgw built, with their provenance (build, run, repository, ref, base commit, merged extras) and their run's status, and external ones (hand-built tags, registry pulls) — with tags, size, creation time, GPU backend label and who uses each: class defaults, model overrides, running and stopped containers, matched by image ID, so two names of one image are one image. A registry image in use (e.g. the ghcr.io audio and stable-diffusion defaults) carries 'registry_update': the digest the registry serves for its tag at the last update check against the digests podman holds, update_available, and an error when it could not be compared — pull an update with lmgw__container_image_pull. The 'disk' footer has podman's image totals and any buildah leftovers on disk, for information: nothing is pruned from here.

Request body required

application/json: object

disk boolean Default true.
engine Engine | null Only this engine's images. Omit for all three. Default null.

Responses

StatusDescription
200 OK.
application/json ContainerImagesResponse
Fields of ContainerImagesResponse
diskrequired DiskInfo
disk_skippedrequired boolean The call asked for no disk footer (disk: false): disk is empty
because it was not read, not because the store is.
imagesrequired array of ContainerImage
default Error.
application/json ApiError
post/api/op/forge_pr

One pull/merge request's current forge state

Capability admin, open to: owner

Request body required

application/json: object

forge Forge Default "plain".
number integer (uint64) Default 0.
repo_url string Default "".

Responses

StatusDescription
200 OK.
application/json ForgePr
Fields of ForgePr
authorrequired string
base_sharequired string
draftrequired boolean
head_sharequired string
merge_commit_sharequired string The commit the merge put on its target branch — the merge, squash or
rebase commit (GitHub merge_commit_sha; GitLab merge_commit_sha,
else squash_commit_sha). Empty when the forge gives none (an open
PR, an old GitLab). A build skips a merged PR as "merged upstream"
only when its base contains this commit (or the PR's head).
merged_atrequired string | null Set once the forge reports it merged.
numberrequired integer (uint64)
staterequired string The forge's own spelling (open | closed).
titlerequired string
updated_atrequired string
urlrequired string
default Error.
application/json ApiError
post/api/op/forge_prs

List a repository's open pull/merge requests

Capability admin, open to: owner

List a repository's open pull requests (GitHub) or merge requests (GitLab), most recently updated first, 100 per page — to find the number to put in a build's extras. Each has number, title, author, draft, state, head and base commit, merged_at and URL. A 'query' that is a number ('16391', '#16391') or a pasted PR URL returns that one PR whatever its state; other words filter the page (GitHub: every word must appear in the number, title or author; GitLab: server-side search), so a filtered page can be empty while next_page says more pages exist. Uses the forge token configured for the repository's host, if any; without one GitHub allows 60 requests an hour, and an exhausted quota is an error saying when it resets (rate_limit shows what is left).

Request body required

application/json: object

forge Forge Where the repository's PRs live. Default: the build's; for a repo_url, github for github.com (always), gitlab for a host with a configured forge token, otherwise plain — which has no PR list. Default "plain".
page integer | null Page number, from 1 — the previous answer's next_page. Default null.
query string | null A PR number or URL, or words to filter titles and authors by. Default null.
repo_url string The repository, when not naming a build: e.g. https://github.com/ggml-org/llama.cpp. Default "".

Responses

StatusDescription
200 OK.
application/json ForgePrPage
Fields of ForgePrPage
next_pagerequired integer | null
prsrequired array of ForgePr
rate_limitrequired RateLimit | null
default Error.
application/json ApiError
post/api/op/forge_refs

List a repository's branches and tags

Capability admin, open to: owner

The remote's branches and tags, for the ref combobox.

Request body required

application/json: object

repo_url string Default "".

Responses

StatusDescription
200 OK.
application/json RemoteRefsView
Fields of RemoteRefsView
default_branchrequired string
headsrequired array of RefEntry
tagsrequired array of RefEntry
default Error.
application/json ApiError

Benchmark ops

post/api/op/bench_cancel

Cancel the running benchmark run

Capability admin, open to: owner. Changes state.

Cancel the benchmark run that is going: its in-flight requests are dropped, its container removed, the GPU released, and the run kept as 'canceled' with the points measured so far. Models it stopped are not restarted.

Request body required

application/json: object

run_id integer | null Optional: the run you mean — refused if another one is going. Default null.

Responses

StatusDescription
200 OK.
application/json BenchDone
Fields of BenchDone
messagerequired string
okrequired boolean
run_idrequired integer (int64)
default Error.
application/json ApiError
post/api/op/bench_delete

Delete a finished benchmark run

Capability admin, open to: owner. Changes state.

Delete a finished benchmark run for good (nothing else prunes runs). A run still going must be canceled first.

Request body required

application/json: object

id integer (int64) The run id (lmgw__bench_runs). Default 0.

Responses

StatusDescription
200 OK.
application/json BenchDone
Fields of BenchDone
messagerequired string
okrequired boolean
run_idrequired integer (int64)
default Error.
application/json ApiError
post/api/op/bench_plan

Preview a benchmark run: settings, command line, points, probes, what it stops

Capability admin, open to: owner

Preview a benchmark run of one local chat model without starting anything: the effective settings after your overrides, the exact podman command line, the build (image and its labels), the points each phase would measure (derived from the row's numbers and marked provisional — a run reads the real slot count and context from the live server), which behaviour probes apply, and every container a start would stop, with whether it is busy. 'blocked' says why a start would be refused right now: the GPU hold is on, another run is going (with its run_id), the row is missing, disabled or not a chat model, the rung does not exist, or the image is not on this machine. Always call this before lmgw__bench_start and show the user what will be stopped.

Request body required

application/json: object

batch_size integer | null Override -b for this run only. Default null.
cache_type_k string | null Override the K cache type (f16, q8_0, q4_0, …) for this run only. Default null.
cache_type_v string | null Override the V cache type for this run only. Default null.
ctx_size integer | null Override --ctx-size for this run only (the row is never changed). Default null.
flash_attn string | null Override flash attention (auto, on, off) for this run only. Default null.
image string | null Run it on this image instead of the row's (a tag or ID from lmgw__container_images) — comparing two builds is two runs of one row with two images. It must already be on this machine. Default null.
kv_unified boolean | null Override --kv-unified for this run only. Default null.
model_id string The local chat model to benchmark (its model_id, see lmgw__models). Default "".
n_gpu_layers integer | null Override -ngl for this run only. Default null.
no_draft boolean Run without the row's speculative drafter. Default false. Default false.
notes string Default "".
parallel integer | null Override -np (slots) for this run only. Default null.
phases array of Phase Comma-separated phases to run: probes, prefill, decode, concurrent, mixed (load always runs). Empty or absent: all of them. Default [].
repetitions integer | null Repetitions per point (median, min and max are stored). Default 3. Default null.
rung integer (uint32) A ladder row's rung: 0 = base (default), up to the row's top rung. Default 0.
ubatch_size integer | null Override -ub for this run only. Default null.

Responses

StatusDescription
200 OK.
application/json BenchPlan
Fields of BenchPlan
blockedrequired BenchBlocked | null Why it cannot start now; None means bench_start would start it.
buildrequired BuildIdentity
command_linerequired string podman run … as it would be started, with the port it would get
shown as <port>.
modelrequired ModelIdentity
model_idrequired string
paramsrequired SuiteParams
pointsrequired PointPlan Derived from the row's numbers (provisional: true); a run derives
them again from the live server.
probesrequired array of PlannedProbe
rungrequired integer (uint32)
rungsrequired integer (uint32) The row's rungs, base included (1 for a row without a ladder).
settingsrequired BenchSettings
settings_hashrequired string
stopsrequired array of BenchStop Every lmgw container on the card, which a start stops (all classes).
total_stepsrequired integer (uint64) Progress steps the plan takes (JobRow.total), from the provisional
points.
warningsrequired array of string Things worth knowing that do not block (a projector the row cannot
read, …).
default Error.
application/json ApiError
post/api/op/bench_run

One whole benchmark run, compared with its previous comparable run

Capability admin, open to: owner

One benchmark run in full: its identity (model file and quant, build, GPU, settings, command line), every probe with its evidence, every measured point per phase (median, min, max over the repetitions, energy and tokens per joule), phase errors, and the comparison with its previous comparable run: per headline metric the delta, the noise band and a verdict (regression, improvement, same, missing, or not_same_point when the two runs measured it at different points — a run that stopped early; its delta is information and counts for nothing), and probes that changed outcome. The 500 ms power/VRAM/temperature timeline is left out unless timeline=true — it is the bulk of a run.

Request body required

application/json: object

id integer (int64) The run id (lmgw__bench_runs). Default 0.
threshold_pct number | null The regression threshold in percent. Default 5. Default null.
timeline boolean | null Include the 500 ms timeline samples. Default false. Default null.

Responses

StatusDescription
200 OK.
application/json BenchRunDetail
Fields of BenchRunDetail
comparisonrequired BenchComparison | null Against the previous comparable run; None when there is none.
headlinerequired Headline
live_job_idrequired integer | null The job still running this run, for the live jobs feed.
runrequired BenchRun
threshold_pctrequired number (double)
default Error.
application/json ApiError
post/api/op/bench_run_set

Edit a benchmark run's notes

Capability admin, open to: owner. Changes state.

Free-text notes on one run (dashboard only).

Request body required

application/json: object

id integer (int64) Default 0.
notes string Default "".

Responses

StatusDescription
200 OK.
application/json BenchDone
Fields of BenchDone
messagerequired string
okrequired boolean
run_idrequired integer (int64)
default Error.
application/json ApiError
post/api/op/bench_runs

List benchmark runs with their headline numbers, newest first

Capability admin, open to: owner

List benchmark runs, newest first: model, quant, rung, image and build, GPU, status (running, done, failed, canceled, aborted, interrupted), the headline numbers (prefill tok/s and TTFT at 2048 tokens, decode tok/s at depth 64 and at the deepest point, aggregate tok/s at all slots, decode tokens per joule, load time, VRAM after load, the mixed-phase stall), probes passed of judged, and against the previous comparable run (same model file, settings, suite version and GPU) how many metrics regressed or improved beyond threshold_pct.

Request body required

application/json: object

before integer | null Only runs older than this run id (the next page). Default null.
limit integer | null At most this many runs. Absent: every run. Default null.
model_id string | null Only this model's runs. Default null.
threshold_pct number | null The regression threshold in percent, widened by each metric's measured noise. Default 5. Default null.

Responses

StatusDescription
200 OK.
application/json BenchRunsResponse
Fields of BenchRunsResponse
morerequired boolean Older runs exist beyond this page.
runsrequired array of BenchRunSummary
threshold_pctrequired number (double)
default Error.
application/json ApiError
post/api/op/bench_start

Start a benchmark run of a local chat model

Capability admin, open to: owner. Changes state.

Start a benchmark run: one local chat model, as its row is configured (plus your overrides), measured through a fixed suite — load time and VRAM, behaviour probes (chat, thinking on/off, tool calls, JSON schema, determinism, vision, reasoning history, needle), prefill throughput and time to first token at several prompt lengths, decode at several depths, concurrent streams, and a long prompt arriving mid-decode — with power and energy throughout. It takes the WHOLE GPU: it STOPS EVERY MODEL on the card (chat, embedding, audio, image; busy ones after their requests finish, nothing is killed) and, until the run ends, BLOCKS ALL LOCAL TRAFFIC — requests for local models go to their fallback alias or are refused with 503 'gpu_benchmark'. Stopped models are not restarted; they load again on their next request. It is refused while the GPU hold is on, and while another run is going (one at a time). A run of a large model at a long context takes minutes; its top points come from the model's real context, nothing is capped. Returns run_id and job_id at once: follow it with lmgw__bench_run id=<run_id>; lmgw__bench_cancel ends it early (partial results are kept). Call lmgw__bench_plan first and confirm what will be stopped with the user.

Request body required

application/json: object

batch_size integer | null Override -b for this run only. Default null.
cache_type_k string | null Override the K cache type (f16, q8_0, q4_0, …) for this run only. Default null.
cache_type_v string | null Override the V cache type for this run only. Default null.
ctx_size integer | null Override --ctx-size for this run only (the row is never changed). Default null.
flash_attn string | null Override flash attention (auto, on, off) for this run only. Default null.
image string | null Run it on this image instead of the row's (a tag or ID from lmgw__container_images) — comparing two builds is two runs of one row with two images. It must already be on this machine. Default null.
kv_unified boolean | null Override --kv-unified for this run only. Default null.
model_id string The local chat model to benchmark (its model_id, see lmgw__models). Default "".
n_gpu_layers integer | null Override -ngl for this run only. Default null.
no_draft boolean Run without the row's speculative drafter. Default false. Default false.
notes string Free text stored with the run (why you ran it). Default "".
parallel integer | null Override -np (slots) for this run only. Default null.
phases array of Phase Comma-separated phases to run: probes, prefill, decode, concurrent, mixed (load always runs). Empty or absent: all of them. Default [].
repetitions integer | null Repetitions per point (median, min and max are stored). Default 3. Default null.
rung integer (uint32) A ladder row's rung: 0 = base (default), up to the row's top rung. Default 0.
ubatch_size integer | null Override -ub for this run only. Default null.

Responses

StatusDescription
200 OK.
application/json BenchStarted
Fields of BenchStarted
job_idrequired integer (int64)
messagerequired string
run_idrequired integer (int64)
stopsrequired array of BenchStop What the run is stopping (as bench_plan listed it).
default Error.
application/json ApiError

Agent ops

post/api/op/agent_config_set

Save a sparse patch over an agent's stored config

Capability admin, open to: owner. Changes state.

A sparse patch over the stored config values. clear is the way out of the patch's one asymmetry: an empty submission keeps a stored secret (the house convention for tokens), so removing a value — including clearing a secret — is its own explicit list, which can also reset any field to its schema default.

Request body required

application/json: object

clear array of string Field names to remove from the stored config outright (the one gesture for 'forget this value', including a secret an empty submission would otherwise keep).
idrequired string Agent id, from /api/agents.
valuesrequired object A sparse patch over the stored config values — a field left out keeps what is stored.

Responses

StatusDescription
200 OK.
application/json AgentConfigSaved
Fields of AgentConfigSaved
cleared_undeclaredrequired array of string Names in clear that the manifest does not declare. Clearing one is
legitimate (it is how a value orphaned by a manifest change goes away),
but a typo in clear looks exactly like it.
configrequired any What is now stored, with every secret field replaced by
{ "has_value": bool } — the merged values, not the patch.
idrequired string
messagerequired string What was done, for a person to read.
mounts_repointedrequired array of string The folder and file slots whose stored path changed, cleared ones
included.
okrequired boolean Always true; a refusal is an error answer instead.
service_stopped string A running app container holds the old folder, so a re-pointed slot stops
it: the name of the container that was stopped; absent when none was
running.
token_scoperequired string The agent's token scope, re-derived from the saved config, in words:
token: any model or the aliases it is fenced to.
default Error.
application/json ApiError
post/api/op/agent_delete

Remove an agent from the catalog

Capability admin, open to: owner. Changes state.

Remove an agent from the catalog. A shipped agent stays deleted across restarts; the agents_restore op on the dashboard is the deliberate way back. If it was hand-written, read its manifest with lmgw__agent_get first — that is the only copy.

Request body required

application/json: object

idrequired string Agent id, from lmgw__agents.

Responses

StatusDescription
200 OK.
application/json AgentDeleted
Fields of AgentDeleted
hintrequired string How to bring it back: agents_restore for a shipped agent, importing
the exported file for any other.
idrequired string
messagerequired string What was done, for a person to read.
okrequired boolean Always true; a refusal is an error answer instead.
threads_keptrequired integer (uint64) Chat threads that were opened through the agent and were kept, on the
Chat page, without it.
default Error.
application/json ApiError
post/api/op/agent_dev_url_set

Point an agent's app at a dev server, or back at its image

Capability admin, open to: owner. Changes state.

A row setting, never part of the manifest: overrides service mode only. Setting one stops a running app container, since it was started from the image this override replaces. Omitting url (or an empty string) clears it back to the image. Both are refused for an agent that declares no run.service.

Request body required

application/json: object

idrequired string Agent id, from /api/agents.
url string The dev server's URL. Omit or empty to serve from the image again.

Responses

StatusDescription
200 OK.
application/json AgentDevUrlSet
Fields of AgentDevUrlSet
dev_urlrequired string The dev server's URL as stored; empty when the override was cleared.
idrequired string
messagerequired string What was done, for a person to read.
okrequired boolean Always true; a refusal is an error answer instead.
stopped string Setting a URL stops a running app container, since it was started from
the image the URL replaces: the name of the container that was stopped.
Absent when none was running, and when the override was cleared.
default Error.
application/json ApiError
post/api/op/agent_duplicate

Copy an agent's manifest under a new id

Capability admin, open to: owner. Changes state.

Same manifest under a new id, config copied minus secrets — a copy must not silently inherit a credential.

Request body required

application/json: object

idrequired string Agent id to copy, from /api/agents.
name string The copy's display name. Default: '<name> (copy)'.
new_idrequired string The copy's id — a DNS label ([a-z0-9][a-z0-9-]*).

Responses

StatusDescription
200 OK.
application/json AgentDuplicated
Fields of AgentDuplicated
config_omittedrequired array of string The secret config fields left out of the copy: a copy must not
silently inherit a credential.
idrequired string The copy's id.
messagerequired string What was done, for a person to read.
namerequired string The copy's name: the one asked for, or the original's with (copy).
okrequired boolean Always true; a refusal is an error answer instead.
default Error.
application/json ApiError
post/api/op/agent_enable

Enable or disable an agent

Capability admin, open to: owner. Changes state.

Disable is the kill switch: the agent's token stops authenticating anywhere, and a running app container is stopped (service_stopped names it; the sentence is in message).

Request body required

application/json: object

enabledrequired boolean Whether the agent (and its token) is usable at all.
idrequired string Agent id, from /api/agents.

Responses

StatusDescription
200 OK.
application/json AgentEnabled
Fields of AgentEnabled
enabledrequired boolean The state it is in now.
idrequired string
messagerequired string What was done, for a person to read.
okrequired boolean Always true; a refusal is an error answer instead.
service_stopped string Disabling stops a running app container: the name of the container that
was stopped; absent when none was running or the agent was enabled. The
sentence is in message.
default Error.
application/json ApiError
post/api/op/agent_install

Install an agent from an OCI image carrying its manifest

Capability admin, open to: owner. Changes state.

Install an agent from an image: lmgw reads its manifest out of the image at /lmgw/agent.json without starting it, then installs it through the same path agent_set uses, so the report shape is the same (plus image, digest — absent when podman reports none — pulled, manifest_path and message). pull defaults to 'never' — an image not already on the box is reported rather than downloaded.

Request body required

application/json: object

imagerequired string The image reference, tag and all (e.g. localhost/mail-labeler:1).
pull string What to do when the image is not on this box. Default 'never' — report it, download nothing. One of never, missing, always.
replace boolean Overwrite an existing agent with the id inside the image (its config is kept). Default false.
validate_only boolean Report what the image would install and write nothing. Default false.

Responses

StatusDescription
200 OK.
application/json AgentInstalled
Fields of AgentInstalled
config_unboundrequired array of string Mount slots this agent has and nothing has bound: an
export never carries a host path, so an imported agent arrives with its
directory and file fields empty and the importer says which folder.
digest string The image's digest; absent when podman could not report one.
dropped_configrequired array of string Stored config keys the **new** manifest no longer declares, removed with
the manifest that declared them (the same rule applies to every replace). Keeping them
would leave a row that fails validation
on every run and cannot be fixed from its own config form.
idrequired string
imagerequired string The image reference that was installed, trimmed.
manifest_pathrequired string Where the manifest was read from inside the image: /lmgw/agent.json.
messagerequired string What was done, for a person to read.
okrequired boolean
pulledrequired boolean This call downloaded the image: false when it was already on the box
(or always found it unchanged), so a download is never left to be
inferred from how long the call took.
replacedrequired boolean An existing agent was overwritten (replace=1), keeping its config.
requiresrequired array of AgentRequirement
validate_onlyrequired boolean validate_only=1: the same report, nothing written.
warningsrequired array of string A missing server label or tool: the agent is saved, Start is disabled.
default Error.
application/json ApiError
post/api/op/agent_open_chat

Open a chat thread for a chat-kind agent

Capability admin, open to: owner. Changes state.

Open a new Chat thread configured from a chat-kind agent's manifest — model alias, system prompt, attached MCP tools — optionally patched by values for this thread only.

Request body required

application/json: object

idrequired string Agent id, from /api/agents.
values object A sparse patch over the stored config, applied to this run only — same shape as agent_config_set's values.

Responses

StatusDescription
200 OK.
application/json AgentChatOpened
Fields of AgentChatOpened
idrequired string The agent's id.
messagerequired string What was done, for a person to read.
modelrequired string The model alias the thread was opened on: the manifest's, rendered
against the config.
okrequired boolean Always true; a refusal is an error answer instead.
thread_idrequired integer (int64) The new thread's id.
toolsrequired array of string The tool labels the thread attaches, in manifest order.
urlrequired string Where the dashboard navigates to: /chat?t=<thread_id>.
warningsrequired array of string What is off about a thread that did open: an alias the gateway does not
serve, a tool server that is not registered, manifest sampling knobs a
thread has no column for.
default Error.
application/json ApiError
post/api/op/agent_pull

Fetch this agent's image again and report whether it moved

Capability admin, open to: owner. Changes state.

Pressing this is the consent, so it pulls under every policy, 'never' included. changed is true when the digest moved or the image arrived (none before), false when it did not, and absent when podman reports no digest after the pull. When it is true, the new image's manifest is read and compared with the stored one — never adopted automatically; that is what agent_reimport is for.

Request body required

application/json: object

idrequired string Agent id, from /api/agents.

Responses

StatusDescription
200 OK.
application/json AgentPulled
Fields of AgentPulled
changed boolean Whether the image changed. Both digests known: they differ. No digest
before and one now: true, the image arrived. Absent when podman could
not report a digest after the pull (unknown).
idrequired string
imagerequired string The image reference that was pulled.
manifest_differsrequired boolean | null Only asked when changed is true: the new image's manifest differs from
the stored one (true), is the same (false), or could not be compared
(null, and note says why). null too when nothing moved.
messagerequired string What was done, for a person to read.
new_digest string The digest after the pull; absent when podman could not report one.
noterequired string What the comparison found, for a person to read; empty when nothing
moved.
okrequired boolean Always true; a refusal is an error answer instead.
old_digest string The digest podman held before the pull; absent when it held none, or
could not report one.
recorded_digest string The digest the agent's row recorded when it was installed or last
pulled — different from old_digest whenever something else on the box
moved the image. Absent for a row that never recorded one.
default Error.
application/json ApiError
post/api/op/agent_reimport

Re-run the install path over an existing agent's row

Capability admin, open to: owner. Changes state.

Run the install path again over an existing row: the manifest is replaced and the config is kept. The answer is the import report plus the image, whether its manifest differed from the stored one, and a message. Refused when the image carries a different agent id than this row — install it as its own agent instead.

Request body required

application/json: object

idrequired string Agent id, from /api/agents.

Responses

StatusDescription
200 OK.
application/json AgentReimported
Fields of AgentReimported
changedrequired boolean The image's manifest differs from the one that was stored. false
also adds a line to warnings saying nothing about the agent changed.
config_unboundrequired array of string Mount slots this agent has and nothing has bound: an
export never carries a host path, so an imported agent arrives with its
directory and file fields empty and the importer says which folder.
dropped_configrequired array of string Stored config keys the **new** manifest no longer declares, removed with
the manifest that declared them (the same rule applies to every replace). Keeping them
would leave a row that fails validation
on every run and cannot be fixed from its own config form.
idrequired string
imagerequired string The image the manifest was read from.
messagerequired string What was done, for a person to read.
okrequired boolean
replacedrequired boolean An existing agent was overwritten (replace=1), keeping its config.
requiresrequired array of AgentRequirement
validate_onlyrequired boolean validate_only=1: the same report, nothing written.
warningsrequired array of string A missing server label or tool: the agent is saved, Start is disabled.
default Error.
application/json ApiError
post/api/op/agent_reset

Restore a shipped agent to its built-in manifest

Capability admin, open to: owner. Changes state.

A shipped agent back to its built-in manifest, keeping its config — except a value the new schema no longer declares, which is dropped and named in the answer.

Request body required

application/json: object

idrequired string Agent id, from /api/agents.

Responses

StatusDescription
200 OK.
application/json AgentReset
Fields of AgentReset
dropped_configrequired array of string Stored config keys the shipped schema no longer declares, dropped so the
next Start does not fail on them.
idrequired string
messagerequired string What was done, for a person to read.
okrequired boolean Always true; a refusal is an error answer instead.
default Error.
application/json ApiError
post/api/op/agent_run

Start one phase of a batch agent's run

Capability admin, open to: owner. Changes state.

One live run per agent: when one is in flight, nothing starts and the answer is that run, with already_running true and its own phase.

Request body required

application/json: object

base_job integer apply only: the job id whose config this apply reuses.
idrequired string Agent id, from /api/agents.
phaserequired string What to run. One of list, classify, rerun, apply.
rows array apply only: the reviewed rows from a finished 'classify' run.
values object A sparse patch over the stored config, applied to this run only.
Example
{
  "base_job": 1234,
  "id": "mail-labeler",
  "phase": "apply"
}

Responses

StatusDescription
200 OK.
application/json AgentRunStarted
Fields of AgentRunStarted
already_runningrequired boolean "One live run per agent" is a report, not a refusal: a run of this
agent was in flight, job_id is that one and nothing was started.
idrequired string
job_idrequired integer (int64) The run's job id, for GET /api/agents/runs/{job_id}: the new run's,
or the one in flight when already_running.
messagerequired string What was done, for a person to read.
okrequired boolean Always true; a refusal is an error answer instead.
phaserequired string The phase of the run job_id names — the one asked for, or when
already_running the in-flight run's own: list, classify, rerun,
apply, or run for a container agent.
default Error.
application/json ApiError
post/api/op/agent_run_cancel

Ask an agent's in-flight run to stop

Capability admin, open to: owner. Changes state.

Cooperative cancel: the executor stops between items and keeps the rows it has.

Request body required

application/json: object

idrequired string Agent id, from /api/agents.

Responses

StatusDescription
200 OK.
application/json AgentRunCancelled
Fields of AgentRunCancelled
idrequired string
messagerequired string What was done, for a person to read.
okrequired boolean Always true; a refusal is an error answer instead.
default Error.
application/json ApiError
post/api/op/agent_service_log

Read an agent's app container's log tail

Capability admin, open to: owner

The App tab's log block, as long as the reader asks for — asking for 0 lines means the whole log; the answer's lines counts what came back. The only account of a detached service container: it writes no run ledger, no job row and no result.

Request body required

application/json: object

idrequired string Agent id, from /api/agents.
lines integer How many lines from the end. 0 = the whole log. Default a short excerpt.

Responses

StatusDescription
200 OK.
application/json AgentServiceLog
Fields of AgentServiceLog
container string The container the log is read from. Absent when nothing is running.
idrequired string
linesrequired integer (uint64) How many lines log holds. Fewer than asked for when the container has
logged less (0 asked for is the whole log).
logrequired string The log's tail.
messagerequired string What was done, for a person to read.
okrequired boolean Always true; a refusal is an error answer instead.
runningrequired boolean Whether the app container is running; log is empty when it is not.
default Error.
application/json ApiError
post/api/op/agent_service_start

Start an agent's app container

Capability admin, open to: owner. Changes state.

The same on-demand path a proxied request takes, pressed by hand: one start however many callers ask, the manifest's health probe, its start_timeout_seconds.

Request body required

application/json: object

idrequired string Agent id, from /api/agents.

Responses

StatusDescription
200 OK.
application/json AgentServiceStarted
Fields of AgentServiceStarted
containerrequired string The container's name.
host_portrequired integer (uint16) The loopback port the container's app is published on.
idrequired string
messagerequired string What was done, for a person to read.
okrequired boolean Always true; a refusal is an error answer instead.
originrequired string Where the app answers now: the agent's own origin, which is what a
reader opens (the host port is lmgw's business).
runningrequired boolean Always true.
default Error.
application/json ApiError
post/api/op/agent_service_stop

Stop an agent's app container

Capability admin, open to: owner. Changes state.

The stop ladder. Stopping something that is not running is success — "make sure this is not running" is what the button means.

Request body required

application/json: object

idrequired string Agent id, from /api/agents.

Responses

StatusDescription
200 OK.
application/json AgentServiceStopped
Fields of AgentServiceStopped
cancelled_startrequired boolean A start was in flight and was interrupted, rather than a running
container being stopped.
idrequired string
messagerequired string What was done, for a person to read.
okrequired boolean Always true; a refusal is an error answer instead.
runningrequired boolean Always false.
stopped string The name of the container that was stopped or collected; absent when
there was none.
default Error.
application/json ApiError
post/api/op/agent_set

Install or replace an agent from a manifest

Capability admin, open to: owner. Changes state.

Install or replace an agent from a manifest. manifest is the whole JSON document as a string — schema_version 1, an id matching [a-z0-9][a-z0-9-]*, a name, a model ({{config.model}} lets whoever configures the agent pick), an optional config schema, the MCP tool labels it may reach, and a run block (chat or batch). Unknown fields are refused naming the key, and every {{config.<field>}} must name a field of the config schema. This is exactly the import path the dashboard uses, so the report it returns is the same: warnings for tool labels this gateway does not have (the agent still installs; it just cannot run yet). Validate first with validate_only=true. Replacing keeps the stored config. Pass the manifest as a JSON *string*, not as an object: an object is accepted but arrives with its keys re-sorted, which reorders the config form the author wrote, and the report says so.

Request body required

application/json: object

manifestrequired string The whole manifest document, as a JSON string. An object works too, but re-sorts the config form — send the string.
replace boolean Overwrite an existing agent with this id. Default true.
validate_only boolean Report what would happen and write nothing. Default false.

Responses

StatusDescription
200 OK.
application/json AgentImportReport
Fields of AgentImportReport
config_unboundrequired array of string Mount slots this agent has and nothing has bound: an
export never carries a host path, so an imported agent arrives with its
directory and file fields empty and the importer says which folder.
dropped_configrequired array of string Stored config keys the **new** manifest no longer declares, removed with
the manifest that declared them (the same rule applies to every replace). Keeping them
would leave a row that fails validation
on every run and cannot be fixed from its own config form.
idrequired string
okrequired boolean
replacedrequired boolean An existing agent was overwritten (replace=1), keeping its config.
requiresrequired array of AgentRequirement
validate_onlyrequired boolean validate_only=1: the same report, nothing written.
warningsrequired array of string A missing server label or tool: the agent is saved, Start is disabled.
default Error.
application/json ApiError
post/api/op/agent_token_get

Read an agent's own MCP/API token

Capability admin, open to: owner. Changes state.

A read of the column that already holds the value, not a reveal-once: lmgw hands this token to the agent's container on every run, including one it did not start. Mints the token first if the agent has none yet, and re-derives its scope from the manifest either way.

Request body required

application/json: object

idrequired string Agent id, from /api/agents.

Responses

StatusDescription
200 OK.
application/json AgentTokenRead
Fields of AgentTokenRead
idrequired string
messagerequired string What was done, for a person to read.
namerequired string agent:<id> — the name Logs and the usage page print.
okrequired boolean Always true; a refusal is an error answer instead.
scope_moderequired string all or allow: whether the token is fenced to model aliases.
scope_noterequired string The scope in words, as the detail page prints it.
scope_patternsrequired string The model aliases the token is fenced to, one per line; empty for all.
tokenrequired string The bearer token. Secret: it is shown here and nowhere else.
default Error.
application/json ApiError
post/api/op/agent_token_rotate

Mint a new token for an agent, invalidating the old one

Capability admin, open to: owner. Changes state.

Replaces the agent's token in one write. A running service container is holding the old one, so it is stopped — the next request to the agent's origin starts it again with the new token. What the old token holds open ends at once: its realtime sessions close with 4003, and its /mcp notification streams end.

Request body required

application/json: object

idrequired string Agent id, from /api/agents.

Responses

StatusDescription
200 OK.
application/json AgentTokenIssued
Fields of AgentTokenIssued
idrequired string
messagerequired string What was done, for a person to read.
namerequired string agent:<id> — the name Logs and the usage page print.
okrequired boolean Always true; a refusal is an error answer instead.
scope_moderequired string all or allow: whether the token is fenced to model aliases.
scope_noterequired string The scope in words, as the detail page prints it.
scope_patternsrequired string The model aliases the token is fenced to, one per line; empty for all.
service_stopped string A rotation stops the app container that was holding the old token: the
name of the container that was stopped; absent when none was running.
tokenrequired string The bearer token. Secret: it is shown here and nowhere else.
warning string A rotation that could not re-derive the scope still rotated: the token
above is the live one, and this says what did not happen. Absent
otherwise.
default Error.
application/json ApiError
post/api/op/agents_restore

Reinstall any shipped agent that was deleted

Capability admin, open to: owner. Changes state.

Every shipped agent not currently installed is put back with its built-in manifest. An agent still installed, edited or not, is left alone.

Responses

StatusDescription
200 OK.
application/json AgentsRestored
Fields of AgentsRestored
messagerequired string What was done, for a person to read.
okrequired boolean Always true; a refusal is an error answer instead.
restoredrequired array of string The ids that were put back; empty when every shipped agent was already
there.
default Error.
application/json ApiError

Agent runtime

Agent runtime

The routes an agent container calls with its own token: reading its own definition and runs, and opening and driving a run.

get/api/agents/runs/{job_id}

Get one agent run

Capability agent-self, open to: agent, owner

One run with its rows: the executor's live buffer while it is in flight, the stored result once it has ended. Ownership is checked before existence, so a run that belongs to another caller and a missing one get the same refusal.

Parameters

NameInDescription
job_idrequiredpath integer

Responses

StatusDescription
200 OK.
application/json AgentRunDetail
Fields of AgentRunDetail
batchrequired AgentBatchShape | null The agent's current review shape, so the table can be drawn from a run
alone — including one finished last week, which is what "reopen this
run's review" needs. For a ledger run its columns carry the undeclared
keys the events brought, appended after the declared ones in first-seen
order.
jobrequired AgentRunSummary
logrequired array of string The run log: log events, rejected events, and the lines lmgw itself
wrote. Empty for an in-process run, which has none yet.
resultrequired any The apply step's structured output and the run's usage total, once the
run has finished.
rowsrequired array The reviewed rows: the executor's live buffer while running, the job
result after. Rows are deliberately **not** pushed through the generic
jobs feed.
default Error.
application/json ApiError
post/api/agents/runs/{job_id}/close

Close an agent run

Capability ledger, open to: agent. Changes state.

Closes a run this caller owns with its terminal status.

Parameters

NameInDescription
job_idrequiredpath integer

Request body required

application/json: AgentRunCloseBody

Fields of AgentRunCloseBody
detail string
output any Any JSON value; carried into the stored result verbatim.
status string Absent defaults to "done". One of done, failed, canceled.

Responses

StatusDescription
200 OK.
application/json Ack
Fields of Ack
okrequired boolean Always true; a failure is an error answer instead.
default Error.
application/json ApiError
post/api/agents/runs/{job_id}/events

Append agent run events

Capability ledger, open to: agent. Changes state.

Appends one ledger event, an array of them, or an NDJSON batch to a run this caller owns, straight into the run's live buffer, which the dashboard's Run tab reads.

Parameters

NameInDescription
job_idrequiredpath integer

Request body required

application/json: AgentRunEventsBody

application/x-ndjson: string

Responses

StatusDescription
200 OK.
application/json AgentEventsApplied
Fields of AgentEventsApplied
appliedrequired integer (uint) How many events went into the run.
okrequired boolean Always true: rejected events are reported below, not failed.
rejectedrequired array of string One line per event the run did not take (unparseable, or refused by
the run's rules), in the order they were sent.
default Error.
application/json ApiError
get/api/agents/{id}

Get an agent

Capability agent-self, open to: agent, owner

One agent's full definition: the complete document for owner credentials or, for the agent's own token, the same document with host paths substituted out.

Parameters

NameInDescription
idrequiredpath string

Responses

StatusDescription
200 OK.
application/json AgentDetail
Fields of AgentDetail
batchrequired AgentBatchShape | null The run surface a batch or container agent offers. None for a
chat agent.
budgetrequired AgentBudget The two Responses settings a turn is bounded by, shown next to Apply.
configrequired any Stored config values with every secret field replaced by
{ "has_value": bool }. The value itself never leaves the process.
created_atrequired string
currencyrequired string The gateway's display currency, so a run's cost is printed the way the
Usage page prints every other one.
descriptionrequired string
dev_urlrequired string The dev-server override. While it is set, /agents/<id>/app/**
goes there and no container is started for the app; runs and applies
still use the image. Empty means "served from the image".
effective_modelrequired string
enabledrequired boolean
errorrequired string | null Set when the stored manifest could not be read at all — a row written by
a newer build. The document still comes back 200 with whatever could
be read, so the Definition editor stays reachable for the very manifest
that needs fixing; a 400 here would lock the client out of it.
fieldsrequired array of AgentField The config schema flattened into form fields, in document order.
idrequired string
kindrequired string
last_run AgentRunSummary The agent's most recent run, with its outcome (status, error, tokens,
cost) — the same summary the catalog card carries. While a run is in
flight it is that run. Absent when the agent has never run, when
retention pruned its runs, and on a row this build cannot read.
live_jobrequired AgentRunSummary | null The run in flight, if any.
manifestrequired string The manifest as stored: the canonical serialization, **as text** — what
the Definition editor loads and what Export writes.

Text and not a serde_json::Value on purpose. serde_json::Map is a
BTreeMap, so a Value here would alphabetize the config schema's
properties and silently re-sort the form the author laid out.
Parse it client-side if a tree is needed, and post it back to
agent_set as a **string**: an object argument is accepted but arrives
already re-sorted, and the import report says so.
model_aliasrequired string
namerequired string
portabilityrequired AgentPortability Whether an export of this agent would land on another box, and what the
receiver would have to do if not. The same answer the export file's
portability key carries, on the page that offers the download.
provenancerequired AgentProvenance | null Where this row was installed from. None for a row that came
from a pasted manifest rather than from an image.
requiresrequired array of AgentRequirement
requires_okrequired boolean
resettablerequired boolean A shipped manifest exists for this id, so "Reset to shipped" applies.
runtimerequired AgentRuntime | null What a container agent runs under. None for every other kind.
servicerequired AgentService | null Service mode, when the manifest declares it.
None means no App tab, no proxy route and no agent:<id> MCP row.
sourcerequired string
threadsrequired integer (int64)
tokenrequired AgentToken The agent's own token — its name, whether one has been minted, and the scope it
currently carries. **Never the value**:
that comes from agent_token_get, which is what Copy token calls.
updated_atrequired string
versionrequired string
warningsrequired array of AgentWarning Warnings that are not tool gaps. Start is disabled while any of them carries
blocks_start.
default Error.
application/json ApiError
get/api/agents/{id}/runs

List an agent's runs

Capability agent-self, open to: agent, owner

This agent's run history. For the agent's own token, a run's error text has host paths substituted out the same way the detail read does.

Parameters

NameInDescription
idrequiredpath string

Responses

StatusDescription
200 OK.
application/json array of AgentRunSummary
Fields of AgentRunSummary
agent_idrequired string
cost_microrequired integer | null What those tokens cost, in micro-units of the gateway's currency.
None is "nobody could price this", which is also not zero.
created_atrequired string
detailrequired any
donerequired integer (uint64)
duration_msrequired integer | null Wall clock from claim to finish. None while it is still going.
errorrequired string | null
finished_atrequired string | null
job_idrequired integer (int64)
model_callsrequired integer | null The model calls the run made, from its result: calls answered without
an error. None until it has a result. Some(0) with no cost_micro
and no tokens is a run that had nothing to price; Some(0) can also
come with a cost, from calls that failed or were stopped after their
rows were priced.
percentrequired integer | null
phaserequired string list, classify, rerun or apply.
stagerequired string
started_atrequired string | null
statusrequired string queued | running | done | failed | canceled.
tokensrequired integer | null Prompt + completion tokens the run spent, from its result.
None until it has one — "not known yet", which is not zero.
totalrequired integer | null
default Error.
application/json ApiError
post/api/agents/{id}/runs

Open an agent run

Capability ledger, open to: agent. Changes state.

Opens a run from outside lmgw, exactly as the manifest's own trigger would. An agent has at most one live run: a second open while one is live is refused with the running job's id.

Parameters

NameInDescription
idrequiredpath string

Request body required

application/json: object

phase string | null Default null.
rows array of Row Default [].

Responses

StatusDescription
200 OK.
application/json AgentRunOpened
Fields of AgentRunOpened
deadline_secondsrequired integer (uint64) How long the run has before lmgw ends it; 0 is no deadline.
runrequired integer (int64) The run's job id, for /api/agents/runs/{job_id} and its events and
close routes.
409 Error, with this body rather than the default one.
application/json AgentRunConflict
Fields of AgentRunConflict
coderequired string Always already_running.
messagerequired string
runrequired integer (int64) The job id of the run that is in flight.
default Error.
application/json ApiError

Schemas

AddableCandidate

One local chat model a draft could add as a candidate.

idrequired string The model's id.
missingrequired array of string The enabled facets (wire names) the model does not support; empty when
it can be added as it is.

AdminLevel

A level of lmgw's admin tools, written off, read_only or full:
what a device's admin tools may do now (the change feed's
hello.self_admin and state.self_admin), the level set on a device
key (KeyRow.self_admin, and self_admin in key_create and
key_set), or the gateway's own (GatewayStatus.self_admin,
SettingsFull.self_admin).

Forward compatible like every enum a client reads: a value a newer
gateway sends reads as AdminLevel::Unknown, as sent, and writes back
unchanged. The document lists the known values only.

One of: string (No admin tools.); string (Reads lmgw's configuration and state.); string (Also changes them.)

AgentBatchShape

What a batch manifest can actually do, for the Run tab.

Derived server-side from the manifest **and the stored config**, because
both halves matter and only one of them is in the manifest: the review
columns are the author's, in the author's order, while the values an
editable field may be set to come from the config field enum_from names —
so widening the taxonomy is a config edit and the table picks it up.
A client re-deriving this from the manifest text would also lose the column
order, since a JSON object parses into a sorted map here.

apply_toolsrequired array of string The tools Apply reaches, named next to the button so the reviewer knows
what is about to be called.
apply_tools_are_ceilingrequired boolean apply_tools is the ceiling the agent's token enforces rather than the
calls the step makes — true for a container, whose image decides. The
Run tab says "may call" instead of "calls".
columnsrequired array of string Review-table columns, in the manifest's order.
deciderequired AgentDecide | null The output can classify through a question set (its decide); None
when it cannot.
editablerequired array of AgentReviewField Output fields the reviewer may override, with their allowed values.
has_applyrequired boolean The manifest declares an apply step, so there is something to write.
has_classifyrequired boolean The manifest declares a per-item model call, so "Dry run" applies.

AgentBudget

The visible bounds a turn runs under: one pair from Settings → Agents & tools,
never a second one invented per agent.

max_tool_callsrequired integer (uint32)
timeout_secondsrequired integer (uint64)

AgentCard

GET /api/agents — one card per catalog entry.

apprequired boolean This agent declares run.service, so it serves an app of its own — the card's
app chip, and a link to the App tab.
descriptionrequired string
effective_modelrequired string
enabledrequired boolean
errorrequired string | null Set when the stored manifest could not be read at all — a row written
by a newer build. The card still lists, saying why, rather than the
whole catalog failing.
idrequired string
kindrequired string The manifest's run.kind: chat, batch or container. Empty for a
row whose stored manifest could not be read (error says why).
labelsrequired array of string The tool labels this agent attaches, in manifest order.
last_runrequired AgentRunSummary | null
model_aliasrequired string The manifest's model alias, template and all — usually
{{config.model}}, in which case effective_model says what the
stored config resolves it to.
namerequired string
requiresrequired array of AgentRequirement
requires_okrequired boolean Every label resolves and every narrowed tool name is currently listed.
sourcerequired string builtin, imported or authored.
threadsrequired integer (int64) Threads a chat agent has opened.
versionrequired string Free text from the manifest, informational.
warningsrequired array of AgentWarning Warnings that are not tool gaps.

AgentDecide

A batch output that classifies through a Decision lab question set
(labs-store design §4): the config field holding the set, the set's
question it asks, and how the stored config's set reads.

enum_fromrequired string | null The config field the enum comes from without a set (enum_from),
which a run with a set does not read.
fieldrequired string The config field holding the set's id (QUESTION_SET_FORMAT).
measuredrequired boolean The threshold was measured on a labelled set run. Only a measured
threshold is applied: an answer whose confidence is below it needs
attention. An unmeasured one is shown, not applied (Decision 10).
model_fieldrequired string | null The config field the agent's model alias is ({{config.<field>}}),
when it is one: a classify needs it or a set, so the Run tab blocks
Classify while both are empty.
problemrequired string | null Why the stored config's set cannot classify (gone, no such question,
not a choice, no default model); a run refuses with it.
questionrequired string The set's question that answers the output field: the output field's
own name. It must be a choice question, whose options are the
review's values with the fallback last.
setrequired integer | null The set the stored config names; None classifies with the model
call, as without decide.
set_namerequired string | null That set's name.
thresholdrequired number | null The threshold the set keeps for its question (0 when it has none),
measured or not: see measured.

AgentField

One rendered config field. ty is string | integer | number |
boolean | array
; format is secret | model_alias | multiline | directory
| file
or empty, or QUESTION_SET_FORMAT on an integer.

accessrequired string For a directory or file field: ro or rw, as the **manifest**
declared it. Empty for every other field — the mode is a
property of the agent, never of the form.
defaultrequired any
descriptionrequired string
enumrequired array of string
formatrequired string
has_valuerequired boolean For a secret field: whether one is stored. Always false otherwise —
the value itself is in config.
maximumrequired number | null
minimumrequired number | null
namerequired string
requiredrequired boolean
titlerequired string
typerequired string

AgentInstallHint

kindrequired string git, image or url.
notesrequired string
refrequired string

AgentPortability

Whether the export of this agent lands on another box.

Shown before the download, never enforced: exporting to the same box is the
common case, and the wrong answer is a file that looks complete while naming
an image only the exporter has.

notesrequired array of string What the receiver would have to do, one sentence each. Empty when
portable.
portablerequired boolean Nothing about this agent is local to this machine.

AgentProvenance

Where this row's document came from.

None on the detail document for a row nobody installed from an image — an
agent written in the Definition editor has no package and says so by having
no provenance, rather than by carrying one full of empty strings.

installed_at and pulled_at are two facts on purpose: the first is when
the row was written from the image, the second when the digest was last
read. agent_pull moves only the second.

digest string podman image inspect --format '{{.Digest}}' at the last read. Absent
when podman could not say — never a placeholder that reads like a digest.
imagerequired string The image reference as it was given at install, tag and all.
installed_atrequired string
manifest_pathrequired string Where in the image the manifest was found (/lmgw/agent.json).
pulled_atrequired string

AgentRequirement

One tools[] entry measured against what the gateway offers right now.

A gap is a warning, never a refusal: an agent is imported before its server
is wired, the same way a server is registered before its image is pulled.

installrequired AgentInstallHint | null The manifest's install hint, for prefilling the MCP page. lmgw never
fetches anything from it.
labelrequired string
missing_toolsrequired array of string Names in allowed the source does not list right now.
registeredrequired boolean The label resolves to a registered server or a built-in toolset.

AgentReviewField

One editable output field. An empty options means free text: there is no
enum behind it to offer.

fieldrequired string
optionsrequired array of string

AgentRowSet

The question set that classified a batch row (labs-store design §4),
stamped on the row as the run read the set: its id, its name and its
updated_at. "Save as labelled set" saves a run's rows into the set
that classified them; a row the model call classified has none.

digest string A digest of the output question's definition (type, text, options
with descriptions, levels) as it was asked. "Save as labelled set"
reports the set changed only when the question's digest differs, not
on any updated_at bump (a threshold write). Empty on a row stamped
without one, which reads as unchanged. Default "".
id integer (int64) The set's preset id. Default 0.
name string Its name then. Default "".
updated_at string Its updated_at then: the version of the set that answered. Default "".

AgentRunCloseBody

detail string
output any Any JSON value; carried into the stored result verbatim.
status string Absent defaults to "done". One of done, failed, canceled.

AgentRunEventsBody

One ledger event object ({row, ...} or {log: "..."} or {done: true, ...}) or a JSON array of them. The same events may be sent as application/x-ndjson instead, one object per line; lmgw reads the raw body either way, whatever its Content-Type. A line or entry it cannot parse is skipped and counted in the response's rejected list, and never fails the whole call.

object | array

AgentRunSummary

One agent_run job as the Runs tab lists it.

The universal job fields plus the run's own detail/result, whose inner
shape belongs to the executor rather than to this DTO — the same
split JobView already makes for every other job kind.

agent_idrequired string
cost_microrequired integer | null What those tokens cost, in micro-units of the gateway's currency.
None is "nobody could price this", which is also not zero.
created_atrequired string
detailrequired any
donerequired integer (uint64)
duration_msrequired integer | null Wall clock from claim to finish. None while it is still going.
errorrequired string | null
finished_atrequired string | null
job_idrequired integer (int64)
model_callsrequired integer | null The model calls the run made, from its result: calls answered without
an error. None until it has a result. Some(0) with no cost_micro
and no tokens is a run that had nothing to price; Some(0) can also
come with a cost, from calls that failed or were stopped after their
rows were priced.
percentrequired integer | null
phaserequired string list, classify, rerun or apply.
stagerequired string
started_atrequired string | null
statusrequired string queued | running | done | failed | canceled.
tokensrequired integer | null Prompt + completion tokens the run spent, from its result.
None until it has one — "not known yet", which is not zero.
totalrequired integer | null

AgentRuntime

What a container agent runs under.

Every limit is here with its default printed next to it on the Run tab:
a container's bounds are shown, never guessed, like a run's tool-call and
wall-clock budget. 0 means "no
limit" everywhere except stop_grace_seconds, where it means SIGKILL at
once — the page says which.

cpusrequired number (double)
deadline_secondsrequired integer (uint64)
imagerequired string
memory_mbrequired integer (uint64)
output_validatedrequired array of string The phases whose output event is validated against a declared schema.
A phase absent here is unvalidated, which the Run tab says out loud
rather than leaving the reader to assume a check that is not happening.
phasesrequired array of string Which phases the image implements, in declaration order.
pidsrequired integer (uint64)
podmanrequired boolean podman --version answered on this box.
podman_noterequired string Why it did not, when it did not.
pullrequired string never | missing | always.
read_onlyrequired boolean
stop_grace_secondsrequired integer (uint64)

AgentService

Service mode as the App tab describes it.

Everything a bound here is read from is a manifest field with its value
printed: the idle window, the start timeout and the health path are the
manifest's, and 0 means what it says everywhere else — never idle-stop,
and wait as long as the start takes.

containerrequired string
health_pathrequired string run.service.health_path. Empty = a TCP connect instead of an HTTP GET.
host_portrequired integer (uint16) The host port this start published on — ephemeral, per start. 0 when
nothing is running.
idle_secondsrequired integer (int64) 0 = never idle-stop, exactly as an MCP server's idle_seconds means it.
idle_seconds_nowrequired integer | null How long ago the last proxied request finished. None when nothing is
running.
in_flightrequired integer (uint) Requests in flight, which is what the idle sweep skips on.
log_tailrequired string The container's own log tail, read while it is running. Empty when
nothing is up — podman logs on a container that is gone has nothing to
say.
log_tail_linesrequired integer (uint) How many lines log_tail is at most, printed beside
it so nobody has to guess whether they are seeing all of it.
mountsrequired array of AgentServiceMount The host mounts this agent's container holds, in the manifest's field order and
only the ones that are bound.

The App tab lists them. host is filled for an Admin reader and left
out for the container reading its own row, which is told
/lmgw/mounts/<field> and nothing else.
originrequired string The origin this agent's UI is served on, as a URL with its slash:
http://board.localhost:8001/. The container's
own LMGW_APP_ORIGIN is the same origin *without* the slash — an
origin to concatenate onto, rather than an href.
origin_resolvesrequired boolean <id>.<suffix> resolves on the machine lmgw is running on — the server
asked the resolver when it rendered this. False is not an error: the
App tab prints the /etc/hosts line that fixes it, and Chrome and
Firefox resolve *.localhost regardless of what the system says.
portrequired integer (uint32) The in-container port the manifest declares.
provides_mcprequired string | null run.provides.mcp, when declared: the path inside the container that
speaks MCP, registered as the agent:<id> server.
runningrequired boolean The container is up and answering.
start_timeout_secondsrequired integer (uint64) 0 = wait as long as the container takes.
started_atrequired string | null When the running container was started.
startingrequired boolean A start is in flight right now.

AgentServiceMount

One bound mount as a reader is shown it.

accessrequired string ro | rw, as the manifest declared it.
fieldrequired string The config field that names the slot.
host string The canonical host path — **Admin only**. None is what the agent's
own view sees, and it is absent from the JSON rather than empty: a
container is not told there is a path it is not being given.
insiderequired string /lmgw/mounts/<field> — what the container sees, for every reader.
kindrequired string directory | file, from the field's format.

AgentToken

The agent's credential as the detail page describes it.

has_valuerequired boolean A token has been minted. false until the first run or the first Copy
token: an agent that is never run never mints a credential.
namerequired string agent:<id> — the name Logs and the usage page print.
scope_noterequired string The derived scope in words — "token: any model", or the aliases it is
fenced to. Shown next to Copy token so the scope is never invisible.

AgentWarning

One warning that is not a tool gap.

Beside requires, of the same shape and rendered in the same place. The
Start gate is requires_ok **and** no warning with blocks_start.

blocks_startrequired boolean
coderequired string A stable identifier — container_without_image, podman_unavailable,
image_absent_pull_never, local_image_on_import,
secrets_dir_fallback, install_image_mismatch, dev_url_active.
messagerequired string

AliasView

A model alias plus its resolved upstream name.

aliasrequired string
capabilities_override any An alias's capabilities override for the derived /v1/models capability facts: a JSON
object with optional keys capabilities, max_output_tokens, notes. None = no
override.
enabledrequired boolean
fallbackrequired string | null The alias's one fallback, as written; None = no fallback.
idrequired integer (int64)
param_overridesrequired Params
upstream_idrequired integer (int64)
upstream_model_idrequired string
upstream_namerequired string | null

AlignedWord

One aligned word.

char_end integer | null One past the word's last matched letter or digit in text, in the
same units as char_start: the span is [char_start, char_end).
char_start integer | null Where the word starts in text, counted in Unicode scalar values
(not bytes, not UTF-16 units). The span is matched on letters and
digits only, case-insensitively, in order: Nuova, and Nuova both
cover the five letters of Nuova in the transcript. Absent, with
char_end, for a word that could not be found in the transcript.
confidence number | null How sure the model is, when it says (several families send 0
for every word, which means "not computed", not "unsure").
endrequired number (double) Where the word ends in the clip, in seconds; as start.
end_sample integer | null end in samples; as start_sample.
startrequired number (double) Where the word starts in the clip, in seconds. Taken from the model,
or computed from start_sample and sample_rate when it sends only
samples.
start_sample integer | null start in samples of sample_rate: as the model answered, or
computed from the seconds when the rate is known. Absent when the
model sends none and the rate is unknown.
wordrequired string The word as the model reported it, punctuation and all (CrisperWhisper
keeps the comma on Nuova,, Qwen3's aligner strips it).

AnthropicCompaction

compaction: on-demand compaction (the top-level compaction), and
which of its types work.

summarizerequired AnthropicSupport context_editing.compaction names summarize.
supportedrequired boolean An Anthropic route (lmgw's context_editing is present) whose
catalog names an on-demand compaction type for the model
(context_editing.compaction): the field goes out as written and
the compaction block comes back as it came. Unpublished is false.

AnthropicContextManagement

context_management: whether a request's context_management reaches
the model, and which of its edit types work.

clear_thinking_20251015required AnthropicSupport context_management.edits names clear_thinking_20251015.
clear_tool_uses_20250919required AnthropicSupport context_management.edits names clear_tool_uses_20250919.
compact_20260112required AnthropicSupport context_management.edits names compact_20260112: the edit goes
out as written and the compaction block Anthropic answers with
comes back as it came.
supportedrequired boolean An Anthropic route, which sends context_management on as written
(lmgw's context_editing is present), whose catalog says the model
takes it (context_editing.supported is true); unpublished is
false.

AnthropicCountTokensRequest

messagesrequired array of object
contentrequired any A string, or an array of blocks: {type:text,text}, {type:image,source:{type:base64,media_type,data} | {type:url,url}}, {type:tool_use,id,name,input} (the id as lmgw gave it: a Gemini model's carries its thought signature and runs to hundreds of characters; echo it exactly, and do not send it to another provider directly), {type:tool_result,tool_use_id,content,is_error}, {type:thinking,thinking,signature} (replayed; unsigned when lmgw itself produced it). Every other block type (redacted_thinking, the provider's own tool blocks, a type newer than lmgw) goes to an Anthropic upstream as written; any other upstream is sent none of it, and x-lmgw-params-ignored names it as content.<type>. A block without a type is refused with 400. A custom tool without input_schema (a server tool) is refused with 400.
rolerequired string One of user, assistant.
modelrequired string
output_config object
system any A string, or an array of {type:text,text} blocks.
thinking object
tool_choice any {type:auto|any|none|tool}.
tools array of object
description string
input_schemarequired object
namerequired string

AnthropicCountTokensResponse

context_management object Anthropic's own count of the input before the request's context edits ({original_input_tokens}), as it reported it. Only on an Anthropic model's count of a request with context_management.
input_tokensrequired integer

AnthropicEffort

effort: whether output_config.effort reaches the model, and which
levels it takes.

highrequired AnthropicSupport reasoning.levels contains high.
lowrequired AnthropicSupport reasoning.levels contains low.
maxrequired AnthropicSupport reasoning.levels contains max.
mediumrequired AnthropicSupport reasoning.levels contains medium.
supportedrequired boolean The model has selectable effort levels (reasoning.kind is
levels): a request's output_config.effort reaches it.
xhighrequired AnthropicSupport reasoning.levels contains xhigh.

AnthropicError

errorrequired object
messagerequired string
typerequired string e.g. invalid_request_error, not_found_error, permission_error, overloaded_error, api_error.
typerequired string One of error.

AnthropicMessage

contentrequired array of object
context_management object The context management an Anthropic model applied ({applied_edits: [...]}), as Anthropic reported it; a stream carries it on its closing message_delta. Absent from every other model's answer.
idrequired string
modelrequired string
rolerequired string One of assistant.
stop_reasonrequired string | null
stop_sequencerequired null
typerequired string One of message.
usagerequired object
cache_creation_input_tokens integer Present only when the upstream reported cache writes.
cache_read_input_tokens integer Present only when the upstream reported a cache read.
input_tokensrequired integer
iterations array of object An Anthropic model's per-iteration usage, as it reported it (a compaction entry for a compaction it ran, which the top-level counts leave out). Present only when the upstream reported it.
output_tokensrequired integer

AnthropicMessagesRequest

compaction object Anthropic's on-demand compaction ({type: summarize}; send its beta flag in anthropic-beta). To an Anthropic model it goes as written, and the compaction block Anthropic answers with comes back as it wrote it (stop_reason compaction). Every other model's provider has no equivalent: it is left out and named in x-lmgw-params-ignored. A model's capabilities.context_editing.compaction says which types it takes.
context_management object Anthropic's context management ({edits: [...]}; send its beta flag in anthropic-beta). To an Anthropic model it goes as written, and Anthropic answers for it; a compaction edit (compact_…) included, whose compaction block comes back as Anthropic wrote it. Every other model's provider has no equivalent: it is left out and named in x-lmgw-params-ignored. A model's capabilities.context_editing on GET /v1/models says what it takes.
max_tokens integer
messagesrequired array of object
contentrequired any A string, or an array of blocks: {type:text,text}, {type:image,source:{type:base64,media_type,data} | {type:url,url}}, {type:tool_use,id,name,input} (the id as lmgw gave it: a Gemini model's carries its thought signature and runs to hundreds of characters; echo it exactly, and do not send it to another provider directly), {type:tool_result,tool_use_id,content,is_error}, {type:thinking,thinking,signature} (replayed; unsigned when lmgw itself produced it). Every other block type (redacted_thinking, the provider's own tool blocks, a type newer than lmgw) goes to an Anthropic upstream as written; any other upstream is sent none of it, and x-lmgw-params-ignored names it as content.<type>. A block without a type is refused with 400. A custom tool without input_schema (a server tool) is refused with 400.
rolerequired string One of user, assistant.
modelrequired string
output_config object lmgw reads output_config.effort as the same reasoning tier x-lmgw-reasoning-effort sets, and output_config.format ({type:json_schema, schema}; the deprecated top-level output_format too) as the structured output every upstream gets in its own spelling. Its refusals are 400 invalid_request_error with the upstream's message. To an OpenAI model the schema goes with strict: true (this format guarantees the schema), so OpenAI's strict-mode rules apply — every property in required, additionalProperties false — and a schema that breaks them comes back as OpenAI's invalid_json_schema refusal, its message kept.
effort string
format object
stop_sequences array of string
stream boolean Default false.
system any A string, or an array of {type:text,text} blocks, joined with blank lines.
temperature number
thinking object {type:enabled,budget_tokens} | {type:disabled} | {type:adaptive} (enabled, no budget — "think as much as judged necessary") | {type:between_tools} (no up-front thinking: an off that goes to an Anthropic model as written; every other model gets its own off, and x-lmgw-reasoning-ignored names between_tools). Any other type is refused with 400. display goes to an Anthropic model inside adaptive and enabled; beside an off, and to every other model, it is left out and x-lmgw-params-ignored names thinking.display.
tool_choice any {type:auto|any|none|tool} (tool also carries name).
tools array of object Custom tools only (input_schema required); a server tool (web_search, computer use, …) is refused with 400.
description string
input_schemarequired object
namerequired string
top_k integer
top_p number

AnthropicModel

capabilities AnthropicModelCapabilities
context_window integer
created_atrequired string (date-time)
display_namerequired string
idrequired string
lifecyclerequired string Always active: a model lmgw lists is one it serves. One of active.
max_input_tokens integer Alias of context_window, under the name the Anthropic SDK types it by.
max_output_tokens integer
max_tokens integer Alias of max_output_tokens.
notes array of string
pricing object
completionrequired string
promptrequired string USD per prompt token, as a decimal string; "0" for a local model.
typerequired string One of model.

AnthropicModelCapabilities

lmgw's own capabilities object (as on the OpenAI shape, where an absent field means unknown) plus Anthropic's ten capability blocks. In the blocks, supported: true means a /v1/messages request using the feature works on this model through lmgw; false means lmgw does not serve it yet or does not know — Anthropic's schema has no unknown.

batchrequired AnthropicSupport Always false yet: lmgw serves no /v1/messages/batches yet.
citationsrequired AnthropicSupport Always false yet. A document or search_result block reaches an
Anthropic-protocol route as the client wrote it and an answer's
citations come back to a Messages client (gateway design §6.1,
"Citations", 2026-11-06), but lmgw does not read the catalog's
citations block yet, so it cannot say per model.
code_executionrequired AnthropicSupport Always false yet: the code execution tool is a server tool, which
the Messages ingress refuses.
compactionrequired AnthropicCompaction
context_editing ContextEditingCaps | null Anthropic's context management (context_management on
/v1/messages: context editing and threshold compaction, and the
top-level on-demand compaction), under a name of its
own because the Anthropic-shaped model entry puts Anthropic's
context_management block beside lmgw's object. Present only on an
Anthropic-protocol route, the one route that sends a request's
context_management on as written; every other route leaves it out
and names it in x-lmgw-params-ignored.
context_managementrequired AnthropicContextManagement
effortrequired AnthropicEffort
endpointsrequired array of string The lmgw routes that accept this model id.
image_inputrequired AnthropicSupport vision is true and the model is served on /v1/messages, whose
ingress takes image blocks (base64 and URL sources).
input_modalities array | null Subset of text, image, audio, video, file, pdf,
embedding. pdf is a catalog's word (Anthropic's pdf_input,
Kilo's and OpenRouter's modality).
Absent = unknown, never "none".
languages array of string ISO 639-1 codes (a few three-letter ones, yue) of the languages a
local audio model works in, whatever its task: speech, recognition,
alignment. A request's language takes them (lmgw sends each in the
model's own spelling). Absent when the model's package names none
as codes; see multilingual for a family that says only that it
covers many.
multilingual boolean | null The model's family says it is multilingual without listing codes
("multilingual", "80+ languages"): it works in more languages than
languages names, which then holds few or none. Absent otherwise;
absent along with languages means unknown, never "one language".
output_modalities array | null The same vocabulary, plus decisions: what a decision model answers
with (llama.cpp's and OpenRouter's word). A client that checks
llama.cpp's architecture.output_modalities for decisions reads
this list instead. Absent = unknown.
pdf_inputrequired AnthropicSupport An Anthropic-protocol route (context_editing present) to a model
whose catalog says pdf_input (input_modalities holds pdf): a
document block reaches it as the client wrote it, base64, URL or
Files API source (gateway design §6.1, "Anthropic blocks lmgw does
not model"). false on every other route, which is sent no
document block.
reasoning ReasoningCaps | null
server_toolsrequired AnthropicServerTools
sourcerequired string Where the facts came from: gguf+config, catalog, config, or
owner (an alias's capabilities override).
speech SpeechCaps | null A text-to-speech model's expressive controls — what instructions,
inline tags, language and stream_format do on it
(the speech capabilities object). A local audio model's is derived; a
cloud alias has one only through an alias's capabilities override.
structured_output StructuredOutputCaps | null
structured_outputsrequired AnthropicSupport structured_output.json_schema is true: the ingress reads
output_config.format (and the older output_format) of type
json_schema.
taskrequired string chat | embedding | rerank | decision (a decision model,
answering on /v1/systemone) | tts | asr | an audio.cpp task
name | an image task | realtime (an OpenAI Realtime model, no lmgw
route). Determines endpoints.
thinkingrequired AnthropicThinking
tool_calls ToolCallCaps | null
vision boolean | null input_modalities contains image. Redundant with the list on
purpose: a client can read this one boolean to decide whether to
send images, e.g. whether a session gets a screenshot tool. Absent
exactly when input_modalities is absent.

AnthropicServerTools

server_tools: Anthropic's server-run tools.

code_executionrequired AnthropicSupport The code execution server tool; false yet, as supported.
supportedrequired boolean Always false yet: the Messages ingress refuses every tool without an
input_schema (a server tool) before any upstream sees it.
web_searchrequired AnthropicSupport The web search server tool; false yet, as supported.

AnthropicStreamEvent

SSE event: <type>, data: <this object>, one per line of the sequence above.

typerequired string One of message_start, content_block_start, content_block_delta, content_block_stop, message_delta, message_stop, error.

AnthropicSupport

One Anthropic capability: {"supported": bool}.

supportedrequired boolean true only when a /v1/messages request using this feature works on
this model through lmgw; false when lmgw does not serve it yet or
does not know.

AnthropicThinking

thinking.

supportedrequired boolean The model reasons: reasoning.kind is toggle or levels, or
fixed with enabled: true.
typesrequired AnthropicThinkingTypes Which thinking types work; all false when supported is.

AnthropicThinkingTypes

thinking.types: which of Messages' thinking types work.

adaptiverequired AnthropicSupport {"type": "adaptive"} (lmgw's bare "on") makes the model think. On
an Anthropic route, which sends it as thinking type adaptive: the
model's catalog names the type (reasoning.thinking_types). Elsewhere:
its default is on, or "on" reaches it (the template's
enable_thinking on a local row).
between_toolsrequired AnthropicSupport {"type": "between_tools"} (no up-front thinking) reaches a model
that takes it: on an Anthropic route, which sends the type as
written, the model's catalog names it (reasoning.thinking_types).
Elsewhere false: those routes send their own off instead, and say
so in x-lmgw-reasoning-ignored.
disabledrequired AnthropicSupport {"type": "disabled"} switches thinking off
(reasoning.can_disable is true; on an Anthropic route, the
catalog's thinking.types.disabled).
enabledrequired AnthropicSupport {"type": "enabled", "budget_tokens": n}: the budget reaches the
model. On an Anthropic route, which forwards the budget form as
written: the model's catalog names the type
(reasoning.thinking_types). Elsewhere: reasoning.control names
x-lmgw-reasoning-budget.

ApiError

Uniform error body for every non-2xx /api response.

coderequired string Stable machine-readable code, e.g. not_found, invalid_input.
messagerequired string Human-readable description, shown verbatim in the UI.

ApiKeyRow

enabledrequired boolean
idrequired integer (int64)
namerequired string

AppliedToCurrent

What a folder patch applied to the folder's current thread (applied
in the patch's answer): the thread and the settings it changed, as the
thread settings name them (temperature, voice.tts_alias).

fieldsrequired array of string
thread_idrequired integer (int64)

ApprovalDecision

One verdict.

approval_request_idrequired string
approverequired boolean
reason string | null Why, for a declined call: the model reads "The user declined this
tool call: <reason>".

ApprovalRequest

One call that waits for an approval.

approval_request_idrequired string The id a decision quotes (mcpr_…), unique in the gateway.
argumentsrequired string The arguments as the model wrote them: a JSON string.
call_id string The call's id, as its ready and result frames carry it
(mcp_apps::ToolReadyFrame::call_id). Absent from an lmgw
before 2026-10-09, and from an ApprovalRequest read off a bound
session's mcp_approval_request item (OpenAI's shape has none):
there the lmgw.chat.frame relaying the approval frame has it.
namerequired string The tool's own name: the name the model called, without its
label's <prefix>__.
server_labelrequired string The thread's label the tool came from.

ApprovalRequested

approval.requested: a turn in the thread stopped on a call that waits
for an approval (client-apps design §6.5). Rendered from the reply's
pending state at delivery; a reply gone by then (deleted, regenerated),
or a call decided by then (its approval.decided follows),
is not delivered. With thread_title, server_label, name and
arguments a client shows it, or a notification, without a fetch. Also
the shape of Hello::open_approvals' entries.

approval_request_idrequired string
argumentsrequired string A JSON string.
call_id string The call's id, as the turn's ready, approval and result frames
carry it. Absent from an lmgw before 2026-10-09.
message_idrequired integer (int64) The reply that waits.
namerequired string The tool's own name, as chat_approvals::ApprovalRequest.
server_labelrequired string
thread_idrequired integer (int64)
thread_titlerequired string The thread's title at delivery (in hello, at the head it read).

AsrForm

The transcription panel's fields (the language is the speech form's).

details boolean Send to /v1/audio/transcriptions/details. Default false.
file_name string The upload's file name, as the page held it; the bytes are the
group's input artifact once sent. Default "".
path string A clip on the model server, for the path source. Default "".
source string upload or path. Default "upload".
stream boolean Default false.

AttachmentFacts

What extraction found in an attachment (AttachmentMeta::meta): which
keys are there depends on the kind. A key a gateway version adds is kept
beside these, so a reader never loses it.

class string | null A PDF's class: text, scanned or hybrid. One of text, scanned, hybrid.
format string | null An office file's or audio clip's format, as sniffed (docx, wav, ...).
media MediaFacts | null A file an image or audio tool made: the model, its parameters and
times (chat-media-tools design §9).
pages integer | null A PDF's page count.
parts integer | null How many parts an office file has.
sheets array | null A spreadsheet's sheet names.
textless array | null A PDF's pages without a text layer, numbered from 1.
tokens integer | null The extracted text's token estimate (text, PDF, office files and
transcribed audio).
transcript_alias string | null The speech-to-text alias that wrote an audio clip's transcript.
transcript_error string | null Why an audio clip's transcription failed, until a retry succeeds.

AttachmentMeta

One attachment's metadata, never its bytes.

blockers array of string For a draft: why it cannot be sent to the thread's current model.
call_id string The tool call that made a tool file, or the card action that made
an action file (its act-<boot>-<n> id, the one its stream's
frames carried); absent for an upload.
extracted_tokensrequired integer | null The extracted text's token estimate; null when there is none.
hints array of string For a draft: what it becomes on the way, sent all the same (an image
as a placeholder, a PDF's pages as its text) under a fallback that
cannot see.
idrequired integer (int64)
kindrequired string image, pdf, text, audio, ... as the upload was classified.
metarequired AttachmentFacts What extraction found: pages, text-less pages, class, sheets,
transcript alias or error, tokens. {} for an image.
mimerequired string
moderequired string | null A text-class PDF's choice, text or images; null when it does
not apply or is not chosen yet.
namerequired string
sizerequired integer (int64) Size in bytes.
sourcerequired string Where the file came from: upload (the user sent it), tool (an
image or audio tool of a turn made it) or action (an image card's
action made it). One of upload, tool, action.

AudioAlignmentsRequest

multipart/form-data only — lmgw's own route (for models whose row has task "align"), not an OpenAI shape.

filerequired string (binary)
language string
modelrequired string
textrequired string

AudioCatalogInstall

POST /api/op/audio_catalog with action: "download" — the package's
files go through the shared HF download queue (target audio), exactly
like a wizard download.

downloadsrequired array of QueuedDownload
enginerequired EngineDownload | null The audio class's image, when it is not on this machine or podman
could not say: the download fetches a missing one too, a
multi-gigabyte download of its own, and starts nothing
(EngineDownload). null when it is here.
familyrequired string
files_queuedrequired integer (uint32)
messagerequired string
okrequired boolean Always true.
packagerequired string
reporequired string
revisionrequired string The revision the files are fetched at: the commit the catalog pins
(under audio.catalog_revision = pinned), else main.

AudioCatalogRefreshed

audio_catalog with action: refresh: the catalog was fetched anew.

familiesrequired integer (uint) How many model families the catalog holds.
fetched_atrequired string RFC 3339 time of the fetch.
messagerequired string The outcome in a sentence.
okrequired boolean Always true; a warning does not fail a refresh.
warningsrequired array of string What the refresh could not do (a spec file that did not load, a
package repository Hugging Face could not list).

AudioFamily

One model family (model_specs/<family>.json).

any_installedrequired boolean At least one package fully downloaded.
builtin_voicesrequired array of string Voices the family ships, and which it uses by default — enough to
configure a TTS row before its container has ever run.
capabilitiesrequired object Per-task capability tags, as the spec writes them.
categoryrequired string Free-form spec category (tts, asr, …) — a badge, not an enum.
default_voicerequired string
descriptionrequired string
display_namerequired string
docsrequired array of string ui.docs — paths into the audio.cpp repo, rendered as links.
familyrequired string
languagesrequired array of string
options AudioFamilyOptions The typed options this family accepts, by group. The dashboard's
catalog always has them; the tool's full listing leaves them out for
options_summary (they are long) and a listing narrowed by family
has them.
options_summary string In the tool's full listing instead of options: where to get them. Never
in the dashboard's catalog.
packagesrequired array of AudioPackage
servedrequired boolean An enabled audio model of this family loads one of its packages
(some package's served). A row that points at the family's files
without saying which package is the packages' serving_unclear; one
that loads nothing of the family is serving_note.
serving_noterequired string One sentence per enabled row of this family that matches none of its
packages — an empty or missing root, a weight_id that picks no file,
GGUFs no package ships — joined by "; ". Empty when there is none.
statusrequired string supported | community | experimental | testing | wip — how
finished upstream calls this family. Empty when the spec is older than
the field.
summaryrequired string One extra line the spec offers beside the description.
tagsrequired array of string ui.tags — short labels from the project's own WebUI.
tasksrequired array of string

AudioFamilyOption

One declared option: name, type, and whatever bounds the spec states.

defaultrequired any The engine's default, as JSON; absent when the spec states none.
descriptionrequired string
kindrequired string string | int | float | bool | enum | path | … — the spec's
own vocabulary, not an enum on this side of the wire.
maxrequired number | null
minrequired number | null
namerequired string
requiredrequired boolean
valuesrequired array of string Accepted values of an enum option (a named preset already expanded).

AudioFamilyOptions

A family's declared options, split the way they are configured: load and
session are the two JSON objects on the model row, request is what a
call may carry.

loadrequired array of AudioFamilyOption
requestrequired array of AudioFamilyOption
sessionrequired array of AudioFamilyOption

AudioInputMode

Whether a voice turn may reach the chat model as audio.

One of: string (The chat model reads the transcript.); string (A chat model that takes audio hears the turn; the transcript is
made beside it.)

AudioInputShown

audio_input: the setting, the level it came from, and the verdict.

blocked AudioInputVerdict The verdict a GPU block would bring: its fallback's, or the refusal
when there is none. Absent unless no block is live now and one would
hand the turn elsewhere.
lead string What handed the turn to model when the resolve swapped ("under the
GPU hold"). Absent when nothing did.
modelrequired string The model the turn goes to: the thread's, or the fallback a block hands
it to.
pathrequired InputPath audio when the model hears the turn, transcript otherwise.
sourcerequired VoiceSource The level value came from.
valuerequired AudioInputMode The setting in effect.
whyrequired string | null Why the transcript, in the page's words; null on the audio path.

AudioInputVerdict

Where a voice turn's words go: as audio, or as the transcript and why.

blocked AudioInputVerdict The verdict a GPU block would bring: its fallback's, or the refusal
when there is none. Absent unless no block is live now and one would
hand the turn elsewhere.
lead string What handed the turn to model when the resolve swapped ("under the
GPU hold"). Absent when nothing did.
modelrequired string The model the turn goes to: the thread's, or the fallback a block hands
it to.
pathrequired InputPath audio when the model hears the turn, transcript otherwise.
whyrequired string | null Why the transcript, in the page's words; null on the audio path.

AudioLabForm

The whole form a kept group stores: which task's panel was shown, every
panel's fields and the speech settings, so a re-opened group puts the
page back as it was when it asked. The model is the plan's.

asr AsrForm Default {"details":false,"file_name":"","path":"","source":"upload","stream":false}.
generic boolean The OpenAI-shaped task was sent through /v1/tasks/run instead. Default false.
settings AudioSettings2Input Default {"pcm":{"bits":"16","channels":"1","rate":"24000"},"speech":{"input":"","instructions":"","language":"","max_tokens":"","model":"","options":"","reference_text":"","response_format":"","seed":"","speed":"","stream":false,"voice":"","voice_ref":""}}.
task string The task picker's id (tts, asr, vc, ...). Default "".
tasks TaskForm Default {"flags":{},"json":"","stream":false,"values":{}}.
timeline_rate string The timeline rate field, for spans in samples. Default "".

AudioLabModel

One enabled audio model, as the lab's pickers need it.

aliasrequired string The alias to send as model: the audio prefix and the model id.
familyrequired string The engine family the model runs in (audio.cpp's own name for it).
moderequired string offline or streaming; only a streaming model can stream speech.
model_idrequired string
taskrequired string What the model does: tts, asr, align or another audio.cpp task.
Decides which panel the lab offers.

AudioLabUploadRequest

multipart/form-data. The body size is not limited.

filerequired string (binary) A clip; send as many file parts as there are clips. A part's file name names the clip: letters, digits, space, '.', '_' and '-', not starting with '.' (anything else is a 400). A clip with the name of a stored one replaces it.
transcript string What the clip says. Applied only when the upload holds exactly one file; blank is ignored.

AudioModel

An audio model row (JSON-map fields stay dynamic).

backendrequired string | null cpu runs this row on the CPU (no VRAM, served under the GPU hold);
None inherits the class's backend.
busy_timeout_msrequired integer | null Per-model busy_timeout_ms and the ceiling a request's own value is
clamped to, in ms; None inherits the class.
config_idrequired string | null Named config/weights asset ids, for a model directory holding several.
default_request_optionsrequired object Request-option defaults applied to every call to this model.
default_voice_presetrequired any
enabledrequired boolean
extra_run_argsrequired array | null Per-model podman run args override; None inherits the audio
class settings' extra_run_args.
fallbackrequired string | null The model or alias that answers whenever this one cannot (the GPU
hold, VRAM outside lmgw, background traffic deferred, a disabled
row), as written. None = no fallback.
familyrequired string
idrequired integer (int64)
imagerequired string | null Per-model container image override;
None inherits the audio class settings' image.
lazyrequired boolean | null Per-model override of the class's lazy_load; None inherits.
load_optionsrequired object
moderequired string
model_idrequired string
model_spec_overriderequired string | null A <family>.json model spec (or a directory of them) under the audio models
dir that replaces the container image's own catalog for this row.
pathrequired string
residencyrequired LearnedResidency | null What this model's container was measured to hold on the GPU once it
had served a request. Learned by the gateway,
never by the editor; audio_model_set's clear: "residency" resets
it. None = not learned, charged at the on-disk size.
session_optionsrequired object
taskrequired string
threadsrequired integer | null Per-row thread count; None inherits (this machine's physical cores
for a row switched to the CPU itself, else the class's — for a row
that inherits a class backend of cpu too).
voice_presetsrequired object
warm_startrequired boolean Start this model's own container at app launch.
weight_idrequired string | null

AudioModelDetail

An audio.cpp model read back.

backendrequired string | null cpu when the row is switched to the CPU; null inherits the class.
busy_timeout_msrequired integer | null
config_idrequired string | null
default_request_optionsrequired object
default_voice_presetrequiredany
effective_extra_run_argsrequired array of string The podman run args in effect, one entry per argument.
effective_imagerequired string The image the container starts from (the row's, else the class's).
enabledrequired boolean
extra_run_argsrequired array | null podman run args override, one entry per argument; null inherits.
fallbackrequired string | null The one fallback (openai egress design §14.2), as written; null =
none.
familyrequired string The audio.cpp model-loader family.
idrequired integer (int64)
imagerequired string | null Container image override; null inherits the audio class's.
lazyrequired boolean | null
load_optionsrequired object
moderequired string
model_idrequired string
model_spec_overriderequired string | null
next_steprequired string How to prove the model works.
pathrequired string The model directory, relative to the audio models dir.
path_presentrequired boolean Whether that path exists.
problemsrequired array of string
public_namerequired string The name clients call it by, with the audio prefix.
residencyrequired LearnedResidency | null What the container was measured to hold on the GPU.
residency_charged_bytesrequired integer | null The learned residency admission charges, when it belongs to the
current configuration.
residency_noterequired string What the row is charged on the GPU, in a sentence.
runningrequired AudioRunning | null The container's state, when one is running.
runs_onrequired string gpu or cpu.
server_jsonrequired any The server.json entry this row renders to.
session_optionsrequired object
taskrequired string
threadsrequired integer | null
threads_in_effectrequired integer (int64)
threads_sourcerequired string row, class, cores or logical_cpus.
voice_presetsrequired object
warm_startrequired boolean
weight_idrequired string | null

AudioModelView

deferrals_24hrequired integer (uint64) LocalModelView::deferrals_24h, for this row's public_name.
modelrequired AudioModel
public_namerequired string
residency_charged_bytesrequired integer | null The learned residency admission charges this row: model.residency's
figure while it belongs to the row's current configuration, None
otherwise (not learned, or learned for a previous configuration — the
on-disk size is charged then).
residency_noterequired string What the row is charged on the GPU and why, in one sentence: its learned residency, or the
on-disk size it is charged
at instead — not learned yet, learned for a previous configuration, or
not learnable on this host (and why).
runs_onrequired string Where the row runs as configured now: gpu | cpu (its own
backend, else the class's). A running container keeps the placement
it was started with until it stops.
threads_in_effectrequired integer (int64) The thread count its server.json renders.
threads_sourcerequired string Where that count comes from: row | class | cores (this
machine's physical cores, for a row switched to the CPU that names
none) | logical_cpus (the same, where the core topology could not
be read and the figure is the logical CPU count).

AudioPackage

One installable package (a file set of a family) plus everything the UI
needs to show its state and to prefill the audio-model editor from it.

availability_noterequired string What is known about whether the repo publishes this package's files,
when it is not simply "all of them": the missing ones with the date of
the listing, or why the repo could not be listed. Empty otherwise.
descriptionrequired string What this package is, when the spec says so (a size, a trade).
display_namerequired string
download_idsrequired array of integer (int64) Tracked download rows for this package's files — the UI joins them
against GET /api/hf/downloads for live progress.
downloaded_fromrequired string Which commit the downloaded files came from, as a sentence — the
commit and the revision the download asked for, or "unknown" for files
downloaded before lmgw recorded it. Empty when nothing is downloaded.
file_countrequired integer (uint32)
formatrequired string gguf / safetensors.
gatedrequired boolean The repo needs an accepted licence and a token: downloading it without
one fails with 401s, so the UI says so before the click.
idrequired string
incompleterequired boolean Downloaded once and short of missing_files now, with nothing on
its way: a download ("complete install") fetches those — and, while
a pin is followed, the package's installed files from another commit
than the pin, so the package is one commit again.
installedrequired boolean Every file downloaded — the package can be served.
missing_filesrequired array of string Spec files the package lacks on this machine, once any of it was
downloaded: no finished download, or the file is gone from disk. A
spec that grew after the package was installed (a new built-in
voice) shows up here.
partialrequired boolean Some (not all) files tracked/downloaded.
pin_followedrequired boolean Whether a download takes pinned_commit: true under
audio.catalog_revision = pinned, false under latest, which takes
main even though the spec pins one. False when nothing is pinned.
pinned_commitrequired string The commit the spec pins the package to — its revision when that is
a full commit hash; empty when it pins none.
precisionrequired string q8_0, f16, … — empty when the spec names none.
recommendedrequired boolean audio.cpp's recommended package for the family.
reporequired string Hugging Face repo the files come from; empty = no download source in
the spec, so the package cannot be installed from here.
revisionrequired string The revision the spec names for the package's repo (main, or a
commit), as written; empty when it names none.
servedrequired boolean An enabled audio model loads this package's weights: the weights file
lmgw takes the row to load (the GGUFs under its root, narrowed by its
weight_id) belongs to this package and no other — or, for a package
without GGUFs, the package is downloaded and the only one under the
row's root. Implies the weights are on disk.
served_byrequired array of string The model_ids of the rows that serve it.
serving_unclearrequired string Non-empty when a row points at this package's files without telling
it apart from another package (its root holds several and no
weight_id picks one): what it is and how to settle it, one sentence
per such row.
sizerequired string Human size of the downloaded files, empty until they are on disk.
suggested_moderequired string
suggested_model_idrequired string
suggested_pathrequired string
suggested_taskrequired string
unavailable_reasonrequired string Why this package cannot be installed from here, in upstream's words —
a licence that forbids redistribution, a GGUF build not published yet.
Empty when it can.
unpublished_filesrequired array of string Spec files the repo does not publish, as of the refresh that listed
it at the revision a download takes (the pin, when followed): the spec
is ahead of the weights, and a download would be refused.

AudioRoute

The route a kept audio group's one cell asks: its plan's variant.

One of: string (/v1/audio/speech, through /audio-lab/api/speech.); string (/v1/audio/transcriptions, through /audio-lab/api/transcriptions.); string (/v1/audio/transcriptions/details (?details=1).); string (/v1/audio/alignments, through /audio-lab/api/alignments.); string (/v1/tasks/run, through /audio-lab/api/tasks/run.); string (/v1/tasks/stream (?stream=1).)

AudioRunning

A running audio container.

in_flightrequired integer (uint64)
staterequired string

AudioSettings

The audio class settings: the same fields as the chat/aux class settings,
plus the engine fields that flow into every audio model's own
server.json.

backendrequired string
busy_timeout_msrequired integer (int64) How long a request waits for a model that is already running before it
fails with 503 server_busy, in ms. **0 = wait forever.**
catalog_revisionrequired string What an audio catalog download takes: pinned (the commit the spec
pins, main where it pins none — the default) or latest (main).
devicerequired integer (int64)
extra_run_argsrequired array of string
idle_unload_msrequired integer (int64) Unload the resident model after this long without a load or run,
freeing its VRAM while the container stays up. **0 = never.**
imagerequired string
lazy_loadrequired boolean
max_request_body_mbrequired integer (int64) Largest request body audiocpp_server buffers, in MiB. **0 = leave the
key out**, so the engine's own 2 GiB default applies.
min_free_memory_mbrequired integer (int64) Free memory (host and GPU) a model load must leave behind, in MiB.
**0 = no guard.**
models_dirrequired string
public_prefixrequired string
request_timeout_secondsrequired integer (uint64) Per-request ceiling for the class, in seconds. 0 = the maximum possible — no deadline of
lmgw's own.
threadsrequired integer (int64)
voice_dirrequired string Shared voice library as the container sees it (/models/voices by
default — the Audio lab's own clips). Empty = no library.
voice_transcribe_aliasrequired string The speech-to-text model that writes voice-library clip transcripts
(its configured fallback answers as for any request). Empty = none:
nothing is transcribed automatically.

AudioSettings2

The audio_settings preset (labs-store design §5): the speech panel's
fields and the PCM format a stream is assembled with.

pcmrequired PcmFormat
speechrequired SpeechForm

AudioSettings2Input

The audio_settings preset (labs-store design §5): the speech panel's
fields and the PCM format a stream is assembled with.

pcm PcmFormatInput Default {"bits":"16","channels":"1","rate":"24000"}.
speech SpeechFormInput Default {"input":"","instructions":"","language":"","max_tokens":"","model":"","options":"","reference_text":"","response_format":"","seed":"","speed":"","stream":false,"voice":"","voice_ref":""}.

AudioSettingsPatch

backend string | null Default null.
busy_timeout_ms integer | null Default null.
catalog_revision string | null pinned | latest. Set by the save, not by apply: it is not part
of the class's container definition. Default null.
device integer | null Default null.
extra_run_args array | null Default null.
idle_unload_ms integer | null Default null.
image string | null Default null.
lazy_load boolean | null Default null.
max_request_body_mb integer | null Default null.
min_free_memory_mb integer | null Default null.
models_dir string | null Default null.
public_prefix string | null Default null.
request_timeout_seconds integer | null Default null.
threads integer | null Default null.
voice_dir string | null Default null.
voice_transcribe_alias string | null Checked by the save (a local asr row, or empty), not by apply. Default null.

AudioSpeechRequest

OpenAI's TTS shape plus audio.cpp's own request options, forwarded with model rewritten to the upstream's own id; a row's configured voice presets apply on top. input may carry inline tags ([laughs], or a stage direction such as (sighs)): rendered by a model whose capabilities.speech.inline_tags says so, stripped everywhere else — never read out. An input of nothing but tags is 400 empty_input, refused before any model is started.

inputrequired string The text. A local model whose engine refuses a character its package lacks (Supertonic) is sent an equivalent it has in its place, or nothing; the x-lmgw-speech response header names each one. An input left with nothing to say (a lone emoji) is 400 empty_input, refused before any model is started.
instructions string A speaking style, or the description a voice-design model builds its voice from (required there: 400 instructions_required without one, unless the row has a default). Dropped for a model that reads none: capabilities.speech.instructions says which, and the x-lmgw-speech response header says when.
language string An ISO 639-1 code or BCP-47 tag; a local model gets it in its own vocabulary.
modelrequired string
response_format string
speed number
stream_format string Streams PCM16 (with response_format pcm) as speech.audio.delta events (sse) or as raw chunked PCM (audio). A local model streams only when its row runs in streaming mode; an offline row is 400 streaming_unsupported before anything starts (capabilities.speech.streaming says which). The x-lmgw-sample-rate response header states the PCM's rate. One of sse, audio.
voice string A row's own voice preset id, when it defines any (GET /v1/audio/voices). A voice-library clip with no transcript, for a model that cannot clone one without, is 400 voice_needs_transcript before anything starts (lmgw.needs_transcript in the voice list); send reference_text, or transcribe the clip in the dashboard's Audio lab. A local model whose audio.cpp image lacks eSpeak NG is 400 audio_image_lacks_espeak.

AudioTiming

The engine's own account of one inference. Each figure is absent when the
engine leaves it out.

audio_duration_ms number | null Milliseconds of audio the engine processed.
rtf number | null Real-time factor: wall_ms over audio_duration_ms; below 1 is
faster than real time.
wall_ms number | null Wall-clock milliseconds of the inference.

AudioTranscription

textrequired string

AudioTranscriptionDetails

The same transcription, plus the detail arrays the plain route leaves out.

segments array of object
speaker_turns array of object
textrequired string
words array of object

AudioTranscriptionsRequest

multipart/form-data (also accepted as application/json with the same fields but no upload: instead of file, audio names a clip by its path on the model server's own filesystem, e.g. /models/clip.wav, and the body is relayed with model rewritten; the multipart form is what real clients send).

filerequired string (binary)
language string
modelrequired string
prompt string
response_format string
temperature number

AudioVoices

lmgw's own route. A local audio model is answered from lmgw's catalog without starting it (?probe=engine asks its own server, starting it); a remote one is asked.

lmgw object Only on a local audio model answered from lmgw's catalog (x-lmgw-voices-source: config).
defaultrequired string | null What speaks when a request names no voice.
engine_askedrequired boolean
entriesrequired array of object
idrequired string
kindrequired string One of preset, library, native, embedding.
sendrequired string Where lmgw puts the name in the engine's request; clients always send it as voice. One of voice, options.voice_id.
transcript boolean A library clip's transcript is recorded.
heldrequired boolean The GPU hold (or a benchmark run) holds the card and the model has no fallback: the list stands, its speech is refused (503 gpu_hold) until the hold is released.
missingrequired array of string Voices the spec names whose file the package lacks.
needs_transcriptrequired boolean The model cannot clone a library clip without its transcript: speech with an entry whose transcript is false is refused (400 voice_needs_transcript) until it has one (the dashboard's Audio lab, Transcribe).
sourcerequired string One of config.
voicesrequired array of string Every name the model answers to as voice, sorted; for a probe of the engine or of a remote upstream, as that source sent it.

AuxModel

An aux container model row — embedders, rerankers and decision models
alike.

argsrequired array of string
backendrequired string | null cpu runs the row on the CPU (no VRAM charged, served under the GPU
hold); null runs it on the GPU.
batch_sizerequired integer | null --batch-size; null takes llama-server's default.
ctx_sizerequired integer | null
enabledrequired boolean
extra_run_argsrequired array | null Per-model podman run args override; None inherits the aux
class settings' extra_run_args.
fallbackrequired string | null The model or alias that answers whenever this one cannot (the GPU
hold, VRAM outside lmgw, background traffic deferred, a disabled
row), as written. None = no fallback.
gguf_pathrequired string
idrequired integer (int64)
idle_secondsrequired integer (int64)
imagerequired string | null Per-model container image override;
None inherits the aux class settings' image.
kindrequired string embed | rerank | decision.
mmproj_pathrequired string | null A projector (--mmproj), relative to the aux models dir.
model_idrequired string
poolingrequired string | null
threadsrequired integer | null --threads; null renders none on the GPU, and on the CPU this
machine's physical cores (the logical CPU count where the core
topology cannot be read) unless the row's extra args name a count.
ubatch_sizerequired integer | null --ubatch-size; null takes llama-server's default.
warm_startrequired boolean Start this model's own container at app launch.

AuxModelDetail

An aux (embedding, rerank or decision) model read back.

backendrequired string | null cpu runs the row on the CPU; null runs it on the GPU.
batch_sizerequired integer | null --batch-size; null takes llama-server's default.
command_linerequired string The podman run … command line this model renders to.
ctx_sizerequired integer | null
downloaded_fromrequired DownloadedFrom | null
enabledrequired boolean
endpointrequired string The route that serves it: /v1/embeddings, /v1/rerank or
/v1/systemone.
extra_argsrequired array of string One entry per llama-server option (round-trips with the patch field).
extra_run_argsrequired array | null podman run args override, one entry per argument; null inherits.
fallbackrequired string | null The one fallback (openai egress design §14.2), as written; null =
none.
fit_noterequired FitNote | null The note of a context fitted to the graphics card (find-a-model
design D26): Get it's or "Fit again"'s; None when the row's
context isn't a fit's shorter one.
gguf_pathrequired string
gguf_presentrequired boolean
idrequired integer (int64)
idle_secondsrequired integer (int64)
imagerequired string | null Container image override; null inherits the aux class's.
kindrequired string embed, rerank or decision.
licencerequired ModelLicence | null The licence the GGUF header states; null when it states none.
mmproj_pathrequired string | null A projector (--mmproj), relative to the aux models dir.
model_idrequired string
poolingrequired string | null
problemsrequired array of string Static findings; empty is not proof it loads.
public_namerequired string The name clients call it by, with the aux prefix.
sourcerequired string hf or manual.
threadsrequired integer | null --threads; null renders none on the GPU, and on the CPU this
machine's physical cores (the logical CPU count where the core
topology cannot be read) unless the row's extra args name a count.
threads_in_effectrequired integer | null The thread count its container starts with: threads, else a count
the extra args name, else on the CPU this machine's cores. Null when
nothing names one (a GPU row: llama-server picks) or the args' value
is not a number.
threads_sourcerequired AuxThreadsSource Where threads_in_effect comes from.
ubatch_sizerequired integer | null --ubatch-size; null takes llama-server's default.
warm_startrequired boolean

AuxModelView

deferrals_24hrequired integer (uint64) LocalModelView::deferrals_24h, for this row's public_name.
licencerequired ModelLicence | null The licence the row's GGUF header states; null when it states none
or the file cannot be read.
modelrequired AuxModel
public_namerequired string
threads_in_effectrequired integer | null The thread count its container starts with: the row's threads, else
a count its extra args name, else on the CPU this machine's cores.
Null when nothing names one (a GPU row: llama-server picks) or the
args' value is not a number.
threads_sourcerequired AuxThreadsSource Where threads_in_effect comes from.

AuxRouterSettings

The aux class settings: the chat/aux class fields, flat beside the prefix
of the decision rows (decision-models design §3.10). Dereferences to the
class fields.

decision_prefixrequired string Namespace of the decision rows (decide → decide/<model id>);
embedders and rerankers are under public_prefix. Empty = bare ids.
extra_run_argsrequired array of string Class default; a model's own extra_run_args overrides it.
imagerequired string Class default; a model's own image overrides it.
models_dirrequired string
public_prefixrequired string
request_timeout_secondsrequired integer (uint64) Per-request ceiling for the class, in seconds: how long lmgw waits for
an answer to start, and how long a streamed answer may then go
without an event before lmgw ends it with an error. **0 = the maximum
possible** — no deadline of lmgw's own. One per class since the four
stopped sharing a single 600 s constant.

AuxRouterSettingsPatch

The aux class's patch: the class fields and the decision rows' prefix
(decision-models design §3.10). Its own type rather than a flattened
RouterSettingsPatch, because a patch denies unknown fields and serde
cannot do that through a flatten.

decision_prefix string | null The prefix decision rows are exposed under (decide); "" = bare ids. Default null.
extra_run_args array | null Default null.
image string | null Default null.
models_dir string | null Default null.
public_prefix string | null Default null.
request_timeout_seconds integer | null Default null.

AuxThreadsSource

Where an aux row's thread count comes from.

One of: string (The row's own threads.); string (A --threads/-t in the row's extra args, rendered as written.); string (This machine's physical cores: a row on the CPU that names no count.); string (Cores where the core topology could not be read: the
logical CPU count stands in.); string (No count: a GPU row that names none renders no --threads, and
llama-server picks.)

BaseUrl

labelrequired string
urlrequired string

BatchColumn

One column of the file.

jsonrequired boolean Every non-empty value is a JSON object or array (in JSONL, written as
one or as a string holding one): the state's JSON mode fits it.
namerequired string

BatchFormat

The uploaded file's format.

One of: string (RFC 4180 with a header row.); string (One JSON object per line; its columns are its top-level keys.)

BatchFromAgentSkip

Why a row of the apply job is no item.

One of: string (The model was never asked about it (no id, or its fetch failed): it
has no state to ask again.); string (Its call failed and its output is still the fallback the failure
gave it: no answer, and no label of the owner's.)

BatchFromAgentSkipped

A row of the apply job that is no item.

idrequired string The row's id.
kindrequired BatchFromAgentSkip
reasonrequired string Why it is no item, with the row's error.

BatchMapping

Which columns a set run reads. A column is named by its header; a
column whose header is empty cannot be mapped (give it a name in the
file).

keyrequired string | null The column holding each item's own key (a ticket number, a row id):
kept per item and carried into both exports, so an answer can be
matched back to its source row. Absent, none; an empty value is no
key.
labelsrequired object Per question id, the column holding its expected answer: an option's
name (choice); yes, no, true, false, 1 or 0 (noul); a level's
exact text or its index, as the whole column reads
(score_labels). An empty value is no label.
score_labelsrequired object Per score question id, how its label column reads. A question not
named here reads as its column does: as level texts when every
non-empty value is a level's exact text, as indices when every one is
an index in range. When both fit and disagree (a scale written "1" to
"5" and values "1" to "4"), or the column mixes the two, the input is
refused until this says which.
staterequired string The column holding each item's state. Required.
state_moderequired StateMode How that column's values are sent: as text, or as JSON (each value
must parse).

BatchMappingInput

Which columns a set run reads. A column is named by its header; a
column whose header is empty cannot be mapped (give it a name in the
file).

key string | null The column holding each item's own key (a ticket number, a row id):
kept per item and carried into both exports, so an answer can be
matched back to its source row. Absent, none; an empty value is no
key. Default null.
labels object Per question id, the column holding its expected answer: an option's
name (choice); yes, no, true, false, 1 or 0 (noul); a level's
exact text or its index, as the whole column reads
(score_labels). An empty value is no label. Default {}.
score_labels object Per score question id, how its label column reads. A question not
named here reads as its column does: as level texts when every
non-empty value is a level's exact text, as indices when every one is
an index in range. When both fit and disagree (a scale written "1" to
"5" and values "1" to "4"), or the column mixes the two, the input is
refused until this says which. Default {}.
state string The column holding each item's state. Required. Default "".
state_mode StateMode How that column's values are sent: as text, or as JSON (each value
must parse). Default "text".

BatchProblem

What stops a file from being run: a line that does not read, a column
that is not there, a state or a label that is no answer.

columnrequired string | null The column at fault.
kindrequired BatchProblemKind
linerequired integer | null The line the row starts on, from 1 (the header is line 1 of a CSV);
null for the mapping.
messagerequired string The whole problem in a sentence, row and value included.
questionrequired string | null The question it is about (a label, a labels or score_labels
entry); null for the file, the state and the state or key column.
rowrequired integer | null The item's number, from 1; null for the file or the mapping.
valuerequired string | null The value at fault, as read.

BatchProblemKind

What kind of problem a BatchProblem is, for a client that acts on one
without reading its message.

One of: string (The file itself: a line that does not read, a header, no rows.); string (The mapping: a column it names that is empty, missing or named twice,
or a labels or score_labels entry naming no question it can take.); string (A row's state: empty, or no JSON in JSON mode.); string (A row's label that is no answer of its question.); string (A score question's label column reads both as level texts and as
indices with different meanings, or mixes the two: the mapping's
score_labels for question has to say which.)

BatchStatus

Where a set run is.

One of: string (Its job is answering items now.); string (Every item has a run.); string (Cancelled with items left; Resume runs the rest.); string (Its job ended with items left: a restart of the gateway, a failure
(job_error says which: lmgw refusing before the model was asked,
such as the GPU hold, ends the job too), or a job row since pruned.
Resume runs the rest.); string (No job ran it yet.)

BatchView

A set run.

cancel_requestedrequired boolean A Cancel already went to the job that runs it now: the next Cancel
aborts the calls in flight (their answers are not kept). False when
no job runs it.
concurrencyrequired integer (uint32)
created_atrequired string
donerequired integer (uint64) Items with a run, whatever it answered: the progress.
failedrequired integer (uint64) Of those, the runs the route did not answer with a 2xx.
idrequired integer (int64)
job_errorrequired string | null That job's error when it failed (interrupted by shutdown after a
restart).
job_idrequired integer | null The last job that ran it (no longer listed once pruned): the live
one while it runs.
labrequired LabKind
labelledrequired integer (uint64) Items with at least one expected answer.
mappingrequired BatchMapping
modelrequired string
preset_idrequired integer | null The saved set it ran; null for an unsaved set, or one deleted
since.
preset_namerequired string | null The saved set's name, when it is still there.
setrequired QuestionSet The set as run: later edits of the saved set do not change it.
source_namerequired string The uploaded file's name.
statusrequired BatchStatus
totalrequired integer (uint64) Items in all.
unreadablerequired integer (uint64) Of those, the 2xx runs that do not read as an answer to every
question of the set (the metrics count them per question as
unreadable).

BenchBlocked

messagerequired string The sentence to show.
reasonrequired BlockedReason
run_idrequired integer | null The running run, for the run_going reason.

BenchComparison

A run against another: the previous comparable run for bench_run.

base_created_atrequired string
base_run_idrequired integer (int64)
comparablerequired boolean Same model file, settings hash, suite version and GPU.
improvementsrequired integer (uint32)
metricsrequired array of MetricDelta
not_comparablerequired array of string Why not, when not.
probesrequired array of ProbeChange
regressionsrequired integer (uint32) Metrics and probes flagged each way (not_same_point and
missing count for neither).
threshold_pctrequired number (double)

BenchOverrides

What a run changes about the row's container, and only about the
bench container. None (and false, 0) is "as the row says".

batch_sizerequired integer | null
cache_type_krequired string | null
cache_type_vrequired string | null
ctx_sizerequired integer | null
flash_attnrequired string | null auto / on / off.
imagerequired string | null Another image, e.g. an Engines page build (comparing two builds is two runs
of one row with two images).
kv_unifiedrequired boolean | null
n_gpu_layersrequired integer | null
no_draftrequired boolean Run without the row's speculative drafter.
parallelrequired integer | null
rungrequired integer (uint32) A ladder row's rung, 0 = base.
ubatch_sizerequired integer | null

BenchRun

One stored run, whole: every column, the JSON ones typed.

buildrequired BuildIdentity
command_linerequired string
created_atrequired string
errorrequired string | null
finished_atrequired string | null
gpurequired GpuIdentity
idrequired integer (int64)
image_idrequired string | null
image_refrequired string
job_idrequired integer | null
modelrequired ModelIdentity
notesrequired string
paramsrequired SuiteParams
probesrequired ProbeReport
resultsrequired RunResults
settingsrequired BenchSettings
settings_hashrequired string
statusrequired BenchStatus
status_reasonrequired string | null Why it ended the way it did, in one word where there is one
(hold, canceled, shutdown).
suite_versionrequired integer (uint32)
timelinerequired Timeline
unreadable array of string The JSON columns that did not decode, each as "<column>: <why>". Each reads as its empty
default here, so the run
is comparable with nothing ):
read as empty, it would compare as "measured nothing".

BenchRunSummary

One row of the runs table.

build_inforequired string | null
commitrequired string | null
completerequired boolean Every selected phase finished without an error.
created_atrequired string
engine_slugrequired string | null dev.lmgw.slug, org.opencontainers.image.version, the commit and
/props build_info — whichever the build has.
errorrequired string | null
finished_atrequired string | null
gpu_namerequired string | null
headlinerequired Headline
idrequired integer (int64)
image_refrequired string
improvementsrequired integer | null
job_idrequired integer | null
model_idrequired string
notesrequired string
phasesrequired array of Phase
previous_idrequired integer | null The previous comparable run, when there is one.
probes_judgedrequired integer (uint32)
probes_passedrequired integer (uint32) Probes that passed, and probes that gave a verdict (pass, fail,
error — not info or skipped).
quantrequired string | null
regressionsrequired integer | null Against it, at the answer's threshold_pct.
repetitionsrequired integer (uint32)
rungrequired integer (uint32)
statusrequired BenchStatus
status_reasonrequired string | null
suite_versionrequired integer (uint32)
throttledrequired boolean
unreadable array of string The stored columns that did not decode. Such a
run is listed with what could be read, and compared with nothing.
versionrequired string | null

BenchSettings

The settings of a run: what the bench container runs,
after the overrides.

**The settings hash covers params, args and extra_run_args only**: the image is the build
identity and may differ between
comparable runs (that is the point of comparing builds), the weights file
is the model identity, and overrides only says how these values came
about — the same effective flags reached with or without an override are
the same settings.

argsrequired array of string The row's freeform llama-server flags (minus the drafter's, with
no_draft).
extra_run_argsrequired array of string podman run flags (GPU devices, …): the row's, or its class's.
gguf_pathrequired string The weights file, relative to the chat models dir (the rung's own for
a ladder rung).
imagerequired string The resolved image the run starts (override, row, or class default).
overridesrequired BenchOverrides
paramsrequired any The effective LlamaParams, as the row stores them.
rungrequired integer (uint32)

BenchStatus

How a run ended.

One of: string; string (Ended by something other than a cancel request — the GPU hold
switching on (status_reason: "hold").); string (Found running at boot: lmgw went away mid-run.)

BenchStop

One container a start stops — what the confirmation lists.

busyrequired boolean Serving lmgw requests right now, or still starting: the run waits for
it to drain rather than cutting it off. A client generating on the
container's own port is only seen at start time (/slots).
classrequired string chat | aux | audio | image.
container_namerequired string
in_flightrequired integer (uint)
model_idrequired string
staterequired string The registry's state: starting | ready | stopping.

BesideTerms

What else is on the card, for the beside measure.

outside_bytesrequired integer | null Other programs' use; None when it couldn't be told (the note says
why), and then the measure is the card less lmgw's models alone.
residents_bytesrequired integer (uint64) lmgw's own models on the card now.

BlockedReason

Why a run cannot start now.

One of: string; string (The GPU hold is on: a benchmark is lmgw using VRAM.); string (Another run holds the card; run_id names it.); string (No chat row has this id.); string (The id names an aux, audio or image row.); string (rung is past the row's top rung.); string (The image is not on this machine: podman run would pull it and the
load phase would time the download.); string (The chat models dir is not configured, or the weights are not in it.); string (lmgw has just started and has not yet adopted the containers a
previous lmgw left running: the drain could not see them yet.); string (The image override is not an image reference: it starts with -
(podman would read it as a flag) or holds whitespace.)

Build

One builds row: the editable definition plus its identity.

archrequired array | null Compute capabilities / GPU targets (["89"], ["86", "89"],
["gfx1100"]). None = auto-detect from the host GPUs.
backendrequired GpuBackend
build_argsrequired string Extra --build-arg lines, one KEY=VALUE per line.
ccacherequired boolean
ccache_max_sizerequired string CCACHE_MAXSIZE, e.g. 10G, 500M; 0 is ccache's "no limit".
cpusrequired string | null --cpuset-cpus (0-15, 0,2,4). None = all cores. Needs podman to
have the cpuset cgroup controller (rootless: delegated to
user@.service); without it a save and a run refuse, naming the fix.
CPUs the host does not have online are refused the same way.
created_atrequired string
cuda_versionrequired string | null None = the preset's default for the engine.
dockerfilerequired string | null Repo-relative Dockerfile path. None = the preset's candidates.
editsrequired array | null None = the preset's edits for the resolved Dockerfile; Some = this
explicit, customized list (which may be empty: no edits at all).
enginerequired Engine
extrasrequired array of BuildExtra Merged on top of git_ref, in order.
forgerequired Forge
idrequired integer (int64)
keep_layersrequired boolean Keep podman's layer cache (--layers=true). Off by default: no
multi-GiB intermediates are left behind.
keep_runsrequired integer | null How many previous runs' immutable tags to keep. None = keep all.
namerequired string
notesrequired string
refrequired string Branch, tag or commit to build on.
repo_urlrequired string A preset or any git URL (https://, http://, ssh://,
git@host:path, file://).
slugrequired string Becomes the tag. Tag charset, bounded so the longest immutable tag
fits 128 characters, and immutable once the build has a run.
targetrequired string | null Final build stage. None = the preset's candidates.
updated_atrequired string

BuildEdit

One Dockerfile edit: a literal find/replace of
**every** occurrence, applied to a copy of the Dockerfile, never to the
checkout, in list order (a later edit sees what the earlier ones wrote).
Each one is logged as applied or not matched; a required edit that does
not match fails the run.

find and replace may carry {{ccache_id}}, {{npm_cache_id}},
{{ccache_max_size}}, {{ccache_shared_mount}}/{{ccache_seed}} and
{{npm_shared_mount}}/{{npm_seed}}, filled in per run, so an edit list
stays the same when only a cache id or the size changes. The last two
pairs render empty for a plain build; with extras they mount the shared
ccache/npm cache read-only and seed the build's own from it. name and
role are for the log and the ccache switch; neither changes the image,
so neither is hashed.

findrequired string
name string Short label for the log and the editor (ccache-mount). May be empty.
replacerequired string
requiredrequired boolean
rolerequired EditRole

BuildEditInput

One Dockerfile edit: a literal find/replace of
**every** occurrence, applied to a copy of the Dockerfile, never to the
checkout, in list order (a later edit sees what the earlier ones wrote).
Each one is logged as applied or not matched; a required edit that does
not match fails the run.

find and replace may carry {{ccache_id}}, {{npm_cache_id}},
{{ccache_max_size}}, {{ccache_shared_mount}}/{{ccache_seed}} and
{{npm_shared_mount}}/{{npm_seed}}, filled in per run, so an edit list
stays the same when only a cache id or the size changes. The last two
pairs render empty for a plain build; with extras they mount the shared
ccache/npm cache read-only and seed the build's own from it. name and
role are for the log and the ccache switch; neither changes the image,
so neither is hashed.

find string Default "".
name string Short label for the log and the editor (ccache-mount). May be empty.
replace string Default "".
required boolean Default false.
role EditRole Default "other".

BuildExtra

One entry of a build's ordered extras list: something merged on top
of the base ref, in order.

With no pin, a run follows the head. A pin is a full commit SHA and
builds exactly that commit.

One of: object (A PR (GitHub) or MR (GitLab) of the build's own repo_url.); object (A branch, tag or commit of another remote: a fork branch, an upstream
llama.cpp PR on top of ik via refs/pull/N/head, …)

BuildIdentity

The build the run measured, filled in by the benchmark runner from the image and its labels,
plus /props build_info where the engine reports it.

build_inforequired string | null
commitrequired string | null dev.lmgw.base, else org.opencontainers.image.revision.
engine_slugrequired string | null dev.lmgw.slug.
git_refrequired string | null dev.lmgw.ref.
image_idrequired string | null
image_refrequired string
labelsrequired object Every label, verbatim.
reporequired string | null dev.lmgw.repo.
versionrequired string | null org.opencontainers.image.version.

BuildRun

One build_runs row: append-only, and kept when its
build is deleted (build_id becomes None).

base_sharequired string | null
build_idrequired integer | null None once the build has been deleted.
cfg_hashrequired string | null
enginerequired Engine
errorrequired string | null
finished_atrequired string | null
idrequired integer (int64)
image_idrequired string | null Full image ID (no sha256:).
image_presentrequired boolean | null Whether image_id is on this machine now, read from one podman image
listing per answer. image_id is history (which image the run made)
and stays after the image is deleted; this says whether the image can
still be tagged, verified or deleted. None when the run made no image,
and when podman could not be asked: unknown is not "deleted". Filled by
the builds and build_get ops, never stored.
inputsrequired BuildRunInputs
job_idrequired integer | null The background job that executed it (JobKind::BuildRun). Not a
foreign key: job rows are pruned by the jobs retention settings, runs
are not.
log_pathrequired string | null The full, never-truncated build log.
promotedrequired boolean lmgw last moved the build's moving tag to this run's image. At most
one run per build carries it. podman is the source of truth: a tag
moved by hand is not reflected here.
size_bytesrequired integer | null
slugrequired string Snapshot of the build's slug and engine, so a run stays readable after
its build is gone.
started_atrequired string
statusrequired BuildRunStatus
tagsrequired array of string Every tag this run put on its image (immutable, and the moving tag
when promoted).
triggerrequired BuildTrigger
verifyrequired any The verify checks' results, shaped by the executor.

BuildRunInputs

A run's inputs column: the full snapshot.

cfg_hashrequired string | null Full sha256 hex of the image-affecting inputs; the immutable tag
carries its first 6 characters. None until resolved.
configrequired BuildSpec The build definition exactly as it was when the run started — a run
outlives edits to its build, and the build itself.
resolvedrequired ResolvedInputs | null None until the run has resolved its refs (phase 1).

BuildRunStatus

Where a build run is, or how it ended.

One of: string; string (Still going — including waiting for the machine-wide build lock, which
the job detail names.); string (Built, verified and promoted: the moving tag points at its image.); string (Built, but not GPU-verified (GPU hold, or a CUDA OOM while probing).
Not promoted; **Verify now** can finish the job later.); string (Built, and a verify check failed. Not promoted.); string (Did not produce an image.); string (The immutable tag for these exact inputs already existed and was
verified; nothing was built.)

BuildSetAction

build_set's action.

string

BuildSpec

Every editable field of a build — the builds row minus its id and
timestamps. What the editor sends, what duplicate copies, and what a run
snapshots into its inputs as "the config as built".

None on the optional fields means **auto**, resolved by the run from the
engine preset and the host, and the resolved value is recorded on the run:
cuda_version → the preset default, arch → the host GPUs' compute
capabilities, dockerfile/target → the preset's candidates, edits →
the preset's edits for the resolved Dockerfile.

archrequired array | null Compute capabilities / GPU targets (["89"], ["86", "89"],
["gfx1100"]). None = auto-detect from the host GPUs.
backendrequired GpuBackend
build_argsrequired string Extra --build-arg lines, one KEY=VALUE per line.
ccacherequired boolean
ccache_max_sizerequired string CCACHE_MAXSIZE, e.g. 10G, 500M; 0 is ccache's "no limit".
cpusrequired string | null --cpuset-cpus (0-15, 0,2,4). None = all cores. Needs podman to
have the cpuset cgroup controller (rootless: delegated to
user@.service); without it a save and a run refuse, naming the fix.
CPUs the host does not have online are refused the same way.
cuda_versionrequired string | null None = the preset's default for the engine.
dockerfilerequired string | null Repo-relative Dockerfile path. None = the preset's candidates.
editsrequired array | null None = the preset's edits for the resolved Dockerfile; Some = this
explicit, customized list (which may be empty: no edits at all).
enginerequired Engine
extrasrequired array of BuildExtra Merged on top of git_ref, in order.
forgerequired Forge
keep_layersrequired boolean Keep podman's layer cache (--layers=true). Off by default: no
multi-GiB intermediates are left behind.
keep_runsrequired integer | null How many previous runs' immutable tags to keep. None = keep all.
namerequired string
notesrequired string
refrequired string Branch, tag or commit to build on.
repo_urlrequired string A preset or any git URL (https://, http://, ssh://,
git@host:path, file://).
slugrequired string Becomes the tag. Tag charset, bounded so the longest immutable tag
fits 128 characters, and immutable once the build has a run.
targetrequired string | null Final build stage. None = the preset's candidates.

BuildSpecInput

Every editable field of a build — the builds row minus its id and
timestamps. What the editor sends, what duplicate copies, and what a run
snapshots into its inputs as "the config as built".

None on the optional fields means **auto**, resolved by the run from the
engine preset and the host, and the resolved value is recorded on the run:
cuda_version → the preset default, arch → the host GPUs' compute
capabilities, dockerfile/target → the preset's candidates, edits →
the preset's edits for the resolved Dockerfile.

arch array | null Compute capabilities / GPU targets (["89"], ["86", "89"],
["gfx1100"]). None = auto-detect from the host GPUs. Default null.
backend GpuBackend Default "cuda".
build_args string Extra --build-arg lines, one KEY=VALUE per line. Default "".
ccache boolean Default true.
ccache_max_size string CCACHE_MAXSIZE, e.g. 10G, 500M; 0 is ccache's "no limit". Default "10G".
cpus string | null --cpuset-cpus (0-15, 0,2,4). None = all cores. Needs podman to
have the cpuset cgroup controller (rootless: delegated to
user@.service); without it a save and a run refuse, naming the fix.
CPUs the host does not have online are refused the same way. Default null.
cuda_version string | null None = the preset's default for the engine. Default null.
dockerfile string | null Repo-relative Dockerfile path. None = the preset's candidates. Default null.
edits array | null None = the preset's edits for the resolved Dockerfile; Some = this
explicit, customized list (which may be empty: no edits at all). Default null.
engine Engine Default "llama".
extras array of BuildExtra Merged on top of git_ref, in order. Default [].
forge Forge Default "plain".
keep_layers boolean Keep podman's layer cache (--layers=true). Off by default: no
multi-GiB intermediates are left behind. Default false.
keep_runs integer | null How many previous runs' immutable tags to keep. None = keep all. Default null.
name string Default "".
notes string Default "".
ref string Branch, tag or commit to build on. Default "".
repo_url string A preset or any git URL (https://, http://, ssh://,
git@host:path, file://). Default "".
slug string Becomes the tag. Tag charset, bounded so the longest immutable tag
fits 128 characters, and immutable once the build has a run. Default "".
target string | null Final build stage. None = the preset's candidates. Default null.

BuildTrigger

What started a run.

One of: string (A click on the Engines page (or the /api op behind it).); string (lmgw__build_run.); string (A scheduled run.)

BuildUpdateEntry

One build's slot in a build_updates_check response.

build_idrequired integer (int64)
updaterequired UpdateStatus | null

BuildView

One row of the Builds tab: a build plus what it is doing and
what is using it right now. current_run is the promoted run — its
image holds the moving tag; last_run is simply the most recent one,
which may be a failed or unverified attempt after current_run.

buildrequired Build
current_runrequired BuildRun | null
last_runrequired BuildRun | null
live_job_idrequired integer | null The JobRow.id of this build's run while one is live.
moving_tagrequired string The build's moving tag **on the answering instance**: <engine repo>:<slug>
in production, localhost/lmgw-dev-<engine repo>:<slug> on a dev
instance (which tags into a namespace of its own). Computed by the
server, the same way its runs tag, so it is right for a build that
has never run too — prefer it to computing the tag client-side.
updaterequired UpdateStatus | null
used_byrequired array of ImageUse

CancelKind

What cancelling a running image job does (design §5.4).

One of: string (The image server's own cancel: the job is dropped, the model stays.); string (The image server cannot stop a running picture, and this call is the
model's only request: lmgw stops its container, and the next picture
loads it again.); string (The image server cannot stop a running picture, and another request
uses the model: the call stops waiting, the picture finishes in the
background and is thrown away.)

CandidateAliasPreview

candidate_alias_set action=preview: the alias editor's live answer to
"what would saving this draft mean right now". It runs the validation and
derivation of a save over the draft and writes nothing.

No single refusal aborts the answer: a draft is the normal state of an
editor nobody has saved yet, so the first problem is error (and ok is
false) while the derivation goes on with the most useful stand-in it has.
Every key is always there.

addablerequired array of AddableCandidate Every enabled local chat model not yet a candidate, and which of the
enabled facets it would lack if added: the "add candidate" list's
filter.
advisoriesrequired array of string Worth flagging, but not an error.
common_facetsrequired array of string Facets every candidate currently supports.
context_lengthrequired integer | null Minimum across routable_candidates; null if any of them is unknown or nothing
is routable.
enabled_facetsrequired array of string The facets the draft would have enabled (wire facet names).
errorrequired string | null The first refusal a save of this draft would make, if any.
fallback_usablerequired boolean The alias fallback resolves and is not local.
max_output_tokensrequired integer | null Same rule as context_length.
okrequired boolean false when error is set.
problemsrequired array of string What is wrong with a candidate or the fallback, in prose.
routable_candidatesrequired array of string Candidates the gate may route to right now, in list order.
unsupported_byrequired object Facet wire name -> candidate ids that do not support it.

CandidateAliasSaved

candidate_alias_set's answer to create, update (also enable and
disable) and delete: the saved row's id, and for a write that leaves a
row a fresh derivation of what it means right now (the shape the editor
and lmgw__models read), so a caller never needs a second call to see
whether the alias it just saved is usable.

The derived keys are absent for delete, and for a create or update
whose row was deleted by a concurrent call between the write and the read:
the write itself succeeded, so that answer is {ok, id, message}.

advisories array of string Worth flagging, but not an error: a candidate with --cache-ram 0, a
fallback that lacks an enabled facet.
common_facets array of string Facets every candidate currently supports: the ceiling a save may enable.
context_length integer | null Minimum across routable_candidates; null if any of them is unknown or nothing
is routable. Absent where the derived keys are.
enabled_facets array of string The stored enabled facet set (wire facet names).
fallback_notes array of string What the save says about the fallback (openai egress design §14.2):
what a chat fallback lacks or adds, a type lmgw could not check, the
same upstream, the references a rename rewrote, the rows a delete
leaves without a working fallback. Absent when there is nothing to
say.
fallback_usable boolean The alias fallback resolves and is not local.
idrequired integer (int64) The row's id.
max_output_tokens integer | null Same rule as context_length.
messagerequired string What was done, for a person to read.
okrequired boolean Always true; a refusal is an error answer instead.
problems array of string What is wrong with a candidate or the fallback, in prose.
routable_candidates array of string Candidates the gate may route to right now, in list order.

CandidateAliasStatus

One entry of GatewayStatus.candidate_aliases (GET /api/status,
lmgw__status): what an alias is, whom it starts and what is wrong with
it, from the same derivation the alias editor reads.

alternatesrequired array of string The other candidates, in preference order.
deferrals_24hrequired integer (uint64) How many gpu_deferred refusals the alias logged in the last 24 hours.
enabled_facetsrequired array of string The stored enabled facet set (wire facet names).
moderequired string background | owner: whose traffic the alias serves.
namerequired string The alias, as clients name it in model.
primaryrequired string | null The candidate the alias starts; null only for a row that saved with
an empty list.
problemsrequired array of string What is wrong with a candidate or the fallback, in prose.

CandidateAliasView

A candidate alias: its stored fields plus what lmgw computes from the live snapshot
(never stored, recomputed on every read).

advisoriesrequired array of string A candidate with --cache-ram 0: not an error, but worth
flagging.
aliasrequired string
backgroundrequired boolean
candidatesrequired array of string Local chat model ids, first = primary, rest = alternates in
preference order.
capabilities_disabledrequired array of string The explicit "turn this common facet off" list (wire facet names).
common_facetsrequired array of string Facets every candidate currently supports — the ceiling a save may
enable.
context_lengthrequired integer | null Minimum across routable_candidates (a ladder candidate at its top rung);
absent if any of them is unknown or nothing is routable.
deferrals_24hrequired integer | null How many gpu_deferred refusals this alias logged in the last 24
hours. Some(0) is a real
zero; None only ever means a frame cached from before this field
existed (#[serde(default)]), never "unknown".
enabledrequired boolean
enabled_facetsrequired array of string The stored enabled facet set (capabilities_enabled as last saved —
see that field's own doc comment for why this is never recomputed
outside a save).
fallbackrequired string | null The alias's one fallback, as written; null = none.
fallback_usablerequired boolean The alias fallback resolves to a model that can stand in (not a
candidate alias).
idrequired integer (int64)
max_output_tokensrequired integer | null
notesrequired string
problemsrequired array of string What is wrong with a candidate or the fallback, in prose.
routable_candidatesrequired array of string Candidates the gate may actually route to right now, in list order.
unsupported_byrequired object Facet wire name -> candidate ids that do not support it (the editor's
"not supported by: <ids>").

CardFile

The other measure's file, when the two picks differ (D120).

bytesrequired integer (uint64)
filerequired string
fitrequired FileFit
quantrequired string | null

CardKind

The kind of row a card's model becomes (D126, D29).

One of: string; string (A decision model: known only from its header (decision.type), so
no search answer says it yet.)

CardMeasure

The card a fit was measured against (design §3.1, §9.2), from one ledger
read.

admissionrequired boolean Admission is on and refuses a model that doesn't fit.
budgetrequired boolean The capacity is the declared budget, not the devices' total.
capacity_bytesrequired integer (uint64) What lmgw may use: the declared GPU memory budget, else the devices'
total.
headroom_bytesrequired integer (uint64) The headroom setting, added to every footprint.
holdrequired boolean The GPU hold is on: local models are paused (D10). The marks don't
change for it.
outside_bytesrequired integer | null What other programs hold on the card now: the devices' used memory
less lmgw's charges. None without a device reading, or when one of
lmgw's models on the card has no figure.
residentsrequired array of CardResident lmgw's own models on the card now, with what admission keeps free for
them.

CardResident

One of lmgw's models on the card now, as the beside measure charges it.

bytesrequired integer (uint64) Its charge plus what admission keeps free for it (an image
pipeline's measured peak, an audio model's pending load).
classrequired string chat | aux | audio | image.
modelrequired string

ChainRow

awaiting_approvalrequired boolean
chain_idrequired string
first_atrequired string
head_idrequired string What a client passes as previous_response_id to continue.
input_tokensrequired integer (int64)
last_atrequired string
modelrequired string
output_tokensrequired integer (int64)
responsesrequired integer (int64)
sizerequired string
statusrequired string

ChatCompletion

choicesrequired array of object
finish_reasonrequired string | null
indexrequired integer
logprobs null Always null: lmgw relays no log probabilities yet. Present because OpenAI's schema requires the field.
messagerequired object
contentrequired string | null
reasoning_content string
rolerequired string One of assistant.
tool_calls array of object
createdrequired integer
idrequired string
modelrequired string
objectrequired string One of chat.completion.
usagerequired object
completion_tokensrequired integer
completion_tokens_details object Present only when the upstream reported reasoning tokens.
reasoning_tokensrequired integer
prompt_tokensrequired integer
prompt_tokens_details object Present only when the upstream reported prompt-cache counts, and each field only when reported: cached_tokens read from the cache, cache_write_tokens written to it. Both are part of prompt_tokens.
cache_write_tokens integer
cached_tokens integer
total_tokensrequired integer

ChatCompletionChunk

One frame: data: <this object>, repeated, ending with the literal data: [DONE].

choicesrequired array of object
deltarequired object
content string | null
reasoning_content string
role string One of assistant.
tool_calls array of object
finish_reasonrequired string | null
indexrequired integer
createdrequired integer
idrequired string
modelrequired string
objectrequired string One of chat.completion.chunk.
usage object | null Only with stream_options.include_usage: null on every frame but the last, whose choices is [] and which carries the request's usage.
completion_tokensrequired integer
completion_tokens_details object Present only when the upstream reported reasoning tokens.
reasoning_tokensrequired integer
prompt_tokensrequired integer
prompt_tokens_details object Present only when the upstream reported prompt-cache counts, and each field only when reported: cached_tokens read from the cache, cache_write_tokens written to it. Both are part of prompt_tokens.
cache_write_tokens integer
cached_tokens integer
total_tokensrequired integer

ChatCompletionRequest

chat_template_kwargs object Only enable_thinking is read (llama-server's own template toggle, distinct from the protocol-neutral reasoning controls above); every key is forwarded verbatim.
frequency_penalty number
json_schema object llama.cpp's own top-level schema; without a response_format, or next to a {type:text} one, it is read as response_format {type:json_schema} and sent in that spelling. Next to a grammar it is 400 bad_request, as llama-server refuses the pair.
max_completion_tokens integer Wins over max_tokens when both are sent.
max_tokens integer
messagesrequired array of object
content any A string, or an array of parts: {type:text,text}, {type:image_url,image_url:{url}} (a plain URL or a data: URI), {type:input_audio,input_audio:{data,format}} (data: URI, or raw base64 with format required). A tool message keeps only its text, as OpenAI defines it; any other part is dropped with a WARN naming it.
name string role: tool only. Forwarded as the tool result's name.
reasoning_content string role: assistant only. Replayed as the leading reasoning part (also accepted spelled 'reasoning', as OpenRouter spells it; DeepSeek and llama.cpp use reasoning_content).
rolerequired string system and developer are both treated as a system message; tool and function are both treated as a tool-result message. One of system, developer, user, assistant, tool, function.
tool_call_id string role: tool only.
tool_calls array of object role: assistant only: [{id, type:function, function:{name, arguments: <JSON string>}}]. Send each id back as lmgw gave it: a Gemini model's call id carries the model's thought signature, which Gemini 3 refuses a replayed call without. Such ids run to hundreds of characters; echo them exactly, and do not send them to another provider directly (lmgw strips the signature there).
modelrequired string An alias, a local model id, a candidate alias, or 'prefix/…' to pass through to an exposed upstream.
presence_penalty number
reasoning object lmgw extension, OpenRouter's shape: {effort, max_tokens, enabled, exclude}. Read for the reasoning tier and forwarded verbatim.
reasoning_budget_tokens integer lmgw extension: a thinking-token budget (also x-lmgw-reasoning-budget). Forwarded verbatim alongside thinking_budget_tokens — whichever spelling a llama-server version reads.
reasoning_effort string lmgw extension: an effort level, or 'none' for off — one spelling of the reasoning control (also x-lmgw-reasoning-effort, and reasoning.effort below); the header wins when both are sent.
response_format object {type:text} | {type:json_object} | {type:json_schema, json_schema:{name, description, schema, strict}} — translated for every upstream: Anthropic output_config.format (json_schema only; json_object is refused with response_format_unsupported), Gemini responseMimeType + responseJsonSchema. A type the model's capabilities.structured_output flag says false is refused before any upstream call (400 response_format_unsupported, param response_format); a schema the upstream rejects is 400 invalid_json_schema with its message. Another type goes verbatim to OpenAI-compatible upstreams. Keys lmgw does not model, on the object and on json_schema, reach OpenAI-compatible and llama.cpp upstreams as sent.
seed integer
service_tier string OpenAI's processing tier (auto, default, flex, priority, fast, scale, ultrafast), forwarded as sent; on an OpenAI platform row lmgw sends auto when it is unset, and prices the answer at the tier the answer reports. A request by a caller with a budget (its key's, or the gateway's) on a cloud model with no price on file for what it is billed in is refused before the send: 403 budget_unpriced, naming the model and the missing price. A flex request needs a flex price: no other tier's price bounds a flex answer's spend, which is cheaper.
stop any A string, or an array of strings.
stream boolean Default false.
stream_options object With stream: true, include_usage ends the stream with a chunk whose choices is [] and that carries usage; every other chunk then has usage: null. Without it no chunk carries usage. Not forwarded: lmgw asks the upstream for usage itself, for its request log.
include_usage boolean Default false.
temperature number
thinking_budget_tokens integer Same as reasoning_budget_tokens; both are read and both stay in the forwarded body.
tool_choice any "auto" | "none" | "required" | {type:function,function:{name}}.
tools array of object
functionrequired object
description string
namerequired string
parameters object
typerequired string One of function.
top_k integer Not part of the OpenAI API, but accepted; llama.cpp supports it.
top_p number

ChatCompletionStreamError

The frame a stream carries instead of a chunk when the upstream fails after the first byte was sent.

errorrequired object
coderequired string One of upstream.
messagerequired string
typerequired string One of api_error.

ChatKnowledgeBase

One knowledge base, as the Chat shows it.

embed_resolvablerequired boolean Whether a model on the gateway still resolves to the base's pinned
embedding model; without one a search is by keyword only.
filesrequired integer (int64) Its files, in any state.
idrequired integer (int64)
namerequired string Unique across the bases.
readyrequired integer (int64) The files ingested and searchable.

ChatKnowledgeFile

The file a ChatKnowledgeSource shows.

idrequired integer (int64)
kindrequired string What the bytes were sniffed as.
namerequired string The name it was uploaded under (a label, never a path).
pagesrequired integer | null Pages, slides or sheets, when the file has them.
statusrequired string pending, ingesting, ready or failed. One of pending, ingesting, ready, failed.

ChatTestPassed

A chat model that loaded and answered, with the comparison of its running
build against the gateway's static derivation.

answer DecideAnswer For decide: the model's answer to the probe's choice question, as
it gave it. The test does not judge the choice, only that the route
answered with one of the options and probabilities that sum to 1
(decision-models design §3.7).
classrequired string aux for an aux model's pass, chat where this is the first part of
a chat model's. One of chat, aux.
dimensions integer (uint) For embed: the embedding's length.
disagreementsrequired array of string Where the running build and the static derivation disagree; empty
when they agree or /props could not be read.
input_tokens integer (uint64) For decide: the input tokens the server reported for the question.
latency_msrequired integer (uint64) How long the load and the probe took, in milliseconds.
loadedrequired boolean Always true.
model_idrequired string
note string Why props could not be read, when it could not.
okrequired boolean Always true.
proberequired string What was sent: generate (one token), embed, rerank or decide
(one System One choice question on /v1/systemone).
propsrequired any llama-server's own /props answer, verbatim; null when it could not
be read.
scored integer (uint) For rerank: how many documents came back scored.
staticrequired StaticCaps The capabilities the gateway derived statically, the part /props
also states an opinion on.

ChatTool

One tool a thread may tick.

descriptionrequired string | null
namerequired string The exposed name (docs__query): what a thread's allowed_tools
and require_approval name.

ChatToolSource

One toolset a thread may attach.

descriptionrequired string A toolset's purpose in one line; empty for a server.
kindrequired string builtin (one of lmgw's own toolsets), server (a registered MCP
server) or agent (a service agent's tools). One of builtin, server, agent.
namerequired string A server's configured name; a toolset's label.
reasonrequired string | null Why it offers nothing now, when it does not.
server_labelrequired string What a thread's mcp_tools entry names: a toolset's own label, a
server's tool prefix, else its name.
statusrequired string A server's connection now: ready, connecting, error or
stopped. A built-in toolset is ready when it offers tools and
unavailable when it offers none (reason says why). One of ready, connecting, error, stopped, unavailable.
tool_countrequired integer (uint32) The tools of it the caller may tick now: a built-in toolset's
tools; a server's tools as last listed, the owner's
switched-off ones and those outside the caller's tool scope left out
(0 before it was first listed).
toolsrequired array of ChatTool A built-in toolset's tools. Empty for a server:
GET /chat/api/tools/{label} lists those, connecting it.

CheckMergeStep

One extra's row in a build_check_merge report.

filesrequired array of string Conflicted paths — set only when outcome is conflict.
labelrequired string
noterequired string
outcomerequired MergeOutcome
sharequired string

ChoiceAnswer

choicerequired string The most probable option.
confidencerequired number (double) How certain the model is, derived from the probabilities.
probabilitiesrequired object Every option with its probability; they sum to 1.

ChoiceQuestion

criteriarequired object Each option with its description, or null when it needs none, in
the order the options are offered. TypeSafe takes up to 255; llama.cpp
names its own per-type limit when a request crosses it.
instructionsrequired any The question: a string, an object or an array.

ChunkRow

One chunk. payload is a **verbatim** slice of the source document and is
rendered as such — never as markdown, since it carries its own fences.

corpus_idrequired integer (int64)
derived_summaryrequired string
derived_titlerequired string LLM-derived — a label, never payload.
document_idrequired integer (int64)
heading_pathrequired string
idrequired string
payloadrequired string
span_endrequired integer (int64)
span_startrequired integer (int64)

ChunkSpan

Where a chunk sits in its file, without its text.

heading_pathrequired string
idrequired string
pagerequired integer | null 1-based page, slide or sheet, when the file has them.
seqrequired integer (int64) The chunk's position in the file.
span_endrequired integer (int64)
span_startrequired integer (int64) Byte range in the file's extracted text.
tokensrequired integer (int64)

ClimbStatus

A climb in progress, and why — "climbing to 3/3 — prompt 41,210 + 8,192 >
30,000".

ofrequired integer (uint)
reasonrequired string Why — the numbers of the request that did not fit.
secondsrequired integer (uint64) Since the mark, in whole seconds.
stagerequired string What it is doing right now, in words.
torequired integer (uint) The rung it climbs to, 1-based.

Clip

One reference clip of the voice library.

namerequired string The file name, extension included.
server_pathrequired string The clip's path inside the model container: what goes into voice_ref
or audio.
sizerequired integer (uint64) Bytes.
transcriptrequired string What the clip says (its line in the library's prompt_text index);
empty while it has none. A cloning model that needs a reference text
reads it from here when a request names the clip as voice.
voicerequired string What a request's voice names once the audio class's voice directory is
this library: the file name without its extension.

ClipFailed

A clip an upload could not transcribe; the upload itself stands.

cliprequired string The clip's file name.
transcribe_errorrequired string

ClipTranscription

One clip of an upload, transcribed or not.

One of: ClipWritten; ClipFailed

ClipWritten

A clip an upload transcribed.

answered_byrequired string | null The fallback alias that answered in place of the one asked, else null.
byrequired string Who wrote it, in a sentence.
cliprequired string The clip's file name.
fallback_reasonrequired string | null Why the fallback answered (hold, external_vram, ...), else null.
transcript_sourcerequired string asr:<model>: the model the transcript came from. When a fallback
answered, that model's name.

CompletionRequest

Forwarded to an OpenAI-protocol upstream verbatim (a llama.cpp row's response_format excepted, see there): this route refuses anything else (an Anthropic or Gemini alias gets 400 rather than a request its upstream cannot answer).

max_completion_tokens integer
max_tokens integer
modelrequired string
n_predict integer llama.cpp spelling of max_tokens; folded into it for local models with a guard or a ladder.
promptrequired any A string, an array of strings, an array of token ids, or a mix of both.
response_format object As on /v1/chat/completions. llama.cpp's own /v1/completions reads no response_format, so for a llama.cpp row it is sent as the top-level json_schema that route reads; a type with no such spelling is 400 response_format_unsupported, and a JSON type next to a grammar 400 bad_request, with nothing sent.
stream boolean Default false.

ConcurrentPoint

One concurrent point: *N* streams released together.

aggregate_tok_srequired Stat Σ predicted_n / (last stream's end − first stream's first token).
draftrequired DraftStats | null
energyrequired Energy | null Over the aggregate's window; tokens are Σ predicted_n.
energy_unmeasuredrequired string | null Why energy is None although the card reports power: a window
shorter than the GPU sampler resolves (two of its ticks, 200 ms at
the 100 ms tick), whose figure would have been the
ticks' average power times its length rather than a measurement.
None otherwise.
per_stream_tok_srequired Stat The median of the streams' predicted_per_second, per repetition.
streamsrequired integer (uint32) *N*.

ConfiguredAs

A configured row already serving the planned GGUF, and how it differs
from the plan.

apply object The patch for the class's set op that brings the row in line with the
plan; absent when it is in sync.
changerequired array of PlanChange Each field the plan would change on the row.
enabledrequired boolean
idrequired integer (int64) The row's id in its class's table.
in_syncrequired boolean Nothing the plan proposes differs from the row.
model_idrequired string
unset array of PlanUnset Chat rows: settings the row's files cannot support, which apply
clears. Absent on aux rows.

ConnectModel

source is alias | local.

namerequired string
sourcerequired string

ContainerAdvisories

A model that starts but misbehaves under some input.

advisoriesrequired array of string
classrequired string
model_idrequired string

ContainerBusy

A model whose container is still serving requests.

classrequired string
in_flightrequired integer (uint32) How many requests it is serving.
model_idrequired string

ContainerFailure

A model an action failed on.

classrequired string
errorrequired string
model_idrequired string

ContainerImage

One local or external image of the three engines.

backendrequired string | null The dev.lmgw.backend label, when present — a free string because
an external image (a build.sh tag, a registry pull) may not carry
it at all.
createdrequired string
enginerequired Engine | null None when the image can't be matched to an engine.
externalrequired boolean No dev.lmgw.run label — a build.sh image or a registry pull.
idrequired string Full image ID (no sha256:).
provenancerequired ImageProvenance | null None for an external image lmgw did not build.
registry_updaterequired RegistryUpdate | null The registry update check for an image a class
default or model override uses under a registry name (not
localhost/). None for every other image, and before the first
check.
run_statusrequired BuildRunStatus | null The run this image came from, when it is one lmgw built.
sizerequired integer (uint64)
tagsrequired array of string
used_byrequired array of ImageUse

ContainerModel

A model named by class and id.

classrequired string chat, aux, audio or image.
model_idrequired string

ContainerPort

A model and the port its container is up on.

classrequired string
model_idrequired string
portrequired integer (uint16) The loopback port the container is published on.

ContainerProblems

A model with problems found by the static checks.

classrequired string
issuesrequired array of string
model_idrequired string

ContextEditingCaps

The context_editing object of a model on an Anthropic route: what
its provider's catalog says about Anthropic's context management
(capabilities.context_management on Anthropic's own /v1/models).

compaction array of string The top-level compaction.type values (on-demand compaction) the
provider says the model takes (summarize, …), sorted: its catalog's
capabilities.compaction. lmgw sends the field on as written, and
the compaction block Anthropic answers with comes back as it came.
Omitted when the provider names none.
edits array of string The context_management.edits[].type values the provider says the
model takes, all of which lmgw sends on (clear_thinking_20251015,
clear_tool_uses_20250919, compact_20260112, …), sorted. A
compaction edit's compaction answer block comes back as Anthropic
sent it. Omitted when the provider names none.
supported boolean | null The provider says whether the model takes context_management at
all. Absent when its catalog says nothing.

ContextExcerpt

One retrieved excerpt, as a user message stores it.

chunk_idrequired string
filerequired string The file's name when it was retrieved.
file_idrequired integer (int64)
file_sharequired string The sha256 of the file version the chunk was cut from; empty for a
context stored before it was kept.
heading_pathrequired string
kbrequired string The base's name when it was retrieved.
kb_idrequired integer (int64)
pagerequired integer | null 1-based PDF page; null for other files.
scorerequired number (float)
span_endrequired integer (int64)
span_startrequired integer (int64) Byte range in the file's extracted text.
textrequired string The chunk's text, verbatim.
tokensrequired integer (uint64)

ContinueState

Whether a thread's last reply can be continued, and why not.

okrequired boolean
reasonrequired string | null

CorpusSource

corpus_idrequired integer (int64)
created_atrequired string
fencerequired array of string Domains a fetch may touch; empty = the root's own host.
idrequired integer (int64)
kindrequired string llms_txt | markdown | rustdoc_json | html.
rootrequired string

CorpusStatusView

The corpus status badges (embedding and evaluation state). Neither blocks a query.

embed_model_resolvablerequired boolean Whether a model on this gateway still resolves to the corpus's pinned
embedding identity. false with embed_status re_embed_required
means the corpus cannot be queried until it is re-embedded; true
means it is mid re-embed and still answers.
embed_statusrequired string
eval_statusrequired string
flagsrequired array of string
warningsrequired array of string

CorpusView

One corpus as the list and the detail view both show it.

chunk_countrequired integer (int64)
corpus_idrequired string The client-facing library@version, as docs__resolve reports it.
crawl_daterequired string
created_atrequired string
embed_dimsrequired integer (int64)
embed_identityrequired string upstream/model@dims, the pinned identity in one string.
embed_modelrequired string
embed_statusrequired string ok | re_embed_required — the same flag docs__resolve reports.
embed_upstreamrequired string
eval_at string When it was measured; absent when no instant was recorded.
eval_best number (double) The best hit@k ever measured; absent = never evaluated.
eval_k integer (int64) The depth eval_score was measured at; absent when no depth was
recorded (never evaluated, or a score stored without one).
eval_regressionrequired boolean
eval_score number (double) Latest measured hit@k; absent = never evaluated, which is not zero.
eval_statusrequired string ok | regression | unmeasured.
flagsrequired array of string Machine-readable badges; warnings is one sentence per flag.
idrequired integer (int64)
ingest_modelrequired string
ingest_prompt_versionrequired string
libraryrequired string
resident_bytesrequired integer (int64) What serving this corpus costs once resident: the visible price of
the exact-KNN scan.
source_kindrequired string
sourcesrequired array of CorpusSource
statusrequired string ready | ingesting | failed | re_embed_required — free-form, a chip.
unembedded_chunksrequired integer (int64) Chunks with no vector yet; non-zero means the KNN stage sees only part
of the corpus.
updated_atrequired string
versionrequired string
warningsrequired array of string

CountSource

Where a ubatch or batch in effect comes from.

One of: string (The row's own field.); string (A flag in the row's extra args.); string (The batch: llama.cpp lowers the ubatch to it.); string (The ubatch: embedding mode (a non-causal type, a causal type with a
head) lowers the batch to it.); string (llama.cpp's default (ubatch 512, batch 2048).)

CountTokensRequest

Routed by model exactly like the chat endpoints, so counting a cold local model's tokens starts its container. The key's alias scope applies: a refused count answers 403 key_scope and is logged; a successful count is not logged. No budget applies, neither the key's nor the gateway's: a count costs nothing.

inputrequired string
modelrequired string

CountTokensResponse

modelrequired string
tokensrequired integer

CurrentReason

Why current answered with a new thread.

One of: string (The folder had no current thread (for a device key: none it can
reach).); string (Its current thread can no longer be continued in the folder. Only
the dashboard and admin keys are given this reason.); string (Its current thread had no message for the folder's idle minutes.); string (The caller asked for a new thread (new: true).)

CurvePoint

One point of the threshold curve: what a cut at threshold keeps.

accuracyrequired number | null correct over labelled; null when none is labelled.
correctrequired integer (uint64) Of those, the ones answered correctly.
coveragerequired number (double) covered over every answered item.
coveredrequired integer (uint64) Answered items at or above it.
labelledrequired integer (uint64) Labelled items among covered.
thresholdrequired number (double) A confidence (certainty for noul) some answer has.

DecideAnswer

The probe's choice answer, with the options in the order the model
gave them. A JSON object would lose that order on the way through an op
(the op's JSON is a sorted map), so the options are a list.

choicerequired string The most probable option.
confidencerequired number (double) How certain the model is, derived from the probabilities.
probabilitiesrequired array of OptionProbability Every option with its probability, in the order llama.cpp answered
them; they sum to 1.

DecisionBackend

Where a local decision row computes.

string

DecisionEstimate

One limit with the form's estimate against it.

limitrequired DecisionLimit
overrequired boolean The estimate is past the limit. A warning: Ask is not blocked.
tokensrequired integer (uint64) The state plus the largest question, or the largest option span.

DecisionFacts

A local decision row's facts: its row, its GGUF header and its running
server.

backendrequired DecisionBackend
batchrequired integer (uint64) The batch in effect.
batch_sourcerequired CountSource
ctx_sizerequired integer | null The row's ctx_size; null takes llama-server's default.
decision_typerequired string | null The header's decision.type (laya, kev, ...).
header_errorrequired string | null Why the header could not be read; the header's fields are null
then.
max_head_tokensrequired integer | null The header's decision.max_head_tokens: past it llama.cpp truncates a
question and its options.
n_ctx_slotrequired integer | null One slot's context as the running server's /props says; null
until a container has run.
shaperequired DecisionShape | null
threads_in_effectrequired integer | null The thread count its container runs with; null when llama-server
picks.
threads_sourcerequired AuxThreadsSource
ubatchrequired integer (uint64) The ubatch in effect: the row's, its args', llama.cpp's default, never
above the batch.
ubatch_sourcerequired CountSource

DecisionFallbackPrice

The price of the alias that answers for a held local row: alias and
what DecisionPrice says of a model, for its own primary route.

aliasrequired string
localrequired boolean Served on this machine: free.
rowsrequired array of PriceRowView The rows that price it, per unit, as DecisionPrice::rows.
unresolvedrequired string | null Why its route did not resolve; rows is empty then.

DecisionForm

The Decision lab's whole form, as the page holds it and the store keeps
it (lab_groups.form). Every list is a Vec, so storing it keeps its
order.

images array of DecisionImageInput Default [].
questions array of QuestionDraftInput Default [].
state string As typed; JSON mode keeps its text verbatim. Default "".
state_mode StateMode Default "text".

DecisionImageInput

One image the form sends.

One of: object (A new image, as the page read it.); object (An image the store keeps already (a re-opened form): its artifact id.
Nothing is uploaded again.)

DecisionLabModel

One model that answers /v1/systemone: a local decide/* row, or a
cloud alias or catalog entry of task decision.

context_lengthrequired integer | null From its capabilities: the context it is planned against, or the
catalog's.
factsrequired DecisionFacts | null What its row and its GGUF header say; null for a cloud model.
fallbackrequired string | null The model or alias that answers for it while it is held, when that
one can (its configured fallback, the first hop of its chain).
heldrequired boolean The GPU hold (or a benchmark's lease) pauses it now: a GPU row while
the hold is on. A CPU row and a cloud model never are.
input_modalitiesrequired array | null From its capabilities; null when unknown.
limitsrequired array of DecisionLimit What must fit in how many tokens (§2.2's table): one or two limits.
localrequired boolean A local aux row of kind decision.
model_idrequired string | null The row's id, for a local model.
namerequired string The public name a request asks for.
notesrequired array of string What GET /v1/models notes about it.
ownerrequired string Who serves it, as GET /v1/models says (lmgw for a local row, the
upstream's name for a cloud model).
pricerequired DecisionPrice What prices a request to it, as the gateway prices one.
reads_imagesrequired boolean It reads images: its running server's vision, else an image among
its input modalities.
staterequired string | null Its container's state (starting, ready, stopping); null when
no container runs, and for a cloud model.
warningsrequired array of string What its container's start found.

DecisionLimit

One limit a request meets on a model.

applies_torequired DecisionMeasure
ofrequired string What the number is and where it comes from ("the ubatch in effect,
set on the row").
rulerequired string The rule in one sentence, with what llama.cpp answers past it.
tokensrequired integer | null The limit in tokens; null when it is not known.

DecisionMeasure

What a limit bounds.

One of: string (The state and one question (with its options and the template): the
gauge's estimate is the state plus the largest question.); string (The span from the first option marker to the end of the prompt: the
estimate is the largest option list.)

DecisionPrice

What prices a request to a decision model: the rows the gateway's own
price lookup selects for its primary route (Snapshot::sheet_for), the
route a request takes when no fallback answers. A fallback that answers
is priced by its own rows.

fallback DecisionFallbackPrice | null While a local row is held and its fallback can answer, the
price of the alias that answers every request instead (the rows the
gateway then records it at). Absent otherwise.
localrequired boolean Served on this machine: free whatever rows exist (Usage records the
compute it takes, not a price).
rowsrequired array of PriceRowView Per unit, the row that prices it, each unit resolved on its own: the
alias's manual row, else the alias's catalog row, else the upstream
model's manual row, else its catalog row; a row without a usable rate
is no row. Empty for a local model, and for a cloud model no row
covers, whose cost Usage records as unknown.
unresolvedrequired string | null Why its route did not resolve (a candidate alias picks its model per
request); rows is empty then.

DecisionQuestionKind

A question's type and its type's fields.

One of: object (Pick one of the options, in the order offered.); object (Rate on 2 to 10 levels, lowest first.); object (Yes or no; yes and no say what each means, both blank sends no
criteria.)

DecisionQuestionKindInput

A question's type and its type's fields.

One of: object (Pick one of the options, in the order offered.); object (Rate on 2 to 10 levels, lowest first.); object (Yes or no; yes and no say what each means, both blank sends no
criteria.)

DecisionShape

A decision model's header shape (decision-models design §3.4).

One of: string (attention.causal = false (Laya, Julia-1): the whole prompt in one
ubatch.); string (Causal with a decision head (Kev, Clef): embedding mode.); string (Causal, answering from label logits (lev, OpenJev): a normal context.)

DecodePoint

One decode point: n_predict: G, ignore_eos, cache_prompt: true.

depthrequired integer (uint64) *D*: the prompt length the generation starts from.
distinct_token_ratiorequired Stat | null Distinct token ids over generated ones, per repetition: near 1 for
prose, low for a degenerate loop that ignore_eos ran into — and a
loop is what a drafter predicts perfectly, so a draft acceptance
next to a low ratio flatters it. Only where the
engine streams token ids (official llama.cpp, not ik).
draftrequired DraftStats | null
energyrequired Energy | null Over first token → last token of each repetition, so the priming
prefill stays out; tokens are those generated after the first.
energy_unmeasuredrequired string | null Why energy is None although the card reports power: a window
shorter than the GPU sampler resolves (two of its ticks, 200 ms at
the 100 ms tick), whose figure would have been the
ticks' average power times its length rather than a measurement.
None otherwise.
evaluated_tokensrequired Stat timings.prompt_n: the first repetition primes the cache (≈ *D*), the
later ones reuse it (a handful).
generatedrequired Stat timings.predicted_n.
tok_srequired Stat Server-side timings.predicted_per_second.

DeviceCaError

Why lmgw's device CA cannot be used.

kindrequired DeviceCaErrorKind What kind of failure it is.
messagerequired string The reason in a sentence, naming the file, the mode found or the
Secret Service's answer.

DeviceCaErrorKind

The kind of DeviceCaError.

One of: string (No CA exists, and the call needed one.); string (The wallet's unlock prompt was declined.); string (A file cannot be read, does not parse, or the key does not open or
does not match the certificate.); string (The key file is readable by group or others, not owned by lmgw's
user, or a symbolic link.); string (The key is wrapped and no Secret Service answers this start.); string (The key is wrapped and the Secret Service holds no wrapping key for
this data directory.); string (The Secret Service answered with an error.)

DeviceCaKeyMode

How tls/ca.key keeps the CA's key (device link design D2).

One of: string (Encrypted (AES-256-GCM) under a key held in the session's Secret
Service.); string (Plain PKCS#8, readable by its owner only: a start without a Secret
Service (headless). The next start that reaches one wraps it.)

DeviceCaState

Whether lmgw's device CA exists and signs.

One of: string (None exists: it is created when the device listener is first turned
on.); string (On disk and not loaded since this start (the device listener has not
run): fp, created and key_mode are read from the files, the key
itself is not opened.); string (Loaded: its key is open and signs.); string (It cannot be used; error says why.)

DeviceCaStatus

lmgw's device CA (device link design §2.1), as the status shows it.

cert_filerequired string The certificate's path (tls/ca.crt in the data directory), PEM,
readable by anyone: what curl --cacert takes.
certificate_pemrequired string | null The CA certificate, PEM: what curl --cacert takes and the Devices
card copies. Public like the file (0644) and the pin; null while
the CA is missing or its certificate cannot be read.
createdrequired string | null The CA's creation day (its notBefore), RFC 3339 UTC; null with
fp.
errorrequired DeviceCaError | null Why the CA cannot be used, with state error.
fprequired string | null sha256: and the lowercase hex SHA-256 of the CA certificate's
SubjectPublicKeyInfo: the pairing link's fp. null while the CA is
missing or its certificate cannot be read.
key_filerequired string The key file's path (tls/ca.key in the data directory).
key_moderequired DeviceCaKeyMode | null How the key file keeps the key; null while the CA is missing or the
key file cannot be read.
staterequired DeviceCaState Whether the CA exists and signs.

DeviceLeafSlot

Which connections a server certificate serves.

One of: string (Every connection to a loopback address (127.0.0.0/8, ::1).); string (Connections to one address of this machine's interfaces.); string (Connections to an address no interface lists: the URL-list hosts
alone.)

DeviceLeafStatus

One server certificate the device listener presents (device link design
§2.2).

addressrequired string | null The local address it serves, for interface; null for loopback
and shared.
issuedrequired string When it was issued, RFC 3339 UTC.
namesrequired array of string The names it carries (its subjectAltNames): its address, or the
loopback addresses and localhost, and every host of every device's
URL list.
renew_afterrequired string From when the next connection it would serve gets a new one: half its
validity.
slotrequired DeviceLeafSlot Which connections it serves.
valid_untilrequired string Its notAfter, RFC 3339 UTC.

DeviceListenerState

Whether the device listener serves.

One of: string (devices.listener is off, or the gateway is not serving.); string (It serves on urls.); string (It is on and does not serve; error says why. The plain listener
serves on.)

DeviceListenerStatus

The device listener (device link design §4.1, §9.2), as the status
shows it: whether it serves, where, or why not, and what it holds open.

connectionsrequired integer (uint64) Its open connections now, TLS handshakes included.
errorrequired string | null Why it does not serve, with state error: a bind error naming the
address and the settings, the device CA's reason, or a port it cannot
derive.
evictedrequired integer (uint64) Such connections it closed since it started to make room for a newer
one, one of those two bounds reached (the oldest goes).
listenrequired string | null The scope it serves, or tried to: loopback, all or an address
(devices.listen); null while off.
portrequired integer | null The port it serves, or tried to (devices.port, or the HTTP port's
number plus one); null while off.
requestsrequired integer (uint64) The requests in flight on it now (an open Chat feed is one).
sessionsrequired integer (uint64) The realtime sessions and turns running on it now.
staterequired DeviceListenerState Whether it serves.
unauthenticatedrequired integer (uint64) Its connections that have not authenticated, now: handshakes in
progress, connections without a certificate, and connections whose
certificate opens no working device. What devices.unauthenticated_max
and devices.unauthenticated_per_peer bound.
urlsrequired array of string What it is bound to, as https:// base URLs: two for loopback
(one when the machine has no IPv6), one otherwise. Empty unless
listening.

DevicePaired

A device's pairing link minted: POST /api/op/key_create with kind:
device
(the row and its first pairing token) and device_token (a new
token for the same row; device link design §3.2, §5.2). The token goes to
the owner once, inside the link.

fprequired string sha256: and the hex SHA-256 of the device CA's SubjectPublicKeyInfo:
the link's fp, which the device's enrolment pins.
idrequired integer (int64) The device row's api_keys.id; a new token keeps it.
linkrequired string lmgw-pair:?v=2&name=…&url=…[&url=…]&fp=sha256:…&token=lmgw-enrol-…:
carries the one-time pairing token to the device. Secret while its
token lives: shown once, never logged.
local_onlyrequired boolean Paired as "this computer": the device reaches lmgw on a loopback
address only.
messagerequired string What was done, for a person to read: what the device does next, and
whether the device listener reaches it from where it is.
namerequired string device:<name>.
okrequired boolean Always true; a refusal is an error answer instead.
token_expires_atrequired string When the pairing token lapses (RFC 3339, UTC): devices.token_minutes
after it was minted.
urlsrequired array of string The device's lmgw URLs: https base URLs of the device listener, in
the owner's order, as the link carries them and enrolment answers
them.

DevicePairingState

Where a device's pairing stands.

One of: string (No key: waiting for its device to enrol with a token (or for a new
token, when its last one ended).); string (A key enrolled and waiting for the owner's confirmation: its every
request is refused 403 device_unconfirmed until then. A key kept
beside it (kept_code) is served until the confirmation ends it.); string (Enrolled and confirmed: the device is served.); string (Paired with a link from before TLS: its bearer key no longer works,
and it needs a new token.)

DevicePairingStatus

Pairing in GET /api/status (device link design §3.3, §9.2): the tokens
alive, and the failed enrolments of the last hour.

counted_sincerequired string Since when failures are counted: the counts live in memory and start
at zero with each start of lmgw (RFC 3339 UTC).
failures_last_hourrequired integer (uint64) Failed enrolments (an unknown, used, lapsed or ended token) in the
last hour, from every address.
last_failure_atrequired string | null When it was, RFC 3339 UTC.
last_failure_fromrequired string | null The address of the last failure (an IPv6 address by its /64), null
when none was counted.
tokens_aliverequired integer (uint64) The pairing tokens alive now (minted, not lapsed, not ended; a used
one stays alive for its same-key repeat): while any is, a device
listener handshake may come without a client certificate, for
enrolment alone.

DevicePairingView

A device row's pairing (device link design §3.6, §9.3), as the Keys
list shows it.

cert_not_afterrequired string | null The certificate of the key that works now: its notAfter, and from
when the card and the device say it lapses (two thirds of its
validity), RFC 3339 UTC.
cert_notice_afterrequired string | null
clientrequired string | null The client its last enrolment named (the enrolment's client, free
text, never trusted for anything): the waiting key's while one waits,
the key that works now's otherwise.
confirm_coderequired string | null The confirmation code, 7F3A-91C2, of the key that waits for the
owner's confirmation in state enrolled, of the confirmed key
otherwise: what the device shows, and what the owner compares and
sends with device_confirm.
confirmed_atrequired string | null When the owner confirmed the key that works now (RFC 3339 UTC); with
a key waiting, the kept key's confirmation.
contested_atrequired string | null When a used token of its came back with another key, and from where:
if the device did not pair, someone else holds a certificate for the
row (unconfirmed until the owner confirms it), so delete it.
contested_fromrequired string | null
device_namerequired string | null The name the device's user gave the device, as its last enrolment
said it (the enrolment's device_name, free text, never trusted for
anything; *added 2026-10-23*): the waiting key's while one waits, the
key that works now's otherwise. Not the name the owner gave the link.
enrolled_atrequired string | null When its last enrolment was (RFC 3339 UTC): the waiting key's while
one waits (state enrolled), the key that works now's otherwise.
enrolled_fromrequired string | null From where its last enrolment came (the peer address): the waiting
key's while one waits, the key that works now's otherwise.
kept_clientrequired string | null With a key waiting beside the kept one: the kept key's client.
kept_coderequired string | null With a new key waiting beside the device's confirmed one (a re-pair
that kept the current key): the kept key's code. The kept key is
served until the waiting one is confirmed, which ends it.
kept_device_namerequired string | null With a key waiting beside the kept one: the kept key's device_name
(*added 2026-10-23*), which device_name no longer shows then.
local_onlyrequired boolean Paired as "this computer".
staterequired DevicePairingState Where its pairing stands.
tokenrequired PairingTokenView | null Its latest pairing token, if it was ever given one.
urlsrequired array of string Its lmgw URLs, https, in the owner's order.

DeviceUrl

One URL proposed for another device.

interfacerequired string The interface the address is on (eth0, wg0); empty for a
listener set to one address.
urlrequired string https://<address>:<device port>.
wireguardrequired boolean The interface is a point-to-point link (WireGuard, Tailscale), not
a LAN's.

DevicesSettings

Settings → Network & access → Devices (devices.* in
GET /api/settings-full, device link design §9.1).

client_cert_daysrequired integer (uint32) A device certificate's validity, in days (1 to 3650); the card and
the device show a notice from two thirds of it. Applies to the next
certificate issued.
enrol_refuse_per_minrequired integer (uint32) Failed enrolments per address (an IPv6 address by its /64) per
minute before the address is answered 429 (1 to 100000); applies at
once.
handshake_timeout_srequired integer (uint32) A TLS handshake's bound, in seconds (1 to 300); applies to the next
connection.
header_timeout_srequired integer (uint32) A request head's bound, and an idle kept-alive connection's wait for
the next one, in seconds (1 to 3600); applies to the next connection.
listenrequired string Where the device listener binds: loopback (127.0.0.1 and [::1],
while every paired device is this computer), all ([::], every
address) or one IP address.
listenerrequired boolean Whether the device listener runs: the TLS listener paired devices
connect to. Off until the first pairing turns it on.
portrequired integer | null The device listener's port; null = the HTTP port's number plus one,
written as a number the first time the listener starts.
port_effectiverequired integer | null The port the device listener binds: port, else the HTTP port's
number plus one; null when port is null and the HTTP port is
65535 (no port above it), so the setting must name one.
server_cert_daysrequired integer (uint32) A server certificate's validity, in days (1 to 3650); a server
certificate is re-issued from half of it, unnoticed by devices.
Applies to the next certificate issued.
token_minutesrequired integer (uint32) A pairing token's lifetime, in minutes (1 to 1440); applies to the
next token.
transfer_expiry_daysrequired integer (uint32) How long a transfer offer between devices lasts, in days (1 to
3650); its bytes are deleted when it expires undelivered. Applies to
the next offer.
unauthenticated_maxrequired integer (uint32) The device listener's connections that have not authenticated yet
(handshakes in progress, connections without a certificate or with
one that opens no working device), at most, from every peer together
(1 to 4096); a new one past it closes the oldest. Applies to the next
connection.
unauthenticated_per_peerrequired integer (uint32) The same, from one peer: an IPv4 address, an IPv6 address by its /64
(1 to 4096); a new one past it closes that peer's oldest. Applies to
the next connection.
unauthenticated_timeout_srequired integer (uint32) A whole connection without a client certificate, in seconds (1 to
300); applies to the next connection.

DevicesSettingsPatch

The sparse patch both saves take under devices.

client_cert_days integer | null A device certificate's validity in days, 1 to 3650; the notice comes
at two thirds of it. Applies to the next certificate issued. Default null.
enrol_refuse_per_min integer | null Failed enrolments per address (an IPv6 address by its /64) per
minute before a 429, 1 to 100000. Applies at once. Default null.
handshake_timeout_s integer | null A TLS handshake's bound in seconds, 1 to 300. Applies to the next
connection. Default null.
header_timeout_s integer | null A request head's bound, and an idle kept-alive connection's, in
seconds, 1 to 3600. Applies to the next connection. Default null.
listen string | null Where it binds: loopback (127.0.0.1 and [::1]), all ([::], every
address) or one IP address. Applies at once, moving it and ending its
connections. Default null.
listener boolean | null The device listener: on or off. Applies at once: on binds it (making
lmgw's device CA on its first start), off closes it and ends its
connections — its feeds, realtime sessions and calls — never the
plain listener's. Default null.
port integer | null Its port, 1 to 65535. Applies at once, moving it and ending its
connections. Unset, it is the HTTP port's number plus one, written
here the first time the listener is turned on. Default null.
server_cert_days integer | null A server certificate's validity in days, 1 to 3650; it is re-issued
from half of it. Applies to the next certificate issued. Default null.
token_minutes integer | null A pairing token's lifetime in minutes, 1 to 1440. Applies to the next
token. Default null.
transfer_expiry_days integer | null How long a transfer offer between devices lasts, in days, 1 to 3650;
its bytes are deleted when it expires undelivered. Applies to the
next offer. Default null.
unauthenticated_max integer | null The device listener's connections that have not authenticated yet
(handshakes in progress included), at most, from every peer
together, 1 to 4096; a new one past it closes the oldest. Applies to
the next connection. Default null.
unauthenticated_per_peer integer | null The same, from one address (an IPv6 address by its /64), 1 to 4096;
a new one past it closes that address's oldest. Applies to the next
connection. Default null.
unauthenticated_timeout_s integer | null A whole connection without a client certificate, in seconds, 1 to
300. Applies to the next connection. Default null.

DevicesStatus

devices in GET /api/status (device link design §9.2): lmgw's device
CA and the server certificates issued from it.

carequired DeviceCaStatus lmgw's device CA: whether it exists and is loaded, its pin and how
its key is kept, or why it cannot be used.
leavesrequired array of DeviceLeafStatus The server certificates issued since this start, one per local
address that served a device connection (one for every loopback
address); empty until the device listener serves.
listenerrequired DeviceListenerStatus The device listener: off, where it listens, or why it does not.
pairingrequired DevicePairingStatus Pairing: the tokens alive and the failed enrolments counted.

DictatedVoice

How a dictated message says it was dictated (voice of a send): the
facts of the transcribe answer, nothing a reply carries. Unknown fields
are refused.

asr string | null The speech-to-text alias that was asked.
asr_answered_by string | null The alias that answered in its place, when a fallback did.
asr_ms integer | null How long the transcription took.
audio_ms integer | null The recording's length.
viarequired string Must be dictation: a realtime turn is written by the bound session
and cannot be sent.

DiskInfo

container_images' disk field:
podman system df totals plus orphaned build leftovers, shown for
information only — nothing is pruned from here.

buildah_orphansrequired array of string /var/tmp/buildahNNN dirs and Storage containers not yet cleaned
up.
images_totalrequired integer (uint64)
reclaimablerequired integer (uint64)

DiskRoom

The models directory's free space against what the files need (D125):
a warning, never a block.

free_bytesrequired integer | null The free bytes of the filesystem the models directory is on, read
with statvfs now; None when it couldn't be read.
needs_bytesrequired integer (uint64) The bytes still to download: every queued file's listed size less
what its kept .part already holds. A file already on disk counts
nothing.
notesrequired array of string What the check leaves out, each a sentence.
sentencerequired string | null "Needs 15.6 GiB on the disk, 8.5 GiB is free", when short; else none.
shortrequired boolean The files need more than is free.

DocRequestRow

One docs__request filing. status is pending | fulfilled | dismissed;
only the first two are settable by hand — fulfilled is what an ingest
job's auto-fulfil writes.

client_namerequired string | null MCP client name from initialize, when it gave one.
countrequired integer (int64)
first_requested_atrequired string
idrequired integer (int64)
last_requested_atrequired string
libraryrequired string
reasonrequired string | null
statusrequired string
versionrequired string Empty when the requester pinned no version.

DocsSearchDefaults

The stage defaults (Settings.docs_search) — where a request that
overrides nothing starts. None of these is a cap: every one is a
per-request parameter the playground and docs__query can override.

budget_tokensrequired integer (uint32) 0 means *no budget* — every one of limit chunks comes back.
eval_krequired integer (uint32) Depth an eval run measures hit@k at when the request names no k.
fts_weightsrequired FtsWeightsView BM25 column weights — a stage default like any other, and one the
playground exposes, so it has to round-trip through a save.
k_ftsrequired integer (uint32)
k_rerankrequired integer (uint32) 0 disables the rerank stage.
k_vecrequired integer (uint32)
limitrequired integer (uint32)
rrf_krequired number (float)

DocsSearchPatch

The Docs search stage defaults. Every field is optional so the Docs tab can
move one knob without restating the rest.

budget_tokens integer | null Default null.
eval_k integer | null Default null.
fts_weights FtsWeightsPatch | null
k_fts integer | null Default null.
k_rerank integer | null Default null.
k_vec integer | null Default null.
limit integer | null Default null.
rrf_k number | null Default null.

DocumentRow

content_hashrequired string Gates incremental re-ingest: unchanged pages never re-run the model.
fetched_atrequired string
idrequired integer (int64)
source_idrequired integer (int64)
urlrequired string

DownloadEstimate

A download's size and the time it takes on this connection (D23).

engine_bytesrequired integer | null The engine image's layers still to fetch; None when it is on this
machine already or its size isn't known (notes says which).
files_bytesrequired integer (uint64) The files: the weights (every part) and their companions.
notesrequired array of string
rate_bytes_per_secrequired number | null Bytes per second; None with nothing measured.
rate_fromrequired RateSource
secsrequired integer | null The whole download's seconds at that rate, rounded up.
sentencerequired string | null "about 4 minutes on your connection".

DownloadRow

dest_pathrequired string
downloaded_atrequired string | null
errorrequired string | null
filerequired string
idrequired integer (int64)
job_idrequired integer | null Id of the hf_download job currently transferring this file, if any —
what "Cancel" acts on. None means nothing is running for this row.
kept_bytesrequired integer | null The bytes a failed, cut or paused transfer left in its .part, which
Retry or Resume goes on from (find-a-model design D135). None while
a transfer runs, and when nothing is kept.
percentrequired integer | null
received_bytesrequired integer | null
reporequired string
requested_revisionrequired string | null The revision the download asks for: main, or the commit an audio
catalog entry pins. None on a row from before it was recorded (a
main download).
resolved_commitrequired string | null The commit the file on disk came from (the hub's X-Repo-Commit).
None when unknown — every row downloaded before it was recorded.
sizerequired string | null
statusrequired string queued | downloading | done | failed | update_available — a row that
claims queued/downloading with no live progress is *interrupted*
(derived, never stored).
targetrequired string chat | aux | audio | image.

DownloadedFrom

Where a downloaded weights file came from.

download_idrequired integer (int64) The download's id.
filerequired string The file within it.
reporequired string The Hugging Face repository.

DraftStats

Speculative decoding's draft statistics, summed over a point's requests. Present only when the
server reported them.

acceptancerequired number | null accepted / drafted, None when nothing was drafted.
acceptedrequired integer (uint64)
draftedrequired integer (uint64)

EditApplied

One Dockerfile edit's result in a resolved preview: the run log's
"applied (N matches)" / "not matched", as data.

appliedrequired integer (uint32) Occurrences replaced; 0 = not matched (a run fails on that when the
edit is required).
indexrequired integer (uint32) Position in the edit list, from 0 (an edit's name may be empty).
namerequired string
requiredrequired boolean
rolerequired EditRole

EditRole

What a Dockerfile edit is for. The role is what lets the build's
own switches reach an edit that was customized: ccache off drops every
ccache and cache edit, whether it came
from the preset or was typed by hand.

One of: string (Compiler-cache wiring: the ccache package, the cache mount, the
compiler launchers, the stats line.); string (Another build cache mount (the web UI's npm cache). Optional, and a
cache like ccache: off with it.); string (Build number / commit / date injection, so --version names what was
built even though .git is not in the build context.); string (docker.io/ in front of a bare base image, so it resolves without a
short-name alias.); string (A different base-image variant (sd.cpp's -cudnn- dropped).); string (Anything else — what a hand-written edit is unless it says otherwise.)

EmbeddingsRequest

dimensions integer Forwarded (Gemini: outputDimensionality). A route that answers with another length — llama-server has no such parameter — is refused with 400 rather than served full-length vectors.
encoding_format string Encoded by the gateway, whatever the upstream: base64 is the little-endian float32 bytes, as OpenAI serves it. One of float, base64.
inputrequired any A string, or an array of strings. Token-id arrays are refused with 400: an alias can route to a model with another tokenizer.
modelrequired string

EmbeddingsResponse

datarequired array of object
embeddingrequired array of number | string Floats, or a base64 string when encoding_format was base64.
indexrequired integer
objectrequired string One of embedding.
modelrequired string
objectrequired string One of list.
usagerequired object
prompt_tokensrequired integer What the model reported; 0 when it reported nothing.
total_tokensrequired integer The same number: embedding generates nothing.

Energy

The energy of a measured window: a point's, summed over its repetitions.

avg_wrequired number (double)
joulesrequired number (double) The whole card, idle draw included.
secondsrequired number (double) Length of the measured windows, summed.
sourcerequired EnergySource
tokensrequired integer (uint64) The tokens those windows produced (prefill: prompt tokens; decode:
generated tokens).
tokens_per_joulerequired number | null tokens / joules; None when the windows measured 0 J.
tokens_per_joule_eachrequired Stat Tokens per joule of each window on its own (one per repetition, or
per request for prefill): the spread the comparison reads as this
figure's noise. A half-second decode window right after an idle
moment is measured while the card's clocks ramp up — live, decode at
depth 64 read 2.47 and 3.01 tok/J in two runs of identical settings.
Windows the counter did not move over are left out.

EnergySource

Where a joule figure came from.

One of: string (The driver's total-energy counter, read at both ends of the window
(NVML nvmlDeviceGetTotalEnergyConsumption).); string (Power samples integrated over the window (trapezoids), because the
counter is not available.)

EnergySummary

The run's VRAM and energy picture.

baseline_vram_bytesrequired integer | null Device VRAM used before the bench container started.
idle_power_wrequired number | null Mean power over the baseline window, so a view can show net energy.
peak_power_wrequired number | null
peak_vram_bytesrequired integer | null
sourcerequired EnergySource | null How the run's joules were measured; None when the GPU reports no
power at all (then unavailable says why).
total_joulesrequired number | null First sample to last.
unavailablerequired string | null

Engine

Which of the three engines lmgw runs a build produces. ik_llama.cpp is
Llama with its own repo preset, not an engine of its own: its images run
in the same classes.

One of: string (llama.cpp and ik_llama.cpp — llama-server.); string (audio.cpp — audiocpp_server.); string (stable-diffusion.cpp — sd-server.)

EngineDownload

What a model download did about the image the models of its class run
in (machine-check design §5, D16): that image was not on this machine,
so the download fetches it too — through the image_pull job a start
of the model would use, keyed by the reference, so a start or an
Engines-page pull of the same image joins it. Nothing is started: the
first request then only loads the model.

imagerequired string The image reference, as the class's Image setting names it.
job_idrequired integer | null The image_pull job fetching it: started now, or the one already
pulling it. Its bytes are on the jobs feed (done/total, and
size_note in its detail when the size is not known), and
container_image_pull_status reads how it ended. null unless
state is downloading; note says why.
noterequired string | null Why nothing is downloading: why it could not begin (an image built
on this machine is never pulled — "run its build again on the
Engines page" — and a reference no registry can give is refused),
or why podman could not say whether the image is here.
staterequired EngineFetch What became of it: downloading, refused, or not known whether it
is needed.

EngineFetch

What became of a model download's fetch of its class's image
(EngineDownload::state).

One of: string (The image is missing and its image_pull job runs (job_id).); string (The image is missing and its download could not begin (note).); string (Podman failed to say whether the image is on this machine, or did
not answer in time (note): nothing was fetched, and the model's
first start looks again.)

EnrolledDevice

Enrolment::device.

idrequired integer (int64) The device row's api_keys.id; re-pairing keeps it.
namerequired string The device's name as lmgw gave it, without device:.

ErrorKindSeries

countsrequired array of integer (int64) Aligned with buckets.
kindrequired string
refusalrequired boolean True when this kind is lmgw refusing, rather than an upstream or a
client failing — the two belong in different colours.
totalrequired integer (int64)

EvalRunRow

One measured run. params is the stage parameter set it was measured under —
two runs under different parameters are not comparable, so the numbers
never travel without them.

corpus_idrequired integer (int64)
created_atrequired string
hit_at_krequired number (double)
idrequired integer (int64)
krequired integer (int64)
mrrrequired number (double)
orphaned_queriesrequired integer (int64) Queries whose every expected chunk is gone — they score zero for a
reason that is not "retrieval got worse".
params any The stage parameters it was measured under; absent when the stored text
does not parse.
queriesrequired integer (int64)
regressionrequired boolean
report any Full per-query breakdown; absent on the same terms as params.

Example

One static example exchange: what the user says, and how the model
replies. Both sides are non-empty.

replyrequired string
userrequired string

ExportAttachment

An attachment as the export carries it: its metadata, position and bytes.

blockers array of string For a draft: why it cannot be sent to the thread's current model.
call_id string The tool call that made a tool file, or the card action that made
an action file (its act-<boot>-<n> id, the one its stream's
frames carried); absent for an upload.
created_atrequired string When it was uploaded.
datarequired string The file's bytes, base64 (standard alphabet, padded).
extractedrequired string | null The text extracted from it (a PDF's pages, an office file, an audio
file's transcript); null when there is none.
extracted_tokensrequired integer | null The extracted text's token estimate; null when there is none.
hints array of string For a draft: what it becomes on the way, sent all the same (an image
as a placeholder, a PDF's pages as its text) under a fallback that
cannot see.
idrequired integer (int64)
kindrequired string image, pdf, text, audio, ... as the upload was classified.
metarequired AttachmentFacts What extraction found: pages, text-less pages, class, sheets,
transcript alias or error, tokens. {} for an image.
mimerequired string
moderequired string | null A text-class PDF's choice, text or images; null when it does
not apply or is not chosen yet.
namerequired string
ordrequired integer (int64) Its position among its message's files.
sizerequired integer (int64) Size in bytes.
sourcerequired string Where the file came from: upload (the user sent it), tool (an
image or audio tool of a turn made it) or action (an image card's
action made it). One of upload, tool, action.

ExportMessage

A message as the export carries it: the columns of a stored message with
its ir_messages parsed, and the files sent with it.

answered_byrequired string | null
attachmentsrequired array of ExportAttachment
completion_tokensrequired integer | null
contentrequired string
contextrequired MessageContext | null
created_atrequired string
idrequired integer (int64)
images_note string
ir_messagesrequired any An agentic turn's tool calls and results as the JSON value the
record holds; null for a plain turn. When the record does not
parse, its raw text and ir_messages_unparsed: true.
ir_messages_unparsed boolean Set (to true) only when ir_messages is the raw text of a record
that did not parse.
kb_refsrequired array of integer (int64)
modelrequired string | null
originrequired string | null A user message's origin: where its client said the user wrote it.
prompt_tokensrequired integer | null
reasoningrequired string
rolerequired string user, assistant or tool.
task MessageTask
thread_idrequired integer (int64)
voicerequired MessageVoice | null

ExportRef

A folder or personality profile named in an export.

idrequired integer (int64)
namerequired string

ExportThread

A thread as the export carries it: the columns of the thread list's row
(ThreadRow) except the two derived from other rows, last_message_at
and purge_at.

agent_idrequired string | null
archived_atrequired string | null
created_atrequired string
folder_idrequired integer | null
frequency_penaltyrequired number | null
idrequired integer (int64) Negative for a temporary thread.
kb_budget_tokensrequired integer | null
kb_idsrequired array of integer (int64)
kb_moderequired KbMode
kindrequired string chat or admin.
max_tokensrequired integer | null
mcp_toolsrequired array of ThreadMcp
media_defaultsrequired MediaDefaults The image and audio tools' default models of its own.
min_prequired number | null
model_aliasrequired string
pinnedrequired boolean
presence_penaltyrequired number | null
profile_idrequired integer | null
reasoning_budgetrequired integer | null
reasoning_effortrequired string | null
reasoning_enabledrequired boolean | null
repeat_penaltyrequired number | null
seedrequired integer | null
stoprequired array of string
system_promptrequired string
temperaturerequired number | null
temporaryrequired boolean The thread was held in memory only (a temporary chat).
titlerequired string
top_krequired integer | null
top_prequired number | null
updated_atrequired string
voicerequired ThreadVoice

ExtraChange

One unpinned extra's change since the last verified run.

changerequired string The badge's own wording: "pushed", "closed unmerged", or one
of the two "merged upstream" readings (see reasons of the update status).
labelrequired string

Fallback

The fallback that answers for a blocked model, and whether it is a local
model: a local one may be a fallback too, and answers where it may run
(a row on the CPU under the hold).

aliasrequired string
localrequired boolean

FallbackUnusable

A named hold fallback that cannot answer: why is the clause the hold's
refusal names it with ("does not resolve", "is itself a candidate alias").

aliasrequired string
whyrequired string

FeedHold

The GPU hold: whether local models are paused. A held model answers with
its own fallback, where one is set (each thread's model says which). The
hold event and part of Hello.

activerequired boolean The owner's GPU hold is on: models on the graphics card are paused.
benchmarkrequired boolean A benchmark run holds the graphics card: every local model waits
until it ends, one on the CPU too, or answers with its fallback
(chat-plane design D6).

FeedPrincipal

Who the feed is for: its kind and the name it is known by, without the
kind's prefix. A paired device is kind device, named as it was paired
("desktop", not "device:desktop"); the gateway's administrator has the
other kind: the dashboard (named dashboard) or an admin key (named as
the key without its prefix).

kindrequired string One of device, owner.
namerequired string

FileFit

One file's fit on the card, by one measure (design §3.1, §9.2).

besiderequired BesideTerms | null What else is on the card, for the beside measure.
bits_per_weightrequired number | null Bits per weight over the repeating layers (D7), every part of a split
file's.
capacity_bytesrequired integer (uint64) The room this measure leaves: the card, less what is beside it for
the beside measure. The headroom comes off it as well.
ctxrequired integer | null The largest context that fits, at most the trained one (D6); None
when nothing fits, without a card, or for a mark by size.
headroom_bytesrequired integer (uint64)
markrequired FitMark
measurerequired FitMeasure
notesrequired array of string What the reader should also know, each a sentence: the hold, admission
off, a term that couldn't be sized, why the header wasn't read.
parametersrequired integer | null The model's parameters from the header's descriptors (D7, D131).
termsrequired FitTerms
trained_ctxrequired integer | null The model's trained context, from its header.
uses_bytesrequired integer (uint64) The footprint at ctx (at one token when nothing fits; the files'
bytes for a mark by size), without the headroom.

FilePick

The file a repo's list recommends, by one measure (design §3.2).

filerequired string | null The recommended file; None when no file qualifies.
full_contextrequired FullContextFile | null When the pick fits only a shorter conversation and a smaller file of
at least 4 bits per weight keeps the whole one.
measurerequired FitMeasure
rulerequired PickRule
whyrequired string The "Why this file" line.

FindAnswer

What a model_find answer is (§4.5).

One of: string (A card: a model with a file that fits by its size.); string (Nothing on the hub matches.); string (A match exists, but no GGUF of it does.); string (Only repos that match some of the words: did_you_mean.); string (Every upload that could be used is gated and couldn't be read.); string (No file of the top author's models fits: the card says so, for the
one closest to fitting.); string (The model has GGUF files, but none of 4 to 8 bits per weight, the
files lmgw picks by itself (D71): the sentence says what they are.); string (The top match is a kind of model Find a model doesn't set up yet
(pictures, speech): the sentence points to where it is added.); string (Hugging Face couldn't be reached.); string (Hugging Face's rate limit is used up: hub_budget.reset_s says when
it resets.); string (An address on another host: answered locally, nothing sent (D124).); string (A Hugging Face page that isn't a model's (an account's, a dataset's,
a Space's): answered locally, nothing sent.); string (A later page of the search (cursor): only the lists.)

FitChange

One parameter "Fit again" changes.

fromrequired integer | null
keyrequired string ctx_size, ubatch_size or batch_size.
torequired integer | null

FitChangeInput

One parameter "Fit again" changes.

from integer | null Default null.
key string ctx_size, ubatch_size or batch_size. Default "".
to integer | null Default null.

FitMark

A file's mark (design §3.3).

One of: string (Fits with the model's whole trained context (ctx is it).); string (Fits a shorter conversation: ctx is the largest that fits.); string (Doesn't fit, not even at one token.); string (The header wasn't read (or couldn't be), and the file's bytes plus
the headroom fit: "fits by size · not checked" (D8).); string (The header wasn't read (or couldn't be), and the file's bytes alone
are more than the room (D8).); string (Neither the header's fit nor the file's size is known: the listing
gives no size, or a split file's part is missing. Never a fit.); string (Nothing to measure against: no GPU telemetry and no declared budget
(D9).)

FitMeasure

Which of the two measures of "fits" a FileFit was taken against
(design D5, D120).

One of: string (The whole card as admission measures it, with nothing else on it:
admission unloads lmgw's other models when this one is asked for.); string (The card less what other programs hold on it now and less lmgw's own
models on it now.)

FitNote

The note a row keeps when its context was fitted to the card rather
than planned at the trained one (D26): what Get it (WP5) writes on the
row it creates, and what the model editor's "Fit again" renews.

atrequired string When, as the server's UTC time (YYYY-MM-DD HH:MM:SS).
capacity_bytesrequired integer (uint64) That measure's room, before the headroom, and the headroom.
ctxrequired integer (uint64) The context the row got.
headroom_bytesrequired integer (uint64)
measurerequired FitMeasure The measure it was fitted to.
trained_ctxrequired integer | null The model's trained context, which the plan proposed.

FitTerms

What a footprint is made of, at the fit's context.

compute_bytesrequired integer (uint64) Working memory: the compute buffers.
kv_cache_bytesrequired integer (uint64) The conversation's memory: the KV cache and any recurrent state.
weights_bytesrequired integer (uint64) The weights on the card, the projector and the drafter included.

Folder

A Chat folder as GET /chat/api/folders lists it, with its thread
counts as the caller may see them.

archive_daysrequired integer | null Days without activity before one of its threads is archived; null
for the Chat's setting, 0 never. Set from the dashboard: a device
key cannot change it.
created_atrequired string
defaultsrequired ThreadDefaults
devices_hiddenrequired boolean Set when a device deleted this folder while it held threads that
device could not see: the folder stays for them, hidden from every
device, until it is shown to devices again from the dashboard. Always
false for a device key, which never sees such a folder.
idrequired integer (int64)
namerequired string Folder names need not be unique.
ongoingrequired FolderOngoing | null null for a folder that is not one ongoing conversation.
purge_daysrequired integer | null Days after archiving before one of its threads is deleted; null
for the Chat's setting, 0 never. Set from the dashboard: a device
key cannot change it.
sortrequired integer (int64) The folder's place in the list.
threads_activerequired integer (int64)
threads_archivedrequired integer (int64)
updated_atrequired string

FolderChanged

folder.created / folder.updated for a folder that exists at
delivery: the folder as GET /chat/api/folders lists it now (its counts
as the reader may see them), with by beside its fields.

archive_daysrequired integer | null Days without activity before one of its threads is archived; null
for the Chat's setting, 0 never. Set from the dashboard: a device
key cannot change it.
byrequired string | null Who made the change; null for the gateway's own.
created_atrequired string
defaultsrequired ThreadDefaults
devices_hiddenrequired boolean Set when a device deleted this folder while it held threads that
device could not see: the folder stays for them, hidden from every
device, until it is shown to devices again from the dashboard. Always
false for a device key, which never sees such a folder.
idrequired integer (int64)
namerequired string Folder names need not be unique.
ongoingrequired FolderOngoing | null null for a folder that is not one ongoing conversation.
purge_daysrequired integer | null Days after archiving before one of its threads is deleted; null
for the Chat's setting, 0 never. Set from the dashboard: a device
key cannot change it.
sortrequired integer (int64) The folder's place in the list.
threads_activerequired integer (int64)
threads_archivedrequired integer (int64)
updated_atrequired string

FolderGone

folder.deleted, and folder.created / folder.updated for a folder
that is gone by the time the event is delivered.

byrequired string | null
deletedrequired boolean
folder_idrequired integer (int64)

FolderOngoing

The ongoing field of a folder: null for a folder that is not an
ongoing conversation.

current_thread_idrequired integer | null The thread the conversation continues in; null until the first
current call, after its thread was deleted, moved out of the
folder or archived by hand, and, for a device key, while the thread
is out of the key's reach.
idle_minutesrequired integer (int64) Minutes without a message after which the next current call starts
a new thread. 0: a new thread only when a client asks for one.

FolderRef

A folder named by its id and name.

idrequired integer (int64)
namerequired string

Forge

Where a build's repository lives, which decides how PR extras are found.

One of: string (PRs are refs/pull/<n>/head, details from the GitHub REST API.); string (MRs are refs/merge-requests/<n>/head, details from /api/v4.); string (No PR list and no forge API: refs from other remotes only.)

ForgePr

One PR (GitHub) or MR (GitLab) as the extras picker shows it.

authorrequired string
base_sharequired string
draftrequired boolean
head_sharequired string
merge_commit_sharequired string The commit the merge put on its target branch — the merge, squash or
rebase commit (GitHub merge_commit_sha; GitLab merge_commit_sha,
else squash_commit_sha). Empty when the forge gives none (an open
PR, an old GitLab). A build skips a merged PR as "merged upstream"
only when its base contains this commit (or the PR's head).
merged_atrequired string | null Set once the forge reports it merged.
numberrequired integer (uint64)
staterequired string The forge's own spelling (open | closed).
titlerequired string
updated_atrequired string
urlrequired string

FtsWeightsPatch

The four BM25 column weights, each optional like every other stage default.

derived_summary number | null Default null.
derived_title number | null Default null.
heading_path number | null Default null.
payload number | null Default null.

FtsWeightsView

BM25 column weights, in chunk_fts column order.

derived_summaryrequired number (float)
derived_titlerequired number (float)
heading_pathrequired number (float)
payloadrequired number (float)

FullContextFile

The smaller file that keeps the whole context, named in the fold when the
pick fits only a shorter one (D7).

bits_per_weightrequired number | null
filerequired string
quantrequired string | null
sentencerequired string "Q4_K_S remembers all 262 144 tokens, at 4.6 bits per weight."
trained_ctxrequired integer (uint64)

FusedHitView

chunk_idrequired string
fts_rankrequired integer | null
knn_rankrequired integer | null
rrf_scorerequired number (float)

GetWaiting

One file of a get that waits (WP7, D108).

filerequired string The file's path in the repo.
noterequired string | null The download row's own note, as the Downloads page shows it; None
when it has none (not_started).
reasonrequired WaitReason

GgufFile

pathrequired string Relative to models_dir — exactly what the path fields take.
role_guessrequired string weights | mmproj | drafter (filename guess).
sizerequired string
size_bytesrequired integer (uint64)
used_byrequired array of string

GoldenCandidateRow

One generated query awaiting a decision. It is **not** a golden query: an
eval never scores it, and only an accept turns it into one.

corpus_idrequired integer (int64)
created_atrequired string
decided_atrequired string Empty while it is still pending.
expected_chunk_idsrequired array of string The chunk it was written from — attached by code, never named by the
model.
golden_query_idrequired integer | null The golden query it became, when it was accepted.
idrequired integer (int64)
modelrequired string The model that wrote it — the corpus's pinned ingest model.
queryrequired string
rationalerequired string The model's sentence about why that chunk answers it.
statusrequired string pending | accepted | rejected.

GoldenQueryRow

corpus_idrequired integer (int64)
expected_chunk_idsrequired array of string
idrequired integer (int64)
originrequired string manual | synthetic.
queryrequired string

GpuBackend

The GPU backend a build targets, labelled **GPU backend** on the Engines
page. Picks the preset's Dockerfile candidate.

string

GpuIdentity

The GPU the run used, as far as the sampler sees it. Sums and maxima over the visible
devices.

clock_eventsrequired integer (uint64) The OR of every sample's clock-event reasons.
devicesrequired integer (uint32)
driverrequired string | null
namerequired string | null The first device's name (a comparison key).
power_limit_wrequired number | null The enforced power limit.
telemetryrequired string The GPU probe's own label (NVML (driver …), or why there is none).
temp_end_crequired integer | null
temp_max_crequired integer | null
temp_start_crequired integer | null
throttledrequired boolean Whether any of those is a throttling reason: NVML's software power cap
(0x4), hardware slowdown (0x8), software or hardware thermal
slowdown (0x20, 0x40) or power-brake slowdown (0x80). Idle, the
applications-clocks setting, sync boost and the display clock are
states, not throttling. A run that throttled reports the throttled
numbers.
vram_total_bytesrequired integer | null

GroupApplied

A group, apply: every running member recreated, and the static checks
over every enabled model in scope.

advisoriesrequired array of ContainerAdvisories
busyrequired array of ContainerBusy
errorsrequired array of ContainerFailure
heldrequired array of ContainerModel Stopped and not started again because the GPU hold is on.
messagerequired string
models_enabledrequired integer (uint)
models_with_advisoriesrequired integer (uint)
models_with_problemsrequired integer (uint)
noterequired string
okrequired boolean
problemsrequired array of ContainerProblems
recreatedrequired array of ContainerPort
targetrequired string

GroupRestarted

A group, restart.

busyrequired array of ContainerBusy
errorsrequired array of ContainerFailure
heldrequired array of ContainerModel Left running untouched because the GPU hold would not let them start
again.
messagerequired string
okrequired boolean
restartedrequired array of ContainerPort
targetrequired string

GroupStarted

A group, start: only the models flagged warm_start are started.

already_runningrequired array of ContainerModel
errorsrequired array of ContainerFailure
heldrequired array of ContainerModel Left alone because the GPU hold is on.
noterequired string
okrequired boolean
startedrequired array of ContainerPort
targetrequired string

GroupStatus

A group, status.

okrequired boolean
runtimerequired array of RuntimeStatus The containers of the group.
targetrequired string The group asked about: all, chat, aux, audio or image.
vramrequired VramStatus The GPU ledger, whole even when one group was asked about.

GroupStopped

A group, stop.

busyrequired array of ContainerBusy Still serving requests and left running; override forces them.
errorsrequired array of ContainerFailure
messagerequired string
okrequired boolean
stoppedrequired array of ContainerModel
targetrequired string

Headline

The headline numbers of one run, each None when the run did not
measure it.

aggregate_streamsrequired integer | null
aggregate_tok_srequired number | null Aggregate tok/s at *N_slots* streams.
decode_deep_depthrequired integer | null
decode_deep_tok_srequired number | null Decode tok/s at the deepest point, *D_max*.
decode_tok_srequired number | null Decode tok/s at depth 64.
decode_tokens_per_joulerequired number | null Decode tokens per joule at depth 64.
load_msrequired integer | null
load_vram_bytesrequired integer | null VRAM the load took (after load minus the baseline).
prefill_tok_srequired number | null Prefill tok/s at 2048 tokens, or the nearest measured length.
prefill_tokensrequired integer | null The length it was measured at.
stall_msrequired number | null The mixed phase's median stall.
ttft_msrequired number | null TTFT at that same length.

HeatCell

dowrequired integer (int64)
hourrequired integer (int64)
requestsrequired integer (int64)

HelloCert

Hello::cert: the device certificate's dates, RFC 3339 UTC.

not_afterrequired string When the certificate lapses.
notice_afterrequired string From when the device says "this certificate lapses on <not_after>;
pair it again before then" (two thirds of its validity).

HfCompanion

A file hf_add queued beside the weights.

filerequired string Path inside the repo.
rolerequired string mmproj | drafter.

HfUpdatesChecked

POST /api/op/hf_set with action: check_updates: the tracked downloads of
one class compared with the hub.

errorsrequired array of string One sentence per file the hub could not be asked about.
okrequired boolean false when a file could not be compared (errors is not empty); the
answer is still a success, for the files that could.
updates_availablerequired integer (uint64) How many finished downloads now differ from the hub's copy; each is
flagged update_available.

HoldSettingsDto

The GPU hold settings. active is
reported here but never settable through SettingsFullPatch — it is
toggled only through the hold_set op, because engaging it has the side
effect of stopping containers.

activerequired boolean

HostCpu

This machine's CPUs (reported as host_cpu).

logical_cpusrequired integer (uint32) Online logical CPUs, SMT siblings included.
physical_coresrequired integer (uint32) Physical cores, or the logical count when the topology is unreadable
(source).
sourcerequired string topology (counted from the kernel's CPU topology) | logical (the
topology could not be read, so the logical count stands in).

HostSettings

Settings → MCP (mcp.* in GET /api/settings-full): the host link's
limits, each explicit on the link's WebSocket (§5.1), and the MCP Tasks
poll interval.

host_max_frame_mbrequired integer (uint32) The largest frame, in MiB; 0 = bounded by host_max_message_mb.
host_max_message_mbrequired integer (uint32) The largest message a device may send, in MiB; 0 = no bound of its
own (a frame is then bounded by host_max_frame_mb). Not 0
together with host_max_frame_mb. A full-desktop screenshot is the
expected large message.
host_ping_interval_srequired integer (uint32) Seconds between the link's pings; a ping with no pong for a whole
interval closes the link. 0 = no pings, and no bound on a device
that stopped answering.
task_poll_interval_srequired integer (uint32) Seconds between two tasks/get of an MCP task whose server suggests
no pollInterval of its own (MCP Tasks design §5.2); a server's
status notifications act at once. At least 1.

HostedCallCount

One hosted call type and its count (UnpricedHostedTool::calls).

callsrequired integer (int64)
item_typerequired string The output item type: web_search_call, file_search_call,
code_interpreter_call, image_generation_call or shell_call.

HubBudget

The hub's rate limit after this answer (§4.5), from its RateLimit and
RateLimit-Policy headers. lmgw keeps no counter of its own.

allowancerequired string | null What the hub allows, from the last policy it sent, with or without
the token ("Without an account it allows 500 requests every 5
minutes; a Hugging Face token in Settings raises that."): the end of
sentence, alone, for a page that says the wait itself. None
without a policy.
callsrequired integer (uint32) The requests this answer made.
nearrequired boolean Fewer requests are left than this answer made: the next search may
meet the limit.
quotarequired integer | null Requests the window allows.
remainingrequired integer | null Requests left in the window.
reset_srequired integer | null Seconds until the window resets.
sentencerequired string | null What the person reads when near or limited.
window_srequired integer | null The window's length in seconds.

ImageAsset

image_upscale boolean
namerequired string

ImageCapabilities

One sd-server's own answer about the pipeline it loaded.

Every field defaults, because this is the one payload in the class that
comes from a moving container tag: a build that stops reporting a number
must leave the rest readable rather than fail the frame.

current_moderequired string
defaults_by_moderequired object The request defaults per mode, as the server serializes its own
request struct (img_gen → {width, height, sample_params, …}).
featuresrequired ImageFeatures
limitsrequired ImageLimits
lorasrequired array of ImageAsset
output_formatsrequired array of string
preview_modesrequired array of string The preview modes the build offers (none, proj, tae, vae);
empty for a build without previews.
samplersrequired array of string
schedulersrequired array of string
supported_modesrequired array of string ["img_gen"], ["img_gen","vid_gen"] — what the loaded pipeline can
actually do, as opposed to what the row claims.
upscalerequired boolean The build can upscale with a model under its upscalers directory.
upscalersrequired array of ImageAsset

ImageEditsRequest

Refused unless the resolved model's row has its edit pipeline enabled.

imagerequired array of string (binary) One or more image files. lmgw relays every multipart field named image verbatim, with no cardinality check of its own.
mask string (binary)
modelrequired string
n integer
promptrequired string
size string

ImageFeatures

Which optional inputs the loaded pipeline admits to accepting. Not an edit
gate — the row's edit column is.

cacherequired boolean
cancel_generatingrequired boolean
cancel_queuedrequired boolean
control_imagerequired boolean
hiresrequired boolean
init_imagerequired boolean
ip_adapter_imagerequired boolean
lorarequired boolean
mask_imagerequired boolean
previewrequired boolean The job API draws previews of a running generation.
ref_imagesrequired boolean
vae_tilingrequired boolean

ImageGenForm

Everything the lab's two panels collect, as typed. Numbers travel as the
strings the inputs hold: an empty field means "say nothing about this", not
zero, and a malformed one has to be reportable as a message rather than
silently become a default.

cfg_scalerequired string
heightrequired string
lorasrequired array of ImageLoraRow
modelrequired string The public alias — image/<id> for a local row, the alias for a cloud
one. Rewritten to the concrete upstream id by the route itself.
nrequired string
negative_promptrequired string
output_compressionrequired string
output_formatrequired string
promptrequired string
samplerrequired string
schedulerrequired string
seedrequired string Blank says nothing (sd-server's own default is a fixed 42); -1 is its
spelling for "random each run".
stepsrequired string
widthrequired string

ImageGenFormInput

Everything the lab's two panels collect, as typed. Numbers travel as the
strings the inputs hold: an empty field means "say nothing about this", not
zero, and a malformed one has to be reportable as a message rather than
silently become a default.

cfg_scale string Default "".
height string Default "".
loras array of ImageLoraRowInput Default [].
model string The public alias — image/<id> for a local row, the alias for a cloud
one. Rewritten to the concrete upstream id by the route itself. Default "".
n string Default "".
negative_prompt string Default "".
output_compression string Default "".
output_format string Default "".
prompt string Default "".
sampler string Default "".
scheduler string Default "".
seed string Blank says nothing (sd-server's own default is a fixed 42); -1 is its
spelling for "random each run". Default "".
steps string Default "".
width string Default "".

ImageGenerationsRequest

Other keys are forwarded for a cloud image upstream.

modelrequired string
n integer
output_compression integer
output_format string
promptrequired string May carry a trailing <sd_cpp_extra_args>{…}</sd_cpp_extra_args> block of raw sd.cpp CLI arguments; the dashboard's Image lab builds this block and is the reference for its contents.
size string

ImageGenerationsResponse

The upstream's answer, relayed as it sends it: each image carries what response_format asked for, plus whatever else the upstream adds (revised_prompt).

createdrequired integer
datarequired array of any | any
b64_json string
revised_prompt string
url string

ImageLabEditRequest

multipart/form-data. The body size is not limited.

formrequired string The form as a JSON string: the ImageGenForm the generate route takes as its body, with optionally image and mask naming kept pictures ({id, name}, an artifact the lab store keeps) in place of an upload.
image string (binary) The picture to edit; stands in for the form's image ref. One of the two is required.
mask string (binary) An optional mask.

ImageLabForm

A group's form: the page's form, and for an edit its picture and mask as
kept files. Also what an edit's form part takes, so a re-opened edit
names its kept picture instead of uploading it again; an image or
mask part of the upload stands in for the ref.

cfg_scale string Default "".
height string Default "".
image LabFileRef | null An edit's picture, kept; null for a generation. Default null.
loras array of ImageLoraRowInput Default [].
mask LabFileRef | null An edit's mask, kept; null without one. Default null.
model string The public alias — image/<id> for a local row, the alias for a cloud
one. Rewritten to the concrete upstream id by the route itself. Default "".
n string Default "".
negative_prompt string Default "".
output_compression string Default "".
output_format string Default "".
prompt string Default "".
sampler string Default "".
scheduler string Default "".
seed string Blank says nothing (sd-server's own default is a fixed 42); -1 is its
spelling for "random each run". Default "".
steps string Default "".
width string Default "".

ImageLabModel

One model the Image lab can generate with: a local image/<id> row, or a
cloud alias whose upstream catalog says it draws. C is the shape of the
probed capabilities: the gateway fills in its own, a reader (and the API
document) uses ImageCapabilities.

argsrequired object | null The flags a local row's container is started with (width, height,
steps, cfg_scale, sampling_method are the form's defaults when
set); null for a cloud alias.
editrequired boolean Whether it serves /v1/images/edits.
endpointsrequired array of string The /v1 routes the model serves.
image_capabilitiesrequired ImageCapabilities | null What the running container reported about its loaded pipeline: the
samplers, schedulers, size bounds and LoRAs on disk. null until a
container has been probed.
localrequired boolean A local row of this gateway, not a cloud alias.
model_idrequired string | null The local row's model id; null for a cloud alias.
modesrequired array | null A local row's pipelines (img_gen, vid_gen, ...), as the operator
declared them; null for a cloud alias.
namerequired string The alias to send as model.
notesrequired array of string What the gateway noticed about the model, one sentence each.
ownerrequired string The upstream that serves it (local for the gateway's own rows).
staterequired string | null A local row's container state (starting, ready, stopping);
null when it has none running, and for a cloud alias.
taskrequired string The model's task, as GET /v1/models reports it.
warningsrequired array of string Non-fatal problems the running container's start found.

ImageLimits

Bounds the server enforces on a request — **the server's real numbers**;
lmgw never substitutes one of its own, so a None is shown as unknown
rather than filled in.

max_batch_countrequired integer | null
max_heightrequired integer | null
max_queue_sizerequired integer | null
max_upscale_heightrequired integer | null
max_upscale_widthrequired integer | null
max_widthrequired integer | null
min_heightrequired integer | null
min_widthrequired integer | null

ImageLoraRow

One row of the optional LoRA table. <lora:…> prompt tags are refused by
every sd.cpp family, so a LoRA is this structured field or nothing.

multiplierrequired string Blank leaves the server's own multiplier in place.
pathrequired string A name from the probed loras list, or a path the server can resolve
under its --lora-model-dir.

ImageLoraRowInput

One row of the optional LoRA table. <lora:…> prompt tags are refused by
every sd.cpp family, so a LoRA is this structured field or nothing.

multiplier string Blank leaves the server's own multiplier in place. Default "".
path string A name from the probed loras list, or a path the server can resolve
under its --lora-model-dir. Default "".

ImageModel

An image model row — one stable-diffusion.cpp pipeline.

The two JSON-map fields stay dynamic on purpose, exactly as the server
types them: sd.cpp adds a model family and its flag every few weeks, and
the keys are validated against the container image's own --help rather
than against any enum on either side of this wire.

argsrequired object Runtime + default-generation flags, same key convention. A true
renders as a bare switch.
capabilities_override any An alias's capabilities override for the derived /v1/models capability facts.
editrequired boolean The pipeline takes reference images and may serve /v1/images/edits.
enabledrequired boolean
extra_run_argsrequired array | null Per-model podman run args override; None inherits the class's.
fallbackrequired string | null The model or alias that answers whenever this one cannot (the GPU
hold, VRAM outside lmgw, background traffic deferred, a disabled
row), as written. None = no fallback.
filesrequired object Flag key → path relative to the image models dir. Exactly one of
model / diffusion_model is present on a valid row.
idrequired integer (int64)
idle_secondsrequired integer (int64) Seconds idle before the container is stopped; 0 never reaps.
imagerequired string | null Per-model container image override; None inherits the image class
settings' image.
model_idrequired string
modesrequired array of string img_gen / vid_gen; empty means the default (img_gen).
peak_extra_bytesrequired integer | null The learned transient peak: what one generation was measured to need
above this pipeline's idle residency. Written by
the gateway, not by the editor — a files or args change resets it
to None, because a different pipeline has a different peak.
peak_learned_atrequired string | null When that figure was observed; None whenever the peak is.
preview_moderequired PreviewMode | null How a running generation's preview is drawn (design §5.2); None
is the default: a quick sketch where the build offers it, else off.
prompt_stylerequired PromptStyle | null How the chat model writes this row's prompts (chat-media-tools
design §3.4); None derives it from the matching recipe.
warm_startrequired boolean

ImageModelDetail

An image-generation pipeline read back.

argsrequired object Runtime and default-generation flags.
capabilities_overriderequiredany
command_linerequired string
editrequired boolean
enabledrequired boolean
endpointsrequired array of string The routes that serve it.
extra_run_argsrequired array | null podman run args override, one entry per argument; null inherits.
fallbackrequired string | null The one fallback (openai egress design §14.2), as written; null =
none.
filesrequired object Flag key to path under the image models dir.
files_presentrequired object For each key of files, whether the file (or directory) exists.
idrequired integer (int64)
idle_secondsrequired integer (int64)
imagerequired string | null
model_idrequired string
modesrequired array of string
peakrequired string peak_extra_bytes in a sentence.
peak_extra_bytesrequired integer | null Bytes one generation was measured to need above idle residency;
null until one has run.
peak_learned_atrequired string | null
problemsrequired array of string
public_namerequired string The name clients call it by, with the image prefix.
warm_startrequired boolean

ImageModelView

deferrals_24hrequired integer (uint64) LocalModelView::deferrals_24h, for this row's public_name.
derived_prompt_stylerequired PromptStyle | null The prompt style the shipped recipe matching this row's weights
gives it (chat-media-tools design §3.4): what applies while the
row's own prompt_style is unset. null when no recipe matches.
modelrequired ImageModel
public_namerequired string

ImageProvenance

An image's build provenance: read
from the dev.lmgw.* OCI labels, so an image stays self-describing even
after its builds/build_runs rows are gone.

baserequired string Base SHA the run built from (dev.lmgw.base).
build_idrequired integer (int64)
build_namerequired string | null The build's name as it is now — its slug when it has no name — read
from the builds table, so "follows <build>" needs no second call.
None once the build is deleted (the labels outlive it).
extrasrequired array of ResolvedExtra The extras merged in, each with its resolved SHA (dev.lmgw.extras,
stored on the image as JSON) — the same
shape a run's inputs.resolved carries.
git_refrequired string
instancerequired string The lmgw instance that built it (dev.lmgw.instance: one per data
dir, so a dev instance's images are told from production's). Empty
on an image built before the label existed.
other_instancerequired boolean Built by another lmgw instance than the one answering. Its build and
run ids are that instance's, so build_id and run_id are 0 and
build_name is None — the provenance is the labels' alone.
reporequired string
run_idrequired integer (int64)
slugrequired string

ImagePullJobDetail

JobRow.detail for kind = "image_pull": podman's latest output line,
and the bytes downloaded so far (machine-check design §5). The job's
own done/total are the same bytes.

done_bytesrequired integer (uint64) Compressed layer bytes downloaded so far, as Podman's API reports
them; 0 while nothing was reported, and on the podman pull command's
path, which reports none.
imagerequired string
last_linerequired string
old_idrequired string | null The image ID the reference named before the pull; None when it was
not on this machine.
size_noterequired string | null Why the size is not known, when it is not: "size not known — …".
total_bytesrequired integer | null The whole download: the compressed size of the layers the registry's
manifest lists for this machine, less those Podman found it already
had. None when it is not known; size_note then says why.

ImagePullResult

The result of a finished image_pull job (stored on its job row). A pull
replaces no running container: used_by is who still runs (or names) the
old image, for the page's "Recreate N running containers" offer.

imagerequired string
logrequired array of string podman's output, line by line: the podman pull command's whole
output, or through Podman's API each blob's changes (not its byte
counts) and a closing line of what came down.
new_digestsrequired array of string
new_idrequired string
old_digestsrequired array of string sha256:… digests podman recorded for the reference before and after.
old_idrequired string | null
updatedrequired boolean The reference now names a different image than before.
used_byrequired array of ImageUse

ImageRecipe

One shipped family.

argsrequired object Runtime + default-generation flags for the prefilled row, already in
ImageModel.args shape.
componentsrequired array of ImageRecipeComponent
descriptionrequired string
display_namerequired string
editrequired boolean
installedrequired boolean Every component is already on disk.
keyrequired string
modesrequired array of string
partialrequired boolean Some but not all components are on disk or downloading.
servedrequired boolean An image model row already names this recipe's primary file.
suggested_model_idrequired string Suggested model_id for the prefilled row.
total_bytesrequired integer (uint64) Bytes of the default file set, on disk.
total_sizerequired string
vram_noterequired string Measured VRAM where a spike measured it, and the word "unmeasured"
where none did — never a number derived from the file sizes.

ImageRecipeAlternative

A different file for the same component — the quantizations the repo ships.

filerequired string
labelrequired string
presentrequired boolean This alternative is the file already on disk.
sizerequired string
size_bytesrequired integer (uint64)

ImageRecipeComponent

One file of a pipeline, under the files key it fills.

alternativesrequired array of ImageRecipeAlternative
dest_pathrequired string Path relative to the image models dir once downloaded — what the row's
files value is.
donerequired boolean A tracked download for it finished.
download_idrequired integer | null Tracked download row id, when there is one — join against
GET /api/hf/downloads for live progress.
downloadingrequired boolean A tracked download exists for it and has not finished.
filerequired string
gatedrequired boolean The hub refuses this repo without a token that accepted the licence.
noterequired string
presentrequired boolean The file is on disk under the image models dir.
reporequired string
rolerequired string The files key — diffusion_model / model / vae / clip_l /
clip_g / t5xxl / llm / llm_vision.
shared_withrequired array of string Display names of the other recipes that name this exact file. A
component is shared on purpose (the second recipe to want it finds it
on disk), but it also means one recipe's download shows up under every
neighbour — this is what lets a card say whose download it is watching.
sizerequired string
size_bytesrequired integer (uint64)

ImageRecipeRow

The prefilled row an "add from recipe" hands to the editor — the field
names POST /api/op/image_model_set (and lmgw__image_model_set) take.

actionrequired string
argsrequired object
editrequired boolean
filesrequired object
model_idrequired string
modesrequired array of string

ImageSettings

The image class settings: the same fields as the chat/aux class settings
and no engine ones. sd-server has no config file, so everything
per-process is a flag in some row's args.

extra_run_argsrequired array of string
imagerequired string
models_dirrequired string
public_prefixrequired string
request_timeout_secondsrequired integer (uint64) Per-request ceiling for the class, in seconds. 0 = the maximum possible — no deadline of
lmgw's own.

ImageSettingsPatch

The image class's patch. Shaped like RouterSettingsPatch — the four
fields are the same four — but kept separate rather than reusing it,
because the two types are not the same settings struct and a shared patch
would make image.backend a compile error away from existing.

extra_run_args array | null Default null.
image string | null Default null.
models_dir string | null Default null.
public_prefix string | null Default null.
request_timeout_seconds integer | null Default null.

ImageTestPassed

An image pipeline that drew its probe image.

bytesrequired integer (uint) The first image's size in bytes.
classrequired string Always image.
endpointrequired string
latency_msrequired integer (uint64)
loadedrequired boolean Always true.
model_idrequired string
nrequired integer (uint) How many images came back.
noterequired string
okrequired boolean Always true.
output_formatrequired any What the server said it encoded; null when it says nothing.
proberequired string Always image_generation.
public_namerequired string
seedrequired integer (int64)
sizerequired string The probe's size, e.g. 256x256.
stepsrequired integer (uint32)

ImageUpscalerEntry

One shipped upscaler.

descriptionrequired string
dest_pathrequired string Where it lands, relative to the image models dir: upscalers/<file>.
display_namerequired string
donerequired boolean
download_id integer (int64)
downloadingrequired boolean
filerequired string
gatedrequired boolean
keyrequired string What image_upscaler_add takes.
licencerequired string The licence the repo states.
presentrequired boolean
reporequired string
scalerequired integer (uint32) How many times larger a side gets per run.
sizerequired string
size_bytesrequired integer (uint64)

ImageUpscalerFile

One upscaler file on disk.

filerequired string
namerequired string The name sd-server and the tools call it by: the file stem.
size_bytesrequired integer (uint64)

ImageUpscalers

The upscaler side of the image recipes (chat-media-tools design §9):
sd-server's POST /sdcpp/v1/upscale runs an ESRGAN model it finds at
the top level of <image models_dir>/upscalers, one directory every
image row reads.

dirrequired string The directory, relative to the image models dir.
on_diskrequired array of ImageUpscalerFile The upscalers on disk, by the name image__upscale and the card's
Upscale take (the file stem), whichever way they got there.
shippedrequired array of ImageUpscalerEntry The models lmgw ships an entry for.

ImageUse

One user of an image.

classrequired string The lmgw class (chat | aux | audio | image).
containerrequired string | null Set for running_container and stopped_container: its name.
kindrequired ImageUseKind
model_idrequired string | null Which model row: set for model_override, and for a
running_container or stopped_container that is one of lmgw's model
containers (read from its labels, else matched by its name) — with
class, what the container op's apply recreates. None for a
container that is no model's (an agent's, or anything else on the
machine).

ImageUseKind

How something is using an image: what
container_image_delete refuses to delete out from under, and what
the promote success panel offers to recreate.

One of: string; string (A container that exists but is not running — exited, created, or a
buildah working container (podman ps -a --external). It keeps its
image from being removed all the same.)

ImportedCorpus

chunksrequired integer (int64)
corpus_idrequired string
documentsrequired integer (int64)
embed_aliasrequired string | null The name on *this* gateway that routes there, when one does.
embed_modelrequired string The embedding identity the corpus is pinned to.
replacedrequired boolean

InputPath

How a voice turn's words reached the chat model.

One of: string (The model heard the turn's audio.); string (The model read the speech-to-text transcript.)

ItemState

How an item came out.

One of: string; string (Worth knowing; never changes the verdict.); string (Not checked, because an item before it is not ok: the sentence says
which.)

JobRow

One background job. done/total are in the kind's own unit (bytes for
hf_download, documents for an ingest, …) and stage names what is
happening; total is absent when the total genuinely isn't known yet.

created_atrequired string
detailrequired any Kind-specific payload; the generic feed does not interpret it.
donerequired integer (uint64)
errorrequired string | null
finished_atrequired string | null
idrequired integer (int64)
keyrequired string | null Dedup key scoped to the kind (hf:<download row id>).
kindrequired string hf_download | ingest | re_embed | eval_run | golden_gen.
labelrequired string
percentrequired integer | null
stagerequired string
started_atrequired string | null
statusrequired string queued | running | done | failed | canceled.
totalrequired integer | null

JsonRpcError

errorrequired object
coderequired integer
messagerequired string
id any
jsonrpcrequired string One of 2.0.

JsonRpcRequest

id any Absent on a notification (e.g. notifications/initialized); string or number otherwise.
jsonrpcrequired string One of 2.0.
methodrequired string e.g. initialize, ping, tools/list, tools/call, resources/list, resources/templates/list, resources/read, notifications/initialized.
params object

JsonRpcResponse

idrequired any
jsonrpcrequired string One of 2.0.
resultrequired object

KbMode

How a thread's knowledge bases reach the model.

One of: string (Search before every turn and send the excerpts with the user's
message.); string (Give the model the knowledge search tools; it searches when it
decides to.)

KeptImage

A tag that was left in place, and why: one a keep_runs prune kept, or one a build_set
delete with delete_images did not remove (in use, a name from outside
the build, a dev instance).

reasonrequired string
tagrequired string

KeyCreated

POST /api/op/key_create for a client or an owner key: the new row, and
its key in the clear.

A device key answers DevicePaired instead. The wrapper
KeyCreateAnswer is the document's description of the one op; a reader
knows the kind it sent and reads that kind's type.

idrequired integer (int64) The new key's api_keys.id.
keyrequired string The key. Secret. A client key's is shown here and nowhere else (only
its hash is stored); an owner key's stays readable with key_reveal.
messagerequired string What was done, for a person to read.
namerequired string The key's name; an owner key's carries the owner: prefix the server
writes.
okrequired boolean Always true; a refusal is an error answer instead.

KeyMap

A files or args map as a patch carries it, the image class's map
counterpart of the list-valued run arguments.

Two spellings for one map, and both are load-bearing. /api/op and the
dashboard send a real JSON object, because that is what the row stores.
The MCP plane cannot: its schemas are flat scalars on purpose (a tool
whose arguments need hand-built JSON is a tool a small local model cannot
call reliably), which is the same reason capabilities_override accepts a
JSON *string* there. So a text block of key = value lines — the syntax
printed by sd-server --help — is accepted wherever the object is.

One of: object; string

KeyRow

One key on the Keys & policy table. GET /api/usage/keys

app_idrequired string | null Devices only: the app id its last enrolment declared
(dev.example.storyplayer), what other devices of the same app
offer files to; null without one, and on every other kind.
budget_microrequired integer (int64)
budget_periodrequired string
concurrency_limitrequired integer (int64)
device_toolsrequired array of string Client and device keys: the device-hosted labels whose tools the key
reaches (["kai"]), whatever its tool scope's mode, which then
filters those tools as any server's. A label no device hosts now is
kept and reaches nothing until one does: compare it with the device
rows' hosts_label. Empty for every other kind.
enabledrequired boolean
expires_atrequired string | null
hosts_labelrequired string | null Devices only: the label it may host MCP tools under; null without
a hosting grant.
idrequired integer (int64)
kindrequired string key | internal | agent | owner | device — an internal
identity is budgetable but can never authenticate anything; an owner
key holds every capability; a device is a paired client app.
last_seen_atrequired string | null Devices only: when one of its long-lived connections (the Chat
feed, a voice session, its tool link) last opened or closed,
RFC 3339 UTC.
last_usedrequired string | null
namerequired string
noterequired string
onlinerequired array of string Devices only: which of its connections are open now — feed,
voice, tools, in that order. Empty means offline.
open_linksrequired array of OpenLinks Devices only: how many connections of each kind in online are
open, in the same order. More than one of a kind is a client that
opened another before its last one closed.
pairingrequired DevicePairingView | null Devices only: its pairing over the device link (device link design
§3, §9.3) — its token, its enrolment and the code to confirm, a
contested token, its certificate's dates and its URLs. null for
every other kind.
reachesrequired array of string Devices with a hosting grant only: every principal that reaches the
hosted label's tools (client-apps design §5.6, L16 as changed
2026-10-15) — owner, the device itself, each key and device whose
device_tools grants the label, and each agent whose manifest names
it — as a sentence each ("owner", "device 'desktop' (hosts it)", "key
'ci'", "agent 'board'"). Empty without a grant.
requestsrequired integer (int64)
rpm_limitrequired integer (int64)
scope_moderequired string
scope_patternsrequired string
self_adminrequired AdminLevel Devices only: the device's level of lmgw's admin tools — off,
read_only (it reads lmgw's configuration and state) or full (it
also changes it, and may register programs that run on the gateway's
machine). Above off it sees and uses the Chat threads and folders
that carry the self-admin toolset (lmgw); at full it may also
attach the toolset and change such threads and folders. The
self-admin level in Settings caps what the tools may do. Admin Chat
stays hidden from every device. off for every other kind.
spent_microrequired integer (int64) Spend so far in the current budget period: what the budget counts.
That includes the budget floor of three kinds of unpriced request,
each a lower bound, so the figure can be above what the priced rows
add up to: one unpriced only for a hosted-tool fee priced nowhere
(the known part of its cost), an OpenAI answer at a tier above
Standard with no price for it (the standard price), and a stream cut
before the upstream reported usage (a local count of its text).
spent_unknown_requestsrequired integer (int64) What that figure does **not** cover — the same obligation every other
money total on this plane carries. Without it the per-key meter would be
the one number on the page that cannot state its own remainder. Every
unpriced request is counted here, those whose floor spent_micro
includes too: their whole cost is still unknown.
spent_unknown_tokensrequired integer (int64) The tokens of those unpriced requests, counted as
spent_unknown_requests counts them.
tool_scope_moderequired string all | allow | deny over exposed MCP tool names — which tools the
key sees on /mcp and may attach in a /v1/responses run. Only a
client key's is read: an agent's tools are its manifest's, and an owner
key is not scoped.
tool_scope_patternsrequired string
tpm_limitrequired integer (int64)

KnowledgeBase

A knowledge base as every route shows it.

chunk_overlaprequired integer (int64)
chunk_tokensrequired integer (int64)
countsrequired KnowledgeCounts
created_atrequired string
descriptionrequired string
embed_aliasrequired string The embedding model alias the base was created with.
embed_contextrequired integer | null The embedding model's context in tokens, when the gateway knows it.
embed_dimsrequired integer (int64) The vector length of the pinned model.
embed_identityrequired string upstream/model (Nd): the pin as one line.
embed_input_limitrequired integer | null What one embedding input may hold, min(context, ubatch) for a local
model; chunk_tokens (heading path included) is checked against it.
embed_input_limit_sourcerequired string One sentence: where embed_input_limit comes from.
embed_modelrequired string The embedding model the base is pinned to.
embed_resolvablerequired boolean Whether a model on this gateway still resolves to the pin. When not,
searches fall back to keywords and new files cannot be embedded.
embed_tokenizerrequired string What counts the tokens: model, tiktoken or tiktoken_guess.
embed_upstreamrequired string The upstream the alias resolved to when the base was pinned.
idrequired integer (int64)
jobrequired JobRow | null The live job on the base, or the last one that ran.
mcp_visiblerequired boolean Whether the kb__* tools on /mcp may search this base.
namerequired string Unique across the bases.
notesrequired array of string One sentence each: what a person should know about the base now.
rerank_aliasrequired string Empty: no rerank stage.
resident_bytesrequired integer (int64) What the base's vectors cost resident in memory: embedded chunks x
dimensions x 2.
statusrequired string ready or re_embed_required (the vectors no longer match the pinned
model; Resume fills them in). One of ready, re_embed_required.
updated_atrequired string
vectors_revrequired integer (int64) Moves on every chunk write.
vision_aliasrequired string Empty: text-less PDF pages are skipped and counted.

KnowledgeCounts

A base's file and chunk counts.

bytesrequired integer (int64) The files' size in bytes.
chunksrequired integer (int64)
embeddedrequired integer (int64) Chunks that have a vector; chunks - embedded are waiting for one.
failedrequired integer (int64)
filesrequired integer (int64)
ingestingrequired integer (int64)
pendingrequired integer (int64)
readyrequired integer (int64)

KnowledgeExcerpt

One retrieved excerpt.

chunk_idrequired string
filerequired string The file's name.
file_idrequired integer (int64)
file_sharequired string The sha256 of the file version the chunk was cut from.
heading_pathrequired string
kbrequired string The base's name.
kb_idrequired integer (int64)
pagerequired integer | null 1-based PDF page; null for other files.
rerank_skipped boolean Present (and true) when the rerank stage ran but did not score this
excerpt (its query + chunk pair was over the reranker's input limit):
score is its fused score and it ranks behind the reranked ones.
scorerequired number (float) The final order's score: the reranker's when it ran, the fused
(reciprocal-rank) score otherwise.
span_endrequired integer (int64)
span_startrequired integer (int64) Byte range in the file's extracted text.
textrequired string The chunk's text, verbatim.
tokensrequired integer (uint) Counted over heading path and text.

KnowledgeFile

One file of a base.

added_atrequired string
chunk_countrequired integer (int64)
errorrequired string | null Why the last ingest failed.
idrequired integer (int64)
ingested_atrequired string | null
kb_idrequired integer (int64)
kindrequired string What the bytes were sniffed as.
mimerequired string
namerequired string The name it was uploaded under (a label, never a path).
notesrequired array of string
pagesrequired integer | null Pages, slides or sheets, when the file has them.
sha256required string
sizerequired integer (int64)
skipped_pagesrequired integer (int64) Text-less PDF pages that were skipped (no vision model on the base).
statusrequired string pending, ingesting, ready or failed. One of pending, ingesting, ready, failed.
subrequired string

KnowledgeUploadRequest

multipart/form-data with one part per file.

file string (binary) One file; send as many parts as there are files. The part's field name does not matter, its file name names the file.

LabArtifactRole

Whether an artifact is a group's input or a run's output.

One of: string (Sent with the group's requests (an image a decision model reads),
shared by its cells.); string (What a run produced (a generated image, a speech clip).)

LabArtifactView

One artifact: media bytes kept as a file named by their sha256.

created_atrequired string
data_url_headrequired string | null An input that came as a data URL: its head as typed, everything
before the comma (data:image/x-receipt;name=a.png;base64). A request
sends it as <head>,<base64 of the bytes>; null for bytes that came
as bytes.
hrefrequired string Where the bytes are: /labs/api/artifacts/{id} from the API, the
file's path inside the zip in an export.
idrequired integer (int64)
mimerequired string The media type, sniffed from the bytes.
namerequired string The upload's name, or the one lmgw gave an output.
ordrequired integer (int64) Its place among the group's inputs or the run's outputs.
rolerequired LabArtifactRole
run_idrequired integer | null The run that produced it; null for a group's input.
sha256required string The sha256 of the bytes, which names the file.
sizerequired integer (uint64) The file's size in bytes.

LabBatchItem

What makes a group an item of a set run (labs-store design §3.1).

batch_idrequired integer (int64) The set run.
expectedrequired object The expected answers, per question id, as the store keeps a label:
the option's name (choice), the level's index (score), yes or
no (noul). Empty when the item is not labelled.
item_ixrequired integer (uint64) The item's place in the run's file, from 0.
keyrequired string | null The item's own key, from the mapping's key column; null without
one.

LabCell

One cell of a group's plan: the model it asks and the variant of the
form it sends. The cells run in plan order, one run each.

modelrequired string The public name asked.
variantrequired string The lab's name for what was sent: the Decision lab's as_written,
no_descriptions or reversed.

LabError

How this plane answers a failure: {"error": "..."}, plus the code of
a refusal that has one.

code string A machine-readable word, on the refusals that have one (for example
dev_shared_models_dir).
errorrequired string

LabExportFormat

The file format of an export.

One of: string (Lossless: one lmgw.lab.v1 line per group; a zip with the files when
the scope has artifacts.); string (The lab's flat table.); string (The Image and Audio labs' files under readable names: one group's
one file as it is, else a zip of the files and a manifest.jsonl
(LabFilesManifestLine). The Decision lab makes no files (a 400).)

LabFileKind

What a file of the export is.

One of: string (A run's output as the store keeps it: a picture, a speech file, a
task's audio.); string (A run's streamed or raw PCM speech, kept as it arrived and written as
a WAV with the PCM format the form held (the gateway's
x-lmgw-sample-rate wins over its rate).); string (A transcription's or a task's text answer, as UTF-8 text.)

LabFileRef

A file the store keeps, as a form names it: the artifact's id and the
name it came with. A re-opened form sends it back, so a re-ask uploads
nothing again.

idrequired integer (int64) The artifact (/labs/api/artifacts/{id}).
namerequired string The upload's file name.

LabFilesInput

One input of the group a file's run read: an upload to transcribe, an
edit's picture. Named here, not carried in the zip: it is the owner's own
file, and the JSONL export carries it.

artifact_idrequired integer (int64) The input artifact.
mimerequired string
namerequired string The upload's name.
sha256required string

LabFilesManifestLine

One line of a files zip's manifest: a file, and the run it came from.

answered_byrequired string Which model answered: a fallback's alias when one did.
artifact_idrequired integer | null The kept artifact the file is (or, for a WAV, was made from); null
for a transcript.
created_atrequired string When the run was answered.
endpointrequired string The /v1 route the run asked.
filerequired string The file's path inside the zip:
<group id>-<model>-<voice or task>-<first words>.<ext>.
formatrequired string Always lmgw.lab.files.v1.
group_idrequired integer (int64)
inputsrequired array of LabFilesInput The group's inputs the run read, which the zip does not carry.
kindrequired LabFileKind
labrequired LabKind
mimerequired string The file's media type.
missingrequired boolean The artifact's file was not in the data dir when the export was
written: the zip does not carry it, and MISSING.txt names it.
modelrequired string The model asked.
parametersrequired any The request as sent: its JSON, or for an upload the multipart
summary (LabMultipartSummary); a request that is no JSON as its
text.
run_idrequired integer | null The run; null for a run the store could not keep.
sha256required string | null That artifact's sha256, which names its file in the data dir.
sizerequired integer (uint64) The file's size in the zip, in bytes; for a missing file, the kept
artifact's.
taskrequired string The Audio lab's task (tts, asr, ...), the Image lab's
generate or edit.
textrequired string | null The text the run was given: what was spoken, the prompt; null
when it was given none.
voicerequired string | null The voice a speech run asked; null for anything else.

LabGroupView

What one click in a lab produced, or one item of a set run.

artifactsrequired array of LabArtifactView The group's inputs, in order.
created_atrequired string
formrequired any The lab's form as the lab held it (the Decision lab's
DecisionForm), with its media as the group's input artifacts.
idrequired integer (int64)
in_flightrequired boolean A cell of it is being answered now: its request is out and its run
not in yet. A group with no run that is not in flight was stopped.
Deleting a group in flight is the 409 in_flight.
itemrequired LabBatchItem | null The set run it is an item of; null for a group of the history.
labrequired LabKind
overriderequired string | null The request override, as typed (its image data URLs as
lab-artifact:<id>), when one was in effect.
planrequired array of LabCell The cells, in run order. A group with fewer runs than cells was
stopped.
runsrequired array of LabRunView The runs so far, in cell order.
titlerequired string Derived once from the form: the state's first line, a prompt.

LabKind

Which lab a group belongs to; the {lab} of /labs/api/{lab}/*.

string

LabPresetKind

What a preset holds.

One of: string (The Decision lab's questions, model and thresholds.); string (The Image lab's form: the model, the prompt and every setting.); string (The Audio lab's speech panel and the PCM format of a stream.)

LabPresetView

A kept preset.

created_atrequired string
idrequired integer (int64)
labrequired LabKind
namerequired string
updated_atrequired string

LabRunView

One dispatch to one /v1 route and what came back.

answered_byrequired string Which model answered: x-lmgw-fallback when a fallback did, else the
model asked.
artifactsrequired array of LabArtifactView What the run produced, in order.
cellrequired integer (uint32) Its index in the group's plan.
created_atrequired string
endpointrequired string The route dispatched to, /v1/systemone.
error_coderequired string | null A failure's code: the envelope's lmgw_code, else its code when
that is a string, else its type (llama.cpp's numeric code only
repeats the status), else the numeric code.
error_messagerequired string | null A failure's message.
fallback_reasonrequired string | null x-lmgw-fallback-reason: why a fallback answered (hold, ...).
group_idrequired integer (int64)
headersrequired object The x-lmgw-* headers the route stamped on its answer.
http_statusrequired integer (uint16) The route's HTTP status, whatever it was.
idrequired integer | null null for a run the store could not keep: the cell's answer is still
here, and store_error beside it says why.
input_tokensrequired integer | null The answer's input tokens, when it reported them.
latency_msrequired integer (uint64) How long the dispatch took in the gateway, answer read included.
model_askedrequired string
output_tokensrequired integer | null The answer's output tokens, when it reported them.
requestrequired string The request as sent, as text, except that each image data URL is
lab-artifact:<id>.
responserequired string | null The answer as received, as text; null when it was no text and is an
output artifact instead.
response_typerequired string | null The answer's Content-Type.
upstream_modelrequired string | null The answer's own model.
variantrequired string

LabVoice

One voice name of a model.

idrequired string The name to send as voice.
kindrequired LabVoiceKind Where the name comes from: a preset, a library clip, a shipped voice,
an embedding, or a name only the model's own server reported.
sendrequired string Where lmgw puts the name in the engine's request: voice, or
options.voice_id for a native voice of a family that reads that.
transcript boolean For a library clip: whether its transcript is recorded. Absent for
every other kind.

LabVoiceKind

Where a voice name comes from.

One of: string (A preset of the model's row.); string (A clip of the voice library (when the class's voice directory is it).); string (A voice the model's package ships.); string (A voice embedding file in the package's embeddings/ folder.); string (A name only the model's own server reported: a running container
(or a remote upstream) knows it, lmgw's catalog does not.)

LabVoicesSource

Where the list of GET /audio-lab/api/voices was read.

One of: string (lmgw's own catalog (the model's presets, its package's voices, the
voice library), plus the names a running container added.); string (A remote upstream, asked: it has no container and no catalog here.)

LadderTest

A ladder row's test: every rung loaded and probed in turn, then the
model stopped.

classrequired string Always chat.
ladderrequired boolean Always true.
model_idrequired string
okrequired boolean Every tested rung passed.
reset_to_baserequired boolean The model was stopped again so the next request starts at the base;
false when other traffic kept it busy.
rungsrequired array of RungTest The rungs tested, in order; a failure ends the list.
top_rungrequired integer (uint) How many rungs the ladder has.
was_running_rungrequired integer | null The rung the model was on before the test, when it was running.

LanguageNote

A speech model its language does not reach as set — the ASR the spoken
language, the TTS the reply language: a thread's voice_resolved.language_notes,
and Settings' chat_voice_language_notes for the Chat's own models.

aliasrequired string The stage's alias.
messagerequired string The whole sentence the page shows: the model, then what it does
("text-to-speech model 'audio/…' takes no language: …").
stagerequired string asr or tts.

LatencyPoint

bucketrequired string
p50_total_msrequired number | null
p50_ttfb_msrequired number | null
p95_total_msrequired number | null
p95_ttfb_msrequired number | null

LearnedResidency

A learned audio residency.

bytesrequired integer (uint64)
keyrequired string The configuration it was read under. A row whose configuration has
changed since keeps the figure but is not charged by it.
learned_atrequired string When it was read (YYYY-MM-DD HH:MM:SS, UTC).

LiveTurn

A turn answering a thread now, who started it, and whether it is a
bound realtime session's voice turn.

byrequired string
thread_idrequired integer (int64)
voicerequired boolean

LiveVoice

A realtime session bound to a thread now, and who bound it ("the
dashboard", "device 'phone'").

byrequired string
thread_idrequired integer (int64)

LlamaCppError

errorrequired object
coderequired integer The HTTP status, repeated in the body as llama.cpp does.
lmgw_coderequired string lmgw's own machine-readable error code, e.g. gpu_hold, gpu_benchmark, gpu_deferred, gpu_setup, engine_download.
messagerequired string
typerequired string One of invalid_request_error, authentication_error, permission_error, not_found_error, not_supported_error, unavailable_error, server_error.

LlamaParams

The full llama-server parameter surface of a local model row.
None/false = flag omitted from the rendered preset.

batch_sizerequired integer | null
cache_ramrequired integer | null
cache_type_krequired string | null
cache_type_vrequired string | null
chat_template_filerequired string | null
chat_template_kwargsrequired object
ctx_sizerequired integer | null
draft_gguf_pathrequired string | null
fitrequired string | null
fit_ctxrequired integer | null
flash_attnrequired string | null
jinjarequired boolean
kv_unifiedrequired boolean | null --kv-unified (true) / --no-kv-unified (false); None leaves
llama-server's default (unified exactly when parallel is unset).
kv_unified_per_slotrequired integer | null --kv-unified-per-slot: per-request context cap on a unified row.
min_prequired number | null
mmproj_pathrequired string | null
n_gpu_layersrequired integer | null
n_predictrequired integer | null --n-predict: the most tokens one response may generate. None =
llama-server's own default (-1, unbounded). This is the number
/v1/models reports as max_output_tokens.
no_mmprojrequired boolean
parallelrequired integer | null
presence_penaltyrequired number | null
reasoningrequired string | null
reasoning_budgetrequired integer | null
reasoning_effortrequired string | null
reasoning_formatrequired string | null
reasoning_preserverequired boolean | null
repeat_penaltyrequired number | null
seedrequired integer | null
spec_draft_n_maxrequired integer | null
spec_draft_n_minrequired integer | null
spec_draft_nglrequired string | null
spec_typerequired string | null
temprequired number | null
threadsrequired integer | null
top_krequired integer | null
top_prequired number | null
ubatch_sizerequired integer | null

LlamaProps

The facts a llama.cpp server reports about its loaded model, read once per start,
climb and adoption. Every field is optional,
and None is unknown — the server did not say — never false.

audiorequired boolean | null modalities.audio: the server loaded a projector that hears.
build_inforequired string | null b<number>-<commit> on official builds; ik_llama.cpp sends none.
capsrequired object | null chat_template_caps, the template's own booleans; empty on
ik_llama.cpp, which sends none of them.
n_ctx_slotrequired integer | null One slot's context in tokens (default_generation_settings.n_ctx).
videorequired boolean | null modalities.video — official builds only.
visionrequired boolean | null modalities.vision: the server loaded a projector that sees.

LoadResult

The load phase, measured by the integration around podman run.

msrequired integer (uint64) podman run → /health 200, container start included.
vram_bytesrequired integer | null vram_used_bytes minus the baseline.
vram_used_bytesrequired integer | null Device VRAM used once healthy.

LocalChain

One local (chat) model's full path from download to container.

aliasesrequired array of string Enabled explicit aliases routing here through a llama-server upstream.
enabledrequired boolean
file_existsrequired boolean The GGUF was found by the models-dir scan.
gguf_pathrequired string
hf_reporequired string <org>/<repo> when the GGUF is a tracked HF download, else empty.
hf_statusrequired string HF row status (done | queued | downloading | failed |
update_available
), empty when the file was not downloaded by lmgw.
idrequired integer (int64)
model_idrequired string
publicrequired boolean
public_namerequired string Client-facing name (prefix applied), meaningful only when public.

LocalModel

argsrequired array of string
capabilities_override any An alias's capabilities override for the derived /v1/models capability facts: a JSON
object with optional keys capabilities, max_output_tokens, notes. None = no
override.
enabledrequired boolean
extra_run_argsrequired array | null Per-model podman run args override; None inherits the chat
class settings' extra_run_args.
fallbackrequired string | null The model or alias that answers whenever this one cannot (the GPU
hold, VRAM outside lmgw, background traffic deferred, a disabled
row), as written. None = no fallback.
gguf_pathrequired string Relative to the models dir — never an in-container /models/… path.
idrequired integer (int64)
idle_secondsrequired integer (int64)
imagerequired string | null Per-model container image override;
None inherits the chat class settings' image.
ladderrequired array of Rung Ladder rungs above the base; empty = not a ladder. Absent in frames from before this
field existed.
model_idrequired string
paramsrequired LlamaParams
publicrequired boolean
warm_startrequired boolean Start this model's own container at app launch.

LocalModelDetail

GET /api/local-model?id=|model_id= — full stored record plus derived
health for the editor.

advisoriesrequired array of string Configuration that loads and serves but misbehaves under some input
(a large image, say). Apart from problems because the model starts.
capabilities_overriderequired any An alias's capabilities override for the derived /v1/models capability facts: a JSON
object with optional keys capabilities, max_output_tokens, notes. None = no
override.
command_linerequired string The exact podman run … command line this model renders to;
the published host port is a placeholder, since it is allocated per
start.
downloaded_fromrequired DownloadedFrom | null The download this file came from, when the downloader fetched it.
draft_presentrequired boolean | null
enabledrequired boolean
extra_argsrequired array of string One entry per llama-server argument (round-trips with the patch field).
extra_run_argsrequired array | null Per-model podman run args override, one entry per argument (round-trips
with the patch field); None inherits the chat class settings'
extra_run_args.
fallbackrequired string | null The one fallback (openai egress design §14.2); None = none.
fit_noterequired FitNote | null The note of a context fitted to the graphics card (find-a-model
design D26): Get it's or "Fit again"'s; None when the row's
context isn't a fit's shorter one.
gguf_pathrequired string
gguf_presentrequired boolean
idrequired integer (int64)
idle_secondsrequired integer (int64)
imagerequired string | null Per-model container image override;
None inherits the chat class settings' image.
ladderrequired array of Rung Ladder rungs above the base; empty = not a ladder. The editor's ladder table reads
it.
licencerequired ModelLicence | null The licence the GGUF header states; null when it states none.
mmproj_presentrequired boolean | null
model_idrequired string
paramsrequired LlamaParams
problemsrequired array of string Static findings; empty means "nothing obviously wrong", not "loads".
publicrequired boolean
rungsrequired array | null Every rung's own command line, per-slot context and switchover;
null on a row that is not a ladder.
sourcerequired string hf | manual.
warm_startrequired boolean Start this model's own container at app launch.

LocalModelView

A local chat model row plus its client-facing public name.

deferrals_24hrequired integer (uint64) How many requests for public_name were deferred (gpu_deferred) in
the last 24 hours: background requests (x-lmgw-background: on) the
model declined rather than disturb other work on the GPU.
licencerequired ModelLicence | null The licence the row's GGUF header states; null when it states none
or the file cannot be read.
modelrequired LocalModel
public_namerequired string

MachineAction

What an item offers to do (§1.4, WP12).

One of: object (Switch the model settings to the ones lmgw ships for this card:
machine_settings_fit with this fit and confirm set to these
changes, after a confirmation that lists them, left and
running. An ordinary settings write: no password.)

MachineCause

Why an item is not plainly ok (§1's tables).

One of: object (No NVIDIA or AMD card; others names the display devices there are.); object (An NVIDIA card bound to another driver (nouveau) or none.); object (The driver libraries on disk are newer than the kernel module that
runs: a restart finishes the update.); object (The driver is installed and its kernel module is not running.
secure_boot: Secure Boot keeps it from loading — it is on, a module
is built for the running kernel, and this boot started after it was
put there. Otherwise it may still be building, or a restart starts
it.); object (The kernel module runs and its libraries are missing.); object (The kernel module's version could not be read.); object (The versions agree, and NVML in a separate process failed.); object (An AMD card without a device node to compute on.); object (NVIDIA's container toolkit is not installed.); object (The toolkit comes from Fedora's retired package.); object (lmgw's description of the card could not be written, and the toolkit
that writes it is to blame (it failed, or what it wrote names paths
that are not there).); object (Writing lmgw's description of the card did not finish within the
load timeout: the card's driver stopped answering.); object (A folder lmgw keeps its description of the card in is not one only
this user may open.); object (lmgw's own files for the description could not be written or read.); object (lmgw writes no description of its own here; the system's is used
(D26).); object (NVIDIA's software source has not loaded since last_loaded while the
system's others did.); object (Another enabled repository offers the toolkit.); object (Podman is not installed.); object (Podman does not work; its own error.); object (This Podman has no --cdi-spec-dir.); object (The settings are NVIDIA's, and the card is AMD's.); object (The settings are AMD's, and the card is NVIDIA's.); object (These kinds of models run on the processor.); object (Models still running with the settings from before a switch of the
model settings (WP12): they use the new ones once they stop.); object (Settings name a CDI device of another kind, which only the system's
specs define.); object (Engine images not on the machine yet.)

MachineCheck

The whole check.

checked_atrequired string When it ran: UTC, YYYY-MM-DD HH:MM:SS.
failed_startrequired MachineFailedStart | null The last start of a local model on the graphics card that failed
because of this computer (the check named why), whoever asked for it:
a client, the Chat, a lab, the model's Test. None before one since
lmgw started. A surface that was told "Not now" asks again once this
is another failed start than the one it was told it beside
(machine-check design D171, D182).
headlinerequired string The verdict in one plain sentence.
itemsrequired array of MachineItem The items, in the order they are checked: graphics card and driver,
using the card for models, running models, model settings, room, the
download.
planrequired MachinePlan | null What can be done about it, when anything is to be done or offered.
verdictrequired MachineVerdict

MachineFailedStart

A local model's start on the graphics card that failed because of this
computer: gpu_setup's start (machine-check design §2.5, D182).

atrequired string When it failed: UTC, YYYY-MM-DD HH:MM:SS.
classrequired string Its class: chat, aux, audio or image.
countrequired integer (uint64) How many such starts failed since lmgw started, this one included:
two in the same second are still two.
modelrequired string The model's id.

MachineItem

One checked thing.

actionrequired MachineAction | null What the person can do about it from here, without a password; only
the model settings item has one yet (§1.4).
causerequired MachineCause | null The typed reason, when the item is not plainly ok.
detailrequired array of string What was read and where from, with the technical names: the fold.
idrequired MachineItemId
sentencerequired string What a newcomer reads.
staterequired ItemState

MachineItemId

Which item (§1.1 … §1.6).

One of: string (§1.1: the graphics card and its driver.); string (§1.2: what lets models use the card (NVIDIA's container toolkit and
lmgw's own description of the card).); string (§1.3: the program that runs models.); string (§1.4: whether the model settings fit the card.); string (§1.5: free disk space.); string (§1.6: the download of what the card needs.)

MachinePlan

What can be done, and how.

hashrequired string SHA-256 over the steps as root runs them (lmgw-machine's
HashedPlan), never over this answer: its sentences and sizes do not
change it.
howrequired PlanHow
stepsrequired array of PlanStep

MachineSummary

The verdict alone, in GET /api/status and the machine frame of
/api/events.

checked_atrequired string
failed_startrequired MachineFailedStart | null MachineCheck::failed_start.
headlinerequired string
verdictrequired MachineVerdict

MachineVerdict

The headline verdict (§1.7).

One of: string (Local models can run.); string (Something is missing that lmgw can set up with a button here.); string (Something is missing that is added by following instructions here.); string (A restart finishes a driver update or start.); string (The NVIDIA card needs NVIDIA's driver.); string (No graphics card: cloud models only.)

ManifestCorpus

chunk_countrequired integer (int64)
corpus_idrequired string
crawl_daterequired string
embed_dimsrequired integer (int64)
embed_modelrequired string
embed_upstreamrequired string
eval_regressionrequired boolean
eval_scorerequired number | null
ingest_modelrequired string
ingest_prompt_versionrequired string
libraryrequired string
source_kindrequired string
statusrequired string
versionrequired string

McpServerDetail

descriptionrequired string A toolset's purpose; "" for a server.
kindrequired string builtin: lmgw's own toolsets (lmgw, for owner credentials only; docs; kb); server: a registered MCP server; agent: a service agent's tools. One of builtin, server, agent.
namerequired string A server's configured name; a toolset's label.
objectrequired string One of mcp.server.
server_labelrequired string What goes into a {"type": "mcp", "server_label"} tool on /v1/realtime or /v1/responses: a built-in toolset's label, a registered server's tool prefix, else its name.
toolsrequired array of object
descriptionrequired string "" when the server gave none.
input_schemarequired object
namerequired string The server's own name for the tool: its exposed name minus the <prefix>__ namespace.

McpServerList

datarequired array of object
descriptionrequired string A toolset's purpose; "" for a server.
kindrequired string builtin: lmgw's own toolsets (lmgw, for owner credentials only; docs; kb); server: a registered MCP server; agent: a service agent's tools. One of builtin, server, agent.
namerequired string A server's configured name; a toolset's label.
objectrequired string One of mcp.server.
server_labelrequired string What goes into a {"type": "mcp", "server_label"} tool on /v1/realtime or /v1/responses: a built-in toolset's label, a registered server's tool prefix, else its name.
objectrequired string One of list.

McpServerView

agent_idrequired string | null Set for an agent's own registration (container-runtime §3.3), so the
MCP page can say who owns a row it must not offer to edit; null for
every row an owner made.
allow_samplingrequired boolean
argsrequired string
autostartrequired boolean
commandrequired string | null
container_imagerequired string | null
cwdrequired string | null
devicerequired string | null A device row's device, by its short name (desktop); null for
every other row.
device_key_idrequired integer | null A device row's key id (api_keys.id); null for every other row.
enabledrequired boolean
envrequired string KEY=value lines, as stored — a server's credentials usually live here.
extra_run_argsrequired array of string
headersrequired string Name: value lines, as stored — an HTTP server's bearer lives here.
idrequired integer (int64)
idle_secondsrequired integer (int64)
namerequired string
open_tasksrequired integer (int64) The MCP tasks this server runs for Chat threads now, at list time
(MCP Tasks design §6): started by a call of one of its required
tools and not ended yet. No cap (T9); a server with open tasks is
never reaped for idleness (T17).
sampling_aliasrequired string | null
statusrequired string ready | connecting | error | stopped at list time; live updates come
from the SSE mcp frame.
status_detailrequired string | null
timeout_msrequired integer (uint64)
tool_countrequired integer (int64)
tool_prefixrequired string
transportrequired string stdio | http | sse | device. A device row is a paired device's
hosted tools (client-apps design §5.2): created by its hosting grant,
connected while the device's host link is open.
urlrequired string | null

McpSettingsPatch

The sparse patch the dashboard's settings save takes under mcp.

host_max_frame_mb integer | null In MiB; 0 = bounded by host_max_message_mb. Not 0 together with
it. Default null.
host_max_message_mb integer | null In MiB; 0 = no bound of its own. Not 0 together with
host_max_frame_mb. Default null.
host_ping_interval_s integer | null Seconds between the link's pings; 0 = none. Default null.
task_poll_interval_s integer | null Seconds between two tasks/get of a task whose server suggests no
pollInterval; at least 1. Default null.

McpStatus

One registered MCP server's connection state: status is connecting |
ready | stopped | error, tool_count the tools it offers, and
detail says why on an error, or that a stopped server was idle-reaped
and reconnects on next use.

detailrequired string | null
idrequired integer (int64)
namerequired string
statusrequired string
tool_countrequired integer (int64)

McpToolView

descriptionrequired string | null
namerequired string The exposed (prefixed) name a model sees and a thread stores.
upstream_namerequired string The server's own name for it, shown when a prefix hides it.

Measured

Where a threshold was measured: a set run, and what the cut gave there.

accuracyrequired number (double) Of those, the share of the labelled ones answered correctly. A cut
with no labelled item at or above it is not written (409
no_labels).
batch_idrequired integer (int64) The set run it was measured on.
coveragerequired number (double) The share of the run's answered items at or above the threshold.
labelledrequired integer (uint64) How many labelled items the accuracy is over: at least 1.

MediaAction

What an image card's action does (design §8.3).

One of: string (The same prompt and settings, a new seed.); string (A variation (img2img) of the picture, on a row without edit.); string (An instruction edit of the picture, on a row with edit.); string (An ESRGAN upscale of the picture.)

MediaChoice

One model a media tool can use, as a picker lists it.

labelrequired string What a person reads: the name, and what it is (its family, on this
machine, a cloud model via its upstream).
localrequired boolean One of lmgw's own rows rather than an alias.
namerequired string The name the tool's model takes and a default stores.

MediaChoices

What each media tool can use, for the default pickers: the same rows
and aliases its model enum lists for the caller.

editrequired array of MediaChoice
generaterequired array of MediaChoice
speakrequired array of MediaChoice
transcriberequired array of MediaChoice
voicesrequired object The voices of each speech row, by its name; a cloud alias has none
listed (its voices are the provider's own).

MediaDefaults

One level's default models, by tool (module doc).

Input is strict (deny_unknown_fields): a write that names a field this
build does not know is refused with the fields it does, rather than
stored as nothing. A stored level is read through
MediaDefaults::from_stored, which drops such a key on its own.

edit string | null image__edit's model.
generate string | null image__generate's model, as its model enum names it
(image/<id> or an alias).
speak string | null audio__speak's model.
transcribe string | null audio__transcribe's model.
voice string | null The voice audio__speak uses with the default speech model when a
call names none.

MediaFacts

The facts of a produced file, under meta.media of its attachment
(design §9). Every field is optional: what a call did not have is left
out, never guessed.

answered_by string | null The model or alias that answered instead of model: its fallback,
for whatever reason it could not answer.
cfg number | null
duration_ms integer | null
height integer | null
job_ms integer | null The job's own time, completed − started (sd-server's job API).
language string | null
model string | null The model the call named (image/z-image-turbo).
negative_prompt string | null
not_applied array of string What the answering route could not take and so did not apply
(seed, steps, ...): a cloud fallback gets no smuggled parameters.
parent integer | null The attachment this one was made from (a card action's source).
prompt string | null
scale number | null
seed integer | null
steps integer | null
strength number | null A variation's strength.
tool string | null The tool that made it: image__generate, audio__speak, ...
upscaler string | null
voice string | null
wall_ms integer | null The call's whole time, loading included.
width integer | null

MediaPhase

What a running image or audio call is doing (ToolProgressFrame::phase).

One of: string; string (The call's model's engine image is being downloaded before the model
can be loaded (machine-check design §5): image, done_bytes, and
total_bytes where the size is known.); string (Another model is being stopped to make room: model names it.); string (The call's own model is being brought onto the GPU.); string (Nothing more can be stopped yet: the call waits for memory
(needs_bytes, free_bytes).); string (The image server holds the job in its queue (queue_position).); string (The picture is being drawn (pass, step, total_steps, preview
where the image server reports them).)

MediaUnavailable

A stored default that does not resolve now, and why: the model was
switched off or deleted, an alias lost the route, the caller's key may
not use it, a voice its model does not have.

fieldrequired string generate, edit, speak, voice or transcribe.
namerequired string The stored name.
reasonrequired string

MergeOutcome

One outcome an extra can have when assembled.

One of: string; string (Its head was already an ancestor of HEAD, or the merge's diff
against its first parent was empty.); string (Skipped on the forge's word (merged_at set).); string (No shared history with the assembled HEAD: applied as a squash of
its changes since its fork point instead of a merge.); string (Only in a check-merge step or a failed run — assemble stops here.)

Message

One stored message of a thread.

answered_byrequired string | null The alias that actually answered, when it was not model (a
fallback); null when model itself answered.
attachmentsrequired array of AttachmentMeta The files sent with this message.
completion_tokensrequired integer | null
contentrequired string
contextrequired MessageContext | null The retrieval that ran for this user message; null when none ran.
created_atrequired string When the message was written (UTC, YYYY-MM-DD HH:MM:SS).
idrequired integer (int64)
images_note string For a reply that a fallback without sight answered: who, for which
model, and what went to it in the images' place. Absent otherwise.
ir_messagesrequired string | null An agentic turn's tool calls and results as JSON text; null for a
plain chat turn.
kb_refsrequired array of integer (int64) Knowledge bases picked with # for this user message only.
modelrequired string | null A reply's model: the alias its turn asked for. null on user
messages and on replies saved before it was recorded.
originrequired string | null A user message's origin: the sentence its client sent with it about
where the user wrote it (origin of the send or the edit), which
the model reads before the message's text. null when its client
sent none, and on every other role.
pending_approvals array of ApprovalRequest The calls a gated turn's reply still waits on
(POST /chat/api/threads/{id}/approvals decides them). Absent when
none wait.
prompt_tokensrequired integer | null
reasoningrequired string A reasoning model's thinking trace; empty otherwise.
rolerequired string user, assistant, or tool (a late MCP task result).
task MessageTask On a late MCP task result (role tool): the task's facts. Absent
otherwise.
thread_idrequired integer (int64)
voicerequired MessageVoice | null How the turn was spoken; null for a typed turn.

MessageAck

A write that reports what it did in a sentence: {"ok": true, "message": …}.

messagerequired string What was done, for a person to read.
okrequired boolean Always true; a failure is an error answer instead.

MessageContext

The retrieval that ran for one user message. Excerpt n in the
<context> block (and [n] in the answer) is excerpts[n - 1].

budget_tokensrequired integer (uint64) The budget the retrieval ran with.
droppedrequired integer (uint64) Excerpts that ranked but did not fit the budget.
excerptsrequired array of ContextExcerpt
kb_idsrequired array of integer (int64) The bases asked for: the thread's and the message's, as they were
then.
msrequired number (double) How long the retrieval took.
notesrequired array of string Why something was not searched, or not fully: one sentence each.
queryrequired string What was searched for.
searchedrequired array of string The bases that were searched, by name.
tokensrequired integer (uint64) Tokens the excerpts use, heading paths included.

MessageTask

What a result row says of its task: task on a message of role tool.

ended_byrequired string | null Who cancelled it, for a cancel lmgw sent ("the dashboard", "device
'phone'"); null otherwise.
server_labelrequired string The label the tool was offered under when it was called.
statusrequired string How it ended: completed, failed, cancelled, or abandoned
(the server no longer knows it, or its server row was removed). One of completed, failed, cancelled, abandoned.
structured_content any The result's MCP structuredContent, for a view of the call
(client-apps design §7.5): the model reads the result's content,
and this only when the content was empty. Absent when the result
had none, and for a result stored by an earlier lmgw.
task_idrequired string The server's id of the task.
toolrequired string The name the model called (<label>__<tool>).

MessageVoice

How a turn was spoken, on its message: null on the message for a typed
turn. On a user message: how it was dictated or spoken in realtime mode,
the speech-to-text alias that was asked and the one that answered, and
the audio's length. On a spoken reply: the text-to-speech alias, the
voice, the part that was never heard and the turn's timing.

asr string
asr_answered_by string
asr_ms integer (uint64)
audio_ms integer (uint64)
input InputPath On a user message: audio when the chat model heard the turn;
absent on the transcript path.
timing VoiceTiming
transcript_error string On a user message the model heard: why its transcription failed.
tts string
tts_answered_by string
unheard string The reply's text after the heard part, shown behind a "not heard"
marker. Not in content, so the model never sees it.
viarequired string dictation or realtime.
voice string

MetricDelta

One headline metric of a comparison.

band_pctrequired number (double) max(threshold, noise): the band a delta has to leave.
delta_pctrequired number | null (new − old) / old, in percent.
labelrequired string
lower_is_betterrequired boolean
metricrequired string Stable key: prefill_tok_s, ttft_ms, decode_tok_s,
decode_deep_tok_s, aggregate_tok_s, decode_tokens_per_joule,
load_ms, load_vram_bytes, stall_ms.
newrequired number | null
noise_pctrequired number (double) The larger relative spread of the two points, in percent.
noterequired string | null E.g. the two runs measured different prompt lengths (the verdict is
then not_same_point).
oldrequired number | null The previous run's value (median), and this run's.
unitrequired string
verdictrequired Verdict

MixedPlan

The mixed phase's shape.

inject_tokensrequired integer (uint64) *P_inj* = min(8192, *P_max*).
stream_predictrequired integer (uint64) Their n_predict: as much as the slot holds, so none runs out before
the injected prompt's first token.
stream_prompt_tokensrequired integer (uint64) Their prompt length.
streamsrequired integer (uint32) *N_slots* − 1 decoding streams.

MixedResult

The mixed phase: what an arriving long prompt costs streams that
are already decoding.

before_tok_srequired Stat Per repetition: the median over the streams of each one's rate in the
steady window before the injection.
during_tok_srequired Stat Per repetition: the median over the streams of each one's rate from
the injection to the injected request's first token.
inject_tokensrequired integer (uint64) *P_inj*.
inject_ttft_msrequired Stat The injected request's TTFT.
notesrequired array of string Anything that makes a repetition's numbers partial (a stream that
ended before the injected first token, …).
solo_ttft_msrequired number | null The prefill phase's median TTFT at the same prompt length, when it
measured that length.
stall_msrequired Stat Per repetition: the longest inter-token gap of any stream across that
window — the stall.
streamsrequired integer (uint32) Decoding streams (*N_slots* − 1).

ModelById

The OpenAiModel shape unless the caller sent anthropic-version, in which case AnthropicModel. No lmgw block on the single-model route.

One of: OpenAiModel; AnthropicModel

ModelCapabilities

The capabilities object of one model on GET /v1/models.

task, endpoints and source are always present — they are what makes
the entry actionable at all ("this id exists, here is where to send it,
here is how much to trust the rest"). Everything else is absent unless a
source stated it.

context_editing ContextEditingCaps | null Anthropic's context management (context_management on
/v1/messages: context editing and threshold compaction, and the
top-level on-demand compaction), under a name of its
own because the Anthropic-shaped model entry puts Anthropic's
context_management block beside lmgw's object. Present only on an
Anthropic-protocol route, the one route that sends a request's
context_management on as written; every other route leaves it out
and names it in x-lmgw-params-ignored.
endpointsrequired array of string The lmgw routes that accept this model id.
input_modalities array | null Subset of text, image, audio, video, file, pdf,
embedding. pdf is a catalog's word (Anthropic's pdf_input,
Kilo's and OpenRouter's modality).
Absent = unknown, never "none".
languages array of string ISO 639-1 codes (a few three-letter ones, yue) of the languages a
local audio model works in, whatever its task: speech, recognition,
alignment. A request's language takes them (lmgw sends each in the
model's own spelling). Absent when the model's package names none
as codes; see multilingual for a family that says only that it
covers many.
multilingual boolean | null The model's family says it is multilingual without listing codes
("multilingual", "80+ languages"): it works in more languages than
languages names, which then holds few or none. Absent otherwise;
absent along with languages means unknown, never "one language".
output_modalities array | null The same vocabulary, plus decisions: what a decision model answers
with (llama.cpp's and OpenRouter's word). A client that checks
llama.cpp's architecture.output_modalities for decisions reads
this list instead. Absent = unknown.
reasoning ReasoningCaps | null
sourcerequired string Where the facts came from: gguf+config, catalog, config, or
owner (an alias's capabilities override).
speech SpeechCaps | null A text-to-speech model's expressive controls — what instructions,
inline tags, language and stream_format do on it
(the speech capabilities object). A local audio model's is derived; a
cloud alias has one only through an alias's capabilities override.
structured_output StructuredOutputCaps | null
taskrequired string chat | embedding | rerank | decision (a decision model,
answering on /v1/systemone) | tts | asr | an audio.cpp task
name | an image task | realtime (an OpenAI Realtime model, no lmgw
route). Determines endpoints.
tool_calls ToolCallCaps | null
vision boolean | null input_modalities contains image. Redundant with the list on
purpose: a client can read this one boolean to decide whether to
send images, e.g. whether a session gets a screenshot tool. Absent
exactly when input_modalities is absent.

ModelCard

The card (§5, §9.2): one model and one file of it, marked by size until
the page reads the header (D123).

byrequired string The author's display name on the hub (D19), else its id.
by_userrequired string | null The account's id when the author is a person, whose display name is
self-chosen: shown beside by. None for an organisation.
canrequired array of string "reads pictures", … (D22): what the listings tell.
companionsrequired array of HfCompanion The projector D121 picks, and the first drafter.
disk_free_bytesrequired integer | null Free bytes where the files land (D125).
downloadrequired DownloadEstimate The file's bytes and its companions', with the time (D23).
downloadsrequired integer (uint64)
filerequired string The file (a split file's first part); empty when none was read.
fitrequired FileFit The file's fit by size (D123): beside what runs now when that pick
exists, else on the whole card (D120); fit.measure says which.
gatedrequired boolean
kindrequired CardKind
licencerequired ModelLicence | null The licence the hub's tags name, linked to the original's page
(D22). Shown, never a filter.
likesrequired integer (uint64) The original's likes and downloads on the hub, as its listing says
them (a later page's card is listed among the other models).
more_uploadsrequired boolean The hub has more uploads than its first page listed.
namerequired string The original's repo name with hyphens as spaces ("Qwen3.6 27B").
named_filerequired string | null The file a pasted address named, when file is that file (WP7,
D100): the header's marks keep it as the card's file while it fits,
and only then pass to their own pick.
originrequired string The original, owner/name.
origin_privaterequired boolean The original is private to the account: a share text from a public
upload of it names the model by the upload (WP7, D109).
other_uploadsrequired array of UploadChoice The original's other uploads, plain ones first: the window the
arguments asked for (D142).
other_uploads_morerequired integer (uint32)
other_uploads_totalrequired integer (uint32) How many other uploads the hub's first page listed, and how many come
after other_uploads.
parametersrequired integer | null The hub listing's parameter total; the header's count replaces it
once read (hf_repo with fit).
partsrequired integer (uint32)
privaterequired boolean The upload or the original is private to the account (D124).
quantrequired string | null
sharerequired ShareLink | null None for a private repo (D124) and for a card without a file.
uploadrequired string The upload the file is from; empty when the walk passed the model
over without reading its uploads (NothingFits).
whole_cardrequired CardFile | null The whole card's pick, when it differs from file (D120).
whyrequired string "Why this file" (§3.2): the upload, the rule, the width by size.

ModelCheck

One model's pre-flight result; class says which kind of model it is and
so which fields it has.

One of: object (A chat-class model.); object (An embedding, rerank or decision model.); object (An image-generation model.)

ModelChoice

One model in a list: "Other models with this name", "Did you mean".

authorrequired string The author's id on the hub (a card's "by" is the display name).
downloadsrequired integer (uint64)
gatedrequired boolean
likesrequired integer (uint64)
matched_wordsrequired integer (uint32) How many of the query's words its name matched (D13).
namerequired string The repo's name with hyphens as spaces.
noterequired string | null "not available as a file lmgw can run yet", when the walk found so.
originrequired string The repo, owner/name.
parametersrequired integer | null The listing's parameter total.
pipelinerequired string | null The hub's pipeline name.
privaterequired boolean

ModelDone

One model, start, stop, restart or apply.

applied boolean apply only: whether the configuration was applied.
classrequired string
held boolean apply only: the GPU hold kept the container from starting again.
messagerequired string
model_idrequired string
okrequired boolean False when the model was still serving requests and was left
running, or could not be stopped under the hold.
port integer (uint16) The port, when the action left the container up.
running boolean apply only: whether the container is running afterwards.

ModelGetDone

A model_get job's result: the row it set up.

createdrequired boolean false when a row already served this file and the get answered
that one (§6.2 step 4).
ctx_sizerequired integer | null The context the row was created with.
fitrequired FileFit | null The fit the context comes from, by the get's measure; None when a
row already served the file.
get_idrequired integer (int64)
model_idrequired string
next_steprequired string
noterequired FitNote | null The note the row keeps when its context is a fit's shorter one
(D26).
public_namerequired string
row_idrequired integer (int64) The row's id in its class's table.
targetrequired string
warningsrequired array of string The plan's and the create's warnings, each a sentence.

ModelGetStage

Where a get is (§6.2), as its job's progress detail says it.

One of: string (The files are downloading.); string (No file is transferring and one or more wait: paused on a metered
connection, or cut and not started again. waiting says which and
why.); string (The files are here: planning, fitting and creating the row.); string (The row is there.)

ModelGetState

How a get stands.

One of: string (Waiting for its files, or setting up the row (stage says which).); string (The row is there (row_id, result).); string (It stopped; error says why and what to do.); string (Cancelled, its own downloads with it.)

ModelIdentity

The model the run measured, filled in by the benchmark runner.

gguf_mtimerequired string | null
gguf_pathrequired string
gguf_sizerequired integer (uint64)
model_idrequired string
quantrequired string | null From the GGUF header's file type.
rungrequired integer (uint32) A ladder row's rung, 0 = base.

ModelLicence

The licence a GGUF header states (general.license, with the optional
general.license.name and general.license.link). Information only: it
is never a filter, a ranking or a warning. At least one field is set.

idrequired string | null general.license: an SPDX-like id or a name, such as apache-2.0
or other.
linkrequired string | null general.license.link.
namerequired string | null general.license.name.

ModelList

OpenAiModelList unless the caller sent anthropic-version, in which case AnthropicModelList.

One of: object; object

ModelLogs

One model, logs.

classrequired string
containerrequired string The container's name.
logsrequired string The container's recent output.
model_idrequired string
okrequired boolean
tailrequired integer (uint) How many lines were asked for.

ModelStatus

One model, status.

classrequired string
enabledrequired boolean | null Null when no model with this id is configured.
enginerequired string The engine the class runs: llama-server, audio.cpp or sd-server.
idle_secondsrequired integer | null
imagerequired string | null The container image in effect.
model_idrequired string
okrequired boolean
runtimerequired RuntimeStatus | null The running container, or null when nothing has started this model.
warm_startrequired boolean | null

ModelTestFailed

A chat, aux or image model that did not load or did not answer.

classrequired string chat, aux or image. One of chat, aux, image.
code string The gateway's error code, when the model's start or the probe failed
with one of lmgw's own errors (gpu_setup when the model could not
start on the graphics card because of the computer,
vram_queue_timeout, …), as the /v1 routes answer it; absent when
the model answered with an error of its own, or with nothing usable.
container_logrequired array of string The lines of the model's container log that look like the reason.
endpoint string For an image model: the route the probe went to.
errorrequired string What went wrong.
hintrequired string What to try.
latency_msrequired integer (uint64)
loadedrequired boolean Always false.
model_idrequired string
okrequired boolean Always false.
proberequired string What was sent: generate, embed, rerank or image_generation.
public_name string For an image model: the name clients call it by.

ModelTestPassed

An aux model that loaded and answered its probe; the first part of a
chat model's pass.

answer DecideAnswer For decide: the model's answer to the probe's choice question, as
it gave it. The test does not judge the choice, only that the route
answered with one of the options and probabilities that sum to 1
(decision-models design §3.7).
classrequired string aux for an aux model's pass, chat where this is the first part of
a chat model's. One of chat, aux.
dimensions integer (uint) For embed: the embedding's length.
input_tokens integer (uint64) For decide: the input tokens the server reported for the question.
latency_msrequired integer (uint64) How long the load and the probe took, in milliseconds.
loadedrequired boolean Always true.
model_idrequired string
okrequired boolean Always true.
proberequired string What was sent: generate (one token), embed, rerank or decide
(one System One choice question on /v1/systemone).
scored integer (uint) For rerank: how many documents came back scored.

NewSource

fence array of string Domains a fetch may touch. Empty derives the fence from the root's own
host, which is the safe default rather than "anywhere". Default [].
kindrequired string llms_txt | markdown | rustdoc_json | html.
rootrequired string

NoulAnswer

noulrequired number (double) P(yes), from 0 (no) to 1 (yes).

NoulCriteria

false string | null What a no means.
true string | null What a yes means.

NoulQuestion

criteria NoulCriteria | null What a yes and a no mean, when the question alone does not say.
instructionsrequired any The yes/no question: a string, an object or an array.

ObjectCounts

aliasesrequired integer (uint64)
api_keysrequired integer (uint64)
local_modelsrequired integer (uint64)
mcp_serversrequired integer (uint64)
upstreamsrequired integer (uint64)

OngoingInput

ongoing in a folder create or patch: an object marks the folder as one
ongoing conversation (its defaults must name a model), null ends that.

idle_minutesrequired integer (int64) Minutes without a message after which a new thread starts; 0: only
when a client asks. A whole number of zero or more.

OpenAiError

errorrequired object
coderequired string lmgw's own machine-readable error code (e.g. gpu_hold, gpu_benchmark, gpu_deferred, gpu_setup — a 503: the local model could not start on the graphics card, and the message says what on the computer lmgw runs on is not ready (fixed there, not by retrying), engine_download — a 502: the engine the local model runs in could not be downloaded, response_format_unsupported — the model or its upstream cannot produce the asked structured output type, invalid_json_schema — the upstream rejected the schema, its message kept, budget_unpriced — a budgeted caller's request on a cloud model with no price on file for what it is billed in, flex without a flex price among them), not the HTTP status.
messagerequired string
param string | null The request field the error is about: response_format (chat completions, completions) or text.format (/v1/responses) for the codes response_format_unsupported and invalid_json_schema; null for every other error.
typerequired string e.g. invalid_request_error, authentication_error, not_found_error, rate_limit_error, api_error.

OpenAiModel

capabilities ModelCapabilities
context_length integer
createdrequired integer Stable for the life of the gateway process rather than the time of each request; the catalog's own timestamp when it has one.
idrequired string
max_output_tokens integer
notes array of string
objectrequired string One of model.
owned_byrequired string
pricing object
completionrequired string
promptrequired string USD per prompt token, as a decimal string; "0" for a local model.

OptionDraft

One option of a choice question.

descriptionrequired string What the option means; blank sends null.
namerequired string

OptionDraftInput

One option of a choice question.

description string What the option means; blank sends null. Default "".
name string Default "".

OptionProbability

One option of a DecideAnswer and its probability.

optionrequired string
probabilityrequired number (double)

OrphanGguf

gguf_pathrequired string
role_guessrequired string weights | mmproj | drafter | imatrix, guessed from the filename.
Only weights can be wired up as a model; the rest are companions a
model's editor attaches (or leftovers). Empty from an older gateway.
suggested_idrequired string Model id the create flow proposes for it.

PairingTokenView

A device's latest pairing token: when it lapses, and what became of it.

aliverequired boolean Whether it is alive now: not lapsed, not ended. A used token stays
alive until then, for its own key's repeat.
created_atrequired string When it was minted and when it lapses, RFC 3339 UTC.
ended_atrequired string | null When the owner ended it (closing the QR card, a new token).
expires_atrequired string
used_atrequired string | null When it was used, and from which address.
used_fromrequired string | null

Params

Alias-level request overrides.

frequency_penalty number | null
max_tokens integer (uint32)
min_p number | null llama.cpp min_p; the llama.cpp and OpenAI-compatible egresses send it.
presence_penalty number | null
reasoning ReasoningControl
repeat_penalty number | null llama.cpp repeat_penalty; the llama.cpp and OpenAI-compatible egresses send it.
seed integer (int64)
stop array of string
temperature number | null
top_k integer (uint32)
top_p number | null

PassthroughUpstream

hiddenrequired array of string Bare (unprefixed) model ids hidden from /v1/models and the client
catalog for this upstream — still reachable directly by name, just
not advertised. POST /api/op/model_visibility toggles membership.
idrequired integer (int64)
prefixrequired string
upstreamrequired string

PcmFormat

The PCM a streamed answer carries, as the page assembles it into a WAV:
the stream itself states none of it. The strings the inputs hold.

bitsrequired string
channelsrequired string
raterequired string

PcmFormatInput

The PCM a streamed answer carries, as the page assembles it into a WAV:
the stream itself states none of it. The strings the inputs hold.

bits string Default "16".
channels string Default "1".
rate string Default "24000".

Phase

One phase of a run, in suite order.

One of: string; string (podman run to a healthy server (the integration's, not the engine's).)

PhaseError

A phase that ended with an error. The points measured before it are kept.

errorrequired string
phaserequired Phase

PhaseSpan

A phase's band on the timeline.

end_msrequired integer | null None while the phase is still running.
phaserequired Phase
start_msrequired integer (uint64)

PickRule

Which of the pick's rules chose the file (design §3.2, D7).

One of: string (The largest file that fits the whole trained context.); string (No file fits the whole context: the largest that fits at least
32 768 tokens, or the trained context when that is smaller.); string (No file of 4 to 8.5 bits per weight fits at least that much.)

PlanChange

One field a plan would change on a configured row.

currentrequired any The row's value now; null when unset.
fieldrequired string
plannedrequiredany
whyrequired string | null The plan's reason for the planned value; null when it gives none.

PlanFile

A file a step writes.

contentrequired string
key_fingerprintrequired string | null For an OpenPGP public key: its fingerprint, computed from content,
in groups of four hex digits as people compare it
(C95B 321B … F796 ECB0). Display only.
moderequired integer (uint32) The mode root gives it (0o644, shown as 0644); in the hash.
pathrequired string
replacesrequired boolean lmgw's own older file replaced, rather than a new file created.

PlanFit

A plan's fit on the card by both measures (design §9.1): what
local_model_plan answers beside a chat or aux plan, from the disk or
the hub. An image plan has none yet.

besiderequired FileFit
cardrequired CardMeasure | null The card both fits were measured against; None without one (D9).
whole_cardrequired FileFit

PlanFrom

Where a plan's input came from (design §2.3, §9.1).

One of: string (The files on disk in the class's models directory.); string (The file's header read from Hugging Face before any download.)

PlanHow

Where the plan is carried out.

One of: object (The button in the app's window: one confirmation, one password.); object (Commands to type in a terminal; why says why there is no button.
With no steps, why says what is in the way and what to do instead.)

PlanSource

A plan's input, as the plan's answer names it.

commitrequired string | null The commit main resolved to when the header was read.
filerequired string | null The file's path in the repo, for a plan from the hub.
fromrequired PlanFrom
header_bytes_readrequired integer (uint64) The header bytes this plan fetched from the hub, every file's (the
weights' parts and the companions'); a header the process had read
already (cached by its hash) adds nothing (D123).
oidrequired string | null The weights' content hash the hub named (lfs.oid).
reporequired string | null The Hugging Face repo, for a plan from the hub.

PlanStep

One step.

commandsrequired array of array of string The exact argv of each program it runs as root, in order.
download_bytesrequired integer | null The download, when the user's package metadata can tell.
kindrequired PlanStepKind
package_scriptsrequired string | null What the package the step installs then changes by itself, through
its own install scripts, beyond the step's commands (machine-check
design §4.5). For the fold: display only, never in the hash.
sentencerequired string The confirmation's bullet.
terminalrequired array of string The same step as lines to type in a terminal, with sudo.
writes_filerequired PlanFile | null The file it writes, in full.

PlanStepKind

Which step.

string

PlanUnset

One setting a plan would clear on a configured chat row.

currentrequiredany
fieldrequired string
whyrequired string

PlannedProbe

A probe the plan would run, or why it would not.

proberequired ProbeKind
skiprequired string | null None: it runs. Judged on the row's capabilities; the live server's
chat_template_caps may still skip tool_call at run time.

PlayoutSource

Where a call's playout allowance comes from (calls design §5.3).

One of: string (The client's latest playout report (lmgw.output_audio.playout): the
measured playout delay less half the round trip.); string (One frame plus twice the client's interarrival jitter: before the
first report, on an unbound call, and after reports stopped.); string (One frame: no receiver report yet.)

PointPlan

The points a run measures, derived from the live server's per-slot
context and slot count — or, in bench_plan, provisionally from the row's
own numbers.

concurrentrequired array of integer (uint32) Stream counts *N*, ascending; the last one is *N_slots*.
decoderequired array of integer (uint64) Context depths *D*, ascending; the last one is *D_max* = *S* − *G* − 1.
generate_tokensrequired integer (uint32) *G*.
mixedrequired MixedPlan | null None when the server has a single slot, or its context cannot hold
a decoding stream.
n_slotsrequired integer (uint32) *N_slots*.
needle_tokensrequired integer | null The needle probe's prompt length, *P_max* − 512; None when the
context is too small to hold one.
notesrequired array of string Why a phase has fewer points than usual, or none at all.
per_slot_ctxrequired integer (uint64) *S*.
prefillrequired array of integer (uint64) Prompt lengths *P*, ascending; the last one is *P_max* = *S* − 2.
provisionalrequired boolean True when derived from the row's configuration rather than read from a
running server (bench_plan).
repetitionsrequired integer (uint32)

PrefillPoint

One prefill point: n_predict: 1, cache_prompt: false.

energyrequired Energy | null Over the TTFT windows; tokens are the evaluated prompt tokens.
energy_unmeasuredrequired string | null Why energy is None although the card reports power: a window
shorter than the GPU sampler resolves (two of its ticks, 200 ms at
the 100 ms tick), whose figure would have been the
ticks' average power times its length rather than a measurement.
None otherwise.
evaluated_tokensrequired Stat timings.prompt_n: what the server actually evaluated. Equal to *P*
when the KV cache stayed out of it.
prompt_msrequired Stat Server-side timings.prompt_ms.
prompt_tok_srequired Stat Server-side timings.prompt_per_second.
prompt_tokensrequired integer (uint64) *P*.
ttft_msrequired Stat Client-side: request sent → first streamed token.

PreviewMode

How sd-server draws a running job's preview (design §5.2).

string

PreviewTokens

The token counts of a preview, through the universal counter.

aliasrequired string
answered_byrequired string | null The alias that counted, when it was not alias (a fallback).
approxrequired array of string How the counts are approximate, as x-lmgw-count-approximate says
it; empty when they are exact.
staticrequired integer (uint64)
text_turnrequired integer (uint64)
voice_turnrequired integer (uint64)

PriceRowView

One price sheet. GET /api/usage/prices

idrequired integer (int64)
noterequired string | null
pricerequired number | null The rate of a unit other than tokens, per that unit's scale (per
minute of input audio, per 1M input characters, per generated image,
per answered request). None on a per_mtok row, whose rates are the
four above; those four are None on every other row.
price_cache_readrequired number | null
price_cache_writerequired number | null
price_inrequired number | null
price_outrequired number | null
scope_keyrequired string
scope_kindrequired string
service_tierrequired string The OpenAI service tier the row prices (PriceTier):
standard, flex, fast, ultrafast or scale. standard on
every other provider's row and every catalog row; a request is priced
with the rows of the tier its answer reported, and a tier with no row
leaves it unpriced.
sourcerequired string
unitrequired string
updated_atrequired string

ProbeChange

One probe's outcome in both runs.

newrequired ProbeOutcome | null
oldrequired ProbeOutcome | null
proberequired ProbeKind
verdictrequired Verdict A pass that became a fail or an error is a regression; the reverse an
improvement.

ProbeEvidence

One response a probe judged.

bodyrequired string | null The raw body when it is not a chat completion: an error status's body,
/apply-template's rendered prompt.
contentrequired string | null choices[0].message.content.
finish_reasonrequired string | null
msrequired integer | null
reasoningrequired string | null choices[0].message.reasoning_content.
statusrequired integer | null The HTTP status; None when the request never got one.
tool_callsrequired any choices[0].message.tool_calls, verbatim.

ProbeKind

The behaviour probes.

One of: string; string (Always last: it is the one probe with a full-context prefill.)

ProbeOutcome

How a probe ended.

One of: string; string (An observation, not a verdict (reasoning_history).); string (Not applicable to this model; detail says why.); string (The server answered with an error status, or not at all.)

ProbeReport

The probe results stored with a run.

probesrequired array of ProbeResult

ProbeResult

One probe's result.

detailrequired string One line: what passed or failed, the skip reason, or the error.
evidencerequired array of ProbeEvidence The responses judged — one, or four for deterministic (the cached
pair, then the no-cache pair).
outcomerequired ProbeOutcome
proberequired ProbeKind

Profile

A profile as GET /chat/api/profiles lists it.

builtinrequired string | null The built-in profile this row is (concise); null for one of the
owner's own. Read only.
created_atrequired string
examplesrequired array of Example Static example exchanges, in order.
follows_builtinrequired array of string The fields a built-in row takes from the built-in text, so they
follow its improvements. Read only.
idrequired integer (int64)
length_rulerequired string How long replies are; empty for none.
namerequired string Unique in any case; never default.
personarequired string Who the model is and how it sounds; empty for none. When set, it
takes the thread's system prompt's place.
reasoningrequired Reasoning | null Reasoning on or off; null inherits.
updated_atrequired string
used_byrequired UsedBy
voicerequired ProfileVoice
voice_blockrequired string | null The voice turn's block: null for the generic one, "" for none, a
text to use as it is.

ProfileChoice

chat_profile as a settings patch writes it (design §3.3): a profile
id, as a number or as a numeric text, or "" for none.

One of: integer (int64); string

ProfileDraft

A profile's content fields, with nothing saved: what Preview, Test and
Speak take, and what a create fills in.

examples array of Example Default [].
length_rule string Default "".
persona string Default "".
reasoning Reasoning | null Default null.
voice ProfileVoiceInput Default {"speech_style":null,"tts_alias":null,"voice":null}.
voice_block string | null Default null.

ProfileVoice

The speech part of a profile: the subset of a thread's voice settings a
profile carries, with the same checks and meanings. Each null inherits.

speech_stylerequired string | null The speaking style the text-to-speech model is given; an empty text
is none.
tts_aliasrequired string | null The text-to-speech alias (task tts or vdes).
voicerequired string | null A voice of that text-to-speech model, or of the Chat's own when
tts_alias is null.

ProfileVoiceInput

The speech part of a profile: the subset of a thread's voice settings a
profile carries, with the same checks and meanings. Each null inherits.

speech_style string | null The speaking style the text-to-speech model is given; an empty text
is none. Default null.
tts_alias string | null The text-to-speech alias (task tts or vdes). Default null.
voice string | null A voice of that text-to-speech model, or of the Chat's own when
tts_alias is null. Default null.

PromptStyle

How an image model wants its prompt written (design §3.4).

One of: string (Plain sentences: FLUX, Z-Image, Qwen-Image, SD 3.5 and the like.); string (Short comma-separated phrases: SDXL base.); string (Booru-style tags: the anime fine-tunes.)

QuestionDraft

One question as the form holds it.

idrequired string The key the answer comes back under.
instructionsrequired string
kindrequired DecisionQuestionKind

QuestionDraftInput

One question as the form holds it.

id string The key the answer comes back under. Default "".
instructions string Default "".
kind DecisionQuestionKindInput Default {"options":[],"type":"choice"}.

QuestionMetrics

One question's metrics.

accuracyrequired number | null The share of scored answered correctly: the winner (choice),
P(yes) ≥ 0.5 (noul), the nearest level (score) equal to the
label; null when nothing is scored.
answeredrequired integer (uint64) Items whose run answered this question.
classesrequired array of string The classes in matrix order, spelled as labels are kept: the options'
names, the levels' indices from "0", or yes and no.
confusionrequired array of array of integer (uint64) Rows the labels, columns the predictions, both in classes order.
curverequired array of CurvePoint One point per distinct confidence (choice, score) or certainty,
max(p, 1 − p) (noul), lowest first.
failedrequired integer (uint64) Items whose run is no 2xx.
idrequired string
itemsrequired integer (uint64) Items in the run.
labelledrequired integer (uint64) Items with an expected answer for this question.
maerequired number | null score only: the mean absolute distance, in levels, between the
expected level (the fractional score) and the label.
reliabilityrequired array of ReliabilityBin The non-empty ones of bins equal-width bins over the predicted
probability, lowest first: the winner's (choice), the nearest
level's (score), P(yes) (noul). Labelled answers only.
scoredrequired integer (uint64) Items both answered and labelled: what accuracy is over.
typerequired string choice, score or noul.
unreadablerequired integer (uint64) Items whose run is a 2xx without a readable answer to this question
(none of its type, a winner the question does not offer, the nearest
level's probability missing).

QuestionSet

A saved list of questions.

default_modelrequired string The model loading the set picks; blank picks none.
questionsrequired array of QuestionDraft In the order asked.
thresholdsrequired object Per question id; a question with none has 0, not measured.

QuestionSetInput

A saved list of questions.

default_model string The model loading the set picks; blank picks none. Default "".
questions array of QuestionDraftInput In the order asked. Default [].
thresholds object Per question id; a question with none has 0, not measured. Default {}.

QuestionTokens

One question's tokens.

idrequired string
option_spanrequired integer | null A choice question's options alone; null for the other types.
tokensrequired integer (uint64) Its instructions and its options, levels or criteria.

QueuedDownload

dest_pathrequired string
filerequired string
idrequired integer (int64)
statusrequired string

RateLimit

The forge API's remaining quota. Without a token GitHub allows 60 requests
an hour; when the limit is hit, the extras picker shows the reset time
instead of an empty list.

remainingrequired integer (uint32)
reset_atrequired string

RateSource

Where a download time's rate came from (D23).

One of: string (This machine's finished Hugging Face downloads, weighted by bytes.); string (The header reads made for this answer, from the same CDN.); string (Nothing measured yet: no time is given.)

RealtimeAvailability

Whether voice mode may bind the thread.

admin_toolsrequired boolean The thread carries lmgw's admin tools while the self-admin level is
full: its tools can change lmgw. Shown, never a refusal.
coderequired string | null The refusal's code, the one the bind answers with
(chat_thread_admin); null when ok.
okrequired boolean
reasonrequired string | null The refusal in words; null when ok.

RealtimeBudgetStage

One stage of the cascade and what it is expected to hold on the GPU.

aliasrequired string | null The alias the stage runs on; None for turn detection and for a
stage nothing is configured for.
bytesrequired integer | null The expected footprint; None = unknown, and the total is then a
lower bound.
labelrequired string The stage in words.
modelrequired string | null The local model, as <class>/<model id>.
noterequired string Where the figure comes from, or why there is none.
placementrequired string local (a model lmgw runs on this GPU) | cloud | external (a
server lmgw does not manage) | cpu | shared (the same local model
as an earlier stage, counted once) | unset | unresolved.
runningrequired boolean Its container is up now.
stagerequired string turn | chat | asr | check | tts.

RealtimeSettings

The realtime settings, with default_instructions spelled
out the way the Chat's default system prompt is: the text in force, the
built-in text beside it, and whether the setting is unset.

asr_aliasrequired string The speech-to-text alias turns are transcribed with; empty =
the Chat's transcription model.
backchannel_wordsrequired array of string
barge_in_checkrequired string words | duration.
barge_in_check_aliasrequired string Empty = the session's own ASR alias.
barge_in_check_scriptsrequired array of string Unicode script names; empty = every script.
barge_in_check_timeout_msrequired integer (uint32) 0 = no bound.
barge_in_guard_msrequired integer (uint32)
barge_in_min_msrequired integer (uint32)
default_instructionsrequired string The instructions a session with audio output uses while the client
gives none: the configured text, "" for none, or the built-in text
while the setting is unset.
default_instructions_builtinrequired string The built-in voice-assistant prompt — what saving
default_instructions as this text returns to.
default_instructions_is_builtinrequired boolean The setting is unset, so it follows the built-in text across
releases.
default_modelrequired string The chat alias a session starts on; empty = none.
default_voicerequired string The voice a session speaks with when it names none or an OpenAI
built-in voice; empty = the TTS row's default preset.
echo_tail_msrequired integer (uint32) The barge-in margin's tail on top of the round trip, in ms: the round
trip from pings on a WebSocket, from RTCP receiver reports on a
WebRTC call.
half_duplexrequired boolean
longest_pause_msrequired integer (uint32) 0 = keep the engine's silences.
max_frame_mbrequired integer (uint32) In MiB; 0 = bounded by the message limit (not both). WebSocket
only: a WebRTC call's single message is bounded by its stack, 256 KiB.
max_message_mbrequired integer (uint32) In MiB; 0 = no bound (not both). The largest WebSocket message; on
a WebRTC call also the largest event lmgw sends in one message and
what may wait for the call's session.
model_maprequired object Client model names mapped to lmgw aliases.
output_lead_msrequired integer (uint32) How far a WebSocket session's audio runs ahead of real time, in ms;
not used on a WebRTC call, whose frame clock sends in real time.
ping_interval_srequired integer (uint32) 0 = no pings and no liveness bound at all. On a WebRTC call also how
long it may stay silent, take to connect and open its events channel,
or wait on a held thread, how long a closing call waits for its last
event's delivery, and when playout reports count as stopped.
post_interrupt_silence_msrequired integer (uint32)
prefix_padding_msrequired integer (uint32)
semantic_floor_window_msrequired integer (uint32)
semantic_vadrequired SemanticVadTable
semantic_vad_enginerequired string smart_turn | server_vad (the escape hatch).
silence_duration_msrequired integer (uint32)
speech_instructionsrequired string The speech instructions a session's TTS gets while the client sends
none: a speaking style, or a voice-design row's description;
empty = none.
synthesis_ahead_srequired integer (uint32) 0 = no bound.
tag_hintrequired boolean An audio response's prompt says what square brackets do for the TTS:
the sounds it can make, or the delivery cues it takes.
thresholdrequired number (double) server_vad.threshold, 0.0..=1.0.
tts_aliasrequired string The text-to-speech alias a session speaks with; empty = none.
Its task is tts or vdes.
voice_maprequired object Client voice names mapped to voices of the TTS model.
warm_on_connectrequired boolean
webrtc_commit_window_msrequired integer (uint32) How far past its stamp a push-to-talk commit on a WebRTC call takes
frames, and how long it waits for them, in ms. Applies to the next
call.
webrtc_enabledrequired boolean The UDP listener for WebRTC calls, beside the HTTP listener and
beside the device listener (its sockets follow that one's addresses
and port); applies at the next start.
webrtc_output_kbpsrequired integer (uint32) A WebRTC call's Opus output bitrate in kbps, capped by the phone's
maxaveragebitrate. Applies to the next call.
webrtc_portrequired integer | null The UDP port WebRTC calls use beside the HTTP listener: null =
the HTTP port's number, 0 = chosen by the OS. Calls over a paired
device's listener use that listener's port instead. Applies at the
next start.
webrtc_reorder_msrequired integer (uint32) How long a WebRTC call's frame waits for a missing earlier one, in
ms; 0 = no wait. Applies to the next call.

RealtimeSettingsPatch

Sparse patch over RealtimeSettings: a field left out keeps its value.
The two maps and the two lists are replaced whole, like a class's
extra_run_args.

asr_alias string | null The speech-to-text alias turns are transcribed with; "" = the
Chat's transcription model. Must be an alias whose task is asr. Default null.
backchannel_words array | null Replaces the whole list. Default null.
barge_in_check string | null words | duration. Default null.
barge_in_check_alias string | null The ASR alias the word check transcribes with; "" = the session's
own ASR alias. Must be an alias whose task is asr. Default null.
barge_in_check_scripts array | null Unicode script names (Latin, Cyrillic, Han, …); [] = every script.
Replaces the whole list. Default null.
barge_in_check_timeout_ms integer | null 0 = no bound. Default null.
barge_in_guard_ms integer | null Default null.
barge_in_min_ms integer | null Default null.
default_instructions string | null The instructions a session with audio output uses while the client
gives none. The built-in text returns to the built-in default (and
follows it from then on); "" = none. Default null.
default_model string | null The chat alias a session starts on when the client names none, or
names an OpenAI Realtime model; "" = none. Must be a chat alias. Default null.
default_voice string | null The voice a session speaks with when it names none, or names an
OpenAI built-in voice; "" = the TTS row's default preset. Default null.
echo_tail_ms integer | null Default null.
half_duplex boolean | null Default null.
longest_pause_ms integer | null The longest silence in synthesized speech, in ms; 0 = keep the
engine's silences. Default null.
max_frame_mb integer | null In MiB; 0 = bounded by max_message_mb. Not 0 together with it. Default null.
max_message_mb integer | null In MiB; 0 = no bound. Not 0 together with max_frame_mb. The
largest WebSocket message a client sends; on a WebRTC call also the
largest event lmgw sends in one message and what may wait for the
call's session before the call ends. Default null.
model_map object | null Client model names mapped to lmgw aliases — session.model to a chat
alias, a transcription model to an ASR alias. Replaces the whole map. Default null.
output_lead_ms integer | null Default null.
ping_interval_s integer | null 0 = no pings, and no liveness bound at all. Default null.
post_interrupt_silence_ms integer | null Default null.
prefix_padding_ms integer | null Default null.
semantic_floor_window_ms integer | null Default null.
semantic_vad SemanticVadTablePatch | null The Smart Turn rows by eagerness; a row or field left out keeps its
value.
semantic_vad_engine string | null smart_turn | server_vad. Default null.
silence_duration_ms integer | null Default null.
speech_instructions string | null The speech instructions a session's TTS gets while the client sends
none: a speaking style, or a voice-design row's description. "" =
none. Default null.
synthesis_ahead_s integer | null 0 = no bound. Default null.
tag_hint boolean | null Whether an audio response's prompt names the sounds the TTS can make. Default null.
threshold number | null server_vad.threshold: the speech probability that counts as voice,
0.0..=1.0. Default null.
tts_alias string | null The text-to-speech alias a session speaks with; "" = none. Must be
an alias whose task is tts, or vdes (a voice designed from the
speech instructions). Default null.
voice_map object | null Client voice names mapped to voices of the TTS model. Replaces the
whole map. Default null.
warm_on_connect boolean | null Default null.
webrtc_commit_window_ms integer | null How far past its own stamp a push-to-talk commit on a WebRTC call
takes frames, and how long it waits for them, in ms. Applies to the
next call. Default null.
webrtc_enabled boolean | null The UDP listener for WebRTC calls (POST /v1/realtime/calls),
beside the HTTP listener and beside the device listener, whose
addresses and port its sockets follow; off, a call on either is
refused 503. Applies at the next start. Default null.
webrtc_output_kbps integer | null A WebRTC call's Opus output bitrate in kbps, 6 to 510, capped by the
phone's maxaveragebitrate. Applies to the next call. Default null.
webrtc_port integer | null The UDP port WebRTC calls use beside the HTTP listener: null = the
HTTP port's number, 0 = chosen by the OS, else 1 to 65535. Calls
over a paired device's listener use that listener's port instead.
Applies at the next start. Default null.
webrtc_reorder_ms integer | null How long a WebRTC call's frame waits for a missing earlier one, in
ms; 0 = no wait, the gap concealed at once. At most 40 950 (what
str0m can hold behind a gap). Applies to the next call. Default null.

Reasoning

A profile's reasoning switch; null where it is used inherits (the
thread's own fields win over it, the route's default comes after it).

string

ReasoningCaps

Reasoning / thinking support and how a request controls it.

budget_tokens integer | null The configured default thinking-token budget, when set and non-zero
(a zero budget is published as enabled: false, not as a budget).
can_disable boolean | null Whether a request can switch thinking off entirely. On an Anthropic
route: the catalog's thinking.types.disabled.supported.
control array of string The exact header and body fields that work on this route; omitted when
empty (nothing to control on a fixed model).
default string | null The effort in force when the request sets none.
enabled boolean | null The default state as this alias is configured. Absent when no source
states it — "the catalog says the model supports reasoning" does not
say whether it is on.
kindrequired string fixed (nothing to change per request), toggle (on/off per
request), levels (effort selectable per request).
levels array of string Accepted effort values, least → most in the canonical order. Only for
kind == "levels"; omitted entirely when empty.
preserve_history boolean | null Whether replayed reasoning of earlier turns reaches the model again.
thinking_types array of string The Messages thinking types the model takes, as an Anthropic
upstream's catalog publishes them (capabilities.thinking.types), in
Anthropic's order: adaptive, between_tools, disabled, enabled
(the budget form). Only on an Anthropic route; omitted when the
catalog names none of them as supported.

ReasoningControl

Per-request reasoning control: on/off, effort level, thinking-token budget.

budget_tokens integer (int64)
effort string
enabled boolean

RefEntry

One branch or tag as git ls-remote reports it.

namerequired string
sharequired string

RegistryUpdate

A registry image's update state: the digest the registry serves for
the tag now, against the digests podman recorded when the image was
pulled. Checked anonymously (the registry's bearer-token flow), by the same
schedule and **Check now** as the builds.

A multi-arch tag is an index: the registry answers with the index digest,
and podman's RepoDigests for such a pull normally carries it too. When it
carries only the platform manifest's digest instead, the index is read and
its members compared, so that case is not mistaken for an update.

checked_atrequired string When the registry was asked (RFC 3339).
errorrequired string | null Why the comparison could not be made: the registry did not answer, it
wants credentials, it rate-limited the check, or podman recorded no
digest to compare with (an image built or loaded here, not pulled).
local_digestsrequired array of string The sha256:… digests podman recorded for this repository on the
local image, right now.
referencerequired string The fully qualified reference that was checked
(ghcr.io/0xshug0/audio.cpp:full-cuda12) — what **Pull update**
(container_image_pull) pulls.
remote_digestrequired string | null sha256:… the registry serves for the tag; None when it could not
be asked (see error).
update_availablerequired boolean The registry serves something the local image is not.

ReliabilityBin

One reliability bin that holds an answer: the labelled answers whose
predicted probability falls in [lower, upper) (the last bin includes
1). lower is index / bins and upper (index + 1) / bins, the very
values an answer is placed by. A bin the list skips holds none.

countrequired integer (uint64) At least 1.
indexrequired integer (uint32) Its place among bins, from 0.
lowerrequired number (double)
mean_predictionrequired number (double) The mean predicted probability.
observedrequired number (double) The observed rate of what was predicted: the share whose winner
(choice) or nearest level (score) is the label; for noul, the
share labelled yes (the bins sort by P(yes)).
upperrequired number (double)

RepoFile

estimated_fromrequired string | null The file whose header this file's fit was estimated from (§3.3):
never smaller than the real use, so its "fits" is true, but its width
isn't known and it is never the recommended file. None when the
file's own header was read, or it is marked by its size alone.
filerequired string
fitrequired PlanFit | null With fit, for a weights file of the chat or aux class: its fit on
the graphics card by both measures (find-a-model design §3.3), what
local_model_plan with repo + file answers as its fit, less
what the list says once (D63): card is None where it is the
list's card, and the notes leave out the list's fit_notes.
None without fit and for the other roles.
partsrequired integer (uint32) >1 = split GGUF; selecting it downloads all parts.
quantrequired string | null
rolerequired string Filename heuristic, in the vocabulary of the target that was listed:
weights | mmproj | drafter | other for chat/aux/audio, and
diffusion | checkpoint | vae | text_encoder | lora | upscaler | other
for image. A string, not an enum, on
both sides of the wire — the image roles are guesses the editor lets
the user override, and a new one must not break an old client.
sizerequired string Human-formatted size, server-rendered.
size_bytesrequired integer (uint64)

RepoFit

What GET /api/hf/repo's fit asks for (find-a-model design §3.3, D68).

One of: string (No marks, and no header read.); string (Marks from the files' headers, read on a metered connection too: the
caller asked for them (D59).); string (Marks from the headers unless the connection is metered; then every
mark is by size and metered says why (D123): what the dashboard
asks by itself.)

RepoPicks

The file a repo's list recommends by each measure (find-a-model design
§3.2, D120).

besiderequired FilePick
whole_cardrequired FilePick

RepoPreset

One entry of the build editor's repository picker: a preset source repository for a
build.

default_refrequired string The default branch — what a new build's ref starts as.
enginerequired Engine
forgerequired Forge
idrequired string
namerequired string
repo_urlrequired string

RequestRow

One request's summary — the request SSE frame and the
row shape of GET /api/logs (log rows additionally carry mcp_tool and
pricing).

audio_in_msrequired integer | null What the request processed besides tokens, each only when it was
measured or the provider reported it: input audio in milliseconds,
input characters as sent, generated images. None = not measured,
which is not the same as zero — render a dash.
cache_write_tokensrequired integer | null
cached_in_tokensrequired integer | null The cache subsets of prompt_tokens, when the provider reported them —
without these a row that cost 8x its neighbour looks identical to it.
None = the provider said nothing, which is not the same as zero.
chars_inrequired integer | null
classrequired string chat | aux | audio | tool.
client_keyrequired string | null Name of the gateway API key that made the call (never the key itself);
absent when auth is disabled or the call was made in-process.
completion_tokensrequired integer | null
cost_microrequired integer | null Currency micro-units. None = **unpriced**, which is not the same as
free — render a dash, never a 0.
degradedrequired string | null What the request's content lost on its way to a model that lacks a
capability: "fallback 'x' lacks vision: 3 images sent as
placeholders", "'m' lacks audio: transcript sent", several joined by
"; ". None = nothing was degraded.
egress_protorequired string | null
error_kindrequired string | null
error_msgrequired string | null
fallback_reasonrequired string | null Why a fallback answered instead of the requested local model: hold
(the GPU hold), external_vram (VRAM outside lmgw's control was
short), background (a background candidate alias), unavailable
(a candidate alias with no model it may use), benchmark, quota,
unreachable, disabled, gpu_setup (the graphics card is not
ready on this computer) or engine_download (a local model's engine
could not be downloaded). None = no fallback; the fallback itself
is upstream_name / upstream_model.
images_outrequired integer | null
ingress_protorequired string
key_idrequired integer | null api_keys.id behind client_key — the id is what a key filter matches
on, and a name match breaks the moment a key is renamed.
log_idrequired integer (int64)
max_tokens_clampedrequired integer | null max_tokens lmgw lowered a client-set value to, on a ladder rung or a
guarded unified-KV pool. None = not clamped — either the row is unguarded, or the
client's value already fit.
mcp_toolrequired string | null MCP tool name for ingress_proto = "mcp" rows; absent on SSE frames.
price_noterequired string | null Why the row's cost is what it is, when that is not plain: "served at
service tier flex; no flex price on file for 'm', a standard one is",
"stream ended before the upstream reported usage". None otherwise.
pricingrequired RowPricing | null How the row was priced: the rates it recorded when it was written,
so each priced part can be shown as quantity × rate even after the
price has changed. On GET /api/logs rows only; absent on SSE
frames, which carry the cost and the quantities alone.
prompt_tokensrequired integer | null **Total** input for the call, cache included.
requested_aliasrequired string
rungrequired integer | null The rung a ladder row answered from — or, for a refusal, the rung it
was judged on — 1-based. None for a row without
a ladder, and for a request its fallback answered.
service_tierrequired string | null The service_tier an OpenAI platform answer reported, verbatim
(default, flex, priority, …): the tier the row is priced at.
None on every other upstream, and when the answer named none.
statusrequired integer (uint16)
streamedrequired boolean
total_msrequired integer | null
tsrequired string
ttfb_msrequired integer | null
upstream_modelrequired string | null
upstream_namerequired string | null

RequestStats

activerequired integer (int64)
completion_tokensrequired integer (uint64)
errorsrequired integer (uint64)
errors_last_minuterequired integer (uint64)
last_minuterequired integer (uint64)
prompt_tokensrequired integer (uint64)
totalrequired integer (uint64)

RerankRequest

documents array of string Jina's spelling.
modelrequired string
queryrequired string
texts array of string TEI's spelling — either works; an embedding-only row is refused.
top_n integer

RerankResponse

Jina's results shape, regardless of which request spelling was sent. Built by lmgw from the model's scores, never relayed: no result carries its document.

modelrequired string The model as the request named it.
objectrequired string One of list.
resultsrequired array of object
indexrequired integer The document's position in the request.
relevance_scorerequired number
usagerequired object
prompt_tokensrequired integer What the model reported; 0 when it reported nothing.
total_tokensrequired integer The same number: reranking generates nothing.

ResolvedExtra

One extra with the commit it resolved to for a run.

extrarequired BuildExtra
sharequired string Full commit SHA that was (or will be) merged.

ResolvedInputs

What every "auto" and every "follow the head" of a build became for one
run. Filled by the run executor; the config hash is computed
over these values, never over the unresolved definition.

archrequired array of string The arch list passed to the build, in the order passed.
base_sharequired string Full SHA the base ref resolved to.
cuda_versionrequired string | null None for a non-CUDA backend.
dockerfilerequired string Repo-relative Dockerfile path.
editsrequired array of BuildEdit The edits applied — the build's explicit list, or the preset's for
dockerfile.
extrasrequired array of ResolvedExtra The extras the run merges, in order, each with its resolved SHA. A
pr extra already merged upstream is skipped by the run and left out
here — it does not change the image.
targetrequired string Final build stage.

Response

An upstream that speaks the Responses API natively is relayed as it sends the body: such a body may carry status queued (background), a null or missing usage and no store. lmgw's own translation always sends usage and store.

access_programs null Always null; present because OpenAI's schema requires the field.
created_atrequired integer
errorrequired object | null
idrequired string
incomplete_detailsrequired object | null
reasonrequired string
modelrequired string
objectrequired string One of response.
outputrequired array of object Items are loosely typed here. An output_text part of a message item carries logprobs: []: lmgw relays no log probabilities yet; OpenAI's schema requires the field.
statusrequired string One of queued, in_progress, completed, incomplete, failed, cancelled.
store boolean Whether lmgw stored this response, so a later request can continue from it with previous_response_id. Sent by lmgw's own translation; a verbatim upstream body may leave it out.
usage object | null
input_tokensrequired integer
input_tokens_detailsrequired object Tokens read from and written to the prompt cache, both part of input_tokens; 0 when the upstream reported none (cache_write_tokens is lmgw's own addition and absent from a verbatim upstream body).
cache_write_tokens integer
cached_tokensrequired integer
output_tokensrequired integer
output_tokens_detailsrequired object
reasoning_tokensrequired integer
total_tokensrequired integer

ResponseDeleted

deletedrequired boolean One of true.
idrequired string
objectrequired string One of response.

ResponseInputItems

datarequired array of object
objectrequired string One of list.

ResponseInputTokens

input_tokensrequired integer
objectrequired string One of response.input_tokens.

ResponseItem

bodyrequired string Full response JSON, pretty-printed.
created_atrequired string
idrequired string
input_tokensrequired integer | null
outlinerequired string Output items at a glance, e.g. 2 mcp_call, message.
output_tokensrequired integer | null
pendingrequired array of string Tool calls awaiting approval, {name} ({approval_id}).
statusrequired string
textrequired string Rendered assistant text.

ResponseStreamEvent

SSE event: response.<name>, data: <this object>. The response.output_text.delta and .done events carry logprobs: [] (lmgw relays no log probabilities yet; OpenAI's schema requires the field).

sequence_numberrequired integer
typerequired string response.created … response.completed/.incomplete/.failed, response.output_text.delta, the mcp_*/function_call_* tool-call events, …

ResponsesRequest

background boolean true is refused on every path: a background response finishes after its answer has left, so lmgw could never record what it spent or hold it to a budget.
include array of string
input any A string (one user turn), or an array of items.
instructions string Becomes the leading system message; an explicit empty string drops it on a chained call.
max_output_tokens integer
max_tool_calls integer
metadata any Echoed back verbatim on the response object.
modelrequired string
parallel_tool_calls boolean Default true.
previous_response_id string Continues a stored response: its conversation, tool calls and results included, goes ahead of this call's input, and mcp_approval_response items settle the calls it stopped at. 400 while the gateway's response store is switched off; 404 when no stored response has this id (it was evicted, or created with storing off). On an upstream that implements the Responses API itself, an id lmgw holds continues in lmgw's own loop and any other id goes to the upstream with the body; with mcp tools lmgw serves, such an id is a 400, since neither side can serve both.
reasoning object The one reasoning control this dialect reads: reasoning.effort.
effort string
service_tier string OpenAI's processing tier (auto, default, flex, priority, fast, scale, ultrafast), forwarded as sent; on an OpenAI platform row lmgw sends auto when it is unset, and prices the answer at the tier the answer reports. A request by a caller with a budget (its key's, or the gateway's) on a cloud model with no price on file for what it is billed in is refused before the send: 403 budget_unpriced, naming the model and the missing price. A flex request needs a flex price: no other tier's price bounds a flex answer's spend, which is cheaper.
store boolean Whether lmgw keeps this response, so a later call can continue it with previous_response_id (default true). Storing also needs the gateway's response store, which is on by default: a request can turn storing off, never on. The response object's store says whether this response was kept, so a client can see up front whether previous_response_id will work. On an upstream that implements the Responses API itself the body goes there as sent, and storing is the provider's.
stream boolean Default false.
temperature number
text object text.format (json_schema, json_object, text) is the structured output every upstream gets in its own spelling, as on /v1/chat/completions; a native Responses upstream gets the body as sent. Its refusals are 400 response_format_unsupported / invalid_json_schema with param text.format.
tool_choice any "auto" | "none" | "required" | {type:function,name} everywhere; any other form the upstream's API defines ({type:web_search_preview}, {type:allowed_tools,…}, {type:mcp,server_label}, …) goes natively to an upstream that implements the Responses API itself and is refused by lmgw's own loop.
tools array of object | object | object function tools the loop hands back to the client; mcp tools run server-side on lmgw's own registered MCP servers, and keep the request in lmgw's own loop on an upstream that implements the Responses API itself (an mcp label lmgw does not serve goes there with the body). Hosted tools (web_search, file_search, code_interpreter, image_generation, computer_use_preview, …) go natively to such an upstream, which runs them, and are refused by lmgw's own loop.
top_k integer
top_p number
truncation string "auto" goes natively to an upstream that implements the Responses API itself; lmgw's own loop refuses it, since it never silently drops conversation history.

ResultTask

The MCP task a call started, on its result frame.

idrequired integer (int64) lmgw's id of the task (ThreadTask.id).
server_labelrequired string
task_idrequired string The server's id of the task.

RetriedRequest

A request the engine sent a second time because its connection broke
before any response arrived. What the
step recorded is the second attempt's.

errorrequired string Why the first attempt failed, with its whole cause chain.
requestrequired string The request, e.g. POST /completion.
stagerequired string The step it belonged to, as the progress line named it
("prefill: 32768 tokens, repetition 1/3").

RevokeKind

What revoked a key, as a CLOSE_REVOKED close's reason starts with it
and the change feed's revoked event carries it (kind):

- device_disabled: a paired device was disabled; it may be enabled
again, so it keeps its pairing;
- key_expired: a paired device's key passed its expiry;
- key_unknown: a paired device's key was rotated or deleted: pair the
device again;
- certificate_expired: a paired device's client certificate passed its
notAfter while the connection was open (device link design §5.1):
pair the device again;
- revoked: any other kind of key, for any of these.

Forward compatible like every enum a client reads: a token a newer
gateway sends reads as RevokeKind::Unknown, as sent. One an older
gateway does not send at all — a close reason without a token, a
revoked event without kind — is an empty Unknown, the default, so
a client never reads a device's rotation as another key's revocation.

One of: string

RouterSettings

The chat/aux *class* settings.
container_name/listen_port/models_max/
auto_start left with router mode: names are derived, ports are dynamic,
and auto-start is the per-model warm_start flag.

extra_run_argsrequired array of string Class default; a model's own extra_run_args overrides it.
imagerequired string Class default; a model's own image overrides it.
models_dirrequired string
public_prefixrequired string
request_timeout_secondsrequired integer (uint64) Per-request ceiling for the class, in seconds: how long lmgw waits for
an answer to start, and how long a streamed answer may then go
without an event before lmgw ends it with an error. **0 = the maximum
possible** — no deadline of lmgw's own. One per class since the four
stopped sharing a single 600 s constant.

RouterSettingsPatch

extra_run_args array | null Default null.
image string | null Default null.
models_dir string | null Default null.
public_prefix string | null Default null.
request_timeout_seconds integer | null Default null.

Row

One row of the review table.

Both a live frame and a stored result use this shape, so the table renders
the same whether the run is in flight or was finished last week.

attention boolean The output equals the fallback, or the call failed; through a question
set also a confidence below the set's measured threshold (decide). Default false.
columns object The manifest's columns, rendered. Order comes from the manifest, not
from this map. Default {}.
error string | null
id string item.id rendered. Empty marks the row errored — there is no
stable identity to apply anything against. Default "".
item any The **source** item, kept so a re-run can re-fetch and re-classify this
row without re-listing the mailbox. Not shown anywhere.
output any The structured answer. null for a list-only run, which makes no call. Default null.
prompt string | null Exactly the user text the model received, for the details modal.
Kept per row because "why did it say that" is the question the
review table exists to answer.
raw string | null What the model actually replied, so a surprising answer is explainable.
set AgentRowSet | null The question set that classified this row, as the run read it
(decide); None for the model call. "Save as labelled set" saves
a run's rows into the set stamped on them.

RowPricing

The rates a request row was priced with and its cost's parts, each as
the row snapshotted it. None = that part or rate did not apply, or
(for the costs) was unknown — never 0.

cost_in_microrequired integer | null The cost's token parts and its part in every other unit, in currency
micro-units.
cost_out_microrequired integer | null
cost_units_microrequired integer | null
currencyrequired string The gateway's configured currency, which every amount here is in.
in_remainderrequired boolean Whether this row is counted in the unpriced remainder the usage
totals state beside their cost (cost_unknown_requests): its cost is
unknown, it is no tool call, and it was answered or spent something
(tokens or a measured quantity). false for a priced row, a tool
call, and a refusal or failure that spent nothing: nothing billed is
missing from a total.
price_inrequired number | null The token rates, per 1M tokens.
price_outrequired number | null
price_per_audio_minuterequired number | null The other units' rates: per minute of input audio, per 1M input
characters, per generated image, per answered request.
price_per_imagerequired number | null
price_per_mcharrequired number | null
price_per_requestrequired number | null
sourcerequired string | null catalog, manual, free_local or unknown.

RunResults

Everything a run measured apart from the probes and the timeline.

completerequired boolean True once every selected phase finished without an error. A crash, a
cancel or a phase error leaves it false: the numbers present are real,
the set is partial.
concurrentrequired array of ConcurrentPoint
corpus_tokensrequired integer | null The corpus, tokenized by the bench server.
decoderequired array of DecodePoint
energyrequired EnergySummary
loadrequired LoadResult | null
mixedrequired MixedResult | null
phase_errorsrequired array of PhaseError
phases_donerequired array of Phase Phases that ran to the end, in order.
pointsrequired PointPlan | null
prefillrequired array of PrefillPoint
prompt_prefixrequired array of integer (uint32) The token ids every measured prompt starts with: the vocabulary's
BOS where it adds one — llama-server adds none to a token-id prompt —
counted inside each prompt's length. Empty when the
vocabulary adds nothing.
retriedrequired array of RetriedRequest Requests sent a second time after a broken connection,
in the order they happened.
serverrequired ServerFacts | null

Rung

One ladder rung above the base — its own weights and its own context. The base rung is
never one of these; it stays the row's own gguf_path and ctx_size.

ctx_sizerequired integer (int64)
gguf_pathrequired string

Rung2

One rung above the base: its own weights and its own -c.
ctx_size is a real token count: a rung with no context at all is not a
rung, so saving one with a non-positive value is refused.

ctx_sizerequired integer (int64) --ctx-size for this rung — the same meaning ctx_size has
everywhere else: it is -c, never the per-slot number.
gguf_pathrequired string GGUF path relative to the models dir, exactly like the base row's
gguf_path.

RungDetail

One ladder rung as the model read shows it.

command_linerequired string The podman run … command line this rung renders to.
ctx_sizerequired integer (int64)
gguf_pathrequired string
ofrequired integer (uint) How many rungs the ladder has.
per_slot_ctxrequired integer | null The context one slot gets on this rung; null when the base row
predates the rule that derives it.
rungrequired integer (uint) This rung's number, from 1 (the base row).
switchoverrequired integer | null The prompt length at which a request moves up to the next rung.

RungFootprint

A model's estimated GPU cost. The CUDA context, allocator slack and a
projector's compute buffer are not in it; those are the headroom's.

compute_bytesrequired integer (uint64) The compute buffers llama.cpp reserves on the card, derived from the
header and the row's slots, batch sizes and context: for a chat row
(a ladder rung) its own context's and its MTP or draft context's,
summed.
ctx_tokensrequired integer | null Context the KV figure was computed for; None when it could not be
derived (also why kv_cache_bytes would be 0).
kv_cache_bytesrequired integer (uint64) The KV cache, a speculative row's MTP or draft cache and recurrent
state included.
noterequired string | null Why a term is missing or approximate, when it is.
total_bytesrequired integer (uint64) weights_bytes + kv_cache_bytes + compute_bytes.
weights_bytesrequired integer (uint64)

RungStatus

The rung a container runs, 1-based (the base is rung 1).

ggufrequired string The weights' file name.
ofrequired integer (uint)
rungrequired integer (uint)

RungTest

One rung's test.

ctx_sizerequired integer | null
error string Why the rung failed, when it did.
gguf_pathrequired string | null
load_secondsrequired number (double) Seconds it took the rung to become ready.
ofrequired integer (uint)
okrequired boolean
per_slot_ctxrequired integer | null
rungrequired integer (uint) This rung's number, from 1 (the base row).
switchoverrequired integer | null

RuntimeStatus

One model container's runtime state.

classrequired string chat | aux | audio | image.
climbing ClimbStatus A climb in progress: to which rung, why, and what it is doing now.
container_namerequired string
draining_for_owner boolean A foreground admission is waiting for room, and background traffic takes
no new work on this model until it is over. Absent = false.
image_capabilities ImageCapabilities What an image container reported about its loaded pipeline. None for
every other class, and for an image container whose capabilities route
answered anything but a 200.
in_flightrequired integer (uint32)
last_used_age_secondsrequired integer (uint64)
llama_props LlamaProps What a llama-server container said about itself in GET /props.
None for every other engine, and when the
read failed — warnings then says why.
model_idrequired string
owner string Whom the container runs for:
"background" when a background candidate alias started it and
foreground traffic has not claimed it since. None — absent from the
frame — is foreground: every request that is not a background candidate
alias's, every warm, boot or operator start, and lmgw's own in-process
callers. That is every container of an install without background
traffic.
placement string "cpu" for an audio container started on the CPU (the per-row CPU
switch): no VRAM, not stopped by the GPU hold. None — absent from
the frame — is the GPU, every other container.
portrequired integer (uint16) 0 while the entry is starting — no port has been allocated yet.
rung RungStatus The rung this container runs. None for a row
without a ladder, and #[serde(default)] so a frame from before this
field existed still decodes.
sends integer (uint32) Sends in flight as the ladder gate counts them — what a climb drains.
Only ladder sends are counted, so this is zero on every other row.
started_at_age_secondsrequired integer (uint64)
staterequired string starting | ready | stopping.
warnings array of string Non-fatal problems this model's start found.
Empty for a clean one, and absent from a frame older than the class.

Sampling

The sampling every request of a run uses: pinned, so builds compare
and speculative decoding's acceptance does not wander with the row's own
sampler.

seedrequired integer (uint64)
temperaturerequired number (double)
top_krequired integer (uint32)
top_prequired number (double)

ScoreAnswer

confidencerequired number (double)
legendrequired object Each level's index ("0", "1", …) with its description.
probabilitiesrequired object Each level's index with its probability.
scorerequired number (double) The expected level index, weighted by probability: it can fall between
two levels.

ScoreLabels

How a score question's label column reads: every value one way.

One of: string (Each value is a level's exact text.); string (Each value is a level's index, from 0.)

ScoreQuestion

criteriarequired array of string The levels' descriptions, lowest first: 2 to 10 of them.
instructionsrequired any The question: a string, an object or an array.

SearchHit

chunkrequired ChunkRow
fts_rankrequired integer | null
knn_rankrequired integer | null
knn_scorerequired number | null
rerank_scorerequired number | null
rerank_skipped boolean The rerank stage ran but did not score this candidate: score is then
its RRF score and it ranks behind the reranked ones. Absent when false.
rrf_scorerequired number (float)
scorerequired number (float) The score the final order is by: the reranker's when it ran, RRF's
otherwise.
tokensrequired integer (uint64)

SearchHit2

One place that matches.

kindrequired string t the title, m a message, a an attachment's name.
message_id integer (int64) The message, for kind m.
role string The message's role, for kind m.
snippetrequired string The text around the match, with the match between U+E000 and U+E001
(private-use characters; escape the text before turning them into
markup).

SearchParamsView

One request's stage parameters. Round-trips: this is both what the trace
reports and what the playground posts back as params.

budget_tokensrequired integer | null None returns all limit chunks — the budget is the caller's choice.
fts_weightsrequired FtsWeightsView
k_ftsrequired integer (uint64)
k_rerankrequired integer (uint64)
k_vecrequired integer (uint64)
limitrequired integer (uint64)
rerankrequired boolean
rrf_krequired number (float)

SearchThread

A thread with matches.

archivedrequired boolean
folder_idrequired integer | null null for a thread in no folder, and for one in a folder the
caller cannot see.
hitsrequired array of SearchHit2 The best matches, up to three.
match_countrequired integer (int64) How many places in the thread match.
thread_idrequired integer (int64)
titlerequired string
updated_atrequired string

SearchTraceView

Per-stage trace: what each stage saw, in the order it saw it.

budget_droppedrequired array of string Chunks the token budget dropped, in the order they would have come.
budget_used_tokensrequired integer (uint64)
corpus_idrequired string
embed_modelrequired string
ftsrequired array of StageHitView
fts_queryrequired string The FTS5 MATCH expression actually issued — user text is never passed
through raw.
fusedrequired array of FusedHitView
knnrequired array of StageHitView
knn_kernelrequired string Which widening kernel the KNN scan used.
knn_skipped string Why the vector stage did not run, so BM25 alone answered. Absent when
it ran.
paramsrequired SearchParamsView
rerankrequired array of StageHitView
rerank_modelrequired string | null
rerank_skippedrequired string | null Why the rerank stage did not run, when params.rerank asked for it.
resident_bytesrequired integer (uint64)
resident_vectorsrequired integer (uint64)
timingsrequired TimingsView
token_counterrequired string

SemanticVadRow

One eagerness's row of realtime.semantic_vad.

floorrequired number (double) A score at or above this and below the threshold commits at
semantic_floor_window_ms; equal to the threshold turns the middle
band off.
max_wait_msrequired integer (uint32) The longest a pause waits, whatever the score.
silence_duration_msrequired integer (uint32) Where a pause that could not be scored commits, and the window the
server_vad engine runs this eagerness on.
thresholdrequired number (double) A Smart Turn score at or above this commits the turn, 0.0..=1.0.

SemanticVadRowPatch

One row's patch.

floor number | null Default null.
max_wait_ms integer | null Default null.
silence_duration_ms integer | null Default null.
threshold number | null Default null.

SemanticVadTable

realtime.semantic_vad: the rows by eagerness (auto is medium).

highrequired SemanticVadRow
lowrequired SemanticVadRow
mediumrequired SemanticVadRow

SemanticVadTablePatch

realtime.semantic_vad's patch: the rows by eagerness.

high SemanticVadRowPatch | null
low SemanticVadRowPatch | null
medium SemanticVadRowPatch | null

SeriesMeta

Identity of one series, with the colour slot it wears everywhere.

foldedrequired integer | null On the folded "Other" series only: how many entities it sums, so a
legend can say "Other (49 aliases)" instead of hiding the tail's size.
null on every named series.
keyrequired string
labelrequired string What to print — a key id resolves to its name here, an upstream id to
its name, an alias is itself.
localrequired boolean True for a locally-served model — it can never appear in a spend chart,
because its money cost is a real zero.
slotrequired integer | null Chart colour slot 0..5, or null for the neutral "Other" bucket.

Assigned from the entity's position in the gateway's own sorted list of
aliases, **not** from its rank in this response: a filter that drops a
series must not repaint the survivors, or a reader who learned "qwen is
teal" is being lied to.

ServedModel

An alias a stage asked for, the one that answered when it was another,
and (for the text-to-speech stage) the voice.

aliasrequired string
answered_byrequired string | null
voice string

ServerFacts

What the live server says about itself: the numbers every point is
derived from, and the build facts /props carries on engines that report
them.

build_inforequired string | null /props build_info (official llama.cpp only).
chat_template_capsrequired object /props chat_template_caps, the boolean entries. Empty when the
engine sends none (ik).
kv_unifiedrequired boolean | null Whether every slot draws its KV cells from one shared pool: then *S* is the whole pool, and
requests running
together must fit in it side by side — a full pool aborts every
running request. From the server where it says (ik's top-level
n_ctx against the per-slot one), else from the row's effective
settings (kv_unified, or parallel left on auto); None when
neither says, read as split.
kv_unified_sourcerequired string | null Where kv_unified was read: props.n_ctx or settings.
model_ftyperequired string | null /props model_ftype (official llama.cpp only).
n_slotsrequired integer (uint32) *N_slots*: /props total_slots, else the length of /slots.
per_slot_ctxrequired integer (uint64) *S*: the per-slot context.
per_slot_ctx_sourcerequired string Where *S* was read: slots, props.default_generation_settings.n_ctx
or props.n_ctx / total_slots.
speculativerequired boolean | null Whether any slot reports speculative decoding (official /slots).
total_ctxrequired integer | null The whole context, where the engine reports it (ik's top-level
/props n_ctx).
visionrequired boolean | null /props modalities.vision.

SettingsFit

Which card's model settings (§1.4): the images, run arguments and audio
backend lmgw ships for it.

One of: string (AMD cards, through Vulkan: the llama.cpp, audio.cpp and
stable-diffusion.cpp Vulkan images, given the render nodes and the
user's groups.); string (NVIDIA cards, through CUDA: lmgw's defaults.)

SettingsFitChange

One field the switch changes.

classrequired string The model class: chat, aux, audio or image.
fieldrequired string The field as the dashboard names it: "Settings → Runtimes → Chat →
Image" for a class, "Image override" or "Extra podman run args
override" on a model's page.
fromrequired SettingsFitValue | null The value now. None: the model has no setting of its own and uses
its class's.
modelrequired string | null The model whose own setting this is; None for the class's setting.
torequired SettingsFitValue | null The value after the switch. None: the model's own setting is
cleared, so it uses its class's from then on.

SettingsFitChangeInput

One field the switch changes.

classrequired string The model class: chat, aux, audio or image.
fieldrequired string The field as the dashboard names it: "Settings → Runtimes → Chat →
Image" for a class, "Image override" or "Extra podman run args
override" on a model's page.
from SettingsFitValue | null The value now. None: the model has no setting of its own and uses
its class's.
model string | null The model whose own setting this is; None for the class's setting.
to SettingsFitValue | null The value after the switch. None: the model's own setting is
cleared, so it uses its class's from then on.

SettingsFitLeft

A setting the switch leaves as it is, and why.

classrequired string The model class: chat, aux, audio or image.
fieldrequired string The field, as SettingsFitChange::field names it.
modelrequired string | null The model whose own setting this is; None for the class's.
valuerequired SettingsFitValue Its value.
whyrequired string Why it stays, in plain words.

SettingsFitOutdated

Why a confirmed switch wrote nothing: the switch worked out when it was
to be written is not the list that was confirmed.

addedrequired array of SettingsFitChange Changes the switch makes now that the confirmed list did not have.
modelsrequired array of string Models whose own settings were changed while the switch was being
written.
withdrawnrequired array of SettingsFitChange Changes of the confirmed list the switch no longer makes as listed.

SettingsFitRunning

A running model whose settings the switch changes.

classrequired string The model class: chat, aux, audio or image.
modelrequired string
stoprequired SettingsFitStop | null What the confirmed switch did to it; None in an offer.

SettingsFitStop

What a confirmed switch did to a running model it concerns.

One of: object (Stopped: its next start uses the new settings.); object (It had stopped by then.); object (It is answering in_flight requests, so it keeps running with the
settings from before until it stops.); object (Stopping it failed; it may still run with the settings from before.)

SettingsFitValue

A setting's value as the switch shows it.

One of: string (An image or the audio backend.); array of string (Run arguments, one podman run argument each, as the field holds
them (one per line in the dashboard).)

Sourced_Nullable_string

A value and the level it came from; source: null when no level sets it.

sourcerequired VoiceSource | null
valuerequired string | null

Sourced_TurnDetectionMode

A value and the level it came from; source: null when no level sets it.

sourcerequired VoiceSource | null
valuerequired TurnDetectionMode

Sourced_boolean

A value and the level it came from; source: null when no level sets it.

sourcerequired VoiceSource | null
valuerequired boolean

SpeechCaps

The speech object of a text-to-speech model's capabilities. Absent
fields are unknown, as everywhere in the schema.

inline_tags string | null What inline tags in input do: none (stripped, never read out),
fixed (the ones in tags are rendered, stage directions mapped
onto them, the rest stripped), free (every [tag] is rendered).
instructions string | null What instructions do: none (dropped — said in x-lmgw-speech),
style (a speaking style for the voice), voice_design (the voice
is designed from them), passthrough (sent; the model reads them —
it declares an instruction option, or lmgw knows its engine reads
one anyway — and decides what they do).
instructions_required boolean | null A request without instructions is refused (instructions_required)
unless the row has a default description.
sample_rate integer | null The sample rate of its audio, in Hz, as its last answer through lmgw
said (a streamed answer's PCM has no header of its own; the same
figure is the x-lmgw-sample-rate header on it). Absent until the
model has answered once since lmgw started.
streaming boolean | null stream_format (sse or audio, response_format: pcm) works on
this row: it runs in streaming mode.
tags array of string The tags a fixed model renders, written [tag].

SpeechForm

The TTS panel's widgets, raw. Parsed by speech_body so the "Request"
disclosure and the actual call are literally the same bytes.

inputrequired string
instructionsrequired string OpenAI's instructions: delivery and style guidance, forwarded as the
engine's instruction option.
languagerequired string Language code passed to models whose contract accepts one; the
transcription panel sends the same field.
max_tokensrequired string
modelrequired string
optionsrequired string Engine options as JSON text, sent as the body's options.
reference_textrequired string
response_formatrequired string
seedrequired string
speedrequired string speed: a positive multiplier, on models that support speed control
(audio.cpp rejects it on models that do not, rather than ignoring it).
streamrequired boolean Stream the answer as server-sent events of PCM.
voicerequired string
voice_refrequired string

SpeechFormInput

The TTS panel's widgets, raw. Parsed by speech_body so the "Request"
disclosure and the actual call are literally the same bytes.

input string Default "".
instructions string OpenAI's instructions: delivery and style guidance, forwarded as the
engine's instruction option. Default "".
language string Language code passed to models whose contract accepts one; the
transcription panel sends the same field. Default "".
max_tokens string Default "".
model string Default "".
options string Engine options as JSON text, sent as the body's options. Default "".
reference_text string Default "".
response_format string Default "".
seed string Default "".
speed string speed: a positive multiplier, on models that support speed control
(audio.cpp rejects it on models that do not, rather than ignoring it). Default "".
stream boolean Stream the answer as server-sent events of PCM. Default false.
voice string Default "".
voice_ref string Default "".

SpeechStyle

The speech instructions; "" is none.

sourcerequired VoiceSource The level the text came from; row when the text-to-speech model's
own description stands in for it.
textrequired string

Stage

One speech stage.

aliasrequired string | null null: nothing configured at any level.
cpurequired boolean An audio model that runs on the CPU: the GPU hold does not stop it, a
benchmark run's lease does.
fallbackrequired Fallback | null What answers instead while the model is blocked; null off this
machine, or when the model has no usable fallback.
fallback_unusablerequired FallbackUnusable | null A fallback the model names that cannot stand in, and why.
inheritedrequired string | null What the levels below the thread give: the alias the thread uses once
its own override is cleared; equal to alias when the thread sets
none.
localrequired boolean | null false for an alias served off this machine; null when the alias
does not resolve.
managedrequired boolean A model lmgw starts itself: the GPU hold and a benchmark run's lease
apply to it.
sourcerequired VoiceSource | null The level alias came from; null with no alias.

StageHitView

One candidate as a stage saw it. score is BM25 (negative, lower is
better), cosine, or the reranker's — read next to the stage it came from.

chunk_idrequired string
rankrequired integer (uint64) 1-based within the stage.
scorerequired number | null null when the embedder or reranker returned NaN, which serde_json
writes as null.
skipped boolean Rerank stage only: the reranker did not score this candidate (its pair
was over the model's input limit); score is then its fused score and
it ranks behind the scored ones. Absent otherwise.

Stat

Median, min and max of one metric over a point's repetitions, and the raw
values in repetition order.

maxrequired number (double)
medianrequired number (double)
minrequired number (double)
valuesrequired array of number (double)

StateMode

How the state is written.

One of: string (Plain text, sent as a JSON string.); string (JSON text (an object, an array, null for the types that take no
state), checked to parse and sent as typed.)

StaticCaps

The statically derived capabilities a /props read is compared with. Each
has the shape the /v1/models capabilities object gives it.

input_modalitiesrequired array | null
reasoningrequired ReasoningCaps | null
tool_callsrequired ToolCallCaps | null

StrList

A list of short names as a patch carries it (modes): a JSON array, or a
comma/whitespace-separated string for the same reason KeyMap takes
text.

One of: array of string; string

StructuredOutputCaps

response_format support.

json_object boolean | null
json_schema boolean | null

SuiteParams

What a run was asked to do. The suite constants are stored
beside the caller's choices, so a stored run says exactly what it measured
without anyone having to know which suite version meant what.

generate_tokensrequired integer (uint32) *G*.
mixed_inject_max_tokensrequired integer (uint64)
mixed_steady_msrequired integer (uint64)
needle_margin_tokensrequired integer (uint64)
phasesrequired array of Phase The selected phases, in suite order; load is always among them.
repetitionsrequired integer (uint32) Repetitions of every point (and of the mixed phase).
samplingrequired Sampling
stream_prompt_tokensrequired integer (uint64)
suite_versionrequired integer (uint32)
warmup_generate_tokensrequired integer (uint32)
warmup_prompt_tokensrequired integer (uint64)

SystemOneAnswer

One answer, by its question's type.

One of: ChoiceAnswer; ScoreAnswer; NoulAnswer

SystemOneQuestion

One question, by its type.

One of: ChoiceQuestion (Pick one of the named options.); ScoreQuestion (Rate on 2 to 10 ordered levels.); NoulQuestion (Yes or no.)

SystemOneResponse

POST /v1/systemone's answer, as the upstream sent it.

model is the upstream's own: the versioned id that answered on TypeSafe
(jev-1.13.0), a dated id on OpenRouter, the server's --alias on
llama.cpp. lmgw does not write the requested name back; which alias
answered is x-lmgw-fallback's to say (§2.1).

answersrequired object One answer per question, under the question's key.
id string | null OpenRouter's extension: the generation's id.
modelrequired string
provider string | null OpenRouter's extension: the provider that answered.
usagerequired SystemOneUsage

SystemOneUsage

What a request processed: lmgw logs input_tokens as the row's prompt
tokens and output_tokens as its completion tokens, and prices them from
its own price rows (§2.6).

cost number | null OpenRouter's extension: what the request cost there, in USD. Relayed,
never read: lmgw prices from its own rows.
input_tokensrequired integer (uint64)
output_tokensrequired integer (uint64) Always 0 on llama.cpp; TypeSafe and OpenRouter report a non-zero
count, which Jev's price does not charge.

Takeover

?takeover=: whether a bind may take its thread from another session.

One of: string (Take the thread over (what a bind without the parameter does).); string (Never: refuse while another session is bound to the thread.); string (Ask first (WebRTC calls only, realtime calls design §2.8): a thread
held when the call's channel opens makes the call wait,
lmgw.session.bind_pending, for the client's
lmgw.session.take_over or the holder's end.)

Target

A device the caller can offer a file to.

device_idrequired integer (int64) Its key id: the offer's to_device.
last_seen_atrequired string | null When one of its connections last opened or closed (RFC 3339 UTC);
null for one that never connected.
namerequired string Its paired name, without device:.
onlinerequired boolean Whether it holds its Chat feed open now, so it hears an offer at
once.

TaskForm

The generic task panel's fields.

flags object Each checkbox, by the request field it sets. Default {}.
json string Raw JSON merged into the request last. Default "".
stream boolean Send to /v1/tasks/stream. Default false.
values object Each field's text, by the request field it fills. Default {}.

TaskRequest

modelrequired string
requestrequired object Relayed to audio.cpp's generic task endpoint untouched; its shape is the task's own and is not modeled here.

TemplateSignals

What the chat template's own text says about reasoning, effort selection
and tool-call rendering. Pure text heuristics: a template that does it
through indirection reads as absent.

effort_defaultrequired string | null The effort it falls back to, verbatim.
effort_levelsrequired array of string The effort levels it compares against, in canonical order.
effort_var_namesrequired array of string Which effort variables it reads.
enable_thinking_defaultrequired boolean | null The default of enable_thinking, when the template states one.
enable_thinking_varrequired boolean The template reads an enable_thinking variable.
parallel_tool_callsrequired boolean The template loops over tool_calls: several calls per turn.
preserve_thinking_varrequired boolean The template reads preserve_thinking.
reasoning_effort_varrequired boolean The template reads a reasoning-effort variable of any name.
thinking_markerrequired string | null The first marker that matched, verbatim.
thinking_markersrequired boolean The template renders a reasoning trace somewhere.
tool_call_formatrequired string | null The native tool-call syntax family it renders.
tools_varrequired boolean tools is used as a variable.

TestUsage

A test call's token usage, as the model reported it.

completion_tokensrequired integer | null
prompt_tokensrequired integer | null

TextCompletion

Relayed as the upstream sends it.

choicesrequired array of object
createdrequired integer
idrequired string
modelrequired string
objectrequired string One of text_completion.
usage object

TextCompletionChunk

One frame, relayed as the upstream sends it: data: <this object>, repeated, ending with the literal data: [DONE].

choicesrequired array of object
createdrequired integer
idrequired string
modelrequired string
objectrequired string One of text_completion.

Thread

One Chat thread with what an open thread shows: its list row, what its
voice resolves to now, and (where it is read whole) whether its last
reply can be continued.

agent_idrequired string | null The agent the thread was opened from, if any.
archived_atrequired string | null When the thread was archived; null while it is active.
continue ContinueState Whether the last reply can be continued. Present where the thread
is read whole, as POST /chat/api/folders/{id}/current answers it.
created_atrequired string
folder_idrequired integer | null The folder the thread is in; null for none.
frequency_penaltyrequired number | null
idrequired integer (int64) Negative for a temporary thread.
kb_budget_tokensrequired integer | null The retrieval budget of auto mode in tokens; null for the Chat's
setting.
kb_idsrequired array of integer (int64) Knowledge bases the thread searches, by id.
kb_moderequired KbMode
kindrequired string chat, or admin for a thread that drives the gateway's own
configuration (never listed for a device key).
last_message_atrequired integer | null When its newest message was written, in unix seconds; null for a
thread without messages. An ongoing folder's idle rollover is
measured from it: a client that shows when the conversation moves
on reads it here rather than timing the turns it saw.
max_tokensrequired integer | null
mcp_toolsrequired array of ThreadMcp The tool servers the thread's turns use; empty for a plain chat. A
thread with lmgw (the self-admin toolset) among them is listed for a
device key only when the device may use lmgw's admin tools.
media_defaultsrequired MediaDefaults The thread's own default models of the image and audio tools; an
absent field inherits its folder's, then Settings → Chat's, and an
empty one is no default (GET /chat/api/media/defaults says what
they resolve to).
min_prequired number | null
model_aliasrequired string The alias the thread's turns go to.
pinnedrequired boolean Pinned threads are listed first and are never archived or deleted
by the sweep.
presence_penaltyrequired number | null
profile_idrequired integer | null The personality profile the thread talks with
(GET /chat/api/profiles); null for none ("Default").
purge_atrequired string | null When an archived thread will be deleted; null while it is active,
pinned, or when deleting is switched off.
reasoning_budgetrequired integer | null
reasoning_effortrequired string | null
reasoning_enabledrequired boolean | null Reasoning overrides sent with every turn; null leaves the route's
default.
repeat_penaltyrequired number | null
seedrequired integer | null
stoprequired array of string Stop sequences; empty leaves the route's default.
system_promptrequired string
temperaturerequired number | null Sampling overrides sent with every turn; null leaves the route's
default.
temporaryrequired boolean The thread lives in memory only and is gone at the gateway's next
start unless it is kept.
titlerequired string
top_krequired integer | null
top_prequired number | null
updated_atrequired string Moves with every change to the thread and every new message.
voicerequired ThreadVoice
voice_resolvedrequired VoiceResolved What the thread's voice resolves to now, field by field with the
level each value comes from (the thread, the Chat's settings, the
realtime settings): the speech-to-text and text-to-speech stages
(asr, tts: alias, whether it runs on this machine, what answers
for it while the GPU is held), voice, speech_style, language,
reply_language, read_aloud, turn_detection, audio_input,
seed, the problems that block a voice feature now, and
realtime: whether voice mode can bind the thread.

ThreadChanged

thread.created / thread.updated for a thread that exists at delivery:
the thread as GET /chat/api/threads lists it now, with by beside its
fields.

agent_idrequired string | null The agent the thread was opened from, if any.
archived_atrequired string | null When the thread was archived; null while it is active.
byrequired string | null Who made the change; null for the gateway's own, such as the sweep.
created_atrequired string
folder_idrequired integer | null The folder the thread is in; null for none.
frequency_penaltyrequired number | null
idrequired integer (int64) Negative for a temporary thread.
kb_budget_tokensrequired integer | null The retrieval budget of auto mode in tokens; null for the Chat's
setting.
kb_idsrequired array of integer (int64) Knowledge bases the thread searches, by id.
kb_moderequired KbMode
kindrequired string chat, or admin for a thread that drives the gateway's own
configuration (never listed for a device key).
last_message_atrequired integer | null When its newest message was written, in unix seconds; null for a
thread without messages. An ongoing folder's idle rollover is
measured from it: a client that shows when the conversation moves
on reads it here rather than timing the turns it saw.
max_tokensrequired integer | null
mcp_toolsrequired array of ThreadMcp The tool servers the thread's turns use; empty for a plain chat. A
thread with lmgw (the self-admin toolset) among them is listed for a
device key only when the device may use lmgw's admin tools.
media_defaultsrequired MediaDefaults The thread's own default models of the image and audio tools; an
absent field inherits its folder's, then Settings → Chat's, and an
empty one is no default (GET /chat/api/media/defaults says what
they resolve to).
min_prequired number | null
model_aliasrequired string The alias the thread's turns go to.
pinnedrequired boolean Pinned threads are listed first and are never archived or deleted
by the sweep.
presence_penaltyrequired number | null
profile_idrequired integer | null The personality profile the thread talks with
(GET /chat/api/profiles); null for none ("Default").
purge_atrequired string | null When an archived thread will be deleted; null while it is active,
pinned, or when deleting is switched off.
reasoning_budgetrequired integer | null
reasoning_effortrequired string | null
reasoning_enabledrequired boolean | null Reasoning overrides sent with every turn; null leaves the route's
default.
repeat_penaltyrequired number | null
seedrequired integer | null
stoprequired array of string Stop sequences; empty leaves the route's default.
system_promptrequired string
temperaturerequired number | null Sampling overrides sent with every turn; null leaves the route's
default.
temporaryrequired boolean The thread lives in memory only and is gone at the gateway's next
start unless it is kept.
titlerequired string
top_krequired integer | null
top_prequired number | null
updated_atrequired string Moves with every change to the thread and every new message.
voicerequired ThreadVoice

ThreadDefaults

What a new thread in a folder starts with. Every field is optional;
null is the Chat's own default. A copy is taken when a thread is
created, except that an ongoing conversation's changed defaults also
reach its current thread — and media_defaults, which every thread in
the folder reads at each turn.

frequency_penaltyrequired number | null
kb_budget_tokensrequired integer | null
kb_idsrequired array | null
kb_moderequired KbMode | null
max_tokensrequired integer | null
mcp_toolsrequired array | null
media_defaultsrequired MediaDefaults | null The image and audio tools' default models of every thread in the
folder, read at each turn rather than copied: an absent field
inherits Settings → Chat's, an empty one is no default, and a
thread's own wins.
min_prequired number | null
model_aliasrequired string | null The model of a new thread; an ongoing conversation needs one.
presence_penaltyrequired number | null
profile_idrequired integer | null The personality profile of a new thread; null for the Chat's own
default (Settings → Chat).
reasoning_budgetrequired integer | null
reasoning_effortrequired string | null
reasoning_enabledrequired boolean | null
repeat_penaltyrequired number | null
seedrequired integer | null
stoprequired array | null
system_promptrequired string | null
temperaturerequired number | null
top_krequired integer | null
top_prequired number | null
voicerequired ThreadVoice | null Voice settings, laid field by field over a new thread's.

ThreadDefaultsInput

What a new thread in a folder starts with. Every field is optional;
null is the Chat's own default. A copy is taken when a thread is
created, except that an ongoing conversation's changed defaults also
reach its current thread — and media_defaults, which every thread in
the folder reads at each turn.

frequency_penalty number | null Default null.
kb_budget_tokens integer | null Default null.
kb_ids array | null Default null.
kb_mode KbMode | null Default null.
max_tokens integer | null Default null.
mcp_tools array | null Default null.
media_defaults MediaDefaults | null The image and audio tools' default models of every thread in the
folder, read at each turn rather than copied: an absent field
inherits Settings → Chat's, an empty one is no default, and a
thread's own wins. Default null.
min_p number | null Default null.
model_alias string | null The model of a new thread; an ongoing conversation needs one. Default null.
presence_penalty number | null Default null.
profile_id integer | null The personality profile of a new thread; null for the Chat's own
default (Settings → Chat). Default null.
reasoning_budget integer | null Default null.
reasoning_effort string | null Default null.
reasoning_enabled boolean | null Default null.
repeat_penalty number | null Default null.
seed integer | null Default null.
stop array | null Default null.
system_prompt string | null Default null.
temperature number | null Default null.
top_k integer | null Default null.
top_p number | null Default null.
voice ThreadVoice | null Voice settings, laid field by field over a new thread's. Default null.

ThreadGone

thread.deleted, and thread.created / thread.updated for a thread
that is gone by the time the event is delivered.

byrequired string | null Who made the change; null for the gateway's own (the sweep).
deletedrequired boolean
thread_idrequired integer (int64)

ThreadMcp

A tool server attached to a thread: the label it is reached by, and
optionally the tools of it the thread uses.

allowed_toolsrequired array | null The tools of that server the thread uses; null for all of them.
require_approval any Which of them wait for an approval before they run, in OpenAI's
shapes: "never" (the default, also when absent), "always", or
{"always": {"tool_names": […]}, "never": {"tool_names": […]}}. A
name may be the tool's own or its prefixed one. read_only is
refused. A gated call stops the turn; POST
/chat/api/threads/{id}/approvals
decides it.
server_labelrequired string A registered tool server's tool prefix (or its name when it has
none), or a built-in toolset such as kb.

ThreadMcpInput

A tool server attached to a thread: the label it is reached by, and
optionally the tools of it the thread uses.

allowed_tools array | null The tools of that server the thread uses; null for all of them. Default null.
require_approval any Which of them wait for an approval before they run, in OpenAI's
shapes: "never" (the default, also when absent), "always", or
{"always": {"tool_names": […]}, "never": {"tool_names": […]}}. A
name may be the tool's own or its prefixed one. read_only is
refused. A gated call stops the turn; POST
/chat/api/threads/{id}/approvals
decides it.
server_labelrequired string A registered tool server's tool prefix (or its name when it has
none), or a built-in toolset such as kb.

ThreadRow

A Chat thread as GET /chat/api/threads lists it, and as the change
feed's thread.created and thread.updated carry it.

agent_idrequired string | null The agent the thread was opened from, if any.
archived_atrequired string | null When the thread was archived; null while it is active.
created_atrequired string
folder_idrequired integer | null The folder the thread is in; null for none.
frequency_penaltyrequired number | null
idrequired integer (int64) Negative for a temporary thread.
kb_budget_tokensrequired integer | null The retrieval budget of auto mode in tokens; null for the Chat's
setting.
kb_idsrequired array of integer (int64) Knowledge bases the thread searches, by id.
kb_moderequired KbMode
kindrequired string chat, or admin for a thread that drives the gateway's own
configuration (never listed for a device key).
last_message_atrequired integer | null When its newest message was written, in unix seconds; null for a
thread without messages. An ongoing folder's idle rollover is
measured from it: a client that shows when the conversation moves
on reads it here rather than timing the turns it saw.
max_tokensrequired integer | null
mcp_toolsrequired array of ThreadMcp The tool servers the thread's turns use; empty for a plain chat. A
thread with lmgw (the self-admin toolset) among them is listed for a
device key only when the device may use lmgw's admin tools.
media_defaultsrequired MediaDefaults The thread's own default models of the image and audio tools; an
absent field inherits its folder's, then Settings → Chat's, and an
empty one is no default (GET /chat/api/media/defaults says what
they resolve to).
min_prequired number | null
model_aliasrequired string The alias the thread's turns go to.
pinnedrequired boolean Pinned threads are listed first and are never archived or deleted
by the sweep.
presence_penaltyrequired number | null
profile_idrequired integer | null The personality profile the thread talks with
(GET /chat/api/profiles); null for none ("Default").
purge_atrequired string | null When an archived thread will be deleted; null while it is active,
pinned, or when deleting is switched off.
reasoning_budgetrequired integer | null
reasoning_effortrequired string | null
reasoning_enabledrequired boolean | null Reasoning overrides sent with every turn; null leaves the route's
default.
repeat_penaltyrequired number | null
seedrequired integer | null
stoprequired array of string Stop sequences; empty leaves the route's default.
system_promptrequired string
temperaturerequired number | null Sampling overrides sent with every turn; null leaves the route's
default.
temporaryrequired boolean The thread lives in memory only and is gone at the gateway's next
start unless it is kept.
titlerequired string
top_krequired integer | null
top_prequired number | null
updated_atrequired string Moves with every change to the thread and every new message.
voicerequired ThreadVoice

ThreadTask

One of a thread's tasks: still running, or ended with its result on its
way into the thread.

byrequired string | null Who started it ("the dashboard", "device 'phone'").
idrequired integer (int64) lmgw's id of the task: the cancel route's {task}.
server_labelrequired string
started_atrequired string When it started (UTC, YYYY-MM-DD HH:MM:SS).
statusrequired string working or input_required while it runs; completed, failed,
cancelled or abandoned once it ended. One of working, input_required, completed, failed, cancelled, abandoned.
status_messagerequired string | null The server's last word on it, when it gave one.
task_idrequired string The server's id of the task.
toolrequired string The name the model called.
ttl_msrequired integer | null How long the server keeps it, as it stated; null when it stated
none.
waiting_forrequired string | null What it waits for, when it waits: a device that is not connected
(its tasks are asked about again when it links), a turn of the
thread that runs (a result enters the thread once it ended), or the
decision on the calls the thread's last reply waits on.

ThreadVoice

A thread's own voice settings. Every field is optional and absent when
unset: an absent field takes the Chat's voice settings.

asr_alias string | null The speech-to-text alias for dictation, voice mode and audio
attachments.
audio_input AudioInputMode | null
language string | null The language the user speaks, a two-letter ISO 639-1 code, or auto
to let the speech-to-text model detect it.
read_aloud boolean | null Read every reply aloud as it streams.
reply_language string | null The language replies are in, a two-letter code, or auto to follow
the language the user speaks.
seed integer | null The thread's text-to-speech seed, so one thread keeps one voice on a
model that draws its voice. Set on first use.
speech_style string | null The speaking style the text-to-speech model is given; an empty text
is none for this thread.
tts_alias string | null The text-to-speech alias for read-aloud and voice mode.
turn_detection TurnDetectionMode | null
voice string | null A voice of that text-to-speech model.

ThreadsFate

What a folder delete does with the threads in the folder.

One of: string (The threads stay, in no folder.); string (The threads are deleted with the folder.)

Threshold

A question's threshold: an answer whose confidence (choice, score)
or certainty, max(p, 1 − p) (noul), is below it needs attention.

measuredrequired Measured | null Where the value was measured; null: not measured.
valuerequired number (double) From 0 to 1. 0 is "never needs attention", what an unmeasured
question has.

ThresholdInput

A question's threshold: an answer whose confidence (choice, score)
or certainty, max(p, 1 − p) (noul), is below it needs attention.

measured Measured | null Where the value was measured; null: not measured.
valuerequired number (double) From 0 to 1. 0 is "never needs attention", what an unmeasured
question has.

Timeline

The sampled timeline stored with a run.

interval_msrequired integer (uint64)
phasesrequired array of PhaseSpan
samplesrequired array of TimelineSample

TimelineSample

One stored sample (spaced interval_ms apart); sums over the devices,
temperature is the hottest one's.

clock_eventsrequired integer | null The OR of the NVML clock-event reason bits seen since the previous stored
sample.
power_wrequired number | null
t_msrequired integer (uint64) Since the sampler started.
temp_crequired integer | null
vram_used_bytesrequired integer | null

Timings

Server-measured prefill and decode timings of a local model: the stats
frame (live per token while it streams) and the done frame's final
timings.

cache_n integer (uint64) Prompt tokens served from the KV cache.
draft_n integer (uint64) Draft tokens proposed (speculative or MTP decoding).
draft_n_accepted integer (uint64) Draft tokens accepted.
predicted_ms number (double) Milliseconds spent generating; absent when llama.cpp gave no finite number.
predicted_nrequired integer (uint64) Tokens generated so far.
predicted_per_second number (double) Tokens generated per second; absent when llama.cpp gave no finite number.
prompt_ms number (double) Milliseconds spent on the prompt; absent when llama.cpp gave no finite number.
prompt_nrequired integer (uint64) Prompt tokens actually processed this turn (the cache excluded).
prompt_per_second number (double) Prompt tokens processed per second; absent when llama.cpp gave no finite number.

TimingsView

embed_msrequired number (double)
fetch_msrequired number (double)
fts_msrequired number (double)
fuse_msrequired number (double)
knn_msrequired number (double)
rerank_msrequired number (double)
total_msrequired number (double)

TokenizeRequest

Every key but model is forwarded to the backend's own /tokenize verbatim. Refused with 501 not_supported_error on any backend but a real llama-server — an id from a tokenizer the backend does not run would be a hidden approximation.

add_special boolean Default false.
content any A string, or a mixed array of strings and token ids.
modelrequired string Required: llama-server's router mode has no other way to pick a backend. A missing model is a 400 naming GET /v1/models.
parse_special boolean Default true.
with_pieces boolean Default false.

TokenizeResponse

tokensrequired any An array of integer token ids, or — with_pieces — an array of {id, piece} (piece a string, or a byte array when it is not valid UTF-8).

ToolArgsFrame

A fragment of a call's JSON arguments, in order.

fragmentrequired string
indexrequired integer (uint)

ToolCallCaps

Tool-calling support.

format string | null The native syntax family the template renders (qwen-xml,
hermes-json, …), provider for cloud, unknown when the template
renders tools with none of the known markers. Informational.
kindrequired string native (lmgw returns structured tool_calls), none (the template
renders no tools; aux/audio rows), text (the template renders tools
in a syntax llama-server has no parser for, so calls may arrive as
prose the caller must read itself).
parallel boolean | null The template can render more than one call per turn. Absent for cloud
models, which publish nothing about it.

ToolEntryView

One tool the gateway can serve, with its provenance and current state.

availablerequired boolean Offered right now: enabled **and** its source's condition holds.
descriptionrequired string | null
disabled_atrequired string | null
enabledrequired boolean The per-tool switch (POST /api/op/tool_set).
moved_fromrequired string | null The name it would have if no other source offered a tool of that
name: set when a collision gave it its server's name as a prefix.
moved_reasonrequired string | null Why it moved: who else claims moved_from, and whether that
claim is only a server's last listing (it is not connected now).
namerequired string Fully-qualified exposed name — the key the switch is stored under.
planerequired string
reasonrequired string | null Why not, when available is false.
server_idrequired integer | null
source_kindrequired string builtin | server.
source_labelrequired string
source_namerequired string
stalerequired boolean A disable record whose tool the gateway no longer offers.
upstream_namerequired string | null

ToolProgressFrame

The progress event of a tool frame: a running image or audio call's
stage, step and latest preview. Lossy: a reader that falls behind misses
some (the next one supersedes them), and they are not in the change
feed.

call_idrequired string The call's id, as its ready frame carries it.
cancel CancelKind What a cancel would do now, while an image job runs; absent before
the job exists (a cancel then just stops the wait) and for audio.
done_bytes integer (uint64) downloading: compressed bytes downloaded so far.
elapsed_msrequired integer (uint64) Since the call started.
free_bytes integer (uint64) waiting_for_room: the memory free when it was last measured.
image string downloading: the image reference being downloaded.
model string The model the phase is about: the one being unloaded for
unloading, the call's own otherwise.
needs_bytes integer (uint64) waiting_for_room: the memory the model needs, headroom included.
pass integer (uint32) The sampling pass (a batch item, a high- or low-noise stage, a hires
pass); a new pass starts its steps again.
phaserequired MediaPhase | null
preview string The latest preview as the image server drew it: base64, PNG. Its
pixel size depends on the row's preview mode (a quick sketch is the
latent's size, an eighth of the picture's side on the spike's
pipeline).
queue_position integer (uint32) queued: the job's place in the image server's queue.
size_note string downloading: why the size is not known, when it is not ("size not
known — …").
step integer (uint32)
total_bytes integer (uint64) downloading: the download's whole size; absent when it is not
known.
total_steps integer (uint32)

ToolReadyFrame

A Chat tool frame whose event is ready (also the data of a bound
realtime session's lmgw.chat.frame for it): a call's arguments are
complete, before it runs — what a host that shows the call's view at once
needs (client-apps design §7.5).

argumentsrequired any The call's arguments.
call_idrequired string | null The call's id, as its result frame carries it.
indexrequired integer (uint) The call's position in its turn.
namerequired string The tool's exposed name, as the model called it.
needs_approvalrequired boolean | null The call waits for an approval and does not run now: an approval
frame follows. false for a call that runs (a resumed turn's decided
calls included). Absent from an lmgw before 2026-10-09.
server_labelrequired string | null The label the tool came from; null for a client's own function.
ui_resourcerequired string | null The UI resource the tool links to, as on the result frame.

ToolResultFrame

A Chat tool frame whose event is result (also the data of a
bound realtime session's lmgw.chat.frame for it), as an MCP Apps host
reads it. MCP's CallToolResult for the view is {content,
structuredContent: structured_content, isError: is_error}
.

attachments array of AttachmentMeta The files the call stored in the thread — an image or audio tool's
pictures and recordings in a Chat turn — so a page shows them
without reading the thread again. Their bytes are at
GET /chat/api/attachments/{id}; content names them as
lmgw:attachment/N resources. Empty for every other call.
call_idrequired string | null The call's id, as its ready frame carries it.
contentrequired array | null The MCP result's content blocks as the server sent them (resource
URIs namespaced as /mcp sends them; images in full — no bound of
lmgw's own, a device's result is bounded by mcp.host_max_message_mb
on its link); a tool lmgw runs itself, or a call that never reached
a server, says its result in the same shape. Absent from an lmgw
before 2026-10-09: output as one text block then.
indexrequired integer (uint) The call's position in its turn.
is_errorrequired boolean
msrequired integer (uint64)
namerequired string The tool's exposed name (<prefix>__<tool>).
outputrequired string The result as text.
server_labelrequired string | null The label the tool came from: a server's tool prefix (else its
name), or a built-in toolset's (lmgw, docs, kb).
structured_contentrequired any The MCP result's structuredContent, for the view. The model was
given it only when content is empty.
task ResultTask For a call that started an MCP task: which. Absent otherwise.
ui_resourcerequired string | null The UI resource the tool links to (_meta.ui.resourceUri),
namespaced as /mcp serves it: resources/read it there.

ToolSourceView

One source of tools, so a source that currently offers none (a disabled
server, self-admin off, a server that has not connected) is still visible
with the reason: the per-tool rows cannot carry that.

availablerequired boolean
disabled_countrequired integer (int64) How many of those the owner has switched off.
kindrequired string builtin | server.
labelrequired string The label a thread or a {"type":"mcp"} block attaches: lmgw, docs,
or a server's prefix/name.
namerequired string
planerequired string /mcp or /mcp/admin.
reasonrequired string | null
server_idrequired integer | null
tool_countrequired integer (int64) Tools this source contributes to the inventory right now.

ToolStartFrame

A tool call starting to stream: its position and name.

id string The model's id of the call; only a turn without tools says it.
indexrequired integer (uint) The call's position in its turn.
namerequired string The tool's exposed name.

TranscribedClip

One clip voice_transcribe wrote a transcript for.

answered_byrequired string | null The fallback alias that answered in place of the one asked, else null.
byrequired string Who wrote it, in a sentence.
charsrequired integer (uint) The transcript's length in characters.
cliprequired string The clip's file name.
fallback_reasonrequired string | null Why the fallback answered (hold, external_vram, ...), else null.
transcript_sourcerequired string asr:<model>: the model the transcript came from. When a fallback
answered, that model's name.

Transfer

A transfer, as every route and transfer.updated answer it.

app_idrequired string The app id the offer names; the receiver declared it at pairing.
created_atrequired string RFC 3339 UTC.
end_reasonrequired string | null Why it ended, a sentence for people ("not delivered within 7 days of
the offer", "canceled by device 'phone'"), naming no setting and no
raw time; null while in progress and once delivered. state is
what a client acts on.
ended_atrequired string | null When it ended (RFC 3339 UTC); null while in progress.
expires_atrequired string When it expires unless delivered first (RFC 3339 UTC):
devices.transfer_expiry_days after the offer.
filenamerequired string The receiver's name for the file.
fromrequired TransferParty
idrequired string Opaque: 32 random lowercase hex digits.
kindrequired string The app's own word for what the file is.
receivedrequired integer (uint64) Bytes lmgw holds: the resume point while uploading (the next
upload's range starts here), size from ready on, and how far it
got for one that ended before.
sha256required string The file's sha256, 64 lowercase hex digits; checked when the last
byte arrives.
sizerequired integer (uint64) The file's size in bytes.
staterequired TransferState
titlerequired string What the card and the receiver show; may be empty.
torequired TransferParty

TransferParty

One side of a transfer: the device by its key id, as the owner's
KeyRow shows it, and its paired name without device:, as it was when
the offer was made.

device_idrequired integer (int64)
namerequired string

TransferRole

GET /transfers/api/transfers' role (a device's).

One of: string (Offered to the caller (from ready on).); string (Offered by the caller.)

TransferState

A transfer's state (§1).

One of: string (Offered; the sender uploads its bytes. The receiver does not see it.); string (Every byte arrived and its sha256 matched: offered to the receiver.); string (The receiver said it got the bytes; they are deleted.); string (The receiver declined it; the bytes are deleted.); string (The sender or the owner canceled it, or a party device was disabled
or deleted; the bytes are deleted.); string (Not delivered by expires_at; the bytes are deleted.); string (The uploaded bytes' sha256 was not the offer's; they are deleted.)

TurnDetectionMode

How voice mode detects the end of the user's turn.

One of: string (A turn model decides when the speaker is done.); string (Silence windows only.); string (A turn is what is spoken while the talk key is held.)

UnpricedHostedTool

Traffic a hosted tool's fees left unpriced (openai egress design §6.1): a
native /v1/responses answer whose upstream ran a tool that bills beyond
its tokens (web search, file search, a code-interpreter container, image
generation). lmgw has no price unit for those fees yet, so such a row
costs nothing anyone can name and counts toward no budget; no price row
fixes it. Read from the request log, so its retention bounds how far back
requests reaches.

callsrequired array of HostedCallCount Each billable call's output item type (web_search_call, …) with how
many of them those requests made.
namerequired string The alias the requests asked for.
requestsrequired integer (int64) Requests left unpriced for their hosted calls, since since.
scope_keyrequired string The upstream model that answered: <upstream_id>:<upstream_model_id>.
sincerequired string When the first of them was logged (UTC, YYYY-MM-DD HH:MM:SS).

UnpricedModel

One model that resolves to no price at all — an entry on the "why is my
spend incomplete" worklist.

requests is what it has already cost that nobody can name, from the
rollup. A configured alias that has never been called is still listed, at
0: it is about to be the same problem.

namerequired string
requestsrequired integer (int64)

UnpricedTier

Traffic an OpenAI service tier left unpriced: a model that answered at a
tier it has no price row for (openai egress design §5.6). It counts
toward no budget until a row of that tier is entered. Read from the
request log, so its retention bounds how far back requests reaches.

missing_unitsrequired array of string The units (per_mtok, …) the row to enter has to price: those with
a row at another tier and none at this one. Empty with no tier.
namerequired string The alias the requests asked for.
reportedrequired string What the answers reported when that names no price tier: auto, or
empty for an answer that named none. Empty beside a service_tier.
There is no price action for such a group; it is listed so the
unpriced traffic can be found.
requestsrequired integer (int64) Requests answered at that tier and left unpriced, since since.
scope_keyrequired string The price scope a row for it would take: the alias, or
<upstream_id>:<upstream_model_id>.
scope_kindrequired string
service_tierrequired string The price tier with no row (flex, fast, …). Empty when the
answers reported no tier a row can be entered for (reported).
sincerequired string When the first of them was logged (UTC, YYYY-MM-DD HH:MM:SS).

UpdateStatus

A build's update badge state: the result of the periodic (or
"Check now") comparison of the resolved ref and extras against the last
verified run.

Some on a build view once the build has been checked against a run it
can be compared with; None before its first check, and for a build with
no succeeded (or unverified) run. A status with no reasons is **up to
date as of checked_at** — has_update is what the Engines nav
badge counts. What could not be checked is in errors, never in reasons:
a rate-limited forge is not an update.

The server re-evaluates the stored remote facts against the build and its
runs on every read, so a run that builds the new head clears "master moved"
at once, and an edit shows "definition changed since last run" at once —
neither waits for the next check.

checked_atrequired string When the remote facts behind this status were fetched (RFC 3339).
errorsrequired array of string What the check could not find out, one sentence each, starting
check failed: — a forge's rate limit (with its reset time), a remote
that did not answer, a ref that no longer exists. Shown, never counted
as an update.
extrasrequired array of ExtraChange
reasonsrequired array of string Human sentences, one per reason ("master +37 commits",
"master moved (abc1234 → def5678)" when the count is not known
without fetching, "PR #1234 pushed", "PR #1234 closed unmerged",
"definition changed since last run (ref, extras)"). A PR the forge
reports merged reads "PR #1234 merged upstream and contained in your
base — drop it"
only once the base is proven (locally, no fetch) to
already hold its merge or head commit; otherwise "PR #1234 merged
upstream at <date>; your base doesn't contain it yet — it's still
merged into your build"
— the same non-committal wording whether that
was proven false or is simply unknown.
ref_movedrequired boolean The base ref itself moved (a branch or tag; a pinned commit never
updates).

UploadChoice

Another upload of the card's model.

downloadsrequired integer (uint64)
gatedrequired boolean
likesrequired integer (uint64)
plainrequired boolean A plain upload (the original's name, D16); a renamed one (an MTP
variant, an abliterated one) when false.
privaterequired boolean
reporequired string

UploadItem

One uploaded file's fate.

filerequired KnowledgeFile | null The stored file; absent for a refused one.
namerequired string The name the part carried.
outcomerequired UploadVerdict
reasonrequired string | null Why it was not added, or what it replaced.

UploadVerdict

What became of one uploaded file.

One of: string (Stored and queued for ingest.); string (A file of that name existed; its content was replaced and queued again.); string (The same name with the same bytes: nothing to do.); string (The same bytes already in the base under another name.); string (Not stored; reason says why (images and audio are refused, as is an
empty or unreadable file).)

UpstreamChain

One remote upstream's exposure path.

aliasesrequired array of string Enabled explicit aliases pointing at this upstream.
enabledrequired boolean
expose_allrequired boolean Whole catalog passed through under prefix.
idrequired integer (int64)
namerequired string
prefixrequired string
protocolrequired string openai | anthropic | gemini.

UpstreamLlamaFacts

What an external llama.cpp server said about itself, or a router about
one model (GET /props). Asked in the
background, one probe per row at a time, and kept until the row is
edited, unreachable, refuses a medium or is tested.

base_urlrequired string The base URL it was asked at.
cachedrequired boolean The answer stands until an event drops it. false for a probe that
found nothing worth keeping (a router that has not loaded the model,
a server that did not answer): it is asked again on the next use.
modelrequired string Empty for the server itself: a llama-server that is no router serves
one model whatever a request names, so its facts hold for every model
of the row. Under a router, the upstream model this entry is about,
as the row's aliases (or an expose_all request) name it.
probingrequired boolean Being asked now, or waiting for the row's probe.
propsrequired LlamaProps | null The facts, when the server stated them: its build, one slot's
context and its modalities. None is unknown; unknown says why.
read_atrequired integer | null Unix seconds of the answer shown; None while the first is on its way.
routerrequired boolean The server is a llama-server router (only on the entry with an empty
model): it states its build and nothing about a model, so props
carries the build alone, and the facts are on the per-model entries.
Defaulted, so a gateway older than the field still parses.
unknownrequired string | null Why the facts are unknown: the server's own answer (an old build's
404, a 401), or why the last probe found nothing.

UpstreamModelEntry

One entry of an upstream's live catalog (catalog::ModelInfo), including
the entries hidden from /v1/models — which is why the dashboard reads
this rather than /v1/models. Every field the catalog does not publish is
None: unknown, never a default.

context_lengthrequired integer | null
createdrequired integer | null Unix seconds.
idrequired string Bare, as the upstream names it (no expose prefix).
input_modalitiesrequired array | null
max_output_tokensrequired integer | null
price_completionrequired string | null
price_promptrequired string | null USD per token, the upstream's verbatim decimal string.
reasoningrequired string | null levels | toggle | fixed.
reasoning_enabledrequired boolean | null Whether it thinks by default, where the catalog says — what tells a
fixed model that always reasons from one that never does.
taskrequired string | null chat | embedding.
toolsrequired boolean | null

UpstreamPriceSync

What a price sync did to one upstream.

errorrequired string | null The catalog fetch failed; nothing was synced for this upstream. Not
fatal to the run as a whole — one unreachable provider should not stop
every other upstream's prices from refreshing. null when it was
asked.
not_syncedrequired object Per field of the catalog's pricing object, how many models had their
token prices synced here and publish that field with a value other
than zero that went into no row. Left out on purpose: image (a
price per *input* image, not a generated one),
web_search (no route carries a hosted search), and the fields lmgw
does not model, such as internal_reasoning, image_output,
overrides or discount. Also a request fee or cache rate that is
not a price ("-1", unparseable). A model counted in
unpriced_models had nothing synced and is not counted here again.
Empty when nothing published was left out.
rows_removedrequired integer (uint) Catalog per_request rows deleted because their model, priced here,
no longer publishes a request fee at all.
rows_writtenrequired integer (uint) Rows created or updated: one per_mtok row per priced model and
scope, and a per_request row beside it where the catalog states a
fee.
unpriced_modelsrequired integer (uint)
upstreamrequired string
upstream_idrequired integer (int64)

UpstreamQuota

What lmgw remembers of an upstream's exhausted quota (openai egress
design §14.6). In memory: a restart forgets it.

coderequired string | null The provider's code (insufficient_quota,
credit_balance_exhausted, …), when it sent one.
messagerequired string The provider's message, verbatim.
next_checkrequired integer (int64) Unix seconds of the next check: the next request after it goes to
the upstream again. The upstream's Retry-After when it sent one,
otherwise quota_recheck_seconds after the answer.
sincerequired integer (int64) Unix seconds of the first quota answer since it was last clear.

UpstreamQuotaStatus

An upstream lmgw remembers out of quota, as GET /api/status lists it.

idrequired integer (int64)
namerequired string
quotarequired UpstreamQuota

UpstreamView

base_urlrequired string
catalog_all_modalitiesrequired boolean The catalog request asks for every output modality
(GET …/models?output_modalities=all), so OpenRouter lists its
decision, embedding, rerank, speech, transcription, image and video
models too. Only an openai_compatible row of kind generic sends
it; on by default, off for an endpoint that refuses it (Gemini's
OpenAI-compatible one).
enabledrequired boolean
expose_allrequired boolean
expose_prefixrequired string
extra_headersrequired array of array Names only; values are redacted server-side.
has_api_keyrequired boolean
host_noterequired string | null Set on an openai row whose host is not api.openai.com or a
regional *.api.openai.com one: lmgw sends it the OpenAI platform's
own dialect, which another provider may refuse. The same note the
write and the Test answer with. None on every other row.
idrequired integer (int64)
kindrequired string generic | llama_server | audio_cpp. llama_server goes with
protocol llama_cpp or anthropic; audio_cpp (an external
audio.cpp server) with openai_compatible.
llama_factsrequired array of UpstreamLlamaFacts A llama_cpp row's server: what GET /props said, when, or why it
is unknown — one entry for the server, and for a router one more per
model (its model). Empty on every other protocol,
and on a llama_cpp row until a chat request or its Test makes lmgw
ask in the background.
namerequired string
protocolrequired string openai | openai_compatible | anthropic | gemini | llama_cpp.
openai is the OpenAI platform (api.openai.com) only and always kind
generic; openai_compatible is every other OpenAI-shaped provider.
llama_cpp is llama.cpp's own server (llama-server, ik_llama.cpp) and
is always kind llama_server.
quotarequired UpstreamQuota | null Set while lmgw remembers the row out of quota (openai egress design
§14.6): its account answered insufficient_quota, so models and
aliases on it that have a fallback answer with the fallback until
the next check. None otherwise.
supports_responsesrequired boolean /v1/responses is forwarded to it natively rather than synthesized
from /v1/chat/completions. A choice on openai_compatible rows only:
implied on openai, and false on every other protocol.
timeout_msrequired integer (uint64)

UsageCell

One (bucket, series) cell.

Money is integer **micro-units** of the configured currency everywhere on
this plane; a float that has been through JSON twice does not add up.

audio_in_msrequired integer (int64) What the requests processed besides tokens, as **measured** or
reported by the provider: input audio in milliseconds, input
characters, generated images. A request that measured nothing adds 0,
so these are measured totals, and before the series' units_since
nothing was recorded at all.
bucketrequired string Local-time bucket label: 2026-09-18, 2026-09-18T14, 2026-W38, 2026-09.
cache_nrequired integer (int64)
chars_inrequired integer (int64)
cost_microrequired integer (int64)
cost_unknown_audio_in_msrequired integer (int64) The same quantities of the requests cost_unknown_requests counts,
so the remainder can say what it holds beside its tokens.
cost_unknown_chars_inrequired integer (int64)
cost_unknown_images_outrequired integer (int64)
cost_unknown_requestsrequired integer (int64) What cost_micro does **not** cover. Every total that is displayed is
obliged to show this beside it — a cost figure with a
silent hole in it is worse than no cost figure.
cost_unknown_tokensrequired integer (int64)
decode_msrequired number (double)
decode_tokensrequired integer (int64) Local-model throughput as a ratio pair: tok/s is Σtokens / Σms, never a
mean of per-request rates.
draft_acceptedrequired integer (int64)
draft_nrequired integer (int64)
errorsrequired integer (int64)
images_outrequired integer (int64)
prefill_msrequired number (double)
prompt_nrequired integer (int64)
refusalsrequired integer (int64)
requestsrequired integer (int64)
seriesrequired string The series key this cell belongs to ("" when ungrouped).
tokens_cache_writerequired integer (int64) Input written *into* the prompt cache — Anthropic's 1.25x tier, the
dearest input a window can contain. Zero everywhere else, because no
other provider bills a cache write.
tokens_cachedrequired integer (int64) Input served from the provider's prompt cache, billed at the cheap
read rate.
tokens_inrequired integer (int64) **Total** input, cache included — the same meaning ir::Usage's
prompt_tokens carries, so fresh (uncached) input is
tokens_in - tokens_cached - tokens_cache_write and never a fourth
stored number that could drift from the other three.
tokens_outrequired integer (int64)
tokens_reasoningrequired integer (int64)
total_countrequired integer (int64)
total_sumrequired integer (int64)
ttfb_countrequired integer (int64)
ttfb_sumrequired integer (int64)

UsedBy

What uses a profile, computed when it is read: what a delete would
clear.

foldersrequired array of FolderRef Folders whose defaults name it.
threadsrequired integer (int64) Stored threads that picked it, archived ones included.

Variant

What a cell sends: the form as written, or one of the two perturbations
(labs-store design §2.6).

One of: string; string (Every choice description null, and no noul criteria.); string (Each choice question's options in reverse.)

Verdict

How one metric moved (by the regression rule).

One of: string; string (Within the band: max(threshold, noise).); string (One of the two runs did not measure it.); string (Both runs measured it, but at different points — another prompt
length, depth or stream count, as when one run stopped early. The delta is kept as
information; it is no verdict, so
it counts neither as a regression nor as an improvement.)

VoiceCandidate

One rendered candidate.

bytesrequired integer (uint64)
duration_msrequired integer | null Its length, read from its WAV header; None for audio that is no
PCM WAV.
indexrequired integer (uint32) Its number in the round, from 1.
mimerequired string Its content type (audio/wav).
seedrequired integer | null The seed it was sent; None when no seed reached the model.
urlrequired string Where it plays: GET this path.

VoiceClipFailed

One clip voice_transcribe could not transcribe.

cliprequired string
errorrequired string Why.

VoiceDescriptionMode

What a text-to-speech model does with a voice description (the speech
route's instructions) — capabilities.speech.instructions.

One of: string (Not read: a description would be dropped on the way.); string (A speaking style for the voice it speaks.); string (The voice is designed from it.); string (Sent; the model decides what it does with it (OmniVoice designs a
voice from it, a cloud model nobody described reads it as it reads
instructions).)

VoiceModels

The models one spoken turn went through.

asrrequired ServedModel | null
chatrequired ServedModel | null
ttsrequired ServedModel | null

VoiceName

The voice the text-to-speech model is asked for.

inheritsrequired string | null Settings → Realtime's default voice, when no name is named: applied by
voice mode, never sent as the voice.
namerequired string | null The voice to ask for; null: none is named, and voice mode's own
chain decides.
noterequired string | null Why a voice set at a less specific level is not used here.
sourcerequired VoiceSource | null Where name came from. With no name, realtime when Settings →
Realtime's default voice is where that chain starts, else null.

VoiceProblem

Something that blocks a voice feature.

coderequired string not_configured, unresolved, or voice_needs_transcript (a voice
clip the text-to-speech model cannot clone without its transcript).
messagerequired string
stagerequired string asr or tts.

VoiceProvenance

How a sample was made: kept beside the library by the Voices lab, and
shown with the clip. "Regenerate" refills the lab's form from it — GPU
output is not bit-identical per seed, so it makes a new candidate rather
than restoring this one.

aliasrequired string The alias asked.
answered_byrequired string The alias that answered (a fallback named as one).
asked_textrequired string | null What the round asked it to say, when lmgw's speech shaping sent the
engine something else (text). Regenerate asks this again.
candidaterequired integer (uint32)
descriptionrequired string | null
fallback_reasonrequired string | null
generated_atrequired string The round's time, RFC 3339.
languagerequired string | null
licencerequired ModelLicence | null The licence the answering row's package states, when known.
roundrequired string The round and the candidate it came from.
rowrequired VoiceRow | null The lmgw audio row behind the answering route.
saved_atrequired string The save's time, RFC 3339.
seedrequired integer | null The seed the candidate was sent, when one reached the model.
sha256required string The saved clip's SHA-256, hex: a clip replaced by other means no
longer matches it.
textrequired string What the clip says: its transcript — the text the engine was sent.
trimrequired VoiceTrim
upstreamrequired string
upstream_modelrequired string
voicerequired string | null

VoiceResolved

A thread's voice, resolved.

asrrequired Stage The speech-to-text stage: dictation, voice mode, audio attachments.
audio_inputrequired AudioInputShown | null Whether a voice turn goes to the chat model as audio, and why not.
languagerequired Sourced_Nullable_string The language the user speaks, ISO 639-1; value: null is none, the
speech-to-text model detects it.
language_notesrequired array of LanguageNote Where a stage's model does not take its language as set.
problemsrequired array of VoiceProblem What blocks a voice feature now: a stage with no alias, or one whose
alias no longer resolves.
read_aloudrequired Sourced_boolean Whether replies are read aloud as they stream.
realtimerequired RealtimeAvailability Whether voice mode may bind the thread.
reply_languagerequired Sourced_Nullable_string The language replies are in, ISO 639-1: the thread's, Settings', else
the spoken one (source: speech_in); value: null is none, the reply
follows the user.
seedrequired integer | null The thread's text-to-speech seed; null until its first use draws
one.
speech_stylerequired SpeechStyle The speech instructions the read-aloud uses.
ttsrequired Stage The text-to-speech stage: read-aloud and voice mode.
turn_detectionrequired Sourced_TurnDetectionMode How voice mode detects the end of a turn.
voicerequired VoiceName The voice the text-to-speech model is asked for.

VoiceRound

One round: what was asked, who answered, and its candidates.

aliasrequired string The alias asked.
answered_byrequired string The alias that answered: alias, or the fallback the GPU hold (or a
busy card) handed the round to.
askedrequired integer (uint32) How many candidates were asked for.
candidatesrequired array of VoiceCandidate
created_atrequired string RFC 3339, UTC.
descriptionrequired string | null
fallback_reasonrequired string | null Why a fallback answered (hold, external_vram, …).
idrequired string The round's id, its directory's name.
languagerequired string | null
language_noterequired string | null What happened to the language when it did not reach the model as
set.
licencerequired ModelLicence | null The licence the answering row's package states, when it states one.
rowrequired VoiceRow | null The lmgw audio row behind the answering route, if it is one.
seeds_sentrequired boolean Each candidate's seed reached the model.
sent_textrequired string | null What the engine was sent instead, when lmgw's speech shaping changed
it (inline tags or characters the engine cannot say): what the
candidates say, and the transcript a saved sample gets.
shapingrequired string | null What lmgw's speech shaping changed in the request
(x-lmgw-speech's words), when it changed anything.
stoppedrequired string | null Why the round ended before asked candidates: the first failure,
or a stop (the page left, Stop, the round discarded).
textrequired string What every candidate was asked to say.
upstreamrequired string The upstream that answered.
upstream_modelrequired string The model name it was sent.
voicerequired string | null

VoiceRow

The lmgw audio row behind a route.

familyrequired string The audio.cpp family (qwen3_tts).
model_idrequired string The row's model id.
variantrequired string | null The package's variant when it says (voice_design).

VoiceSample

One library clip with how it was made, when the Voices lab made it.

cliprequired Clip
provenancerequired VoiceProvenance | null The Voices lab's record of it; None for a clip it did not make.
provenance_currentrequired boolean The record still describes the file (its SHA-256 matches). false
with a record: the clip was replaced since, by an upload or by hand.

VoiceSentence

One language of the sentence table: the built-in sentence, the owner's
own when saved, and the short line the cloning check speaks.

builtinrequired string | null The built-in sentence; None for a language the table lacks, which
only an owner's sentence brings into the list.
check_linerequired string The built-in line the cloning check speaks; empty without one.
languagerequired string ISO 639-1 code, lowercase (en).
namerequired string The language's English name (German), or the code for one lmgw
has no name for.
savedrequired boolean text is the owner's own sentence, saved for this language.
textrequired string The sentence in effect: the owner's saved one, else the built-in
one, else empty.

VoiceSource

The level a value came from.

One of: string (The thread's own override.); string (The thread's personality profile.); string (Settings → Chat → Voice.); string (Settings → Realtime.); string (The text-to-speech model's own description of its voice (a speech
style only).); string (The reply language only: none is set for it, so it is the language the
user speaks.)

VoiceTiming

A spoken reply's timing: each stage measured from the one before,
to_first_audio_ms their sum from the end of speech, cold the stages
that loaded during the turn.

asr_msrequired integer | null
coldrequired array of string The stages that loaded during the turn.
end_of_turn_msrequired integer | null
first_audio_msrequired integer | null
first_clause string announcement when the first clause said was an announcement of a
skipped block.
first_clause_msrequired integer | null
first_token_msrequired integer | null
input InputPath How the turn reached the chat model; absent with audio input off.
input_why string Why the transcript went where audio input is on.
message_idrequired integer | null
modelsrequired VoiceModels
reasoning_ms integer (uint64) How long the chat model reasoned before its first token (part of
first_token_ms); absent when it did not reason.
response_idrequired string | null
to_first_audio_msrequired integer | null
total_msrequired integer | null
transcript_wait_ms integer (uint64) How long the first output was held for the turn's transcript; absent
on the transcript path.

VoiceTrim

What trimming took off a saved sample. Only silence is cut; the samples
kept are the candidate's own, at their own loudness.

kept_msrequired integer (uint64) What is left.
lead_msrequired integer (uint64) Silence cut from the start, in milliseconds.
noterequired string | null Why nothing was cut, when nothing could be (not a PCM WAV, nothing
above the silence floor).
tail_msrequired integer (uint64) Silence cut from the end.

VramBenchmark

A benchmark run's GPU lease.

model_idrequired string
run_idrequired integer (int64)

VramDevice

free_bytesrequired integer (uint64)
indexrequired integer (uint32)
namerequired string
total_bytesrequired integer (uint64)
used_bytesrequired integer (uint64)

VramEstimate

The GPU cost of the weights and the KV cache at the trained context; a
chat model's is laid out as its row is charged, for one slot. Compute
buffers depend on a row's settings and are in the plan's footprint, not
here.

kv_cache_bytes_at_full_ctx_f16required integer | null KV cache for context_length tokens at f16; null when the header
lacks what the estimate needs.
kv_cache_bytes_at_full_ctx_q8_0required integer | null The same at q8_0.
noterequired string What the figures leave out.
weights_bytesrequired integer (uint64)

VramKeptFree

What admission keeps free on top of the memory in use: memory the driver
cannot show yet. Each part is zero when nothing of that kind is kept.

image_peak_bytesrequired integer (uint64) What resident image pipelines take above their idle residency while
they draw (the residents' peak_extra_bytes).
pending_load_bytesrequired integer (uint64) What ready audio containers will still load on their first request
(the residents' pending_bytes).
starting_bytesrequired integer (uint64) Containers still starting, and starts admitted whose container is not
up yet: weights on their way onto the card.

VramKvPool

One guarded model's shared KV pool.

capacity_tokensrequired integer (uint64) The pool's size in tokens, as the running container was started
with it.
in_flightrequired integer (uint)
modelrequired string
queuerequired array of VramKvPoolWaiter Requests waiting for room, head first.
releasingrequired integer (uint) Requests that ended without a normal completion and keep their
reservation until llama-server lets go of their slots.
reserved_tokensrequired integer (uint64) Σ (prompt + max output) of the requests in flight and releasing.

VramKvPoolWaiter

One request waiting for room in a pool.

aliasrequired string
needs_tokensrequired integer (uint64)
positionrequired integer (uint)
waiting_msrequired integer (uint64)

VramResident

containerrequired string chat | aux | audio.
estimated_bytesrequired integer (uint64)
idle_secondsrequired integer | null
in_flightrequired integer (uint)
modelrequired string
noterequired string | null
peak_extra_bytesrequired integer | null What one generation of a resident image pipeline has been measured to
need *above* its idle residency, and what admission keeps free for it. None for every
other class, and for an image
model that has not generated anything yet — note says which.
pending_bytesrequired integer | null What a ready audio container will still load on its first request,
kept free by admission on top of the measured use: its expected
residency less what its processes hold now, else less what it was
read holding at rest, or all of it where neither could be read.
None once loaded (lmgw routed a request that loaded it, or its
processes hold at least that much now), and for every other class.
staterequired string starting | ready as the runtime registry holds it, or reserved for
a start the scheduler has admitted whose container is not up yet.

VramSettingsDto

The GPU admission (VRAM) settings.

budget_mbrequired integer (uint64) 0 = the device's real total, as the driver reports it (NVML on
NVIDIA, amdgpu sysfs on AMD).
enabledrequired boolean
fallback_on_externalrequired boolean Fall back when VRAM outside lmgw's control is short. Absent reads as on, like the server's
own default.
headroom_mbrequired integer (uint64)
load_timeout_secondsrequired integer (uint64)
queue_timeout_secondsrequired integer (uint64) 0 = wait indefinitely.
unload_timeout_secondsrequired integer (uint64)

VramSettingsPatch

VRAM admission control. Every field is optional so one knob moves
without restating the rest.

budget_mb integer | null Default null.
enabled boolean | null Default null.
fallback_on_external boolean | null Fall back when VRAM outside lmgw's control is short. Default null.
headroom_mb integer | null Default null.
load_timeout_seconds integer | null Default null.
queue_timeout_seconds integer | null Default null.
unload_timeout_seconds integer | null Default null.

VramStatus

GET /api/vram and the vram SSE frame — measured figures and
estimated ones are separate fields on
purpose: the UI must be able to say which is which.

activerequired boolean Whether admission is actually arbitrating; false is explained by
inactive_reason.
benchmarkrequired VramBenchmark | null The benchmark run holding the card, if one does: no local model is admitted until it ends.
capacity_bytesrequired integer (uint64)
devicesrequired array of VramDevice
downloadingrequired array of VramWaiter Starts whose model's engine image is still downloading (machine-check
design §5), oldest first: each phase is downloading with the bytes
so far. They hold no place in queue and nothing on the card; once
its download is done a start is admitted like any other, and enters
queue if it has to wait for room. Absent from an older gateway's
frame.
drainingrequired array of string Resident model ids that are busy or still starting while hold is
active — visible continuously, not only in the one-shot hold_set
response. Empty whenever hold is not active.
enabledrequired boolean
estimated_resident_bytesrequired integer (uint64)
external_trigger_activerequired boolean Whether the outside-VRAM fallback can fire right now.
external_trigger_reasonrequired string | null Why it cannot, when it cannot (the switch, admission, the hold, no
telemetry, an unattributable lmgw model).
free_bytesrequired integer | null
free_measuredrequired boolean False when free_bytes was derived from the estimate rather than read
from the driver.
headroom_bytesrequired integer (uint64)
hold_activerequired boolean The hold.active setting — hold is a switch on
the resolve/start paths, orthogonal to enabled/active above.
inactive_reasonrequired string | null
kept_freerequired VramKeptFree What free_bytes was lowered by on top of the memory in use, by
reason. With a measured free figure, free_bytes is the capacity's
measured free memory — the devices' free memory, or with
vram.budget_mb the budget less the devices' used memory — less
these (never below zero). The devices' total less their used and free
memory is in neither: memory the probe reports as not available
(NVML: the driver's own reserve; an AMD APU: GTT the host's RAM
cannot back).
kv_poolsrequired array of VramKvPool The token ledger of every guarded unified-KV chat model with a request
in flight or waiting — vram::VramView's
kv_pools. Absent from an older gateway's frame, hence the default.
lmgw_share_bytesrequired integer | null lmgw's own share of the pooled devices' used memory, measured per
process. None when it
cannot be measured — see external_trigger_reason.
noterequired string
outside_share_bytesrequired integer | null Used memory that is not lmgw's — games, the desktop, other apps.
None exactly when lmgw_share_bytes is.
queuerequired array of VramWaiter
residentrequired array of VramResident
telemetryrequired string Where the measured numbers come from, verbatim.
telemetry_okrequired boolean

VramWaiter

aliasrequired string
containerrequired string
modelrequired string
needs_bytesrequired integer (uint64) Footprint plus headroom; 0 for an entry of downloading, whose
footprint is read at admission, after the download.
phaserequired WaitPhase | null stage typed: what admission is doing for this request now. Absent
from an older gateway's frame.
positionrequired integer (uint) The 1-based place in the admission queue; 0 for an entry of
downloading, which holds no place in it.
stagerequired string
waiting_msrequired integer (uint64)

WaitPhase

What admission is doing for a request that waits for room on the GPU
(chat-media-tools design §5.3), told apart by kind.

One of: object (The model's engine image is not on this machine yet and is being
downloaded (machine-check design §5), before admission: nothing is
evicted or reserved for it meanwhile, and the queue's time budget
starts after it. done_bytes of total_bytes compressed layer bytes
as Podman reports them; total_bytes is absent when the size is not
known (no registry manifest, or Podman's API was not reachable and
the podman pull command reports no byte counts — done_bytes then
stays 0), and size_note then says why.); object (Waiting for the admission gate: another request is being admitted.); object (Measuring the GPU's memory.); object (Stopping an idle model to make room: <class>/<model>
(chat/qwen3-30b).); object (Nothing idle is left to stop: waiting for a busy model to finish, or
for memory held outside lmgw.); object (Room is there: the container is starting.)

WaitReason

Why a file of a get waits with nothing transferring it (WP7, D108),
read from its download row.

One of: string (Paused on a metered connection (D122): it goes on once the
connection isn't metered, or with Resume on the Downloads page.); string (Queued, or cut by a shutdown, and nothing transfers it yet.); string (The download row keeps another note: note says it.)

WebRtcCallState

Where a call stands (calls design §3.4).

One of: string (Answered: waiting for ICE and DTLS.); string (ICE and DTLS-SRTP are up; oai-events has not opened.); string (oai-events is open; the bind runs.); string (takeover=ask found its thread held: it waits for the client's
lmgw.session.take_over or the holder's end (held_by).); string (Its session runs.); string (It let go: its slot is back, and it only delivers its last events
before it closes, at most realtime.ping_interval_s.)

WebRtcCallStatus

One live call (calls design §3.4, §9).

allowance_msrequired integer | null The playout allowance in ms (calls design §5.3): NetEQ's part of the
delay, which the window's end, drained and a barge-in's heard take.
null before the call's audio out runs.
allowance_sourcerequired PlayoutSource | null Where the allowance comes from.
candidaterequired string Its one host candidate: the local address its POST arrived on, on
its group's UDP port.
client_jitter_msrequired number | null The client's interarrival jitter on lmgw's stream, by its latest
receiver report, in ms (to 0.1); null while closing.
connected_atrequired string | null When ICE and DTLS connected (RFC 3339 UTC); null before.
egress_lossrequired number | null The share of lmgw's packets the client lost, 0 to 1, by its latest
receiver report (to 0.001); null while closing.
grouprequired WebRtcGroup The socket group it lives on: the listener its POST came in on.
held_byrequired string | null Who holds its thread while it is pending, as voice.bound.by
names a client.
idrequired string Its id, rtc_…: what POST /v1/realtime/calls/{call_id}/hangup
takes.
ingress_lossrequired number | null The share of the client's packets lmgw lost over the last second, 0
to 1 (to 0.001); null for a second in which none arrived, and while
closing.
jitter_buffer_msrequired number | null The latest playout report's jitter_buffer_ms (to 0.1): NetEQ's own
delay as the client's getStats gives it, the allowance seen from
the phone.
keyrequired string | null The key that made it (device:phone, owner:…); null for an
anonymous caller.
playout_report_age_msrequired integer | null How long ago the latest playout report arrived, whatever it carried,
in ms: the age of jitter_buffer_ms. null before the first.
receiver_report_age_msrequired integer | null How long ago the client's latest receiver report arrived, in ms: the
age of egress_loss, client_jitter_ms and the round trip it fed.
A client sends one every few seconds; null before the first, and
while closing.
remoterequired string | null Where the client's last authenticated traffic came from.
round_trip_msrequired integer | null The session's round trip, in ms: the least of the last five the
client's receiver reports measured, as the playout allowance and the
barge-in margin take it. null before the first report reached the
call's audio out, and while closing.
sessionrequired string | null Its realtime session's id, once the session runs.
staterequired WebRtcCallState
threadrequired integer | null The Chat thread its session is bound to.

WebRtcGroup

Which listener a socket group serves.

One of: string (The plain listener's: stock clients.); string (The device listener's: paired devices.)

WebRtcGroupState

Where a socket group stands.

One of: string (realtime.webrtc_enabled was off at the gateway's start: a call on
its listener is refused 503 naming the setting.); string (Not bound: its listener does not serve, or it is moving with it.); string (Bound on addrs.); string (Its bind failed, or its sockets were lost; error says why. Its
listener serves on, and a call there is refused 503 naming it.)

WebRtcGroupStatus

One socket group: the sockets of the listener a call's POST came in on.

addrsrequired array of string Its sockets, as udp:// addresses: one per address of its listener.
Empty unless bound.
errorrequired string | null Why it is not bound, with state failed: the bind error naming the
address, or the call driver's stop.
grouprequired WebRtcGroup
rulerequired string The rule that binds it, naming its settings: the plain listener's
bind_addr and realtime.webrtc_port, or the device listener's
addresses and port.
staterequired WebRtcGroupState

WebRtcStatus

GET /api/status's webrtc.

callsrequired array of WebRtcCallStatus The live calls, oldest first, those still delivering their last
events (closing) included.
droppedrequired integer (uint64) Datagrams no call accepted, dropped unanswered since lmgw started
(the count outlives the call driver, which a panic starts again).
enabledrequired boolean realtime.webrtc_enabled as the gateway's last start read it: the
setting applies at the next start, so a saved value may differ until
then.
groupsrequired array of WebRtcGroupStatus The socket groups: the plain listener's, then the device listener's.