# Groups

User group management

## GET /api/v1/groups

> Lists all groups

```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.1"},"tags":[{"name":"hq_groups","description":"User group management"}],"servers":[{"url":"{server}","variables":{"server":{"default":"https://api.example.com"}}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"The bearer token can be obtained by creating a ServiceAccount.\n"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"session_id","description":"On successful SAML/SSO login, the API will set a cookie with a session id.\n"}},"schemas":{"hq_CompactGroupList":{"type":"object","description":"Contains a list of CompactGroups.","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/hq_CompactGroup"}}},"required":["items"]},"hq_CompactGroup":{"type":"object","description":"Represents a Group in a compact way.","properties":{"name":{"type":"string"},"display_name":{"type":"string"},"sso_name":{"type":"string"},"lrn":{"type":"string","description":"Contains the resource identifier for use in access control policies."},"id":{"type":"string"},"created_at":{"format":"date-time","type":"string"},"description":{"type":"string"},"user_count":{"type":"integer","description":"Is set to the number of users in this group."},"sa_count":{"type":"integer","description":"Is set to the number of service accounts in this group."},"role_count":{"type":"integer","description":"Is set to the number of roles associated with this group."},"metadata":{"$ref":"#/components/schemas/hq_Metadata"}},"required":["name","display_name","sso_name","lrn","id","created_at","description","user_count","sa_count","role_count"]},"hq_Metadata":{"type":"object","description":"Allows attaching custom string key/values to resources.\nThe following maxima apply:\n- 50 keys/values;\n- 40 bytes key length;\n- 500 bytes value length.\n","additionalProperties":{"type":"string"}},"hq_Error":{"type":"object","description":"Implements the RFC7807 \"Problem Details\", see https://www.rfc-editor.org/rfc/rfc7807.","properties":{"type":{"$ref":"#/components/schemas/hq_ErrorType"},"title":{"description":"Describes the problem in a human readable fashion.","type":"string"},"status":{"description":"Is a copy of the http status code.","type":"integer"},"invalid_fields":{"description":"Lists for validation errors the fields that failed validation.","type":"array","items":{"$ref":"#/components/schemas/hq_InvalidField"}},"sso_url":{"description":"Contains in case of an \"unauthorised\" type of error, the url of the SSO provider, if any.","type":"string"},"request_id":{"description":"Is set to the id of this request. Can be used to correlate backend logs.","type":"string"}},"required":["status","title"]},"hq_ErrorType":{"type":"string","description":"Enumerates possible error types.","enum":["not_found","unauthorised","forbidden","internal_server_error","agent_rpc_error","missing_agent_capabilities","agent_not_connected","validation_error","invalid_metadata","missing_parameter","invalid_parameter","licence_limitation","ai_server_unavailable","conflict","unspecified"]},"hq_InvalidField":{"type":"object","properties":{"name":{"type":"string"},"error":{"$ref":"#/components/schemas/hq_FieldErrorType"},"title":{"type":"string"},"pointer":{"description":"Holds a RFC-6901 JSON Pointer.","type":"string"}},"required":["name","error","title"]},"hq_FieldErrorType":{"type":"string","description":"Enumerates field validation error types.","enum":["reference_not_found","not_unique","invalid_value","other_error"]}}},"paths":{"/api/v1/groups":{"get":{"description":"Lists all groups","operationId":"listGroups","responses":{"200":{"description":"Happy response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_CompactGroupList"}}}},"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_groups"]}}}}
```

## POST /api/v1/groups

> Creates a new Group.

