> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nerves-hub.org/llms.txt
> Use this file to discover all available pages before exploring further.

# List Devices



## OpenAPI

````yaml https://manage.nervescloud.com/api/openapi get /api/orgs/{org_name}/products/{product_name}/devices
openapi: 3.0.0
info:
  description: >
    The NervesCloud API gives users full access to their

    Orgs, Products, and corresponding Device fleets.


    The API can be used to integrate with your own systems, providing full
    access to your Product and Device data.


    The API is documented using the OpenAPI 3.0 specification.
  title: NervesCloud API
  version: 2.0.0
servers:
  - url: https://manage.nervescloud.com
    variables: {}
security:
  - bearer_auth: []
tags:
  - description: User authentication and API token creation
    name: Auth
  - description: Organization Certificate Authority management
    name: CA Certificates
  - description: >-
      Device management, including action requests eg. upgrade, reboot,
      reconnect
    name: Devices
  - description: Log lines Devices have sent over the logging extension
    name: Device Logs
  - description: >-
      Device management, including action requests eg. upgrade, reboot,
      reconnect
    name: Devices (short URL)
  - description: Device Certificate management
    name: Device Certificates
  - description: Identities a Device holds on networks NervesHub does not run
    name: Network Identities
  - description: Deployment Group and release management
    name: Deployment Groups
  - description: Firmware uploading and management
    name: Firmwares
  - description: Organization iroh endpoint id registration
    name: Iroh Endpoints
  - description: Organization management
    name: Organizations
  - description: Organization User membership management
    name: Organization Members
  - description: Product management
    name: Products
  - description: Organization Signing Key management
    name: Signing Keys
  - description: Product Support Script management
    name: Support Scripts
  - description: Platform healthcheck
    name: Platform Status
paths:
  /api/orgs/{org_name}/products/{product_name}/devices:
    get:
      tags:
        - Devices
      summary: List Devices
      operationId: NervesHubWeb.API.DevicesController.index
      parameters:
        - description: Organization Name
          example: example_org
          in: path
          name: org_name
          required: true
          schema:
            type: string
        - description: Product Name
          example: example_product
          in: path
          name: product_name
          required: true
          schema:
            type: string
        - description: Sort By
          example: identifier
          in: query
          name: sort
          required: false
          schema:
            type: string
        - description: Sort Direction
          example: asc
          in: query
          name: sort_direction
          required: false
          schema:
            type: string
        - description: Pagination
          in: query
          name: pagination
          required: false
          schema:
            properties:
              page:
                default: 1
                example: '5'
                type: integer
              page_size:
                default: 10
                example: '20'
                type: integer
            type: object
          style: deepObject
        - description: Filtering
          in: query
          name: filters
          required: false
          schema:
            properties:
              advanced_query:
                description: >
                  A query in the device list's advanced query language, the same
                  one the

                  web UI's search bar uses. Values are quoted; expressions
                  combine with

                  `and`/`or`/`not` and parentheses. Custom health metrics are
                  queried as

                  `metric:<key>` with numeric comparisons against each device's
                  latest

                  reading. Input that doesn't look like a query expression is
                  treated as

                  a free-text search across the device's textual fields; an
                  invalid

                  query expression is rejected with a 422 and the parse error.


                  Examples:

                  * `metric:cpu_temp > 70`

                  * `connection = "connected" and tags contains "prod"`

                  * `health_status != "healthy" or alarm_status = "with"`

                  * `metric:battery_soc < 20 and updates = "enabled"`
                example: metric:cpu_temp > 70 and connection = "connected"
                type: string
              alarm:
                example: SomeAlarm
                type: string
              alarm_status:
                enum:
                  - with
                  - without
                type: string
              connection:
                enum:
                  - connected
                  - disconnected
                  - not_seen
                type: string
              deployment_id:
                example: '12'
                type: string
              display_deleted:
                enum:
                  - include
                  - exclude
                  - only
                type: string
              firmware_version:
                example: 1.10.0
                type: string
              has_no_tags:
                enum:
                  - 'true'
                  - 'false'
                type: string
              health_status:
                enum:
                  - healthy
                  - unhealthy
                  - warning
                  - unknown
                type: string
              identifier:
                example: sn123
                type: string
              only_updating:
                enum:
                  - 'true'
                  - 'false'
                type: string
              platform:
                example: rpi4
                type: string
              search:
                example: sn123
                type: string
              tags:
                example: prod,staging
                type: string
              updates:
                enum:
                  - enabled
                  - disabled
                  - automatic
                  - device-managed
                  - penalty-box
                type: string
            type: object
          style: deepObject
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceListResponse'
          description: Device List Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Forbidden
      callbacks: {}
      deprecated: false
      security:
        - bearer_auth: []
