{
 "openapi": "3.1.0",
 "info": {
  "title": "LLMs Technical Reviews API",
  "version": "1.0.0",
  "description": "Static, read-only JSON describing source-level reviews of open-source LLM tooling. No authentication. Rate limited to 10 requests/second per client (burst 40)."
 },
 "servers": [
  {
   "url": "https://llms-technical-reviews.com",
   "description": "Production"
  }
 ],
 "security": [],
 "paths": {
  "/api/v1/categories.json": {
   "get": {
    "operationId": "listCategories",
    "summary": "List categories",
    "description": "Every category with its comparison questions and the slugs of its published projects.",
    "responses": {
     "200": {
      "description": "All categories",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/CategoryList"
        }
       }
      }
     },
     "429": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/projects.json": {
   "get": {
    "operationId": "listProjects",
    "summary": "List projects",
    "description": "Every published project with repository, pinned commit, tagline and stack. The full list is returned in one response (no pagination; under 100 items).",
    "responses": {
     "200": {
      "description": "All projects",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ProjectList"
        }
       }
      }
     },
     "429": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/projects/{slug}.json": {
   "get": {
    "operationId": "getProject",
    "summary": "Get a project",
    "description": "Editorial overview (markdown) and every per-question answer with citations at the pinned commit.",
    "parameters": [
     {
      "name": "slug",
      "in": "path",
      "required": true,
      "description": "Project slug from listProjects",
      "schema": {
       "type": "string",
       "description": "Project slug from listProjects",
       "example": "stagehand"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Project detail",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ProjectDetail"
        }
       }
      }
     },
     "404": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/questions/{category}/{qid}.json": {
   "get": {
    "operationId": "getQuestion",
    "summary": "Get a comparison question",
    "description": "The editor verdict plus one answer per published project in the category.",
    "parameters": [
     {
      "name": "category",
      "in": "path",
      "required": true,
      "description": "Category id from listCategories",
      "schema": {
       "type": "string",
       "description": "Category id from listCategories",
       "example": "browser-control"
      }
     },
     {
      "name": "qid",
      "in": "path",
      "required": true,
      "description": "Question id from listCategories",
      "schema": {
       "type": "string",
       "description": "Question id from listCategories",
       "example": "page-perception"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Question detail",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/QuestionDetail"
        }
       }
      }
     },
     "404": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/status.json": {
   "get": {
    "operationId": "getStatus",
    "summary": "Build status",
    "description": "When the data was last rebuilt and how much it contains.",
    "responses": {
     "200": {
      "description": "Status",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Status"
        }
       }
      }
     },
     "429": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  }
 },
 "components": {
  "securitySchemes": {},
  "schemas": {
   "Error": {
    "type": "object",
    "description": "Problem details",
    "required": [
     "type",
     "title",
     "status",
     "message"
    ],
    "properties": {
     "type": {
      "type": "string",
      "description": "Error type URI"
     },
     "title": {
      "type": "string",
      "description": "Short title"
     },
     "status": {
      "type": "integer",
      "description": "HTTP status"
     },
     "message": {
      "type": "string",
      "description": "What went wrong"
     },
     "retry_hint": {
      "type": "string",
      "description": "do_not_retry or retry_after_seconds:N"
     }
    }
   },
   "Citation": {
    "type": "object",
    "description": "A line range in the repository at the pinned commit",
    "properties": {
     "path": {
      "type": "string",
      "description": "Repo-relative file path"
     },
     "start": {
      "type": "integer",
      "description": "First line (1-based)"
     },
     "end": {
      "type": "integer",
      "description": "Last line"
     }
    }
   },
   "Answer": {
    "type": "object",
    "description": "One project's answer to one question",
    "properties": {
     "qid": {
      "type": "string",
      "description": "Question id"
     },
     "status": {
      "type": "string",
      "enum": [
       "answered",
       "not_applicable",
       "insufficient_evidence"
      ],
      "description": "Answer status"
     },
     "answer": {
      "type": "string",
      "description": "Markdown answer"
     },
     "citations": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Citation"
      },
      "description": "Verified citations"
     },
     "editor_note": {
      "type": "string",
      "description": "Editor's correction, if any"
     }
    }
   },
   "Project": {
    "type": "object",
    "description": "A reviewed repository",
    "properties": {
     "slug": {
      "type": "string",
      "description": "Slug"
     },
     "repo": {
      "type": "string",
      "description": "owner/name on GitHub"
     },
     "category": {
      "type": "string",
      "description": "Category id"
     },
     "tagline": {
      "type": "string",
      "description": "One-line summary"
     },
     "sha": {
      "type": "string",
      "description": "Pinned commit"
     },
     "stars": {
      "type": "integer",
      "description": "GitHub stars at build"
     }
    }
   },
   "ProjectList": {
    "type": "object",
    "description": "Projects",
    "properties": {
     "projects": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Project"
      },
      "description": "All projects"
     }
    }
   },
   "ProjectDetail": {
    "allOf": [
     {
      "$ref": "#/components/schemas/Project"
     },
     {
      "type": "object",
      "properties": {
       "overview_markdown": {
        "type": "string",
        "description": "Editorial overview"
       },
       "answers": {
        "type": "array",
        "items": {
         "$ref": "#/components/schemas/Answer"
        },
        "description": "Answers"
       }
      }
     }
    ],
    "description": "Project with overview and answers"
   },
   "CategoryList": {
    "type": "object",
    "description": "Categories",
    "properties": {
     "categories": {
      "type": "array",
      "description": "All categories",
      "items": {
       "type": "object",
       "description": "Category",
       "properties": {
        "id": {
         "type": "string",
         "description": "Id"
        },
        "title": {
         "type": "string",
         "description": "Title"
        },
        "projects": {
         "type": "array",
         "items": {
          "type": "string"
         },
         "description": "Project slugs"
        },
        "questions": {
         "type": "array",
         "description": "Questions",
         "items": {
          "type": "object",
          "description": "Question",
          "properties": {
           "qid": {
            "type": "string",
            "description": "Id"
           },
           "title": {
            "type": "string",
            "description": "Question"
           }
          }
         }
        }
       }
      }
     }
    }
   },
   "QuestionDetail": {
    "type": "object",
    "description": "A question with verdict and answers",
    "properties": {
     "title": {
      "type": "string",
      "description": "Question"
     },
     "verdict_markdown": {
      "type": "string",
      "description": "Editor verdict"
     },
     "answers": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Answer"
      },
      "description": "One answer per project"
     }
    }
   },
   "Status": {
    "type": "object",
    "description": "Build status",
    "properties": {
     "status": {
      "type": "string",
      "description": "ok"
     },
     "last_updated": {
      "type": "string",
      "format": "date-time",
      "description": "Build time"
     },
     "incidents": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Open incidents"
     }
    }
   }
  }
 }
}