{
  "openapi": "3.1.0",
  "info": {
    "title": "shir-man.com Free LLM Recommendation API",
    "version": "1.0.0",
    "description": "Daily recommendation API for the best free OpenRouter-compatible text model plus fallback routing information."
  },
  "servers": [
    {
      "url": "https://shir-man.com"
    }
  ],
  "paths": {
    "/api/free-llm/recommendation": {
      "get": {
        "summary": "Get the current free model recommendation",
        "operationId": "getFreeLlmRecommendation",
        "responses": {
          "200": {
            "description": "Current recommendation payload",
            "headers": {
              "X-Free-LLM-Seed": {
                "description": "True when the endpoint returned the built-in seed instead of KV-backed data.",
                "schema": {
                  "type": "string",
                  "enum": ["true", "false"]
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Recommendation"
                }
              }
            }
          }
        }
      }
    },
    "/api/free-llm/top-models": {
      "get": {
        "summary": "Get the ordered shortlist of top free models",
        "operationId": "getFreeLlmTopModels",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Optional maximum number of ordered models to return from the stored shortlist.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Ordered shortlist payload",
            "headers": {
              "X-Free-LLM-Seed": {
                "description": "True when the endpoint returned the built-in seed instead of KV-backed data.",
                "schema": {
                  "type": "string",
                  "enum": ["true", "false"]
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TopModelsResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/free-llm/health": {
      "get": {
        "summary": "Get freshness information for the recommendation cache",
        "operationId": "getFreeLlmHealth",
        "responses": {
          "200": {
            "description": "Health payload",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Health"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "RankedModel": {
        "type": "object",
        "required": ["id", "name", "score"],
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "score": { "type": "number" },
          "metadataScore": { "type": "number" },
          "healthScore": { "type": "number" },
          "latencyScore": { "type": "number" },
          "liteEvalScore": { "type": "number" },
          "instabilityPenalty": { "type": "number" },
          "evalSuite": { "type": "string" },
          "evalSummary": {
            "$ref": "#/components/schemas/EvalSummary"
          },
          "reason": { "type": "string" },
          "contextLength": { "type": "number" },
          "maxCompletionTokens": { "type": "number" },
          "supportsTools": { "type": "boolean" },
          "supportsStructuredOutputs": { "type": "boolean" },
          "supportsReasoning": { "type": "boolean" },
          "healthStatus": { "type": "string" },
          "latencyMs": {
            "type": ["number", "null"]
          }
        }
      },
      "TopRankedModel": {
        "allOf": [
          {
            "$ref": "#/components/schemas/RankedModel"
          },
          {
            "type": "object",
            "required": ["rank"],
            "properties": {
              "rank": { "type": "integer", "minimum": 1 }
            }
          }
        ]
      },
      "Recommendation": {
        "type": "object",
        "required": ["updatedAt", "baseUrl", "fallback", "notes"],
        "properties": {
          "updatedAt": { "type": "string", "format": "date-time" },
          "source": { "type": "string" },
          "rankingVersion": { "type": "string" },
          "probeMode": { "type": "string" },
          "refreshMode": { "type": "string", "enum": ["metadataOnly", "healthOnly", "fullEval", "forceEval"] },
          "liteEvalMode": { "type": "string" },
          "liteEvalSuite": { "type": "string" },
          "rankingConfidence": { "type": "string", "enum": ["high", "medium", "low"] },
          "rankingConfidenceReason": { "type": "string" },
          "evalCoverage": {
            "$ref": "#/components/schemas/EvalCoverage"
          },
          "baseUrl": { "type": "string", "format": "uri" },
          "createKeyUrl": { "type": "string", "format": "uri" },
          "primary": {
            "anyOf": [
              { "$ref": "#/components/schemas/RankedModel" },
              { "type": "null" }
            ]
          },
          "fallback": {
            "type": "object",
            "required": ["id", "reason"],
            "properties": {
              "id": { "type": "string" },
              "reason": { "type": "string" }
            }
          },
          "alternatives": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RankedModel"
            }
          },
          "notes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "TopModelsResponse": {
        "type": "object",
        "required": ["updatedAt", "baseUrl", "fallback", "count", "models", "notes"],
        "properties": {
          "updatedAt": { "type": "string", "format": "date-time" },
          "source": { "type": "string" },
          "rankingVersion": { "type": "string" },
          "probeMode": { "type": "string" },
          "refreshMode": { "type": "string", "enum": ["metadataOnly", "healthOnly", "fullEval", "forceEval"] },
          "liteEvalMode": { "type": "string" },
          "liteEvalSuite": { "type": "string" },
          "rankingConfidence": { "type": "string", "enum": ["high", "medium", "low"] },
          "rankingConfidenceReason": { "type": "string" },
          "evalCoverage": {
            "$ref": "#/components/schemas/EvalCoverage"
          },
          "baseUrl": { "type": "string", "format": "uri" },
          "createKeyUrl": { "type": "string", "format": "uri" },
          "fallback": {
            "type": "object",
            "required": ["id", "reason"],
            "properties": {
              "id": { "type": "string" },
              "reason": { "type": "string" }
            }
          },
          "count": { "type": "integer", "minimum": 0 },
          "models": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TopRankedModel"
            }
          },
          "notes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "Health": {
        "type": "object",
        "required": ["ok", "usingSeedFallback", "hasKvBinding"],
        "properties": {
          "ok": { "type": "boolean" },
          "lastUpdatedAt": {
            "type": ["string", "null"],
            "format": "date-time"
          },
          "ageHours": {
            "type": ["number", "null"]
          },
          "maxFreshHours": { "type": "number" },
          "usingSeedFallback": { "type": "boolean" },
          "hasKvBinding": { "type": "boolean" }
        }
      },
      "EvalSummary": {
        "type": "object",
        "required": ["suite", "status", "passed", "total", "tasks"],
        "properties": {
          "suite": { "type": "string" },
          "status": { "type": "string" },
          "passed": { "type": "integer", "minimum": 0 },
          "total": { "type": "integer", "minimum": 0 },
          "updatedAt": {
            "type": ["string", "null"],
            "format": "date-time"
          },
          "tasks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EvalTask"
            }
          }
        }
      },
      "EvalCoverage": {
        "type": "object",
        "required": ["evaluated", "totalRanked", "unevaluatedCanStillWin"],
        "properties": {
          "evaluated": { "type": "integer", "minimum": 0 },
          "completedToday": { "type": "integer", "minimum": 0 },
          "attemptedToday": { "type": "integer", "minimum": 0 },
          "totalRanked": { "type": "integer", "minimum": 0 },
          "candidatePool": { "type": "integer", "minimum": 0 },
          "unevaluatedCanStillWin": { "type": "boolean" },
          "unevaluatedThreatCount": { "type": "integer", "minimum": 0 },
          "topUnevaluatedThreat": {
            "type": ["string", "null"]
          },
          "maxUnevaluatedPossibleScore": {
            "type": ["number", "null"]
          }
        }
      },
      "EvalTask": {
        "type": "object",
        "required": ["id", "source", "score", "points", "status"],
        "properties": {
          "id": { "type": "string" },
          "source": { "type": "string" },
          "score": { "type": "number", "minimum": 0 },
          "points": { "type": "number", "minimum": 0 },
          "maxPoints": { "type": "number", "minimum": 0 },
          "status": { "type": "string" },
          "details": { "type": "object" }
        }
      }
    }
  }
}