netbird/shared/management/http/apiv1alpha1/peer/peers.yaml

get:
  summary: List all Peers
  description: Returns a list of all peers
  tags: [ Peers ]
  parameters:
    - name: page
      in: query
      description: Page number
      required: false
      schema:
        type: integer
        minimum: 1
        default: 1
    - name: page_size
      in: query
      description: Number of peers per page
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 250
        default: 100
    - name: user_id
      in: query
      description: filter peers by their user_id
      required: false
      schema:
        type: string
    - name: group_ids
      in: query
      description: filter peers by group_ids
      required: false
      schema:
        type: array
        items:
          type: string
    - name: peer_ids
      in: query
      description: filter peers by their ids
      required: false
      schema:
        type: array
        minItems: 1
        maxItems: 50
        items:
          type: string
    - name: connected
      in: query
      description: Filter by peer connected status
      required: false
      schema:
        type: boolean
    - name: approval_required
      in: query
      description: Filter by approval_required field
      required: false
      schema:
        type: boolean
    - name: os
      in: query
      description: Peer os
      required: false
      schema:
        type: array
        items:
          type: string
          enum:
           - linux
           - windows
           - darwin
           - android
           - ios
           - js
    - name: ip
      in: query
      description: filter peers by ip
      required: false
      schema:
        type: string
    - name: mac
      in: query
      description: filter peers by mac address
      required: false
      schema:
        type: string
    - name: name
      in: query
      description: filter peers by hostname
      required: false
      schema:
        type: string
    - name: hostname
      in: query
      description: filter peers by hostname
      required: false
      schema:
        type: string
    - name: kind
      in: query
      description: filter peers by host kind
      required: false
      schema:
        type: string
        enum:
          - server
          - user_device
    - name: sort_by
      in: query
      description: sorting of peers
      required: false
      example: sort_by=name,asc&sort_by=last_seen,desc&sort_by=version
      schema:
        type: array
        items:
          type: string
          enum:
           - name
           - last_seen
           - version
           - asc
           - desc
  security:
    - BearerAuth: [ ]
    - TokenAuth: [ ]
  responses:
    '200':
      description: A JSON Array of Peers
      content:
        application/json:
          schema:
            $ref: './components.yaml#/components/schemas/PeerBatch'
    '400':
      "$ref": "../openapi.yaml#/components/responses/bad_request"
    '401':
      "$ref": "../openapi.yaml#/components/responses/requires_authentication"
    '403':
      "$ref": "../openapi.yaml#/components/responses/forbidden"
    '422':
      "$ref": "../openapi.yaml#/components/responses/unprocessable"
    '500':
      "$ref": "../openapi.yaml#/components/responses/internal_error"