components:
  schemas:
    DeviceListResponse:
      description: Response schema for multiple Devices
      example:
        data:
          - connection_status: connected
            deployment_group:
              firmware_uuid: 6fd2bbc8-52b8-4826-5c2a-189968d0de23
              firmware_version: 1.2.3
              is_active: true
              name: Prod Deployment
            description: A great device
            firmware_metadata:
              architecture: arm
              author: ''
              description: Prod Firmware
              fwup_version: 1.10.1
              id: 3f2264c3-cc52-2ba9-b77d-e441f8bb91b6
              misc: extra comments
              platform: rpi5
              product: AmazingProduct
              uuid: 6fd2bbc8-52b8-4826-5c2a-189968d0de23
              vcs_identifier: ''
              version: 1.2.3
            identifier: abc123
            last_communication: '2050-04-20T00:33:09Z'
            online: true
            org_name: BigCompany
            product_name: AmazingProduct
            tags: prod, customerABC
            updates_blocked_until: '2050-04-20T00:33:09Z'
            updates_enabled: true
            version: 1.2.3
          - connection_status: disconnected
            deployment_group:
              firmware_uuid: 6fd2bbc8-52b8-4826-5c2a-189968d0de23
              firmware_version: 1.2.3
              is_active: true
              name: Prod Deployment
            description: Another great device
            firmware_metadata:
              architecture: arm
              author: ''
              description: Prod Firmware
              fwup_version: 1.10.1
              id: 3f2264c3-cc52-2ba9-b77d-e441f8bb91b6
              misc: extra comments
              platform: rpi5
              product: AmazingProduct
              uuid: 6fd2bbc8-52b8-4826-5c2a-189968d0de23
              vcs_identifier: ''
              version: 1.2.3
            identifier: def456
            last_communication: '2050-04-20T00:33:09Z'
            online: false
            org_name: BigCompany
            product_name: AmazingProduct
            tags: prod, customerDEF
            updates_blocked_until: '2050-04-20T00:33:09Z'
            updates_enabled: true
            version: 1.2.3
        pagination:
          page_number: 1
          page_size: 10
          total_entries: 2
          total_pages: 1
      properties:
        data:
          description: The Device schema
          items:
            $ref: '#/components/schemas/Device'
          type: array
        pagination:
          properties:
            page_number:
              type: integer
            page_size:
              type: integer
            total_entries:
              type: integer
            total_pages:
              type: integer
          type: object
      title: DeviceListResponse
      type: object
    ErrorResponse:
      description: Error response
      example:
        errors:
          detail: Resource Not Found or Authorization Insufficient
      properties:
        errors:
          properties:
            detail:
              type: string
          type: object
      title: ErrorResponse
      type: object
    Device:
      example:
        connection_status: connected
        deployment_group:
          firmware_uuid: 6fd2bbc8-52b8-4826-5c2a-189968d0de23
          firmware_version: 1.2.3
          is_active: true
          name: Prod Deployment
        description: A great device
        firmware_metadata:
          architecture: arm
          author: ''
          description: Prod Firmware
          fwup_version: 1.10.1
          id: 3f2264c3-cc52-2ba9-b77d-e441f8bb91b6
          misc: extra comments
          platform: rpi5
          product: AmazingProduct
          uuid: 6fd2bbc8-52b8-4826-5c2a-189968d0de23
          vcs_identifier: ''
          version: 1.2.3
        identifier: abc123
        last_communication: '2050-04-20T00:33:09Z'
        online: true
        org_name: BigCompany
        product_name: AmazingProduct
        tags: prod, customerABC
        updates_blocked_until: '2050-04-20T00:33:09Z'
        updates_enabled: true
        version: 1.2.3
      properties:
        connection_status:
          enum:
            - connected
            - disconnected
          type: string
        deployment_group:
          properties:
            firmware_uuid:
              type: string
            firmware_version:
              type: string
            is_active:
              type: boolean
            name:
              type: string
          type: object
        description:
          type: string
        firmware_metadata:
          properties:
            architecture:
              type: string
            author:
              type: string
            description:
              type: string
            fwup_version:
              type: string
            id:
              type: string
            misc:
              type: string
            platform:
              type: string
            product:
              type: string
            uuid:
              type: string
            vcs_identifier:
              type: string
            version:
              type: string
          type: object
        identifier:
          type: string
        last_communication:
          deprecated: true
          format: date-time
          type: string
        online:
          type: boolean
        org_name:
          type: string
        product_name:
          type: string
        tags:
          type: string
        update_mode:
          description: >-
            How the device receives firmware. automatic: pushed by its
            deployment group. device_managed: the device asks for updates
            itself. off: neither, only a manual push.
          enum:
            - 'off'
            - automatic
            - device_managed
          type: string
        updates_blocked_until:
          description: Device penalty box expiration timestamp
          format: date-time
          type: string
        updates_enabled:
          description: >-
            Whether the device takes updates at all. False only when update_mode
            is off.
          type: boolean
        version:
          type: string
      title: Device
      type: object
  securitySchemes:
    bearer_auth:
      scheme: bearer
      type: http

````