Update Device Controls

PATCH /clients/{client_id}/devices/{device_id}

Updates a single device's collection controls (collection state and log shipping). All fields are optional -- only include fields you want to change.

Path Parameters

Parameter	Type	Description
client_id	string (uuid)	Unique identifier for the client organization
device_id	string (uuid)	Unique identifier for the device

Request Body

Field	Type	Required	Description
collection_state	string	No	New collection state: enabled, disabled, deleted
log_shipping_enabled	boolean	No	Whether to enable full log shipping for this device

Business Rules

• deleted is irreversible -- transitions FROM deleted to any other state are rejected (400).
• If the client's collection_mode is deleted, all device control changes are rejected (400).
• No-op if the values are already the requested state (returns 200, no audit entry created).
• All changes are recorded in the Collection Control Audit Log.
• Returns the updated Device object including the recomputed effective_mode.

Response

Returns the updated Device object with status 200 OK.

Example Request

curl -X PATCH "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/devices/f1e2d3c4-b5a6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "collection_state": "disabled",
    "log_shipping_enabled": true
  }'

Error Responses

Status	Description
400	Invalid transition (e.g. FROM deleted, or device under a deleted client)
401	Authentication required
403	Insufficient permissions for this client
404	Device or client not found
500	Server error

Example error -- transition from deleted

{
  "error": {
    "code": "invalid_transition",
    "message": "Cannot transition from deleted to another collection state",
    "details": {
      "device_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
      "current_state": "deleted",
      "requested_state": "enabled"
    }
  }
}

Example error -- client is deleted

{
  "error": {
    "code": "client_deleted",
    "message": "Cannot modify device controls for a deleted client",
    "details": {
      "client_id": "aa7cf840-9ca9-46a3-9778-9015d6580d50"
    }
  }
}

Related Endpoints

• Get Device - View current device state
• Bulk Enable Devices - Enable collection on multiple devices
• Bulk Disable Devices - Disable collection on multiple devices
• Bulk Delete Devices - Mark multiple devices as deleted
• Collection Control Audit Log - Audit trail of all collection control changes