{
  "openapi": "3.0.3",
  "info": {
    "title": "FitLLM Agent API",
    "version": "1.0.0",
    "description": "Will this local LLM fit this hardware? Auditable, architecture-aware memory estimates (MLA / sliding-window / hybrid-linear / MoE), with documented runtime/OS reserves. No auth, no key. Engine: MIT (github.com/click6067-ship-it/fitllm-engine) · data: CC0 (fitllm.run/data).",
    "license": { "name": "MIT", "url": "https://github.com/click6067-ship-it/fitllm-engine/blob/master/LICENSE" },
    "x-mcp-server": "https://fitllm.run/api/mcp",
    "x-mcp-registry": "https://registry.modelcontextprotocol.io/v0.1/servers?search=run.fitllm%2Ffitllm"
  },
  "servers": [{ "url": "https://fitllm.run" }],
  "externalDocs": {
    "description": "Canonical agent workflow, status handling, and citation rules",
    "url": "https://fitllm.run/agent/answer-with-citation.md"
  },
  "paths": {
    "/api/check": {
      "get": {
        "operationId": "checkLlmFit",
        "summary": "Check whether an LLM fits on a GPU (incl. multi-GPU rigs) or Apple Silicon Mac",
        "parameters": [
          { "name": "model", "in": "query", "required": true, "schema": { "type": "string" }, "description": "LLM name, fuzzy — e.g. 'gemma 4 31b'" },
          { "name": "gpu", "in": "query", "schema": { "type": "string" }, "description": "GPU name, fuzzy. Multi-GPU: join with + (e.g. '5090+3090'). Provide gpu OR ram." },
          { "name": "ram", "in": "query", "schema": { "type": "integer", "minimum": 8, "maximum": 2048 }, "description": "Apple Silicon unified memory (GB)" },
          { "name": "quant", "in": "query", "schema": { "type": "string" }, "description": "GPU: Q4_K_M(default)/Q5_K_M/Q6_K/Q8_0/FP16 · Mac: 4|8(default)|16" },
          { "name": "ctx", "in": "query", "schema": { "type": "integer" }, "description": "Context tokens (default 8192)" },
          { "name": "kv", "in": "query", "schema": { "type": "integer", "enum": [16, 8, 4] }, "description": "KV-cache bits (default 16)" },
          { "name": "count", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 8 }, "description": "Copies of gpu" },
          { "name": "format", "in": "query", "schema": { "type": "string", "enum": ["json", "text", "md"] }, "description": "Default json; curl user-agents get text; md returns a citation block for both computed 200 results and numeric-null 422 statuses" }
        ],
        "responses": {
          "200": {
            "description": "Fit verdict with full memory breakdown, max context, receipt permalink, and a computed fix when it doesn't fit",
            "content": { "application/json": { "schema": {
              "type": "object",
              "properties": {
                "verdict": { "type": "string", "enum": ["yes", "tight", "no"] },
                "receipt": { "type": "string", "description": "Stable permalink for this verdict" },
                "model": { "type": "string" }, "hardware": { "type": "string" },
                "quant": { "type": "string" }, "kvBits": { "type": "integer" }, "ctx": { "type": "integer" },
                "memory": { "type": "object", "properties": {
                  "usedGB": { "type": "number" }, "totalGB": { "type": "number" }, "freeGB": { "type": "number" },
                  "breakdown": { "type": "object", "properties": { "weightsGB": { "type": "number" }, "kvCacheGB": { "type": "number" }, "overheadGB": { "type": "number" }, "reserveGB": { "type": "number" } } } } },
                "maxContext": { "type": "integer" },
                "fix": { "type": "string", "nullable": true, "description": "Concrete actionable change when verdict is not 'yes' — relay verbatim" }
              } } } }
          },
          "422": {
            "description": "The exact model is identity-verified but its architecture is not modeled. No fit estimate was computed; cite statusUrl and pinned evidence instead.",
            "content": { "application/json": { "schema": {
              "type": "object",
              "required": ["schemaVersion", "status", "model", "verifiedRevision", "verifiedAt", "missingComponents", "verdict", "memory", "usedGB", "maxContext", "message", "statusUrl", "evidence"],
              "properties": {
                "schemaVersion": { "type": "string", "enum": ["fitllm.model-status.v1"] },
                "status": { "type": "string", "enum": ["unsupported_architecture"] },
                "model": { "type": "string", "enum": ["Qwen/Qwen3.8-Flash-Next"] },
                "verifiedRevision": { "type": "string", "enum": ["de4b8e4d43b917e7706784d8bb445c9af86a3540"] },
                "verifiedAt": { "type": "string", "format": "date" },
                "missingComponents": { "type": "array", "items": { "type": "string", "enum": ["QSA_INDEXER", "NGRAM_RESIDENCY", "MTP_RESIDENCY", "HC_ACTIVATION", "MULTIMODAL_WORKLOAD"] } },
                "verdict": { "type": "string", "nullable": true, "enum": [null] },
                "memory": { "type": "object", "nullable": true, "enum": [null] },
                "usedGB": { "type": "number", "nullable": true, "enum": [null] },
                "maxContext": { "type": "integer", "nullable": true, "enum": [null] },
                "message": { "type": "string" },
                "statusUrl": { "type": "string", "format": "uri" },
                "evidence": { "type": "array", "items": { "type": "object", "required": ["kind", "url"], "properties": { "kind": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "sha256": { "type": "string" } } } }
              }
            } } }
          },
          "404": { "description": "Unknown model/gpu — do not substitute a nearby model; request the exact ID" }
        }
      }
    },
    "/api/badge": {
      "get": {
        "operationId": "fitBadge",
        "summary": "shields.io endpoint badge for a model×hardware verdict (live)",
        "parameters": [
          { "name": "model", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "gpu", "in": "query", "schema": { "type": "string" } },
          { "name": "ram", "in": "query", "schema": { "type": "integer" } },
          { "name": "quant", "in": "query", "schema": { "type": "string" } },
          { "name": "ctx", "in": "query", "schema": { "type": "integer" } },
          { "name": "kv", "in": "query", "schema": { "type": "integer" } }
        ],
        "responses": { "200": { "description": "shields.io endpoint schema JSON" } }
      }
    }
  }
}