openapi: 3.1.0
info:
  title: Bright Data Account Management API
  description: |
    Programmatic management of Bright Data zones (proxy pools and product entitlements), IP
    allocations, access control (whitelists, blacklists, domain permissions), passwords, and
    billing/bandwidth reporting. Authentication uses a Bearer API token issued from the control panel.
  version: '1.0'
  contact:
    name: Bright Data
    url: https://docs.brightdata.com
servers:
  - url: https://api.brightdata.com
    description: Production
security:
  - BearerAuth: []
tags:
  - name: Zones
  - name: IPs
  - name: Access
  - name: Billing
paths:
  /zone:
    post:
      summary: Add Zone
      operationId: addZone
      tags: [Zones]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [zone, plan]
              properties:
                zone: { type: string }
                plan:
                  type: object
                  properties:
                    type: { type: string, enum: [residential, isp, datacenter, mobile, unblocker, serp, scraping_browser] }
                    country: { type: string }
                    ips: { type: integer }
      responses:
        "200":
          description: Zone created.
          content:
            application/json: { schema: { $ref: '#/components/schemas/Zone' } }
    get:
      summary: Get Zone
      operationId: getZone
      tags: [Zones]
      parameters:
        - { name: zone, in: query, required: true, schema: { type: string } }
      responses:
        "200":
          description: Zone detail.
          content:
            application/json: { schema: { $ref: '#/components/schemas/Zone' } }
    delete:
      summary: Delete Zone
      operationId: deleteZone
      tags: [Zones]
      parameters:
        - { name: zone, in: query, required: true, schema: { type: string } }
      responses:
        "200":
          description: Zone deleted.
          content:
            application/json: { schema: { type: object } }
  /zone/change_disable:
    post:
      summary: Enable or Disable Zone
      operationId: toggleZone
      tags: [Zones]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [zone, disable]
              properties:
                zone: { type: string }
                disable: { type: boolean }
      responses:
        "200":
          description: Updated.
          content:
            application/json: { schema: { type: object } }
  /zone/ips:
    get:
      summary: List Zone IPs
      operationId: listZoneIps
      tags: [IPs]
      parameters:
        - { name: zone, in: query, required: true, schema: { type: string } }
      responses:
        "200":
          description: Allocated IPs.
          content:
            application/json:
              schema:
                type: array
                items: { type: string }
    post:
      summary: Add IPs to Zone
      operationId: addZoneIps
      tags: [IPs]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [zone, ips]
              properties:
                zone: { type: string }
                ips: { type: integer }
                country: { type: string }
      responses:
        "200":
          description: Allocation submitted.
          content:
            application/json: { schema: { type: object } }
    delete:
      summary: Remove IPs from Zone
      operationId: removeZoneIps
      tags: [IPs]
      parameters:
        - { name: zone, in: query, required: true, schema: { type: string } }
        - { name: ips, in: query, schema: { type: integer } }
      responses:
        "200":
          description: Removed.
          content:
            application/json: { schema: { type: object } }
  /zone/ips/refresh:
    post:
      summary: Refresh Zone IPs
      operationId: refreshZoneIps
      tags: [IPs]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [zone]
              properties:
                zone: { type: string }
                ips: { type: integer }
      responses:
        "200":
          description: Refresh queued.
          content:
            application/json: { schema: { type: object } }
  /zone/whitelist:
    post:
      summary: Add IPs to Zone Whitelist
      operationId: addWhitelist
      tags: [Access]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [zone, ip]
              properties:
                zone: { type: string }
                ip: { type: string }
      responses:
        "200":
          description: Whitelist updated.
          content:
            application/json: { schema: { type: object } }
  /zone/blacklist:
    post:
      summary: Add to Zone Blacklist
      operationId: addBlacklist
      tags: [Access]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [zone, ip]
              properties:
                zone: { type: string }
                ip: { type: string }
      responses:
        "200":
          description: Blacklist updated.
          content:
            application/json: { schema: { type: object } }
  /zone/domain_perm:
    get:
      summary: Get Zone Domain Permissions
      operationId: getDomainPermissions
      tags: [Access]
      parameters:
        - { name: zone, in: query, required: true, schema: { type: string } }
      responses:
        "200":
          description: Domain permission entries.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /customer/balance:
    get:
      summary: Get Customer Balance
      operationId: getCustomerBalance
      tags: [Billing]
      responses:
        "200":
          description: Account balance.
          content:
            application/json:
              schema:
                type: object
                properties:
                  balance: { type: number }
                  currency: { type: string }
                  pending: { type: number }
  /zone/bw:
    get:
      summary: Get Zone Bandwidth Usage
      operationId: getZoneBandwidth
      tags: [Billing]
      parameters:
        - { name: zone, in: query, schema: { type: string } }
        - { name: from, in: query, schema: { type: string, format: date } }
        - { name: to, in: query, schema: { type: string, format: date } }
      responses:
        "200":
          description: Bandwidth usage.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
  schemas:
    Zone:
      type: object
      properties:
        zone: { type: string }
        type: { type: string }
        password: { type: string }
        ips: { type: integer }
        country: { type: string }
        plan: { type: object, additionalProperties: true }
        disabled: { type: boolean }