# Roles

Role-based access control management

## GET /api/v1/roles

> Returns all roles.

```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.1"},"tags":[{"name":"hq_roles","description":"Role-based access control 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_CompactRoleList":{"type":"object","description":"Contains a list of CompactRoles.","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/hq_CompactRole"}}},"required":["items"]},"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_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/roles":{"get":{"description":"Returns all roles.","operationId":"listRoles","responses":{"200":{"description":"Happy response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_CompactRoleList"}}}},"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_roles"]}}}}
```

## POST /api/v1/roles

> Creates a new role.

```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.1"},"tags":[{"name":"hq_roles","description":"Role-based access control 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_CreateRoleRequest":{"type":"object","description":"Contains the fields needed to create a role.","properties":{"name":{"type":"string","description":"Sets the unique name of the new role. 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,"format":"hq-resource-name"},"display_name":{"type":"string","description":"Sets the display name of the new role. If not provided, the value of\n\"name\" will be used.\n","minLength":1,"maxLength":150},"description":{"type":"string","description":"Sets the description of the new role.","maxLength":280},"policy":{"type":"array","description":"Contains a list of permission statements.","items":{"$ref":"#/components/schemas/hq_PermissionStatement"}},"metadata":{"$ref":"#/components/schemas/hq_Metadata"}},"required":["name","policy"]},"hq_PermissionStatement":{"type":"object","description":"Describes the effect for an action and resource.","properties":{"effect":{"$ref":"#/components/schemas/hq_PermissionEffect"},"action":{"$ref":"#/components/schemas/hq_PermissionActionScalarOrList"},"resource":{"$ref":"#/components/schemas/hq_PermissionResourceScalarOrList"}},"required":["effect","action","resource"]},"hq_PermissionEffect":{"type":"string","description":"Enumerates permission effects.","enum":["allow","deny"]},"hq_PermissionActionScalarOrList":{"description":"Is either a single action or a list of actions.","oneOf":[{"type":"string"},{"type":"array","minItems":1,"items":{"type":"string"}}]},"hq_PermissionResourceScalarOrList":{"description":"Is either a single string or a list of strings.","oneOf":[{"type":"string"},{"type":"array","minItems":1,"items":{"type":"string"}}]},"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_Role":{"type":"object","description":"Bundles a list of permission statements with a name.","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":{"type":"array","items":{"$ref":"#/components/schemas/hq_PermissionStatement"}},"metadata":{"$ref":"#/components/schemas/hq_Metadata"}},"required":["name","display_name","lrn","description","id","created_at","policy"]},"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/roles":{"post":{"description":"Creates a new role.","operationId":"createRole","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_CreateRoleRequest"}}}},"responses":{"201":{"description":"Happy response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Role"}}}},"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_roles"]}}}}
```

## POST /api/v1/roles/{name}/policy

> Adds a permission statement to an existing Role's policy. No deduplication is done.

```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.1"},"tags":[{"name":"hq_roles","description":"Role-based access control 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_PermissionStatement":{"type":"object","description":"Describes the effect for an action and resource.","properties":{"effect":{"$ref":"#/components/schemas/hq_PermissionEffect"},"action":{"$ref":"#/components/schemas/hq_PermissionActionScalarOrList"},"resource":{"$ref":"#/components/schemas/hq_PermissionResourceScalarOrList"}},"required":["effect","action","resource"]},"hq_PermissionEffect":{"type":"string","description":"Enumerates permission effects.","enum":["allow","deny"]},"hq_PermissionActionScalarOrList":{"description":"Is either a single action or a list of actions.","oneOf":[{"type":"string"},{"type":"array","minItems":1,"items":{"type":"string"}}]},"hq_PermissionResourceScalarOrList":{"description":"Is either a single string or a list of strings.","oneOf":[{"type":"string"},{"type":"array","minItems":1,"items":{"type":"string"}}]},"hq_Role":{"type":"object","description":"Bundles a list of permission statements with a name.","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":{"type":"array","items":{"$ref":"#/components/schemas/hq_PermissionStatement"}},"metadata":{"$ref":"#/components/schemas/hq_Metadata"}},"required":["name","display_name","lrn","description","id","created_at","policy"]},"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/roles/{name}/policy":{"post":{"description":"Adds a permission statement to an existing Role's policy. No deduplication is done.","operationId":"addPermissionStatementToRole","parameters":[{"in":"path","name":"name","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_PermissionStatement"}}}},"responses":{"200":{"description":"Happy response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Role"}}}},"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_roles"]}}}}
```

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

