---
title: "Register a device for passthrough"
method: POST
path: "/devices"
---

# Register a device for passthrough

`POST /devices`

## Request body

- CreateDeviceRequest
  - `name` string — Optional globally unique device name. If not provided, a name is auto-generated from the PCI address (e.g., "pci-0000-a2-00-0")
  - `pci_address` string, required — PCI address of the device (required, e.g., "0000:a2:00.0")
  - `tags` Tags — User-defined key-value tags.

## Response `201`

Device registered

- Device
  - `id` string, required — Auto-generated unique identifier (CUID2 format)
  - `name` string — Device name (user-provided or auto-generated from PCI address)
  - `type` 'gpu' | 'pci', required — Type of PCI device
  - `tags` Tags — User-defined key-value tags.
  - `pci_address` string, required — PCI address
  - `vendor_id` string, required — PCI vendor ID (hex)
  - `device_id` string, required — PCI device ID (hex)
  - `iommu_group` integer, required — IOMMU group number
  - `bound_to_vfio` boolean, required — Whether the device is currently bound to the vfio-pci driver, which is required for VM passthrough. - true: Device is bound to vfio-pci and ready for (or currently in use by) a VM. The device's native driver has been unloaded. - false: Device is using its native driver (e.g., nvidia) or no driver. Hypeman will automatically bind to vfio-pci when attaching to an instance.
  - `attached_to` string, nullable — Instance ID if attached
  - `created_at` string, date-time, required — Registration timestamp (RFC3339)

## Other responses

- `400` — Bad request (invalid name or PCI address)
- `401` — Unauthorized
- `404` — PCI device not found on host
- `409` — Conflict - device or name already registered
- `500` — Internal server error

---

[API](https://skmtc.net/kernel/apis/hypeman-api.md) · [All operations](https://skmtc.net/kernel/apis/hypeman-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/kernel/hypeman-api/versions/b4642bb950dc/schema)