List a node's PCI devices (operator-only).

GET

/v1/compute/nodes/{nodeId}/pci-devices

Code sample: Shell / cURL

curl --request GET \
  --url https://stratum.example.com/v1/compute/nodes/example/pci-devices \
  --header 'Authorization: Bearer <token>'

• A Stratum cluster endpoint.

. Returns every PCI function on the host — GPUs, accelerators, NICs, storage and USB controllers, audio functions and bridges — with its IDs, class, bound driver, IOMMU group, NUMA node, and SR-IOV capacity where the function has it.

Bridges are included so a consumer can see the whole tree (which root port a card hangs off, what shares its IOMMU group); a console that only wants the cards filters on category.

A display device carries bootVga. true marks the display the firmware and host console drive — a workstation’s only card, or a server BMC’s VGA — which is NOT a GPU for guests; capability.gpu.present on the node counts only display devices with bootVga: false.

Read-only, collected by each node for itself on the same refresh pass as the disk/NIC/DIMM/thermal inventory, by reading /sys/bus/pci/devices. Vendor and device names come from the host’s pci.ids when it has one. Cedar action compute:DescribeNode. Platform-tenant.

Authorizations

• bearerAuth

Parameters

Path Parameters

nodeId

required

string

/^n-[a-z0-9-]+$/

Responses

200

The node’s PCI functions, in bus-address order.

Media typeapplication/json

object

items

required

Array<object>

One PCI function on a node, read from /sys/bus/pci/devices.

Multi-function cards appear once per function: a GPU and its HDMI audio are two entries at .0 and .1 of the same slot, and usually share an IOMMU group, which means they can only be passed through together.

object

address

required

PCI address, domain:bus:device.function. Stable for as long as the card stays in its slot.

string

vendorId

required

16-bit vendor ID, four lowercase hex digits, no 0x.

string

/^[0-9a-f]{4}$/

deviceId

required

16-bit device ID, four lowercase hex digits, no 0x.

string

/^[0-9a-f]{4}$/

classCode

required

24-bit class / subclass / programming interface, six lowercase hex digits. 030000 is a VGA-compatible controller.

string

/^[0-9a-f]{6}$/

category

required

Derived from classCode.

• gpu — display controller, class 03 (VGA, XGA, 3D). Includes the host’s own console display; see bootVga.
• accelerator — processing accelerator, class 12.
• network — network controller, class 02.
• storage — mass storage controller, class 01 (NVMe, SATA, RAID).
• usb — USB controller, class 0c03.
• audio — audio device, class 0401 or 0403 (a GPU’s HDMI audio lands here).
• bridge — bridge, class 06 (host bridges, root ports, switches).
• other — anything else.

string

Allowed values: gpu accelerator network storage usb audio bridge other

vendorName

required

Vendor name from the host’s pci.ids; empty when unknown.

string

deviceName

required

Device name from the host’s pci.ids; empty when unknown.

string

driver

required

Bound kernel driver; empty when none is bound. vfio-pci means the function is held for passthrough.

string

iommuGroup

required

IOMMU group number; empty when the IOMMU is off or the function has no group. Functions sharing a group can only be passed through together.

string

numaNode

required

NUMA node the device is attached to; -1 when the platform does not say.

integer

bootVga

Present on display devices (category: gpu) only. true is the display the firmware and host console drive — a workstation’s only card or a server BMC’s VGA — and is not a GPU for guests. false is a display device that is not the console; the node’s capability.gpu.present is true exactly when at least one of these exists.

boolean

sriovTotalVfs

Virtual functions this physical function supports. Absent when the function is not SR-IOV capable.

integer

sriovNumVfs

Virtual functions currently created. Absent when the function is not SR-IOV capable.

integer

Example

{
  "items": [
    {
      "address": "0000:07:00.0",
      "vendorId": "10de",
      "deviceId": "128b",
      "classCode": "030000",
      "category": "gpu",
      "vendorName": "NVIDIA Corporation",
      "deviceName": "GK208B [GeForce GT 710]",
      "driver": "nouveau",
      "iommuGroup": "14",
      "numaNode": -1
    }
  ]
}

404

Resource not found.

Media typeapplication/problem+json

object

type

required

string format: uri

title

required

string

status

required

integer

>= 400 <= 599

detail

string

instance

string format: uri-reference

requestId

required

string

code

required

string

issues

The findings of a rejected IAM policy document (custom and resource policies).

Array<object>

One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.

object

code

required

The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.

string

statement

required

Index of the statement at fault; -1 for the document as a whole.

integer

>= -1

detail

required

string

action

The offending action, where one is at fault (ACTION_NOT_APPLICABLE).

string

errors

Field errors, for codes that carry them: each problem at its field (see FieldError). Documented on the responses that set it, e.g. approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED. Absent otherwise.

Array<object>

One field’s problem, the stage-2 installer API’s shape. field is the field’s path, message what is wrong with it.

object

field

required

The field’s path, e.g. links[0].interface, disks[1].confirm, mgmt.address or role; empty for the whole request.

string

message

required

string

details

Structured facts about the refusal, for codes that carry them. The shape is fixed per code and documented on the response that answers it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and IMAGE_IN_USE. Absent for codes that carry none.

object

key

additional properties

any

Example

{
  "issues": [
    {
      "code": "ACTION_NOT_APPLICABLE",
      "action": "compute:CreateVpc"
    }
  ]
}