{
  "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"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Ambiguous model or GPU name — the query matched several catalog entries. The API returns the candidate list instead of picking one, because picking would silently answer about a different model than asked. Re-request with one exact name.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "candidates": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Exact catalog names that matched the ambiguous query."
                    }
                  }
                }
              }
            }
          },
          "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"
          }
        }
      }
    }
  }
}