API-Referenz

ollaya serve stellt zwei APIs auf http://localhost:11435 bereit:

• die native API unter /api/*, modelliert nach Ollamas API, für Entscheidungen und Modellverwaltung;
• die TypeSafe-kompatible API unter /v1/*, wire-identisch mit TypeSafe, sodass vorhandene TypeSafe-SDKs unverändert funktionieren. Siehe TypeSafe-Kompatibilität.

/api/push und /api/blobs/:digest sind reserviert und antworten 501 NOT_IMPLEMENTED. Ollamas Text-Endpunkte (/api/generate, /api/chat, /api/embed) antworten 404: Entscheidungsmodelle erzeugen nie Text.

Konventionen

• JSON. Anfrage- und Antwortkörper sind JSON-Objekte. Der Körper wird unabhängig von seinem Content-Type als JSON geparst, curl -d funktioniert also unverändert. Anfragen sind höchstens 8 MiB groß.
• Feldnamen sind snake_case. Unbekannte Anfragefelder werden ignoriert; null bedeutet abwesend.
• Modellnamen sind [host/][namespace/]model[:tag], ohne Beachtung der Groß-/Kleinschreibung. Ein fehlender Tag bedeutet latest. Antworten verwenden immer die kanonische Form, etwa laya:latest.
• Zahlen. Wahrscheinlichkeiten, Konfidenzen, score und noul werden auf 4 Nachkommastellen gerundet. Dauern sind ganze Zahlen in Nanosekunden; Zeitstempel sind RFC 3339 in UTC.
• Streaming. /api/pull und /api/create streamen zeilenweise getrenntes JSON, ein Objekt pro Zeile, und enden mit genau einem {"status":"success"} oder einer Fehlerzeile. Sende "stream": false für eine einzelne Antwort.
• Request-IDs. Jede Antwort trägt X-Request-Id, und /v1/*-Antworten zusätzlich x-typesafe-request-id. Eine gültige, vom Client gesendete X-Request-Id wird zurückgegeben.
• Nebenläufigkeit. Ein geladenes Modell führt jeweils eine Anfrage aus, und jede Anfrage beantwortet alle ihre Fragen in einem Durchlauf. Anfragen an dasselbe Modell werden in eine Warteschlange gestellt, mehr gleichzeitig zu senden wird also nicht schneller fertig; die Umlaufzeit jeder einzelnen enthält dann die Wartezeit. Stelle jede Frage zu einem Zustand in einer Anfrage. Verschiedene geladene Modelle laufen parallel.
• Keine impliziten Pulls. Kein Endpunkt lädt ein Modell als Nebenwirkung herunter. ollaya run lädt zuerst herunter; Anwendungen rufen /api/pull auf.

Fehler

Jeder Fehler hat an jedem Endpunkt diesen Körper:

{
  "error": "model \"laya:xl\" not found, try pulling it first",
  "code": "MODEL_NOT_FOUND"
}

Die Menge der Codes ist offen: Behandle einen unbekannten anhand seines HTTP-Status. Ein Validierungsfehler listet jedes Problem auf einmal auf:

{
  "error": "state: Field required; questions.urgency.score.criteria: List should have at least 2 items after validation, not 1",
  "code": "INVALID_REQUEST",
  "detail": [
    {"loc": ["body", "state"], "msg": "Field required", "type": "missing"},
    {
      "loc": ["body", "questions", "urgency", "score", "criteria"],
      "msg": "List should have at least 2 items after validation, not 1",
      "type": "too_short",
      "ctx": {"field_type": "List", "min_length": 2, "actual_length": 1}
    }
  ]
}

Sobald ein Stream begonnen hat, kommt ein Fehler als letzte Zeile in derselben Form, etwa {"error": "…", "code": "DIGEST_MISMATCH"}. Prüfe jede Zeile auf error, bevor du sie als Fortschritt liest.

Fragen

/api/decide, /v1/systemone und /api/create teilen sich ein Fragenschema, das von TypeSafe. Eine Anfrage hat 1–256 Fragen, mit einer beliebigen ID als Schlüssel; die Antworten kommen in derselben Reihenfolge zurück.

• instructions kann ein String, ein Objekt, ein Array oder null sein. Fehlt es oder ist es null, liest das Modell stattdessen die Frage-ID, sodass eine beschreibende ID wie is_spam für sich allein funktioniert.
• state ist ein String, ein Objekt oder ein Array, bis zu 65.536 Token. Überschreitet er den verfügbaren Kontext des Modells, kürzt /api/decide ihn und meldet state_truncated: true. /v1/systemone und /v1/decisions geben 422 STATE_TRUNCATED zurück, mit dem antwortenden Modell in detail[0].ctx.model.
• Modellgrenzen. Jede Option braucht Platz im Kontext des Modells: etwa 125 Optionen für laya:en (512 Token) und 250 für laya:multilingual (1.024). Mehr ergibt 422 TOO_MANY_OPTIONS. Bei einem Router gelten die Grenzen des Ziels.

Antworten sind TypeSafe-Formen, in dieser Feldreihenfolge:

confidence ist die von TypeSafe normalisierte Spitzenwahrscheinlichkeit, (K · p_max − 1) / (K − 1) für K Optionen: 0, wenn jede Option gleich wahrscheinlich ist, 1, wenn eine Option die ganze Wahrscheinlichkeit auf sich vereint. Die Formel ist für jedes Modell dieselbe, was eine gegebene Konfidenz bedeutet, aber nicht: Modelle sind unterschiedlich kalibriert, stimme einen Schwellenwert also pro Modell auf deinen eigenen Daten ab. Wahrscheinlichkeiten werden mit den Temperaturen jedes Modells kalibriert. Auf einer CUDA-GPU läuft der fp16-Graph, dessen Antworten bei knappen Ausgängen von fp32 abweichen können.

keep_alive

Wie lange ein Modell nach dem Ende einer Anfrage geladen bleibt, mit Ollamas Semantik:

Der Timer startet, wenn eine Anfrage endet, und der Wert der letzten Anfrage gewinnt. Bei einem Router gilt er für das Ziel, das geantwortet hat. /v1/* ignoriert keep_alive.

Decide

POST /api/decide

Beantwortet typisierte Fragen zu einem Zustand in einem Vorwärtsdurchlauf. Der Körper ist der Körper von /v1/systemone plus native Optionen; die Antwort ist TypeSafes Antwort plus native Felder, sodass auch ein TypeSafe-Client sie parsen kann.

curl http://localhost:11435/api/decide -d '{
  "model": "laya",
  "state": "I was charged twice for my subscription this month. Please refund the second charge.",
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this ticket?",
      "criteria": {
        "billing": "Payments, invoices and refunds",
        "technical": "Bugs, errors and outages",
        "account": "Login, profile and settings"
      }
    },
    "urgency": {
      "type": "score",
      "instructions": "How urgent is this ticket?",
      "criteria": ["Can wait", "Needs attention this week", "Needs attention today"]
    },
    "refund": {
      "type": "noul",
      "instructions": "The customer asks for money back.",
      "criteria": {"true": "Asks for a refund", "false": "Does not ask for a refund"}
    }
  },
  "keep_alive": "10m"
}'

{
  "model": "laya:en",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "billing",
      "confidence": 0.7781,
      "probabilities": {"billing": 0.8521, "technical": 0.0611, "account": 0.0868}
    },
    "urgency": {
      "type": "score",
      "score": 1.1982,
      "confidence": 0.3418,
      "legend": {"0": "Can wait", "1": "Needs attention this week", "2": "Needs attention today"},
      "probabilities": {"0": 0.1203, "1": 0.5612, "2": 0.3185}
    },
    "refund": {"type": "noul", "noul": 0.9127}
  },
  "usage": {"input_tokens": 118, "output_tokens": 0},
  "routing": {
    "router": "laya:latest",
    "model": "laya:en",
    "route": "english",
    "reason": "English Latin text"
  },
  "state_truncated": false,
  "done_reason": "decide",
  "created_at": "2026-09-24T09:30:12.418Z",
  "total_duration": 18734512,
  "load_duration": 0,
  "eval_duration": 16302117
}

Mit "extras": ["laya"] hat jede Antwort außerdem ein laya-Objekt: confidence (layas entropiebasierte Konfidenz) und act_probability (aus dem Act-Head des Modells oder null).

Bilder

Ein Vision-Modell (decider:2b-vision oder winnow:e4b-vision) beantwortet Fragen zu einem Bild ebenso wie zum Zustand. Sende das Bild in images, base64-kodiert, so wie Ollamas images funktioniert:

curl http://localhost:11435/api/decide -d '{
  "model": "decider:2b-vision",
  "state": "A photo from the warehouse camera.",
  "images": ["'"$(base64 -w0 shelf.png)"'"],
  "questions": {
    "blocked": {"type": "noul", "instructions": "Is the aisle blocked?"},
    "fill": {"type": "score", "instructions": "How full is the shelf?", "criteria": ["empty", "half full", "full"]}
  }
}'

• Decider: Ein Bild pro Anfrage, nur PNG. Die Vorverarbeitung des Modells wird Wert für Wert reproduziert, die Pixel müssen also zu dem passen, was die Autoren des Modells dekodieren. Rusts JPEG-Decoder weichen bei manchen Pixeln um bis zu 4 Stufen von libjpeg-turbo ab, JPEG wird deshalb noch nicht akzeptiert: Konvertiere es zuerst nach PNG.
• Decider: Das Bild wird auf Vielfache von 32 Pixeln skaliert, wie das Modell es erwartet, und kann danach höchstens 4.096 Patches von 16x16 Pixeln haben, etwa ein Megapixel (1024x1024). Ein größeres Bild erhält eine 422, die das sagt; skaliere es zuerst herunter.
• Decider: Fragen haben höchstens 10 Optionen. Dasselbe Modell beantwortet auch reine Textanfragen.
• Winnow E4B vision: bis zu 16 geordnete PNGs, 2–64 Optionen pro Frage, im kombinierten Bild-/Zustands-/Fragekontext. Der passende Projektor wird separat aus derselben Autoren-Revision heruntergeladen. Bestehende Winnow-Text-Tags laden ihn nicht.
• Ein Modell, das keine Bilder liest, beantwortet eine Anfrage mit images mit einer 422.

/v1/systemone und /v1/decisions bleiben identisch mit der API von TypeSafe, die kein Bildfeld hat.

Laden und Entladen. Eine Anfrage ohne state und questions entscheidet nie. Ohne keep_alive oder mit einem positiven oder negativen lädt sie das Modell (bei einem Router jedes Ziel) und gibt done_reason: "load" zurück. Mit keep_alive: 0 entlädt sie es ("unload"). ollaya run lädt auf diese Weise vor, und ollaya stop entlädt.

curl http://localhost:11435/api/decide -d '{"model": "laya:en", "keep_alive": -1}'
curl http://localhost:11435/api/decide -d '{"model": "laya:en", "keep_alive": 0}'

Eine Entscheidung hat keine Nebenwirkung auf gespeicherte Daten, ein erneuter Versuch ist also sicher.

Presets

Ein Preset ist ein benannter Fragensatz. Sechs sind eingebaut (triage, email, guard, moderation, router, agent), und du kannst eigene speichern. Sende "preset": "NAME" an /api/decide anstelle von questions.

curl http://localhost:11435/api/presets/create -d '{
  "name": "billing-check",
  "description": "Billing, and how upset the customer is",
  "questions": {
    "billing": {"type": "noul", "instructions": "The message is about a charge, an invoice or a refund."},
    "tone": {"type": "choice", "instructions": "How does the customer sound?", "criteria": {"calm": null, "annoyed": null, "angry": null}}
  }
}'
curl http://localhost:11435/api/decide -d '{"model": "winnow:e4b", "state": "I was charged twice this month.", "preset": "billing-check"}'

Namen bestehen aus 1 bis 64 Zeichen aus Kleinbuchstaben, Ziffern, - und _. Ein eingebauter Name kann nicht wiederverwendet (422) oder gelöscht (403) werden, und ein unbekannter Name ist ein 404. Eigene Presets werden neben den Modellen gespeichert, sodass jeder Client des Servers dieselben sieht.

Router

Ein Router wie laya (laya:latest) hat keine Gewichte: Für jede Anfrage wählt er eines seiner Ziele, das dann antwortet. laya liest nur den state:

Kurzer Text in Großbuchstaben ohne akzentuierte Buchstaben, etwa Händlernamen auf einem Kreditkartenauszug (MIGROS KADIKOY ISTANBUL TR), SKUs oder Benutzernamen, lässt sich meist nicht identifizieren und geht an laya:en. Wenn du die Sprache kennst, fordere laya:multilingual oder laya:en direkt an; das model der Antwort sagt, welcher Checkpoint geantwortet hat.

Routing kostet Mikrosekunden. Verzweige nach route, niemals nach reason, dessen Formulierung sich ändern kann. laya:typed-decisions wird vom Router nie gewählt; fordere es direkt an.

Lokale Modelle auflisten

GET /api/tags

Die Modelle auf diesem Rechner, neueste zuerst. Jeder Eintrag hat name, model (denselben), modified_at, size in Bytes, digest (sha256 des Manifests, reines Hex) und details: parent_model, format (onnx, gguf oder router), family, families, parameter_size und quantization_level (die mitgeführten Genauigkeiten wie F16/F32 oder die Quantisierung eines GGUF-Modells wie Q8_0).

{
  "models": [
    {
      "name": "laya:en",
      "model": "laya:en",
      "modified_at": "2026-09-24T08:11:02.117Z",
      "size": 853634822,
      "digest": "bf30e4654e9483ff1e6a4fe6fb21b8a71baff6c8a01013046e7d13339020efd7",
      "details": {
        "parent_model": "",
        "format": "onnx",
        "family": "laya",
        "families": ["laya"],
        "parameter_size": "421M",
        "quantization_level": "F16/F32"
      }
    }
  ]
}

Modelldetails anzeigen

POST /api/show

curl http://localhost:11435/api/show -d '{"model": "laya:en"}'

Ein Router wird als er selbst angezeigt, nicht zu einem Ziel aufgelöst.

Laufende Modelle auflisten

GET /api/ps

Die geladenen Modelle, nach Namen sortiert. Router erscheinen nie; ihre geladenen Ziele schon. Jeder Eintrag hat name, model, size (Speicher, RAM plus VRAM), digest, details (mit der tatsächlich geladenen Genauigkeit: F16 oder F32 oder die Quantisierung eines GGUF-Modells), expires_at (wann es entladen wird, oder null, wenn geladen gehalten), size_vram, context_length und device (cpu, cuda:0, metal, …).

Ein Modell herunterladen

POST /api/pull

{"model": "laya:en"}

Lädt das Modell in den lokalen Speicher herunter und prüft jeden Blob gegen seinen sha256. Ein Router lädt beim Pull auch jedes Modell herunter, an das er weiterleitet. Nur die Ebenen, die dieser Rechner braucht, werden heruntergeladen, zwischen Modellen geteilte Blobs werden einmal heruntergeladen, und unterbrochene Downloads werden fortgesetzt.

Die Antwort streamt den Fortschritt, mit Ollamas Status-Strings:

{"status":"pulling manifest"}
{"status":"pulling 891102d37268","digest":"sha256:891102d372688fc2a094dac56a384bc537b87c63f21f9f3dac0be2b7cbc8d86c","total":842609210,"completed":420557117}
{"status":"pulling 891102d37268","digest":"sha256:891102d372688fc2a094dac56a384bc537b87c63f21f9f3dac0be2b7cbc8d86c","total":842609210,"completed":842609210}
{"status":"verifying sha256 digest"}
{"status":"writing manifest"}
{"status":"success"}

Ein Modell erscheint erst nach writing manifest in /api/tags. Bei einem Router gibt es ein success, ganz am Ende. Ein Name, der sich nicht parsen lässt, ein Modell, das nicht in der Registry ist, und eine nicht erreichbare Registry sind gewöhnliche HTTP-Fehler (422, 404, 502), bevor der Stream beginnt, curl --fail funktioniert also. Mit "stream": false ist die Antwort nach Abschluss {"status": "success"}. Ein zweiter Pull desselben Namens schließt sich dem laufenden an. Ein erneuter Versuch ist sicher.

Ein Modell löschen

DELETE /api/delete

{"model": "triage"}

Entfernt den Namen und die Blobs, die kein anderes Modell verwendet. Ein geladenes Modell wird entladen, sobald seine Anfragen beendet sind; das Löschen eines Routers behält seine Ziele. Die Antwort ist 200 mit leerem Körper und 404 MODEL_NOT_FOUND, wenn der Name nicht existiert; behandle das nach einem Timeout als Erfolg.

Ein Modell kopieren

POST /api/copy

{"source": "laya:en", "destination": "my-guardrail"}

Kopiert ein Modell unter einen neuen Namen und überschreibt ein vorhandenes Ziel. Die Antwort ist 200 mit leerem Körper.

Ein Modell erstellen

POST /api/create

Die API hinter ollaya create -f Modelfile: Die CLI liest das Modelfile und die darin genannten Dateien und sendet ihren Inhalt als JSON.

curl http://localhost:11435/api/create -d '{
  "model": "triage",
  "from": "laya:en",
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this ticket?",
      "criteria": ["billing", "technical", "account"]
    }
  },
  "parameters": {"precision": "fp32"},
  "description": "Support ticket triage"
}'

Der Stream meldet using existing layer sha256:… für jede geerbte Ebene, creating new layer sha256:… für jede neue, dann writing manifest und success. Ebenen sind inhaltsadressiert, ein wiederholtes Create ergibt also dasselbe Modell.

Version

GET /api/version

{"version": "0.1.0"}

TypeSafe-kompatible Endpunkte

/v1/* ignoriert native Felder wie keep_alive und extras und fügt seinen Antworten nie native Felder hinzu. Fehler verwenden denselben Körper wie /api/*, den das TypeSafe-SDK korrekt liest. Siehe TypeSafe-Kompatibilität.

Sicherheit

Der Server bindet an 127.0.0.1:11435 und vertraut wie Ollama lokalen Aufrufern. Bindest du ihn an eine andere Adresse (OLLAYA_HOST=0.0.0.0), kann jeder, der den Port erreicht, Entscheidungen ausführen sowie Modelle herunterladen, löschen und erstellen, also:

• OLLAYA_API_KEY lässt jede Anfrage außer GET /, HEAD / und CORS-Preflight Authorization: Bearer <key> erfordern; andernfalls lautet die Antwort 401 UNAUTHORIZED. Das TypeSafe-SDK sendet seinen Schlüssel so, und die ollaya-CLI sendet $OLLAYA_API_KEY. Der Server protokolliert eine Warnung, wenn er über Loopback hinaus ohne Schlüssel lauscht.
• TLS wird nicht vom Server terminiert; stelle für den Fernzugriff einen Reverse-Proxy davor.
• Browser. Anfragen mit einem Origin-Header sind nur von localhost, 127.0.0.1, 0.0.0.0 und [::1] (beliebiger Port), App- und Editor-Webviews und den Ursprüngen in OLLAYA_ORIGINS (durch Kommas getrennt, *-Platzhalter) erlaubt. Ein Loopback-Server lehnt außerdem unerwartete Host-Header ab, was DNS-Rebinding blockiert.
• Deine Daten. Zustände und Fragen werden nie protokolliert und nie in Fehlern zurückgegeben.