{
  "openapi": "3.0.3",
  "info": {
    "title": "Zoipi Public Discovery API",
    "version": "1.0.0",
    "description": "Read-only JSON endpoints for discovering AI tools and MCP servers listed on Zoipi. Free to use with attribution to Zoipi (https://zoipi.com).",
    "contact": { "name": "Zoipi Support", "email": "contact@zoipi.com", "url": "https://zoipi.com/contact" },
    "license": { "name": "Free to cite with attribution" }
  },
  "servers": [{ "url": "https://zoipi.com", "description": "Production" }],
  "tags": [
    { "name": "tools", "description": "AI tool and MCP server listings" },
    { "name": "categories", "description": "Directory taxonomy" }
  ],
  "paths": {
    "/api/tools": {
      "get": {
        "tags": ["tools"],
        "operationId": "listTools",
        "summary": "List and search approved AI tools",
        "description": "Returns approved directory listings. Supports full-text style search plus filtering by category, pricing, foundation model, BYOK support and MCP type.",
        "parameters": [
          { "name": "q", "in": "query", "description": "Search query matched against tool name and description.", "required": false, "schema": { "type": "string", "maxLength": 120 } },
          { "name": "category", "in": "query", "description": "Category name or slug.", "required": false, "schema": { "type": "string" } },
          { "name": "pricing", "in": "query", "description": "Pricing tier filter.", "required": false, "schema": { "type": "string", "enum": ["Free", "Freemium", "Paid"] } },
          { "name": "model", "in": "query", "description": "Foundation model substring, e.g. \"GPT-4o\", \"Claude\", \"Stable Diffusion\".", "required": false, "schema": { "type": "string" } },
          { "name": "byok", "in": "query", "description": "Only return tools that support bringing your own API key.", "required": false, "schema": { "type": "boolean" } },
          { "name": "mcp", "in": "query", "description": "Filter to (true) or exclude (false) MCP servers.", "required": false, "schema": { "type": "boolean" } },
          { "name": "limit", "in": "query", "description": "Maximum results (1-200).", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } },
          { "name": "offset", "in": "query", "description": "Result offset for pagination.", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } }
        ],
        "responses": {
          "200": {
            "description": "A page of tools.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ToolList" }
              }
            }
          },
          "400": { "description": "Invalid query parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "503": { "description": "Directory temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/tools.json": {
      "get": {
        "tags": ["tools"],
        "operationId": "getToolsIndex",
        "summary": "Full machine-readable directory export",
        "description": "Complete JSON snapshot of every approved tool plus the category taxonomy. Intended for bulk ingestion by agents.",
        "responses": {
          "200": { "description": "Full directory export.", "content": { "application/json": { "schema": { "type": "object" } } } },
          "503": { "description": "Directory temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/categories": {
      "get": {
        "tags": ["categories"],
        "operationId": "listCategories",
        "summary": "List directory categories",
        "description": "Returns every category with its slug, description, icon and approved tool count.",
        "responses": {
          "200": {
            "description": "Category taxonomy.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryList" } } }
          },
          "503": { "description": "Directory temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Tool": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "slug": { "type": "string" },
          "zoipi_url": { "type": "string", "format": "uri" },
          "website": { "type": "string", "format": "uri" },
          "category": { "type": "string" },
          "categories": { "type": "array", "items": { "type": "string" } },
          "subcategory": { "type": "string", "nullable": true },
          "pricing": { "type": "string", "enum": ["Free", "Freemium", "Paid"] },
          "foundation_model": { "type": "string", "nullable": true },
          "byok": { "type": "boolean" },
          "is_mcp": { "type": "boolean" },
          "rating": { "type": "number", "format": "float" },
          "review_count": { "type": "integer" },
          "description": { "type": "string" },
          "listed_at": { "type": "string", "format": "date-time" }
        },
        "required": ["name", "slug", "zoipi_url", "website", "category", "pricing", "description"]
      },
      "ToolList": {
        "type": "object",
        "properties": {
          "source": { "type": "string", "example": "https://zoipi.com" },
          "generated_at": { "type": "string", "format": "date-time" },
          "count": { "type": "integer" },
          "limit": { "type": "integer" },
          "offset": { "type": "integer" },
          "tools": { "type": "array", "items": { "$ref": "#/components/schemas/Tool" } }
        },
        "required": ["count", "tools"]
      },
      "Category": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "slug": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "icon": { "type": "string", "nullable": true },
          "description": { "type": "string", "nullable": true },
          "tool_count": { "type": "integer" }
        },
        "required": ["name", "slug", "url"]
      },
      "CategoryList": {
        "type": "object",
        "properties": {
          "source": { "type": "string" },
          "generated_at": { "type": "string", "format": "date-time" },
          "count": { "type": "integer" },
          "categories": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } }
        },
        "required": ["count", "categories"]
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "boolean", "example": true },
          "code": { "type": "integer", "example": 404 },
          "message": { "type": "string", "example": "Resource not found" },
          "resolution": { "type": "string", "example": "Visit /openapi.json or /llms.txt for available endpoints" }
        },
        "required": ["error", "code", "message", "resolution"]
      }
    }
  }
}