{
  "openapi": "3.1.0",
  "info": {
    "title": "Bright Data 深度查询 API",
    "description": "Bright Data 深度查询 API 允许您预览、优化并执行研究查询。\n支持数据丰富、取消操作以及多种格式的结果导出。",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.brightdata.com/datasets/deep_lookup/v1"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/preview": {
      "post": {
        "summary": "创建预览",
        "description": "生成预览以验证您的查询。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": ["query"],
                  "properties": {
                    "query": {
                      "type": "string",
                      "examples": [
                        "查找所有 2020 年后成立且员工超过 50 人的 AI 初创公司"
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "预览创建成功",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PreviewResponse" }
              }
            }
          }
        }
      }
    },
    "/preview/{id}": {
      "get": {
        "summary": "获取预览数据",
        "description": "检索预览结果及元数据。",
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "examples": ["dld_meu4lhla1lj08i6p30"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "预览详情",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/GetPreviewResponse" }
              }
            }
          }
        }
      }
    },
    "/enhance_query": {
      "post": {
        "summary": "优化查询",
        "description": "根据额外要求优化您的研究查询。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": ["query"],
                  "properties": {
                    "query": {
                      "type": "string",
                      "examples": ["查找所有 AI 初创公司"]
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "查询优化成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EnhanceQueryResponse"
                }
              }
            }
          }
        }
      }
    },
    "/trigger": {
      "post": {
        "summary": "触发完整请求",
        "description": "根据预览或详细规格执行完整研究。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/TriggerFromPreview"
                  },
                  {
                    "$ref": "#/components/schemas/DirectTriggerWithSpecifications"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "研究请求已成功触发",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TriggerResponse"
                }
              }
            }
          }
        }
      }
    },
    "/request/{id}/status": {
      "get": {
        "summary": "获取请求状态",
        "description": "检查研究请求的当前状态。",
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "examples": ["ai_meu3z0171o8k9jc4dh"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "请求状态",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RequestStatusResponse"
                }
              }
            }
          }
        }
      }
    },
    "/request/{id}": {
      "get": {
        "summary": "获取请求数据",
        "description": "检索研究的完整结果。",
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "examples": ["ai_meu3z0171o8k9jc4dh"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "请求数据",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/RequestDataResponse" }
              }
            }
          }
        }
      }
    },
    "/request/{id}/enrich": {
      "post": {
        "summary": "丰富列",
        "description": "为现有结果添加额外数据列。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "column_name": {
                      "type": "string",
                      "examples": ["cto_name"]
                    },
                    "query": {
                      "type": "string",
                      "examples": ["CTO 或工程负责人姓名"]
                    }
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "examples": ["ai_meu3z0171o8k9jc4dh"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "已触发数据丰富",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/EnrichResponse" }
              }
            }
          }
        }
      }
    },
    "/request/{id}/cancel": {
      "post": {
        "summary": "取消请求",
        "description": "取消正在进行中的研究请求。",
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "examples": ["ai_meu3z0171o8k9jc4dh"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "请求已取消",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CancelResponse" }
              }
            }
          }
        }
      }
    },
    "/request/{id}/download": {
      "get": {
        "summary": "下载结果",
        "description": "以 JSON、CSV 或 Excel 导出结果。",
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "examples": ["ai_meu3z0171o8k9jc4dh"]
            }
          },
          {
            "in": "query",
            "name": "format",
            "description": "**注意：** Excel 格式当前不可用。",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["json", "csv"],
              "default": "json",
              "examples": ["csv"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "文件下载",
            "content": {
              "application/json": {}
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "PreviewResponse": {
        "type": "object",
        "properties": {
          "preview_id": {
            "type": "string",
            "examples": ["dld_meu4lhla1lj08i6p30"]
          },
          "columns": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "examples": [
              [
                {
                  "company_name": "Anthropic",
                  "website": "anthropic.com",
                  "founded_year": 2021,
                  "employee_count": 160
                }
              ]
            ]
          }
        }
      },
      "GetPreviewResponse": {
        "type": "object",
        "properties": {
          "preview_id": {
            "type": "string",
            "examples": ["dld_meu4lhla1lj08i6p30"]
          },
          "query": {
            "type": "string",
            "examples": ["查找所有 2020 年后成立且员工超过 50 人的 AI 初创公司"]
          },
          "status": {
            "type": "string",
            "description": "- `queued` - 请求排队等待处理\n- `running` - 正在生成预览\n- `completed` - 结果已准备好\n- `failed` - 出现错误",
            "enum": ["pending", "processing", "completed", "failed"],
            "examples": ["completed"]
          },
          "sample_data": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "examples": [
              {
                "company_name": "Anthropic",
                "website": "anthropic.com",
                "founded_year": 2021,
                "employee_count": 160
              }
            ]
          },
          "columns": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "examples": [
              [
                {
                  "company_name": "Anthropic",
                  "website": "anthropic.com",
                  "founded_year": 2021,
                  "employee_count": 160
                }
              ]
            ]
          },
          "result_limit": {
            "type": "integer",
            "examples": [10]
          }
        }
      },
      "EnhanceQueryResponse": {
        "type": "object",
        "properties": {
          "enhanced_query": {
            "type": "string",
            "examples": [
              "查找在美国的所有 AI 初创公司，这些公司已获得 A 轮及以上融资，总部位于主要科技中心"
            ]
          }
        }
      },
      "TriggerFromPreview": {
        "type": "array",
        "items": {
          "type": "object",
          "required": ["preview_id"],
          "properties": {
            "preview_id": {
              "type": "string",
              "description": "要触发的预览请求 ID",
              "examples": ["dld_meu4lhla1lj08i6p30"]
            },
            "result_limit": {
              "type": "integer",
              "description": "限制返回结果的数量",
              "examples": [100]
            }
          }
        }
      },
      "DirectTriggerWithSpecifications": {
        "type": "array",
        "items": {
          "type": "object",
          "required": ["query", "spec"],
          "properties": {
            "query": {
              "type": "string",
              "description": "研究的高级查询",
              "examples": ["查找以色列的所有 AI 初创公司"]
            },
            "spec": {
              "type": "object",
              "required": ["name", "query", "title", "columns"],
              "properties": {
                "name": {
                  "type": "string",
                  "examples": ["companies"]
                },
                "query": {
                  "type": "string",
                  "examples": ["查找在以色列开发 AI 产品的所有初创公司"]
                },
                "title": {
                  "type": "string",
                  "examples": ["以色列的 AI 初创公司"]
                },
                "columns": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": ["name", "description", "type"],
                    "properties": {
                      "name": {
                        "type": "string"
                      },
                      "description": {
                        "type": "string"
                      },
                      "type": {
                        "type": "string",
                        "enum": ["enrichment", "constraint"]
                      }
                    }
                  },
                  "examples": [
                    {
                      "name": "founding_date",
                      "description": "公司的成立日期",
                      "type": "enrichment"
                    },
                    {
                      "name": "is_startup_check",
                      "description": "公司必须是初创公司（早期公司，通常为私人持有，最近成立）",
                      "type": "constraint"
                    },
                    {
                      "name": "employee_count",
                      "description": "员工数量",
                      "type": "enrichment"
                    }
                  ]
                }
              }
            },
            "result_limit": {
              "type": "integer",
              "description": "限制返回结果的数量",
              "examples": [50]
            }
          }
        }
      },
      "TriggerResponse": {
        "type": "object",
        "properties": {
          "request_id": {
            "type": "string",
            "examples": ["ai_meu3z0171o8k9jc4dh"]
          },
          "status": {
            "type": "string",
            "description": "- `queued` - 请求排队等待处理\n- `running` - 研究进行中",
            "enum": ["queued", "running"],
            "examples": ["queued"]
          },
          "max_cost": {
            "type": "string",
            "example": "$50.00"
          }
        }
      },
      "RequestStatusResponse": {
        "type": "object",
        "properties": {
          "request_id": {
            "type": "string",
            "examples": ["ai_meu3z0171o8k9jc4dh"]
          },
          "status": {
            "type": "string",
            "description": "- `queued` - 请求排队等待处理\n- `running` - 研究进行中\n- `completed` - 结果已准备好\n- `failed` - 出现错误\n- `cancelled` - 请求已取消",
            "enum": ["queued", "running", "completed", "failed", "cancelled"],
            "examples": ["running"]
          },
          "progress": {
            "type": "integer",
            "description": "进度百分比 (0-100)",
            "examples": [65]
          },
          "pages_read": {
            "type": "integer",
            "examples": [342]
          },
          "pages_considered": {
            "type": "integer",
            "examples": [1250]
          },
          "matched_records": {
            "type": "integer",
            "examples": [31]
          },
          "is_trial": {
            "type": "boolean",
            "examples": [false]
          },
          "result_limit": {
            "type": "integer",
            "examples": [50]
          }
        }
      },
      "RequestDataResponse": {
        "type": "object",
        "properties": {
          "request_id": {
            "type": "string",
            "examples": ["ai_meu3z0171o8k9jc4dh"]
          },
          "query": {
            "type": "string",
            "examples": ["查找以色列的所有 AI 初创公司"]
          },
          "status": {
            "type": "string",
            "examples": ["completed"]
          },
          "title": {
            "type": "string",
            "examples": ["以色列的 AI 初创公司"]
          },
          "step": {
            "type": "string",
            "description": "- `identifying` - 理解并分析查询\n- `generating_schema` - 创建数据结构\n- `generating` - 收集并处理数据\n- `done` - 研究完成",
            "examples": ["done"]
          },
          "matched_records": {
            "type": "integer",
            "examples": [73]
          },
          "skipped_records": {
            "type": "integer",
            "description": "**注意:** `skipped_records` 表示未匹配筛选条件的实体",
            "examples": [27]
          },
          "pages_read": {
            "type": "integer",
            "examples": [892]
          },
          "pages_considered": {
            "type": "integer",
            "examples": [3421]
          },
          "total_cost": {
            "type": "string",
            "description": "**注意:** `total_cost` 显示当前费用（对于进行中的请求，此值反映迄今收集的记录）",
            "examples": ["$73.00"]
          },
          "columns": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["name", "description", "type"],
              "properties": {
                "name": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "type": {
                  "type": "string",
                  "enum": ["enrichment", "constraint"]
                }
              }
            },
            "examples": [
              [
                {
                  "name": "company_name",
                  "description": "公司名称",
                  "type": "enrichment"
                }
              ]
            ]
          },
          "data": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "examples": [
              [
                {
                  "company_name": "Run:ai",
                  "website": "run.ai",
                  "founding_date": "2018",
                  "employee_count": 120
                }
              ]
            ]
          }
        }
      },
      "EnrichResponse": {
        "type": "object",
        "properties": {
          "column_name": {
            "type": "string",
            "examples": ["cto_name"]
          },
          "status": {
            "type": "string",
            "description": "- `processing` - 正在丰富数据\n- `completed` - 数据丰富完成",
            "enum": ["processing", "completed"],
            "examples": ["processing"]
          },
          "max_additional_cost": {
            "type": "string",
            "description": "**注意:** `max_additional_cost` 显示可能的最高费用，最终费用仅基于匹配的记录计算",
            "examples": ["$3.65"]
          }
        }
      },
      "CancelResponse": {
        "type": "object",
        "properties": {
          "request_id": {
            "type": "string",
            "examples": ["ai_meu3z0171o8k9jc4dh"]
          },
          "status": {
            "type": "string",
            "examples": ["cancelled"]
          },
          "records_processed": {
            "type": "integer",
            "examples": [45]
          },
          "charge": {
            "type": "string",
            "examples": ["$45.00"]
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "在 Authorization 头中使用您的 Bright Data API Key 作为 Bearer token。\n\n**认证方法:**\n1. 从 Bright Data 账户设置获取您的 API Key: https://brightdata.com/cp/setting/users\n2. 在请求的 Authorization 头中包含 API Key\n3. 格式: `Authorization: Bearer YOUR_API_KEY`\n\n**示例:**\n```\nAuthorization: Bearer b5648e1096c6442f60a6c4bbbe73f8d2234d3d8324554bd6a7ec8f3f251f07df\n```\n\n了解如何获取 Bright Data API Key: https://docs.brightdata.com/cn/api-reference/authentication#如何生成新的-api-key？",
        "bearerFormat": "API Key"
      }
    }
  }
}