> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/xsoar-8-api/cortex-xsoar-8.x-apis/system-management.md).
# System Management
APIs for system management
## Get roles
> Retrieve information about one or more roles created in your environment.
```json
{"openapi":"3.0.1","info":{"title":"Cortex XSOAR 8 API","version":"XSOAR 8 Cloud"},"tags":[{"name":"System Management","description":"APIs for system management"}],"servers":[{"url":"https://api-yourfqdn","description":""}],"paths":{"/public_api/v1/rbac/get_roles":{"post":{"tags":["System Management"],"summary":"Get roles","description":"Retrieve information about one or more roles created in your environment.","parameters":[{"schema":{"type":"string"},"in":"header","name":"authorization","description":"api_key","required":true},{"schema":{"type":"string"},"in":"header","name":"x-xdr-auth-id","description":"api_key_id","required":true}],"operationId":"post-public_api-v1-rbac-get_roles","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"request_data":{"type":"object","properties":{"role_names":{"type":"array","description":"List of one or more role names in your environment for which you want detailed information.","items":{"type":"string"}}},"description":"A dictionary containing the API request fields."}}}}},"required":false},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"reply":{"type":"array","description":"JSON object containing the query result.","items":{"type":"object","properties":{"pretty_name":{"type":"string","description":"Name of the role as it appears in the Management Console."},"permissions":{"type":"array","description":"List of permissions associated with this role.","items":{"type":"string"}},"insert_time":{"type":"integer","description":"Timestamp of when the Role was created."},"update_time":{"type":"integer","description":"Timestamp of when the Role was last updated.Email of the user who created the Role.","nullable":true},"created_by":{"type":"string","description":"Email of the user who created the Role."},"description":{"type":"string","description":"Description of the Role, if available."},"groups":{"type":"array","description":"Group names associated with the Role.","items":{"type":"string"}},"users":{"type":"array","description":"Email addresses of users associated with the Role.","items":{"type":"string"}}}}}}}},"Example 1":{}}},"400":{"description":"Bad Request. Got an invalid JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"401":{"description":"Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"402":{"description":"Unauthorized access. User does not have the required license type to run this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"403":{"description":"Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"500":{"description":"Internal server error. A unified status for API communication type errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}}}}}},"components":{"schemas":{"reply":{"title":"reply","type":"object","properties":{"err_code":{"type":"string","description":"HTTP response code."},"err_msg":{"type":"string","description":"Error message."},"err_extra":{"type":"string","description":"Additional information describing the error."}},"description":"The query result upon error."}}}}
```
## Get user groups
> Retrieve a list of the current user emails associated with one or more user groups in your environment.
```json
{"openapi":"3.0.1","info":{"title":"Cortex XSOAR 8 API","version":"XSOAR 8 Cloud"},"tags":[{"name":"System Management","description":"APIs for system management"}],"servers":[{"url":"https://api-yourfqdn","description":""}],"paths":{"/public_api/v1/rbac/get_user_group":{"post":{"tags":["System Management"],"summary":"Get user groups","description":"Retrieve a list of the current user emails associated with one or more user groups in your environment.","parameters":[{"schema":{"type":"string"},"in":"header","name":"authorization","description":"api_key","required":true},{"schema":{"type":"string"},"in":"header","name":"x-xdr-auth-id","description":"api_key_id","required":true}],"operationId":"post-public_api-v1-rbac-get_user_group","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"request_data":{"type":"object","properties":{"group_names":{"type":"array","description":"List of one or more user group names for which you want the associated users.","items":{"type":"string"}}},"description":"A dictionary containing the API request fields."}}}}},"required":false},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"reply":{"type":"array","description":"JSON object containing the query result.","items":{"type":"object","properties":{"group_name":{"type":"string","description":"Name of the User Group."},"description":{"type":"string","description":"Description of the User Group, if available."},"pretty_name":{"type":"string","description":"Name of the User Group as it appears in the Management Console."},"insert_time":{"type":"integer","description":"Timestamp of when the User Group was created."},"update_time":{"type":"integer","description":"Timestamp of when the User Group was last updated."},"user_email":{"type":"array","description":"List of email addresses belonging to the users associated with the User Group.","items":{"type":"string"}},"source":{"type":"string","description":"Type of User Group."}}}}}}},"Example 1":{}}},"400":{"description":"Bad Request. Got an invalid JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"401":{"description":"Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"402":{"description":"Unauthorized access. User does not have the required license type to run this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"403":{"description":"Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"500":{"description":"Internal server error. A unified status for API communication type errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}}}}}},"components":{"schemas":{"reply":{"title":"reply","type":"object","properties":{"err_code":{"type":"string","description":"HTTP response code."},"err_msg":{"type":"string","description":"Error message."},"err_extra":{"type":"string","description":"Additional information describing the error."}},"description":"The query result upon error."}}}}
```
## Get users
> Retrieve a list of the current users in your environment.
```json
{"openapi":"3.0.1","info":{"title":"Cortex XSOAR 8 API","version":"XSOAR 8 Cloud"},"tags":[{"name":"System Management","description":"APIs for system management"}],"servers":[{"url":"https://api-yourfqdn","description":""}],"paths":{"/public_api/v1/rbac/get_users":{"post":{"tags":["System Management"],"summary":"Get users","description":"Retrieve a list of the current users in your environment.","parameters":[{"schema":{"type":"string"},"in":"header","name":"authorization","description":"api_key","required":true},{"schema":{"type":"string"},"in":"header","name":"x-xdr-auth-id","description":"api_key_id","required":true}],"operationId":"post-public_api-v1-rbac-get_users","requestBody":{"content":{"application/json":{"schema":{"type":"object"}}},"required":false},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"reply":{"type":"array","description":"JSON object containing the query result.","items":{"type":"object","properties":{"user_email":{"type":"string","description":"Email address of the user."},"user_first_name":{"type":"string","description":"First name of the user."},"user_last_name":{"type":"string","description":"Last name of the user."},"role_name":{"type":"string","description":"Role name associated with the user."},"last_logged_in":{"type":"integer","description":"Timestamp of when the user last logged in."},"user_type":{"type":"string","description":"Type of user."},"groups":{"type":"array","description":"Name of user groups associated with the user, if applicable.","items":{"type":"string"}},"scope":{"type":"array","description":"Name of scope associated with the user, if applicable.","items":{"type":"string"}}}}}}}},"Example 1":{}}},"400":{"description":"Bad Request. Got an invalid JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"401":{"description":"Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Unauthorized access. User does not have the required license type to run this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"403":{"description":"Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"500":{"description":"Internal server error. A unified status for API communication type errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}}}}}},"components":{"schemas":{"reply":{"title":"reply","type":"object","properties":{"err_code":{"type":"string","description":"HTTP response code."},"err_msg":{"type":"string","description":"Error message."},"err_extra":{"type":"string","description":"Additional information describing the error."}},"description":"The query result upon error."}}}}
```
## Set a user role
> Add or remove one or more users from a role.
```json
{"openapi":"3.0.1","info":{"title":"Cortex XSOAR 8 API","version":"XSOAR 8 Cloud"},"tags":[{"name":"System Management","description":"APIs for system management"}],"servers":[{"url":"https://api-yourfqdn","description":""}],"paths":{"/public_api/v1/rbac/set_user_role":{"post":{"tags":["System Management"],"summary":"Set a user role","description":"Add or remove one or more users from a role.","parameters":[{"schema":{"type":"string"},"in":"header","name":"authorization","description":"api_key","required":true},{"schema":{"type":"string"},"in":"header","name":"x-xdr-auth-id","description":"api_key_id","required":true}],"operationId":"post-public_api-v1-rbac-set_user_role","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"request_data":{"type":"object","properties":{"user_emails":{"type":"array","description":"List of one or more user emails of users you want to add to or remove from a role.","items":{"type":"string"}},"role_name":{"type":"string","description":"Name of the role you want to add a user to. Send an empty field to remove the user."}},"description":"A dictionary containing the API request fields."}}}}},"required":false},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"reply":{"type":"object","properties":{"update_count":{"type":"string","description":"Number of updated users."}},"description":"JSON object containing the query result."}}}},"Example 1":{}}},"400":{"description":"Bad Request. Got an invalid JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"401":{"description":"Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"402":{"description":"Unauthorized access. User does not have the required license type to run this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"403":{"description":"Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}}}}}},"components":{"schemas":{"reply":{"title":"reply","type":"object","properties":{"err_code":{"type":"string","description":"HTTP response code."},"err_msg":{"type":"string","description":"Error message."},"err_extra":{"type":"string","description":"Additional information describing the error."}},"description":"The query result upon error."}}}}
```
## Get System Health Metrics
> Retrieves system health metrics snapshots for the tenant. Each snapshot\
> contains node metrics, component statuses, storage usage, queue depths,\
> and external connectivity information.\
> \
> By default, returns data from the last 24 hours. Snapshots are ordered\
> by timestamp descending (most recent first).
> \\
>
> \
> \*\*Note:\*\* This endpoint is supported in XSOAR 8.13 On-prem and later.
```json
{"openapi":"3.0.1","info":{"title":"Cortex XSOAR 8 API","version":"XSOAR 8 Cloud"},"tags":[{"name":"System Management","description":"APIs for system management"}],"servers":[{"url":"https://api-yourfqdn","description":""}],"paths":{"/public_api/v1/system_diagnostics/data/papi/":{"post":{"tags":["System Management"],"summary":"Get System Health Metrics","description":"Retrieves system health metrics snapshots for the tenant. Each snapshot\ncontains node metrics, component statuses, storage usage, queue depths,\nand external connectivity information.\n\nBy default, returns data from the last 24 hours. Snapshots are ordered\nby timestamp descending (most recent first). \r\n\r\n**Note:** This endpoint is supported in XSOAR 8.13 On-prem and later. \n","parameters":[{"schema":{"type":"string"},"in":"header","name":"authorization","description":"api_key","required":true},{"schema":{"type":"string"},"in":"header","name":"x-xdr-auth-id","description":"api_key_id","required":true}],"operationId":"getSystemHealthMetrics","responses":{"200":{"description":"Successful response containing system diagnostics snapshots.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SystemDiagnosticsResponse"}}}},"400":{"description":"Bad Request. Got an invalid JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Unauthorized access. User does not have the required license type to run this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error. A unified status for API communication type errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"SystemDiagnosticsResponse":{"type":"object","required":["reply"],"properties":{"reply":{"$ref":"#/components/schemas/SystemDiagnosticsResults"}}},"SystemDiagnosticsResults":{"type":"object","required":["results"],"properties":{"results":{"type":"array","description":"List of system diagnostics snapshots ordered by timestamp descending (most recent first).","items":{"$ref":"#/components/schemas/SystemDiagnosticsSnapshot"}}}},"SystemDiagnosticsSnapshot":{"type":"object","description":"A point-in-time system diagnostics snapshot.","required":["timestamp"],"properties":{"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp of the diagnostics snapshot."},"nodes":{"type":"array","description":"List of node-level health metrics.","items":{"$ref":"#/components/schemas/NodeMetrics"}},"cluster_disk_usage":{"type":"number","format":"float","nullable":true,"description":"Cluster-wide disk usage percentage (0.0–100.0)."},"components":{"type":"object","description":"Component group names mapped to their health status. Possible statuses: HEALTHY, WARNING, ERROR.","additionalProperties":{"type":"string","enum":["HEALTHY","WARNING","ERROR"]}},"storage":{"type":"object","description":"Storage group names mapped to their usage percentage.","additionalProperties":{"type":"number","format":"float"}},"queues":{"type":"object","description":"Queue names mapped to their current depth (number of items).","additionalProperties":{"type":"integer"}},"connectivity":{"$ref":"#/components/schemas/ConnectivityStatus"}}},"NodeMetrics":{"type":"object","description":"Health metrics for a single cluster node.","required":["name","connected"],"properties":{"name":{"type":"string","description":"Node name identifier (typically the hostname or IP-based name)."},"cpu_usage":{"type":"number","format":"float","nullable":true,"description":"CPU usage percentage (0.0–100.0)."},"memory_usage":{"type":"number","format":"float","nullable":true,"description":"Memory usage percentage (0.0–100.0)."},"os_disk_usage":{"type":"number","format":"float","nullable":true,"description":"OS disk usage percentage (0.0–100.0)."},"connected":{"type":"boolean","description":"Whether the node is currently connected and reporting metrics."}}},"ConnectivityStatus":{"type":"object","description":"External connectivity status to Palo Alto Networks cloud services.","required":["connected"],"properties":{"connected":{"type":"boolean","description":"Whether external connectivity is currently established."},"since":{"type":"string","format":"date-time","nullable":true,"description":"ISO 8601 UTC timestamp of when the current connectivity status began. Null if no connectivity data is available."},"error":{"type":"string","nullable":true,"description":"Error message describing the connectivity issue. Null when connected successfully."}}},"ErrorResponse":{"type":"object","properties":{"reply":{"type":"object","properties":{"err_code":{"type":"integer","description":"HTTP response code."},"err_msg":{"type":"string","description":"Error message."},"err_extra":{"type":"string","nullable":true,"description":"Additional information describing the 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://cortex-docs.paloaltonetworks.com/xsoar-8-api/cortex-xsoar-8.x-apis/system-management.md?ask=&goal=
```
`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.