> ## 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 device candidates with eligibility > Return paginated devices for a site with per-device workflow eligibility. ## OpenAPI ````yaml /openapi/fleet-manager-openapi.yaml get /api/v1/eligibility/device-candidates/ 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/eligibility/device-candidates/: get: tags: - Eligibility summary: List device candidates with eligibility description: >- Return paginated devices for a site with per-device workflow eligibility. operationId: api_v1_eligibility_device_candidates_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 - in: query name: chad_ignore schema: type: boolean - in: query name: cordon_only schema: type: boolean description: >- Evaluate Quarantine eligibility for a cordon-only run, which removes the customer-ready trait without adopting the node or touching its instance. Widens readiness to an in-use or available node with an active instance. Ignored by workflows that do not explicitly support this readiness path. - 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: eligible schema: type: boolean description: >- Filter by eligibility. true=eligible only, false=ineligible only. Omit to return all. - in: query name: force_rebuild schema: type: boolean description: >- Evaluate Quarantine eligibility for in-place rebuild of an already-adopted node. Widens readiness to an active node with an instance, without the in-use requirement force_reclaim carries. Ignored by workflows that do not explicitly support this readiness path. - in: query name: force_reclaim schema: type: boolean description: >- Evaluate Quarantine eligibility for destructive force reclaim. Ignored by workflows that do not explicitly support this readiness path. - 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: 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: string format: uuid description: Site to scope candidate devices to. required: true - 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 - 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 - in: query name: workflow_id schema: type: string format: uuid description: Workflow to evaluate eligibility against. required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedDeviceCandidateList' 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: - workflow:read - device:read - cookieAuth: [] components: schemas: PaginatedDeviceCandidateList: 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/DeviceCandidate' 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' DeviceCandidate: type: object description: |- Device row annotated with per-device workflow eligibility. Response-only, and every field is always present. Standalone serializer — does NOT inherit from DeviceSerializer to avoid the expensive allocation queries in DeviceSerializer.to_representation. properties: id: type: string format: uuid readOnly: true name: type: string pattern: ^[A-Za-z0-9._-]+$ maxLength: 255 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 inventory_status: allOf: - $ref: '#/components/schemas/DeviceInventoryStatusEnum' readOnly: true operational_status: allOf: - $ref: '#/components/schemas/DeviceOperationalStatusEnum' readOnly: true health_status: allOf: - $ref: '#/components/schemas/DeviceHealthStatusEnum' readOnly: true ironic_provision_state: allOf: - $ref: '#/components/schemas/IronicProvisionStateEnum' readOnly: true nullable: true location_name: type: string readOnly: true rack_name: type: string readOnly: true 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. topology: type: object additionalProperties: type: array items: type: string description: Return topology paths keyed by facet. readOnly: true role_name: 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 chad_ignore: type: boolean readOnly: true in_triage: type: boolean readOnly: true eligibility: allOf: - $ref: '#/components/schemas/DeviceEligibility' readOnly: true required: - chad_ignore - device_type_model - device_type_resource_class - device_type_vendor - eligibility - health_status - id - in_triage - inventory_status - ironic_provision_state - location_name - name - operational_status - position - rack_name - role_name - short_name - topology 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 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 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 DeviceEligibility: type: object description: Inline eligibility status for a single device row. properties: is_eligible: type: boolean issues: type: array items: $ref: '#/components/schemas/DeviceEligibilityIssue' required: - is_eligible - issues DeviceEligibilityIssue: type: object description: A typed eligibility issue for a single device row. properties: code: $ref: '#/components/schemas/CodeEnum' message: type: string scope: $ref: '#/components/schemas/ScopeEnum' severity: $ref: '#/components/schemas/SeverityEnum' condition_type: $ref: '#/components/schemas/DeviceConditionTypeEnum' required: - code - message - scope - severity CodeEnum: enum: - inventory_status_not_allowed - operational_status_not_allowed - device_class_not_allowed - device_count_out_of_range - resource_class_missing - resource_class_mismatch - device_site_mismatch - active_workflow_conflict - device_in_triage - device_not_placed - device_inventory_only - ironic_node_not_ready - condition_prerequisite_missing - condition_prerequisite_false - condition_prerequisite_unknown - condition_disqualifier_asserted - condition_disqualifier_unproven - device_has_active_jobs - enrollment_proof_missing - topology_sync_not_healthy type: string description: |- * `inventory_status_not_allowed` - inventory_status_not_allowed * `operational_status_not_allowed` - operational_status_not_allowed * `device_class_not_allowed` - device_class_not_allowed * `device_count_out_of_range` - device_count_out_of_range * `resource_class_missing` - resource_class_missing * `resource_class_mismatch` - resource_class_mismatch * `device_site_mismatch` - device_site_mismatch * `active_workflow_conflict` - active_workflow_conflict * `device_in_triage` - device_in_triage * `device_not_placed` - device_not_placed * `device_inventory_only` - device_inventory_only * `ironic_node_not_ready` - ironic_node_not_ready * `condition_prerequisite_missing` - condition_prerequisite_missing * `condition_prerequisite_false` - condition_prerequisite_false * `condition_prerequisite_unknown` - condition_prerequisite_unknown * `condition_disqualifier_asserted` - condition_disqualifier_asserted * `condition_disqualifier_unproven` - condition_disqualifier_unproven * `device_has_active_jobs` - device_has_active_jobs * `enrollment_proof_missing` - enrollment_proof_missing * `topology_sync_not_healthy` - topology_sync_not_healthy ScopeEnum: enum: - device - cohort - parameters type: string description: |- * `device` - device * `cohort` - cohort * `parameters` - parameters SeverityEnum: enum: - error - warning type: string description: |- * `error` - error * `warning` - warning DeviceConditionTypeEnum: enum: - ProvisioningHealthy - MaintenanceClear - Enrolled - InValidationPool - InstanceAllocated - CustomerAllocated - CustomerReady - SlurmMember - SlurmSchedulable - TelemetryHealthy - SystemHealthy - ChassisHealthy - ProcessorHealthy - MemoryHealthy - StorageHealthy - DiskHealthy - PowerSupplyHealthy - GpuHealthy - FpgaHealthy - CustodyIntent - FrontendPortsInCustomerVrf - NvLinkGpusInRepairPartition - BackendPortsInMaintenanceVrf type: string description: |- * `ProvisioningHealthy` - Provisioning healthy * `MaintenanceClear` - Maintenance clear * `Enrolled` - Enrolled * `InValidationPool` - In validation pool * `InstanceAllocated` - Instance allocated * `CustomerAllocated` - Customer allocated * `CustomerReady` - Customer ready * `SlurmMember` - Slurm member * `SlurmSchedulable` - Slurm schedulable * `TelemetryHealthy` - Telemetry healthy * `SystemHealthy` - System healthy * `ChassisHealthy` - Chassis healthy * `ProcessorHealthy` - Processor healthy * `MemoryHealthy` - Memory healthy * `StorageHealthy` - Storage healthy * `DiskHealthy` - Disk healthy * `PowerSupplyHealthy` - Power supply healthy * `GpuHealthy` - GPU healthy * `FpgaHealthy` - FPGA healthy * `CustodyIntent` - Custody intent * `FrontendPortsInCustomerVrf` - Front-end ports in customer VRF * `NvLinkGpusInRepairPartition` - GPUs in NVLink repair partition * `BackendPortsInMaintenanceVrf` - Back-end ports in maintenance VRF 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.