Update Client

PATCH /clients/{client_id}

Updates client-level settings. Currently supports changing the agent data collection_mode. 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

Request Body

Field	Type	Required	Description
collection_mode	string	No	New collection mode: discovery, saas_usage, disabled, deleted

Collection Mode Values

Mode	Description
discovery	Agent collects device info and installed software only -- no app usage or browsing telemetry
saas_usage	Full data collection (default)
disabled	All collection stopped; agents send lightweight heartbeats to poll for config changes
deleted	Permanent teardown -- agents self-uninstall. Irreversible.

Business Rules

• Transitions between discovery, saas_usage, and disabled are allowed freely.
• Transition to deleted is irreversible -- once set, the client cannot be moved back to any other mode.
• No-op if the mode is already the requested value (returns 200, no audit entry created).
• All mode changes are recorded in the Collection Control Audit Log.

Response

Returns the updated Client object with status 200 OK.

Example Request

curl -X PATCH "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "collection_mode": "disabled"
  }'

Example Response

{
  "id": "aa7cf840-9ca9-46a3-9778-9015d6580d50",
  "name": "Acme Corporation",
  "status": "active",
  "collection_mode": "disabled",
  "partner": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "name": "TechPartner Inc."
  },
  "enrollment_token": {
    "id": "e1f2a3b4-c5d6-7890-abcd-ef1234567890",
    "value": "enroll_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    "description": "Default enrollment token",
    "site_id": null,
    "status": "active",
    "max_uses": null,
    "remaining_uses": null,
    "expires_at": null,
    "created_at": "2026-01-15T10:00:00.000Z"
  },
  "created_at": "2025-06-01T00:00:00.000Z",
  "updated_at": "2026-03-10T14:30:00.000Z"
}

Error Responses

Status	Description
400	Invalid request (e.g. transitioning FROM deleted to another mode)
401	Authentication required
403	Insufficient permissions for this client
404	Client not found
500	Server error

Example error -- transition from deleted

{
  "error": {
    "code": "invalid_transition",
    "message": "Cannot transition from deleted to another collection mode",
    "details": {
      "current_mode": "deleted",
      "requested_mode": "saas_usage"
    }
  }
}

Related Endpoints

• Get Client - View current client state
• Collection Control Audit Log - Audit trail of all collection control changes