{
  "openapi": "3.1.0",
  "info": {
    "title": "QHSE Tech Public API",
    "version": "1.1.0",
    "summary": "Read-only access to the QHSE Tech software directory.",
    "description": "Public REST API providing programmatic access to QHSE & ESG software products, categories, reviews, glossary terms, and AI-powered semantic search. Free tier with API-key authentication and request logging.",
    "contact": { "name": "QHSE Tech", "url": "https://qhsetech.com/contact", "email": "info@qhsetech.com" },
    "license": { "name": "Proprietary — fair use", "url": "https://qhsetech.com/api-docs" }
  },
  "servers": [
    { "url": "https://nypdfolwwyubfqqljmxj.functions.supabase.co/public-api", "description": "Production" }
  ],
  "security": [{ "bearerAuth": [] }],
  "tags": [
    { "name": "Software", "description": "QHSE & ESG software products" },
    { "name": "Categories", "description": "Software categories taxonomy" },
    { "name": "Reviews", "description": "User-submitted reviews" },
    { "name": "Glossary", "description": "QHSE terminology" },
    { "name": "Search", "description": "AI-powered semantic search" },
    { "name": "Meta", "description": "Service metadata" }
  ],
  "paths": {
    "/": {
      "get": {
        "tags": ["Meta"],
        "summary": "Service info & health check",
        "description": "Public health-check endpoint. No authentication required.",
        "security": [],
        "responses": {
          "200": {
            "description": "Service metadata",
            "headers": {
              "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }
            },
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceInfo" } } }
          }
        }
      }
    },
    "/v1/software": {
      "get": {
        "tags": ["Software"],
        "summary": "List software products",
        "description": "Paginated, filtered list of software products. Default sort is by rating descending.",
        "parameters": [
          { "name": "category", "in": "query", "required": false, "schema": { "type": "string" } },
          { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } },
          { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of software products.",
            "headers": {
              "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } },
              "Cache-Control": { "schema": { "type": "string", "example": "public, max-age=60" } }
            },
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoftwareListResponse" } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "500": { "$ref": "#/components/responses/ServerError" }
        }
      }
    },
    "/v1/software/{id}": {
      "get": {
        "tags": ["Software"],
        "summary": "Get a single software product",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "tekmon" }
        ],
        "responses": {
          "200": {
            "description": "Software product detail.",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SoftwareProduct" } } } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "500": { "$ref": "#/components/responses/ServerError" }
        }
      }
    },
    "/v1/categories": {
      "get": {
        "tags": ["Categories"],
        "summary": "List categories with counts",
        "responses": {
          "200": {
            "description": "Categories with product counts.",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } } } } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "500": { "$ref": "#/components/responses/ServerError" }
        }
      }
    },
    "/v1/reviews/{softwareId}": {
      "get": {
        "tags": ["Reviews"],
        "summary": "List approved reviews for a software product",
        "parameters": [
          { "name": "softwareId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "tekmon" }
        ],
        "responses": {
          "200": {
            "description": "Approved reviews (max 100, newest first).",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Review" } } } } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "500": { "$ref": "#/components/responses/ServerError" }
        }
      }
    },
    "/v1/glossary": {
      "get": {
        "tags": ["Glossary"],
        "summary": "List QHSE glossary terms",
        "parameters": [
          { "name": "q", "in": "query", "required": false, "description": "Substring filter on term or definition.", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Glossary terms.",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GlossaryTerm" } } } } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/v1/search": {
      "get": {
        "tags": ["Search"],
        "summary": "AI-ranked semantic search across the catalog",
        "parameters": [
          { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "example": "software for ISO 45001 audits" },
          { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 25, "default": 10 } }
        ],
        "responses": {
          "200": {
            "description": "Ranked search results.",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SoftwareProduct" } } } } } }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "qhse_live_<random>",
        "description": "Generate at https://qhsetech.com/api-docs and pass as `Authorization: Bearer <key>`."
      }
    },
    "schemas": {
      "ServiceInfo": {
        "type": "object",
        "properties": {
          "service": { "type": "string", "example": "QHSE Tech Public API" },
          "version": { "type": "string", "example": "v1" },
          "status": { "type": "string", "example": "ok" },
          "time": { "type": "string", "format": "date-time" },
          "docs": { "type": "string", "format": "uri" },
          "endpoints": { "type": "array", "items": { "type": "string" } }
        }
      },
      "SoftwareProduct": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "example": "tekmon" },
          "name": { "type": "string", "example": "Tekmon" },
          "tagline": { "type": "string" },
          "description": { "type": "string" },
          "category": { "type": "string", "example": "EHS" },
          "category_tags": { "type": "array", "items": { "type": "string" } },
          "website": { "type": "string", "format": "uri" },
          "pricing_model": { "type": "string" },
          "pricing_starting_at": { "type": "string", "nullable": true },
          "rating": { "type": "number", "format": "float" },
          "review_count": { "type": "integer" },
          "badge": { "type": "string", "nullable": true },
          "industries": { "type": "array", "items": { "type": "string" } },
          "company_size": { "type": "array", "items": { "type": "string" } },
          "certifications": { "type": "array", "items": { "type": "string" } }
        },
        "required": ["id", "name", "category"]
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "limit": { "type": "integer" },
          "offset": { "type": "integer" },
          "total": { "type": "integer" },
          "has_more": { "type": "boolean" },
          "next_offset": { "type": "integer", "nullable": true }
        }
      },
      "SoftwareListResponse": {
        "type": "object",
        "properties": {
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/SoftwareProduct" } },
          "pagination": { "$ref": "#/components/schemas/Pagination" }
        }
      },
      "Category": {
        "type": "object",
        "properties": {
          "name": { "type": "string", "example": "EHS" },
          "count": { "type": "integer", "example": 17 }
        }
      },
      "Review": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "software_id": { "type": "string" },
          "author_name": { "type": "string" },
          "author_role": { "type": "string", "nullable": true },
          "author_company": { "type": "string", "nullable": true },
          "rating": { "type": "integer", "minimum": 1, "maximum": 5 },
          "review_text": { "type": "string" },
          "source": { "type": "string", "nullable": true },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "GlossaryTerm": {
        "type": "object",
        "properties": {
          "term": { "type": "string", "example": "ISO 45001" },
          "definition": { "type": "string" },
          "related": { "type": "string", "description": "Path to the related guide page on qhsetech.com" }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": { "type": "string", "example": "not_found" },
              "message": { "type": "string", "example": "Software 'foo' not found" },
              "request_id": { "type": "string", "format": "uuid" }
            },
            "required": ["code", "message", "request_id"]
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid request parameters.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "Unauthorized": {
        "description": "Missing or invalid API key.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "Forbidden": {
        "description": "API key revoked.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "NotFound": {
        "description": "Resource not found.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "RateLimited": {
        "description": "Upstream AI service temporarily rate-limited.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "Unavailable": {
        "description": "Service temporarily unavailable.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "ServerError": {
        "description": "Internal server error.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    }
  }
}