> ## Documentation Index > Fetch the complete documentation index at: https://docs.internal.nscale.com/llms.txt > Use this file to discover all available pages before exploring further. # List devices > List, retrieve, create and update devices for a site. ## OpenAPI ````yaml /openapi/fleet-manager-openapi.yaml get /api/v1/devices/ openapi: 3.0.3 info: title: Fleet Manager API version: 1.0.0 description: API for the Nscale Fleet Manager servers: [] security: [] paths: /api/v1/devices/: get: tags: - Devices summary: List devices description: List, retrieve, create and update devices for a site. operationId: api_v1_devices_list parameters: - in: query name: allocation_id schema: type: array items: type: string format: uuid description: Multiple values may be separated by commas. explode: false style: form - name: annotation_eq required: false in: query description: >- Filter by annotation key=value pairs (AND semantics). Use annotation_eq[key]=value. style: deepObject explode: true schema: type: object additionalProperties: type: string - name: annotation_has required: false in: query description: Filter by annotation key existence (comma-separated, AND semantics). schema: type: string - in: query name: chad_ignore schema: type: boolean - in: query name: current_instance_uuid schema: type: string - in: query name: current_tenant_id schema: type: array items: type: string format: uuid description: Multiple values may be separated by commas. explode: false style: form - in: query name: customer_ready schema: type: boolean - in: query name: device_class schema: type: array items: type: string enum: - cpu_baremetal - cpu_hypervisor - gpu_compute - switch description: Multiple values may be separated by commas. explode: false style: form - in: query name: device_group_id schema: type: array items: type: string format: uuid description: Multiple values may be separated by commas. explode: false style: form - in: query name: device_type_id schema: type: array items: type: string format: uuid description: Multiple values may be separated by commas. explode: false style: form - in: query name: health_status schema: type: array items: type: string enum: - critical - degraded - healthy - unknown description: Multiple values may be separated by commas. explode: false style: form - in: query name: in_triage schema: type: boolean - in: query name: infrastructure_ref schema: type: string - in: query name: infrastructure_ref__startswith schema: type: string - in: query name: inventory_only schema: type: boolean - in: query name: inventory_status schema: type: array items: type: string enum: - active - decommissioned - decommissioning - failed - inventory - offline - planned - returned - rma - staged - unknown description: Multiple values may be separated by commas. explode: false style: form - in: query name: ironic_provision_state schema: type: array items: type: string enum: - active - adopt failed - adopting - available - clean failed - clean hold - clean wait - cleaning - deleted - deleting - deploy complete - deploy failed - deploy hold - deploying - enroll - error - inspect failed - inspect wait - inspecting - manageable - rebuild - rescue - rescue failed - rescue wait - rescuing - service - service failed - service hold - service wait - servicing - unknown - unrescue failed - unrescuing - verifying - wait call-back description: Multiple values may be separated by commas. explode: false style: form - in: query name: job_id schema: type: array items: type: string format: uuid description: Multiple values may be separated by commas. explode: false style: form - name: limit required: false in: query description: Number of results to return per page. schema: type: integer maximum: 500 minimum: 1 - in: query name: location_id schema: type: array items: type: string format: uuid description: Multiple values may be separated by commas. explode: false style: form - in: query name: name schema: type: string - in: query name: name_exact schema: type: string - in: query name: netbox_id schema: type: integer - in: query name: operational_status schema: type: array items: type: string enum: - available - delegated - drained - failed - in_use - pending_handover - quarantine - unknown - validation description: Multiple values may be separated by commas. explode: false style: form - name: ordering required: false in: query description: Which field to use when ordering the results. schema: type: array items: type: string enum: - name - '-name' - created_at - '-created_at' - updated_at - '-updated_at' x-enum-varnames: - NameAsc - NameDesc - CreatedAtAsc - CreatedAtDesc - UpdatedAtAsc - UpdatedAtDesc style: form explode: false - name: page required: false in: query description: A page number within the paginated result set. schema: type: integer - in: query name: rack_id schema: type: array items: type: string format: uuid description: Multiple values may be separated by commas. explode: false style: form - in: query name: role_id schema: type: array items: type: string format: uuid description: Multiple values may be separated by commas. explode: false style: form - in: query name: serial_number schema: type: string - in: query name: site_id schema: type: array items: type: string format: uuid description: Multiple values may be separated by commas. explode: false style: form - in: query name: slurm_states schema: type: array items: type: string enum: - ALLOCATED - BLOCKED - CLOUD - COMPLETING - DOWN - DRAIN - DYNAMIC_FUTURE - DYNAMIC_NORM - ERROR - FAIL - FUTURE - IDLE - INVALID_REG - MAINTENANCE - MIXED - NOT_RESPONDING - PLANNED - POWERED_DOWN - POWERING_DOWN - POWERING_UP - POWER_DOWN - POWER_DRAIN - POWER_UP - REBOOT_CANCELED - REBOOT_ISSUED - REBOOT_REQUESTED - RESERVED - RESUME - UNDRAIN - UNKNOWN description: >- SLURM node states. A device matches when its own state list contains any of these. Multiple values may be separated by commas. explode: false style: form - name: tag required: false in: query description: Filter by tags (comma-separated, OR semantics). schema: type: string - in: query name: topology_group_id schema: type: array items: type: string format: uuid description: Multiple values may be separated by commas. explode: false style: form - in: query name: topology_group_id_strict schema: type: array items: type: string format: uuid description: Multiple values may be separated by commas. explode: false style: form responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedDeviceList' description: '' '400': description: Validation error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Authentication credentials were not provided or are invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: You do not have permission to perform this action. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - oauth2: - device:read - cookieAuth: [] components: schemas: PaginatedDeviceList: type: object required: - count - results properties: count: type: integer example: 123 next: type: string nullable: true format: uri example: http://api.example.org/accounts/?page=4 previous: type: string nullable: true format: uri example: http://api.example.org/accounts/?page=2 results: type: array items: $ref: '#/components/schemas/Device' ErrorResponse: type: object description: >- Uniform error body for every 4xx/5xx response. `detail` is a human-readable message, always present, safe to display to end users. `code` is the machine-readable identifier. `field_errors` lists per-input-field validation messages and is empty for non-field errors (auth, permission, not-found, conflict, server). required: - detail - code - field_errors properties: detail: type: string code: $ref: '#/components/schemas/ErrorCodeEnum' field_errors: type: array items: $ref: '#/components/schemas/FieldError' Device: type: object description: Serializer for Device model. properties: id: type: string format: uuid readOnly: true nvswitch_rack_slot: allOf: - $ref: '#/components/schemas/NVSwitchRackSlotEnum' readOnly: true nullable: true nvswitch_switch_role: allOf: - $ref: '#/components/schemas/NVSwitchSwitchRoleEnum' readOnly: true nvswitch_nvos_hostname: type: string readOnly: true maxLength: 255 annotations: type: object additionalProperties: type: string description: >- Key-value annotations. Keys must start with a lowercase letter and contain only lowercase alphanumeric segments joined by hyphens or underscores (e.g. 'org-id', 'gpu_ready'). tags: type: array items: type: string description: >- Tags for the resource. Must start with a lowercase letter and contain only lowercase alphanumeric segments joined by hyphens or underscores (e.g. 'gpu-ready', 'needs_review'). Stored deduplicated and sorted. serial_number: type: string nullable: true infrastructure_ref: type: string nullable: true enrollment_validated_ref: type: string nullable: true readOnly: true current_instance_uuid: type: string nullable: true readOnly: true ironic_provision_state: allOf: - $ref: '#/components/schemas/IronicProvisionStateEnum' nullable: true placement_traits: type: array items: type: string slurm_states: type: array items: $ref: '#/components/schemas/DeviceSlurmStateEnum' slurm_state_updated_at: type: string format: date-time nullable: true slurm_state_reason: type: string nullable: true operational_failure_reason: type: string nullable: true operational_failure_details: type: string nullable: true ironic_maintenance: type: boolean ironic_maintenance_reason: type: string nullable: true ironic_fault: type: string nullable: true ironic_last_error: type: string nullable: true triage_ticket_url: nullable: true oneOf: - type: string format: uri minLength: 1 - type: string maxLength: 0 parent_ticket_url: nullable: true oneOf: - type: string format: uri minLength: 1 - type: string maxLength: 0 netbox_link: type: string format: uri writeOnly: true maxLength: 200 netbox_id: type: integer maximum: 2147483647 minimum: 0 nullable: true netbox_source_updated_at: type: string format: date-time writeOnly: true nullable: true description: >- NetBox device last_updated timestamp acknowledged by the lifecycle sync. This is NetBox source time, not a Fleet Manager wall-clock timestamp. Only the exact netbox-agent OAuth client may submit this field. interfaces: type: array items: $ref: '#/components/schemas/Interface' inventory_status: $ref: '#/components/schemas/DeviceInventoryStatusEnum' operational_status: $ref: '#/components/schemas/DeviceOperationalStatusEnum' health_status: $ref: '#/components/schemas/DeviceHealthStatusEnum' device_type_kind: type: string readOnly: true device_type_vendor: type: string readOnly: true device_type_model: type: string readOnly: true device_type_resource_class: type: string readOnly: true role_name: type: string readOnly: true role_slug: type: string readOnly: true pattern: ^[-a-zA-Z0-9_]+$ device_class: allOf: - $ref: '#/components/schemas/DeviceClassEnum' readOnly: true rack_name: type: string readOnly: true rack_serial_number: type: string readOnly: true default: '' description: >- Rack serial number for this device's rack. Empty string if not synced. location_name: type: string readOnly: true site_name: type: string readOnly: true site_slug: type: string readOnly: true pattern: ^[-a-zA-Z0-9_]+$ organisation_id: type: string format: uuid readOnly: true organisation_slug: type: string readOnly: true pattern: ^[-a-zA-Z0-9_]+$ links: allOf: - $ref: '#/components/schemas/DeviceLinks' readOnly: true customer_ready: type: boolean description: Compute customer_ready based on status fields. readOnly: true topology: type: object additionalProperties: type: array items: type: string description: Return topology paths keyed by facet. readOnly: true topology_group_types: type: object additionalProperties: type: object additionalProperties: type: string description: >- Return topology as {facet: {type: label}} using cached path_types/path_labels. Enables type-aware lookup (e.g. find the "pod" label within "networking") even when the device is a member of a deeper group like "nvlink-domain". No extra queries — both path_types and path_labels are cached JSON fields on TopologyGroup. readOnly: true short_name: type: string description: >- Extract short device identifier from full name. Takes the last hyphen-separated segment (e.g. "gpu1255" from "sta1-p-phy-gpu1255"). Falls back to the full name if the segment doesn't contain both letters and digits. readOnly: true current_tenant_id: type: string format: uuid readOnly: true nullable: true current_tenant_name: type: string nullable: true readOnly: true current_allocation_annotations: type: object additionalProperties: type: string readOnly: true nullable: true description: UNI region annotations from the device's active allocation. created_at: type: string format: date-time readOnly: true updated_at: type: string format: date-time readOnly: true name: type: string pattern: ^[A-Za-z0-9._-]+$ maxLength: 255 nvswitch_ztp_completed_at: type: string format: date-time readOnly: true nullable: true nvswitch_ztp_evidence_source: type: string readOnly: true description: e.g. netbox_tag, network_api, manual position: type: string format: decimal pattern: ^-?\d{0,3}(?:\.\d{0,1})?$ nullable: true description: >- Rack U position. Null for an unpositioned device, one NetBox has in its rack without a U. platform_class: type: string description: >- Hardware descriptor key ___, computed by the enrollment workflow from NetBox and mirrored to NetBox custom_fields.platform_class. Empty until the device first enrols. maxLength: 128 enrollment_proof_source: allOf: - $ref: '#/components/schemas/EnrollmentProofSourceEnum' readOnly: true description: |- Provenance of the current enrollment identity proof. * `enrolled` - Enrolled * `legacy` - Legacy * `unmigrated` - Unmigrated * `none` - None entered_service_at: type: string format: date-time nullable: true in_triage: type: boolean entered_triage_at: type: string format: date-time readOnly: true nullable: true chad_ignore: type: boolean inventory_only: type: boolean readOnly: true device_type: type: string format: uuid role: type: string format: uuid rack: type: string format: uuid location: type: string format: uuid readOnly: true site: type: string format: uuid readOnly: true required: - created_at - current_allocation_annotations - current_instance_uuid - current_tenant_id - current_tenant_name - customer_ready - device_class - device_type - device_type_kind - device_type_model - device_type_resource_class - device_type_vendor - enrollment_proof_source - enrollment_validated_ref - entered_triage_at - id - inventory_only - links - location - location_name - name - netbox_link - nvswitch_nvos_hostname - nvswitch_rack_slot - nvswitch_switch_role - nvswitch_ztp_completed_at - nvswitch_ztp_evidence_source - organisation_id - organisation_slug - position - rack - rack_name - rack_serial_number - role - role_name - role_slug - short_name - site - site_name - site_slug - topology - topology_group_types - updated_at ErrorCodeEnum: type: string description: >- Stable machine-readable error identifier. New members may be added within this API version; clients must tolerate unknown values. enum: - error - invalid - parse_error - authentication_failed - not_authenticated - permission_denied - not_found - method_not_allowed - not_acceptable - unsupported_media_type - conflict - enrollment_infrastructure_reference_pending - enrollment_infrastructure_reference_changed - unprocessable_entity - throttled - service_unavailable FieldError: type: object description: One input field's validation messages. required: - field - messages properties: field: type: string description: >- Dotted path to the offending input field, or to the collection row when the whole row is invalid (e.g. `filters.end_date`, `memberships.0.role`, `memberships.0`). messages: type: array minItems: 1 items: type: string NVSwitchRackSlotEnum: enum: - ST0 - ST1 - ST2 - ST3 - ST4 - ST5 - ST6 - ST7 - ST8 type: string description: |- * `ST0` - ST0 * `ST1` - ST1 * `ST2` - ST2 * `ST3` - ST3 * `ST4` - ST4 * `ST5` - ST5 * `ST6` - ST6 * `ST7` - ST7 * `ST8` - ST8 NVSwitchSwitchRoleEnum: enum: - '' - lead - member type: string description: |- * `` - Unset * `lead` - Lead * `member` - Member IronicProvisionStateEnum: enum: - enroll - verifying - manageable - available - active - wait call-back - deploying - deploy failed - deploy complete - deploy hold - deleting - deleted - cleaning - clean wait - clean failed - clean hold - error - rebuild - inspecting - inspect failed - inspect wait - adopting - adopt failed - rescue - rescue failed - rescue wait - rescuing - unrescue failed - unrescuing - service - servicing - service wait - service failed - service hold - unknown type: string description: |- * `enroll` - enroll * `verifying` - verifying * `manageable` - manageable * `available` - available * `active` - active * `wait call-back` - wait call-back * `deploying` - deploying * `deploy failed` - deploy failed * `deploy complete` - deploy complete * `deploy hold` - deploy hold * `deleting` - deleting * `deleted` - deleted * `cleaning` - cleaning * `clean wait` - clean wait * `clean failed` - clean failed * `clean hold` - clean hold * `error` - error * `rebuild` - rebuild * `inspecting` - inspecting * `inspect failed` - inspect failed * `inspect wait` - inspect wait * `adopting` - adopting * `adopt failed` - adopt failed * `rescue` - rescue * `rescue failed` - rescue failed * `rescue wait` - rescue wait * `rescuing` - rescuing * `unrescue failed` - unrescue failed * `unrescuing` - unrescuing * `service` - service * `servicing` - servicing * `service wait` - service wait * `service failed` - service failed * `service hold` - service hold * `unknown` - unknown DeviceSlurmStateEnum: enum: - ALLOCATED - DOWN - ERROR - FUTURE - IDLE - MIXED - UNKNOWN - BLOCKED - CLOUD - COMPLETING - DRAIN - DYNAMIC_FUTURE - DYNAMIC_NORM - FAIL - INVALID_REG - MAINTENANCE - NOT_RESPONDING - PLANNED - POWERED_DOWN - POWERING_DOWN - POWERING_UP - POWER_DOWN - POWER_DRAIN - POWER_UP - REBOOT_CANCELED - REBOOT_ISSUED - REBOOT_REQUESTED - RESERVED - RESUME - UNDRAIN type: string description: |- * `ALLOCATED` - ALLOCATED * `DOWN` - DOWN * `ERROR` - ERROR * `FUTURE` - FUTURE * `IDLE` - IDLE * `MIXED` - MIXED * `UNKNOWN` - UNKNOWN * `BLOCKED` - BLOCKED * `CLOUD` - CLOUD * `COMPLETING` - COMPLETING * `DRAIN` - DRAIN * `DYNAMIC_FUTURE` - DYNAMIC_FUTURE * `DYNAMIC_NORM` - DYNAMIC_NORM * `FAIL` - FAIL * `INVALID_REG` - INVALID_REG * `MAINTENANCE` - MAINTENANCE * `NOT_RESPONDING` - NOT_RESPONDING * `PLANNED` - PLANNED * `POWERED_DOWN` - POWERED_DOWN * `POWERING_DOWN` - POWERING_DOWN * `POWERING_UP` - POWERING_UP * `POWER_DOWN` - POWER_DOWN * `POWER_DRAIN` - POWER_DRAIN * `POWER_UP` - POWER_UP * `REBOOT_CANCELED` - REBOOT_CANCELED * `REBOOT_ISSUED` - REBOOT_ISSUED * `REBOOT_REQUESTED` - REBOOT_REQUESTED * `RESERVED` - RESERVED * `RESUME` - RESUME * `UNDRAIN` - UNDRAIN Interface: type: object description: Serializer for Interface model. properties: ip_addresses: type: array items: type: string name: type: string maxLength: 50 type: type: string maxLength: 50 type_display: type: string maxLength: 50 mac_address: type: string nullable: true maxLength: 17 ib_device_guid: type: string nullable: true maxLength: 16 required: - name - type - type_display DeviceInventoryStatusEnum: enum: - planned - staged - active - failed - offline - rma - returned - decommissioning - decommissioned - inventory - unknown type: string description: |- * `planned` - Planned * `staged` - Staged * `active` - Active * `failed` - Failed * `offline` - Offline * `rma` - RMA * `returned` - Returned * `decommissioning` - Decommissioning * `decommissioned` - Decommissioned * `inventory` - Inventory * `unknown` - Unknown DeviceOperationalStatusEnum: enum: - unknown - quarantine - validation - available - in_use - delegated - pending_handover - drained - failed type: string description: |- * `unknown` - Unknown * `quarantine` - Quarantine * `validation` - Validation * `available` - Available * `in_use` - In Use * `delegated` - Delegated * `pending_handover` - Pending Handover * `drained` - Drained * `failed` - Failed DeviceHealthStatusEnum: enum: - unknown - healthy - degraded - critical type: string description: |- * `unknown` - Unknown * `healthy` - Healthy * `degraded` - Degraded * `critical` - Critical DeviceClassEnum: enum: - gpu_compute - cpu_hypervisor - cpu_baremetal - switch type: string description: |- * `gpu_compute` - GPU Compute * `cpu_hypervisor` - CPU Hypervisor * `cpu_baremetal` - CPU Baremetal * `switch` - Switch DeviceLinks: type: object description: Serializer for device links. properties: self: type: string format: uri readOnly: true collection: type: string format: uri readOnly: true device_type: type: string format: uri readOnly: true role: type: string format: uri readOnly: true rack: type: string format: uri readOnly: true location: type: string format: uri readOnly: true site: type: string format: uri readOnly: true jobs: type: string format: uri readOnly: true job_device_statuses: type: string format: uri readOnly: true netbox: type: string format: uri description: |- Construct the NetBox URL from netbox_id and configured public URL. If netbox_id is set and NETBOX_PUBLIC_URL is configured, constructs the public URL. Otherwise falls back to the stored netbox_link. readOnly: true required: - collection - device_type - job_device_statuses - jobs - location - netbox - rack - role - self - site EnrollmentProofSourceEnum: enum: - enrolled - legacy - unmigrated - none type: string description: |- * `enrolled` - Enrolled * `legacy` - Legacy * `unmigrated` - Unmigrated * `none` - None securitySchemes: oauth2: type: oauth2 flows: {} cookieAuth: type: apiKey in: cookie name: sessionid ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.