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
| Client | Base URL |
|---|---|
| OpenAI SDKs and tools | http://127.0.0.1:8787/v1 |
Anthropic SDKs, Claude Code (ANTHROPIC_BASE_URL) | http://127.0.0.1:8787 |
| Realtime voice sessions | ws://127.0.0.1:8787/v1/realtime |
| MCP clients | http://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.
| Header | Sent in | Meaning |
|---|---|---|
x-lmgw-background | request | on|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-candidate | response | On 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-approximate | response | On 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-fallback | response | The 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-chain | response | Every 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-reason | response | Why 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-omitted | response | Sent 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-clamped | response | The 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-defaulted | response | The 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-raised | response | The max_tokens value lmgw raised the request's cap to, because the requested thinking budget would not fit underneath it. |
x-lmgw-params-ignored | response | Comma-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-refused | response | Comma-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-reasoning | request | on|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-budget | request | Integer 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-effort | request | An 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-ignored | response | Comma-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-run | request | The 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-rung | response | On 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-rate | response | On 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-speech | response | On 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-source | response | On 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
/v1/audio/alignmentsAlign 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
| Status | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json AudioAlignment
Fields of AudioAlignment
Headers: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
| ||||||||||
default |
Error.
application/json OpenAiErrorHeaders: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
|
/v1/audio/speechGenerate 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
| Status | Description |
|---|---|
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 OpenAiErrorHeaders: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason, x-lmgw-sample-rate, x-lmgw-speech
|
/v1/audio/transcriptionsTranscribe 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
| Status | Description |
|---|---|
200 |
OK.
Headers: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
|
default |
Error.
application/json OpenAiErrorHeaders: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
|
/v1/audio/transcriptions/detailsTranscribe 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
| Status | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json AudioTranscriptionDetails Fields of AudioTranscriptionDetails
Headers: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
| ||||||||
default |
Error.
application/json OpenAiErrorHeaders: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
|
/v1/audio/voicesList 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
| Name | In | Description |
|---|---|---|
model | query | string |
probe | query | string | null |
Also takes x-lmgw-background, x-lmgw-run (see lmgw headers).
Responses
| Status | Description | ||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json AudioVoices Fields of AudioVoices
Headers: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason, x-lmgw-voices-source
| ||||||||||||||||||||||||||
default |
Error.
application/json OpenAiErrorHeaders: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason, x-lmgw-voices-source
|
/v1/chat/completionsCreate 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
| Status | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json ChatCompletion Fields of ChatCompletion
text/event-stream string1 event types
One of 2 shapesChatCompletionChunk Fields of ChatCompletionChunk
ChatCompletionStreamError Fields of ChatCompletionStreamError
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 |
/v1/completionsCreate 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
| Status | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json TextCompletion Fields of TextCompletion
text/event-stream string1 event types
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 |
/v1/embeddingsCreate 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
| Status | Description | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json EmbeddingsResponse Fields of EmbeddingsResponse
Headers: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
| ||||||||||||||||||
default |
Error.
application/json OpenAiErrorHeaders: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
|
/v1/images/editsEdit 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
| Status | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json ImageGenerationsResponse Fields of ImageGenerationsResponse
Headers: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
| ||||||||||
default |
Error.
application/json OpenAiErrorHeaders: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
|
/v1/images/generationsGenerate 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
| Status | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json ImageGenerationsResponse Fields of ImageGenerationsResponse
Headers: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
| ||||||||||
default |
Error.
application/json OpenAiErrorHeaders: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
|
/v1/modelsList 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
| Status | Description | ||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json ModelList ModelList: 2 shapesobject
Fields
object
Fields
| ||||||||||||||||||||||||||||||||||||||||||||
default |
Error.
application/json OpenAiError |
/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
| Name | In | Description |
|---|---|---|
idrequired | path | string |
Also takes x-lmgw-run (see lmgw headers).
Responses
| Status | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json ModelById ModelById: 2 shapesOpenAiModel Fields of OpenAiModel
AnthropicModel Fields of AnthropicModel
| ||||||||||||||||||||||||||||||||||||||||||||||||||
default |
Error.
application/json OpenAiError |
/v1/realtimeOpen 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
| Name | In | Description |
|---|---|---|
call_id | query | string | null |
chat_folder | query | integer | null |
chat_thread | query | integer | null |
model | query | string | null |
new | query | boolean | null |
takeover | query | Takeover | null |
Also takes x-lmgw-run (see lmgw headers).
Responses
| Status | Description |
|---|---|
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 |
/v1/realtime/callsStart 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
| Name | In | Description |
|---|---|---|
call_id | query | string | null |
chat_folder | query | integer | null |
chat_thread | query | integer | null |
model | query | string | null |
new | query | boolean | null |
takeover | query | 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 datachannel oai-events, created before createOffer. |
session |
object The session (application/json): a JSON object, the session assession.update takes it — OpenAI's GA session object. Not checkedbefore the answer: the session applies it as its first update, right after session.created and before any event of the client's, andanswers it as any update, session.updated or an error. On a callbound to a Chat thread only what the client owns applies (turn detection or lmgw.turn_mode, lmgw.half_duplex, lmgw.echo_tail_ms). |
Responses
| Status | Description |
|---|---|
201 |
Created.
application/sdp stringHeaders: Location
|
default |
Error.
application/json OpenAiError |
/v1/realtime/calls/{call_id}/hangupHang 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
| Name | In | Description |
|---|---|---|
call_idrequired | path | string |
Also takes x-lmgw-run (see lmgw headers).
Responses
| Status | Description |
|---|---|
200 |
OK. |
default |
Error.
application/json OpenAiError |
/v1/responsesCreate 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
| Status | Description | ||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json Response Fields of Response
text/event-stream string1 event types
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 |
/v1/responses/input_tokensCount 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
| Status | Description | ||||
|---|---|---|---|---|---|
200 |
OK.
application/json ResponseInputTokens Fields of ResponseInputTokens
Headers: x-lmgw-candidate, x-lmgw-count-approximate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
| ||||
default |
Error.
application/json OpenAiErrorHeaders: x-lmgw-candidate, x-lmgw-count-approximate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
|
/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
| Name | In | Description |
|---|---|---|
idrequired | path | string |
Also takes x-lmgw-run (see lmgw headers).
Responses
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/json ResponseDeleted Fields of ResponseDeleted
| ||||||
default |
Error.
application/json OpenAiError |
/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
| Name | In | Description |
|---|---|---|
idrequired | path | string |
Also takes x-lmgw-run (see lmgw headers).
Responses
| Status | Description | ||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json Response Fields of Response
| ||||||||||||||||||||||||||||||||||||||||
default |
Error.
application/json OpenAiError |
/v1/responses/{id}/input_itemsList 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
| Name | In | Description |
|---|---|---|
idrequired | path | string |
Also takes x-lmgw-run (see lmgw headers).
Responses
| Status | Description | ||||
|---|---|---|---|---|---|
200 |
OK.
application/json ResponseInputItems Fields of ResponseInputItems
| ||||
default |
Error.
application/json OpenAiError |
Anthropic-compatible
/v1/messagesCreate 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
| Name | In | Description |
|---|---|---|
anthropic-version | header | 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
| Status | Description | ||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json AnthropicMessage Fields of AnthropicMessage
text/event-stream string1 event types
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 |
/v1/messages/count_tokensCount 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
| Name | In | Description |
|---|---|---|
anthropic-version | header | 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
| Status | Description | ||||
|---|---|---|---|---|---|
200 |
OK.
application/json AnthropicCountTokensResponse Fields of AnthropicCountTokensResponse
Headers: x-lmgw-candidate, x-lmgw-count-approximate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
| ||||
default |
Error.
application/json AnthropicErrorHeaders: x-lmgw-candidate, x-lmgw-count-approximate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
|
llama.cpp-compatible
/tokenizeTokenize 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
| Status | Description | ||
|---|---|---|---|
200 |
OK.
application/json TokenizeResponse Fields of TokenizeResponse
Headers: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
| ||
default |
Error.
application/json LlamaCppErrorHeaders: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
|
/v1/systemoneAsk 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. nullonly 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
| Status | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json SystemOneResponse Fields of SystemOneResponse
Headers: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
| ||||||||||
default |
Error.
application/json LlamaCppErrorHeaders: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
|
lmgw extensions
/v1/count_tokensCount 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
| Status | Description | ||||
|---|---|---|---|---|---|
200 |
OK.
application/json CountTokensResponse Fields of CountTokensResponse
Headers: x-lmgw-candidate, x-lmgw-count-approximate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
| ||||
default |
Error.
application/json OpenAiErrorHeaders: x-lmgw-candidate, x-lmgw-count-approximate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
|
/v1/openapi.jsonGet 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
| Status | Description |
|---|---|
200 |
OK.
application/json object |
default |
Error.
application/json OpenAiError |
/v1/rerankRerank 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
| Status | Description | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json RerankResponse Fields of RerankResponse
Headers: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
| ||||||||||||||||
default |
Error.
application/json OpenAiErrorHeaders: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
|
/v1/tasks/runRun 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
| Status | Description |
|---|---|
200 |
OK.
application/json objectHeaders: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason, x-lmgw-speech
|
default |
Error.
application/json OpenAiErrorHeaders: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason, x-lmgw-speech
|
/v1/tasks/streamRun 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
| Status | Description |
|---|---|
200 |
OK.
application/json objectHeaders: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason, x-lmgw-speech
|
default |
Error.
application/json OpenAiErrorHeaders: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason, x-lmgw-speech
|
MCP
/mcpEnd an MCP session
Capability inference, open to: agent, device, key, owner. Changes state.
Ends a session.
Parameters
| Name | In | Description |
|---|---|---|
Accept | header | string MCP Streamable HTTP requires the client accept both JSON and server-sent events. |
Also takes x-lmgw-run (see lmgw headers).
Responses
| Status | Description |
|---|---|
204 |
No content. |
default |
Error.
application/json JsonRpcError |
/mcpOpen 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
| Name | In | Description |
|---|---|---|
Accept | header | string MCP Streamable HTTP requires the client accept both JSON and server-sent events. |
Also takes x-lmgw-run (see lmgw headers).
Responses
| Status | Description |
|---|---|
200 |
An event stream.
text/event-stream string1 event types
|
default |
Error.
application/json JsonRpcError |
/mcpCall 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
| Name | In | Description |
|---|---|---|
Accept | header | 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
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/json JsonRpcResponse Fields of JsonRpcResponse
| ||||||
default |
Error.
application/json JsonRpcError |
/mcp/adminEnd 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
| Name | In | Description |
|---|---|---|
Accept | header | string MCP Streamable HTTP requires the client accept both JSON and server-sent events. |
Also takes x-lmgw-run (see lmgw headers).
Responses
| Status | Description |
|---|---|
204 |
No content. |
default |
Error.
application/json JsonRpcError |
/mcp/adminOpen 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
| Name | In | Description |
|---|---|---|
Accept | header | string MCP Streamable HTTP requires the client accept both JSON and server-sent events. |
Also takes x-lmgw-run (see lmgw headers).
Responses
| Status | Description |
|---|---|
200 |
An event stream.
text/event-stream string1 event types
|
default |
Error.
application/json JsonRpcError |
/mcp/adminCall 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
| Name | In | Description |
|---|---|---|
Accept | header | 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
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/json JsonRpcResponse Fields of JsonRpcResponse
| ||||||
default |
Error.
application/json JsonRpcError |
/mcp/hostHost 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
| Status | Description |
|---|---|
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 |
/v1/mcp/serversList 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
| Status | Description | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json McpServerList Fields of McpServerList
| ||||||||||||||
default |
Error.
application/json OpenAiError |
/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
| Name | In | Description |
|---|---|---|
labelrequired | path | string |
Also takes x-lmgw-run (see lmgw headers).
Responses
| Status | Description | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json McpServerDetail Fields of McpServerDetail
| ||||||||||||||||||
default |
Error.
application/json OpenAiError |
Gateway
API description
/api/connectGet 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
| Status | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json ConnectInfo
Fields of ConnectInfo
| ||||||||||||
default |
Error.
application/json ApiError |
/api/openapi.jsonGet the full OpenAPI description
Capability admin, open to: owner
This description, generated rather than hand-maintained.
Responses
| Status | Description |
|---|---|
200 |
OK.
application/json object |
default |
Error.
application/json ApiError |
/api/versionGet 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
| Status | Description | ||
|---|---|---|---|
200 |
OK.
application/json VersionInfo
Fields of VersionInfo
| ||
default |
Error.
application/json ApiError |
Dashboard API
Session
/api/sessionSign 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
| Status | Description |
|---|---|
204 |
No content. |
default |
Error.
application/json ApiError |
/api/sessionRead 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
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/json SessionView
Fields of SessionView
| ||||||
default |
Error.
application/json ApiError |
/api/sessionSign 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
| Status | Description |
|---|---|
204 |
No content. |
default |
Error.
application/json ApiError |
/api/session/loginLog 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
| Name | In | Description |
|---|---|---|
nonce | query | string | null |
token | query | string | null |
Responses
| Status | Description |
|---|---|
302 |
Redirect. |
default |
Error.
application/json ApiError |
Status & live feed
/api/eventsOpen 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
| Status | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
An event stream.
text/event-stream string10 event types
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/api/jobsList 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
| Name | In | Description |
|---|---|---|
active | query | boolean | null |
kind | query | string | null |
limit | query | integer | null |
Responses
| Status | Description |
|---|---|
200 |
OK.
|
default |
Error.
application/json ApiError |
/api/logsList 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
| Name | In | Description |
|---|---|---|
alias | query | string | null |
alias_q | query | string | null |
before_id | query | integer | null |
class | query | string | null |
error_kind | query | string | null |
errors_only | query | string | null |
key_id | query | integer | null |
limit | query | integer | null |
upstream | query | string | null |
upstream_q | query | string | null |
Responses
| Status | Description |
|---|---|
200 |
OK.
|
default |
Error.
application/json ApiError |
/api/statusGet 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
| Status | Description | ||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json GatewayStatus
Fields of GatewayStatus
| ||||||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/api/vramGet 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
| Status | Description | ||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json VramStatus
Fields of VramStatus
| ||||||||||||||||||||||||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
Models
/api/gguf-filesList GGUF files on disk
Capability admin, open to: owner
GGUF files under a class's models dir, matched against an optional search string.
Parameters
| Name | In | Description |
|---|---|---|
search | query | string | null |
target | query | string | null |
Responses
| Status | Description | ||||
|---|---|---|---|---|---|
200 |
OK.
application/json GgufFiles
Fields of GgufFiles
| ||||
default |
Error.
application/json ApiError |
/api/ladder-rung-planPlan 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
| Name | In | Description |
|---|---|---|
cache_type_k | query | string | null |
cache_type_v | query | string | null |
ctx_sizerequired | query | integer (int64) |
draft_gguf_path | query | string | null |
gguf_pathrequired | query | string |
mmproj_path | query | string | null |
n_gpu_layers | query | integer | null |
Responses
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/json RungPlan
Fields of RungPlan
| ||||||
default |
Error.
application/json ApiError |
/api/llama-flagsPreview 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
| Name | In | Description |
|---|---|---|
model | query | string | null |
search | query | string | null |
Responses
| Status | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json LlamaFlags
Fields of LlamaFlags
| ||||||||||||
default |
Error.
application/json ApiError |
/api/local-modelGet 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
| Name | In | Description |
|---|---|---|
id | query | integer | null |
model_id | query | string | null |
target | query | string | null |
Responses
| Status | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json One of 4 shapesLocalModelDetail Fields of LocalModelDetail
AuxModelDetail Fields of AuxModelDetail
ImageModelDetail Fields of ImageModelDetail
AudioModelDetail Fields of AudioModelDetail
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/api/local-model-checkCheck 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
| Name | In | Description |
|---|---|---|
model_id | query | string | null |
target | query | string | null |
Responses
| Status | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json LocalModelCheck
Fields of LocalModelCheck
| ||||||||||
default |
Error.
application/json ApiError |
/api/local-model-planPlan 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
| Name | In | Description |
|---|---|---|
file | query | string | null |
path | query | string | null |
repo | query | string | null |
target | query | string | null |
Responses
| Status | Description | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json PlanResult
Fields of PlanResult
| ||||||||||||||||
default |
Error.
application/json ApiError |
/api/model-inspectInspect 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
| Name | In | Description |
|---|---|---|
pathrequired | query | string |
target | query | string | null |
Responses
| Status | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json ModelInspect
Fields of ModelInspect
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/api/models/fullList 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
| Status | Description | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json ModelsFull
Fields of ModelsFull
| ||||||||||||||
default |
Error.
application/json ApiError |
/api/wiringGet 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
| Status | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json WiringView
Fields of WiringView
| ||||||||||||
default |
Error.
application/json ApiError |
Upstreams
/api/upstream-modelsList 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
| Name | In | Description |
|---|---|---|
idrequired | query | integer (int64) |
Responses
| Status | Description | ||||
|---|---|---|---|---|---|
200 |
OK.
application/json UpstreamModelsResponse
Fields of UpstreamModelsResponse
| ||||
default |
Error.
application/json ApiError |
/api/upstreamsList upstreams
Capability admin, open to: owner
Every configured upstream, secrets redacted to has_api_key and extra header values shown as <set>.
Responses
| Status | Description | ||
|---|---|---|---|
200 |
OK.
application/json UpstreamsResponse
Fields of UpstreamsResponse
| ||
default |
Error.
application/json ApiError |
MCP servers & tools
/api/mcp-serversList 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
| Status | Description | ||
|---|---|---|---|
200 |
OK.
application/json McpServersResponse
Fields of McpServersResponse
| ||
default |
Error.
application/json ApiError |
/api/mcp-servers/{id}/toolsList one MCP server's tools
Capability admin, open to: owner
One server's exposed tools — what a Chat thread's MCP picker offers.
Parameters
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
Responses
| Status | Description | ||
|---|---|---|---|
200 |
OK.
application/json McpServerToolsResponse
Fields of McpServerToolsResponse
| ||
default |
Error.
application/json ApiError |
/api/toolsList 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
| Status | Description | ||||
|---|---|---|---|---|---|
200 |
OK.
application/json ToolInventory
Fields of ToolInventory
| ||||
default |
Error.
application/json ApiError |
Downloads
/api/audio/catalogGet 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
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/json AudioCatalog
Fields of AudioCatalog
| ||||||
default |
Error.
application/json ApiError |
/api/hf/downloadsList 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
| Name | In | Description |
|---|---|---|
active | query | boolean | null |
ids | query | string | null |
Responses
| Status | Description |
|---|---|
200 |
OK.
|
default |
Error.
application/json ApiError |
/api/hf/repoList 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
| Name | In | Description |
|---|---|---|
fit | query | RepoFit | null |
reporequired | query | string |
search | query | string | null |
target | query | string | null |
Responses
| Status | Description | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json RepoFiles
Fields of RepoFiles
| ||||||||||||||||||||
default |
Error.
application/json ApiError |
Settings
/api/settings-fullGet 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
| Status | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json SettingsFull
Fields of SettingsFull
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
Stored responses
/api/responsesList stored response chains
Capability admin, open to: owner
Every stored /v1/responses conversation chain, most recent first, capped at 200.
Responses
| Status | Description | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json ResponsesIndex
Fields of ResponsesIndex
| ||||||||||||||||
default |
Error.
application/json ApiError |
/api/responses/chainGet 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
| Name | In | Description |
|---|---|---|
idrequired | query | string |
Responses
| Status | Description | ||||
|---|---|---|---|---|---|
200 |
OK.
application/json ChainDetail
Fields of ChainDetail
| ||||
default |
Error.
application/json ApiError |
Usage
/api/usage/errorsGet usage errors by kind
Capability admin, open to: owner
Refusals and errors over a time range, grouped by error kind.
Parameters
| Name | In | Description |
|---|---|---|
alias | query | string | null |
bucket | query | string | null |
class | query | string | null |
from | query | string | null |
key_id | query | integer | null |
to | query | string | null |
tz | query | integer | null |
Responses
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/json UsageErrorsResponse
Fields of UsageErrorsResponse
| ||||||
default |
Error.
application/json ApiError |
/api/usage/export.csvExport 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
| Name | In | Description |
|---|---|---|
alias | query | string | null |
class | query | string | null |
from | query | string | null |
key_id | query | integer | null |
to | query | string | null |
tz | query | integer | null |
upstream_id | query | integer | null |
Responses
| Status | Description |
|---|---|
200 |
OK.
text/csv string (binary) |
default |
Error.
application/json ApiError |
/api/usage/heatGet a usage heatmap
Capability admin, open to: owner
Cost by hour-of-day × day-of-week, for the usage heatmap.
Parameters
| Name | In | Description |
|---|---|---|
alias | query | string | null |
class | query | string | null |
from | query | string | null |
key_id | query | integer | null |
to | query | string | null |
tz | query | integer | null |
upstream_id | query | integer | null |
Responses
| Status | Description | ||||
|---|---|---|---|---|---|
200 |
OK.
application/json UsageHeatResponse
Fields of UsageHeatResponse
| ||||
default |
Error.
application/json ApiError |
/api/usage/keysList keys with their usage
Capability admin, open to: owner
Every gateway key with its lifetime and recent spend, scope and last-used time.
Responses
| Status | Description | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json KeysResponse
Fields of KeysResponse
| ||||||||||||||
default |
Error.
application/json ApiError |
/api/usage/localGet 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
| Name | In | Description |
|---|---|---|
alias | query | string | null |
class | query | string | null |
from | query | string | null |
key_id | query | integer | null |
to | query | string | null |
tz | query | integer | null |
Responses
| Status | Description | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json UsageLocalResponse
Fields of UsageLocalResponse
| ||||||||||||||||
default |
Error.
application/json ApiError |
/api/usage/pricesList 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
| Status | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json PricesResponse
Fields of PricesResponse
| ||||||||||
default |
Error.
application/json ApiError |
/api/usage/seriesGet 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
| Name | In | Description |
|---|---|---|
alias | query | string | null |
bucket | query | string | null |
class | query | string | null |
from | query | string | null |
group_by | query | string | null |
key_id | query | integer | null |
limit | query | integer | null |
to | query | string | null |
tz | query | integer | null |
upstream_id | query | integer | null |
Responses
| Status | Description | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json UsageSeriesResponse
Fields of UsageSeriesResponse
| ||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/api/usage/topGet 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
| Name | In | Description |
|---|---|---|
alias | query | string | null |
class | query | string | null |
dim | query | string | null |
from | query | string | null |
key_id | query | integer | null |
limit | query | integer | null |
to | query | string | null |
tz | query | integer | null |
upstream_id | query | integer | null |
Responses
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/json UsageTopResponse
Fields of UsageTopResponse
| ||||||
default |
Error.
application/json ApiError |
Doc corpora
/api/docs/chunksList a document's chunks
Capability admin, open to: owner
One document's chunks, verbatim payload included, for the corpus browser's leaf view.
Parameters
| Name | In | Description |
|---|---|---|
document_idrequired | query | integer (int64) |
Responses
| Status | Description |
|---|---|
200 |
OK.
|
default |
Error.
application/json ApiError |
/api/docs/corporaList 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
| Status | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json DocsOverview
Fields of DocsOverview
| ||||||||
default |
Error.
application/json ApiError |
/api/docs/corporaCreate 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
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/json CorpusCreated
Fields of CorpusCreated
| ||||||
default |
Error.
application/json ApiError |
/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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
limit | query | integer | null |
Responses
| Status | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json CorpusDetail
Fields of CorpusDetail
| ||||||||
default |
Error.
application/json ApiError |
/api/docs/corpora/{id}/deleteDelete 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
Responses
| Status | Description | ||||
|---|---|---|---|---|---|
200 |
OK.
application/json MessageAck
Fields of MessageAck
| ||||
default |
Error.
application/json ApiError |
/api/docs/corpora/{id}/documentsList 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
Responses
| Status | Description | ||
|---|---|---|---|
200 |
OK.
application/json DocumentsResponse
Fields of DocumentsResponse
| ||
default |
Error.
application/json ApiError |
/api/docs/corpora/{id}/ingestStart 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
Responses
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/json DocsJobStarted
Fields of DocsJobStarted
| ||||||
default |
Error.
application/json ApiError |
/api/docs/corpora/{id}/re-embedStart 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
| Name | In | Description |
|---|---|---|
idrequired | path | 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
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/json DocsJobStarted
Fields of DocsJobStarted
| ||||||
default |
Error.
application/json ApiError |
/api/docs/evalList 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
| Name | In | Description |
|---|---|---|
corpus_idrequired | query | integer (int64) |
limit | query | integer | null |
Responses
| Status | Description |
|---|---|
200 |
OK.
|
default |
Error.
application/json ApiError |
/api/docs/evalStart 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 defaultsdocs__query itself runs with. Default null. |
Responses
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/json DocsJobStarted
Fields of DocsJobStarted
| ||||||
default |
Error.
application/json ApiError |
/api/docs/exportExport 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
| Name | In | Description |
|---|---|---|
corpus_id | query | integer | null |
Responses
| Status | Description |
|---|---|
200 |
OK.
application/vnd.sqlite3 string (binary) |
default |
Error.
application/json ApiError |
/api/docs/export/manifestPreview 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
| Name | In | Description |
|---|---|---|
corpus_id | query | integer | null |
Responses
| Status | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json ExportManifest
Fields of ExportManifest
| ||||||||
default |
Error.
application/json ApiError |
/api/docs/goldenList 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
| Name | In | Description |
|---|---|---|
corpus_idrequired | query | integer (int64) |
limit | query | integer | null |
Responses
| Status | Description | ||
|---|---|---|---|
200 |
OK.
application/json GoldenResponse
Fields of GoldenResponse
| ||
default |
Error.
application/json ApiError |
/api/docs/goldenCreate 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 sayingwhere it came from. Default null. |
queryrequired |
string |
Responses
| Status | Description | ||||
|---|---|---|---|---|---|
200 |
OK.
application/json GoldenSaved
Fields of GoldenSaved
| ||||
default |
Error.
application/json ApiError |
/api/docs/golden/candidatesList 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
| Name | In | Description |
|---|---|---|
corpus_idrequired | query | integer (int64) |
status | query | string | null |
Responses
| Status | Description | ||||
|---|---|---|---|---|---|
200 |
OK.
application/json GoldenCandidatesResponse
Fields of GoldenCandidatesResponse
| ||||
default |
Error.
application/json ApiError |
/api/docs/golden/candidates/{id}/acceptAccept 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
| Name | In | Description |
|---|---|---|
idrequired | path | 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
| Status | Description | ||||
|---|---|---|---|---|---|
200 |
OK.
application/json GoldenSaved
Fields of GoldenSaved
| ||||
default |
Error.
application/json ApiError |
/api/docs/golden/candidates/{id}/rejectReject 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
Responses
| Status | Description | ||
|---|---|---|---|
200 |
OK.
application/json Ack
Fields of Ack
| ||
default |
Error.
application/json ApiError |
/api/docs/golden/generateGenerate 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 — therun is as big as the corpus unless a smaller sample is asked for. Default null. |
Responses
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/json DocsJobStarted
Fields of DocsJobStarted
| ||||||
default |
Error.
application/json ApiError |
/api/docs/golden/{id}/deleteDelete a golden query
Capability admin, open to: owner. Changes state.
Deletes one golden query.
Parameters
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
Responses
| Status | Description | ||
|---|---|---|---|
200 |
OK.
application/json Ack
Fields of Ack
| ||
default |
Error.
application/json ApiError |
/api/docs/importImport 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
| Name | In | Description |
|---|---|---|
replace | query | boolean |
validate_only | query | boolean |
Request body required
application/vnd.sqlite3: string (binary)
Responses
| Status | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json ImportReport
Fields of ImportReport
| ||||||||
default |
Error.
application/json ApiError |
/api/docs/requestsList 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
| Name | In | Description |
|---|---|---|
status | query | string | null |
Responses
| Status | Description | ||
|---|---|---|---|
200 |
OK.
application/json DocRequestsResponse
Fields of DocRequestsResponse
| ||
default |
Error.
application/json ApiError |
/api/docs/requests/{id}/statusSet 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
Request body required
application/json: object
statusrequired |
string dismissed to clear it, pending to put it back. |
Responses
| Status | Description | ||
|---|---|---|---|
200 |
OK.
application/json Ack
Fields of Ack
| ||
default |
Error.
application/json ApiError |
/api/docs/searchSearch 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
| Status | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json DocsSearchResponse
Fields of DocsSearchResponse
| ||||||||||||
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.
/api/knowledge/basesList 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
| Status | Description |
|---|---|
200 |
OK.
|
default |
Error.
application/json ApiError |
/api/knowledge/basesCreate 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 whenabsent. 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
| Status | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json KnowledgeBase
Fields of KnowledgeBase
| ||||||||||||||||||||||||||||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
Responses
| Status | Description | ||||
|---|---|---|---|---|---|
200 |
OK.
application/json KnowledgeBaseDetail
Fields of KnowledgeBaseDetail
| ||||
default |
Error.
application/json ApiError |
/api/knowledge/bases/{id}/cancelCancel 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
Responses
| Status | Description | ||||
|---|---|---|---|---|---|
200 |
OK.
application/json CancelResult
Fields of CancelResult
| ||||
default |
Error.
application/json ApiError |
/api/knowledge/bases/{id}/deleteDelete 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
Responses
| Status | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json KnowledgeBaseDeleted
Fields of KnowledgeBaseDeleted
| ||||||||
default |
Error.
application/json ApiError |
/api/knowledge/bases/{id}/filesList 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
Responses
| Status | Description |
|---|---|
200 |
OK.
|
default |
Error.
application/json ApiError |
/api/knowledge/bases/{id}/filesUpload 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
| Name | In | Description |
|---|---|---|
idrequired | path | 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
| Status | Description | ||||
|---|---|---|---|---|---|
200 |
OK.
application/json UploadResult
Fields of UploadResult
| ||||
default |
Error.
application/json ApiError |
/api/knowledge/bases/{id}/resumeResume 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
Responses
| Status | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json ResumeResult
Fields of ResumeResult
| ||||||||||
default |
Error.
application/json ApiError |
/api/knowledge/bases/{id}/settingsChange 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
| Name | In | Description |
|---|---|---|
idrequired | path | 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
| Status | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json KnowledgeBaseEdited
Fields of KnowledgeBaseEdited
| ||||||||
default |
Error.
application/json ApiError |
/api/knowledge/files/{id}/deleteDelete 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
Responses
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/json KnowledgeFileDeleted
Fields of KnowledgeFileDeleted
| ||||||
default |
Error.
application/json ApiError |
/api/knowledge/files/{id}/originalDownload 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
Responses
| Status | Description |
|---|---|
200 |
OK.
*/* string (binary) |
default |
Error.
application/json ApiError |
/api/knowledge/files/{id}/reingestIngest 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
Responses
| Status | Description | ||||
|---|---|---|---|---|---|
200 |
OK.
application/json KnowledgeFileRequeued
Fields of KnowledgeFileRequeued
| ||||
default |
Error.
application/json ApiError |
/api/knowledge/files/{id}/textRead 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
chunk | query | string | null |
sha | query | string | null |
span_end | query | integer | null |
span_start | query | integer | null |
Responses
| Status | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json KnowledgeSource
Fields of KnowledgeSource
| ||||||||||||
default |
Error.
application/json ApiError |
/api/knowledge/searchSearch 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 ownlimit 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
| Status | Description | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json KnowledgeSearchResult
Fields of KnowledgeSearchResult
| ||||||||||||||
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/*.
/audio-lab/api/alignmentsAlign 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
| Name | In | Description |
|---|---|---|
group | query | integer | null |
Request body required
multipart/form-data: AudioAlignmentsRequest
Fields of AudioAlignmentsRequest
filerequired |
string (binary) |
language |
string |
modelrequired |
string |
textrequired |
string |
Responses
| Status | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json AudioAlignment
Fields of AudioAlignment
| ||||||||||
default |
Error.
application/json OpenAiError |
/audio-lab/api/groupsKeep 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
| Status | Description | ||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json LabGroupView
Fields of LabGroupView
| ||||||||||||||||||||||
default |
Error.
application/json LabError |
/audio-lab/api/modelsList 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
| Status | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json AudioLabModels
Fields of AudioLabModels
| ||||||||||
default |
Error.
application/json LabError |
/audio-lab/api/refsList 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
| Status | Description | ||||
|---|---|---|---|---|---|
200 |
OK.
application/json ClipList
Fields of ClipList
| ||||
default |
Error.
application/json LabError |
/audio-lab/api/refsUpload 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
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/json ClipsUploaded
Fields of ClipsUploaded
| ||||||
default |
Error.
application/json LabError |
/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
| Name | In | Description |
|---|---|---|
namerequired | path | string |
Responses
| Status | Description |
|---|---|
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 |
/audio-lab/api/refs/{name}/deleteDelete 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
| Name | In | Description |
|---|---|---|
namerequired | path | string |
Responses
| Status | Description | ||||
|---|---|---|---|---|---|
200 |
OK.
application/json ClipsAck
Fields of ClipsAck
| ||||
default |
Error.
application/json LabError |
/audio-lab/api/refs/{name}/textSet 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
| Name | In | Description |
|---|---|---|
namerequired | path | 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
| Status | Description | ||||
|---|---|---|---|---|---|
200 |
OK.
application/json ClipsAck
Fields of ClipsAck
| ||||
default |
Error.
application/json LabError |
/audio-lab/api/refs/{name}/transcribeTranscribe 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
| Name | In | Description |
|---|---|---|
namerequired | path | 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
| Status | Description | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json ClipTranscribed
Fields of ClipTranscribed
| ||||||||||||||||||
default |
Error.
application/json LabError |
/audio-lab/api/speechSynthesize 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
| Name | In | Description |
|---|---|---|
group | query | 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
| Status | Description |
|---|---|
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 |
/audio-lab/api/tasks/runRun 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
| Name | In | Description |
|---|---|---|
group | query | integer | null |
stream | query | 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
| Status | Description |
|---|---|
200 |
OK.
application/json object |
default |
Error.
application/json OpenAiError |
/audio-lab/api/transcriptionsTranscribe 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
| Name | In | Description |
|---|---|---|
details | query | string | null |
group | query | 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
| Status | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json One of 2 shapesAudioTranscription Fields of AudioTranscription
AudioTranscriptionDetails Fields of AudioTranscriptionDetails
| ||||||||||
default |
Error.
application/json OpenAiError |
/audio-lab/api/voicesList 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
| Name | In | Description |
|---|---|---|
modelrequired | query | string |
Responses
| Status | Description | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json LabVoices
Fields of LabVoices
| ||||||||||||||||
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.
/image-lab/api/groupsKeep 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 cloudone. 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 itsspelling for "random each run". Default "". |
steps |
string Default "". |
width |
string Default "". |
Responses
| Status | Description | ||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json LabGroupView
Fields of LabGroupView
| ||||||||||||||||||||||
default |
Error.
application/json OpenAiError |
/image-lab/api/groups/editKeep 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
| Status | Description | ||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json LabGroupView
Fields of LabGroupView
| ||||||||||||||||||||||
default |
Error.
application/json OpenAiError |
/image-lab/api/groups/{id}/runRun 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
Responses
| Status | Description | ||||
|---|---|---|---|---|---|
200 |
OK.
application/json ImageLabAnswer
Fields of ImageLabAnswer
| ||||
default |
Error.
application/json OpenAiError |
/image-lab/api/modelsList 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
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/json ImageLabModels
Fields of ImageLabModels
| ||||||
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.
/decision-lab/api/batchesList 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
| Status | Description |
|---|---|
200 |
OK.
|
default |
Error.
application/json ApiError |
/decision-lab/api/batchesStart 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
| Status | Description | ||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json BatchView
Fields of BatchView
| ||||||||||||||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/decision-lab/api/batches/from-agentSave 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
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/json BatchFromAgentSaved
Fields of BatchFromAgentSaved
| ||||||
default |
Error.
application/json ApiError |
/decision-lab/api/batches/previewPreview 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 listseach 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
| Status | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json BatchPreviewed
Fields of BatchPreviewed
| ||||||||
default |
Error.
application/json ApiError |
/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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
Responses
| Status | Description | ||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json BatchView
Fields of BatchView
| ||||||||||||||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/decision-lab/api/batches/{id}/cancelCancel 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
Responses
| Status | Description | ||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json BatchView
Fields of BatchView
| ||||||||||||||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/decision-lab/api/batches/{id}/deleteDelete 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
Responses
| Status | Description | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json LabUsage
Fields of LabUsage
| ||||||||||||||||||||
default |
Error.
application/json ApiError |
/decision-lab/api/batches/{id}/itemsRead 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
after | query | integer | null |
limit | query | integer | null |
Responses
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/json BatchItemPage
Fields of BatchItemPage
| ||||||
default |
Error.
application/json ApiError |
/decision-lab/api/batches/{id}/metricsRead 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
bins | query | integer | null |
question | query | string | null |
Responses
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/json BatchMetrics
Fields of BatchMetrics
| ||||||
default |
Error.
application/json ApiError |
/decision-lab/api/batches/{id}/resumeResume 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
| Name | In | Description |
|---|---|---|
idrequired | path | 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
| Status | Description | ||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json BatchView
Fields of BatchView
| ||||||||||||||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/decision-lab/api/batches/{id}/thresholdUse 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
| Name | In | Description |
|---|---|---|
idrequired | path | 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
| Status | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json LabPresetView
Fields of LabPresetView
| ||||||||||
default |
Error.
application/json ApiError |
/decision-lab/api/countCount 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
| Status | Description | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json DecisionCounted
Fields of DecisionCounted
| ||||||||||||||
default |
Error.
application/json ApiError |
/decision-lab/api/groupsAsk: 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 onlymodel rewritten per model. Default null. |
variants |
array of Variant The checked perturbations; every model is also asked as written, first. Default []. |
Responses
| Status | Description | ||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json LabGroupView
Fields of LabGroupView
| ||||||||||||||||||||||
default |
Error.
application/json ApiError |
/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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
cellrequired | path | integer |
Responses
| Status | Description | ||||
|---|---|---|---|---|---|
200 |
OK.
application/json LabCellResult
Fields of LabCellResult
| ||||
default |
Error.
application/json ApiError |
/decision-lab/api/modelsList 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
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/json DecisionLabModels
Fields of DecisionLabModels
| ||||||
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.
/voice-lab/api/clone-checkSpeak 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
| Status | Description |
|---|---|
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 |
/voice-lab/api/modelWhat 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
| Name | In | Description |
|---|---|---|
aliasrequired | query | string |
language | query | string | null |
voice | query | string | null |
Responses
| Status | Description | ||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json VoiceModelFacts
Fields of VoiceModelFacts
| ||||||||||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/voice-lab/api/roundsList 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
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/json VoiceRounds
Fields of VoiceRounds
| ||||||
default |
Error.
application/json ApiError |
/voice-lab/api/roundsRender 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
| Status | Description | ||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json VoiceRound
Fields of VoiceRound
| ||||||||||||||||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/voice-lab/api/rounds/clearDiscard 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
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/json VoiceRounds
Fields of VoiceRounds
| ||||||
default |
Error.
application/json ApiError |
/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
| Name | In | Description |
|---|---|---|
idrequired | path | string |
nrequired | path | integer |
Responses
| Status | Description |
|---|---|
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 |
/voice-lab/api/rounds/{id}/deleteDiscard 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
| Name | In | Description |
|---|---|---|
idrequired | path | string |
Responses
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/json VoiceRounds
Fields of VoiceRounds
| ||||||
default |
Error.
application/json ApiError |
/voice-lab/api/samplesList 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
| Status | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json VoiceSamples
Fields of VoiceSamples
| ||||||||
default |
Error.
application/json ApiError |
/voice-lab/api/samplesSave 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 isdropped. |
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
| Status | Description | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json VoiceSampleSaved
Fields of VoiceSampleSaved
| ||||||||||||||||
default |
Error.
application/json ApiError |
/voice-lab/api/sentencesList 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
| Status | Description | ||||
|---|---|---|---|---|---|
200 |
OK.
application/json VoiceSentences
Fields of VoiceSentences
| ||||
default |
Error.
application/json ApiError |
/voice-lab/api/sentencesSave 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
| Status | Description | ||||
|---|---|---|---|---|---|
200 |
OK.
application/json VoiceSentences
Fields of VoiceSentences
| ||||
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.
/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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
Responses
| Status | Description |
|---|---|
200 |
OK.
*/* string (binary) |
default |
Error.
application/json ApiError |
/labs/api/{lab}/clearClear 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
| Name | In | Description |
|---|---|---|
labrequired | path | string |
Responses
| Status | Description | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json LabUsage
Fields of LabUsage
| ||||||||||||||||||||
default |
Error.
application/json ApiError |
/labs/api/{lab}/exportExport 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
| Name | In | Description |
|---|---|---|
labrequired | path | string |
batch | query | integer | null |
format | query | LabExportFormat |
from | query | string | null |
group | query | integer | null |
model | query | string | null |
to | query | string | null |
Responses
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/x-ndjson LabExportLine
Fields of LabExportLine
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 |
/labs/api/{lab}/groupsRead 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
| Name | In | Description |
|---|---|---|
labrequired | path | string |
before | query | integer | null |
limit | query | integer | null |
model | query | string | null |
Responses
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/json LabGroupPage
Fields of LabGroupPage
| ||||||
default |
Error.
application/json ApiError |
/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
| Name | In | Description |
|---|---|---|
labrequired | path | string |
idrequired | path | integer |
Responses
| Status | Description | ||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json LabGroupView
Fields of LabGroupView
| ||||||||||||||||||||||
default |
Error.
application/json ApiError |
/labs/api/{lab}/groups/{id}/deleteDelete 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
| Name | In | Description |
|---|---|---|
labrequired | path | string |
idrequired | path | integer |
Responses
| Status | Description | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json LabUsage
Fields of LabUsage
| ||||||||||||||||||||
default |
Error.
application/json ApiError |
/labs/api/{lab}/orphans/deleteRemove 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
| Name | In | Description |
|---|---|---|
labrequired | path | string |
Responses
| Status | Description | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json LabUsage
Fields of LabUsage
| ||||||||||||||||||||
default |
Error.
application/json ApiError |
/labs/api/{lab}/presetsList 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
| Name | In | Description |
|---|---|---|
labrequired | path | string |
kind | query | LabPresetKind | null |
Responses
| Status | Description |
|---|---|
200 |
OK.
|
default |
Error.
application/json ApiError |
/labs/api/{lab}/presetsSave 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
| Name | In | Description |
|---|---|---|
labrequired | path | string |
Request body required
application/json: object | object | object
namerequired |
string Unique among the lab's presets of its kind. |
Responses
| Status | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json LabPresetView
Fields of LabPresetView
| ||||||||||
default |
Error.
application/json ApiError |
/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
| Name | In | Description |
|---|---|---|
labrequired | path | string |
idrequired | path | integer |
Responses
| Status | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json LabPresetView
Fields of LabPresetView
| ||||||||||
default |
Error.
application/json ApiError |
/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
| Name | In | Description |
|---|---|---|
labrequired | path | string |
idrequired | path | 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 (anotheredit, a threshold written), the update is a 409 set_changed. |
Responses
| Status | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json LabPresetView
Fields of LabPresetView
| ||||||||||
default |
Error.
application/json ApiError |
/labs/api/{lab}/presets/{id}/deleteDelete 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
| Name | In | Description |
|---|---|---|
labrequired | path | string |
idrequired | path | integer |
Responses
| Status | Description |
|---|---|
200 |
OK.
|
default |
Error.
application/json ApiError |
/labs/api/{lab}/usageRead 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
| Name | In | Description |
|---|---|---|
labrequired | path | string |
Responses
| Status | Description | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json LabUsage
Fields of LabUsage
| ||||||||||||||||||||
default |
Error.
application/json ApiError |
Agents
/api/agentsList agents
Capability admin, open to: owner
Every agent in the catalog, with its warnings, requirements and last-run summary.
Responses
| Status | Description | ||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json array of AgentCard Fields of AgentCard
| ||||||||||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/api/agents/importImport 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
| Name | In | Description |
|---|---|---|
replace | query | string | null |
validate_only | query | string | null |
Request body required
application/json: string (binary)
Responses
| Status | Description | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json AgentImportReport
Fields of AgentImportReport
| ||||||||||||||||
default |
Error.
application/json ApiError |
/api/agents/{id}/exportExport 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
| Name | In | Description |
|---|---|---|
idrequired | path | string |
include_config | query | string | null |
Responses
| Status | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json AgentExport
Fields of AgentExport
| ||||||||||||
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.
/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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
Responses
| Status | Description |
|---|---|
200 |
OK.
*/* string (binary) |
default |
Error.
application/json ApiError |
/chat/api/attachments/{id}/deleteDelete 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
Responses
| Status | Description | ||
|---|---|---|---|
200 |
OK.
application/json Ack
Fields of Ack
| ||
default |
Error.
application/json ApiError |
/chat/api/attachments/{id}/mediaRun 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
| Name | In | Description |
|---|---|---|
idrequired | path | 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 ownwhen omitted, else the row's default. |
upscaler |
string upscale: the upscaler's name (a file stem of the image models dir'supscalers/); the server's first compatible one when omitted. |
Responses
| Status | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
An event stream.
text/event-stream string4 event types
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/chat/api/attachments/{id}/modeChoose 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
Request body required
application/json: object
moderequired |
string text sends the PDF's extracted text, images its pages asimages. One of text, images. |
Responses
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/json ModeSet
Fields of ModeSet
| ||||||
default |
Error.
application/json ApiError |
/chat/api/attachments/{id}/textRead 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
Responses
| Status | Description |
|---|---|
200 |
OK.
text/plain; charset=utf-8 string (binary) |
default |
Error.
application/json ApiError |
/chat/api/attachments/{id}/transcribeTranscribe 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
Responses
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/json Transcribed
Fields of Transcribed
| ||||||
default |
Error.
application/json ApiError |
/chat/api/exportExport 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
| Name | In | Description |
|---|---|---|
archived | query | string |
format | query | string |
Responses
| Status | Description |
|---|---|
200 |
OK.
application/zip string (binary) |
default |
Error.
application/json ApiError |
/chat/api/feedFollow 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
| Name | In | Description |
|---|---|---|
keepalive_s | query | integer | null |
since | query | string | null |
Responses
| Status | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
An event stream.
text/event-stream string29 event types
One of 2 shapesany any
One of 2 shapesany any
One of 2 shapesany any
One of 2 shapesany any
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/chat/api/foldersList 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
| Status | Description | ||
|---|---|---|---|
200 |
OK.
application/json FolderList
Fields of FolderList
| ||
default |
Error.
application/json ApiError |
/chat/api/foldersCreate 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 (403forbidden): 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, asarchive_days. |
Responses
| Status | Description | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json Folder
Fields of Folder
| ||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/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
| Name | In | Description |
|---|---|---|
idrequired | path | 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 devicekey cannot set it (403 forbidden). |
defaults |
ThreadDefaultsInput | null Replaces the folder's defaults whole ({} clears them). Not besidedefaults_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 asstored, so a save of the fields one client changed never writes back what another changed meanwhile. voice is laid field by field thesame way ( voice: null unsets the whole voice). Not besidedefaults. |
devices_hidden |
boolean | null false shows a folder that a device's delete hid from devices tothem again; the owner's alone. true is refused (400): a device'sdelete 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
| Status | Description | ||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json FolderPatched
Fields of FolderPatched
| ||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/chat/api/folders/{id}/currentGet 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
| Name | In | Description |
|---|---|---|
idrequired | path | 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
| Status | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json CurrentThread
Fields of CurrentThread
| ||||||||
default |
Error.
application/json ApiError |
/chat/api/folders/{id}/deleteDelete 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
Request body required
application/json: object
threadsrequired |
ThreadsFate |
Responses
| Status | Description | ||
|---|---|---|---|
200 |
OK.
application/json Ack
Fields of Ack
| ||
default |
Error.
application/json ApiError |
/chat/api/folders/{id}/exportExport 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
archived | query | string |
format | query | string |
Responses
| Status | Description |
|---|---|
200 |
OK.
application/zip string (binary) |
default |
Error.
application/json ApiError |
/chat/api/knowledge/basesList 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
| Status | Description | ||
|---|---|---|---|
200 |
OK.
application/json ChatKnowledgeBases
Fields of ChatKnowledgeBases
| ||
default |
Error.
application/json ApiError |
/chat/api/knowledge/files/{id}/originalDownload 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
Responses
| Status | Description |
|---|---|
200 |
OK.
*/* string (binary) |
default |
Error.
application/json ApiError |
/chat/api/knowledge/files/{id}/textRead 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
chunk | query | string | null |
sha | query | string | null |
span_end | query | integer | null |
span_start | query | integer | null |
Responses
| Status | Description | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json ChatKnowledgeSource
Fields of ChatKnowledgeSource
| ||||||||||||||
default |
Error.
application/json ApiError |
/chat/api/media/defaultsThe 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
| Name | In | Description |
|---|---|---|
folder | query | integer | null |
thread | query | integer | null |
Responses
| Status | Description | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json MediaDefaultsView
Fields of MediaDefaultsView
| ||||||||||||||
default |
Error.
application/json ApiError |
/chat/api/profilesList 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
| Status | Description | ||||
|---|---|---|---|---|---|
200 |
OK.
application/json ProfileList
Fields of ProfileList
| ||||
default |
Error.
application/json ApiError |
/chat/api/profilesCreate 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
| Status | Description | ||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json Profile
Fields of Profile
| ||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/chat/api/profiles/previewPreview 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
| Status | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json PreviewAnswer
Fields of PreviewAnswer
| ||||||||
default |
Error.
application/json ApiError |
/chat/api/profiles/speakSpeak 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
| Status | Description |
|---|---|
200 |
OK.
audio/wav string (binary) |
default |
Error.
application/json ApiError |
/chat/api/profiles/testTest 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
| Status | Description | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json TestAnswer
Fields of TestAnswer
| ||||||||||||||||||
default |
Error.
application/json ApiError |
/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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
Responses
| Status | Description | ||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json Profile
Fields of Profile
| ||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/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
| Name | In | Description |
|---|---|---|
idrequired | path | 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
| Status | Description | ||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json Profile
Fields of Profile
| ||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/chat/api/profiles/{id}/deleteDelete 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
Responses
| Status | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json ProfileDeleted
Fields of ProfileDeleted
| ||||||||
default |
Error.
application/json ApiError |
/chat/api/profiles/{id}/resetReset 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
Responses
| Status | Description | ||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json Profile
Fields of Profile
| ||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/chat/api/searchSearch the Chat
Capability chat, open to: device, owner
Full-text search over thread titles, message text and the names of sent attachments, in pages of 50 threads, each with up to three of its best hits. Temporary threads are never searched. A device key's search leaves out Admin Chat threads, and names no thread as being in a folder it cannot see. A query shorter than two characters, or archived other than 0, 1 or all, is a 400 bad_request.
Parameters
| Name | In | Description |
|---|---|---|
archived | query | string |
folder | query | integer | null |
offset | query | integer | null |
q | query | string |
Responses
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/json SearchPage
Fields of SearchPage
| ||||||
default |
Error.
application/json ApiError |
/chat/api/settingsRead 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
| Status | Description | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json ChatSettings
Fields of ChatSettings
| ||||||||||||||||||
default |
Error.
application/json ApiError |
/chat/api/threadsList 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
| Name | In | Description |
|---|---|---|
archived | query | string |
Responses
| Status | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json ThreadList
Fields of ThreadList
| ||||||||
default |
Error.
application/json ApiError |
/chat/api/threadsCreate 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'sown 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
| Status | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json Thread
Fields of Thread
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/chat/api/threads/rowsRead 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
| Name | In | Description |
|---|---|---|
ids | query | string |
Responses
| Status | Description | ||
|---|---|---|---|
200 |
OK.
application/json ThreadRows
Fields of ThreadRows
| ||
default |
Error.
application/json ApiError |
/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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
Responses
| Status | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json ThreadDetail
Fields of ThreadDetail
| ||||||||
default |
Error.
application/json ApiError |
/chat/api/threads/{id}/answerAnswer 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
Request body required
application/json: object
speak |
boolean Read the answer aloud as it streams, as a send's speak. Default false. |
Responses
| Status | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
An event stream.
text/event-stream string14 event types
One of 6 shapesToolStartFrame Fields of ToolStartFrame
ToolArgsFrame Fields of ToolArgsFrame
ToolReadyFrame Fields of ToolReadyFrame
ApprovalRequest Fields of ApprovalRequest
ToolResultFrame Fields of ToolResultFrame
ToolProgressFrame Fields of ToolProgressFrame
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/chat/api/threads/{id}/approvalsDecide 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
| Name | In | Description |
|---|---|---|
idrequired | path | 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
| Status | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
An event stream.
text/event-stream string14 event types
One of 6 shapesToolStartFrame Fields of ToolStartFrame
ToolArgsFrame Fields of ToolArgsFrame
ToolReadyFrame Fields of ToolReadyFrame
ApprovalRequest Fields of ApprovalRequest
ToolResultFrame Fields of ToolResultFrame
ToolProgressFrame Fields of ToolProgressFrame
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/chat/api/threads/{id}/archiveArchive 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
Request body required
application/json: object
archivedrequired |
boolean Archive (true) the thread by hand, or restore it. |
Responses
| Status | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json Thread
Fields of Thread
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/chat/api/threads/{id}/attachmentsUpload 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
namerequired | query | string |
Request body required
application/octet-stream: string (binary)
Responses
| Status | Description | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json AttachmentMeta
Fields of AttachmentMeta
| ||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/chat/api/threads/{id}/continueContinue 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
Request body
application/json: object
speak |
boolean Read the answer aloud as it streams. |
Responses
| Status | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
An event stream.
text/event-stream string14 event types
One of 6 shapesToolStartFrame Fields of ToolStartFrame
ToolArgsFrame Fields of ToolArgsFrame
ToolReadyFrame Fields of ToolReadyFrame
ApprovalRequest Fields of ApprovalRequest
ToolResultFrame Fields of ToolResultFrame
ToolProgressFrame Fields of ToolProgressFrame
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/chat/api/threads/{id}/deleteDelete 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
Responses
| Status | Description | ||
|---|---|---|---|
200 |
OK.
application/json Ack
Fields of Ack
| ||
default |
Error.
application/json ApiError |
/chat/api/threads/{id}/exportExport 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
archived | query | string |
format | query | string |
Responses
| Status | Description | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json ChatExport
Fields of ChatExport
text/markdown; charset=utf-8 string (binary) | ||||||||||||||
default |
Error.
application/json ApiError |
/chat/api/threads/{id}/media/{call_id}/cancelCancel 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
call_idrequired | path | string |
Responses
| Status | Description | ||||
|---|---|---|---|---|---|
200 |
OK.
application/json MediaCancelled
Fields of MediaCancelled
| ||||
default |
Error.
application/json ApiError |
/chat/api/threads/{id}/messages/{mid}/deleteDelete 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
midrequired | path | integer |
Responses
| Status | Description | ||
|---|---|---|---|
200 |
OK.
application/json Ack
Fields of Ack
| ||
default |
Error.
application/json ApiError |
/chat/api/threads/{id}/messages/{mid}/editEdit 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
midrequired | path | 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 theones it had; absent keeps them. Ignored for a reply. |
origin |
string | null A user message's new origin (origin of a send): where the userwrites 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
| Status | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json ReplyEdited
Fields of ReplyEdited
text/event-stream string15 event types
One of 6 shapesToolStartFrame Fields of ToolStartFrame
ToolArgsFrame Fields of ToolArgsFrame
ToolReadyFrame Fields of ToolReadyFrame
ApprovalRequest Fields of ApprovalRequest
ToolResultFrame Fields of ToolResultFrame
ToolProgressFrame Fields of ToolProgressFrame
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/chat/api/threads/{id}/messages/{mid}/regenerateAnswer 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
midrequired | path | integer |
Request body
application/json: object
speak |
boolean Read the answer aloud as it streams. |
Responses
| Status | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
An event stream.
text/event-stream string15 event types
One of 6 shapesToolStartFrame Fields of ToolStartFrame
ToolArgsFrame Fields of ToolArgsFrame
ToolReadyFrame Fields of ToolReadyFrame
ApprovalRequest Fields of ApprovalRequest
ToolResultFrame Fields of ToolResultFrame
ToolProgressFrame Fields of ToolProgressFrame
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/chat/api/threads/{id}/messages/{mid}/speakRead 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
midrequired | path | integer |
Responses
| Status | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
An event stream.
text/event-stream string6 event types
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/chat/api/threads/{id}/moveMove 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
Request body required
application/json: object
folder_id |
integer | null The target folder; null takes the thread out of any folder. |
Responses
| Status | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json Thread
Fields of Thread
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/chat/api/threads/{id}/persistKeep 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
Responses
| Status | Description | ||||
|---|---|---|---|---|---|
200 |
OK.
application/json ThreadKept
Fields of ThreadKept
| ||||
default |
Error.
application/json ApiError |
/chat/api/threads/{id}/pinPin 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
Request body required
application/json: object
pinnedrequired |
boolean Pin (true) or unpin the thread. Pinning an archived thread alsorestores it. |
Responses
| Status | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json Thread
Fields of Thread
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/chat/api/threads/{id}/sendSend 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
| Name | In | Description |
|---|---|---|
idrequired | path | 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 messagecan 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 messagesays 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
| Status | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
An event stream.
text/event-stream string15 event types
One of 6 shapesToolStartFrame Fields of ToolStartFrame
ToolArgsFrame Fields of ToolArgsFrame
ToolReadyFrame Fields of ToolReadyFrame
ApprovalRequest Fields of ApprovalRequest
ToolResultFrame Fields of ToolResultFrame
ToolProgressFrame Fields of ToolProgressFrame
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/chat/api/threads/{id}/settingsChange 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
| Name | In | Description |
|---|---|---|
idrequired | path | 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 theChat'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 ([] detachesall). 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 modelenum ( "" for none), or the voice. A name the tool cannot use forthis caller is a 400 bad_request; one the thread already holdspasses, 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; nullfor 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, nullclears 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
| Status | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json SettingsAck
Fields of SettingsAck
| ||||||||
default |
Error.
application/json ApiError |
/chat/api/threads/{id}/speech/stopStop 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
Responses
| Status | Description | ||||
|---|---|---|---|---|---|
200 |
OK.
application/json SpeechStopped
Fields of SpeechStopped
| ||||
default |
Error.
application/json ApiError |
/chat/api/threads/{id}/tasksList 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
Responses
| Status | Description | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json array of ThreadTask Fields of ThreadTask
| ||||||||||||||||||||
default |
Error.
application/json ApiError |
/chat/api/threads/{id}/tasks/{task}/cancelCancel 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
taskrequired | path | integer |
Responses
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/json TaskCancelled
Fields of TaskCancelled
| ||||||
default |
Error.
application/json ApiError |
/chat/api/threads/{id}/titleRename 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
| Name | In | Description |
|---|---|---|
idrequired | path | 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
| Status | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json Thread
Fields of Thread
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/chat/api/threads/{id}/transcribeTranscribe 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
Request body required
audio/wav: string (binary)
Responses
| Status | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json Dictation
Fields of Dictation
Headers: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
| ||||||||||||
default |
Error.
application/json ApiErrorHeaders: x-lmgw-candidate, x-lmgw-fallback, x-lmgw-fallback-chain, x-lmgw-fallback-reason
|
/chat/api/threads/{id}/voice/warmWarm 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
| Name | In | Description |
|---|---|---|
idrequired | path | integer |
Request body required
application/json: object
stagesrequired |
array of string The stages to warm, each named once and in this order: asr, ttsand chat (the thread's own model). Empty or an unknown name is400 bad_request. |
Responses
| Status | Description | ||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
An event stream.
text/event-stream string3 event types
| ||||||||||||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/chat/api/toolsList 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
| Status | Description |
|---|---|
200 |
OK.
|
default |
Error.
application/json ApiError |
/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
| Name | In | Description |
|---|---|---|
labelrequired | path | string |
Responses
| Status | Description | ||||
|---|---|---|---|---|---|
200 |
OK.
application/json ChatToolDetail
Fields of ChatToolDetail
| ||||
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.
/transfers/api/targetsWho 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
| Name | In | Description |
|---|---|---|
app_idrequired | query | string |
Responses
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/json Targets
Fields of Targets
| ||||||
default |
Error.
application/json ApiError |
/transfers/api/transfersList 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
| Name | In | Description |
|---|---|---|
role | query | TransferRole | null |
Responses
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/json TransferList
Fields of TransferList
| ||||||
default |
Error.
application/json ApiError |
/transfers/api/transfersOffer 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 invisiblecharacters, 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
| Status | Description | ||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
201 |
OK.
application/json Transfer
Fields of Transfer
| ||||||||||||||||||||||||||||||
409 |
Error, with this body rather than the default one.
application/json TransferRefusal
Fields of TransferRefusal
| ||||||||||||||||||||||||||||||
507 |
Error, with this body rather than the default one.
application/json TransferRefusal
Fields of TransferRefusal
| ||||||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/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
| Name | In | Description |
|---|---|---|
idrequired | path | string |
Responses
| Status | Description | ||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json Transfer
Fields of Transfer
| ||||||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/transfers/api/transfers/{id}/cancelCancel 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
| Name | In | Description |
|---|---|---|
idrequired | path | string |
Responses
| Status | Description | ||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json Transfer
Fields of Transfer
| ||||||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/transfers/api/transfers/{id}/contentDownload 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
| Name | In | Description |
|---|---|---|
idrequired | path | string |
Responses
| Status | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/octet-stream string (binary) | ||||||||||
409 |
Error, with this body rather than the default one.
application/json TransferRefusal
Fields of TransferRefusal
| ||||||||||
507 |
Error, with this body rather than the default one.
application/json TransferRefusal
Fields of TransferRefusal
| ||||||||||
default |
Error.
application/json ApiError |
/transfers/api/transfers/{id}/contentUpload 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
| Name | In | Description |
|---|---|---|
idrequired | path | string |
Request body required
application/octet-stream: string (binary)
Responses
| Status | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json ContentReceived
Fields of ContentReceived
| ||||||||||
409 |
Error, with this body rather than the default one.
application/json TransferRefusal
Fields of TransferRefusal
| ||||||||||
507 |
Error, with this body rather than the default one.
application/json TransferRefusal
Fields of TransferRefusal
| ||||||||||
default |
Error.
application/json ApiError |
/transfers/api/transfers/{id}/declineDecline 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
| Name | In | Description |
|---|---|---|
idrequired | path | string |
Responses
| Status | Description | ||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json Transfer
Fields of Transfer
| ||||||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/transfers/api/transfers/{id}/receivedSay 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
| Name | In | Description |
|---|---|---|
idrequired | path | string |
Responses
| Status | Description | ||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json Transfer
Fields of Transfer
| ||||||||||||||||||||||||||||||
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.
/devices/enrolEnrol 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 theowner'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. Secretuntil used. |
Responses
| Status | Description | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
201 |
OK.
application/json Enrolment
Fields of Enrolment
| ||||||||||||||||
default |
Error.
application/json ApiError |
Ops
Routing ops
/api/op/alias_setCreate 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 capabilityfacts 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 asmodel_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
| Status | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json RowSaved
Fields of RowSaved
| ||||||||||
default |
Error.
application/json ApiError |
/api/op/candidate_alias_setCreate, 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
| Status | Description | ||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json One of 2 shapesCandidateAliasPreview Fields of CandidateAliasPreview
action: preview.CandidateAliasSaved Fields of CandidateAliasSaved
action: create, update, enable, disable or delete. | ||||||||||||||||||||||||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/api/op/model_setCreate, 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
| Status | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json RowSaved
Fields of RowSaved
| ||||||||||
default |
Error.
application/json ApiError |
/api/op/model_visibilityHide 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
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/json ModelVisibilitySaved
Fields of ModelVisibilitySaved
| ||||||
default |
Error.
application/json ApiError |
/api/op/upstream_quota_clearForget 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
| Status | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json RowSaved
Fields of RowSaved
| ||||||||||
default |
Error.
application/json ApiError |
/api/op/upstream_setCreate, 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
| Status | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json RowSaved
Fields of RowSaved
| ||||||||||
default |
Error.
application/json ApiError |
/api/op/upstream_set_fullCreate 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 anopenai_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.cppserver); llama_cpp is llama_server only; anthropic is generic orllama_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 toopenai_compatible upstreams only; on any other protocol it is refusedwhen turned on and switched off when the row leaves openai_compatible. Default null. |
timeout_ms |
integer | null Default null. |
Responses
| Status | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json RowSaved
Fields of RowSaved
| ||||||||||
default |
Error.
application/json ApiError |
/api/op/upstream_testTest 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
| Status | Description | ||||
|---|---|---|---|---|---|
200 |
OK.
application/json UpstreamTested
Fields of UpstreamTested
| ||||
default |
Error.
application/json ApiError |
Model ops
/api/op/audio_model_setCreate, 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
| Status | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json AudioModelSaved
Fields of AudioModelSaved
| ||||||||||
default |
Error.
application/json ApiError |
/api/op/aux_model_setCreate, 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
| Status | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json AuxModelSaved
Fields of AuxModelSaved
| ||||||||||||
default |
Error.
application/json ApiError |
/api/op/image_model_setCreate, 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
| Status | Description | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json ImageModelSaved
Fields of ImageModelSaved
| ||||||||||||||||
default |
Error.
application/json ApiError |
/api/op/local_model_setCreate, 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 itunchanged; an empty list is no override either, and clear reverts apreviously 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 setoverride 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
| Status | Description | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json LocalModelSaved
Fields of LocalModelSaved
| ||||||||||||||
default |
Error.
application/json ApiError |
/api/op/local_model_testLoad 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
| Status | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json One of 5 shapesLadderTest Fields of LadderTest
ImageTestPassed Fields of ImageTestPassed
ModelTestFailed Fields of ModelTestFailed
any any | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/api/op/voice_generateRender 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
| Status | Description | ||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json VoiceRound
Fields of VoiceRound
| ||||||||||||||||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/api/op/voice_sample_saveSave 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
| Status | Description | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json VoiceSampleSaved
Fields of VoiceSampleSaved
| ||||||||||||||||
default |
Error.
application/json ApiError |
/api/op/voice_transcribeTranscribe 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
| Status | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json VoiceTranscribed
Fields of VoiceTranscribed
| ||||||||||
default |
Error.
application/json ApiError |
Runtime ops
/api/op/containerControl 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
| Status | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json One of 8 shapesGroupApplied Fields of GroupApplied
action: apply.GroupStarted Fields of GroupStarted
action: start.GroupRestarted Fields of GroupRestarted
action: restart.GroupStopped Fields of GroupStopped
action: stop.GroupStatus Fields of GroupStatus
action: status.ModelLogs Fields of ModelLogs
action: logs.ModelStatus Fields of ModelStatus
action: status.ModelDone Fields of ModelDone
action: start, stop, restart or apply. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/api/op/hold_setEngage 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
| Status | Description | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json HoldSet
Fields of HoldSet
| ||||||||||||||||
default |
Error.
application/json ApiError |
/api/op/job_cancelCancel 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
| Status | Description | ||||
|---|---|---|---|---|---|
200 |
OK.
application/json MessageAck
Fields of MessageAck
| ||||
default |
Error.
application/json ApiError |
/api/op/machine_checkCheck 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
| Status | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json MachineCheck
Fields of MachineCheck
| ||||||||||||
default |
Error.
application/json ApiError |
/api/op/machine_settings_fitSwitch 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 (thesettings item's action, or an answer without confirm), as theywere 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, andthe answer says what the switch would change. Default null. |
fitrequired |
SettingsFit Which card's settings to switch to. |
Responses
| Status | Description | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json MachineSettingsFit
Fields of MachineSettingsFit
| ||||||||||||||||||
default |
Error.
application/json ApiError |
Download ops
/api/op/audio_catalogRefresh 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
| Status | Description | ||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json One of 2 shapesAudioCatalogRefreshed Fields of AudioCatalogRefreshed
action: refresh.AudioCatalogInstall Fields of AudioCatalogInstall
action: download. | ||||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/api/op/hf_addDownload 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
| Status | Description | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json HfAddResult
Fields of HfAddResult
| ||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/api/op/hf_setRe-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
| Status | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json One of 2 shapesMessageAck Fields of MessageAck
action: redownload | cancel | delete.HfUpdatesChecked Fields of HfUpdatesChecked
action: check_updates. | ||||||||||
default |
Error.
application/json ApiError |
/api/op/image_recipe_addQueue 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
| Status | Description | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json ImageRecipeAddResult
Fields of ImageRecipeAddResult
| ||||||||||||||||||||
default |
Error.
application/json ApiError |
/api/op/image_recipesList 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
| Status | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json ImageRecipes
Fields of ImageRecipes
| ||||||||||||
default |
Error.
application/json ApiError |
/api/op/image_upscaler_addQueue 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
| Status | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json ImageUpscalerAddResult
Fields of ImageUpscalerAddResult
| ||||||||||||
default |
Error.
application/json ApiError |
/api/op/model_findFind 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
| Status | Description | ||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json ModelFind
Fields of ModelFind
| ||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/api/op/model_fit_againFit 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
| Status | Description | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json ModelFitAgain
Fields of ModelFitAgain
| ||||||||||||||||||
default |
Error.
application/json ApiError |
/api/op/model_getGet 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
| Status | Description | ||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json ModelGetStarted
Fields of ModelGetStarted
| ||||||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/api/op/model_get_statusHow 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
| Status | Description | ||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json ModelGetStatus
Fields of ModelGetStatus
| ||||||||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
Settings ops
/api/op/realtime_budgetSize 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
| Status | Description | ||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json RealtimeBudget
Fields of RealtimeBudget
| ||||||||||||||||||||||
default |
Error.
application/json ApiError |
/api/op/settings_setChange 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, anaccess 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
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/json SettingsSaved
Fields of SettingsSaved
| ||||||
default |
Error.
application/json ApiError |
/api/op/settings_set_fullChange 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 wouldshadow 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 scriptstep 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 itfor 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 TCPkeep-alive timer). Default null. |
chat_feed_keepalive_s |
integer | null Seconds between the Chat feed's keep-alive comments, from 1 tochat_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 everyrecord. 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'smodel 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 ownpurge_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 audiowhen 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 likehf_token: a non-empty value replaces that host's token, an empty onekeeps 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 patchsettings_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
| Status | Description | ||||
|---|---|---|---|---|---|
200 |
OK.
application/json MessageAck
Fields of MessageAck
| ||||
default |
Error.
application/json ApiError |
/api/op/update_checkCheck 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
| Status | Description | ||||
|---|---|---|---|---|---|
200 |
OK.
application/json MessageAck
Fields of MessageAck
| ||||
default |
Error.
application/json ApiError |
Tool ops
/api/op/mcp_server_setCreate, 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
| Status | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json McpServerSaved
Fields of McpServerSaved
| ||||||||
default |
Error.
application/json ApiError |
/api/op/tool_setEnable 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
| Status | Description | ||||
|---|---|---|---|---|---|
200 |
OK.
application/json MessageAck
Fields of MessageAck
| ||||
default |
Error.
application/json ApiError |
Key ops
/api/op/device_ca_rotateReplace 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
| Status | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json DeviceCaRotated
Fields of DeviceCaRotated
| ||||||||
default |
Error.
application/json ApiError |
/api/op/device_confirmConfirm 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
| Status | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json DeviceConfirmed
Fields of DeviceConfirmed
| ||||||||||||
default |
Error.
application/json ApiError |
/api/op/device_tokenGive 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
| Status | Description | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json DevicePaired
Fields of DevicePaired
| ||||||||||||||||||
default |
Error.
application/json ApiError |
/api/op/device_token_endEnd 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
| Status | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json DeviceTokenEnded
Fields of DeviceTokenEnded
| ||||||||||
default |
Error.
application/json ApiError |
/api/op/key_createCreate 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
| Status | Description | ||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json One of 2 shapesKeyCreated Fields of KeyCreated
kind: client (or key, or none) and kind: owner.DevicePaired Fields of DevicePaired
kind: device. | ||||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/api/op/key_deleteRevoke 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
| Status | Description | ||||
|---|---|---|---|---|---|
200 |
OK.
application/json MessageAck
Fields of MessageAck
| ||||
default |
Error.
application/json ApiError |
/api/op/key_revealShow 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
| Status | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json KeySecret
Fields of KeySecret
| ||||||||||
default |
Error.
application/json ApiError |
/api/op/key_rotateMint 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
| Status | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json KeySecret
Fields of KeySecret
| ||||||||||
default |
Error.
application/json ApiError |
/api/op/key_setChange 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 toolscope'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 readingexpiry 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 andfolders with the self-admin toolset and the lmgw label in its toolscope; 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 thedevice 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
| Status | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json KeySaved
Fields of KeySaved
| ||||||||||
default |
Error.
application/json ApiError |
Usage & pricing ops
/api/op/price_deleteDelete 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
| Status | Description | ||||
|---|---|---|---|---|---|
200 |
OK.
application/json IdAck
Fields of IdAck
| ||||
default |
Error.
application/json ApiError |
/api/op/price_setSet 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
| Status | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json PriceSaved
Fields of PriceSaved
| ||||||||||||
default |
Error.
application/json ApiError |
/api/op/prices_syncRe-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
| Status | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json PriceSyncSummary
Fields of PriceSyncSummary
| ||||||||||
default |
Error.
application/json ApiError |
Stored-response ops
/api/op/response_chain_deleteDelete 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
| Status | Description | ||||
|---|---|---|---|---|---|
200 |
OK.
application/json MessageAck
Fields of MessageAck
| ||||
default |
Error.
application/json ApiError |
/api/op/responses_gcEvict 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
| Status | Description | ||||
|---|---|---|---|---|---|
200 |
OK.
application/json MessageAck
Fields of MessageAck
| ||||
default |
Error.
application/json ApiError |
Backends & build ops
/api/op/build_check_mergeCheck 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
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/json CheckMergeReport
Fields of CheckMergeReport
| ||||||
default |
Error.
application/json ApiError |
/api/op/build_envWhat the build editor needs when it opens
Capability admin, open to: owner
Responses
| Status | Description | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json BuildEnv
Fields of BuildEnv
| ||||||||||||||||
default |
Error.
application/json ApiError |
/api/op/build_getOne 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
| Status | Description |
|---|---|
200 |
OK.
|
default |
Error.
application/json ApiError |
/api/op/build_promoteMove 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
| Status | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json PromoteResponse
Fields of PromoteResponse
| ||||||||
default |
Error.
application/json ApiError |
/api/op/build_resolvePreview 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
| Status | Description | ||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json ResolvedPreview
Fields of ResolvedPreview
| ||||||||||||||||||||||
default |
Error.
application/json ApiError |
/api/op/build_runStart 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
| Status | Description | ||||
|---|---|---|---|---|---|
200 |
OK.
application/json BuildRunStarted
Fields of BuildRunStarted
| ||||
default |
Error.
application/json ApiError |
/api/op/build_run_logRead 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
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/json RunLogChunk
Fields of RunLogChunk
| ||||||
default |
Error.
application/json ApiError |
/api/op/build_setCreate, 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
| Status | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json BuildSetResponse
Fields of BuildSetResponse
| ||||||||||
default |
Error.
application/json ApiError |
/api/op/build_updates_checkCheck 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
| Status | Description | ||
|---|---|---|---|
200 |
OK.
application/json BuildUpdatesResponse
Fields of BuildUpdatesResponse
| ||
default |
Error.
application/json ApiError |
/api/op/build_verifyRe-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
| Status | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json VerifyReport
Fields of VerifyReport
| ||||||||
default |
Error.
application/json ApiError |
/api/op/buildsList 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
| Status | Description | ||||
|---|---|---|---|---|---|
200 |
OK.
application/json BuildsResponse
Fields of BuildsResponse
| ||||
default |
Error.
application/json ApiError |
/api/op/container_image_deleteDelete 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
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/json ContainerImageDeleteResponse
Fields of ContainerImageDeleteResponse
| ||||||
default |
Error.
application/json ApiError |
/api/op/container_image_pullPull 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
| Status | Description | ||||
|---|---|---|---|---|---|
200 |
OK.
application/json ContainerImagePullStarted
Fields of ContainerImagePullStarted
| ||||
default |
Error.
application/json ApiError |
/api/op/container_image_pull_statusRead 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
| Status | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json ContainerImagePullStatus
Fields of ContainerImagePullStatus
| ||||||||||||
default |
Error.
application/json ApiError |
/api/op/container_image_tagAdd 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
| Status | Description | ||
|---|---|---|---|
200 |
OK.
application/json ContainerImageTagResponse
Fields of ContainerImageTagResponse
| ||
default |
Error.
application/json ApiError |
/api/op/container_imagesList 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
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/json ContainerImagesResponse
Fields of ContainerImagesResponse
| ||||||
default |
Error.
application/json ApiError |
/api/op/forge_prOne 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
| Status | Description | ||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json ForgePr
Fields of ForgePr
| ||||||||||||||||||||||
default |
Error.
application/json ApiError |
/api/op/forge_prsList 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
| Status | Description |
|---|---|
200 |
OK.
|
default |
Error.
application/json ApiError |
/api/op/forge_refsList 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
| Status | Description |
|---|---|
200 |
OK.
|
default |
Error.
application/json ApiError |
Benchmark ops
/api/op/bench_cancelCancel 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
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/json BenchDone
Fields of BenchDone
| ||||||
default |
Error.
application/json ApiError |
/api/op/bench_deleteDelete 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
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/json BenchDone
Fields of BenchDone
| ||||||
default |
Error.
application/json ApiError |
/api/op/bench_planPreview 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
| Status | Description | ||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json BenchPlan
Fields of BenchPlan
| ||||||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/api/op/bench_runOne 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
| Status | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json BenchRunDetail
Fields of BenchRunDetail
| ||||||||||
default |
Error.
application/json ApiError |
/api/op/bench_run_setEdit 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
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/json BenchDone
Fields of BenchDone
| ||||||
default |
Error.
application/json ApiError |
/api/op/bench_runsList 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
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/json BenchRunsResponse
Fields of BenchRunsResponse
| ||||||
default |
Error.
application/json ApiError |
/api/op/bench_startStart 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
| Status | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json BenchStarted
Fields of BenchStarted
| ||||||||
default |
Error.
application/json ApiError |
Agent ops
/api/op/agent_config_setSave 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
| Status | Description | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json AgentConfigSaved
Fields of AgentConfigSaved
| ||||||||||||||||
default |
Error.
application/json ApiError |
/api/op/agent_deleteRemove 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
| Status | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json AgentDeleted
Fields of AgentDeleted
| ||||||||||
default |
Error.
application/json ApiError |
/api/op/agent_dev_url_setPoint 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
| Status | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json AgentDevUrlSet
Fields of AgentDevUrlSet
| ||||||||||
default |
Error.
application/json ApiError |
/api/op/agent_duplicateCopy 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
| Status | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json AgentDuplicated
Fields of AgentDuplicated
| ||||||||||
default |
Error.
application/json ApiError |
/api/op/agent_enableEnable 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
| Status | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json AgentEnabled
Fields of AgentEnabled
| ||||||||||
default |
Error.
application/json ApiError |
/api/op/agent_installInstall 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
| Status | Description | ||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json AgentInstalled
Fields of AgentInstalled
| ||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/api/op/agent_open_chatOpen 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
| Status | Description | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json AgentChatOpened
Fields of AgentChatOpened
| ||||||||||||||||
default |
Error.
application/json ApiError |
/api/op/agent_pullFetch 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
| Status | Description | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json AgentPulled
Fields of AgentPulled
| ||||||||||||||||||||
default |
Error.
application/json ApiError |
/api/op/agent_reimportRe-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
| Status | Description | ||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json AgentReimported
Fields of AgentReimported
| ||||||||||||||||||||||
default |
Error.
application/json ApiError |
/api/op/agent_resetRestore 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
| Status | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json AgentReset
Fields of AgentReset
| ||||||||
default |
Error.
application/json ApiError |
/api/op/agent_runStart 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
| Status | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json AgentRunStarted
Fields of AgentRunStarted
| ||||||||||||
default |
Error.
application/json ApiError |
/api/op/agent_run_cancelAsk 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
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/json AgentRunCancelled
Fields of AgentRunCancelled
| ||||||
default |
Error.
application/json ApiError |
/api/op/agent_service_logRead 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
| Status | Description | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json AgentServiceLog
Fields of AgentServiceLog
| ||||||||||||||
default |
Error.
application/json ApiError |
/api/op/agent_service_startStart 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
| Status | Description | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json AgentServiceStarted
Fields of AgentServiceStarted
| ||||||||||||||
default |
Error.
application/json ApiError |
/api/op/agent_service_stopStop 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
| Status | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json AgentServiceStopped
Fields of AgentServiceStopped
| ||||||||||||
default |
Error.
application/json ApiError |
/api/op/agent_setInstall 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
| Status | Description | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json AgentImportReport
Fields of AgentImportReport
| ||||||||||||||||
default |
Error.
application/json ApiError |
/api/op/agent_token_getRead 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
| Status | Description | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json AgentTokenRead
Fields of AgentTokenRead
| ||||||||||||||||
default |
Error.
application/json ApiError |
/api/op/agent_token_rotateMint 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
| Status | Description | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json AgentTokenIssued
Fields of AgentTokenIssued
| ||||||||||||||||||||
default |
Error.
application/json ApiError |
/api/op/agents_restoreReinstall 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
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/json AgentsRestored
Fields of AgentsRestored
| ||||||
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.
/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
| Name | In | Description |
|---|---|---|
job_idrequired | path | integer |
Responses
| Status | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json AgentRunDetail
Fields of AgentRunDetail
| ||||||||||
default |
Error.
application/json ApiError |
/api/agents/runs/{job_id}/closeClose an agent run
Capability ledger, open to: agent. Changes state.
Closes a run this caller owns with its terminal status.
Parameters
| Name | In | Description |
|---|---|---|
job_idrequired | path | 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
| Status | Description | ||
|---|---|---|---|
200 |
OK.
application/json Ack
Fields of Ack
| ||
default |
Error.
application/json ApiError |
/api/agents/runs/{job_id}/eventsAppend 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
| Name | In | Description |
|---|---|---|
job_idrequired | path | integer |
Request body required
application/json: AgentRunEventsBody
application/x-ndjson: string
Responses
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/json AgentEventsApplied
Fields of AgentEventsApplied
| ||||||
default |
Error.
application/json ApiError |
/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
| Name | In | Description |
|---|---|---|
idrequired | path | string |
Responses
| Status | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json AgentDetail
Fields of AgentDetail
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/api/agents/{id}/runsList 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
| Name | In | Description |
|---|---|---|
idrequired | path | string |
Responses
| Status | Description | ||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
OK.
application/json array of AgentRunSummary Fields of AgentRunSummary
| ||||||||||||||||||||||||||||||||||
default |
Error.
application/json ApiError |
/api/agents/{id}/runsOpen 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
| Name | In | Description |
|---|---|---|
idrequired | path | string |
Request body required
application/json: object
phase |
string | null Default null. |
rows |
array of Row Default []. |
Responses
| Status | Description | ||||||
|---|---|---|---|---|---|---|---|
200 |
OK.
application/json AgentRunOpened
Fields of AgentRunOpened
| ||||||
409 |
Error, with this body rather than the default one.
application/json AgentRunConflict
Fields of AgentRunConflict
| ||||||
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'shello.self_admin and state.self_admin), the level set on a device
key (KeyRow.self_admin, and self_admin in key_create andkey_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 thecalls 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); Nonewhen 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'sapp 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 arow 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 thestored 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 thereview's values with the fallback last. |
setrequired |
integer | null The set the stored config names; None classifies with the modelcall, 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 | arrayformat is secret | model_alias | multiline | directory or empty, or
| fileQUESTION_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 whenportable. |
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. Absentwhen 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 itsupdated_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 stampedwithout 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_microand no tokens is a run that had nothing to price; Some(0) can alsocome 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 whennothing 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 isrunning. |
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 tosay. |
log_tail_linesrequired |
integer (uint) How many lines log_tail is at most, printed besideit 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 leftout 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'sown LMGW_APP_ORIGIN is the same origin *without* the slash — anorigin to concatenate onto, rather than an href. |
origin_resolvesrequired |
boolean <id>.<suffix> resolves on the machine lmgw is running on — the serverasked the resolver when it rendered this. False is not an error: the App tab prints the /etc/hosts line that fixes it, and Chrome andFirefox 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 thatspeaks 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'sown 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 Copytoken: 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 JSONobject with optional keys capabilities, max_output_tokens, notes. None = nooverride. |
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 thesame 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 bothcover the five letters of Nuova in the transcript. Absent, withchar_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 0for 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 onlysamples. |
start_sample |
integer | null start in samples of sample_rate: as the model answered, orcomputed 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) whosecatalog names an on-demand compaction type for the model ( context_editing.compaction): the field goes out as written andthe 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 goesout as written and the compaction block Anthropic answers withcomes 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 modeltakes it ( context_editing.supported is true); unpublished isfalse. |
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 islevels): 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 anAnthropic-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, whichthe Messages ingress refuses. |
compactionrequired |
AnthropicCompaction |
context_editing |
ContextEditingCaps | null Anthropic's context management (context_management on/v1/messages: context editing and threshold compaction, and thetop-level on-demand compaction), under a name of itsown because the Anthropic-shaped model entry puts Anthropic's context_management block beside lmgw's object. Present only on anAnthropic-protocol route, the one route that sends a request's context_management on as written; every other route leaves it outand 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, whoseingress 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 alocal audio model works in, whatever its task: speech, recognition, alignment. A request's language takes them (lmgw sends each in themodel's own spelling). Absent when the model's package names none as codes; see multilingual for a family that says only that itcovers 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 answerswith (llama.cpp's and OpenRouter's word). A client that checks llama.cpp's architecture.output_modalities for decisions readsthis list instead. Absent = unknown. |
pdf_inputrequired |
AnthropicSupport An Anthropic-protocol route (context_editing present) to a modelwhose catalog says pdf_input (input_modalities holds pdf): adocument block reaches it as the client wrote it, base64, URL orFiles API source (gateway design §6.1, "Anthropic blocks lmgw does not model"). false on every other route, which is sent nodocument block. |
reasoning |
ReasoningCaps | null |
server_toolsrequired |
AnthropicServerTools |
sourcerequired |
string Where the facts came from: gguf+config, catalog, config, orowner (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 readsoutput_config.format (and the older output_format) of typejson_schema. |
taskrequired |
string chat | embedding | rerank | decision (a decision model,answering on /v1/systemone) | tts | asr | an audio.cpp taskname | an image task | realtime (an OpenAI Realtime model, no lmgwroute). Determines endpoints. |
thinkingrequired |
AnthropicThinking |
tool_calls |
ToolCallCaps | null |
vision |
boolean | null input_modalities contains image. Redundant with the list onpurpose: 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 aninput_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 onthis model through lmgw; false when lmgw does not serve it yet ordoes not know. |
AnthropicThinking
thinking.
supportedrequired |
boolean The model reasons: reasoning.kind is toggle or levels, orfixed 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. Onan 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 modelthat 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 sayso in x-lmgw-reasoning-ignored. |
disabledrequired |
AnthropicSupport {"type": "disabled"} switches thinking off( reasoning.can_disable is true; on an Anthropic route, thecatalog's thinking.types.disabled). |
enabledrequired |
AnthropicSupport {"type": "enabled", "budget_tokens": n}: the budget reaches themodel. On an Anthropic route, which forwards the budget form as written: the model's catalog names the type ( reasoning.thinking_types). Elsewhere: reasoning.control namesx-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 lmgwbefore 2026-10-09, and from an ApprovalRequest read off a boundsession'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 andarguments 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 framescarry 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 madean action file (its act-<boot>-<n> id, the one its stream'sframes 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 doesnot 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 (animage or audio tool of a turn made it) or action (an image card'saction 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 familyhas them. |
options_summary |
string In the tool's full listing instead of options: where to get them. Neverin 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 fileswithout saying which package is the packages' serving_unclear; onethat 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 — howfinished 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'sown 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 andsession 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 theGPU 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 theGPU 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 isclamped 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 audioclass 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 modelsdir 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" resetsit. 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 coresfor 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_presetrequired | any |
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'sfigure while it belongs to the row's current configuration, Noneotherwise (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 ownbackend, else the class's). A running container keeps the placementit 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 (thismachine's physical cores, for a row switched to the CPU that names none) | logical_cpus (the same, where the core topology could notbe 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 onits 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 underaudio.catalog_revision = pinned, false under latest, which takesmain 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 isa 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 acommit), 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 packagewithout 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 sentenceper 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 ownserver.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 specpins, 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 bydefault — 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 partof 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 isfaster 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 GPUhold); 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 auxclass 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 thismachine'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'scontext 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 thismachine'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 countthe 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, elsea 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 flattenedRouterSettingsPatch, 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'sexact 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 notnamed 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'sexact 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 notnamed 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_labelsentry); 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'sscore_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 arestart). |
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 deletedsince. |
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 andmissing 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, withno_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 sayswhy), 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 tohave the cpuset cgroup controller (rootless: delegated touser@.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 = thisexplicit, 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: nomulti-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 androle 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 androle 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 imagelisting 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 aforeign 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 tohave the cpuset cgroup controller (rootless: delegated touser@.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 = thisexplicit, 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: nomulti-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 tohave the cpuset cgroup controller (rootless: delegated touser@.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 = thisexplicit, 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: nomulti-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 devinstance (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 isfalse) 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 nothingis 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 anddisable) 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, afallback 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 nothingis 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 withan 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 worthflagging. |
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 24hours. Some(0) is a realzero; None only ever means a frame cached from before this fieldexisted ( #[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 oflmgw'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, asit 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 ofa 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 notbe read. |
scored |
integer (uint) For rerank: how many documents came back scored. |
staticrequired |
StaticCaps The capabilities the gateway derived statically, the part /propsalso 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_toolsand 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 MCPserver) 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, aserver's tool prefix, else its name. |
statusrequired |
string A server's connection now: ready, connecting, error orstopped. A built-in toolset is ready when it offers tools andunavailable 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'stools; a server's tools as last listed, the owner'sswitched-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, inthe 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_refor 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 isthis 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 fallbackanswered, 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 windowshorter 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 applyclears. 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 becausean external image (a build.sh tag, a registry pull) may not carryit 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 firstcheck. |
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) theprovider says the model takes ( summarize, …), sorted: its catalog'scapabilities.compaction. lmgw sends the field on as written, andthe 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 themodel takes, all of which lmgw sends on ( clear_thinking_20251015,clear_tool_uses_20250919, compact_20260112, …), sorted. Acompaction edit's compaction answer block comes back as Anthropicsent it. Omitted when the provider names none. |
supported |
boolean | null The provider says whether the model takes context_management atall. 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_requiredmeans the corpus cannot be queried until it is re-embedded; truemeans 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 wasrecorded (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 nullthen. |
max_head_tokensrequired |
integer | null The header's decision.max_head_tokens: past it llama.cpp truncates aquestion and its options. |
n_ctx_slotrequired |
integer | null One slot's context as the running server's /props says; nulluntil a container has run. |
shaperequired |
DecisionShape | null |
threads_in_effectrequired |
integer | null The thread count its container runs with; null when llama-serverpicks. |
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, theupstream'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 amongits input modalities. |
staterequired |
string | null Its container's state (starting, ready, stopping); null whenno 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, theprice 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 nocriteria.)
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 nocriteria.)
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 aloop 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 windowshorter 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*), thelater 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 Devicescard copies. Public like the file ( 0644) and the pin; null whilethe CA is missing or its certificate cannot be read. |
createdrequired |
string | null The CA's creation day (its notBefore), RFC 3339 UTC; null withfp. |
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'sSubjectPublicKeyInfo: the pairing link's fp. null while the CA ismissing 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 thekey 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 loopbackand 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'sURL 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 theaddress 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'snumber 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_maxand 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: (the row and its first pairing token) and
devicedevice_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_minutesafter it was minted. |
urlsrequired |
array of string The device's lmgw URLs: https base URLs of the device listener, inthe 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), nullwhen 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 fromwhen 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, freetext, 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 theowner's confirmation in state enrolled, of the confirmed keyotherwise: 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 foranything; *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 alistener 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.* inGET /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 ([::], everyaddress) 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'snumber plus one; null when port is null and the HTTP port is65535 (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 ([::], everyaddress) 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 sessionand 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 cleanedup. |
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 countsnothing. |
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 thismachine 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, whichRetry or Resume goes on from (find-a-model design D135). None whilea 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 audiocatalog entry pins. None on a row from before it was recorded (amain 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 thatclaims 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 theedit 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 everyccache 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 nopower 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 isLlama 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 alreadypulling it. Its bytes are on the jobs feed ( done/total, andsize_note in its detail when the size is not known), andcontainer_image_pull_status reads how it ended. null unlessstate 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 madean action file (its act-<boot>-<n> id, the one its stream'sframes 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 doesnot 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 (animage or audio tool of a turn made it) or action (an image card'saction 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 notparse, 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 recordthat 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 oneof 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). Thehold 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); Nonewhen 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; nullfor the Chat's setting, 0 never. Set from the dashboard: a devicekey 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; nullfor the Chat's setting, 0 never. Set from the dashboard: a devicekey 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; nullfor the Chat's setting, 0 never. Set from the dashboard: a devicekey 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; nullfor the Chat's setting, 0 never. Set from the dashboard: a devicekey 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 firstcurrent call, after its thread was deleted, moved out of thefolder 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 startsa 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 openPR, 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; Nonewhen 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 thermalslowdown ( 0x20, 0x40) or power-brake slowdown (0x80). Idle, theapplications-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); theanswer 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 (thetopology 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 itsown (a frame is then bounded by host_max_frame_mb). Not 0together with host_max_frame_mb. A full-desktop screenshot is theexpected 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 devicethat stopped answering. |
task_poll_interval_srequired |
integer (uint32) Seconds between two tasks/get of an MCP task whose server suggestsno pollInterval of its own (MCP Tasks design §5.2); a server'sstatus 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 andRateLimit-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. Nonewithout 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 canactually 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 cloudone. 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 itsspelling 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 cloudone. 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 itsspelling 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 ormask 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 cloudone. 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 itsspelling 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 whenset); 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 acontainer 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 operatordeclared 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 resolveunder 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 resolveunder 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 truerenders 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 ofmodel / 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 classsettings' 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 itto 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); Noneis 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_overriderequired | any |
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 datadir, 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 andbuild_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'spath, which reports none. |
imagerequired |
string |
last_linerequired |
string |
old_idrequired |
string | null The image ID the reference named before the pull; None when it wasnot 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 wholeoutput, 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 inImageModel.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'sfiles value is. |
donerequired |
boolean A tracked download for it finished. |
download_idrequired |
integer | null Tracked download row id, when there is one — join againstGET /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'sUpscale 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 arunning_container or stopped_container that is one of lmgw's modelcontainers (read from its labels, else matched by its name) — with class, what the container op's apply recreates. None for acontainer that is no model's (an agent's, or anything else on the machine). |
ImageUseKind
How something is using an image: whatcontainer_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 forhf_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 wrapperKeyCreateAnswer 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 serverwrites. |
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 appoffer 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 thenfilters 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 withouta hosting grant. |
idrequired |
integer (int64) |
kindrequired |
string key | internal | agent | owner | device — an internalidentity 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 areopen, 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 forevery 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 whosedevice_tools grants the label, and each agent whose manifest namesit — 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 (italso changes it, and may register programs that run on the gateway's machine). Above off it sees and uses the Chat threads and foldersthat carry the self-admin toolset ( lmgw); at full it may alsoattach 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_microincludes too: their whole cost is still unknown. |
spent_unknown_tokensrequired |
integer (int64) The tokens of those unpriced requests, counted asspent_unknown_requests counts them. |
tool_scope_moderequired |
string all | allow | deny over exposed MCP tool names — which tools thekey sees on /mcp and may attach in a /v1/responses run. Only aclient 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 localmodel; 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 pinnedmodel; 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 requestsends it as <head>,<base64 of the bytes>; null for bytes that cameas bytes. |
hrefrequired |
string Where the bytes are: /labs/api/artifacts/{id} from the API, thefile'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 orno (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 withoutone. |
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 exampledev_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'sx-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); nullfor 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 itstext. |
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'sgenerate or edit. |
textrequired |
string | null The text the run was given: what was spoken, the prompt; nullwhen 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'sDecisionForm), 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 aslab-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 themodel 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 whenthat is a string, else its type (llama.cpp's numeric code onlyrepeats 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 stillhere, 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 islab-artifact:<id>. |
responserequired |
string | null The answer as received, as text; null when it was no text and is anoutput 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, oroptions.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 leavesllama-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 onik_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 |), 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 JSONobject with optional keys capabilities, max_output_tokens, notes. None = nooverride. |
enabledrequired |
boolean |
extra_run_argsrequired |
array | null Per-model podman run args override; None inherits the chatclass 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 JSONobject with optional keys capabilities, max_output_tokens, notes. None = nooverride. |
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-tripswith 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'scontext 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) inthe last 24 hours: background requests ( x-lmgw-background: on) themodel 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 thesechanges, after a confirmation that lists them, left andrunning. 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 sincelmgw 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'sHashedPlan), never over this answer: its sentences and sizes do notchange 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 forevery 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 forevery 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 requiredtools 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 comefrom 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'shosted 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 withit. Default null. |
host_max_message_mb |
integer | null In MiB; 0 = no bound of its own. Not 0 together withhost_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 nopollInterval; 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, anddetail 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 throughMediaDefaults::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 acall 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, andtotal_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).)
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 (afallback); 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 aplain 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 usermessages 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), whichthe model reads before the message's text. null when its clientsent 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 whennone 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. Absentotherwise. |
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 beforethe 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 thetop-level on-demand compaction), under a name of itsown because the Anthropic-shaped model entry puts Anthropic's context_management block beside lmgw's object. Present only on anAnthropic-protocol route, the one route that sends a request's context_management on as written; every other route leaves it outand 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 alocal audio model works in, whatever its task: speech, recognition, alignment. A request's language takes them (lmgw sends each in themodel's own spelling). Absent when the model's package names none as codes; see multilingual for a family that says only that itcovers 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 answerswith (llama.cpp's and OpenRouter's word). A client that checks llama.cpp's architecture.output_modalities for decisions readsthis list instead. Absent = unknown. |
reasoning |
ReasoningCaps | null |
sourcerequired |
string Where the facts came from: gguf+config, catalog, config, orowner (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 taskname | an image task | realtime (an OpenAI Realtime model, no lmgwroute). Determines endpoints. |
tool_calls |
ToolCallCaps | null |
vision |
boolean | null input_modalities contains image. Redundant with the list onpurpose: 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 answeredthat 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 arow 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 optionalgeneral.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.0or 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 notstart on the graphics card because of the computer, vram_queue_timeout, …), as the /v1 routes answer it; absent whenthe 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, asit 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 ofa 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: onlywhen 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. |
OpenLink
One open connection of a device.
callrequired |
string | null A voice link that is a WebRTC call (POST /v1/realtime/calls): thecall's id, as the status block's webrtc.calls lists it; null fora WebSocket session and for the other kinds. |
keepalive_srequired |
integer | null The keep-alive it asked for, in seconds: a feed's keepalive_s;null for the other kinds. |
peerrequired |
string | null The address it connected from (IP and port); null when lmgw didnot see one. |
sincerequired |
string When it opened (RFC 3339 UTC). |
OpenLinks
How many connections of one kind a device holds open.
countrequired |
integer (uint32) |
kindrequired |
string feed, voice or tools. |
linksrequired |
array of OpenLink Each of them, the oldest first (device link design §9.3): "feed (keep-alive 120 s, since 09:00, from 192.0.2.2)". |
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 clientcatalog 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 |
plannedrequired | any |
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): whatlocal_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.
currentrequired | any |
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'schat_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 holda decoding stream. |
n_slotsrequired |
integer (uint32) *N_slots*. |
needle_tokensrequired |
integer | null The needle probe's prompt length, *P_max* − 512; None when thecontext 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 windowshorter 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 saysit; 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 thefour 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 onevery 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 cachedpair, 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 theowner'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, atext 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 whentts_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 whentts_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 thelabel; 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 theexpected level (the fractional score) and the label. |
reliabilityrequired |
array of ReliabilityBin The non-empty ones of bins equal-width bins over the predictedprobability, lowest first: the winner's ( choice), the nearestlevel'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 isfull: 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 astage nothing is configured for. |
bytesrequired |
integer | null The expected footprint; None = unknown, and the total is then alower 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 (aserver lmgw does not manage) | cpu | shared (the same local modelas 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 textwhile the setting is unset. |
default_instructions_builtinrequired |
string The built-in voice-assistant prompt — what savingdefault_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). WebSocketonly: 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; ona 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 howlong 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'smaxaveragebitrate. 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 paireddevice'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'sextra_run_args.
asr_alias |
string | null The speech-to-text alias turns are transcribed with; "" = theChat'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'sown 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 theengine'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. Thelargest 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 chatalias, 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 bean alias whose task is tts, or vdes (a voice designed from thespeech 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 = theHTTP port's number, 0 = chosen by the OS, else 1 to 65535. Callsover 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 (whatstr0m 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 perrequest), levels (effort selectable per request). |
levels |
array of string Accepted effort values, least → most in the canonical order. Only forkind == "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 Anthropicupstream's catalog publishes them ( capabilities.thinking.types), inAnthropic'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 thelocal 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 notbe 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, theshare 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 thefile'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 onthe graphics card by both measures (find-a-model design §3.3), what local_model_plan with repo + file answers as its fit, lesswhat the list says once (D63): card is None where it is thelist'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, anddiffusion | checkpoint | vae | text_encoder | lora | upscaler | otherfor image. A string, not an enum, onboth 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 andpricing).
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 asfree — 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 wasshort), 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 notready on this computer) or engine_download (a local model's enginecould not be downloaded). None = no fallback; the fallback itselfis 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 matcheson, 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 aguarded unified-KV pool. None = not clamped — either the row is unguarded, or theclient'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 SSEframes, 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 withouta 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 fordockerfile. |
extrasrequired |
array of ResolvedExtra The extras the run merges, in order, each with its resolved SHA. Apr extra already merged upstream is skipped by the run and left outhere — 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, arevoked 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, notfrom this map. Default {}. |
error |
string | null |
id |
string item.id rendered. Empty marks the row errored — there is nostable 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" savesa 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 isunknown, it is no tool call, and it was answered or spent something (tokens or a measured quantity). false for a priced row, a toolcall, 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 haseverywhere else: it is -c, never the per-slot number. |
gguf_pathrequired |
string GGUF path relative to the models dir, exactly like the base row'sgguf_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 bederived (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 forevery 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 theread failed — warnings then says why. |
model_idrequired |
string |
owner |
string Whom the container runs for:"background" when a background candidate alias started it andforeground traffic has not claimed it since. None — absent from theframe — 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 CPUswitch): no VRAM, not stopped by the GPU hold. None — absent fromthe 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 rowwithout a ladder, and #[serde(default)] so a frame from before thisfield 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 thenits 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 thecaller 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 atsemantic_floor_window_ms; equal to the threshold turns the middleband 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 theserver_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 theengine 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 effectivesettings ( kv_unified, or parallel left on auto); None whenneither 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_ctxor 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 usesits 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 iscleared, 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 usesits 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 iscleared, 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 mappedonto 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 voiceis 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 themodel has answered once since lmgw started. |
streaming |
boolean | null stream_format (sse or audio, response_format: pcm) works onthis 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 theengine'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 theengine'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'sown 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 thismachine, 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 setsnone. |
localrequired |
boolean | null false for an alias served off this machine; null when the aliasdoes 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_jsonwrites 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 andit 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'slmgw.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'ssetting. |
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 ownconfiguration (never listed for a device key). |
last_message_atrequired |
integer | null When its newest message was written, in unix seconds; null for athread 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 adevice 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 whatthey 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'sdefault. |
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'sdefault. |
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 answersfor 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, andrealtime: 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'ssetting. |
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 ownconfiguration (never listed for a device key). |
last_message_atrequired |
integer | null When its newest message was written, in unix seconds; null for athread 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 adevice 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 whatthey 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'sdefault. |
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'sdefault. |
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 owndefault (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 owndefault (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": […]}}. Aname may be the tool's own or its prefixed one. read_only isrefused. A gated call stops the turn; POST 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": […]}}. Aname may be the tool's own or its prefixed one. read_only isrefused. A gated call stops the turn; POST 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'ssetting. |
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 ownconfiguration (never listed for a device key). |
last_message_atrequired |
integer | null When its newest message was written, in unix seconds; null for athread 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 adevice 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 whatthey 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'sdefault. |
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'sdefault. |
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 statednone. |
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 autoto 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 followthe 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 finaltimings.
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 templaterenders tools with none of the known markers. Informational. |
kindrequired |
string native (lmgw returns structured tool_calls), none (the templaterenders no tools; aux/audio rows), text (the template renders toolsin 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 thatclaim 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 forunloading, 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 notknown — …"). |
step |
integer (uint32) |
total_bytes |
integer (uint64) downloading: the download's whole size; absent when it is notknown. |
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 approvalframe follows. false for a call that runs (a resumed turn's decidedcalls 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 aslmgw: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 (resourceURIs namespaced as /mcp sends them; images in full — no bound oflmgw's own, a device's result is bounded by mcp.host_max_message_mbon 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 wasgiven 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 fallbackanswered, 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 iswhat 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 nextupload's range starts here), size from ready on, and how far itgot 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'sKeyRow 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 backrequests reaches.
callsrequired |
array of HostedCallCount Each billable call's output item type (web_search_call, …) with howmany 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, at0: 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 witha 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, orempty 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 theanswers 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, startingcheck failed: — a forge's rate limit (with its reset time), a remotethat 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 knownwithout fetching, "PR #1234 pushed", "PR #1234 closed unmerged","definition changed since last run (ref, extras)"). A PR the forgereports merged reads "PR #1234 merged upstream and contained in your only once the base is proven (locally, no fetch) toalready hold its merge or head commit; otherwise "PR #1234 merged — the same non-committal wording whether thatwas proven false or is simply unknown. |
ref_movedrequired |
boolean The base ref itself moved (a branch or tag; a pinned commit neverupdates). |
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 thatfound 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 emptymodel): it states its build and nothing about a model, so propscarries 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 isNone: 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 afixed 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 wasasked. |
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 (aprice per *input* image, not a generated one), web_search (no route carries a hosted search), and the fields lmgwdoes not model, such as internal_reasoning, image_output,overrides or discount. Also a request fee or cache rate that isnot a price ( "-1", unparseable). A model counted inunpriced_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 andscope, and a per_request row beside it where the catalog states afee. |
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 itsdecision, embedding, rerank, speech, transcription, image and video models too. Only an openai_compatible row of kind generic sendsit; 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 aregional *.api.openai.com one: lmgw sends it the OpenAI platform'sown 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 withprotocol llama_cpp or anthropic; audio_cpp (an externalaudio.cpp server) with openai_compatible. |
llama_factsrequired |
array of UpstreamLlamaFacts A llama_cpp row's server: what GET /props said, when, or why itis 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 lmgwask 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 kindgeneric; openai_compatible is every other OpenAI-shaped provider.llama_cpp is llama.cpp's own server (llama-server, ik_llama.cpp) andis 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 andaliases 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 synthesizedfrom /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_sincenothing 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 isobliged 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'sprompt_tokens carries, so fresh (uncached) input istokens_in - tokens_cached - tokens_cache_write and never a fourthstored 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 noPCM 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 ownchain 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 voiceclip 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, thespeech-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 replyfollows the user. |
seedrequired |
integer | null The thread's text-to-speech seed; null until its first use drawsone. |
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 abusy 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). falsewith 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, whichonly 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 lmgwhas 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 askipped 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 offirst_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 headerlacks 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 everyother 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 itsprocesses hold at least that much now), and for every other class. |
staterequired |
string starting | ready as the runtime registry holds it, or reserved fora 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 onNVIDIA, 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 byinactive_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 bytesso far. They hold no place in queue and nothing on the card; onceits 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'sframe. |
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_setresponse. 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 readfrom the driver. |
headroom_bytesrequired |
integer (uint64) |
hold_activerequired |
boolean The hold.active setting — hold is a switch onthe 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, byreason. With a measured free figure, free_bytes is the capacity'smeasured free memory — the devices' free memory, or with vram.budget_mb the budget less the devices' used memory — lessthese (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'skv_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 itcannot 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, whosefootprint is read at admission, after the download. |
phaserequired |
WaitPhase | null stage typed: what admission is doing for this request now. Absentfrom an older gateway's frame. |
positionrequired |
integer (uint) The 1-based place in the admission queue; 0 for an entry ofdownloading, 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'slmgw.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.bynames a client. |
idrequired |
string Its id, rtc_…: what POST /v1/realtime/calls/{call_id}/hanguptakes. |
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 whileclosing. |
jitter_buffer_msrequired |
number | null The latest playout report's jitter_buffer_ms (to 0.1): NetEQ's owndelay as the client's getStats gives it, the allowance seen fromthe phone. |
keyrequired |
string | null The key that made it (device:phone, owner:…); null for ananonymous 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, andwhile 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 thecall'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 theaddress, or the call driver's stop. |
grouprequired |
WebRtcGroup |
rulerequired |
string The rule that binds it, naming its settings: the plain listener'sbind_addr and realtime.webrtc_port, or the device listener'saddresses 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: thesetting 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. |