HTTP API: models

Katalog modelů, který distribuce deklaruje — dodavatelé, kanonické reference modelů, typované schopnosti, kontextová okna, životní cyklus — a vysvětlitelné směrování nad ním: co vybere uvedená potřeba, co za tím stojí a proč každý vyloučený model vypadl. Deklarovaná data; nic zde nevolá model ani nečte hodnotu přihlašovacího údaje.

Vykresleno z docs/generated/openapi.json, který spustitelný soubor generuje ze svého registru schopností a CI jej odmítne, je-li zastaralý. Surový dokument je na /openapi.json; běžící server servíruje stejný dokument na vlastní /openapi.json a Swagger UI na /swagger.

models

GET /api/v1/models models.list

Katalog modelů

Každý deklarovaný vendor a model, volitelně zúžený podle vendora, slova schopnosti nebo jednoho id či aliasu. Vendoři nesou, zda je nastavena proměnná s jejich pojmenovaným přihlašovacím údajem — jen přítomnost, nikdy hodnota. Pořadí je pořadí deklarace, které je i preferenčním pořadím směrování; zjištění samotného katalogu (duplicitní alias, nedeklarovaný vendor) jdou s sebou.

query
experimentální
vyžaduje se měření výkonu
proces cache (max_entries=4, ttl_seconds=5)
Nástroj MCP majordomus_models
Zdroj MCP {"name": "models", "uri": "majordomus://models"}
$ models list

Parametry dotazu

název	typ	povinné	popis	příklady
vendor	string	ne	Pouze tento dodavatel.	narrowed: "anthropic"
schopnost	string	ne	Pouze modely deklarující toto slovo schopnosti.	narrowed: "text"
id	string	ne	Jeden model, podle kanonického id nebo aliasu.	zúženo: "claude-opus-5"

Vyzkoušejte

Port je ten, který server zalogoval; 8741 je ten, o který žádá jako první. Hodnoty jsou první příklad operace.

curl -s "http://127.0.0.1:8741/api/v1/models?vendor=anthropic&capability=text&id=claude-opus-5"

Testováno v apps/majordomus-cli/tests/http_serve.rs, který přehrává routu s těmito hodnotami proti serveru na skutečném socketu.

Odpovědi

status	tělo	význam
200	ModelsReport	Katalog modelů: výsledek.
400	ErrorBody	`invalid_input`: Vstup neodpovídá schématu: parametr špatného typu, neznámý parametr nebo hodnota, kterou schopnost odmítne.
404	ErrorBody	`not_found`: Vstup pojmenovává něco, co repozitář nemá.
500	ErrorBody	`internal`: Schopnost selhala z vlastního důvodu; zpráva ho pojmenovává.
výchozí	ErrorBody	Jakékoli jiné selhání, které transport hlásí: 405 `method_not_allowed` pro jinou metodu na této cestě, 400 `invalid_input` pro tělo, které není objektem JSON.

GET /api/v1/models/route models.route

Nasměrovat potřebu na model

Rozhodne, který deklarovaný model uvedená potřeba vybere: první v pořadí deklarace, který splňuje každý požadavek, zbytek vyhovujících jako záložní řetězec a každý vyloučený model s první kontrolou, na které selhal. Čisté nad katalogem a vstupem — stejná otázka dostane stejnou odpověď a „proč“ je přímo v odpovědi.

query
experimentální
vyžaduje se měření výkonu
cache vypnuta
MCP nástroj majordomus_models_route
$ models route

Parametry dotazu

název	typ	povinné	popis	příklady
require	string	ne	Slova schopností, která model musí deklarovat, oddělená čárkami: `vision,tools`.	výchozí: "text"
min_context	integer (uint64)	ne	Nejmenší kontextové okno, tokeny.
vendor	string	ne	Pouze tento dodavatel.
local_only	boolean	ne	Jen lokální inference.
model	string	ne	Model pojmenovaný přímo, kanonickým id nebo aliasem — stále kontrolovaný vůči ostatním požadavkům.

Vyzkoušejte

Port je ten, který server zalogoval; 8741 je ten, o který žádá jako první. Hodnoty jsou první příklad operace.

curl -s "http://127.0.0.1:8741/api/v1/models/route?require=text"

Testováno v apps/majordomus-cli/tests/http_serve.rs, který přehrává routu s těmito hodnotami proti serveru na skutečném socketu.

Odpovědi

status	tělo	význam
200	RoutingDecision	Nasměrovat potřebu na model: výsledek.
400	ErrorBody	`invalid_input`: Vstup neodpovídá schématu: parametr špatného typu, neznámý parametr nebo hodnota, kterou schopnost odmítne.
404	ErrorBody	`not_found`: Vstup pojmenovává něco, co repozitář nemá.
500	ErrorBody	`internal`: Schopnost selhala z vlastního důvodu; zpráva ho pojmenovává.
výchozí	ErrorBody	Jakékoli jiné selhání, které transport hlásí: 405 `method_not_allowed` pro jinou metodu na této cestě, 400 `invalid_input` pro tělo, které není objektem JSON.

Schémata

Komponenty, které používají jen operace tohoto tagu. Každý řádek je pole daného typu, jeho doc komentář je popis; typ vlastněný jinou stránkou na ni odkazuje.

