{
  "openapi": "3.1.0",
  "info": {
    "title": "ToolSpotter API",
    "version": "1.0.0",
    "description": "Programmatic access to the ToolSpotter AI tool catalog. 750+ tools across 26 categories.",
    "contact": {
      "name": "ToolSpotter",
      "url": "https://toolspotter.com/developer/docs"
    }
  },
  "servers": [{ "url": "https://toolspotter.com/api/v1" }],
  "security": [{ "bearerAuth": [] }],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "ts_live_… or ts_test_…"
      }
    },
    "schemas": {
      "Tool": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "slug": { "type": "string" },
          "name": { "type": "string" },
          "tagline": { "type": "string", "nullable": true },
          "short_desc": { "type": "string", "nullable": true },
          "long_desc": { "type": "string", "nullable": true },
          "website_url": { "type": "string", "nullable": true },
          "logo_url": { "type": "string", "nullable": true },
          "pricing_model": { "type": "string", "nullable": true },
          "min_price": { "type": "number", "nullable": true },
          "rating": { "type": "number" },
          "review_count": { "type": "integer" },
          "categories": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } },
          "tags": { "type": "array", "items": { "type": "string" } },
          "video_id": { "type": "string", "nullable": true },
          "created_at": { "type": "string", "format": "date-time" },
          "updated_at": { "type": "string", "format": "date-time" }
        }
      },
      "Category": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "slug": { "type": "string" },
          "name": { "type": "string" },
          "emoji": { "type": "string", "nullable": true },
          "description": { "type": "string", "nullable": true },
          "tool_count": { "type": "integer" }
        }
      },
      "Review": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "tool_id": { "type": "string", "format": "uuid" },
          "rating": { "type": "integer" },
          "title": { "type": "string", "nullable": true },
          "body": { "type": "string" },
          "helpful_count": { "type": "integer" },
          "reviewer_display_name": { "type": "string" },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "Price": {
        "type": "object",
        "properties": {
          "plan_name": { "type": "string" },
          "price_monthly": { "type": "number", "nullable": true },
          "price_annual": { "type": "number", "nullable": true },
          "currency": { "type": "string" },
          "recorded_at": { "type": "string", "format": "date-time" }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "type": { "type": "string" },
              "message": { "type": "string" },
              "code": { "type": "integer" }
            }
          }
        }
      }
    }
  },
  "paths": {
    "/tools": {
      "get": {
        "summary": "List tools",
        "parameters": [
          { "name": "category", "in": "query", "schema": { "type": "string" } },
          { "name": "pricing_model", "in": "query", "schema": { "type": "string" } },
          { "name": "min_rating", "in": "query", "schema": { "type": "number" } },
          { "name": "sort", "in": "query", "schema": { "type": "string", "enum": ["rating", "newest", "clicks"] } },
          { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }
        ],
        "responses": {
          "200": {
            "description": "Paginated tool list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/Tool" } },
                    "meta": { "type": "object" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/tools/{slug}": {
      "get": {
        "summary": "Get a single tool",
        "parameters": [{ "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Tool record" }, "404": { "description": "Not found" } }
      }
    },
    "/tools/{slug}/reviews": {
      "get": {
        "summary": "List reviews (Business plan)",
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }
        ],
        "responses": { "200": { "description": "Reviews list" }, "403": { "description": "Scope not allowed" } }
      }
    },
    "/tools/{slug}/prices": {
      "get": {
        "summary": "List pricing plans (Business plan)",
        "parameters": [{ "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Pricing list" }, "403": { "description": "Scope not allowed" } }
      }
    },
    "/categories": {
      "get": {
        "summary": "List categories",
        "responses": { "200": { "description": "Categories list" } }
      }
    },
    "/categories/{slug}": {
      "get": {
        "summary": "Get category + top tools",
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }
        ],
        "responses": { "200": { "description": "Category with tools" }, "404": { "description": "Not found" } }
      }
    },
    "/search": {
      "get": {
        "summary": "Full-text search",
        "parameters": [
          { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2 } },
          { "name": "limit", "in": "query", "schema": { "type": "integer" } }
        ],
        "responses": { "200": { "description": "Matching tools" } }
      }
    }
  }
}