{
  "openapi": "3.1.0",
  "info": {
    "title": "2D Digital Icons 图标 API",
    "version": "1.9.0",
    "description": "提供只读的图标目录搜索、来源静态/动画能力筛选、模型规划的动画 SVG、语义分类、PaintPlan 元数据、代码和受限 SVG 导出接口。目录整合 Iconify 与独立来源的图标集合；搜索与批量导出默认排除非商业许可集合。"
  },
  "externalDocs": {
    "description": "Agent 使用指南",
    "url": "https://icons.2d.digital/agents"
  },
  "servers": [
    {
      "url": "https://icons.2d.digital"
    }
  ],
  "paths": {
    "/api/v1/search": {
      "get": {
        "operationId": "searchIcons",
        "summary": "搜索图标",
        "parameters": [
          { "name": "q", "in": "query", "description": "使用英文或常见简体、繁体中文描述图标概念，例如 calendar outline、日历描边或日曆描邊。", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 120 } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 24, "default": 8 } },
          { "name": "cursor", "in": "query", "description": "由 nextCursor 返回的不透明续页令牌。复用时必须保持 q、limit、prefixes、category、variant、palette、motion 和 includeNonCommercial 完全一致。搜索最多允许 3 页，第三页不会继续返回令牌。", "schema": { "type": "string", "minLength": 1, "maxLength": 256 } },
          { "name": "prefixes", "in": "query", "description": "最多 8 个以逗号分隔的集合前缀。", "schema": { "type": "string" } },
          { "name": "category", "in": "query", "description": "使用 /api/v1/categories.json 中的精确分类 ID，例如 communications、e-commerce 或 science-technology。未知 ID 返回 400，不接受旧集合分类。", "schema": { "$ref": "#/components/schemas/CategoryId" } },
          { "name": "variant", "in": "query", "description": "精确的 UI 样式或变体标签，例如 Bold、Filled、Outline 或 Outline Rounded。匹配结果确定，并接受 fill/filled、outline/outlined、round/rounded、line/lines 等常见别名。可通过 /api/v1/collections 返回的 variants 字段查询支持的标签。", "schema": { "type": "string", "minLength": 1, "maxLength": 48 } },
          { "name": "palette", "in": "query", "schema": { "type": "string", "enum": ["any", "monotone", "color"], "default": "any" } },
          { "name": "motion", "in": "query", "description": "按动画能力或来源状态筛选。animated 表示存在原生或模型规划的动画变体；static 表示来源 SVG 原本静态。两者可重叠。", "schema": { "type": "string", "enum": ["any", "static", "animated"], "default": "any" } },
          { "name": "includeNonCommercial", "in": "query", "schema": { "type": "boolean", "default": false } }
        ],
        "responses": {
          "200": {
            "description": "不包含 SVG 正文的精简候选结果。",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" },
          "502": { "$ref": "#/components/responses/Error" },
          "503": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/v1/collections": {
      "get": {
        "operationId": "listCollections",
        "summary": "列出或筛选图标集合",
        "parameters": [
          { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 120 } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 250, "default": 24 } },
          { "name": "includeNonCommercial", "in": "query", "schema": { "type": "boolean", "default": false } }
        ],
        "responses": {
          "200": { "description": "返回集合摘要、支持的变体标签和许可元数据。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionListResponse" } } } },
          "400": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/v1/categories.json": {
      "get": {
        "operationId": "getIconCategories",
        "summary": "获取当前图标分类与 facets",
        "responses": {
          "200": { "description": "返回参考 Hugeicons 的 59 个平级分类、覆盖统计以及 asset type、style、grid facets。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoriesResponse" } } } }
        }
      }
    },
    "/api/v1/optimization.json": {
      "get": {
        "operationId": "getIconOptimizationReport",
        "summary": "获取全量 SVG 优化审计摘要",
        "responses": {
          "200": { "description": "返回确定性无损优化策略、逐集合统计、源/输出哈希以及完整逐图标压缩报告地址。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OptimizationResponse" } } } }
        }
      }
    },
    "/api/v1/paint-plans.json": {
      "get": {
        "operationId": "getPaintPlanReport",
        "summary": "获取全量 PaintPlan 编译与能力摘要",
        "responses": {
          "200": { "description": "返回确定性 PaintPlan 编译策略、能力与风险统计、逐集合哈希，以及完整分片报告地址。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaintPlanReport" } } } }
        }
      }
    },
    "/api/v1/motion.json": {
      "get": {
        "operationId": "getIconMotionReport",
        "summary": "获取全量动画规划与编译摘要",
        "responses": {
          "200": { "description": "返回模型规划器、确定性 SMIL 编译策略、动作配方和来源静态/原生/生成动画统计。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotionReport" } } } }
        }
      }
    },
    "/api/v1/icons/{prefix}/{name}": {
      "get": {
        "operationId": "getIcon",
        "summary": "获取单个图标的元数据或代码",
        "parameters": [
          { "name": "prefix", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/IconPart" } },
          { "name": "name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/IconPart" } },
          { "name": "target", "in": "query", "schema": { "$ref": "#/components/schemas/IconTarget" } },
          { "name": "size", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 512, "default": 24 } },
          { "$ref": "#/components/parameters/MotionDelivery" },
          { "$ref": "#/components/parameters/LegacyColor" },
          { "$ref": "#/components/parameters/LegacyColorMode" },
          { "$ref": "#/components/parameters/PaintRecipeQuery" },
          { "$ref": "#/components/parameters/ExpectedPaintFingerprint" }
        ],
        "responses": {
          "200": { "description": "始终包含作者、来源、许可和 PaintPlan 元数据；非 metadata 目标会在 content 字段中返回生成内容。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IconResponse" } } } },
          "400": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" },
          "413": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" },
          "502": { "$ref": "#/components/responses/Error" },
          "503": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/v1/icons/{prefix}/{name}.svg": {
      "get": {
        "operationId": "getIconSvg",
        "summary": "获取带来源说明注释的 SVG",
        "parameters": [
          { "name": "prefix", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/IconPart" } },
          { "name": "name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/IconPart" } },
          { "name": "size", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 512, "default": 24 } },
          { "$ref": "#/components/parameters/MotionDelivery" },
          { "$ref": "#/components/parameters/LegacyColor" },
          { "$ref": "#/components/parameters/LegacyColorMode" },
          { "$ref": "#/components/parameters/PaintRecipeQuery" },
          { "$ref": "#/components/parameters/ExpectedPaintFingerprint" }
        ],
        "responses": {
          "200": {
            "description": "返回 SVG；响应头保留许可、PaintPlan 指纹和非空 warning code。完整 PaintPlan 元数据可从同一路径的 JSON 响应取得。",
            "headers": {
              "X-Icon-License-SPDX": { "schema": { "type": "string" } },
              "X-Icon-Paint-Fingerprint": { "schema": { "$ref": "#/components/schemas/PaintFingerprint" } },
              "X-Icon-Paint-Warnings": { "description": "以逗号分隔的 PaintWarning code；没有 warning 时省略。", "schema": { "type": "string" } }
            },
            "content": { "image/svg+xml": { "schema": { "type": "string" } } }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" },
          "413": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" },
          "502": { "$ref": "#/components/responses/Error" },
          "503": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/v1/bundles/icons": {
      "get": {
        "operationId": "prepareIconDownload",
        "summary": "为选定图标准备无状态下载方案",
        "description": "接收来自最多 8 个集合的 1–24 个最终图标 ID。选择状态由调用方维护，服务端不会创建选择袋；非商业许可必须明确选择加入。",
        "parameters": [
          { "name": "id", "in": "query", "description": "每个选定的 prefix:name ID 分别传入一次。", "required": true, "schema": { "type": "array", "minItems": 1, "maxItems": 24, "items": { "$ref": "#/components/schemas/IconId" } }, "style": "form", "explode": true },
          { "name": "size", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 512, "default": 24 } },
          { "$ref": "#/components/parameters/MotionDelivery" },
          { "$ref": "#/components/parameters/LegacyColor" },
          { "$ref": "#/components/parameters/LegacyColorMode" },
          { "$ref": "#/components/parameters/PaintRecipeQuery" },
          { "$ref": "#/components/parameters/ExpectedPaintFingerprint" },
          { "name": "includeNonCommercial", "in": "query", "description": "仅在确认预期用途符合所有相关非商业许可后设为 true。", "schema": { "type": "boolean", "default": false } }
        ],
        "responses": {
          "200": { "description": "返回包含 ZIP 下载 URL 与归档内容说明的精简方案。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IconBundlePlan" } } } },
          "400": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/v1/bundles/icons.zip": {
      "get": {
        "operationId": "downloadSelectedIcons",
        "summary": "下载带许可元数据的选定独立 SVG",
        "description": "以流式方式返回内容确定的 ZIP，其中包含来自最多 8 个集合的独立 SVG 文件、icons-manifest.json，以及提供来源和许可参考的 THIRD_PARTY_NOTICES.md。非商业许可必须明确选择加入，无需安装 @iconify-json 包。",
        "parameters": [
          { "name": "id", "in": "query", "description": "每个选定的 prefix:name ID 分别传入一次。", "required": true, "schema": { "type": "array", "minItems": 1, "maxItems": 24, "items": { "$ref": "#/components/schemas/IconId" } }, "style": "form", "explode": true },
          { "name": "size", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 512, "default": 24 } },
          { "$ref": "#/components/parameters/MotionDelivery" },
          { "$ref": "#/components/parameters/LegacyColor" },
          { "$ref": "#/components/parameters/LegacyColorMode" },
          { "$ref": "#/components/parameters/PaintRecipeQuery" },
          { "$ref": "#/components/parameters/ExpectedPaintFingerprint" },
          { "name": "includeNonCommercial", "in": "query", "description": "仅在确认预期用途符合所有相关非商业许可后设为 true。", "schema": { "type": "boolean", "default": false } }
        ],
        "responses": {
          "200": { "description": "返回包含最多 24 个选定 SVG 的 ZIP；icons-manifest.json 为每个图标保留来源、许可、PaintPlan 元数据与 warning code。", "headers": { "X-Icon-Count": { "schema": { "type": "integer" } } }, "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } },
          "400": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" },
          "413": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" },
          "502": { "$ref": "#/components/responses/Error" },
          "503": { "$ref": "#/components/responses/Error" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "IconPart": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
      "IconId": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*:[a-z0-9]+(?:-[a-z0-9]+)*$" },
      "IconTarget": { "type": "string", "enum": ["metadata", "svg", "iconify", "react", "vue", "svelte", "unplugin-icons", "unocss", "tailwind-iconify", "css"], "default": "metadata" },
      "MotionDelivery": { "type": "string", "enum": ["source", "static", "animated"], "default": "source" },
      "MotionKind": { "type": "string", "enum": ["static", "animated"] },
      "MotionSource": { "type": "string", "enum": ["none", "native", "generated"] },
      "MotionRecipe": { "type": "string", "enum": ["blink", "bounce", "breathe", "drop", "flip", "float", "launch", "move-down", "move-left", "move-right", "move-up", "press", "pulse", "reveal", "ring", "rock", "rotate-ccw", "rotate-cw", "scan", "shake", "spin-loop", "squeeze", "tilt", "wave", "write"] },
      "ColorMode": { "type": "string", "enum": ["auto", "monochrome", "original"], "description": "旧颜色适配器模式；未提供 recipe 时，服务端才会推导默认值。" },
      "PaintValue": {
        "type": "string",
        "pattern": "^(?:currentColor|#[0-9a-fA-F]{3,4}|#[0-9a-fA-F]{6}|#[0-9a-fA-F]{8})$",
        "examples": ["currentColor", "#01c853", "#ffffffff"]
      },
      "PaintFingerprint": {
        "type": "string",
        "minLength": 1,
        "maxLength": 256,
        "pattern": "^[A-Za-z0-9._:+-]+$",
        "description": "由 compiler version、PaintPlan shard hash 与 plan index 派生的稳定几何身份。",
        "examples": ["1.2.0:8a7d04548bae24e4:0"]
      },
      "PaintRecipe": {
        "description": "声明式 PaintPlan 配方。palette 只改指定 slot；single-color 仅接受 capability=safe；tint 仅接受 tint=safe。",
        "oneOf": [
          {
            "type": "object",
            "required": ["mode"],
            "properties": { "mode": { "const": "original" } },
            "additionalProperties": false
          },
          {
            "type": "object",
            "required": ["mode", "overrides"],
            "properties": {
              "mode": { "const": "palette" },
              "overrides": {
                "type": "object",
                "maxProperties": 512,
                "patternProperties": { "^p(?:0|[1-9][0-9]*)$": { "$ref": "#/components/schemas/PaintValue" } },
                "additionalProperties": false
              }
            },
            "additionalProperties": false
          },
          {
            "type": "object",
            "required": ["mode", "color"],
            "properties": {
              "mode": { "const": "single-color" },
              "color": { "$ref": "#/components/schemas/PaintValue" }
            },
            "additionalProperties": false
          },
          {
            "type": "object",
            "required": ["mode", "color"],
            "properties": {
              "mode": { "const": "tint" },
              "color": { "$ref": "#/components/schemas/PaintValue" }
            },
            "additionalProperties": false
          }
        ]
      },
      "PaintCapability": { "type": "string", "enum": ["unsupported", "lossy", "safe"] },
      "PaintCapabilities": {
        "type": "object",
        "required": ["palette", "directMonochrome", "tint"],
        "properties": {
          "palette": { "type": "boolean" },
          "directMonochrome": { "$ref": "#/components/schemas/PaintCapability" },
          "tint": { "$ref": "#/components/schemas/PaintCapability" }
        },
        "additionalProperties": false
      },
      "PaintSlot": {
        "type": "object",
        "required": ["id", "label", "kind", "value", "atomIds"],
        "properties": {
          "id": { "type": "string", "pattern": "^p(?:0|[1-9][0-9]*)$" },
          "label": { "type": "string" },
          "kind": { "type": "string", "enum": ["solid", "gradient", "effect"] },
          "value": { "$ref": "#/components/schemas/PaintValue" },
          "atomIds": { "type": "array", "items": { "type": "string" } }
        },
        "additionalProperties": false
      },
      "PaintVariant": {
        "type": "object",
        "required": ["id", "label"],
        "properties": {
          "id": { "$ref": "#/components/schemas/IconId" },
          "label": { "type": "string", "enum": ["Mark", "With background"] }
        },
        "additionalProperties": false
      },
      "PaintWarning": { "type": "string", "enum": ["LOSSY_MONOCHROME", "PAINT_UNSUPPORTED", "RECIPE_NORMALIZED"] },
      "PaintMetadata": {
        "type": "object",
        "required": ["fingerprint", "recipe", "capabilities", "slots", "paintVariants", "warnings"],
        "properties": {
          "fingerprint": { "$ref": "#/components/schemas/PaintFingerprint" },
          "recipe": { "$ref": "#/components/schemas/PaintRecipe" },
          "capabilities": { "$ref": "#/components/schemas/PaintCapabilities" },
          "slots": { "type": "array", "items": { "$ref": "#/components/schemas/PaintSlot" } },
          "paintVariants": { "type": "array", "items": { "$ref": "#/components/schemas/PaintVariant" } },
          "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/PaintWarning" }, "uniqueItems": true }
        },
        "additionalProperties": false
      },
      "PaintRenderingRequest": {
        "type": "object",
        "required": ["size", "motion", "geometryChanged"],
        "properties": {
          "size": { "type": "integer", "minimum": 1, "maximum": 512 },
          "motion": { "$ref": "#/components/schemas/MotionDelivery" },
          "color": { "$ref": "#/components/schemas/PaintValue" },
          "colorMode": { "$ref": "#/components/schemas/ColorMode" },
          "recipe": { "$ref": "#/components/schemas/PaintRecipe" },
          "expectedFingerprint": { "$ref": "#/components/schemas/PaintFingerprint" },
          "geometryChanged": { "const": false }
        },
        "oneOf": [
          { "required": ["recipe"], "not": { "anyOf": [{ "required": ["color"] }, { "required": ["colorMode"] }] } },
          { "required": ["color", "colorMode"], "not": { "required": ["recipe"] } }
        ],
        "additionalProperties": false
      },
      "CategoryId": { "type": "string", "pattern": "^[a-z]+(?:-[a-z]+)*$", "maxLength": 80, "examples": ["communications", "e-commerce", "science-technology"] },
      "Classification": {
        "type": "object",
        "required": ["confidence", "method"],
        "properties": {
          "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
          "method": { "type": "string", "enum": ["manual", "name", "source-category", "collection", "fallback"] }
        }
      },
      "IconCategory": {
        "type": "object",
        "required": ["id", "label", "count", "collectionCount"],
        "properties": {
          "id": { "$ref": "#/components/schemas/CategoryId" },
          "label": { "type": "string" },
          "preview": { "$ref": "#/components/schemas/IconId" },
          "count": { "type": "integer", "minimum": 0 },
          "collectionCount": { "type": "integer", "minimum": 0 }
        }
      },
      "CategoriesResponse": {
        "type": "object",
        "required": ["schemaVersion", "reference", "encoding", "categories", "facets", "counts"],
        "properties": {
          "schemaVersion": { "const": 1 },
          "reference": {
            "type": "object",
            "required": ["name", "url"],
            "properties": {
              "name": { "const": "Hugeicons" },
              "url": { "const": "https://hugeicons.com/icons" }
            }
          },
          "encoding": { "const": "category-bytes" },
          "categories": { "type": "array", "minItems": 59, "maxItems": 59, "items": { "$ref": "#/components/schemas/IconCategory" } },
          "facets": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } },
          "counts": { "type": "object", "additionalProperties": true }
        }
      },
      "OptimizationSummary": {
        "type": "object",
        "required": ["canonicalIcons", "beforeBytes", "afterBytes", "savedBytes", "savingPercent", "statuses", "risks"],
        "properties": {
          "canonicalIcons": { "type": "integer", "minimum": 0 },
          "beforeBytes": { "type": "integer", "minimum": 0 },
          "afterBytes": { "type": "integer", "minimum": 0 },
          "savedBytes": { "type": "integer", "minimum": 0 },
          "savingPercent": { "type": "number", "minimum": 0 },
          "statuses": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } },
          "risks": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }
        }
      },
      "OptimizationResponse": {
        "type": "object",
        "required": ["schemaVersion", "optimizerVersion", "encoding", "policy", "statuses", "riskFlags", "summary", "collections"],
        "properties": {
          "schemaVersion": { "const": 1 },
          "optimizerVersion": { "type": "integer", "minimum": 1 },
          "encoding": { "const": "icon-optimization-byte-v2" },
          "policy": { "type": "object", "additionalProperties": { "type": "string" } },
          "statuses": { "type": "array", "items": { "type": "string", "enum": ["unchanged", "optimized", "preserved-risk", "fallback"] } },
          "riskFlags": { "type": "array", "items": { "type": "string" } },
          "summary": { "$ref": "#/components/schemas/OptimizationSummary" },
          "collections": { "type": "array", "items": { "type": "object", "additionalProperties": true } }
        }
      },
      "PaintPlanReport": {
        "type": "object",
        "required": ["schemaVersion", "compilerVersion", "encoding", "pipelineHash", "policy", "summary", "collections"],
        "properties": {
          "schemaVersion": { "const": 1 },
          "compilerVersion": { "type": "string" },
          "encoding": { "const": "svg-paint-plan-v1" },
          "pipelineHash": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
          "generatedAt": { "type": "string", "format": "date-time" },
          "policy": { "type": "object", "additionalProperties": true },
          "summary": { "type": "object", "additionalProperties": true },
          "collections": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["id", "icons", "planHash", "sourceHash"],
              "properties": {
                "id": { "$ref": "#/components/schemas/IconPart" },
                "icons": { "type": "integer", "minimum": 0 },
                "planHash": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
                "sourceHash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
              },
              "additionalProperties": true
            }
          }
        },
        "additionalProperties": true
      },
      "MotionReport": {
        "type": "object",
        "required": ["schemaVersion", "generatedAt", "encoding", "planner", "policy", "recipes", "summary"],
        "properties": {
          "schemaVersion": { "const": 2 },
          "generatedAt": { "type": "string", "format": "date-time" },
          "encoding": { "const": "motion-recipe-bytes-v2" },
          "planner": {
            "type": "object",
            "required": ["provider", "model", "method"],
            "properties": {
              "provider": { "type": "string" },
              "model": { "type": "string" },
              "method": { "const": "semantic-policy" }
            }
          },
          "policy": { "type": "object", "additionalProperties": { "type": "string" } },
          "recipes": { "type": "array", "items": { "$ref": "#/components/schemas/MotionRecipe" }, "uniqueItems": true },
          "summary": {
            "type": "object",
            "required": ["animated", "automaticCandidates", "generated", "native", "sourceStatic", "staticOnly", "total", "modelOverrideConcepts"],
            "properties": {
              "animated": { "type": "integer", "minimum": 0 },
              "automaticCandidates": { "type": "integer", "minimum": 0 },
              "generated": { "type": "integer", "minimum": 0 },
              "native": { "type": "integer", "minimum": 0 },
              "sourceStatic": { "type": "integer", "minimum": 0 },
              "staticOnly": { "type": "integer", "minimum": 0 },
              "total": { "type": "integer", "minimum": 0 },
              "modelOverrideConcepts": { "type": "integer", "minimum": 0 }
            }
          }
        }
      },
      "License": {
        "type": "object",
        "required": ["title"],
        "properties": {
          "title": { "type": "string" },
          "spdx": { "type": "string" },
          "url": { "type": "string", "format": "uri" }
        }
      },
      "Author": {
        "type": "object",
        "required": ["name"],
        "properties": {
          "name": { "type": "string" },
          "url": { "type": "string", "format": "uri" }
        }
      },
      "CollectionSummary": {
        "type": "object",
        "required": ["id", "name", "palette", "tags", "license", "nonCommercial"],
        "properties": {
          "id": { "$ref": "#/components/schemas/IconPart" },
          "name": { "type": "string" },
          "total": { "type": "integer", "minimum": 0 },
          "palette": { "type": "string", "enum": ["monotone", "color"] },
          "tags": { "type": "array", "items": { "type": "string" } },
          "variants": {
            "type": "array",
            "description": "该集合可供搜索 variant 参数使用的精确 UI 样式或变体标签。",
            "items": { "type": "string", "minLength": 1, "maxLength": 48 },
            "uniqueItems": true
          },
          "author": { "$ref": "#/components/schemas/Author" },
          "license": { "$ref": "#/components/schemas/License" },
          "nonCommercial": { "type": "boolean" },
          "provider": { "type": "string" },
          "sourceVersion": { "type": "string" },
          "projectUrl": { "type": "string", "format": "uri" },
          "sourcePublishedAt": { "type": "string", "format": "date-time" },
          "copyright": { "type": "string" }
        }
      },
      "CollectionListResponse": {
        "type": "object",
        "required": ["total", "collections"],
        "properties": {
          "total": { "type": "integer", "minimum": 0 },
          "collections": {
            "type": "array",
            "maxItems": 250,
            "items": { "$ref": "#/components/schemas/CollectionSummary" }
          }
        }
      },
      "SearchResult": {
        "type": "object",
        "required": ["id", "canonicalId", "collection", "palette", "motion", "motionSource", "sourceMotion", "license", "nonCommercial", "previewUrl", "primaryCategory", "secondaryCategories", "semanticCategories", "assetTypes", "styles", "grid", "classification"],
        "properties": {
          "id": { "type": "string" },
          "canonicalId": { "type": "string", "description": "Resolved canonical icon ID. For aliases this is the upstream canonical target, not the requested alias ID." },
          "collection": { "type": "string" },
          "palette": { "type": "string", "enum": ["monotone", "color"] },
          "motion": { "$ref": "#/components/schemas/MotionKind" },
          "motionSource": { "$ref": "#/components/schemas/MotionSource" },
          "sourceMotion": { "$ref": "#/components/schemas/MotionKind" },
          "primaryCategory": { "$ref": "#/components/schemas/CategoryId" },
          "secondaryCategories": { "type": "array", "items": { "$ref": "#/components/schemas/CategoryId" }, "uniqueItems": true },
          "semanticCategories": { "type": "array", "description": "包含 primary 与 secondary 平级分类。", "items": { "$ref": "#/components/schemas/CategoryId" }, "uniqueItems": true },
          "assetTypes": { "type": "array", "items": { "type": "string", "enum": ["icon", "emoji", "logo", "flag"] }, "uniqueItems": true },
          "styles": { "type": "array", "items": { "type": "string", "enum": ["regular", "outline", "filled", "duotone", "multicolor", "animated"] }, "uniqueItems": true },
          "grid": { "type": "string", "enum": ["16px", "20px", "24px", "32px", "scalable", "other"] },
          "classification": { "$ref": "#/components/schemas/Classification" },
          "license": { "$ref": "#/components/schemas/License" },
          "nonCommercial": { "type": "boolean" },
          "previewUrl": { "type": "string", "format": "uri" }
        }
      },
      "SearchResponse": {
        "type": "object",
        "required": ["query", "matchedQuery", "total", "matchedTotal", "catalogTotal", "results", "nextCursor"],
        "properties": {
          "query": { "type": "string" },
          "matchedQuery": {
            "type": "string",
            "description": "实际匹配的上游查询；必要时，自然语言短语会回退到其中的主要概念。"
          },
          "total": { "type": "integer", "minimum": 0, "maximum": 24, "description": "当前页返回的候选数量。" },
          "matchedTotal": { "type": "integer", "minimum": 0, "description": "本站目录中通过全部搜索过滤条件的匹配数量。" },
          "catalogTotal": { "type": "integer", "minimum": 0, "description": "应用本地许可、palette 和 variant 过滤前，上游与独立来源合并后的匹配数量。" },
          "results": { "type": "array", "maxItems": 24, "items": { "$ref": "#/components/schemas/SearchResult" } },
          "nextCursor": {
            "type": ["string", "null"],
            "maxLength": 256,
            "description": "用于获取下一受限页面的不透明续页令牌；没有更多候选或到达第 3 页时为 null。仅可与生成该令牌时完全相同的搜索参数配合使用。"
          }
        }
      },
      "IconResponse": {
        "type": "object",
        "required": ["id", "canonicalId", "target", "motion", "availableMotion", "motionSource", "sourceMotion", "license", "nonCommercial", "attribution", "sourceUrl", "paint", "primaryCategory", "secondaryCategories", "semanticCategories", "assetTypes", "styles", "grid", "classification"],
        "properties": {
          "id": { "type": "string" },
          "canonicalId": { "type": "string" },
          "target": { "$ref": "#/components/schemas/IconTarget" },
          "motion": { "$ref": "#/components/schemas/MotionKind" },
          "availableMotion": { "type": "array", "items": { "$ref": "#/components/schemas/MotionKind" }, "uniqueItems": true },
          "motionRecipe": { "$ref": "#/components/schemas/MotionRecipe" },
          "motionSource": { "$ref": "#/components/schemas/MotionSource" },
          "sourceMotion": { "$ref": "#/components/schemas/MotionKind" },
          "primaryCategory": { "$ref": "#/components/schemas/CategoryId" },
          "secondaryCategories": { "type": "array", "items": { "$ref": "#/components/schemas/CategoryId" }, "uniqueItems": true },
          "semanticCategories": { "type": "array", "items": { "$ref": "#/components/schemas/CategoryId" }, "uniqueItems": true },
          "assetTypes": { "type": "array", "items": { "type": "string", "enum": ["icon", "emoji", "logo", "flag"] }, "uniqueItems": true },
          "styles": { "type": "array", "items": { "type": "string", "enum": ["regular", "outline", "filled", "duotone", "multicolor", "animated"] }, "uniqueItems": true },
          "grid": { "type": "string", "enum": ["16px", "20px", "24px", "32px", "scalable", "other"] },
          "classification": { "$ref": "#/components/schemas/Classification" },
          "license": { "$ref": "#/components/schemas/License" },
          "nonCommercial": { "type": "boolean" },
          "attribution": { "type": "string" },
          "sourceUrl": { "type": "string", "format": "uri" },
          "projectUrl": { "type": "string", "format": "uri" },
          "sourceVersion": { "type": "string" },
          "sourcePublishedAt": { "type": "string", "format": "date-time" },
          "provider": { "type": "string" },
          "copyright": { "type": "string" },
          "paint": { "$ref": "#/components/schemas/PaintMetadata" },
          "content": { "type": "string" }
        }
      },
      "IconBundlePlan": {
        "type": "object",
        "required": ["count", "ids", "format", "rendering", "download", "contains"],
        "properties": {
          "count": { "type": "integer", "minimum": 1, "maximum": 24 },
          "ids": { "type": "array", "items": { "$ref": "#/components/schemas/IconId" } },
          "format": { "const": "svg" },
          "includeNonCommercial": { "type": "boolean", "default": false },
          "rendering": { "$ref": "#/components/schemas/PaintRenderingRequest" },
          "download": {
            "type": "object",
            "required": ["url", "filename", "contentType"],
            "properties": {
              "url": { "type": "string", "format": "uri" },
              "filename": { "const": "2d-digital-icons-svg.zip" },
              "contentType": { "const": "application/zip" }
            }
          },
          "contains": { "type": "array", "items": { "type": "string" } },
          "note": { "type": "string" }
        }
      },
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message"],
            "properties": { "code": { "type": "string" }, "message": { "type": "string" } }
          }
        }
      }
    },
    "parameters": {
      "MotionDelivery": {
        "name": "motion",
        "in": "query",
        "description": "选择交付版本：source 保持上游原貌；static 移除原生或生成动画；animated 保留原生动画，或将模型选择的动作配方确定性编译为安全 SMIL。非 source 只适用于 SVG/CSS 内容，不适用于外部 Iconify ID 代码片段。",
        "schema": { "$ref": "#/components/schemas/MotionDelivery" }
      },
      "LegacyColor": {
        "name": "color",
        "in": "query",
        "description": "旧颜色适配器。只能在 recipe 缺席时使用；color 与 colorMode 均未提供时才默认为 currentColor/auto。",
        "schema": { "$ref": "#/components/schemas/PaintValue" }
      },
      "LegacyColorMode": {
        "name": "colorMode",
        "in": "query",
        "description": "旧颜色适配器模式。不能与 recipe 同时提供。",
        "schema": { "$ref": "#/components/schemas/ColorMode" }
      },
      "PaintRecipeQuery": {
        "name": "recipe",
        "in": "query",
        "description": "URL 编码的 PaintRecipe JSON。必须先读取图标的 paint capabilities、slots 与 fingerprint；不能与 color 或 colorMode 同时提供。",
        "schema": { "type": "string", "minLength": 1, "maxLength": 16384 },
        "examples": {
          "palette": { "value": "{\"mode\":\"palette\",\"overrides\":{\"p0\":\"#01c853\",\"p1\":\"#ffffff\"}}" },
          "singleColor": { "value": "{\"mode\":\"single-color\",\"color\":\"currentColor\"}" }
        }
      },
      "ExpectedPaintFingerprint": {
        "name": "expectedFingerprint",
        "in": "query",
        "description": "上次读取的 PaintPlan fingerprint。几何或 plan 已改变时请求失败，避免把旧 slot 选择应用到新图标；批量端点仅在恰好选择一个图标时接受。",
        "schema": { "$ref": "#/components/schemas/PaintFingerprint" }
      }
    },
    "responses": {
      "Error": {
        "description": "结构化错误响应",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    }
  }
}