ExcludedModel

object

Jeden model, který nesplnil požadavky, a přesně proč.

vlastnost	typ	povinné	popis
model	string	ano	Kanonické id.
důvod	string	ano	První důvod, proč vypadla, v pořadí, v jakém kontroly běží.

Používá RoutingDecision

Inference

"remote" | "local"

Kde běží inference dodavatele.

remoteAPI po síti.
localRuntime na tomto stroji.

Používá VendorView

ModelEntry

object

Jeden model: kanonická reference, kterou tento repozitář používá, vlastní název od výrobce a jeho typované schopnosti. Slova schopností jsou data, která katalog deklaruje — spotřebitelé porovnávají se seznamem požadavků, nikdy s napevno zapsaným názvem.

vlastnost	typ	povinné	popis
id	string	ano	Kanonické id, jedinečné v katalogu: to, co pojmenovávají relace, konfigurace a směrování. Stabilní i když dodavatel přejmenuje.
vendor	string	ano	Dodavatel, který jej poskytuje.
native_id	string	ano	Vlastní identifikátor dodavatele, doslovně.
aliasy	array of string	ne	Další jména, která se překládají na tento model. Aliasy žijí tady a nikde jinde.
capabilities	array of string	ne	Typovaná slova schopností: `text`, `vision`, `tools`, `structured_output`, `reasoning`, `streaming`, `embeddings` — deklarovaný slovník, který katalog může rozšířit bez změny kódu.
context_window	integer \| null	ne	Kontextové okno, tokeny.
status	ModelStatus \| null → ModelStatus	ne	Stav životního cyklu, když ho katalog deklaruje. Chybějící je nedeklarováno: katalog připouští jen fakta s původem a směrování model stále zvažuje, ale nic nesmí říct, že je dostupný za katalog.
poznámka	string \| null	ne	Jeden řádek, který člověk potřebuje při výběru; nikdy ne ceny — cena, kterou nástroj nedokáže ověřit, je fakt, který nesmí uvádět (nic zde nevymýšlí data o nákladech).

Používá ModelsReport

ModelStatus

"available" | "preview" | "deprecated" | "retired"

Postavení modelu v jeho životním cyklu, jak ho deklaruje katalog. Neexistuje výchozí hodnota: položka katalogu, která žádné nedeklaruje, má nedeklarované postavení, což není tentýž fakt jako „dostupné“, a žádný čtenář ho tak nesmí vykreslit.

availableObecně dostupné.
previewPoužitelné, očekává se změna.
deprecatedStále servírováno, směrování to už nevybírá, pokud není uvedeno výslovně.
retiredPryč; ponecháno, aby odkaz starého záznamu stále vedl na řádek s příběhem.

Používá ModelEntry

ModelsReport

object

Odpověď models.list.

vlastnost	typ	povinné	popis
počet	integer (uint)	ano	Kolik modelů se shodovalo.
vendoruje	pole VendorView → VendorView	ano	Poskytovatelé, pořadí deklarace.
models	pole ModelEntry → ModelEntry	ano	Odpovídající modely v pořadí deklarace — což je pořadí preferencí směrování.
diagnostika	array of string	ne	Vlastní nálezy katalogu: duplicitní jména, nedeklarovaní dodavatelé. Prázdné je běžný případ.

Používá models.list

RoutingDecision

object

Odpověď směrování: co bylo vybráno, co za tím stojí, kdo vypadl a proč. Celé rozhodnutí se odvozuje z katalogu a požadavků — spusťte dvakrát, dostanete dvakrát totéž; není žádný stav, který by se konzultoval, a žádné zdraví, které by se hádalo.

vlastnost	typ	povinné	popis
vybráno	string \| null	ne	Kanonické id vybraného modelu; `None`, když nic nevyhovuje.
důvod	string \| null	ne	Proč byl vybraný model vybrán.
záložní varianty	array of string	ne	Modely, které také vyhovují, v pořadí preferencí: záložní řetězec.
vyloučeno	pole ExcludedModel → ExcludedModel	ne	Každý model, který nevyhověl, s důvodem.

Používá models.route

VendorView

object

Jeden dodavatel s údajem, zda je nakonfigurován jeho přihlašovací údaj — přítomnost pojmenované proměnné prostředí a nic víc. Žádná hodnota se nečte.

vlastnost	typ	povinné	popis
id	string	ano	Id dodavatele, jedinečné v katalogu.
název	string	ano	Lidský název.
odvození	Inference → Inference	ne	Kde běží inference: `remote` (API po síti) nebo `local` (runtime na tomto stroji). Zde typováno, aby `local_only` směrování byla data, ne test na jméno.
credential_env	string \| null	ne	Proměnná prostředí, jejíž přítomnost znamená, že je pověření nakonfigurováno. Žije zde jen název a hlásí se jen přítomnost — žádný kód tohoto crate hodnotu nečte a cache prostředí ji odmítá držet.
credential_configured	boolean \| null	ne	Zda je pojmenovaná proměnná s přihlašovacími údaji nastavena v prostředí tohoto procesu. `None`, když dodavatel žádnou proměnnou nepojmenovává.

Používá ModelsReport