> Returns a specific role.

```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.1"},"tags":[{"name":"hq_roles","description":"Role-based access control 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_Role":{"type":"object","description":"Bundles a list of permission statements with a name.","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":{"type":"array","items":{"$ref":"#/components/schemas/hq_PermissionStatement"}},"metadata":{"$ref":"#/components/schemas/hq_Metadata"}},"required":["name","display_name","lrn","description","id","created_at","policy"]},"hq_PermissionStatement":{"type":"object","description":"Describes the effect for an action and resource.","properties":{"effect":{"$ref":"#/components/schemas/hq_PermissionEffect"},"action":{"$ref":"#/components/schemas/hq_PermissionActionScalarOrList"},"resource":{"$ref":"#/components/schemas/hq_PermissionResourceScalarOrList"}},"required":["effect","action","resource"]},"hq_PermissionEffect":{"type":"string","description":"Enumerates permission effects.","enum":["allow","deny"]},"hq_PermissionActionScalarOrList":{"description":"Is either a single action or a list of actions.","oneOf":[{"type":"string"},{"type":"array","minItems":1,"items":{"type":"string"}}]},"hq_PermissionResourceScalarOrList":{"description":"Is either a single string or a list of strings.","oneOf":[{"type":"string"},{"type":"array","minItems":1,"items":{"type":"string"}}]},"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/roles/{name}":{"get":{"description":"Returns a specific role.","operationId":"getRole","parameters":[{"in":"path","name":"name","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Happy response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Role"}}}},"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_roles"]}}}}
```

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

> Deletes a role.

```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.1"},"tags":[{"name":"hq_roles","description":"Role-based access control 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/roles/{name}":{"delete":{"description":"Deletes a role.","operationId":"deleteRole","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_roles"]}}}}
```

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

> Updates a role.

```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.1"},"tags":[{"name":"hq_roles","description":"Role-based access control 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_UpdateRoleRequest":{"type":"object","description":"Updates a role. Absent fields are left untouched.","properties":{"display_name":{"type":"string","description":"Updates the display name of the role.","minLength":1,"maxLength":150},"description":{"type":"string","description":"Updates the description of the role.","maxLength":280},"policy":{"type":"array","description":"Sets, if specififed, the new permission statements.","items":{"$ref":"#/components/schemas/hq_PermissionStatement"}},"metadata":{"$ref":"#/components/schemas/hq_MetadataPatchRequest"}}},"hq_PermissionStatement":{"type":"object","description":"Describes the effect for an action and resource.","properties":{"effect":{"$ref":"#/components/schemas/hq_PermissionEffect"},"action":{"$ref":"#/components/schemas/hq_PermissionActionScalarOrList"},"resource":{"$ref":"#/components/schemas/hq_PermissionResourceScalarOrList"}},"required":["effect","action","resource"]},"hq_PermissionEffect":{"type":"string","description":"Enumerates permission effects.","enum":["allow","deny"]},"hq_PermissionActionScalarOrList":{"description":"Is either a single action or a list of actions.","oneOf":[{"type":"string"},{"type":"array","minItems":1,"items":{"type":"string"}}]},"hq_PermissionResourceScalarOrList":{"description":"Is either a single string or a list of strings.","oneOf":[{"type":"string"},{"type":"array","minItems":1,"items":{"type":"string"}}]},"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_Role":{"type":"object","description":"Bundles a list of permission statements with a name.","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":{"type":"array","items":{"$ref":"#/components/schemas/hq_PermissionStatement"}},"metadata":{"$ref":"#/components/schemas/hq_Metadata"}},"required":["name","display_name","lrn","description","id","created_at","policy"]},"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/roles/{name}":{"patch":{"description":"Updates a role.","operationId":"updateRole","parameters":[{"in":"path","name":"name","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_UpdateRoleRequest"}}}},"responses":{"200":{"description":"Happy response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Role"}}}},"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_roles"]}}}}
```


---

# 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/roles.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.