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

# List Devices

> List all the devices for a given connection.



## OpenAPI

````yaml get /entities/devices
openapi: 3.1.0
info:
  title: Leen Security API
  version: 0.0.1
servers:
  - description: Production API (US)
    url: https://api.leen.dev/v1
  - description: Production API (EU)
    url: https://api.eu-c1.leen.dev/v1
  - description: Production API (APAC)
    url: https://api.ap-se2.leen.dev/v1
security: []
paths:
  /entities/devices:
    get:
      tags:
        - entities
      summary: List Devices
      description: List all the devices for a given connection.
      operationId: list_devices
      parameters:
        - in: query
          name: status
          required: false
          schema:
            title: Status
            type: string
        - in: query
          name: vendor
          required: false
          schema:
            title: Vendor
            type: string
        - in: query
          name: ip
          required: false
          schema:
            title: Ip
            type: string
        - in: query
          name: fqdn
          required: false
          schema:
            title: Fqdn
            type: string
        - in: query
          name: hostname
          required: false
          schema:
            title: Hostname
            type: string
        - in: query
          name: includeDeviceGroups
          required: false
          schema:
            default: false
            title: Includedevicegroups
            type: boolean
        - description: >-
            Enable cursor based pagination instead of default offset-based
            pagination
          in: query
          name: enableCursor
          required: false
          schema:
            default: false
            description: >-
              Enable cursor based pagination instead of default offset-based
              pagination
            title: Enablecursor
            type: boolean
        - description: >-
            Only records whose `updated_at` is at or after this time. Leen bumps
            `updated_at` whenever any field on a record changes, so this is the
            filter for an incremental sync: it returns records that are new and
            records that changed, and nothing that has stood still. Example:
            `2021-01-01T00:00:00+00:00`.
          in: query
          name: updatedSince
          required: false
          schema:
            anyOf:
              - format: date-time
                type: string
              - type: 'null'
            description: >-
              Only records whose `updated_at` is at or after this time. Leen
              bumps `updated_at` whenever any field on a record changes, so this
              is the filter for an incremental sync: it returns records that are
              new and records that changed, and nothing that has stood still.
              Example: `2021-01-01T00:00:00+00:00`.
            examples:
              - '2021-01-01T00:00:00+00:00'
            title: Updatedsince
        - description: >-
            How many records to return per page. The walk is the same either
            way; a larger page means fewer round trips and more memory per
            response.
          in: query
          name: limit
          required: false
          schema:
            default: 100
            description: >-
              How many records to return per page. The walk is the same either
              way; a larger page means fewer round trips and more memory per
              response.
            maximum: 500
            minimum: 1
            title: Limit
            type: integer
        - description: >-
            Where to start, counted in records. Offset paging is stable only
            while the underlying data is; prefer the cursor for anything
            long-running.
          in: query
          name: offset
          required: false
          schema:
            default: 0
            description: >-
              Where to start, counted in records. Offset paging is stable only
              while the underlying data is; prefer the cursor for anything
              long-running.
            minimum: 0
            title: Offset
            type: integer
        - description: >-
            Skip counting the total. Counting is the expensive half of a large
            query, so set this when you are walking every page anyway and never
            read `total`. `total` comes back null.
          in: query
          name: excludeTotal
          required: false
          schema:
            default: false
            description: >-
              Skip counting the total. Counting is the expensive half of a large
              query, so set this when you are walking every page anyway and
              never read `total`. `total` comes back null.
            title: Excludetotal
            type: boolean
        - description: >-
            Opaque position of the next page, taken from the previous response.
            Ignore its contents; it encodes where the walk had reached.
          in: query
          name: cursor
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Opaque position of the next page, taken from the previous
              response. Ignore its contents; it encodes where the walk had
              reached.
            title: Cursor
      responses:
        '200':
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: >-
                      #/components/schemas/OffsetPaginatedResponse_Union_DeviceRespModel__DeviceWithGroupsRespModel__
                  - $ref: >-
                      #/components/schemas/KeySetPaginatedResponse_Union_DeviceRespModel__DeviceWithGroupsRespModel__
                title: Response List Devices
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unprocessable Content
      security:
        - API-Key: []
          Connection-ID: []