```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.1"},"tags":[{"name":"hq_groups","description":"User group management"}],"servers":[{"url":"{server}","variables":{"server":{"default":"https://api.example.com"}}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"The bearer token can be obtained by creating a ServiceAccount.\n"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"session_id","description":"On successful SAML/SSO login, the API will set a cookie with a session id.\n"}},"schemas":{"hq_CreateGroupRequest":{"type":"object","properties":{"name":{"type":"string","format":"hq-resource-name","description":"Sets the unique name of the new group. It must be a valid HQ\nresource name: it can only contain lowercase alphanumeric characters\nor hyphens; hyphens cannot appear at the end or start; the length is\n63 characters at most.\n","minLength":1,"maxLength":63},"display_name":{"type":"string","description":"Sets the display name of the new group. If not provided, the value\nof \"name\" will be used.\n","minLength":1,"maxLength":150},"sso_name":{"type":"string","description":"Sets the SSO name of the new group. If not provided, the value of\n\"name\" will be used. When users sign in via SSO, this field is used\nto map SSO-provided groups onto HQ groups. Having a dedicated field\nhelps in e.g. the Active Directory situation, where the groups in\nthe SAML assertion are passed as UUIDs. E.g., one can have a group\nnamed \"my-group\" with display_name \"My Group of Lovely People\" and\nsso_name \"f3f2e850-b5d4-11ef-ac7e-96584d5248b2\".\n","minLength":1,"maxLength":150},"description":{"type":"string","description":"Sets the description of the new group.","maxLength":250},"members":{"description":"Lists principal names (users, service accounts) to be member of this group.","type":"array","items":{"type":"string"}},"roles":{"description":"Sets the Roles that are bound to this Group by name.","type":"array","items":{"type":"string"}},"metadata":{"$ref":"#/components/schemas/hq_Metadata"}},"required":["name"]},"hq_Metadata":{"type":"object","description":"Allows attaching custom string key/values to resources.\nThe following maxima apply:\n- 50 keys/values;\n- 40 bytes key length;\n- 500 bytes value length.\n","additionalProperties":{"type":"string"}},"hq_Group":{"type":"object","description":"Contains Users and Service accounts, and the Roles assigned to it.","properties":{"name":{"type":"string","description":"Holds the name of the Group. Must be unique."},"display_name":{"type":"string","description":"Holds the display name of the Group."},"sso_name":{"type":"string","description":"Holds the SSO name of the Group."},"lrn":{"type":"string","description":"Contains the resource identifier for use in access control policies."},"id":{"type":"string"},"created_at":{"format":"date-time","type":"string"},"description":{"type":"string"},"roles":{"type":"array","items":{"$ref":"#/components/schemas/hq_CompactRole"}},"users":{"type":"array","items":{"$ref":"#/components/schemas/hq_CompactUser"}},"service_accounts":{"type":"array","items":{"$ref":"#/components/schemas/hq_CompactServiceAccount"}},"metadata":{"$ref":"#/components/schemas/hq_Metadata"}},"required":["name","display_name","sso_name","lrn","id","created_at","description","roles","users","service_accounts"]},"hq_CompactRole":{"type":"object","description":"Represents a Role in a compact way.","properties":{"name":{"description":"Holds the unique name of this role.","type":"string"},"display_name":{"type":"string"},"lrn":{"type":"string","description":"Contains the resource identifier for use in access control policies."},"description":{"type":"string","description":"Contains the description of the role."},"id":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"policy_length":{"description":"Is set to the number of PermissionStatements in the Policy.","type":"integer"},"metadata":{"$ref":"#/components/schemas/hq_Metadata"}},"required":["name","display_name","lrn","description","id","created_at","policy_length"]},"hq_CompactUser":{"type":"object","description":"Represents a User in a compact way.","properties":{"name":{"type":"string"},"display_name":{"type":"string"},"lrn":{"type":"string","description":"Contains the resource identifier for use in access control policies."},"id":{"type":"string"},"created_at":{"format":"date-time","type":"string"},"profile":{"$ref":"#/components/schemas/hq_UserProfile"},"is_admin":{"type":"boolean"},"metadata":{"$ref":"#/components/schemas/hq_Metadata"}},"required":["name","display_name","lrn","id","created_at","profile","is_admin"]},"hq_UserProfile":{"type":"object","description":"Models a user's Profile.","properties":{"full_name":{"description":"Contains the users' full name, e.g. Mary Jane Doe.","type":"string"},"email_address":{"description":"Contains the users' email address, e.g. mary.jane@doe.net. Note that\nthis is not necessarily the same as the user's name, which often\nlooks like an email address, but is not per se.\n","type":"string"}},"required":["full_name","email_address"]},"hq_CompactServiceAccount":{"type":"object","description":"Represents a ServiceAccount in a compact way.","properties":{"name":{"type":"string"},"display_name":{"type":"string"},"lrn":{"type":"string","description":"Contains the resource identifier for use in access control policies."},"id":{"type":"string"},"created_at":{"format":"date-time","type":"string"},"is_admin":{"type":"boolean"},"metadata":{"$ref":"#/components/schemas/hq_Metadata"}},"required":["name","display_name","lrn","id","created_at","is_admin"]},"hq_Error":{"type":"object","description":"Implements the RFC7807 \"Problem Details\", see https://www.rfc-editor.org/rfc/rfc7807.","properties":{"type":{"$ref":"#/components/schemas/hq_ErrorType"},"title":{"description":"Describes the problem in a human readable fashion.","type":"string"},"status":{"description":"Is a copy of the http status code.","type":"integer"},"invalid_fields":{"description":"Lists for validation errors the fields that failed validation.","type":"array","items":{"$ref":"#/components/schemas/hq_InvalidField"}},"sso_url":{"description":"Contains in case of an \"unauthorised\" type of error, the url of the SSO provider, if any.","type":"string"},"request_id":{"description":"Is set to the id of this request. Can be used to correlate backend logs.","type":"string"}},"required":["status","title"]},"hq_ErrorType":{"type":"string","description":"Enumerates possible error types.","enum":["not_found","unauthorised","forbidden","internal_server_error","agent_rpc_error","missing_agent_capabilities","agent_not_connected","validation_error","invalid_metadata","missing_parameter","invalid_parameter","licence_limitation","ai_server_unavailable","conflict","unspecified"]},"hq_InvalidField":{"type":"object","properties":{"name":{"type":"string"},"error":{"$ref":"#/components/schemas/hq_FieldErrorType"},"title":{"type":"string"},"pointer":{"description":"Holds a RFC-6901 JSON Pointer.","type":"string"}},"required":["name","error","title"]},"hq_FieldErrorType":{"type":"string","description":"Enumerates field validation error types.","enum":["reference_not_found","not_unique","invalid_value","other_error"]}}},"paths":{"/api/v1/groups":{"post":{"description":"Creates a new Group.","operationId":"createGroup","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_CreateGroupRequest"}}}},"responses":{"201":{"description":"Happy response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Group"}}}},"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_groups"]}}}}
```

