curl --request GET \
--url https://api.example.com/api/v1/devices/{id}/ \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.example.com/api/v1/devices/{id}/"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.example.com/api/v1/devices/{id}/', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/v1/devices/{id}/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/v1/devices/{id}/"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.example.com/api/v1/devices/{id}/")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/devices/{id}/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"nvswitch_rack_slot": "ST0",
"nvswitch_switch_role": "",
"nvswitch_nvos_hostname": "<string>",
"enrollment_validated_ref": "<string>",
"current_instance_uuid": "<string>",
"device_type_kind": "<string>",
"device_type_vendor": "<string>",
"device_type_model": "<string>",
"device_type_resource_class": "<string>",
"role_name": "<string>",
"role_slug": "<string>",
"device_class": "gpu_compute",
"rack_name": "<string>",
"rack_serial_number": "",
"location_name": "<string>",
"site_name": "<string>",
"site_slug": "<string>",
"organisation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"organisation_slug": "<string>",
"links": {
"self": "<string>",
"collection": "<string>",
"device_type": "<string>",
"role": "<string>",
"rack": "<string>",
"location": "<string>",
"site": "<string>",
"jobs": "<string>",
"job_device_statuses": "<string>",
"netbox": "<string>"
},
"customer_ready": true,
"topology": {},
"topology_group_types": {},
"short_name": "<string>",
"current_tenant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"current_tenant_name": "<string>",
"current_allocation_annotations": {},
"operational_status_conditions": {
"decisive_types": [
"ProvisioningHealthy"
],
"conditions": [
{
"type": "ProvisioningHealthy",
"status": "True",
"source": "ironic",
"reason": "<string>",
"message": "<string>",
"observed_at": "2023-11-07T05:31:56Z",
"last_transitioned_at": "2023-11-07T05:31:56Z",
"decisive": true
}
]
},
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"name": "<string>",
"nvswitch_ztp_completed_at": "2023-11-07T05:31:56Z",
"nvswitch_ztp_evidence_source": "<string>",
"position": "<string>",
"enrollment_proof_source": "enrolled",
"entered_triage_at": "2023-11-07T05:31:56Z",
"inventory_only": true,
"device_type": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"role": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"rack": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"location": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"site": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"annotations": {},
"tags": [
"<string>"
],
"serial_number": "<string>",
"infrastructure_ref": "<string>",
"ironic_provision_state": "enroll",
"placement_traits": [
"<string>"
],
"slurm_states": [
"ALLOCATED"
],
"slurm_state_updated_at": "2023-11-07T05:31:56Z",
"slurm_state_reason": "<string>",
"operational_failure_reason": "<string>",
"operational_failure_details": "<string>",
"ironic_maintenance": true,
"ironic_maintenance_reason": "<string>",
"ironic_fault": "<string>",
"ironic_last_error": "<string>",
"triage_ticket_url": "<string>",
"parent_ticket_url": "<string>",
"netbox_id": 1073741823,
"interfaces": [
{
"name": "<string>",
"type": "<string>",
"type_display": "<string>",
"ip_addresses": [
"<string>"
],
"mac_address": "<string>",
"ib_device_guid": "<string>"
}
],
"inventory_status": "planned",
"operational_status": "unknown",
"health_status": "unknown",
"platform_class": "<string>",
"entered_service_at": "2023-11-07T05:31:56Z",
"in_triage": true,
"chad_ignore": true
}{
"detail": "<string>",
"code": "error",
"field_errors": [
{
"field": "<string>",
"messages": [
"<string>"
]
}
]
}{
"detail": "<string>",
"code": "error",
"field_errors": [
{
"field": "<string>",
"messages": [
"<string>"
]
}
]
}{
"detail": "<string>",
"code": "error",
"field_errors": [
{
"field": "<string>",
"messages": [
"<string>"
]
}
]
}Get device
List, retrieve, create and update devices for a site.
curl --request GET \
--url https://api.example.com/api/v1/devices/{id}/ \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.example.com/api/v1/devices/{id}/"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.example.com/api/v1/devices/{id}/', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/v1/devices/{id}/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/v1/devices/{id}/"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.example.com/api/v1/devices/{id}/")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/devices/{id}/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"nvswitch_rack_slot": "ST0",
"nvswitch_switch_role": "",
"nvswitch_nvos_hostname": "<string>",
"enrollment_validated_ref": "<string>",
"current_instance_uuid": "<string>",
"device_type_kind": "<string>",
"device_type_vendor": "<string>",
"device_type_model": "<string>",
"device_type_resource_class": "<string>",
"role_name": "<string>",
"role_slug": "<string>",
"device_class": "gpu_compute",
"rack_name": "<string>",
"rack_serial_number": "",
"location_name": "<string>",
"site_name": "<string>",
"site_slug": "<string>",
"organisation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"organisation_slug": "<string>",
"links": {
"self": "<string>",
"collection": "<string>",
"device_type": "<string>",
"role": "<string>",
"rack": "<string>",
"location": "<string>",
"site": "<string>",
"jobs": "<string>",
"job_device_statuses": "<string>",
"netbox": "<string>"
},
"customer_ready": true,
"topology": {},
"topology_group_types": {},
"short_name": "<string>",
"current_tenant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"current_tenant_name": "<string>",
"current_allocation_annotations": {},
"operational_status_conditions": {
"decisive_types": [
"ProvisioningHealthy"
],
"conditions": [
{
"type": "ProvisioningHealthy",
"status": "True",
"source": "ironic",
"reason": "<string>",
"message": "<string>",
"observed_at": "2023-11-07T05:31:56Z",
"last_transitioned_at": "2023-11-07T05:31:56Z",
"decisive": true
}
]
},
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"name": "<string>",
"nvswitch_ztp_completed_at": "2023-11-07T05:31:56Z",
"nvswitch_ztp_evidence_source": "<string>",
"position": "<string>",
"enrollment_proof_source": "enrolled",
"entered_triage_at": "2023-11-07T05:31:56Z",
"inventory_only": true,
"device_type": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"role": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"rack": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"location": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"site": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"annotations": {},
"tags": [
"<string>"
],
"serial_number": "<string>",
"infrastructure_ref": "<string>",
"ironic_provision_state": "enroll",
"placement_traits": [
"<string>"
],
"slurm_states": [
"ALLOCATED"
],
"slurm_state_updated_at": "2023-11-07T05:31:56Z",
"slurm_state_reason": "<string>",
"operational_failure_reason": "<string>",
"operational_failure_details": "<string>",
"ironic_maintenance": true,
"ironic_maintenance_reason": "<string>",
"ironic_fault": "<string>",
"ironic_last_error": "<string>",
"triage_ticket_url": "<string>",
"parent_ticket_url": "<string>",
"netbox_id": 1073741823,
"interfaces": [
{
"name": "<string>",
"type": "<string>",
"type_display": "<string>",
"ip_addresses": [
"<string>"
],
"mac_address": "<string>",
"ib_device_guid": "<string>"
}
],
"inventory_status": "planned",
"operational_status": "unknown",
"health_status": "unknown",
"platform_class": "<string>",
"entered_service_at": "2023-11-07T05:31:56Z",
"in_triage": true,
"chad_ignore": true
}{
"detail": "<string>",
"code": "error",
"field_errors": [
{
"field": "<string>",
"messages": [
"<string>"
]
}
]
}{
"detail": "<string>",
"code": "error",
"field_errors": [
{
"field": "<string>",
"messages": [
"<string>"
]
}
]
}{
"detail": "<string>",
"code": "error",
"field_errors": [
{
"field": "<string>",
"messages": [
"<string>"
]
}
]
}Authorizations
The access token received from the authorization server in the OAuth 2.0 flow.
Path Parameters
A UUID string identifying this device.
Response
Retrieve-only serializer: the device fields plus status-explanation conditions.
Detail-only by design. /devices/ lists through the shared DeviceSerializer
over get_device_queryset(), which does not prefetch conditions — adding the
field there would N+1 the list. This subclass is used for retrieve only (the
viewset's get_serializer_class), and the field is deliberately kept off the base
DeviceSerializer (used for create/update and embedded elsewhere) so it never
leaks a misleading value there.
ST0- ST0ST1- ST1ST2- ST2ST3- ST3ST4- ST4ST5- ST5ST6- ST6ST7- ST7ST8- ST8
ST0, ST1, ST2, ST3, ST4, ST5, ST6, ST7, ST8 - `` - Unset
lead- Leadmember- Member
, lead, member 255^[-a-zA-Z0-9_]+$gpu_compute- GPU Computecpu_hypervisor- CPU Hypervisorcpu_baremetal- CPU Baremetalswitch- Switch
gpu_compute, cpu_hypervisor, cpu_baremetal, switch Rack serial number for this device's rack. Empty string if not synced.
^[-a-zA-Z0-9_]+$^[-a-zA-Z0-9_]+$Serializer for device links.
Show child attributes
Show child attributes
Compute customer_ready based on status fields.
Return topology paths keyed by facet.
Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes
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.
UNI region annotations from the device's active allocation.
Show child attributes
Show child attributes
Conditions explaining the device's operational_status: decisive_types and the conditions behind the status, each flagged decisive. Computed on read from the current conditions (no stored derivation). Null when the status is custody-frozen or impairment-held, or when the derivation abstains (no Ironic-source condition).
Show child attributes
Show child attributes
255^[A-Za-z0-9._-]+$e.g. netbox_tag, network_api, manual
Rack U position. Null for an unpositioned device, one NetBox has in its rack without a U.
^-?\d{0,3}(?:\.\d{0,1})?$Provenance of the current enrollment identity proof.
enrolled- Enrolledlegacy- Legacyunmigrated- Unmigratednone- None
enrolled, legacy, unmigrated, none 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').
Show child attributes
Show child attributes
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.
enroll- enrollverifying- verifyingmanageable- manageableavailable- availableactive- activewait call-back- wait call-backdeploying- deployingdeploy failed- deploy faileddeploy complete- deploy completedeploy hold- deploy holddeleting- deletingdeleted- deletedcleaning- cleaningclean wait- clean waitclean failed- clean failedclean hold- clean holderror- errorrebuild- rebuildinspecting- inspectinginspect failed- inspect failedinspect wait- inspect waitadopting- adoptingadopt failed- adopt failedrescue- rescuerescue failed- rescue failedrescue wait- rescue waitrescuing- rescuingunrescue failed- unrescue failedunrescuing- unrescuingservice- serviceservicing- servicingservice wait- service waitservice failed- service failedservice hold- service holdunknown- unknown
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 ALLOCATED- ALLOCATEDDOWN- DOWNERROR- ERRORFUTURE- FUTUREIDLE- IDLEMIXED- MIXEDUNKNOWN- UNKNOWNBLOCKED- BLOCKEDCLOUD- CLOUDCOMPLETING- COMPLETINGDRAIN- DRAINDYNAMIC_FUTURE- DYNAMIC_FUTUREDYNAMIC_NORM- DYNAMIC_NORMFAIL- FAILINVALID_REG- INVALID_REGMAINTENANCE- MAINTENANCENOT_RESPONDING- NOT_RESPONDINGPLANNED- PLANNEDPOWERED_DOWN- POWERED_DOWNPOWERING_DOWN- POWERING_DOWNPOWERING_UP- POWERING_UPPOWER_DOWN- POWER_DOWNPOWER_DRAIN- POWER_DRAINPOWER_UP- POWER_UPREBOOT_CANCELED- REBOOT_CANCELEDREBOOT_ISSUED- REBOOT_ISSUEDREBOOT_REQUESTED- REBOOT_REQUESTEDRESERVED- RESERVEDRESUME- RESUMEUNDRAIN- UNDRAIN
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 110 <= x <= 2147483647Show child attributes
Show child attributes
planned- Plannedstaged- Stagedactive- Activefailed- Failedoffline- Offlinerma- RMAreturned- Returneddecommissioning- Decommissioningdecommissioned- Decommissionedinventory- Inventoryunknown- Unknown
planned, staged, active, failed, offline, rma, returned, decommissioning, decommissioned, inventory, unknown unknown- Unknownquarantine- Quarantinevalidation- Validationavailable- Availablein_use- In Usedelegated- Delegatedpending_handover- Pending Handoverdrained- Drainedfailed- Failed
unknown, quarantine, validation, available, in_use, delegated, pending_handover, drained, failed unknown- Unknownhealthy- Healthydegraded- Degradedcritical- Critical
unknown, healthy, degraded, critical Hardware descriptor key _, computed by the enrollment workflow from NetBox and mirrored to NetBox custom_fields.platform_class. Empty until the device first enrols.
128