Mist Sites Clients - Wired API

openapi: 3.2.0
info:
  contact:
    email: tmunzer@juniper.net
    name: Thomas Munzer
  description: '> Version: **2606.1.1**

    >

    > Date: **July 10, 2026**


    NOTE:

    Some important API changes will be introduced.'
  license:
    name: MIT
    url: https://raw.githubusercontent.com/tmunzer/Mist-OAS3.0/main/LICENSE
  title: Mist Sites Clients - Wired API
  version: 2606.1.1
  x-logo:
    altText: Juniper-MistAI
    backgroundColor: '#FFFFFF'
    url: https://www.mist.com/wp-content/uploads/logo.png
servers:
- description: Mist Global 01
  url: https://api.mist.com
- description: Mist Global 02
  url: https://api.gc1.mist.com
- description: Mist Global 03
  url: https://api.ac2.mist.com
- description: Mist Global 04
  url: https://api.gc2.mist.com
- description: Mist Global 05
  url: https://api.gc4.mist.com
- description: Mist EMEA 01
  url: https://api.eu.mist.com
- description: Mist EMEA 02
  url: https://api.gc3.mist.com
- description: Mist EMEA 03
  url: https://api.ac6.mist.com
- description: Mist EMEA 04
  url: https://api.gc6.mist.com
- description: Mist APAC 01
  url: https://api.ac5.mist.com
- description: Mist APAC 02
  url: https://api.gc5.mist.com
- description: Mist APAC 03
  url: https://api.gc7.mist.com
security:
- apiToken: []
- csrfToken: []
tags:
- description: Wired Clients are Wired devices connected to a Juniper switch monitored or managed by Mist.
  name: Sites Clients - Wired
paths:
  /api/v1/sites/{site_id}/wired_clients/count:
    parameters:
    - $ref: '#/components/parameters/site_id'
    get:
      description: Count wired clients for a site, optionally grouped by the `distinct` field and filtered by MAC address, switch port, VLAN, and time range. Use Count Org Wired Clients to count wired clients across the organization.
      operationId: countSiteWiredClients
      parameters:
      - description: 'Field used to group this count response. enum: `mac`, `port_id`, `vlan`'
        in: query
        name: distinct
        schema:
          $ref: '#/components/schemas/site_wired_clients_count_distinct'
      - description: Filter results by MAC address
        in: query
        name: mac
        schema:
          examples:
          - 0123456789ab
          type: string
      - description: Filter results by device MAC address
        in: query
        name: device_mac
        schema:
          examples:
          - 0123456789ab
          type: string
      - description: Filter results by port identifier
        in: query
        name: port_id
        schema:
          examples:
          - ge-1/1/1
          type: string
      - description: Filter results by VLAN ID
        in: query
        name: vlan
        schema:
          examples:
          - '10'
          type: string
      - $ref: '#/components/parameters/start'
      - $ref: '#/components/parameters/end'
      - $ref: '#/components/parameters/duration'
      - $ref: '#/components/parameters/limit'
      responses:
        '200':
          $ref: '#/components/responses/Count'
        '400':
          $ref: '#/components/responses/HTTP400'
        '401':
          $ref: '#/components/responses/HTTP401'
        '403':
          $ref: '#/components/responses/HTTP403'
        '404':
          $ref: '#/components/responses/HTTP404'
        '429':
          $ref: '#/components/responses/HTTP429'
      summary: countSiteWiredClients
      tags:
      - Sites Clients - Wired
  /api/v1/sites/{site_id}/wired_clients/search:
    parameters:
    - $ref: '#/components/parameters/site_id'
    get:
      description: Search wired clients for a site with filters for device MAC address, client MAC address, IP address, switch port, VLAN, manufacturer, DHCP attributes, NAC rule, and time range. Use Search Org Wired Clients to search wired clients across the organization.
      operationId: searchSiteWiredClients
      parameters:
      - description: Filter results by device MAC address
        in: query
        name: device_mac
        schema:
          examples:
          - 0123456789ab
          type: string
      - description: Filter results by MAC address
        in: query
        name: mac
        schema:
          examples:
          - 0123456789ab
          type: string
      - description: Filter results by IP address
        in: query
        name: ip
        schema:
          examples:
          - 10.3.5.12
          type: string
      - description: Filter results by port identifier
        in: query
        name: port_id
        schema:
          examples:
          - ge-1/1/1
          type: string
      - description: 'Filter results by client learning source. enum: `lldp`, `mac`'
        in: query
        name: source
        schema:
          $ref: '#/components/schemas/client_info_source'
      - description: Filter results by VLAN ID
        in: query
        name: vlan
        schema:
          examples:
          - '10'
          type: string
      - description: Filter results by manufacturer
        in: query
        name: manufacture
        schema:
          examples:
          - Juniper-Mist
          type: string
      - description: Single entry of hostname/mac
        in: query
        name: text
        schema:
          examples:
          - client-hostname
          type: string
      - description: Filter results by NAC rule identifier
        in: query
        name: nacrule_id
        schema:
          examples:
          - 8bfc2490-d726-3587-038d-cb2e71bd2330
          type: string
      - description: Filter results by DHCP hostname
        in: query
        name: dhcp_hostname
        schema:
          examples:
          - client-hostname
          type: string
      - description: Filter results by DHCP FQDN
        in: query
        name: dhcp_fqdn
        schema:
          examples:
          - client.example.com
          type: string
      - description: Filter results by DHCP client identifier
        in: query
        name: dhcp_client_identifier
        schema:
          examples:
          - 01:23:45:67:89:ab
          type: string
      - description: DHCP Vendor Class Identifier
        in: query
        name: dhcp_vendor_class_identifier
        schema:
          examples:
          - Juniper-Mist-AP,Juniper-Mist-Client
          type: string
      - description: Filter results by DHCP request parameters
        in: query
        name: dhcp_request_params
        schema:
          examples:
          - hostname,domain-name,domain-name-servers
          type: string
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/start'
      - $ref: '#/components/parameters/end'
      - $ref: '#/components/parameters/duration'
      - $ref: '#/components/parameters/sort'
      - $ref: '#/components/parameters/search_after'
      responses:
        '200':
          $ref: '#/components/responses/WiredClientsSearch'
        '400':
          $ref: '#/components/responses/HTTP400'
        '401':
          $ref: '#/components/responses/HTTP401'
        '403':
          $ref: '#/components/responses/HTTP403'
        '404':
          $ref: '#/components/responses/HTTP404'
        '429':
          $ref: '#/components/responses/HTTP429'
      summary: searchSiteWiredClients
      tags:
      - Sites Clients - Wired
