Groups Api Update Group

Groups Api Update Group
Update a Security Group

When agentDisabledStatus changes, the Group's active agents are sent the disable or enable command after the change commits, in the background; the response does not wait for them. Requires the ADMIN or SECURITY_OPERATOR role. Only ADMIN may send agentDisabledStatus true.

Request
URI
PUT
https://{api_host}/api/v1/groups/{id}
COPY
Path Parameters
integer
id
Required  

Security Group id

id example
1

Request Body

The Security Group fields to change. A field that is left out keeps its stored value.

UpdateGroupRequest of type(s) application/json
Required  
{
    "name": "Production Servers",
    "description": "Hosts that run production workloads",
    "heartbeatIntervalSeconds": 120,
    "enforcementMode": "ENFORCE",
    "agentDisabledStatus": false
}
string
name
Optional
Constraints: minLength: 1 maxLength: 255

Same character and uniqueness rules as create; an unchanged name is not re-checked for characters

string
description
Optional
Constraints: maxLength: 2000

Replaces the description, trimmed with the same 2,000-character limit as on create. Absent or null leaves the description unchanged

integer As int32 As int32
heartbeatIntervalSeconds
Optional
Constraints: minimum: 30 maximum: 300

New seconds between agent heartbeats, from 30 to 300 inclusive; any other value is INVALID_HEARTBEAT_INTERVAL. Absent or null leaves the interval unchanged

string
enforcementMode
Optional

A Group's own enforcement posture, passed to its agents unchanged.

  • ENFORCE: The Group's agents are sent the enforcement mode MODE_ENFORCE; the mode of a new Group when none is given
  • MONITOR: The Group's agents are sent the enforcement mode MODE_MONITOR
Enumeration: ENFORCE, MONITOR
boolean
agentDisabledStatus
Optional

Changing it sends the disable or enable command to the Group's active agents after the change commits, in the background. Only ADMIN may send true.

Authentication
This operation uses the following authentication methods.
Responses
200

200 OK successful response envelope. The updated Security Group

Returns SecurityGroupDto of type(s) application/json
{
    "securityGroupId": 1,
    "name": "Production Servers",
    "description": "Hosts that run production workloads",
    "isDefault": false,
    "heartbeatIntervalSeconds": 120,
    "enforcementMode": "ENFORCE",
    "agentDisabledStatus": false,
    "policyVersion": 3,
    "hasPendingChanges": true,
    "hypervisorCount": 2,
    "policyCount": 2,
    "createdBy": 1,
    "createdByUsername": "alice.example",
    "updatedBy": 2,
    "updatedByUsername": "bob.example",
    "createdAt": "2026-01-02T09:00:00Z",
    "updatedAt": "2026-01-15T09:20:00Z"
}
integer As int64 As int64
securityGroupId
Required  

Identifier of the Group, assigned by the server when the Group is created

string
name
Required  

Group name, stored trimmed, at most 255 characters, and different from every other Group's name ignoring case. The Default Group cannot be renamed

string
description
Optional

Free text, stored trimmed, at most 2,000 characters; a whitespace-only text is stored as an empty string. Null when none was given

boolean
isDefault
Required  

True for the seeded Default Group, which cannot be deleted or renamed and whose Agent Protection cannot be disabled

integer As int32 As int32
heartbeatIntervalSeconds
Required  

Agent heartbeat interval in seconds (30-300)

string
enforcementMode
Required  

A Group's own enforcement posture, passed to its agents unchanged.

  • ENFORCE: The Group's agents are sent the enforcement mode MODE_ENFORCE; the mode of a new Group when none is given
  • MONITOR: The Group's agents are sent the enforcement mode MODE_MONITOR
Enumeration: ENFORCE, MONITOR
boolean
agentDisabledStatus
Required  

Circuit breaker: true unhooks every agent in this Group and stops rule evaluation without uninstalling. Default false (protection enabled).

integer As int64 As int64
policyVersion
Required  

Version of the Group's live published bundle

boolean
hasPendingChanges
Required  

True after a change a Group publish would send (attaching or detaching a Policy, changing a stack rank, syncing Policies, or publishing a Policy attached to the Group) until the Group is published. It is also cleared when the Group has been published before and a check finds nothing differing from what was last published; the Group's pending changes give the exact comparison

integer As int64 As int64
hypervisorCount
Required  

Number of active Hypervisors currently assigned to this Group

integer As int64 As int64
policyCount
Required  

Number of Policies currently attached to this Group

integer As int64 As int64
createdBy
Optional

Id of the creating user. Absent for the seeded Default Group and system-created Groups.

string
createdByUsername
Optional

Username of createdBy; absent when createdBy is absent or the user no longer exists

integer As int64 As int64
updatedBy
Optional

Id of the user who last updated the Group; absent when never updated by a user

string
updatedByUsername
Optional

Username of updatedBy; absent when updatedBy is absent or the user no longer exists

string As date-time As date-time
createdAt
Required  

When the Group was created, as an ISO 8601 date-time with offset; never changes

string As date-time As date-time
updatedAt
Required  

When the Group was last updated, as an ISO 8601 date-time with offset


400

400 Bad Request: INVALID_GROUP_NAME, DUPLICATE_GROUP_NAME, INVALID_HEARTBEAT_INTERVAL or MALFORMED_REQUEST

Returns ApiErrorResponse of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


401

401 Unauthorized: UNAUTHENTICATED when the VTP_SESSION cookie is missing, unknown, expired or revoked

Returns Unauthenticated of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


403

403 Forbidden: FORBIDDEN or CSRF_ERROR. CSRF_ERROR when the X-XSRF-TOKEN header is missing or wrong on a POST, PUT, PATCH or DELETE (only POST /api/v1/auth/login is exempt, and a request without a valid session gets 401 UNAUTHENTICATED instead); PASSWORD_CHANGE_REQUIRED when the account must change its password first (only GET /api/v1/auth/session, POST /api/v1/auth/logout and POST /api/v1/auth/change-password are exempt); LICENSE_REQUIRED or LICENSE_EXPIRED while the license pool is restricted (no license, or expired past grace) (exempt: every route under /api/v1/auth, GET /api/v1/user/preferences, GET /api/v1/licensing/summary and POST /api/v1/licensing/licenses)

Returns ApiErrorResponse of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


404

404 Not Found: SECURITY_GROUP_NOT_FOUND

Returns ApiErrorResponse of type(s) application/json
"ApiErrorResponse Object"
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


409

409 Conflict: DEFAULT_GROUP_NAME_LOCKED when the update changes the name of the Default Group, or DEFAULT_GROUP_PROTECTION_LOCKED when it sets agentDisabledStatus to true on the Default Group

Returns ApiErrorResponse of type(s) application/json
"ApiErrorResponse Object"
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


Code Samples
COPY
                    curl -X PUT -H 'Authorization: <value>' -H 'Content-Type: application/json' -d '{}' https://{api_host}/api/v1/groups/{id}