> For the complete documentation index, see [llms.txt](https://docs.zenlytic.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zenlytic.com/developers-beta/api-reference/admin/groups.md).

# Groups

## Get Group User Attributes

> List the user attribute values set on a group.\
> \
> These apply to every member of the group. When a member is in several groups that set the\
> same attribute, the group with the highest \`\`user\_attribute\_precedence\`\` wins.\
> \
> \`\`source\`\` is always \`\`"group"\`\` and \`\`source\_id\`\` always matches this group's ID here —\
> both only vary on the member user attributes endpoint, where a value can come from any of a\
> member's groups or be set directly on the member.

```json
{"openapi":"3.1.0","info":{"title":"FastAPI","version":"2.0.0"},"tags":[{"name":"Groups"}],"servers":[{"url":"https://api-external.zenlytic.com/api/v2","description":"US"},{"url":"https://euapi-external.zenlytic.com/api/v2","description":"EU"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","description":"A Personal Access Token (PAT).","scheme":"bearer"}},"schemas":{"ApiV2CollectionResponse_UserAttributeSchema_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/UserAttributeSchema"},"type":"array","title":"Data"},"meta":{"$ref":"#/components/schemas/MetaSchema"}},"type":"object","required":["data","meta"],"title":"ApiV2CollectionResponse[UserAttributeSchema]"},"UserAttributeSchema":{"properties":{"id":{"type":"string","title":"Id"},"user_attribute_definition_id":{"type":"string","title":"User Attribute Definition Id"},"value":{"type":"string","title":"Value","description":"Formatted per `data_type`: \"string\" allows free text, \"number\" requires a parseable number, \"date\" requires `YYYY-MM-DD`."},"data_type":{"$ref":"#/components/schemas/UserAttributeDataType","description":"Determines `value`'s format: \"string\" allows free text, \"number\" requires a parseable number, \"date\" requires `YYYY-MM-DD`."},"name":{"type":"string","title":"Name","description":"The referenced `user_attribute_definition_id`'s `name`."},"source":{"$ref":"#/components/schemas/UserAttributeSource","description":"Whether this value is set directly on the member (\"user\") or inherited from a group (\"group\")."},"source_id":{"type":"string","title":"Source Id","description":"ID of the group or member (matching `source`) this value comes from."},"user_attribute_precedence":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"User Attribute Precedence","description":"The source group's precedence; null when `source` is \"user\" - only groups carry a precedence."},"is_overridden":{"type":"boolean","title":"Is Overridden","description":"True if a higher-precedence group value, or a directly-set member value, takes effect instead of this one."}},"type":"object","required":["id","user_attribute_definition_id","value","data_type","name","source","source_id","user_attribute_precedence","is_overridden"],"title":"UserAttributeSchema"},"UserAttributeDataType":{"type":"string","enum":["string","number","date"],"title":"UserAttributeDataType"},"UserAttributeSource":{"type":"string","enum":["user","group"],"title":"UserAttributeSource"},"MetaSchema":{"properties":{"status":{"$ref":"#/components/schemas/ResponseStatus"},"errors":{"items":{"$ref":"#/components/schemas/ErrorSchema"},"type":"array","title":"Errors","description":"Non-empty exactly when `status` is \"error\"."},"warnings":{"items":{"$ref":"#/components/schemas/WarningSchema"},"type":"array","title":"Warnings","description":"Can be non-empty even when `status` is \"success\" - a non-fatal issue with an otherwise-successful request."},"request_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Request Source","description":"Which auth mechanism served this request (e.g. \"api_key\", \"pat\"); null when not tracked for this endpoint."}},"type":"object","required":["status"],"title":"MetaSchema"},"ResponseStatus":{"type":"string","enum":["success","error"],"title":"ResponseStatus"},"ErrorSchema":{"properties":{"message":{"type":"string","title":"Message"},"status_code":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Status Code","description":"Matches this response's actual HTTP status code."},"occurred_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Occurred At","description":"ISO 8601 UTC timestamp."},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Code","description":"Machine-readable code for errors that need special handling (e.g. \"SSO_REQUIRED\") rather than being shown generically; null for most errors."},"error_metadata":{"anyOf":[{"$ref":"#/components/schemas/BaseErrorMetadata"},{"type":"null"}],"description":"Additional structured detail for specific error conditions; usually null."}},"type":"object","required":["message"],"title":"ErrorSchema"},"BaseErrorMetadata":{"properties":{},"type":"object","title":"BaseErrorMetadata"},"WarningSchema":{"properties":{"message":{"type":"string","title":"Message"}},"type":"object","required":["message"],"title":"WarningSchema"},"ApiV2ErrorResponse":{"properties":{"meta":{"$ref":"#/components/schemas/MetaSchema"}},"type":"object","required":["meta"],"title":"ApiV2ErrorResponse"}}},"paths":{"/workspaces/{workspace_id}/groups/{group_id}/user_attributes":{"get":{"tags":["Groups"],"summary":"Get Group User Attributes","description":"List the user attribute values set on a group.\n\nThese apply to every member of the group. When a member is in several groups that set the\nsame attribute, the group with the highest ``user_attribute_precedence`` wins.\n\n``source`` is always ``\"group\"`` and ``source_id`` always matches this group's ID here —\nboth only vary on the member user attributes endpoint, where a value can come from any of a\nmember's groups or be set directly on the member.","operationId":"get_group_user_attributes_workspaces__workspace_id__groups__group_id__user_attributes_get","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","title":"Workspace Id"}},{"name":"group_id","in":"path","required":true,"schema":{"type":"string","title":"Group Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiV2CollectionResponse_UserAttributeSchema_"}}}},"4XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiV2ErrorResponse"}}},"description":"Client Error"},"5XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiV2ErrorResponse"}}},"description":"Server Error"}}}}}}
```

## Create Group User Attribute

> Set a user attribute value on a group.\
> \
> \`\`user\_attribute\_definition\_id\`\` must reference an existing definition in the workspace. A\
> group can only set each definition once; a second value for the same definition returns\
> 409 — patch the existing value instead.\
> \
> \`\`value\`\` must match the definition's \`\`data\_type\`\`: \`\`YYYY-MM-DD\`\` for \`\`date\`\`, a numeric\
> string for \`\`number\`\`.

```json
{"openapi":"3.1.0","info":{"title":"FastAPI","version":"2.0.0"},"tags":[{"name":"Groups"}],"servers":[{"url":"https://api-external.zenlytic.com/api/v2","description":"US"},{"url":"https://euapi-external.zenlytic.com/api/v2","description":"EU"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","description":"A Personal Access Token (PAT).","scheme":"bearer"}},"schemas":{"CreateUserAttributeSchema":{"properties":{"user_attribute_definition_id":{"type":"string","title":"User Attribute Definition Id","description":"ID of an existing definition in this workspace - see `GET .../user_attribute_definitions`."},"value":{"type":"string","title":"Value","description":"Must match the referenced definition's `data_type` format: \"string\" allows free text, \"number\" requires a parseable number, \"date\" requires `YYYY-MM-DD`."}},"type":"object","required":["user_attribute_definition_id","value"],"title":"CreateUserAttributeSchema"},"ApiV2Response_UserAttributeSchema_":{"properties":{"data":{"$ref":"#/components/schemas/UserAttributeSchema"},"meta":{"$ref":"#/components/schemas/MetaSchema"}},"type":"object","required":["data","meta"],"title":"ApiV2Response[UserAttributeSchema]"},"UserAttributeSchema":{"properties":{"id":{"type":"string","title":"Id"},"user_attribute_definition_id":{"type":"string","title":"User Attribute Definition Id"},"value":{"type":"string","title":"Value","description":"Formatted per `data_type`: \"string\" allows free text, \"number\" requires a parseable number, \"date\" requires `YYYY-MM-DD`."},"data_type":{"$ref":"#/components/schemas/UserAttributeDataType","description":"Determines `value`'s format: \"string\" allows free text, \"number\" requires a parseable number, \"date\" requires `YYYY-MM-DD`."},"name":{"type":"string","title":"Name","description":"The referenced `user_attribute_definition_id`'s `name`."},"source":{"$ref":"#/components/schemas/UserAttributeSource","description":"Whether this value is set directly on the member (\"user\") or inherited from a group (\"group\")."},"source_id":{"type":"string","title":"Source Id","description":"ID of the group or member (matching `source`) this value comes from."},"user_attribute_precedence":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"User Attribute Precedence","description":"The source group's precedence; null when `source` is \"user\" - only groups carry a precedence."},"is_overridden":{"type":"boolean","title":"Is Overridden","description":"True if a higher-precedence group value, or a directly-set member value, takes effect instead of this one."}},"type":"object","required":["id","user_attribute_definition_id","value","data_type","name","source","source_id","user_attribute_precedence","is_overridden"],"title":"UserAttributeSchema"},"UserAttributeDataType":{"type":"string","enum":["string","number","date"],"title":"UserAttributeDataType"},"UserAttributeSource":{"type":"string","enum":["user","group"],"title":"UserAttributeSource"},"MetaSchema":{"properties":{"status":{"$ref":"#/components/schemas/ResponseStatus"},"errors":{"items":{"$ref":"#/components/schemas/ErrorSchema"},"type":"array","title":"Errors","description":"Non-empty exactly when `status` is \"error\"."},"warnings":{"items":{"$ref":"#/components/schemas/WarningSchema"},"type":"array","title":"Warnings","description":"Can be non-empty even when `status` is \"success\" - a non-fatal issue with an otherwise-successful request."},"request_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Request Source","description":"Which auth mechanism served this request (e.g. \"api_key\", \"pat\"); null when not tracked for this endpoint."}},"type":"object","required":["status"],"title":"MetaSchema"},"ResponseStatus":{"type":"string","enum":["success","error"],"title":"ResponseStatus"},"ErrorSchema":{"properties":{"message":{"type":"string","title":"Message"},"status_code":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Status Code","description":"Matches this response's actual HTTP status code."},"occurred_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Occurred At","description":"ISO 8601 UTC timestamp."},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Code","description":"Machine-readable code for errors that need special handling (e.g. \"SSO_REQUIRED\") rather than being shown generically; null for most errors."},"error_metadata":{"anyOf":[{"$ref":"#/components/schemas/BaseErrorMetadata"},{"type":"null"}],"description":"Additional structured detail for specific error conditions; usually null."}},"type":"object","required":["message"],"title":"ErrorSchema"},"BaseErrorMetadata":{"properties":{},"type":"object","title":"BaseErrorMetadata"},"WarningSchema":{"properties":{"message":{"type":"string","title":"Message"}},"type":"object","required":["message"],"title":"WarningSchema"},"ApiV2ErrorResponse":{"properties":{"meta":{"$ref":"#/components/schemas/MetaSchema"}},"type":"object","required":["meta"],"title":"ApiV2ErrorResponse"}}},"paths":{"/workspaces/{workspace_id}/groups/{group_id}/user_attributes":{"post":{"tags":["Groups"],"summary":"Create Group User Attribute","description":"Set a user attribute value on a group.\n\n``user_attribute_definition_id`` must reference an existing definition in the workspace. A\ngroup can only set each definition once; a second value for the same definition returns\n409 — patch the existing value instead.\n\n``value`` must match the definition's ``data_type``: ``YYYY-MM-DD`` for ``date``, a numeric\nstring for ``number``.","operationId":"create_group_user_attribute_workspaces__workspace_id__groups__group_id__user_attributes_post","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","title":"Workspace Id"}},{"name":"group_id","in":"path","required":true,"schema":{"type":"string","title":"Group Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUserAttributeSchema"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiV2Response_UserAttributeSchema_"}}}},"4XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiV2ErrorResponse"}}},"description":"Client Error"},"5XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiV2ErrorResponse"}}},"description":"Server Error"}}}}}}
```

## Delete Group User Attribute

> Remove a user attribute value from a group.\
> \
> The definition itself is untouched — only this group's value for it is deleted.

```json
{"openapi":"3.1.0","info":{"title":"FastAPI","version":"2.0.0"},"tags":[{"name":"Groups"}],"servers":[{"url":"https://api-external.zenlytic.com/api/v2","description":"US"},{"url":"https://euapi-external.zenlytic.com/api/v2","description":"EU"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","description":"A Personal Access Token (PAT).","scheme":"bearer"}},"schemas":{"ApiV2ErrorResponse":{"properties":{"meta":{"$ref":"#/components/schemas/MetaSchema"}},"type":"object","required":["meta"],"title":"ApiV2ErrorResponse"},"MetaSchema":{"properties":{"status":{"$ref":"#/components/schemas/ResponseStatus"},"errors":{"items":{"$ref":"#/components/schemas/ErrorSchema"},"type":"array","title":"Errors","description":"Non-empty exactly when `status` is \"error\"."},"warnings":{"items":{"$ref":"#/components/schemas/WarningSchema"},"type":"array","title":"Warnings","description":"Can be non-empty even when `status` is \"success\" - a non-fatal issue with an otherwise-successful request."},"request_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Request Source","description":"Which auth mechanism served this request (e.g. \"api_key\", \"pat\"); null when not tracked for this endpoint."}},"type":"object","required":["status"],"title":"MetaSchema"},"ResponseStatus":{"type":"string","enum":["success","error"],"title":"ResponseStatus"},"ErrorSchema":{"properties":{"message":{"type":"string","title":"Message"},"status_code":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Status Code","description":"Matches this response's actual HTTP status code."},"occurred_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Occurred At","description":"ISO 8601 UTC timestamp."},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Code","description":"Machine-readable code for errors that need special handling (e.g. \"SSO_REQUIRED\") rather than being shown generically; null for most errors."},"error_metadata":{"anyOf":[{"$ref":"#/components/schemas/BaseErrorMetadata"},{"type":"null"}],"description":"Additional structured detail for specific error conditions; usually null."}},"type":"object","required":["message"],"title":"ErrorSchema"},"BaseErrorMetadata":{"properties":{},"type":"object","title":"BaseErrorMetadata"},"WarningSchema":{"properties":{"message":{"type":"string","title":"Message"}},"type":"object","required":["message"],"title":"WarningSchema"}}},"paths":{"/workspaces/{workspace_id}/groups/{group_id}/user_attributes/{user_attribute_id}":{"delete":{"tags":["Groups"],"summary":"Delete Group User Attribute","description":"Remove a user attribute value from a group.\n\nThe definition itself is untouched — only this group's value for it is deleted.","operationId":"delete_group_user_attribute_workspaces__workspace_id__groups__group_id__user_attributes__user_attribute_id__delete","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","title":"Workspace Id"}},{"name":"group_id","in":"path","required":true,"schema":{"type":"string","title":"Group Id"}},{"name":"user_attribute_id","in":"path","required":true,"schema":{"type":"string","title":"User Attribute Id"}}],"responses":{"204":{"description":"Successful Response"},"4XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiV2ErrorResponse"}}},"description":"Client Error"},"5XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiV2ErrorResponse"}}},"description":"Server Error"}}}}}}
```

## Update Group User Attribute

> Update the value of a user attribute already set on a group.\
> \
> Only \`\`value\`\` is mutable; to point at a different definition, delete this value and\
> create a new one. \`\`value\`\` must match the existing definition's \`\`data\_type\`\`:\
> \`\`YYYY-MM-DD\`\` for \`\`date\`\`, a numeric string for \`\`number\`\`.

```json
{"openapi":"3.1.0","info":{"title":"FastAPI","version":"2.0.0"},"tags":[{"name":"Groups"}],"servers":[{"url":"https://api-external.zenlytic.com/api/v2","description":"US"},{"url":"https://euapi-external.zenlytic.com/api/v2","description":"EU"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","description":"A Personal Access Token (PAT).","scheme":"bearer"}},"schemas":{"UpdateUserAttributeSchema":{"properties":{"value":{"type":"string","title":"Value","description":"Must match the existing definition's `data_type` format: \"string\" allows free text, \"number\" requires a parseable number, \"date\" requires `YYYY-MM-DD`."}},"type":"object","required":["value"],"title":"UpdateUserAttributeSchema"},"ApiV2Response_UserAttributeSchema_":{"properties":{"data":{"$ref":"#/components/schemas/UserAttributeSchema"},"meta":{"$ref":"#/components/schemas/MetaSchema"}},"type":"object","required":["data","meta"],"title":"ApiV2Response[UserAttributeSchema]"},"UserAttributeSchema":{"properties":{"id":{"type":"string","title":"Id"},"user_attribute_definition_id":{"type":"string","title":"User Attribute Definition Id"},"value":{"type":"string","title":"Value","description":"Formatted per `data_type`: \"string\" allows free text, \"number\" requires a parseable number, \"date\" requires `YYYY-MM-DD`."},"data_type":{"$ref":"#/components/schemas/UserAttributeDataType","description":"Determines `value`'s format: \"string\" allows free text, \"number\" requires a parseable number, \"date\" requires `YYYY-MM-DD`."},"name":{"type":"string","title":"Name","description":"The referenced `user_attribute_definition_id`'s `name`."},"source":{"$ref":"#/components/schemas/UserAttributeSource","description":"Whether this value is set directly on the member (\"user\") or inherited from a group (\"group\")."},"source_id":{"type":"string","title":"Source Id","description":"ID of the group or member (matching `source`) this value comes from."},"user_attribute_precedence":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"User Attribute Precedence","description":"The source group's precedence; null when `source` is \"user\" - only groups carry a precedence."},"is_overridden":{"type":"boolean","title":"Is Overridden","description":"True if a higher-precedence group value, or a directly-set member value, takes effect instead of this one."}},"type":"object","required":["id","user_attribute_definition_id","value","data_type","name","source","source_id","user_attribute_precedence","is_overridden"],"title":"UserAttributeSchema"},"UserAttributeDataType":{"type":"string","enum":["string","number","date"],"title":"UserAttributeDataType"},"UserAttributeSource":{"type":"string","enum":["user","group"],"title":"UserAttributeSource"},"MetaSchema":{"properties":{"status":{"$ref":"#/components/schemas/ResponseStatus"},"errors":{"items":{"$ref":"#/components/schemas/ErrorSchema"},"type":"array","title":"Errors","description":"Non-empty exactly when `status` is \"error\"."},"warnings":{"items":{"$ref":"#/components/schemas/WarningSchema"},"type":"array","title":"Warnings","description":"Can be non-empty even when `status` is \"success\" - a non-fatal issue with an otherwise-successful request."},"request_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Request Source","description":"Which auth mechanism served this request (e.g. \"api_key\", \"pat\"); null when not tracked for this endpoint."}},"type":"object","required":["status"],"title":"MetaSchema"},"ResponseStatus":{"type":"string","enum":["success","error"],"title":"ResponseStatus"},"ErrorSchema":{"properties":{"message":{"type":"string","title":"Message"},"status_code":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Status Code","description":"Matches this response's actual HTTP status code."},"occurred_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Occurred At","description":"ISO 8601 UTC timestamp."},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Code","description":"Machine-readable code for errors that need special handling (e.g. \"SSO_REQUIRED\") rather than being shown generically; null for most errors."},"error_metadata":{"anyOf":[{"$ref":"#/components/schemas/BaseErrorMetadata"},{"type":"null"}],"description":"Additional structured detail for specific error conditions; usually null."}},"type":"object","required":["message"],"title":"ErrorSchema"},"BaseErrorMetadata":{"properties":{},"type":"object","title":"BaseErrorMetadata"},"WarningSchema":{"properties":{"message":{"type":"string","title":"Message"}},"type":"object","required":["message"],"title":"WarningSchema"},"ApiV2ErrorResponse":{"properties":{"meta":{"$ref":"#/components/schemas/MetaSchema"}},"type":"object","required":["meta"],"title":"ApiV2ErrorResponse"}}},"paths":{"/workspaces/{workspace_id}/groups/{group_id}/user_attributes/{user_attribute_id}":{"patch":{"tags":["Groups"],"summary":"Update Group User Attribute","description":"Update the value of a user attribute already set on a group.\n\nOnly ``value`` is mutable; to point at a different definition, delete this value and\ncreate a new one. ``value`` must match the existing definition's ``data_type``:\n``YYYY-MM-DD`` for ``date``, a numeric string for ``number``.","operationId":"update_group_user_attribute_workspaces__workspace_id__groups__group_id__user_attributes__user_attribute_id__patch","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","title":"Workspace Id"}},{"name":"group_id","in":"path","required":true,"schema":{"type":"string","title":"Group Id"}},{"name":"user_attribute_id","in":"path","required":true,"schema":{"type":"string","title":"User Attribute Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateUserAttributeSchema"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiV2Response_UserAttributeSchema_"}}}},"4XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiV2ErrorResponse"}}},"description":"Client Error"},"5XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiV2ErrorResponse"}}},"description":"Server Error"}}}}}}
```

## Get Groups

> List every group in the workspace, including the built-in "All Users" group.\
> \
> Each group carries its member ids and its \`\`user\_attribute\_precedence\`\`. A warning is\
> returned when two groups in the workspace share a precedence value, since the winning\
> user attribute is then undefined.

```json
{"openapi":"3.1.0","info":{"title":"FastAPI","version":"2.0.0"},"tags":[{"name":"Groups"}],"servers":[{"url":"https://api-external.zenlytic.com/api/v2","description":"US"},{"url":"https://euapi-external.zenlytic.com/api/v2","description":"EU"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","description":"A Personal Access Token (PAT).","scheme":"bearer"}},"schemas":{"ApiV2CollectionResponse_GroupResponseSchema_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/GroupResponseSchema"},"type":"array","title":"Data"},"meta":{"$ref":"#/components/schemas/MetaSchema"}},"type":"object","required":["data","meta"],"title":"ApiV2CollectionResponse[GroupResponseSchema]"},"GroupResponseSchema":{"properties":{"id":{"type":"string","title":"Id"},"workspace_id":{"type":"string","title":"Workspace Id"},"name":{"type":"string","title":"Name"},"is_all_users":{"type":"boolean","title":"Is All Users","description":"Whether this is the built-in group containing every workspace member; its membership always tracks the roster and can't be edited directly."},"user_attribute_precedence":{"type":"integer","title":"User Attribute Precedence","description":"Determines which group's value wins when a member is in several groups that set the same user attribute; higher wins."},"users":{"items":{"type":"string"},"type":"array","title":"Users","description":"IDs of the group's members."}},"type":"object","required":["id","workspace_id","name","is_all_users","user_attribute_precedence","users"],"title":"GroupResponseSchema"},"MetaSchema":{"properties":{"status":{"$ref":"#/components/schemas/ResponseStatus"},"errors":{"items":{"$ref":"#/components/schemas/ErrorSchema"},"type":"array","title":"Errors","description":"Non-empty exactly when `status` is \"error\"."},"warnings":{"items":{"$ref":"#/components/schemas/WarningSchema"},"type":"array","title":"Warnings","description":"Can be non-empty even when `status` is \"success\" - a non-fatal issue with an otherwise-successful request."},"request_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Request Source","description":"Which auth mechanism served this request (e.g. \"api_key\", \"pat\"); null when not tracked for this endpoint."}},"type":"object","required":["status"],"title":"MetaSchema"},"ResponseStatus":{"type":"string","enum":["success","error"],"title":"ResponseStatus"},"ErrorSchema":{"properties":{"message":{"type":"string","title":"Message"},"status_code":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Status Code","description":"Matches this response's actual HTTP status code."},"occurred_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Occurred At","description":"ISO 8601 UTC timestamp."},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Code","description":"Machine-readable code for errors that need special handling (e.g. \"SSO_REQUIRED\") rather than being shown generically; null for most errors."},"error_metadata":{"anyOf":[{"$ref":"#/components/schemas/BaseErrorMetadata"},{"type":"null"}],"description":"Additional structured detail for specific error conditions; usually null."}},"type":"object","required":["message"],"title":"ErrorSchema"},"BaseErrorMetadata":{"properties":{},"type":"object","title":"BaseErrorMetadata"},"WarningSchema":{"properties":{"message":{"type":"string","title":"Message"}},"type":"object","required":["message"],"title":"WarningSchema"},"ApiV2ErrorResponse":{"properties":{"meta":{"$ref":"#/components/schemas/MetaSchema"}},"type":"object","required":["meta"],"title":"ApiV2ErrorResponse"}}},"paths":{"/workspaces/{workspace_id}/groups":{"get":{"tags":["Groups"],"summary":"Get Groups","description":"List every group in the workspace, including the built-in \"All Users\" group.\n\nEach group carries its member ids and its ``user_attribute_precedence``. A warning is\nreturned when two groups in the workspace share a precedence value, since the winning\nuser attribute is then undefined.","operationId":"get_groups_workspaces__workspace_id__groups_get","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","title":"Workspace Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiV2CollectionResponse_GroupResponseSchema_"}}}},"4XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiV2ErrorResponse"}}},"description":"Client Error"},"5XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiV2ErrorResponse"}}},"description":"Server Error"}}}}}}
```

## Create Group

> Create a group in the workspace.\
> \
> \`\`user\_attribute\_precedence\`\` must be greater than 0 and decides which group's value wins\
> when a member belongs to several groups that set the same user attribute. A warning is\
> returned when the new group duplicates an existing precedence value.

```json
{"openapi":"3.1.0","info":{"title":"FastAPI","version":"2.0.0"},"tags":[{"name":"Groups"}],"servers":[{"url":"https://api-external.zenlytic.com/api/v2","description":"US"},{"url":"https://euapi-external.zenlytic.com/api/v2","description":"EU"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","description":"A Personal Access Token (PAT).","scheme":"bearer"}},"schemas":{"CreateGroupSchema":{"properties":{"name":{"type":"string","title":"Name"},"user_attribute_precedence":{"type":"integer","title":"User Attribute Precedence","description":"Must be greater than 0; 0 is reserved for the all_users group."}},"type":"object","required":["name","user_attribute_precedence"],"title":"CreateGroupSchema"},"ApiV2Response_GroupResponseSchema_":{"properties":{"data":{"$ref":"#/components/schemas/GroupResponseSchema"},"meta":{"$ref":"#/components/schemas/MetaSchema"}},"type":"object","required":["data","meta"],"title":"ApiV2Response[GroupResponseSchema]"},"GroupResponseSchema":{"properties":{"id":{"type":"string","title":"Id"},"workspace_id":{"type":"string","title":"Workspace Id"},"name":{"type":"string","title":"Name"},"is_all_users":{"type":"boolean","title":"Is All Users","description":"Whether this is the built-in group containing every workspace member; its membership always tracks the roster and can't be edited directly."},"user_attribute_precedence":{"type":"integer","title":"User Attribute Precedence","description":"Determines which group's value wins when a member is in several groups that set the same user attribute; higher wins."},"users":{"items":{"type":"string"},"type":"array","title":"Users","description":"IDs of the group's members."}},"type":"object","required":["id","workspace_id","name","is_all_users","user_attribute_precedence","users"],"title":"GroupResponseSchema"},"MetaSchema":{"properties":{"status":{"$ref":"#/components/schemas/ResponseStatus"},"errors":{"items":{"$ref":"#/components/schemas/ErrorSchema"},"type":"array","title":"Errors","description":"Non-empty exactly when `status` is \"error\"."},"warnings":{"items":{"$ref":"#/components/schemas/WarningSchema"},"type":"array","title":"Warnings","description":"Can be non-empty even when `status` is \"success\" - a non-fatal issue with an otherwise-successful request."},"request_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Request Source","description":"Which auth mechanism served this request (e.g. \"api_key\", \"pat\"); null when not tracked for this endpoint."}},"type":"object","required":["status"],"title":"MetaSchema"},"ResponseStatus":{"type":"string","enum":["success","error"],"title":"ResponseStatus"},"ErrorSchema":{"properties":{"message":{"type":"string","title":"Message"},"status_code":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Status Code","description":"Matches this response's actual HTTP status code."},"occurred_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Occurred At","description":"ISO 8601 UTC timestamp."},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Code","description":"Machine-readable code for errors that need special handling (e.g. \"SSO_REQUIRED\") rather than being shown generically; null for most errors."},"error_metadata":{"anyOf":[{"$ref":"#/components/schemas/BaseErrorMetadata"},{"type":"null"}],"description":"Additional structured detail for specific error conditions; usually null."}},"type":"object","required":["message"],"title":"ErrorSchema"},"BaseErrorMetadata":{"properties":{},"type":"object","title":"BaseErrorMetadata"},"WarningSchema":{"properties":{"message":{"type":"string","title":"Message"}},"type":"object","required":["message"],"title":"WarningSchema"},"ApiV2ErrorResponse":{"properties":{"meta":{"$ref":"#/components/schemas/MetaSchema"}},"type":"object","required":["meta"],"title":"ApiV2ErrorResponse"}}},"paths":{"/workspaces/{workspace_id}/groups":{"post":{"tags":["Groups"],"summary":"Create Group","description":"Create a group in the workspace.\n\n``user_attribute_precedence`` must be greater than 0 and decides which group's value wins\nwhen a member belongs to several groups that set the same user attribute. A warning is\nreturned when the new group duplicates an existing precedence value.","operationId":"create_group_workspaces__workspace_id__groups_post","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","title":"Workspace Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateGroupSchema"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiV2Response_GroupResponseSchema_"}}}},"4XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiV2ErrorResponse"}}},"description":"Client Error"},"5XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiV2ErrorResponse"}}},"description":"Server Error"}}}}}}
```

## Get Group

> Retrieve a single group in the workspace by id.\
> \
> Returns 404 if no group with that id exists in the workspace.

```json
{"openapi":"3.1.0","info":{"title":"FastAPI","version":"2.0.0"},"tags":[{"name":"Groups"}],"servers":[{"url":"https://api-external.zenlytic.com/api/v2","description":"US"},{"url":"https://euapi-external.zenlytic.com/api/v2","description":"EU"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","description":"A Personal Access Token (PAT).","scheme":"bearer"}},"schemas":{"ApiV2Response_GroupResponseSchema_":{"properties":{"data":{"$ref":"#/components/schemas/GroupResponseSchema"},"meta":{"$ref":"#/components/schemas/MetaSchema"}},"type":"object","required":["data","meta"],"title":"ApiV2Response[GroupResponseSchema]"},"GroupResponseSchema":{"properties":{"id":{"type":"string","title":"Id"},"workspace_id":{"type":"string","title":"Workspace Id"},"name":{"type":"string","title":"Name"},"is_all_users":{"type":"boolean","title":"Is All Users","description":"Whether this is the built-in group containing every workspace member; its membership always tracks the roster and can't be edited directly."},"user_attribute_precedence":{"type":"integer","title":"User Attribute Precedence","description":"Determines which group's value wins when a member is in several groups that set the same user attribute; higher wins."},"users":{"items":{"type":"string"},"type":"array","title":"Users","description":"IDs of the group's members."}},"type":"object","required":["id","workspace_id","name","is_all_users","user_attribute_precedence","users"],"title":"GroupResponseSchema"},"MetaSchema":{"properties":{"status":{"$ref":"#/components/schemas/ResponseStatus"},"errors":{"items":{"$ref":"#/components/schemas/ErrorSchema"},"type":"array","title":"Errors","description":"Non-empty exactly when `status` is \"error\"."},"warnings":{"items":{"$ref":"#/components/schemas/WarningSchema"},"type":"array","title":"Warnings","description":"Can be non-empty even when `status` is \"success\" - a non-fatal issue with an otherwise-successful request."},"request_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Request Source","description":"Which auth mechanism served this request (e.g. \"api_key\", \"pat\"); null when not tracked for this endpoint."}},"type":"object","required":["status"],"title":"MetaSchema"},"ResponseStatus":{"type":"string","enum":["success","error"],"title":"ResponseStatus"},"ErrorSchema":{"properties":{"message":{"type":"string","title":"Message"},"status_code":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Status Code","description":"Matches this response's actual HTTP status code."},"occurred_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Occurred At","description":"ISO 8601 UTC timestamp."},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Code","description":"Machine-readable code for errors that need special handling (e.g. \"SSO_REQUIRED\") rather than being shown generically; null for most errors."},"error_metadata":{"anyOf":[{"$ref":"#/components/schemas/BaseErrorMetadata"},{"type":"null"}],"description":"Additional structured detail for specific error conditions; usually null."}},"type":"object","required":["message"],"title":"ErrorSchema"},"BaseErrorMetadata":{"properties":{},"type":"object","title":"BaseErrorMetadata"},"WarningSchema":{"properties":{"message":{"type":"string","title":"Message"}},"type":"object","required":["message"],"title":"WarningSchema"},"ApiV2ErrorResponse":{"properties":{"meta":{"$ref":"#/components/schemas/MetaSchema"}},"type":"object","required":["meta"],"title":"ApiV2ErrorResponse"}}},"paths":{"/workspaces/{workspace_id}/groups/{group_id}":{"get":{"tags":["Groups"],"summary":"Get Group","description":"Retrieve a single group in the workspace by id.\n\nReturns 404 if no group with that id exists in the workspace.","operationId":"get_group_workspaces__workspace_id__groups__group_id__get","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","title":"Workspace Id"}},{"name":"group_id","in":"path","required":true,"schema":{"type":"string","title":"Group Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiV2Response_GroupResponseSchema_"}}}},"4XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiV2ErrorResponse"}}},"description":"Client Error"},"5XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiV2ErrorResponse"}}},"description":"Server Error"}}}}}}
```

## Delete Group

> Delete a group and the user attributes attached to it.\
> \
> Members are not deleted, only their membership. The built-in "All Users" group cannot be\
> deleted.

```json
{"openapi":"3.1.0","info":{"title":"FastAPI","version":"2.0.0"},"tags":[{"name":"Groups"}],"servers":[{"url":"https://api-external.zenlytic.com/api/v2","description":"US"},{"url":"https://euapi-external.zenlytic.com/api/v2","description":"EU"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","description":"A Personal Access Token (PAT).","scheme":"bearer"}},"schemas":{"ApiV2ErrorResponse":{"properties":{"meta":{"$ref":"#/components/schemas/MetaSchema"}},"type":"object","required":["meta"],"title":"ApiV2ErrorResponse"},"MetaSchema":{"properties":{"status":{"$ref":"#/components/schemas/ResponseStatus"},"errors":{"items":{"$ref":"#/components/schemas/ErrorSchema"},"type":"array","title":"Errors","description":"Non-empty exactly when `status` is \"error\"."},"warnings":{"items":{"$ref":"#/components/schemas/WarningSchema"},"type":"array","title":"Warnings","description":"Can be non-empty even when `status` is \"success\" - a non-fatal issue with an otherwise-successful request."},"request_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Request Source","description":"Which auth mechanism served this request (e.g. \"api_key\", \"pat\"); null when not tracked for this endpoint."}},"type":"object","required":["status"],"title":"MetaSchema"},"ResponseStatus":{"type":"string","enum":["success","error"],"title":"ResponseStatus"},"ErrorSchema":{"properties":{"message":{"type":"string","title":"Message"},"status_code":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Status Code","description":"Matches this response's actual HTTP status code."},"occurred_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Occurred At","description":"ISO 8601 UTC timestamp."},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Code","description":"Machine-readable code for errors that need special handling (e.g. \"SSO_REQUIRED\") rather than being shown generically; null for most errors."},"error_metadata":{"anyOf":[{"$ref":"#/components/schemas/BaseErrorMetadata"},{"type":"null"}],"description":"Additional structured detail for specific error conditions; usually null."}},"type":"object","required":["message"],"title":"ErrorSchema"},"BaseErrorMetadata":{"properties":{},"type":"object","title":"BaseErrorMetadata"},"WarningSchema":{"properties":{"message":{"type":"string","title":"Message"}},"type":"object","required":["message"],"title":"WarningSchema"}}},"paths":{"/workspaces/{workspace_id}/groups/{group_id}":{"delete":{"tags":["Groups"],"summary":"Delete Group","description":"Delete a group and the user attributes attached to it.\n\nMembers are not deleted, only their membership. The built-in \"All Users\" group cannot be\ndeleted.","operationId":"delete_group_workspaces__workspace_id__groups__group_id__delete","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","title":"Workspace Id"}},{"name":"group_id","in":"path","required":true,"schema":{"type":"string","title":"Group Id"}}],"responses":{"204":{"description":"Successful Response"},"4XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiV2ErrorResponse"}}},"description":"Client Error"},"5XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiV2ErrorResponse"}}},"description":"Server Error"}}}}}}
```

## Update Group

> Update a group's name or user attribute precedence.\
> \
> The built-in "All Users" group cannot be updated; its membership always tracks the\
> workspace roster. A warning is returned if the update makes this group's precedence\
> match another group's in the workspace.

```json
{"openapi":"3.1.0","info":{"title":"FastAPI","version":"2.0.0"},"tags":[{"name":"Groups"}],"servers":[{"url":"https://api-external.zenlytic.com/api/v2","description":"US"},{"url":"https://euapi-external.zenlytic.com/api/v2","description":"EU"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","description":"A Personal Access Token (PAT).","scheme":"bearer"}},"schemas":{"UpdateGroupSchema":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"user_attribute_precedence":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"User Attribute Precedence","description":"Must be greater than 0; 0 is reserved for the all_users group."}},"type":"object","title":"UpdateGroupSchema"},"ApiV2Response_GroupResponseSchema_":{"properties":{"data":{"$ref":"#/components/schemas/GroupResponseSchema"},"meta":{"$ref":"#/components/schemas/MetaSchema"}},"type":"object","required":["data","meta"],"title":"ApiV2Response[GroupResponseSchema]"},"GroupResponseSchema":{"properties":{"id":{"type":"string","title":"Id"},"workspace_id":{"type":"string","title":"Workspace Id"},"name":{"type":"string","title":"Name"},"is_all_users":{"type":"boolean","title":"Is All Users","description":"Whether this is the built-in group containing every workspace member; its membership always tracks the roster and can't be edited directly."},"user_attribute_precedence":{"type":"integer","title":"User Attribute Precedence","description":"Determines which group's value wins when a member is in several groups that set the same user attribute; higher wins."},"users":{"items":{"type":"string"},"type":"array","title":"Users","description":"IDs of the group's members."}},"type":"object","required":["id","workspace_id","name","is_all_users","user_attribute_precedence","users"],"title":"GroupResponseSchema"},"MetaSchema":{"properties":{"status":{"$ref":"#/components/schemas/ResponseStatus"},"errors":{"items":{"$ref":"#/components/schemas/ErrorSchema"},"type":"array","title":"Errors","description":"Non-empty exactly when `status` is \"error\"."},"warnings":{"items":{"$ref":"#/components/schemas/WarningSchema"},"type":"array","title":"Warnings","description":"Can be non-empty even when `status` is \"success\" - a non-fatal issue with an otherwise-successful request."},"request_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Request Source","description":"Which auth mechanism served this request (e.g. \"api_key\", \"pat\"); null when not tracked for this endpoint."}},"type":"object","required":["status"],"title":"MetaSchema"},"ResponseStatus":{"type":"string","enum":["success","error"],"title":"ResponseStatus"},"ErrorSchema":{"properties":{"message":{"type":"string","title":"Message"},"status_code":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Status Code","description":"Matches this response's actual HTTP status code."},"occurred_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Occurred At","description":"ISO 8601 UTC timestamp."},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Code","description":"Machine-readable code for errors that need special handling (e.g. \"SSO_REQUIRED\") rather than being shown generically; null for most errors."},"error_metadata":{"anyOf":[{"$ref":"#/components/schemas/BaseErrorMetadata"},{"type":"null"}],"description":"Additional structured detail for specific error conditions; usually null."}},"type":"object","required":["message"],"title":"ErrorSchema"},"BaseErrorMetadata":{"properties":{},"type":"object","title":"BaseErrorMetadata"},"WarningSchema":{"properties":{"message":{"type":"string","title":"Message"}},"type":"object","required":["message"],"title":"WarningSchema"},"ApiV2ErrorResponse":{"properties":{"meta":{"$ref":"#/components/schemas/MetaSchema"}},"type":"object","required":["meta"],"title":"ApiV2ErrorResponse"}}},"paths":{"/workspaces/{workspace_id}/groups/{group_id}":{"patch":{"tags":["Groups"],"summary":"Update Group","description":"Update a group's name or user attribute precedence.\n\nThe built-in \"All Users\" group cannot be updated; its membership always tracks the\nworkspace roster. A warning is returned if the update makes this group's precedence\nmatch another group's in the workspace.","operationId":"update_group_workspaces__workspace_id__groups__group_id__patch","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","title":"Workspace Id"}},{"name":"group_id","in":"path","required":true,"schema":{"type":"string","title":"Group Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateGroupSchema"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiV2Response_GroupResponseSchema_"}}}},"4XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiV2ErrorResponse"}}},"description":"Client Error"},"5XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiV2ErrorResponse"}}},"description":"Server Error"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.zenlytic.com/developers-beta/api-reference/admin/groups.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.