components:
  examples:
    HTTP429Example:
      value:
        detail: Too Many Request. The API Token used for the request reached the 5000 API Calls per hour threshold
    CountExample:
      value:
        distinct: string
        end: 0
        limit: 0
        results:
        - count: 0
          property: string
        start: 0
        total: 0
    HTTP403Example:
      value:
        detail: You do not have permission to perform this action.
    WiredClientsSearchExample:
      value:
        end: 1648529800.8221116
        limit: 1000
        results:
        - auth_method: mac_auth
          auth_state: authenticated
          device_mac:
          - '001122334455'
          dhcp_client_identifier: MAC address 00155df6d500
          dhcp_client_options:
          - code: DHO_DHCP_MESSAGE_TYPE(53)
            data: DHCPREQUEST
          - code: DHO_DHCP_CLIENT_IDENTIFIER(61)
            data: MAC address 00155df6d500
          - code: DHO_DHCP_REQUESTED_ADDRESS(50)
            data: 172.17.10.255
          - code: DHO_DHCP_SERVER_IDENTIFIER(54)
            data: 172.17.8.1
          - code: DHO_DHCP_MAX_MESSAGE_SIZE(57)
            data: '1280'
          - code: DHO_DHCP_PARAMETER_REQUEST_LIST(55)
            data: ' 1 3 6 12 15 28 43 180'
          - code: DHO_VENDOR_CLASS_IDENTIFIER(60)
            data: MSFT 5.0
          - code: DHO_HOST_NAME(12)
            data: ITS-VMMT0-D1N02
          dhcp_fqdn: ITS-VMMT0-D1N02.mgthub.local
          dhcp_hostname: ITS-VMMT0-D1N02
          dhcp_request_params: 1 3 6 15 31 33 43 44 46 47 119 121 249 252
          dhcp_vendor_class_identifier: MSFT 5.0
          mac: '112233445566'
          org_id: c168ddee-c14c-11e5-8e81-1258369c38a9
          port_id:
          - et-0/0/1
          site_id: c168ddee-c14c-11e5-8e81-1258369c38a9
          timestamp: 1571174567.807
          vlan:
          - 0
          - 1001
        start: 1648443400.8221116
        total: 1
    HTTP401Example:
      value:
        detail: Authentication credentials were not provided.
    HTTP400Example:
      value:
        detail: 'JSON parse error - Expecting value: line 5 column 8 (char 56)'
  parameters:
    sort:
      description: On which field the list should be sorted, -prefix represents DESC order
      in: query
      name: sort
      schema:
        default: timestamp
        examples:
        - -site_id
        type: string
    duration:
      description: Time range duration for the query, using relative units such as `10m`, `7d`, or `2w`
      in: query
      name: duration
      schema:
        default: 1d
        examples:
        - 10m
        type: string
    end:
      description: Upper bound of the time range, as an epoch timestamp in seconds or a relative value such as `-1d`, `-2h`, or `now`
      in: query
      name: end
      schema:
        type: string
    start:
      description: Lower bound of the time range, as an epoch timestamp in seconds or a relative value such as `-1d` or `-1w`
      in: query
      name: start
      schema:
        type: string
    search_after:
      description: Pagination cursor for retrieving subsequent pages of results. This value is automatically populated by Mist in the `next` URL from the previous response and should not be manually constructed.
      in: query
      name: search_after
      schema:
        type: string
    limit:
      description: Maximum number of results to return per page
      in: query
      name: limit
      schema:
        default: 100
        minimum: 0
        type: integer
    site_id:
      in: path
      name: site_id
      required: true
      schema:
        examples:
        - 000000ab-00ab-00ab-00ab-0000000000ab
        format: uuid
        type: string
  schemas:
    site_wired_clients_count_distinct:
      default: mac
      description: 'enum: `mac`, `port_id`, `vlan`'
      enum:
      - mac
      - port_id
      - vlan
      type: string
    wired_client_response_device_mac_port:
      description: Per-port switch or gateway observations for a wired client
      items:
        $ref: '#/components/schemas/wired_client_response_device_mac_port_item'
      readOnly: true
      type: array
      uniqueItems: true
    timestamp:
      description: Epoch timestamp, in seconds
      format: double
      readOnly: true
      type: number
    search_wired_client:
      additionalProperties: false
      description: Paginated response for wired client searches
      properties:
        end:
          description: Upper bound timestamp of the wired client search window, in epoch seconds
          type: number
        limit:
          description: Maximum number of wired client records returned by this page
          type: integer
        next:
          description: URL for the next page of wired client records, when more results are available
          type: string
        results:
          $ref: '#/components/schemas/search_wired_client_results'
          description: Wired client records returned by the search response
        start:
          description: Lower bound timestamp of the wired client search window, in epoch seconds
          type: number
        total:
          description: Count of wired client records matching the search
          type: integer
      required:
      - end
      - limit
      - results
      - start
      - total
      type: object
    wired_client_response_vlan:
      description: Client VLAN IDs observed for a wired client
      items:
        readOnly: true
        type: integer
      readOnly: true
      type: array
    site_id:
      description: Unique identifier of a Mist site
      examples:
      - 441a1214-6928-442a-8e92-e1d34b8ec6a6
      format: uuid
      readOnly: true
      type: string
    count_results:
      description: List of count result rows
      items:
        $ref: '#/components/schemas/count_result'
      type: array
      uniqueItems: true
    dhcp_client_option:
      additionalProperties: false
      description: DHCP client option observed in a DHCP packet
      properties:
        code:
          description: DHCP option code and option name
          examples:
          - DHO_DHCP_MESSAGE_TYPE(53)
          type: string
        data:
          description: Decoded value carried by the DHCP option
          examples:
          - DHCPREQUEST
          type: string
      type: object
    search_wired_client_results:
      description: Wired client records returned by a search response
      items:
        $ref: '#/components/schemas/wired_client_response'
      type: array
      uniqueItems: true
    response_count:
      additionalProperties: false
      description: Distinct count response for time-bounded search results
      properties:
        distinct:
          description: Field used to group the count results
          type: string
        end:
          description: Search window end timestamp for the count request, in epoch seconds
          type: integer
        limit:
          description: Maximum number of distinct count results requested
          type: integer
        results:
          $ref: '#/components/schemas/count_results'
          description: Count results grouped by the distinct field
        start:
          description: Search window start timestamp for the count request, in epoch seconds
          type: integer
        total:
          description: Number of distinct result buckets returned
          type: integer
      required:
      - distinct
      - end
      - limit
      - results
      - start
      - total
      type: object
    client_info_source:
      description: 'source from where the client was learned (lldp, mac). enum: `lldp`, `mac`'
      enum:
      - lldp
      - mac
      type: string
    response_http404:
      additionalProperties: false
      description: Standard HTTP 404 not found error response
      properties:
        id:
          description: Missing resource identifier, when the API includes one
          type: string
      type: object
    response_http400:
      additionalProperties: false
      description: Standard HTTP 400 bad request error response
      properties:
        detail:
          description: Human-readable explanation of the bad request error
          examples:
          - 'JSON parse error - Expecting value: line 5 column 8 (char 56)'
          type: string
      type: object
    response_http401:
      additionalProperties: false
      description: Standard HTTP 401 authentication error response
      properties:
        detail:
          description: Human-readable explanation of the authentication error
          examples:
          - Authentication credentials were not provided.
          type: string
      type: object
    count_result:
      additionalProperties:
        type: string
      description: Count result row with the matching distinct field values
      properties:
        count:
          description: Number of matching items for the distinct value or values in this result
          type: integer
      required:
      - count
      type: object
    response_http403:
      additionalProperties: false
      description: Standard HTTP 403 permission error response
      properties:
        detail:
          description: Human-readable explanation of the permission error
          examples:
          - You do not have permission to perform this action.
          type: string
      type: object
    wired_client_response_ip:
      description: Client IP addresses observed for a wired client
      items:
        readOnly: true
        type: string
      readOnly: true
      type: array
    wired_client_response_port_id:
      description: Switch or gateway port identifiers where a wired client was observed
      items:
        readOnly: true
        type: string
      readOnly: true
      type: array
    wired_client_dhcp_client_options:
      description: DHCP options observed for a wired client
      items:
        $ref: '#/components/schemas/dhcp_client_option'
      type: array
    wired_client_response_device_mac:
      description: Switch or gateway MAC addresses where the wired client was observed
      items:
        readOnly: true
        type: string
      readOnly: true
      type: array
    wired_client_response_device_mac_port_item:
      additionalProperties: false
      description: Switch or gateway port observation for a wired client
      properties:
        device_mac:
          description: Switch or gateway MAC address for this wired client observation
          minLength: 1
          type: string
        ip:
          description: Client IP address observed for this port entry
          readOnly: true
          type: string
        port_id:
          description: Interface identifier where the wired client was observed
          readOnly: true
          type: string
        port_parent:
          description: Parent interface or port group associated with this port entry
          type: string
        start:
          description: Time when this wired client observation began
          readOnly: true
          type: string
        vlan:
          description: Client VLAN identifier observed for this port entry
          readOnly: true
          type: integer
        when:
          description: Time when this wired client port entry was recorded
          readOnly: true
          type: string
      readOnly: true
      type: object
    wired_client_response:
      additionalProperties: false
      description: Wired client record returned by a wired client search
      properties:
        auth_method:
          description: Method used to authenticate the wired client
          examples:
          - mac_auth
          type: string
        auth_state:
          description: State reported for wired client authentication
          examples:
          - authenticated
          type: string
        device_mac:
          $ref: '#/components/schemas/wired_client_response_device_mac'
          description: MAC addresses of switches or gateways where the wired client was observed
        device_mac_port:
          $ref: '#/components/schemas/wired_client_response_device_mac_port'
          description: Per-port switch or gateway observations for the wired client
        dhcp_client_identifier:
          description: Identifier value reported by the wired client in DHCP
          examples:
          - MAC address 00155df6d500
          type: string
        dhcp_client_options:
          $ref: '#/components/schemas/wired_client_dhcp_client_options'
          description: DHCP options observed from the wired client
        dhcp_fqdn:
          description: Fully qualified domain name reported by the wired client through DHCP
          examples:
          - ITS-VMMT0-D1N02.mgthub.local
          type: string
        dhcp_hostname:
          description: Hostname reported by the wired client through DHCP
          examples:
          - ITS-VMMT0-D1N02
          type: string
        dhcp_request_params:
          description: Parameter request list advertised by the wired client in DHCP
          examples:
          - 1 3 6 15 31 33 43 44 46 47 119 121 249 252
          type: string
        dhcp_vendor_class_identifier:
          description: Vendor class identifier reported by the wired client in DHCP
          examples:
          - MSFT 5.0
          type: string
        ip:
          $ref: '#/components/schemas/wired_client_response_ip'
          description: Client IP addresses observed for the wired client
        mac:
          description: Client MAC address for the wired client record
          readOnly: true
          type: string
        org_id:
          $ref: '#/components/schemas/org_id'
          description: Owning organization associated with the wired client record
        port_id:
          $ref: '#/components/schemas/wired_client_response_port_id'
          description: Switch or gateway port identifiers where the wired client was observed
        site_id:
          $ref: '#/components/schemas/site_id'
          description: Mist site associated with the wired client record
        timestamp:
          $ref: '#/components/schemas/timestamp'
          description: Time when the wired client record was observed, in epoch seconds
        vlan:
          $ref: '#/components/schemas/wired_client_response_vlan'
          description: Client VLAN identifiers observed for the wired client
      type: object
    response_http429:
      additionalProperties: false
      description: Standard HTTP 429 rate limit error response
      properties:
        detail:
          description: Human-readable explanation of the rate limit error
          examples:
          - Too Many Request. The API Token used for the request reached the 5000 API Calls per hour threshold
          type: string
      type: object
    org_id:
      description: Unique identifier of a Mist organization
      examples:
      - a97c1b22-a4e9-411e-9bfd-d8695a0f9e61
      format: uuid
      readOnly: true
      type: string
  responses:
    WiredClientsSearch:
      content:
        application/json:
          examples:
            Example:
              $ref: '#/components/examples/WiredClientsSearchExample'
          schema:
            $ref: '#/components/schemas/search_wired_client'
        application/vnd.api+json:
          examples:
            Example:
              $ref: '#/components/examples/WiredClientsSearchExample'
          schema:
            $ref: '#/components/schemas/search_wired_client'
      description: OK
    HTTP401:
      content:
        application/json:
          examples:
            Example:
              $ref: '#/components/examples/HTTP401Example'
          schema:
            $ref: '#/components/schemas/response_http401'
        application/vnd.api+json:
          examples:
            Example:
              $ref: '#/components/examples/HTTP401Example'
          schema:
            $ref: '#/components/schemas/response_http401'
      description: Unauthorized
    HTTP404:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/response_http404'
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/response_http404'
      description: Not found. The API endpoint doesn’t exist or resource doesn’ t exist
    HTTP400:
      content:
        application/json:
          examples:
            Example:
              $ref: '#/components/examples/HTTP400Example'
          schema:
            $ref: '#/components/schemas/response_http400'
        application/vnd.api+json:
          examples:
            Example:
              $ref: '#/components/examples/HTTP400Example'
          schema:
            $ref: '#/components/schemas/response_http400'
      description: Bad Syntax
    HTTP429:
      content:
        application/json:
          examples:
            Example:
              $ref: '#/components/examples/HTTP429Example'
          schema:
            $ref: '#/components/schemas/response_http429'
        application/vnd.api+json:
          examples:
            Example:
              $ref: '#/components/examples/HTTP429Example'
          schema:
            $ref: '#/components/schemas/response_http429'
      description: Too Many Request. The API Token used for the request reached the 5000 API Calls per hour threshold
    HTTP403:
      content:
        application/json:
          examples:
            Example:
              $ref: '#/components/examples/HTTP403Example'
          schema:
            $ref: '#/components/schemas/response_http403'
        application/vnd.api+json:
          examples:
            Example:
              $ref: '#/components/examples/HTTP403Example'
          schema:
            $ref: '#/components/schemas/response_http403'
      description: Permission Denied
    Count:
      content:
        application/json:
          examples:
            Example:
              $ref: '#/components/examples/CountExample'
          schema:
            $ref: '#/components/schemas/response_count'
        application/vnd.api+json:
          examples:
            Example:
              $ref: '#/components/examples/CountExample'
          schema:
            $ref: '#/components/schemas/response_count'
      description: Result of Count
  securitySchemes:
    apiToken:
      description: "Preferred authentication method for automation and integrations. Send the API token in the HTTP `Authorization` header.\n\n**Format**:\n  `Authorization: Token {apitoken}`\n\n**Notes**:\n* An API token generated for a specific admin has the same privileges as that admin\n* An API token is automatically removed if it is not used for more than 90 days\n* SSO admins cannot generate admin API tokens. Use organization API tokens when scoped Org/Site privileges are needed."
      in: header
      name: Authorization
      type: apiKey
    csrfToken:
      description: 'Session-based authentication for browser or login/password flows. After a successful [Login](/#operations/login) request, Mist returns a `csrftoken` cookie. Send that value in the `X-CSRFToken` header on later API requests that use the login session.


        **Format**:

        ```

        X-CSRFToken: vwvBuq9qkqaKh7lu8tNc0gkvBfEaLAmx

        ```


        For automation, API Token authentication is preferred.'
      in: header
      name: X-CSRFToken
      type: apiKey