/admin/device: Create or update a device.

POST /admin/device

What

Registers a device with the Shigoto Hub so that it can be paired to a location, or updates a device that is already known. The serialId is the key: if the account already owns a device with that serial id, it is updated, otherwise a new one is created. The response tells you which of the two happened (created).

Use this endpoint whenever a device is not (or not yet) reported by a Shigoto Sensor — for example a Wi-Fi access point that should mark a whole office area, or a docking station you want to register up front, before anybody has sat down at that desk.

Pairing is a separate step. This endpoint never assigns a location: a newly created device starts out unpaired, and an update leaves an existing pairing untouched. To attach the device to a location, call POST /admin/pair afterwards with the same serialId in deviceSerialIDs. To detach it again, call GET /admin/unpairDevice.

A device is only written to the database once it is paired to a location. Until then it exists in the Hub's memory only and is discarded when the server restarts — so create and pair in one go rather than leaving devices lying around unpaired.

Device types

Value	Name	Meaning
2	Monitor	A display, identified through its EDID. Identifies a single workstation.
4	Usb	A USB device, typically a docking station. Identifies a single workstation.
8	NIC	A network adapter of the machine itself. Identifies the machine, not a place.
16	Router	The default gateway of the network. Identifies an area (a floor, an office).
32	Wifi	A Wi-Fi access point, identified through its BSSID. Identifies an area.

The values are flags of the same enum the sensor reports (1 = Undefined is reserved for devices whose type could not be determined and should not be used here). Monitor, Usb and NIC pin down a concrete workstation; Router and Wifi cover an area and are the right choice for pseudo locations such as "Wi-Fi in the Munich office".

How the serial id is built

A serial id is always three fields joined by semicolons: <manufacturer>;<serial>;<productCode>. Devices created here must use exactly the same layout the sensor uses, otherwise the sensor's report and your entry describe two different devices and nothing is ever recognised. The value is matched literally — case, separators and padding all matter.

Type	Layout	Example
2 Monitor	`<EDID vendor id, 3 letters>;<EDID serial>;<EDID product code, 4 hex digits>`	`DEL;J8N4P2A;A1C0`
4 Usb	`<USB vendor id, 4 hex digits>;<USB serial>;<USB product id, decimal>`	`17EF;8SSF1234;12354`
8 NIC	`Ethernet;<MAC>;NIC` or `WLAN;<MAC>;NIC`	`Ethernet;a4:bb:6d:1f:0e:22;NIC`
16 Router	`Network;<MAC of the gateway>;Gateway`	`Network;ac:84:c6:11:22:33;Gateway`
32 Wifi	`Network;<BSSID>;WiFi`	`Network;ac:84:c6:11:22:33;WiFi`

MAC addresses and BSSIDs are written in lowercase hexadecimal, colon separated, with a leading zero per byte (0e, not e). Hex digits in the monitor and USB fields are uppercase; the USB product id, in contrast, is decimal.

For Wi-Fi the sensor additionally reports the SSID as the device name and the frequency band as its info ("CubeFour", "5 GHz"). Use the same convention for devices you register yourself so that the lists in the sensor and the admin panel stay consistent.

Never guess: read the value back from a sensor that already sees the device. GET /admin/getDevicesForLocations returns the serial ids exactly as the Hub stores them, and that is the string this endpoint expects.

Who

Account administrators of the account (and higher).

Login

Minimal Example /admin/device

{
	"serialId": "Network;ac:84:c6:11:22:33;WiFi",
	"deviceType": 32,
	"name": "CubeFour",
	"info": "5 GHz"
}

Request

Responses

Device created or updated.

/admin/device: Create or update a device.

/admin/device

Request​

Responses​

Request

Responses