openapi: 3.1.0
info:
  title: Bright Data Proxy Manager API
  description: |
    Local self-hosted REST control plane for the Bright Data Proxy Manager. The Proxy Manager runs
    on `localhost:22999` by default and exposes endpoints to create and configure proxy ports, ban
    misbehaving IPs, refresh pools, read zone configuration, and manage SSL/logging/statistics.
  version: '1.0'
  contact:
    name: Bright Data
    url: https://docs.brightdata.com/proxy-networks/proxy-manager/api
servers:
  - url: http://localhost:22999
    description: Local Proxy Manager
tags:
  - name: Proxies
  - name: Zones
  - name: Tokens
paths:
  /api/proxies:
    get:
      summary: List Proxy Ports
      operationId: listProxies
      tags: [Proxies]
      responses:
        "200":
          description: Configured ports.
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/ProxyPort' }
    post:
      summary: Create Proxy Port
      operationId: createProxy
      tags: [Proxies]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ProxyPort' }
      responses:
        "200":
          description: Port created.
          content:
            application/json: { schema: { $ref: '#/components/schemas/ProxyPort' } }
  /api/proxies/{port}:
    parameters:
      - { name: port, in: path, required: true, schema: { type: integer } }
    get:
      summary: Get Proxy Port
      operationId: getProxy
      tags: [Proxies]
      responses:
        "200":
          description: Port detail.
          content:
            application/json: { schema: { $ref: '#/components/schemas/ProxyPort' } }
    put:
      summary: Update Proxy Port
      operationId: updateProxy
      tags: [Proxies]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ProxyPort' }
      responses:
        "200":
          description: Updated.
          content:
            application/json: { schema: { $ref: '#/components/schemas/ProxyPort' } }
    delete:
      summary: Delete Proxy Port
      operationId: deleteProxy
      tags: [Proxies]
      responses:
        "200":
          description: Deleted.
          content:
            application/json: { schema: { type: object } }
  /api/proxies/{port}/banip:
    parameters:
      - { name: port, in: path, required: true, schema: { type: integer } }
    post:
      summary: Ban an IP for Port
      operationId: banIp
      tags: [Proxies]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [ip]
              properties:
                ip: { type: string }
                ttl_ms: { type: integer }
      responses:
        "200":
          description: Banned.
          content:
            application/json: { schema: { type: object } }
  /api/refresh_ips:
    post:
      summary: Refresh IPs
      operationId: refreshIps
      tags: [Proxies]
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                zone: { type: string }
                ips: { type: integer }
      responses:
        "200":
          description: Refresh started.
          content:
            application/json: { schema: { type: object } }
  /api/zones:
    get:
      summary: List Zones
      operationId: listZones
      tags: [Zones]
      responses:
        "200":
          description: Zones configured in the Proxy Manager.
          content:
            application/json:
              schema:
                type: array
                items: { type: object, additionalProperties: true }
  /api/gen_token:
    get:
      summary: Generate Proxy Manager Token
      operationId: genToken
      tags: [Tokens]
      responses:
        "200":
          description: New token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  token: { type: string }
components:
  schemas:
    ProxyPort:
      type: object
      properties:
        port: { type: integer }
        zone: { type: string }
        country: { type: string }
        city: { type: string }
        session: { type: string, enum: [rand, sticky, round-robin] }
        sticky_ip: { type: boolean }
        rotate_session: { type: integer }
        max_requests: { type: integer }
        allow_proxy_auth: { type: boolean }
        log: { type: string, enum: [none, error, warn, info, debug] }