Groups Api Create Group
Also creates the mandatory empty published snapshot at policyVersion 1, atomically. Requires the ADMIN or SECURITY_OPERATOR role. Only ADMIN may send agentDisabledStatus true.
The new Security Group. name is required; description, heartbeatIntervalSeconds, enforcementMode and agentDisabledStatus are optional, and only an ADMIN may send agentDisabledStatus true.
Show optional properties
{
"name": "string"
}
{
"name": "Staging Servers",
"description": "Pre-production test hosts",
"heartbeatIntervalSeconds": 300,
"enforcementMode": "ENFORCE",
"agentDisabledStatus": false
}
Trimmed; letters, digits, space and - _ . : ( ) only (INVALID_GROUP_NAME). Unique ignoring case (DUPLICATE_GROUP_NAME).
Optional free text. It is trimmed; longer than 2,000 characters after trimming is INVALID_DESCRIPTION. Absent or null stores no description
Seconds between agent heartbeats, from 30 to 300 inclusive; any other value is INVALID_HEARTBEAT_INTERVAL. Absent keeps the default of 300
Defaults to ENFORCE when omitted
Defaults to false when omitted. Only ADMIN may send true (403 FORBIDDEN otherwise).
201 Created successful response envelope. The created Security Group
{
"securityGroupId": 2,
"name": "Staging Servers",
"description": "Pre-production test hosts",
"isDefault": false,
"heartbeatIntervalSeconds": 300,
"enforcementMode": "ENFORCE",
"agentDisabledStatus": false,
"policyVersion": 1,
"hasPendingChanges": false,
"hypervisorCount": 0,
"policyCount": 0,
"createdBy": 1,
"createdByUsername": "alice.example",
"updatedBy": 1,
"updatedByUsername": "alice.example",
"createdAt": "2026-01-03T09:00:00Z",
"updatedAt": "2026-01-03T09:00:00Z"
}
Identifier of the Group, assigned by the server when the Group is created
Group name, stored trimmed, at most 255 characters, and different from every other Group's name ignoring case. The Default Group cannot be renamed
Free text, stored trimmed, at most 2,000 characters; a whitespace-only text is stored as an empty string. Null when none was given
True for the seeded Default Group, which cannot be deleted or renamed and whose Agent Protection cannot be disabled
Agent heartbeat interval in seconds (30-300)
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 givenMONITOR: The Group's agents are sent the enforcement mode MODE_MONITOR
Circuit breaker: true unhooks every agent in this Group and stops rule evaluation without uninstalling. Default false (protection enabled).
Version of the Group's live published bundle
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
Number of active Hypervisors currently assigned to this Group
Number of Policies currently attached to this Group
Id of the creating user. Absent for the seeded Default Group and system-created Groups.
Username of createdBy; absent when createdBy is absent or the user no longer exists
Id of the user who last updated the Group; absent when never updated by a user
Username of updatedBy; absent when updatedBy is absent or the user no longer exists
When the Group was created, as an ISO 8601 date-time with offset; never changes
When the Group was last updated, as an ISO 8601 date-time with offset
400 Bad Request: INVALID_GROUP_NAME, DUPLICATE_GROUP_NAME, INVALID_HEARTBEAT_INTERVAL or MALFORMED_REQUEST
{
"errorCode": "string",
"message": "string",
"path": "string",
"timestamp": "string",
"reason": "string"
}
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.
Human-readable error description
Request URI path that produced the error
Timestamp when the error occurred as an ISO 8601 date-time with offset
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 Unauthorized: UNAUTHENTICATED when the VTP_SESSION cookie is missing, unknown, expired or revoked
{
"errorCode": "string",
"message": "string",
"path": "string",
"timestamp": "string",
"reason": "string"
}
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.
Human-readable error description
Request URI path that produced the error
Timestamp when the error occurred as an ISO 8601 date-time with offset
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 Forbidden: FORBIDDEN, including a SECURITY_OPERATOR sending agentDisabledStatus true, 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)
{
"errorCode": "string",
"message": "string",
"path": "string",
"timestamp": "string",
"reason": "string"
}
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.
Human-readable error description
Request URI path that produced the error
Timestamp when the error occurred as an ISO 8601 date-time with offset
A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.
curl -X POST -H 'Authorization: <value>' -H 'Content-Type: application/json' -d '{"name":"string"}' https://{api_host}/api/v1/groups