components:
  schemas:
    OffsetPaginatedResponse_Union_DeviceRespModel__DeviceWithGroupsRespModel__:
      properties:
        count:
          description: Number of items return in the response
          title: Count
          type: integer
        items:
          description: The records on this page.
          items:
            anyOf:
              - $ref: '#/components/schemas/DeviceRespModel'
              - $ref: '#/components/schemas/DeviceWithGroupsRespModel'
          title: Items
          type: array
        total:
          anyOf:
            - type: integer
            - type: 'null'
          description: Total number of items that can be returned
          title: Total
      required:
        - count
        - items
      title: >-
        OffsetPaginatedResponse[Union[DeviceRespModel,
        DeviceWithGroupsRespModel]]
      type: object
    KeySetPaginatedResponse_Union_DeviceRespModel__DeviceWithGroupsRespModel__:
      properties:
        items:
          description: The records on this page.
          items:
            anyOf:
              - $ref: '#/components/schemas/DeviceRespModel'
              - $ref: '#/components/schemas/DeviceWithGroupsRespModel'
          title: Items
          type: array
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Opaque position of the next page. Pass it back as `cursor` to
            continue; null when this is the last page.
          title: Next Cursor
        previous_cursor:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Opaque position of the previous page, for walking backwards. Null on
            the first page.
          title: Previous Cursor
      required:
        - items
      title: >-
        KeySetPaginatedResponse[Union[DeviceRespModel,
        DeviceWithGroupsRespModel]]
      type: object
    ErrorResponse:
      properties:
        code:
          description: Error code
          title: Code
          type: string
        detail:
          description: List of error dictionaries
          items:
            additionalProperties: true
            type: object
          title: Detail
          type: array
        message:
          description: Error message
          title: Message
          type: string
        type:
          description: Type of error
          title: Type
          type: string
      required:
        - type
        - code
        - message
        - detail
      title: ErrorResponse
      type: object
    DeviceRespModel:
      properties:
        ad_info:
          anyOf:
            - $ref: '#/components/schemas/DeviceADInfo'
            - type: 'null'
          description: >-
            Active Directory placement -- organisational unit and site -- where
            the tool reports it.
        cloud_metadata:
          anyOf:
            - $ref: '#/components/schemas/AWSMetadata'
            - type: 'null'
          description: CloudMetadata, currently only AWS is supported
        first_seen:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: >-
            When the tool first registered this device. The tool's own
            timestamp, not when Leen synced it.
          title: First Seen
        fqdns:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          description: Fully qualified domain names for this device.
          title: Fqdns
        hostnames:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          description: Hostnames the tool knows this device by. A device can have several.
          title: Hostnames
        id:
          description: Leen's identifier for this device.
          format: uuid
          title: Id
          type: string
        identities:
          anyOf:
            - items:
                $ref: '#/components/schemas/DeviceIdentity'
              type: array
            - type: 'null'
          description: >-
            Accounts associated with the device, such as its last logged-in
            user.
          title: Identities
        installed_software:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          description: Software the tool reported as installed.
          title: Installed Software
        ipv4s:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          description: IPv4 addresses the tool last observed. Not necessarily current.
          title: Ipv4S
        ipv6s:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          description: IPv6 addresses the tool last observed.
          title: Ipv6S
        last_seen:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: >-
            When the tool last had contact with the device. Use it to tell a
            decommissioned machine from one that simply has no findings.
          title: Last Seen
        mac_addresses:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          description: MAC addresses of the device's interfaces.
          title: Mac Addresses
        os_major_version:
          anyOf:
            - type: string
            - type: 'null'
          description: Major version, split out of `os_version` so it can be filtered on.
          title: Os Major Version
        os_minor_version:
          anyOf:
            - type: string
            - type: 'null'
          description: Minor version, split out of `os_version`.
          title: Os Minor Version
        os_version:
          anyOf:
            - type: string
            - type: 'null'
          description: Full operating system version string, as the tool reports it.
          title: Os Version
        platform:
          anyOf:
            - $ref: '#/components/schemas/DevicePlatform'
            - type: 'null'
          description: Operating system family, normalised across tools.
        source_vendors:
          description: >-
            The tool this device came from, and that tool's identifier for it. A
            list because the shape allows several; today a device carries
            exactly one.
          items:
            $ref: '#/components/schemas/DeviceVendor'
          title: Source Vendors
          type: array
        status:
          $ref: '#/components/schemas/DeviceStatus'
          description: >-
            Device state as the tool reports it. `quarantined` means the tool
            has isolated it; `deleted` means the tool no longer returns it.
        tags:
          anyOf:
            - items:
                $ref: '#/components/schemas/DeviceTags'
              type: array
            - type: 'null'
          description: Tags the tool carries for this device.
          title: Tags
        vendor_data:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          description: Vendor specific pass through data, values can vary based on vendor
          title: Vendor Data
      required:
        - id
        - status
        - last_seen
        - first_seen
        - source_vendors
        - installed_software
        - ad_info
      title: Device
      type: object
    DeviceWithGroupsRespModel:
      properties:
        ad_info:
          anyOf:
            - $ref: '#/components/schemas/DeviceADInfo'
            - type: 'null'
          description: >-
            Active Directory placement -- organisational unit and site -- where
            the tool reports it.
        cloud_metadata:
          anyOf:
            - $ref: '#/components/schemas/AWSMetadata'
            - type: 'null'
          description: CloudMetadata, currently only AWS is supported
        device_groups:
          default: []
          description: >-
            Pass in the includeDeviceGroups query parameter to include device
            group information.
          items:
            $ref: '#/components/schemas/DeviceGroupsBase'
          title: Device Groups
          type: array
        first_seen:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: >-
            When the tool first registered this device. The tool's own
            timestamp, not when Leen synced it.
          title: First Seen
        fqdns:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          description: Fully qualified domain names for this device.
          title: Fqdns
        hostnames:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          description: Hostnames the tool knows this device by. A device can have several.
          title: Hostnames
        id:
          description: Leen's identifier for this device.
          format: uuid
          title: Id
          type: string
        identities:
          anyOf:
            - items:
                $ref: '#/components/schemas/DeviceIdentity'
              type: array
            - type: 'null'
          description: >-
            Accounts associated with the device, such as its last logged-in
            user.
          title: Identities
        installed_software:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          description: Software the tool reported as installed.
          title: Installed Software
        ipv4s:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          description: IPv4 addresses the tool last observed. Not necessarily current.
          title: Ipv4S
        ipv6s:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          description: IPv6 addresses the tool last observed.
          title: Ipv6S
        last_seen:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: >-
            When the tool last had contact with the device. Use it to tell a
            decommissioned machine from one that simply has no findings.
          title: Last Seen
        mac_addresses:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          description: MAC addresses of the device's interfaces.
          title: Mac Addresses
        os_major_version:
          anyOf:
            - type: string
            - type: 'null'
          description: Major version, split out of `os_version` so it can be filtered on.
          title: Os Major Version
        os_minor_version:
          anyOf:
            - type: string
            - type: 'null'
          description: Minor version, split out of `os_version`.
          title: Os Minor Version
        os_version:
          anyOf:
            - type: string
            - type: 'null'
          description: Full operating system version string, as the tool reports it.
          title: Os Version
        platform:
          anyOf:
            - $ref: '#/components/schemas/DevicePlatform'
            - type: 'null'
          description: Operating system family, normalised across tools.
        source_vendors:
          description: >-
            The tool this device came from, and that tool's identifier for it. A
            list because the shape allows several; today a device carries
            exactly one.
          items:
            $ref: '#/components/schemas/DeviceVendor'
          title: Source Vendors
          type: array
        status:
          $ref: '#/components/schemas/DeviceStatus'
          description: >-
            Device state as the tool reports it. `quarantined` means the tool
            has isolated it; `deleted` means the tool no longer returns it.
        tags:
          anyOf:
            - items:
                $ref: '#/components/schemas/DeviceTags'
              type: array
            - type: 'null'
          description: Tags the tool carries for this device.
          title: Tags
        vendor_data:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          description: Vendor specific pass through data, values can vary based on vendor
          title: Vendor Data
      required:
        - id
        - status
        - last_seen
        - first_seen
        - source_vendors
        - installed_software
        - ad_info
      title: DeviceWithGroups
      type: object
    DeviceADInfo:
      properties:
        device_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Device Id
        domain:
          anyOf:
            - type: string
            - type: 'null'
          title: Domain
        org_unit:
          anyOf:
            - type: string
            - type: 'null'
          title: Org Unit
        site_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Site Name
      title: DeviceADInfo
      type: object
    AWSMetadata:
      properties:
        account_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Account Id
        availability_zone:
          anyOf:
            - type: string
            - type: 'null'
          title: Availability Zone
        cloud_provider:
          $ref: '#/components/schemas/CloudProvider'
          default: aws
        image_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Image Id
        instance_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Instance Id
        instance_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Instance Type
        kernel_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Kernel Id
        region:
          anyOf:
            - type: string
            - type: 'null'
          title: Region
        subnet_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Subnet Id
        vpc_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Vpc Id
      title: AWSMetadata
      type: object
    DeviceIdentity:
      properties:
        user_sid:
          anyOf:
            - type: string
            - type: 'null'
          title: User Sid
        username:
          title: Username
          type: string
      required:
        - username
      title: DeviceIdentity
      type: object
    DevicePlatform:
      enum:
        - mac
        - windows
        - linux
        - unknown
      title: DevicePlatform
      type: string
    DeviceVendor:
      properties:
        agent_info:
          anyOf:
            - $ref: '#/components/schemas/DeviceAgentInfo'
            - type: 'null'
        vendor:
          title: Vendor
          type: string
        vendor_id:
          title: Vendor Id
          type: string
      required:
        - vendor
        - vendor_id
      title: DeviceVendor
      type: object
    DeviceStatus:
      enum:
        - active
        - offline
        - quarantined
        - unknown
        - deleted
      title: DeviceStatus
      type: string
    DeviceTags:
      properties:
        key:
          title: Key
          type: string
        source:
          $ref: '#/components/schemas/DeviceTagSource'
        value:
          title: Value
          type: string
      required:
        - key
        - value
        - source
      title: DeviceTags
      type: object
    DeviceGroupsBase:
      properties:
        created_by:
          anyOf:
            - type: string
            - type: 'null'
          description: Who created the group in the tool.
          title: Created By
        description:
          anyOf:
            - type: string
            - type: 'null'
          description: Group description, where the tool has one.
          title: Description
        id:
          description: Leen's identifier for this group.
          format: uuid
          title: Id
          type: string
        name:
          description: Group name, as the tool names it.
          title: Name
          type: string
        vendor:
          description: Connector that produced this group.
          title: Vendor
          type: string
        vendor_created_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: When the group was created in the tool, where the tool reports it.
          title: Vendor Created At
        vendor_data:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          description: Vendor specific pass through data, values can vary based on vendor
          title: Vendor Data
        vendor_id:
          description: The tool's own identifier for the group.
          title: Vendor Id
          type: string
      required:
        - id
        - name
        - vendor_id
        - vendor
      title: DeviceGroupsBase
      type: object
    CloudProvider:
      enum:
        - aws
      title: CloudProvider
      type: string
    DeviceAgentInfo:
      properties:
        agent_version:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Version
        policies:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Policies
        signature_version:
          anyOf:
            - type: string
            - type: 'null'
          title: Signature Version
      title: DeviceAgentInfo
      type: object
    DeviceTagSource:
      enum:
        - aws
        - qualys
        - wiz_vms
        - insight_vm
      title: DeviceTagSource
      type: string
  securitySchemes:
    API-Key:
      in: header
      name: X-API-KEY
      type: apiKey
    Connection-ID:
      in: header
      name: X-CONNECTION-ID
      type: apiKey

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.