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.

⚠️ Full-replace (PUT) semantics. Every editable field is written on each call. Any field omitted from the payload is reset to its default (empty string or 0). This matches how the frontend edit form works — it always sends the complete device state.

To update a single field without affecting others, use POST /device/<mac>/update-column instead.

Request Body:

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

Behavior:

• If createNew=true → inserts a new device row
• Otherwise → replaces all editable fields on the existing device

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 exactly one field for a device without touching any other fields.

✅ Partial-update (PATCH) semantics. Only the specified column is written. All other fields are left unchanged. Use this for automation, integrations, and any workflow that needs to update a single attribute.

To replace all fields at once (e.g. saving from the edit form), use POST /device/<mac>.

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"}'