{
  "openapi": "3.1.0",
  "info": {
    "title": "AI123Box Public API",
    "version": "1.0.0",
    "summary": "Agent-friendly JSON API over the AI123Box (AI百宝箱) AI tool directory.",
    "description": "Read-only JSON API covering 2900+ curated AI tools across 23 categories. Designed to be called by AI agents: simple query parameters, deterministic responses, CORS-enabled, 5-minute CDN cache.",
    "contact": { "name": "AI123Box", "url": "https://ai123box.com" },
    "license": { "name": "Attribution — link back to ai123box.com" }
  },
  "servers": [
    { "url": "https://ai123box.com", "description": "Production" }
  ],
  "paths": {
    "/api/tools": {
      "get": {
        "summary": "Search or list AI tools",
        "operationId": "searchTools",
        "description": "Returns a paginated list of AI tools. Supports full-text search across name, description, category, and tags. When `id` is provided, returns a single tool object (not wrapped in `{tools, total}`).",
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "description": "Free-text query matched against name, description, category and tags (case-insensitive LIKE).",
            "schema": { "type": "string" }
          },
          {
            "name": "category",
            "in": "query",
            "description": "Exact category name (Chinese). Pass `全部` or omit for all.",
            "schema": {
              "type": "string",
              "enum": [
                "全部", "对话助手", "图像生成", "视频生成", "音乐音频",
                "编程开发", "写作内容", "设计工具", "办公效率", "模型平台",
                "AI Agent", "AI 搜索", "AI 科研", "商业营销", "AI 基础设施",
                "提示工程", "数据工具", "内容检测", "求职学习", "社区资源",
                "行业报告", "模型评测", "开源项目", "其他工具"
              ]
            }
          },
          {
            "name": "sort",
            "in": "query",
            "description": "Sort order. Default `hot` ranks recently-updated high-rated tools first.",
            "schema": {
              "type": "string",
              "enum": ["hot", "rating", "newest", "name"],
              "default": "hot"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Max rows returned.",
            "schema": { "type": "integer", "default": 200, "minimum": 1, "maximum": 500 }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Row offset for pagination.",
            "schema": { "type": "integer", "default": 0, "minimum": 0 }
          },
          {
            "name": "id",
            "in": "query",
            "description": "If provided, returns a single tool by stable id (e.g. `chatgpt`, `claude`, `cursor`).",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    { "$ref": "#/components/schemas/ToolList" },
                    { "$ref": "#/components/schemas/Tool" }
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Tool id not found (only when `id` query is used).",
            "content": {
              "application/json": {
                "schema": { "type": "object", "properties": { "error": { "type": "string" } } }
              }
            }
          }
        }
      }
    },
    "/data/tools.json": {
      "get": {
        "summary": "Full tool snapshot",
        "operationId": "fullSnapshot",
        "description": "Static JSON of every tool in the directory. Useful for batch ingestion or training-time embedding. Updated on every deploy.",
        "responses": {
          "200": {
            "description": "Array of Tool",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/Tool" }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Tool": {
        "type": "object",
        "required": ["id", "name", "url", "category"],
        "properties": {
          "id": { "type": "string", "description": "Stable identifier, e.g. `chatgpt`." },
          "name": { "type": "string", "description": "Display name." },
          "desc": { "type": "string", "description": "One-line Chinese description." },
          "url": { "type": "string", "format": "uri", "description": "Canonical homepage." },
          "category": { "type": "string", "description": "Category in Chinese." },
          "tags": { "type": "array", "items": { "type": "string" } },
          "hot": { "type": "boolean", "description": "Trending (high rating + recent update)." },
          "isNew": { "type": "boolean", "description": "Added or updated within the last 30 days." },
          "rating": { "type": "number", "minimum": 0, "maximum": 5 },
          "users": { "type": "string", "description": "Approximate user count, e.g. `200M+`." },
          "updated": { "type": "string", "format": "date" },
          "source": { "type": "string" },
          "addedAt": { "type": "string", "format": "date" }
        }
      },
      "ToolList": {
        "type": "object",
        "required": ["tools", "total"],
        "properties": {
          "tools": { "type": "array", "items": { "$ref": "#/components/schemas/Tool" } },
          "total": { "type": "integer", "description": "Total matching rows ignoring limit/offset." }
        }
      }
    }
  }
}