{
  "openapi": "3.1.0",
  "info": {
    "title": "Brightdata API",
    "description": "用于与数据集市场交互的 API",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.brightdata.com"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/datasets/filter": {
      "post": {
        "description": "根据提供的筛选条件创建数据集快照",
        "parameters": [
          {
            "name": "dataset_id",
            "required": true,
            "in": "query",
            "description": "要筛选的数据集 ID（在 multipart/form-data 模式下为必填）",
            "schema": {
              "type": "string",
              "example": "gd_l1viktl72bvl7bjuj0"
            }
          },
          {
            "name": "records_limit",
            "description": "限制包含在快照中的记录数量",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "example": 1000
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/FilterDatasetBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "创建快照的任务已成功启动",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "snapshot_id": {
                      "type": "string",
                      "description": "快照 ID"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "错误请求",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationErrorBody"
                },
                "example": {
                  "validation_errors": [
                    "\"filter.filters[0].invalid_prop\" 不允许",
                    "\"records_limit\" 必须为正数"
                  ]
                }
              }
            }
          },
          "402": {
            "description": "余额不足，无法创建快照",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "example": {
                  "error": "您当前的余额不足以处理此数据收集请求。请向您的账户充值或调整请求以继续。 ($1 缺失)"
                }
              }
            }
          },
          "422": {
            "description": "提供的筛选条件未匹配任何记录",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "example": {
                  "error": "提供的筛选条件未匹配任何记录"
                }
              }
            }
          },
          "429": {
            "description": "并行任务过多",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "example": {
                  "error": "每个数据集的最大任务限制 100 已超出"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "DatasetFilter": {
        "anyOf": [
          {
            "$ref": "#/components/schemas/DatasetFilterItem",
            "title": "单字段筛选器"
          },
          {
            "$ref": "#/components/schemas/DatasetFilterGroup",
            "title": "筛选器组"
          },
          {
            "$ref": "#/components/schemas/DatasetFilterItemNoVal",
            "title": "无值单字段筛选器"
          }
        ]
      },
      "DatasetFilterGroup": {
        "type": "object",
        "required": ["operator", "filters"],
        "additionalProperties": false,
        "properties": {
          "operator": {
            "type": "string",
            "enum": ["and", "or"]
          },
          "combine_nested_fields": {
            "type": "boolean",
            "description": "对于对象数组：如果为 true，则所有筛选器必须在同一个对象中匹配"
          },
          "filters": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DatasetFilter"
            }
          }
        },
        "example": {
          "operator": "and",
          "filters": [
            {
              "name": "name",
              "operator": "=",
              "value": "John"
            },
            {
              "name": "age",
              "operator": ">",
              "value": "30"
            }
          ]
        }
      },
      "DatasetFilterItem": {
        "type": "object",
        "required": ["name", "operator", "value"],
        "additionalProperties": false,
        "properties": {
          "name": {
            "type": "string",
            "description": "用于筛选的字段名称"
          },
          "operator": {
            "type": "string",
            "enum": [
              "=",
              "!=",
              ">",
              "<",
              ">=",
              "<=",
              "in",
              "not_in",
              "includes",
              "not_includes",
              "array_includes",
              "not_array_includes"
            ]
          },
          "value": {
            "description": "筛选值",
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              },
              {
                "type": "object"
              },
              {
                "type": "array",
                "items": {
                  "oneOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "number"
                    },
                    {
                      "type": "boolean"
                    }
                  ]
                }
              }
            ]
          }
        },
        "example": {
          "name": "name",
          "operator": "=",
          "value": "John"
        }
      },
      "DatasetFilterItemNoVal": {
        "type": "object",
        "required": ["name", "operator"],
        "additionalProperties": false,
        "properties": {
          "name": {
            "type": "string",
            "description": "用于筛选的字段名称"
          },
          "operator": {
            "type": "string",
            "enum": ["is_null", "is_not_null"]
          }
        },
        "example": {
          "name": "reviews_count",
          "operator": "is_not_null"
        }
      },
      "ErrorBody": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        }
      },
      "FilterDatasetBody": {
        "type": "object",
        "required": ["filter"],
        "properties": {
          "filter": {
            "$ref": "#/components/schemas/DatasetFilter"
          }
        }
      },
      "ValidationErrorBody": {
        "type": "object",
        "properties": {
          "validation_errors": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    },
    "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"
      }
    }
  }
}