## GET /api/v1/groups/{name}

> Gets a group by its name.

```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.1"},"tags":[{"name":"hq_groups","description":"User group management"}],"servers":[{"url":"{server}","variables":{"server":{"default":"https://api.example.com"}}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"The bearer token can be obtained by creating a ServiceAccount.\n"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"session_id","description":"On successful SAML/SSO login, the API will set a cookie with a session id.\n"}},"schemas":{"hq_Group":{"type":"object","description":"Contains Users and Service accounts, and the Roles assigned to it.","properties":{"name":{"type":"string","description":"Holds the name of the Group. Must be unique."},"display_name":{"type":"string","description":"Holds the display name of the Group."},"sso_name":{"type":"string","description":"Holds the SSO name of the Group."},"lrn":{"type":"string","description":"Contains the resource identifier for use in access control policies."},"id":{"type":"string"},"created_at":{"format":"date-time","type":"string"},"description":{"type":"string"},"roles":{"type":"array","items":{"$ref":"#/components/schemas/hq_CompactRole"}},"users":{"type":"array","items":{"$ref":"#/components/schemas/hq_CompactUser"}},"service_accounts":{"type":"array","items":{"$ref":"#/components/schemas/hq_CompactServiceAccount"}},"metadata":{"$ref":"#/components/schemas/hq_Metadata"}},"required":["name","display_name","sso_name","lrn","id","created_at","description","roles","users","service_accounts"]},"hq_CompactRole":{"type":"object","description":"Represents a Role in a compact way.","properties":{"name":{"description":"Holds the unique name of this role.","type":"string"},"display_name":{"type":"string"},"lrn":{"type":"string","description":"Contains the resource identifier for use in access control policies."},"description":{"type":"string","description":"Contains the description of the role."},"id":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"policy_length":{"description":"Is set to the number of PermissionStatements in the Policy.","type":"integer"},"metadata":{"$ref":"#/components/schemas/hq_Metadata"}},"required":["name","display_name","lrn","description","id","created_at","policy_length"]},"hq_Metadata":{"type":"object","description":"Allows attaching custom string key/values to resources.\nThe following maxima apply:\n- 50 keys/values;\n- 40 bytes key length;\n- 500 bytes value length.\n","additionalProperties":{"type":"string"}},"hq_CompactUser":{"type":"object","description":"Represents a User in a compact way.","properties":{"name":{"type":"string"},"display_name":{"type":"string"},"lrn":{"type":"string","description":"Contains the resource identifier for use in access control policies."},"id":{"type":"string"},"created_at":{"format":"date-time","type":"string"},"profile":{"$ref":"#/components/schemas/hq_UserProfile"},"is_admin":{"type":"boolean"},"metadata":{"$ref":"#/components/schemas/hq_Metadata"}},"required":["name","display_name","lrn","id","created_at","profile","is_admin"]},"hq_UserProfile":{"type":"object","description":"Models a user's Profile.","properties":{"full_name":{"description":"Contains the users' full name, e.g. Mary Jane Doe.","type":"string"},"email_address":{"description":"Contains the users' email address, e.g. mary.jane@doe.net. Note that\nthis is not necessarily the same as the user's name, which often\nlooks like an email address, but is not per se.\n","type":"string"}},"required":["full_name","email_address"]},"hq_CompactServiceAccount":{"type":"object","description":"Represents a ServiceAccount in a compact way.","properties":{"name":{"type":"string"},"display_name":{"type":"string"},"lrn":{"type":"string","description":"Contains the resource identifier for use in access control policies."},"id":{"type":"string"},"created_at":{"format":"date-time","type":"string"},"is_admin":{"type":"boolean"},"metadata":{"$ref":"#/components/schemas/hq_Metadata"}},"required":["name","display_name","lrn","id","created_at","is_admin"]},"hq_Error":{"type":"object","description":"Implements the RFC7807 \"Problem Details\", see https://www.rfc-editor.org/rfc/rfc7807.","properties":{"type":{"$ref":"#/components/schemas/hq_ErrorType"},"title":{"description":"Describes the problem in a human readable fashion.","type":"string"},"status":{"description":"Is a copy of the http status code.","type":"integer"},"invalid_fields":{"description":"Lists for validation errors the fields that failed validation.","type":"array","items":{"$ref":"#/components/schemas/hq_InvalidField"}},"sso_url":{"description":"Contains in case of an \"unauthorised\" type of error, the url of the SSO provider, if any.","type":"string"},"request_id":{"description":"Is set to the id of this request. Can be used to correlate backend logs.","type":"string"}},"required":["status","title"]},"hq_ErrorType":{"type":"string","description":"Enumerates possible error types.","enum":["not_found","unauthorised","forbidden","internal_server_error","agent_rpc_error","missing_agent_capabilities","agent_not_connected","validation_error","invalid_metadata","missing_parameter","invalid_parameter","licence_limitation","ai_server_unavailable","conflict","unspecified"]},"hq_InvalidField":{"type":"object","properties":{"name":{"type":"string"},"error":{"$ref":"#/components/schemas/hq_FieldErrorType"},"title":{"type":"string"},"pointer":{"description":"Holds a RFC-6901 JSON Pointer.","type":"string"}},"required":["name","error","title"]},"hq_FieldErrorType":{"type":"string","description":"Enumerates field validation error types.","enum":["reference_not_found","not_unique","invalid_value","other_error"]}}},"paths":{"/api/v1/groups/{name}":{"get":{"description":"Gets a group by its name.","operationId":"getGroup","parameters":[{"in":"path","name":"name","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Happy response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Group"}}}},"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_groups"]}}}}
```

