{
  "openapi": "3.1.0",
  "info": {
    "title": "Spyglass Tools API",
    "description": "REST API for 220+ verified SaaS tools. Access pricing data, feature comparisons, category insights, and competitive intelligence. Build competitive analysis into your product — no AI hallucinations, just structured data.\n\n**Free tier:** 30 requests/minute per IP. No API key required.\n**Starter:** $9/month — 1,000 requests/month, API key.\n**Pro:** $29/month — 10,000 requests/month, priority support, all endpoints.",
    "version": "1.0.0",
    "contact": {
      "name": "Spyglass",
      "url": "https://www.spyglassci.com",
      "email": "hello@spyglassci.com"
    },
    "x-logo": {
      "url": "https://www.spyglassci.com/images/og-api.png"
    }
  },
  "servers": [
    {
      "url": "https://www.spyglassci.com",
      "description": "Production"
    }
  ],
  "tags": [
    { "name": "Tools", "description": "Search and retrieve SaaS tool data" },
    { "name": "Compare", "description": "Side-by-side tool comparisons" },
    { "name": "Categories", "description": "Category listings and stats" },
    { "name": "Account", "description": "Subscription and API key management" }
  ],
  "paths": {
    "/api/v1/tools": {
      "get": {
        "tags": ["Tools"],
        "summary": "Search and list tools",
        "description": "Returns a paginated list of SaaS tools with filters for category, pricing model, and free tier. Use the `slug` parameter to retrieve a single tool with its competitors.",
        "operationId": "listTools",
        "parameters": [
          { "name": "q", "in": "query", "description": "Search by name, category, description, or differentiator", "schema": { "type": "string" } },
          { "name": "search", "in": "query", "description": "Alias for q", "schema": { "type": "string" } },
          { "name": "slug", "in": "query", "description": "Retrieve a single tool by slug (e.g. notion, stripe). Returns tool detail + same-category competitors.", "schema": { "type": "string" } },
          { "name": "category", "in": "query", "description": "Filter by exact category name (e.g. Analytics, CRM, Design)", "schema": { "type": "string" } },
          { "name": "model", "in": "query", "description": "Filter by pricing model (Freemium, Subscription, Usage-based, Free)", "schema": { "type": "string" } },
          { "name": "free", "in": "query", "description": "Filter by free tier availability (true or false)", "schema": { "type": "string", "enum": ["true", "false"] } },
          { "name": "sort", "in": "query", "description": "Sort order", "schema": { "type": "string", "enum": ["name", "category", "price"], "default": "name" } },
          { "name": "limit", "in": "query", "description": "Results per page (1-100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } },
          { "name": "offset", "in": "query", "description": "Pagination offset", "schema": { "type": "integer", "minimum": 0, "default": 0 } }
        ],
        "security": [{}, { "ApiKeyHeader": [] }],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ToolsListResponse" },
                "example": {
                  "api_version": "1.0.0",
                  "total": 220,
                  "offset": 0,
                  "limit": 2,
                  "tools": [
                    {
                      "slug": "notion",
                      "name": "Notion",
                      "url": "https://notion.so",
                      "category": "Project Management",
                      "pricing_model": "Freemium",
                      "starting_price": "$0",
                      "free_tier": true,
                      "description": "All-in-one workspace for notes, docs, databases, and wikis",
                      "differentiator": "Infinite flexibility — build any workflow with blocks",
                      "features": ["Block editor", "Databases", "Wikis", "AI assistant"],
                      "target_audience": "Startups, individuals, teams 5-500"
                    }
                  ],
                  "categories_available": ["Analytics", "CRM", "Design", "Project Management"]
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/RateLimitError" }
              }
            }
          }
        }
      }
    },
    "/api/v1/tools/{slug}": {
      "get": {
        "tags": ["Tools"],
        "summary": "Get tool by slug",
        "description": "Retrieve a single tool by its URL slug with same-category competitors and category statistics.",
        "operationId": "getToolBySlug",
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "description": "Tool slug (e.g. notion, stripe, vercel)", "schema": { "type": "string" } }
        ],
        "security": [{}, { "ApiKeyHeader": [] }],
        "responses": {
          "200": {
            "description": "Tool found",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ToolDetailResponse" },
                "example": {
                  "api_version": "1.0.0",
                  "tool": {
                    "slug": "notion",
                    "name": "Notion",
                    "url": "https://notion.so",
                    "category": "Project Management",
                    "pricing_model": "Freemium",
                    "starting_price": "$0",
                    "free_tier": true,
                    "description": "All-in-one workspace",
                    "differentiator": "Infinite flexibility with block editor",
                    "features": ["Block editor", "Databases", "Wikis"],
                    "target_audience": "Startups, individuals"
                  },
                  "category_stats": {
                    "total_in_category": 25,
                    "free_tier_count": 15
                  },
                  "competitors": [
                    { "slug": "airtable", "name": "Airtable", "url": "https://airtable.com", "starting_price": "$0", "free_tier": true, "pricing_model": "Freemium", "differentiator": "Spreadsheet-database hybrid" }
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Tool not found"
          }
        }
      }
    },
    "/api/v1/compare": {
      "get": {
        "tags": ["Compare"],
        "summary": "Compare two tools",
        "description": "Side-by-side comparison of two SaaS tools with feature gap analysis, competitive intensity score, and category context.",
        "operationId": "compareTools",
        "parameters": [
          { "name": "a", "in": "query", "required": true, "description": "First tool slug or name", "schema": { "type": "string" } },
          { "name": "tool1", "in": "query", "description": "Alias for a", "schema": { "type": "string" } },
          { "name": "b", "in": "query", "required": true, "description": "Second tool slug or name", "schema": { "type": "string" } },
          { "name": "tool2", "in": "query", "description": "Alias for b", "schema": { "type": "string" } }
        ],
        "security": [{}, { "ApiKeyHeader": [] }],
        "responses": {
          "200": {
            "description": "Comparison result",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CompareResponse" },
                "example": {
                  "api_version": "1.0.0",
                  "comparison": {
                    "tool_a": { "slug": "notion", "name": "Notion", "category": "Project Management", "pricing_model": "Freemium", "starting_price": "$0", "free_tier": true },
                    "tool_b": { "slug": "airtable", "name": "Airtable", "category": "Project Management", "pricing_model": "Freemium", "starting_price": "$0", "free_tier": true }
                  },
                  "feature_analysis": {
                    "shared_features": ["Collaboration", "Integrations"],
                    "tool_a_only": ["Block editor", "Wikis", "AI assistant"],
                    "tool_b_only": ["Spreadsheet interface", "Views", "Extensions"]
                  },
                  "category_context": {
                    "category": "Project Management",
                    "same_category": true,
                    "total_tools_in_category": 25,
                    "free_tier_percentage": 60,
                    "competitive_intensity": 72,
                    "intensity_label": "High",
                    "competitors_in_category": [
                      { "slug": "clickup", "name": "ClickUp", "starting_price": "$0", "free_tier": true }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing a or b parameter"
          },
          "404": {
            "description": "One or both tools not found"
          }
        }
      }
    },
    "/api/v1/categories": {
      "get": {
        "tags": ["Categories"],
        "summary": "List all categories",
        "description": "Returns all tool categories with tool counts, free tier statistics, pricing models, and top tools per category.",
        "operationId": "listCategories",
        "security": [{}, { "ApiKeyHeader": [] }],
        "responses": {
          "200": {
            "description": "Categories list",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CategoriesResponse" },
                "example": {
                  "api_version": "1.0.0",
                  "total_categories": 20,
                  "total_tools": 220,
                  "categories": [
                    {
                      "category": "Project Management",
                      "tool_count": 25,
                      "free_tier_count": 15,
                      "free_tier_percentage": 60,
                      "pricing_models": ["Freemium", "Subscription", "Free"],
                      "top_tools": [
                        { "slug": "notion", "name": "Notion", "starting_price": "$0", "free_tier": true }
                      ]
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/checkout": {
      "post": {
        "tags": ["Account"],
        "summary": "Create API subscription checkout",
        "description": "Creates a Stripe Checkout Session for API subscription ($9/month Starter, $29/month Pro). Returns a checkout URL for redirect.",
        "operationId": "createCheckout",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CheckoutRequest" },
              "example": {
                "email": "developer@example.com",
                "tier": "starter"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Checkout session created",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CheckoutResponse" },
                "example": {
                  "success": true,
                  "checkout_url": "https://checkout.stripe.com/c/pay/cs_test_..."
                }
              }
            }
          },
          "400": {
            "description": "Invalid email or missing fields"
          },
          "500": {
            "description": "Payment service error"
          }
        }
      }
    },
    "/api/v1/validate-key": {
      "post": {
        "tags": ["Account"],
        "summary": "Validate an API key",
        "description": "Check if an API key is valid and return its tier and usage info.",
        "operationId": "validateKey",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ValidateKeyRequest" },
              "example": {
                "key": "spyglass_v1_aBcDeFgHiJkLmNoPqRsTuVwXyZ1234567890"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Validation result",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ValidateKeyResponse" },
                "example": {
                  "valid": true,
                  "tier": "starter",
                  "email": "developer@example.com",
                  "requests_this_month": 42
                }
              }
            }
          },
          "400": {
            "description": "Invalid API key format"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "API key for higher rate limits. Get one by subscribing at https://www.spyglassci.com/api-docs"
      }
    },
    "schemas": {
      "Tool": {
        "type": "object",
        "properties": {
          "slug": { "type": "string", "example": "notion" },
          "name": { "type": "string", "example": "Notion" },
          "url": { "type": "string", "format": "uri", "example": "https://notion.so" },
          "category": { "type": "string", "example": "Project Management" },
          "pricing_model": { "type": "string", "example": "Freemium" },
          "starting_price": { "type": "string", "example": "$0" },
          "free_tier": { "type": "boolean", "example": true },
          "description": { "type": "string", "example": "All-in-one workspace" },
          "differentiator": { "type": "string", "example": "Infinite flexibility with blocks" },
          "features": { "type": "array", "items": { "type": "string" } },
          "target_audience": { "type": "string", "example": "Startups, individuals" }
        }
      },
      "ToolsListResponse": {
        "type": "object",
        "properties": {
          "api_version": { "type": "string", "example": "1.0.0" },
          "total": { "type": "integer", "example": 220 },
          "offset": { "type": "integer", "example": 0 },
          "limit": { "type": "integer", "example": 50 },
          "tools": { "type": "array", "items": { "$ref": "#/components/schemas/Tool" } },
          "categories_available": { "type": "array", "items": { "type": "string" } }
        }
      },
      "ToolDetailResponse": {
        "type": "object",
        "properties": {
          "api_version": { "type": "string" },
          "tool": { "$ref": "#/components/schemas/Tool" },
          "category_stats": {
            "type": "object",
            "properties": {
              "total_in_category": { "type": "integer" },
              "free_tier_count": { "type": "integer" }
            }
          },
          "competitors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "slug": { "type": "string" },
                "name": { "type": "string" },
                "url": { "type": "string" },
                "starting_price": { "type": "string" },
                "free_tier": { "type": "boolean" },
                "pricing_model": { "type": "string" },
                "differentiator": { "type": "string" }
              }
            }
          }
        }
      },
      "CompareResponse": {
        "type": "object",
        "properties": {
          "api_version": { "type": "string" },
          "comparison": {
            "type": "object",
            "properties": {
              "tool_a": { "$ref": "#/components/schemas/Tool" },
              "tool_b": { "$ref": "#/components/schemas/Tool" }
            }
          },
          "feature_analysis": {
            "type": "object",
            "properties": {
              "shared_features": { "type": "array", "items": { "type": "string" } },
              "tool_a_only": { "type": "array", "items": { "type": "string" } },
              "tool_b_only": { "type": "array", "items": { "type": "string" } }
            }
          },
          "category_context": {
            "type": "object",
            "properties": {
              "category": { "type": "string" },
              "same_category": { "type": "boolean" },
              "total_tools_in_category": { "type": "integer" },
              "free_tier_percentage": { "type": "integer" },
              "competitive_intensity": { "type": "integer" },
              "intensity_label": { "type": "string", "enum": ["Low", "Medium", "High"] },
              "competitors_in_category": { "type": "array", "items": { "type": "object" } }
            }
          }
        }
      },
      "CategoriesResponse": {
        "type": "object",
        "properties": {
          "api_version": { "type": "string" },
          "total_categories": { "type": "integer" },
          "total_tools": { "type": "integer" },
          "categories": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "category": { "type": "string" },
                "tool_count": { "type": "integer" },
                "free_tier_count": { "type": "integer" },
                "free_tier_percentage": { "type": "integer" },
                "pricing_models": { "type": "array", "items": { "type": "string" } },
                "top_tools": { "type": "array", "items": { "type": "object" } }
              }
            }
          }
        }
      },
      "CheckoutRequest": {
        "type": "object",
        "required": ["email"],
        "properties": {
          "email": { "type": "string", "format": "email", "description": "Customer email for the subscription" },
          "tier": { "type": "string", "enum": ["starter", "pro"], "default": "starter", "description": "Subscription tier" }
        }
      },
      "CheckoutResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean" },
          "checkout_url": { "type": "string", "format": "uri", "description": "Stripe Checkout URL to redirect the user to" }
        }
      },
      "ValidateKeyRequest": {
        "type": "object",
        "required": ["key"],
        "properties": {
          "key": { "type": "string", "description": "API key to validate" }
        }
      },
      "ValidateKeyResponse": {
        "type": "object",
        "properties": {
          "valid": { "type": "boolean" },
          "tier": { "type": "string", "enum": ["starter", "pro"] },
          "email": { "type": "string", "format": "email" },
          "requests_this_month": { "type": "integer" }
        }
      },
      "RateLimitError": {
        "type": "object",
        "properties": {
          "error": { "type": "string", "example": "Rate limit exceeded" },
          "limit": { "type": "integer", "example": 30 },
          "retry_after_seconds": { "type": "integer", "example": 45 },
          "message": { "type": "string" }
        }
      }
    }
  }
}