API リファレンス

ollaya serve は http://localhost:11435 で 2 つの API を公開します。

• /api/* 配下のネイティブ API —— Ollama を手本にしたもので、決定とモデル管理に使います。
• /v1/* 配下の TypeSafe 互換 API —— TypeSafe とワイヤ単位で同一なので、既存の TypeSafe SDK がそのまま動きます。詳しくは TypeSafe 互換を参照してください。

/api/push と /api/blobs/:digest は予約済みで、501 NOT_IMPLEMENTED を返します。Ollama のテキスト系エンドポイント（/api/generate、/api/chat、/api/embed）は 404 を返します。決定モデルは決してテキストを生成しません。

規約

• JSON。 リクエストとレスポンスのボディは JSON オブジェクトです。Content-Type が何であれボディは JSON としてパースされるので、curl -d がそのまま使えます。リクエストは最大 8 MiB です。
• フィールド名は snake_case です。未知のリクエストフィールドは無視され、null は不在を意味します。
• モデル名は [host/][namespace/]model[:tag] で、大文字小文字を区別しません。タグを省略すると latest を意味します。レスポンスは常に正規形（laya:latest など）を使います。
• 数値。 確率、信頼度、score、noul は小数点以下 4 桁に丸められます。継続時間はナノ秒単位の整数で、タイムスタンプは UTC の RFC 3339 です。
• ストリーミング。 /api/pull と /api/create は改行区切りの JSON をストリーミングし、1 行に 1 オブジェクト、末尾にちょうど 1 つの {"status":"success"} か 1 行のエラーを付けます。単一のレスポンスが必要なら "stream": false を送ります。
• リクエスト ID。 すべてのレスポンスは X-Request-Id を運び、/v1/* のレスポンスは x-typesafe-request-id も運びます。クライアントが送った有効な X-Request-Id はそのまま返されます。
• 並行性。 ロード済みのモデルは一度に 1 つのリクエストを実行し、各リクエストは自分のすべての質問に 1 パスで答えます。同じモデルへのリクエストはキューに入るので、一度に多く送っても早く終わりません。その場合、各リクエストの往復には待ち時間が含まれます。ある state についての質問は 1 つのリクエストにまとめてください。ロード済みの別々のモデルは並列に実行されます。
• 暗黙のプルはありません。 副作用としてモデルをダウンロードするエンドポイントはありません。ollaya run は先にプルし、アプリケーションは /api/pull を呼びます。

エラー

すべてのエンドポイントのすべてのエラーは、このボディを持ちます。

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

コードの集合は開いています。未知のコードはその HTTP ステータスで処理してください。検証エラーはすべての問題を一度に列挙します。

{
  "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}
    }
  ]
}

ストリームが始まったあと、失敗は同じ形の最終行として届きます（例：{"error": "…", "code": "DIGEST_MISMATCH"}）。各行を進捗として読む前に、error を確認してください。

質問

/api/decide、/v1/systemone、/api/create は 1 つの質問スキーマ（TypeSafe のもの）を共有します。1 つのリクエストには1〜256 個の質問があり、任意の id をキーにします。答えは同じ順序で返ります。

• instructions は文字列、オブジェクト、配列、または null です。省略または null のとき、モデルは代わりに質問 id を読みます。したがって is_spam のような説明的な id はそれだけで機能します。
• state は文字列、オブジェクト、または配列で、最大 65,536 トークンです。モデルが使えるコンテキストを超えると、/api/decide はそれを切り詰め、state_truncated: true を報告します。/v1/systemone と /v1/decisions は 422 STATE_TRUNCATED を返し、答えたモデルを detail[0].ctx.model に含めます。
• モデルの制限。 すべての選択肢はモデルのコンテキストに余地を必要とします。laya:en（512 トークン）で約 125 個、laya:multilingual（1,024）で 250 個です。それより多いと 422 TOO_MANY_OPTIONS になります。ルーターの場合は、ターゲットの制限が適用されます。

答えは TypeSafe の形で、このフィールド順です。

confidence は TypeSafe の正規化された最大確率で、K 個の選択肢に対して (K · p_max − 1) / (K − 1) です。すべての選択肢が等確率のとき 0、1 つの選択肢がすべての確率を持つとき 1 になります。この式はどのモデルでも同じですが、与えられた confidence の意味は同じではありません。モデルごとに較正が異なるので、自分のデータでモデルごとにしきい値を調整してください。確率は各モデルの temperature で較正されます。CUDA GPU では fp16 のグラフが動き、その答えは接戦で fp32 と異なることがあります。

keep_alive

リクエストが終わったあと、モデルがどれだけロードされたままになるか。Ollama の意味論に従います。

タイマーはリクエストが終わったときに始まり、最新のリクエストの値が優先されます。ルーターの場合は、答えたターゲットに適用されます。/v1/* は keep_alive を無視します。

決定

POST /api/decide

1 回のフォワードパスで、ある state に関する型付きの質問に答えます。ボディは /v1/systemone のボディにネイティブのオプションを加えたもので、レスポンスは TypeSafe のレスポンスにネイティブのフィールドを加えたものです。したがって TypeSafe クライアントでもパースできます。

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
}

"extras": ["laya"] を付けると、すべての答えに laya オブジェクトも付きます：confidence（laya のエントロピーに基づく信頼度）と act_probability（モデルの act ヘッドからの値。なければ null）。

画像

ビジョンモデル（decider:2b-vision または winnow:e4b-vision）は、state と同様に画像に関する質問にも答えます。画像は images に入れて base64 エンコードで送ります。Ollama の images と同じ動作です。

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: 1 リクエストにつき画像 1 枚、PNG のみです。モデルの前処理は値単位で再現されるので、ピクセルはモデルの作者がデコードするものと一致しなければなりません。Rust の JPEG デコーダは一部のピクセルで libjpeg-turbo と最大 4 レベル異なるため、JPEG はまだ受け付けません。先に PNG に変換してください。
• Decider: 画像はモデルが期待するとおり 32 ピクセルの倍数にリサイズされ、その後は 16x16 ピクセルのパッチを最大 4,096 個、およそ 100 万ピクセル（1024x1024）まで持てます。それより大きい画像はその旨を示す 422 になります。先に縮小してください。
• Decider: 質問は最大 10 個の選択肢を取ります。同じモデルはテキストのみのリクエストにも答えます。
• Winnow E4B vision: 順序づけられた PNG を最大 16 枚、質問あたり 2–64 個の選択肢、画像・状態・質問を合わせたコンテキストの範囲内で。対応するプロジェクターは同じ著者のリビジョンから別途ダウンロードします。既存の Winnow テキストタグはそれを読み込みません。
• 画像を読まないモデルは、images 付きのリクエストに 422 で答えます。

/v1/systemone と /v1/decisions は、画像フィールドを持たない TypeSafe の API と同一のままです。

ロードとアンロード。 state と questions のないリクエストは決して決定しません。keep_alive がない場合、または正か負の値の場合は、モデル（ルーターならすべてのターゲット）をロードし、done_reason: "load" を返します。keep_alive: 0 の場合はアンロードします（"unload"）。ollaya run はこの方法でプリロードし、ollaya stop はアンロードします。

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}'

決定は保存されたデータに副作用がないので、再試行しても安全です。

プリセット

プリセットは名前付きの質問セットです。6 つが組み込みで（triage、email、guard、moderation、router、agent）、独自のものも保存できます。questions の代わりに "preset": "NAME" を /api/decide に送ります。

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"}'

名前は小文字、数字、-、_ の 1〜64 文字です。組み込みの名前は再利用できず（422）、削除もできません（403）。未知の名前は 404 です。カスタムプリセットはモデルの隣に保存されるので、サーバーのどのクライアントも同じものを見ます。

ルーター

laya（laya:latest）のようなルーターは重みを持ちません。リクエストごとにターゲットの 1 つを選び、選ばれたものが答えます。laya は state だけを読みます。

カード明細の加盟店名（MIGROS KADIKOY ISTANBUL TR）のように、アクセント記号のない大文字の短いテキスト、SKU、ユーザー名は通常識別できず、laya:en に行きます。言語がわかっている場合は、laya:multilingual または laya:en を直接リクエストしてください。レスポンスの model が、どのチェックポイントが答えたかを示します。

ルーティングのコストはマイクロ秒です。route で分岐し、reason では決して分岐しないでください。その文言は変わりえます。laya:typed-decisions はルーターに決して選ばれません。直接リクエストしてください。

ローカルモデルの一覧

GET /api/tags

このマシン上のモデルを新しい順に並べます。各エントリは name、model（同じ値）、modified_at、バイト単位の size、digest（マニフェストの sha256、素の 16 進）と details を持ちます：parent_model、format（onnx、gguf、router のいずれか）、family、families、parameter_size、quantization_level（F16/F32 のように保持する精度、または Q8_0 のような GGUF モデルの量子化）。

{
  "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"
      }
    }
  ]
}

モデル詳細の表示

POST /api/show

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

ルーターはターゲットに解決されず、それ自体として表示されます。

実行中モデルの一覧

GET /api/ps

ロード済みのモデルを名前順に並べます。ルーターは決して現れません。ロード済みのターゲットが現れます。各エントリは name、model、size（メモリ、RAM と VRAM）、digest、details（実際にロードされた精度：F16 か F32、または GGUF モデルの量子化）、expires_at（アンロードされる時刻。ロードしたままなら null）、size_vram、context_length、device（cpu、cuda:0、metal など）を持ちます。

モデルのプル

POST /api/pull

{"model": "laya:en"}

モデルをローカルストアにダウンロードし、すべての blob を sha256 と照合します。ルーターをプルすると、それがルーティングするすべてのモデルもプルします。このマシンに必要なレイヤーだけがダウンロードされ、モデル間で共有される blob は一度だけダウンロードされ、中断したダウンロードは再開されます。

レスポンスは進捗をストリーミングし、Ollama のステータス文字列を使います。

{"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"}

モデルは writing manifest のあとに初めて /api/tags に現れます。ルーターの場合は最後に 1 つの success があります。パースできない名前、レジストリにないモデル、到達できないレジストリは、ストリームが始まる前の通常の HTTP エラー（422、404、502）なので、curl --fail が機能します。"stream": false の場合、完了時のレスポンスは {"status": "success"} です。同じ名前の 2 回目のプルは、進行中のものに合流します。再試行しても安全です。

モデルの削除

DELETE /api/delete

{"model": "triage"}

名前と、他のどのモデルも使わない blob を削除します。ロード済みのモデルはリクエストが終わるとアンロードされます。ルーターを削除してもターゲットは残ります。レスポンスはボディが空の 200 で、名前が存在しないときは 404 MODEL_NOT_FOUND です。タイムアウトの後は、それを成功として扱ってください。

モデルのコピー

POST /api/copy

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

モデルを新しい名前へコピーし、既存のコピー先を上書きします。レスポンスはボディが空の 200 です。

モデルの作成

POST /api/create

ollaya create -f Modelfile の背後にある API です。CLI は Modelfile とそれが名指すファイルを読み、その内容を 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"
}'

ストリームは、継承したレイヤーごとに using existing layer sha256:…、新しいレイヤーごとに creating new layer sha256:… を報告し、その後 writing manifest と success を報告します。レイヤーは内容でアドレス指定されるので、作成を繰り返すと同じモデルになります。

バージョン

GET /api/version

{"version": "0.1.0"}

TypeSafe 互換エンドポイント

/v1/* は keep_alive や extras のようなネイティブのフィールドを無視し、レスポンスにネイティブのフィールドを決して加えません。エラーは /api/* と同じボディを使い、TypeSafe SDK はそれを正しく読みます。詳しくは TypeSafe 互換を参照してください。

セキュリティ

サーバーは 127.0.0.1:11435 にバインドし、Ollama と同様にローカルの呼び出し元を信頼します。別のアドレス（OLLAYA_HOST=0.0.0.0）にバインドすると、そのポートに到達できる誰もが決定を実行し、モデルをプル・削除・作成できるので、次の点に注意してください。

• OLLAYA_API_KEY を設定すると、GET /、HEAD /、CORS プリフライトを除くすべてのリクエストが Authorization: Bearer <key> を要求します。そうでなければ答えは 401 UNAUTHORIZED です。TypeSafe SDK はこの方法でキーを送り、ollaya CLI は $OLLAYA_API_KEY を送ります。サーバーはループバックを超えて待ち受けるとき、キーがなければ警告をログに記録します。
• TLS はサーバーでは終端されません。リモートアクセスには前にリバースプロキシを置いてください。
• ブラウザ。 Origin ヘッダー付きのリクエストは、localhost、127.0.0.1、0.0.0.0、[::1]（任意のポート）、アプリとエディタのウェブビュー、および OLLAYA_ORIGINS（カンマ区切り、* ワイルドカード）のオリジンからのみ許可されます。ループバックサーバーは予期しない Host ヘッダーも拒否し、これが DNS リバインディングを防ぎます。
• データ。 state と質問は決してログに記録されず、エラーの中にそのまま返されることもありません。