## DELETE /api/v1/groups/{name}

> Deletes a group.

```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.1"},"tags":[{"name":"hq_groups","description":"User group management"}],"servers":[{"url":"{server}","variables":{"server":{"default":"https://api.example.com"}}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"The bearer token can be obtained by creating a ServiceAccount.\n"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"session_id","description":"On successful SAML/SSO login, the API will set a cookie with a session id.\n"}},"schemas":{"hq_Error":{"type":"object","description":"Implements the RFC7807 \"Problem Details\", see https://www.rfc-editor.org/rfc/rfc7807.","properties":{"type":{"$ref":"#/components/schemas/hq_ErrorType"},"title":{"description":"Describes the problem in a human readable fashion.","type":"string"},"status":{"description":"Is a copy of the http status code.","type":"integer"},"invalid_fields":{"description":"Lists for validation errors the fields that failed validation.","type":"array","items":{"$ref":"#/components/schemas/hq_InvalidField"}},"sso_url":{"description":"Contains in case of an \"unauthorised\" type of error, the url of the SSO provider, if any.","type":"string"},"request_id":{"description":"Is set to the id of this request. Can be used to correlate backend logs.","type":"string"}},"required":["status","title"]},"hq_ErrorType":{"type":"string","description":"Enumerates possible error types.","enum":["not_found","unauthorised","forbidden","internal_server_error","agent_rpc_error","missing_agent_capabilities","agent_not_connected","validation_error","invalid_metadata","missing_parameter","invalid_parameter","licence_limitation","ai_server_unavailable","conflict","unspecified"]},"hq_InvalidField":{"type":"object","properties":{"name":{"type":"string"},"error":{"$ref":"#/components/schemas/hq_FieldErrorType"},"title":{"type":"string"},"pointer":{"description":"Holds a RFC-6901 JSON Pointer.","type":"string"}},"required":["name","error","title"]},"hq_FieldErrorType":{"type":"string","description":"Enumerates field validation error types.","enum":["reference_not_found","not_unique","invalid_value","other_error"]}}},"paths":{"/api/v1/groups/{name}":{"delete":{"description":"Deletes a group.","operationId":"deleteGroup","parameters":[{"in":"path","name":"name","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Successful deletion."},"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_groups"]}}}}
```

