NetAlertX/docs/API_DEVICE.md

Device API Endpoints

Manage a single device by its MAC address. Operations include retrieval, updates, deletion, resetting properties, and copying data between devices. All endpoints require authorization via Bearer token.

---

1. Retrieve Device Details

• GET /device/<mac> Fetch all details for a single device, including:

• Computed status (devStatus) → On-line, Off-line, or Down

• Session and event counts (devSessions, devEvents, devDownAlerts)

• Presence hours (devPresenceHours)

• Children devices (devChildrenDynamic) and NIC children (devChildrenNicsDynamic)

Special case: mac=new returns a template for a new device with default values.

Response (success):

{
  "devMac": "AA:BB:CC:DD:EE:FF",
  "devName": "Net - Huawei",
  "devOwner": "Admin",
  "devType": "Router",
  "devVendor": "Huawei",
  "devStatus": "On-line",
  "devSessions": 12,
  "devEvents": 5,
  "devDownAlerts": 1,
  "devPresenceHours": 32,
  "devChildrenDynamic": [...],
  "devChildrenNicsDynamic": [...],
  ...
}

Error Responses:

• Device not found → HTTP 404
• Unauthorized → HTTP 403

MCP Integration: Available as get_device_info and set_device_alias tools. See MCP Server Bridge API.

---

2. Update Device Fields

• POST /device/<mac> Create or update a device record.

Request Body:

{
  "devName": "New Device",
  "devOwner": "Admin",
  "createNew": true
}

Behavior:

• If createNew=true → creates a new device
• Otherwise → updates existing device fields

Response:

{
  "success": true
}

Error Responses:

• Unauthorized → HTTP 403

---

3. Delete a Device

• DELETE /device/<mac>/delete Deletes the device with the given MAC.

Response:

{
  "success": true
}

Error Responses:

• Unauthorized → HTTP 403

---

4. Delete All Events for a Device

• DELETE /device/<mac>/events/delete Removes all events associated with a device.

Response:

{
  "success": true
}

---

5. Reset Device Properties

• POST /device/<mac>/reset-props Resets the device's custom properties to default values.

Request Body: Optional JSON for additional parameters.

Response:

{
  "success": true
}

---

6. Copy Device Data

• POST /device/copy Copy all data from one device to another. If a device exists with macTo, it is replaced.

Request Body:

{
  "macFrom": "AA:BB:CC:DD:EE:FF",
  "macTo": "11:22:33:44:55:66"
}

Response:

{
  "success": true,
  "message": "Device copied from AA:BB:CC:DD:EE:FF to 11:22:33:44:55:66"
}

Error Responses:

• Missing macFrom or macTo → HTTP 400
• Unauthorized → HTTP 403

---

7. Update a Single Column

• POST /device/<mac>/update-column Update one specific column for a device.

Allowed columnName values: devName, devOwner, devType, devVendor, devGroup, devLocation, devComments, devIcon, devFavorite, devAlertEvents, devAlertDown, devCanSleep, devSkipRepeated, devReqNicsOnline, devForceStatus, devParentMAC, devParentPort, devParentRelType, devSSID, devSite, devVlan, devStaticIP, devIsNew, devIsArchived, devCustomProps.

Request Body:

{
  "columnName": "devName",
  "columnValue": "Updated Device Name"
}

Response (success):

{
  "success": true
}

Error Responses:

• Device not found → HTTP 404
• Missing columnName or columnValue → HTTP 400
• Unauthorized → HTTP 403

---

8. Lock / Unlock a Device Field

• POST /device/<mac>/field/lock Lock a field to prevent plugin overwrites, or unlock it to allow overwrites again.

Request Body:

{
  "fieldName": "devName",
  "lock": true
}

Field	Type	Required	Description
fieldName	string	✅	Field to lock/unlock (e.g. devName, devVendor)
lock	boolean	❌	true to lock (default), false to unlock

Response (success):

{
  "success": true,
  "fieldName": "devName",
  "locked": true,
  "message": "Field devName locked"
}

Error Responses:

• Field does not support locking → HTTP 400
• Unauthorized → HTTP 403

---

9. Unlock / Clear Device Fields (Bulk)

• POST /devices/fields/unlock Unlock fields (clear LOCKED/USER sources) for one device, a list of devices, or all devices.

Request Body:

{
  "mac": "AA:BB:CC:DD:EE:FF",
  "fields": ["devName", "devVendor"],
  "clearAll": false
}

Field	Type	Required	Description
mac	string or array	❌	Single MAC, list of MACs, or omit for all devices
fields	array of strings	❌	Fields to unlock. Omit to unlock all tracked fields
clearAll	boolean	❌	true clears all sources; false (default) clears only LOCKED/USER

Response (success):

{
  "success": true
}

Error Responses:

• fields is not a list → HTTP 400
• Unauthorized → HTTP 403

---

10. Set Device Alias

• POST /device/<mac>/set-alias Convenience wrapper to update the device display name (devName).

Request Body:

{
  "alias": "My Router"
}

Response (success):

{
  "success": true
}

Error Responses:

• Missing alias → HTTP 400
• Device not found → HTTP 404
• Unauthorized → HTTP 403

---

Example curl Requests

Get Device Details:

curl -X GET "http://<server_ip>:<GRAPHQL_PORT>/device/AA:BB:CC:DD:EE:FF" \
  -H "Authorization: Bearer <API_TOKEN>"

Update Device Fields:

curl -X POST "http://<server_ip>:<GRAPHQL_PORT>/device/AA:BB:CC:DD:EE:FF" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  --data '{"devName": "New Device Name"}'

Delete Device:

curl -X DELETE "http://<server_ip>:<GRAPHQL_PORT>/device/AA:BB:CC:DD:EE:FF/delete" \
  -H "Authorization: Bearer <API_TOKEN>"

Copy Device Data:

curl -X POST "http://<server_ip>:<GRAPHQL_PORT>/device/copy" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  --data '{"macFrom":"AA:BB:CC:DD:EE:FF","macTo":"11:22:33:44:55:66"}'

Update Single Column:

curl -X POST "http://<server_ip>:<GRAPHQL_PORT>/device/AA:BB:CC:DD:EE:FF/update-column" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  --data '{"columnName":"devName","columnValue":"Updated Device"}'

Lock a Field:

curl -X POST "http://<server_ip>:<GRAPHQL_PORT>/device/AA:BB:CC:DD:EE:FF/field/lock" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  --data '{"fieldName":"devName","lock":true}'

Unlock Fields (all devices):

curl -X POST "http://<server_ip>:<GRAPHQL_PORT>/devices/fields/unlock" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  --data '{"fields":["devName","devVendor"]}'

Set Device Alias:

curl -X POST "http://<server_ip>:<GRAPHQL_PORT>/device/AA:BB:CC:DD:EE:FF/set-alias" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  --data '{"alias":"My Router"}'