{
  "openapi": "3.1.0",
  "info": {
    "title": "Brightdata API",
    "description": "API for interaction with datasets marketplace",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.brightdata.com"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/datasets/filter": {
      "post": {
        "description": "Create a dataset snapshot based on a provided filter",
        "parameters": [
          {
            "name": "dataset_id",
            "required": true,
            "in": "query",
            "description": "ID of the dataset to filter (required in multipart/form-data mode)",
            "schema": {
              "type": "string",
              "example": "gd_l1viktl72bvl7bjuj0"
            }
          },
          {
            "name": "records_limit",
            "description": "Limit the number of records to be included in the snapshot",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "example": 1000
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/FilterDatasetBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Job of creating the snapshot successfully started",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "snapshot_id": {
                      "type": "string",
                      "description": "ID of the snapshot"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationErrorBody"
                },
                "example": {
                  "validation_errors": [
                    "\"filter.filters[0].invalid_prop\" is not allowed",
                    "\"records_limit\" must be a positive number"
                  ]
                }
              }
            }
          },
          "402": {
            "description": "Not enough funds to create the snapshot",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "example": {
                  "error": "Your current balance is insufficient to process this data collection request. Please add funds to your account or adjust your request to continue. ($1 is missing)"
                }
              }
            }
          },
          "422": {
            "description": "Provided filter did not match any records",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "example": {
                  "error": "Provided filter did not match any records"
                }
              }
            }
          },
          "429": {
            "description": "Too many parallel jobs",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "example": {
                  "error": "Maximum limit of 100 jobs per dataset has been exceeded"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "DatasetFilter": {
        "anyOf": [
          {
            "$ref": "#/components/schemas/DatasetFilterItem",
            "title": "Single field filter"
          },
          {
            "$ref": "#/components/schemas/DatasetFilterGroup",
            "title": "Filters group"
          },
          {
            "$ref": "#/components/schemas/DatasetFilterItemNoVal",
            "title": "Single field filter w/out value"
          }
        ]
      },
      "DatasetFilterGroup": {
        "type": "object",
        "required": [
          "operator",
          "filters"
        ],
        "additionalProperties": false,
        "properties": {
          "operator": {
            "type": "string",
            "enum": [
              "and",
              "or"
            ]
          },
          "combine_nested_fields": {
            "type": "boolean",
            "description": "For arrays of objects: if true, all filters must match within a single object"
          },
          "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": "Field name to filter by"
          },
          "operator": {
            "type": "string",
            "enum": [
              "=",
              "!=",
              ">",
              "<",
              ">=",
              "<=",
              "in",
              "not_in",
              "includes",
              "not_includes",
              "array_includes",
              "not_array_includes"
            ]
          },
          "value": {
            "description": "Value to filter by",
            "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": "Field name to filter by"
          },
          "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": "Use your Bright Data API Key as a Bearer token in the Authorization header.\n\n**How to authenticate:**\n1. Obtain your API Key from the Bright Data account settings at https://brightdata.com/cp/setting/users\n2. Include the API Key in the Authorization header of your requests\n3. Format: `Authorization: Bearer YOUR_API_KEY`\n\n**Example:**\n```\nAuthorization: Bearer b5648e1096c6442f60a6c4bbbe73f8d2234d3d8324554bd6a7ec8f3f251f07df\n```\n\nLearn how to get your Bright Data API key: https://docs.brightdata.com/api-reference/authentication",
        "bearerFormat": "API Key"
      }
    }
  }
}