## PATCH /api/v1/groups/{name}

> Updates a group.

```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.1"},"tags":[{"name":"hq_groups","description":"User group management"}],"servers":[{"url":"{server}","variables":{"server":{"default":"https://api.example.com"}}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"The bearer token can be obtained by creating a ServiceAccount.\n"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"session_id","description":"On successful SAML/SSO login, the API will set a cookie with a session id.\n"}},"schemas":{"hq_UpdateGroupRequest":{"type":"object","properties":{"display_name":{"type":"string","description":"Updates the display name of the group.","minLength":1,"maxLength":150},"sso_name":{"type":"string","description":"Updates the SSO name of the group.","minLength":1,"maxLength":150},"description":{"type":"string","maxLength":250,"description":"Updates the Group description, if a value is provided."},"roles":{"description":"Sets the Roles that are bound to this Group to the Roles (specified by their names), if provided.","type":"array","items":{"type":"string"}},"add_members":{"description":"Adds the users/principals (specified by their names) to this group, if provided.","type":"array","items":{"type":"string"}},"remove_members":{"description":"Removes the users/principals (specified by their names) from this\ngroup, if provided. If members are specified in both add_members as\nwell in here, removal wins.\n","type":"array","items":{"type":"string"}},"set_members":{"description":"Sets the members of this group to those users/principals (specified\nby their names) in an absolute fashion, if provided. Cannot be\ncombined with the add_members or remove_members fields.\n","type":"array","items":{"type":"string"}},"metadata":{"$ref":"#/components/schemas/hq_MetadataPatchRequest"}}},"hq_MetadataPatchRequest":{"type":"object","description":"Patches metadata. It has the following semantics:\n  - Absent keys are left untouched;\n  - Null values are deleted;\n  - Non-null values are replaced.\n","additionalProperties":{"type":"string","nullable":true}},"hq_Group":{"type":"object","description":"Contains Users and Service accounts, and the Roles assigned to it.","properties":{"name":{"type":"string","description":"Holds the name of the Group. Must be unique."},"display_name":{"type":"string","description":"Holds the display name of the Group."},"sso_name":{"type":"string","description":"Holds the SSO name of the Group."},"lrn":{"type":"string","description":"Contains the resource identifier for use in access control policies."},"id":{"type":"string"},"created_at":{"format":"date-time","type":"string"},"description":{"type":"string"},"roles":{"type":"array","items":{"$ref":"#/components/schemas/hq_CompactRole"}},"users":{"type":"array","items":{"$ref":"#/components/schemas/hq_CompactUser"}},"service_accounts":{"type":"array","items":{"$ref":"#/components/schemas/hq_CompactServiceAccount"}},"metadata":{"$ref":"#/components/schemas/hq_Metadata"}},"required":["name","display_name","sso_name","lrn","id","created_at","description","roles","users","service_accounts"]},"hq_CompactRole":{"type":"object","description":"Represents a Role in a compact way.","properties":{"name":{"description":"Holds the unique name of this role.","type":"string"},"display_name":{"type":"string"},"lrn":{"type":"string","description":"Contains the resource identifier for use in access control policies."},"description":{"type":"string","description":"Contains the description of the role."},"id":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"policy_length":{"description":"Is set to the number of PermissionStatements in the Policy.","type":"integer"},"metadata":{"$ref":"#/components/schemas/hq_Metadata"}},"required":["name","display_name","lrn","description","id","created_at","policy_length"]},"hq_Metadata":{"type":"object","description":"Allows attaching custom string key/values to resources.\nThe following maxima apply:\n- 50 keys/values;\n- 40 bytes key length;\n- 500 bytes value length.\n","additionalProperties":{"type":"string"}},"hq_CompactUser":{"type":"object","description":"Represents a User in a compact way.","properties":{"name":{"type":"string"},"display_name":{"type":"string"},"lrn":{"type":"string","description":"Contains the resource identifier for use in access control policies."},"id":{"type":"string"},"created_at":{"format":"date-time","type":"string"},"profile":{"$ref":"#/components/schemas/hq_UserProfile"},"is_admin":{"type":"boolean"},"metadata":{"$ref":"#/components/schemas/hq_Metadata"}},"required":["name","display_name","lrn","id","created_at","profile","is_admin"]},"hq_UserProfile":{"type":"object","description":"Models a user's Profile.","properties":{"full_name":{"description":"Contains the users' full name, e.g. Mary Jane Doe.","type":"string"},"email_address":{"description":"Contains the users' email address, e.g. mary.jane@doe.net. Note that\nthis is not necessarily the same as the user's name, which often\nlooks like an email address, but is not per se.\n","type":"string"}},"required":["full_name","email_address"]},"hq_CompactServiceAccount":{"type":"object","description":"Represents a ServiceAccount in a compact way.","properties":{"name":{"type":"string"},"display_name":{"type":"string"},"lrn":{"type":"string","description":"Contains the resource identifier for use in access control policies."},"id":{"type":"string"},"created_at":{"format":"date-time","type":"string"},"is_admin":{"type":"boolean"},"metadata":{"$ref":"#/components/schemas/hq_Metadata"}},"required":["name","display_name","lrn","id","created_at","is_admin"]},"hq_Error":{"type":"object","description":"Implements the RFC7807 \"Problem Details\", see https://www.rfc-editor.org/rfc/rfc7807.","properties":{"type":{"$ref":"#/components/schemas/hq_ErrorType"},"title":{"description":"Describes the problem in a human readable fashion.","type":"string"},"status":{"description":"Is a copy of the http status code.","type":"integer"},"invalid_fields":{"description":"Lists for validation errors the fields that failed validation.","type":"array","items":{"$ref":"#/components/schemas/hq_InvalidField"}},"sso_url":{"description":"Contains in case of an \"unauthorised\" type of error, the url of the SSO provider, if any.","type":"string"},"request_id":{"description":"Is set to the id of this request. Can be used to correlate backend logs.","type":"string"}},"required":["status","title"]},"hq_ErrorType":{"type":"string","description":"Enumerates possible error types.","enum":["not_found","unauthorised","forbidden","internal_server_error","agent_rpc_error","missing_agent_capabilities","agent_not_connected","validation_error","invalid_metadata","missing_parameter","invalid_parameter","licence_limitation","ai_server_unavailable","conflict","unspecified"]},"hq_InvalidField":{"type":"object","properties":{"name":{"type":"string"},"error":{"$ref":"#/components/schemas/hq_FieldErrorType"},"title":{"type":"string"},"pointer":{"description":"Holds a RFC-6901 JSON Pointer.","type":"string"}},"required":["name","error","title"]},"hq_FieldErrorType":{"type":"string","description":"Enumerates field validation error types.","enum":["reference_not_found","not_unique","invalid_value","other_error"]}}},"paths":{"/api/v1/groups/{name}":{"patch":{"description":"Updates a group.","operationId":"updateGroup","parameters":[{"in":"path","name":"name","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_UpdateGroupRequest"}}}},"responses":{"200":{"description":"Happy response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Group"}}}},"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_groups"]}}}}
```


---

# Agent Instructions: 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:

```
GET https://docs.lenses.io/latest/api-reference/6.1/reference/groups.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.