> 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/xpanse-api/xpanse-public-api/incident-management.md). # Incident Management APIs for managing incidents ## Get Alerts > Get a single alert or list of alerts with multiple events.\ > \- Response is concatenated using AND condition (OR is not supported).\ > \- Maximum result set size is 100.\ > \- Offset is the zero-based number of alerts from the start of the result set.\ > \ > \
Note: You can send a request to retrieve all or filtered results. \
Required license: \*\*Cortex Xpanse Expander\*\*
```json {"openapi":"3.0.2","info":{"title":"Cortex Xpanse REST API","version":"2.12.0"},"tags":[{"name":"Incident Management","description":"APIs for managing incidents"}],"servers":[{"url":"https://api-{{fqdn}}"}],"paths":{"/public_api/v2/alerts/get_alerts_multi_events/":{"post":{"parameters":[{"in":"header","name":"authorization","description":"api-key","schema":{"type":"string"},"required":true},{"in":"header","name":"x-xdr-auth-id","description":"api-key-id","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetAlertsMultiEventsResponse"}}}},"400":{"description":"Bad Request. Got an invalid JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultApiErrorResponse"}}}},"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/DefaultApiErrorResponse"}}}},"402":{"description":"Unauthorized access. User does not have the required license type to run this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultApiErrorResponse"}}}},"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/DefaultApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_ENTITY"},"500":{"description":"Internal server error. A unified status for API communication type errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultApiErrorResponse"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetAlertsMultiEventsRequest"}}},"description":"If no parameters are included, all results will be returned."},"summary":"Get Alerts","description":"Get a single alert or list of alerts with multiple events.\n - Response is concatenated using AND condition (OR is not supported).\n - Maximum result set size is 100.\n - Offset is the zero-based number of alerts from the start of the result set.\n\n
Note: You can send a request to retrieve all or filtered results.
Required license: **Cortex Xpanse Expander**\n","tags":["Incident Management"]}}},"components":{"schemas":{"GetAlertsMultiEventsResponse":{"type":"object","properties":{"reply":{"$ref":"#/components/schemas/GetAlertsMultiEventsPage"}},"required":["reply"],"additionalProperties":true},"GetAlertsMultiEventsPage":{"type":"object","properties":{"total_count":{"type":"integer","description":"The number of total results of this filter without paging. If the filter returned 10,000 results or more than 9,999 will be the value and you can use paging to view the entire set of data."},"result_count":{"type":"integer","description":"The number of alerts actually returned as result (integer)."},"alerts":{"type":"array","items":{"$ref":"#/components/schemas/Alert"},"description":"A list of alerts."},"next_page_token":{"type":"string","description":"This attribute is only returned if use_page_token is provided in the request with value true"}},"required":["result_count","total_count"],"additionalProperties":true},"Alert":{"type":"object","properties":{"category":{"type":"string"},"project":{"type":"string"},"cloud_provider":{"type":"string"},"resource_sub_type":{"type":"string"},"resource_type":{"type":"string"},"action_country":{"type":"array","items":{"type":"string"}},"description":{"type":"string"},"events":{"type":"string"},"event_type":{"type":"string"},"is_whitelisted":{"type":"boolean"},"image_name":{"type":"string"},"action_local_ip":{"type":"string"},"action_local_port":{"type":"string"},"mitre_tactic_id_and_name":{"type":"array","items":{"type":"string"}},"mitre_technique_id_and_name":{"type":"array","items":{"type":"string"}},"action_external_hostname":{"type":"string"},"action_remote_ip":{"type":"array","items":{"type":"string"}},"action_remote_port":{"type":"array","items":{"type":"integer"}},"matching_service_rule_id":{"type":"string"},"starred":{"type":"boolean"},"external_id":{"type":"string"},"severity":{"type":"string"},"matching_status":{"type":"string"},"end_match_attempt_ts":{"type":"string"},"local_insert_ts":{"type":"integer","description":"The UNIX timestamp that this record was written to the database"},"last_modified_ts":{"type":"integer","description":"The UNIX timestamp that this record was last modified"},"case_id":{"type":"integer"},"deduplicate_tokens":{"type":"string"},"filter_rule_id":{"type":"string"},"event_id":{"type":"string"},"event_timestamp":{"type":"array","items":{"type":"integer"}},"action_local_ip_v6":{"type":"string"},"action_remote_ip_v6":{"type":"array","items":{"type":"string"}},"alert_type":{"type":"string"},"resolution_status":{"type":"string"},"resolution_comment":{"type":"string"},"dynamic_fields":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"malicious_urls":{"type":"string"},"asm_alert_categories":{"type":"array","items":{"type":"string"}},"aws_cloud_tags":{"type":"array","items":{"type":"string"}},"azure_cloud_tags":{"type":"array","items":{"type":"string"}},"gcp_cloud_tags":{"type":"array","items":{"type":"string"}},"last_observed":{"type":"integer"},"country_codes":{"type":"array","items":{"type":"string"}},"cloud_providers":{"type":"array","items":{"type":"string"}},"ipv4_addresses":{"type":"array","items":{"type":"string"}},"ipv6_addresses":{"type":"array","items":{"type":"string"}},"domain_names":{"type":"array","items":{"type":"string"}},"service_ids":{"type":"array","items":{"type":"string"}},"website_ids":{"type":"array","items":{"type":"string"}},"asset_ids":{"type":"array","items":{"type":"string"}},"certificate":{"$ref":"#/components/schemas/IncidentCertificate"},"port_protocol":{"type":"string"},"port_number":{"type":"integer"},"cloud_management_status":{"type":"string"},"business_unit_hierarchies":{"type":"array","items":{"type":"array","items":{"$ref":"#/components/schemas/BusinessUnitHierarchy"}}},"attack_surface_rule_name":{"type":"string"},"remediation_guidance":{"type":"string"},"attack_surface_rule_id":{"type":"string"},"asset_identifiers":{"type":"array","items":{"$ref":"#/components/schemas/AssetIdentifiers"}},"integration_source":{"type":"string"},"alert_id":{"type":"string"},"detection_timestamp":{"type":"integer"},"name":{"type":"string"},"endpoint_id":{"type":"string"},"host_ip":{"type":"string"},"host_name":{"type":"string"},"action":{"type":"string"},"source":{"type":"string"},"user_name":{"type":"string"},"mac_addresses":{"type":"string"},"action_pretty":{"type":"string"}},"additionalProperties":true},"IncidentCertificate":{"type":"object","properties":{"issuerName":{"type":"string"},"subjectName":{"type":"string"},"validNotBefore":{"type":"integer"},"validNotAfter":{"type":"integer"},"serialNumber":{"type":"string"}},"additionalProperties":true},"BusinessUnitHierarchy":{"type":"object","properties":{"creation_time":{"type":"integer"},"family":{"type":"string"},"family_alias":{"type":"string"},"id":{"type":"string"},"is_active":{"type":"integer"},"name":{"type":"string"},"parent_id":{"type":"string"},"update_time":{"type":"integer"}},"additionalProperties":true},"AssetIdentifiers":{"type":"object","properties":{"domain":{"type":"string"},"certificate":{"$ref":"#/components/schemas/IncidentCertificate"},"ipv4Address":{"type":"string"},"ipv6Address":{"type":"string"},"httpPath":{"type":"string"},"portNumber":{"type":"integer"},"portProtocol":{"type":"string"},"firstObserved":{"type":"integer"},"lastObserved":{"type":"integer"}},"additionalProperties":true},"DefaultApiErrorResponse":{"type":"object","properties":{"reply":{"description":"The query results upon error.","allOf":[{"$ref":"#/components/schemas/GenericReply"}]}},"required":["reply"],"additionalProperties":true},"GenericReply":{"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."}},"additionalProperties":true},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors"}}},"GetAlertsMultiEventsRequest":{"type":"object","properties":{"request_data":{"$ref":"#/components/schemas/GetAlertsMultiEventsRequestData"}},"required":["request_data"],"additionalProperties":true},"GetAlertsMultiEventsRequestData":{"type":"object","description":"A dictionary containing the API request fields. An empty dictionary returns all results.\n","properties":{"filters":{"type":"array","description":"An array of filter fields.","items":{"$ref":"#/components/schemas/AlertFilter"}},"search_from":{"type":"integer","default":0,"minimum":0,"description":"An integer representing the starting offset within the query result set from which you want alerts returned. Alerts are returned as a zero-based list. Any alert indexed less than this value is not returned in the final result set and defaults to zero.\n"},"search_to":{"type":"integer","default":100,"minimum":0,"description":"An integer representing the end offset within the result set after which you do not want alerts returned. Alerts in the alerts list that are indexed higher than this value are not returned in the final results set. Defaults to 100, which returns all alerts to the end of the list. Use this field to specify the number of results on a page when using page token pagination.\n
Max value - 100\n"},"sort":{"$ref":"#/components/schemas/AlertSort"},"use_page_token":{"type":"boolean","description":"Use `\"use_page_token\":true` in the initial request to paginate the response data.\n"},"next_page_token":{"type":"string","description":"If `\"use_page_token\":true` was included in the initial request, the response for that request will include a page token. Use `\"next_page_token\":\"string\"` to pass that page token into the next request to paginate the next set of data."}}},"AlertFilter":{"type":"object","properties":{"field":{"type":"string","enum":["business_units_list","tags","asm_alert_categories","attack_surface_rule_id","alert_id_list","external_id_list","alert_source","creation_time","last_modified_ts","server_creation_time","severity","status","attack_surface_rule_name","host_name","xpanse_policy_id","case_id_list","cloud_management_status","integration_source","aws_cloud_tags","gcp_cloud_tags","azure_cloud_tags","first_observed","last_observed"],"description":"Identifies the alert fields the filter is matching. \n "},"operator":{"type":"string","enum":["gte","lte","in","range","relative_timestamp"],"description":"String that identifies the comparison operator you want to use for this filter. Possible values:\n - **in**— use with `alert_id_list`, `alert_source`, `asm_alert_categories`, `case_id_list`, `business_units_list`, `cloud_management_status`, `tags`, `xpanse_policy_id`, `severity`, `integration_source`\n - **gte**— Filters data from a specific timestamp onwards. Use with `creation_time`, `first_observed`, `last_observed`.\n - **lte**— Filters data up to a specific timestamp. Use with `creation_time`, `first_observed`, `last_observed`.\n - **range**— Filters data between two specific timestamps. Use with `first_observed`, `last_observed`.\n - **relative_timestamp**— Filters data relative to the current time (e.g., last 30 days). Use with `first_observed`, `last_observed`."},"value":{"oneOf":[{"type":"string"},{"type":"integer"},{"type":"array","items":{"type":"string"}}],"description":"Value that this filter must match. The contents of this field will differ depending on the alert field that you specified for this filter:\n - **alert_id_list** — List of integers. Each item in the list must be an alert ID.\n - **alert_source** — List of strings.\n - **asm_alert_categories** — List of strings. Example values: \"Development Infrastructure\", \"Unpatched, Misconfigured, and end-of-life (EOL) systems\".\n - **business_units_list** — String or list of strings in the format \"BU name\" or \"BU:BU name\", for example “Acme & Co, Inc.” or “BU:Acme & Co, Inc.”\n - **case_id_list** — List of integers. Each item in the list must be a case ID.\n - **cloud_management_status** — String. Values are `Managed Cloud`, `Unmanaged Cloud`, and `Not Applicable`.\n - **creation_time** — Integer representing the number of seconds or milliseconds after the Unix epoch, UTC timezone. The value is returned in the response under the detection_timestamp field and represented in the console under the TIMESTAMP field.\n - **external_id_list**— List of strings representing external IDs.\n - **first_observed** — Values in milliseconds format\n - with **gte** or **lte** operator, specify a specific date or time as a timestamp in milliseconds format\n - with **range** operator, specify \"to\" and \"from\" values as timestamps in milliseconds format\n \"value\": { \"from\": \"{{previous30Days}}\",\"to\": \"{{previous7Days}}\"\n - with **relative_timestamp** operator, specify time interval to look back on (24H, 7D, 30D, etc.) as a value in milliseconds format\n - **integration_source** — Valid values: `AWS`, `AZURE`, `GOOGLE`, `PRISMA_CLOUD`\n - **last_observed** — values in milliseconds format\n - with **gte** or **lte** operator, specify a specific date or time as a timestamp in milliseconds format\n - with **range** operator, specify \"to\" and \"from\" values as timestamps in milliseconds format, as follows\n \"value\": { \"from\": \"{{previous30Days}}\",\"to\": \"{{previous7Days}}\"\n - with **relative_timestamp** operator, specify time interval to look back on (24H, 7D, 30D, etc.) as a value in milliseconds format\n - **severity** — Valid values: `low`, `medium`, `high`, `critical`, `informational`\n - **status** — Valid values: `new`, `reopened`, `resolved_no_risk`, `resolved_risk_accepted`, `resolved_no_longer_observed`, `resolved_contested_asset`, `resolved_remediated_automatically`, `resolved`, `under_investigation`.\n - **tags** — List of strings indicating the tags to filter on in the format `\"tag-family:tag-name\"`, for example `\"AR:registered to you\"`.\n - **xpanse_policy_id** — List of strings representing the xpanse policy IDs."}}},"AlertSort":{"type":"object","properties":{"field":{"type":"string","default":"creation_time","enum":["creation_time","severity","server_creation_time"],"description":"Can either be `severity` or `creation_time`."},"keyword":{"type":"string","default":"desc","enum":["ASC","asc","DESC","desc"],"description":"Can either be ASC (ascending order) or DESC (descending order). Case sensitive."}},"additionalProperties":true,"description":"Identifies the sort order for the result set. "}},"responses":{"UNPROCESSABLE_ENTITY":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}} ``` ## Get Incidents > Get details for a single incident or a list of incidents filtered by a list of severity or creation time. - The response is concatenated using AND condition (OR is not supported).\
- The maximum result set size is >100.\
- Offset is the zero-based number of incidents from the start of the result set.\
\
Note: You can send a request to retrieve either \*\*all\*\* or \*\*filtered\*\* results.\
\
Required license: \*\*Cortex Xpanse Expander\*\* \

```json {"openapi":"3.0.2","info":{"title":"Cortex Xpanse REST API","version":"2.12.0"},"tags":[{"name":"Incident Management","description":"APIs for managing incidents"}],"servers":[{"url":"https://api-{{fqdn}}"}],"paths":{"/public_api/v1/incidents/get_incidents/":{"post":{"parameters":[{"in":"header","name":"authorization","description":"api-key","schema":{"type":"string"},"required":true},{"in":"header","name":"x-xdr-auth-id","description":"api-key-id","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetIncidentsResponse"}}}},"400":{"description":"Bad Request. Got an invalid JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultApiErrorResponse"}}}},"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/DefaultApiErrorResponse"}}}},"402":{"description":"Unauthorized access. User does not have the required license type to run this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultApiErrorResponse"}}}},"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/DefaultApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_ENTITY"},"500":{"description":"Internal server error. A unified status for API communication type errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultApiErrorResponse"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetIncidentsRequest"}}},"description":"If no parameters are included, all results will be returned."},"summary":"Get Incidents","description":"Get details for a single incident or a list of incidents filtered by a list of severity or creation time. - The response is concatenated using AND condition (OR is not supported).
- The maximum result set size is >100.
- Offset is the zero-based number of incidents from the start of the result set.

Note: You can send a request to retrieve either **all** or **filtered** results.

Required license: **Cortex Xpanse Expander**
\n","tags":["Incident Management"]}}},"components":{"schemas":{"GetIncidentsResponse":{"type":"object","properties":{"reply":{"$ref":"#/components/schemas/GetIncidentsPage"}},"required":["reply"],"additionalProperties":true},"GetIncidentsPage":{"type":"object","properties":{"total_count":{"type":"integer"},"result_count":{"type":"integer"},"incidents":{"type":"array","items":{"$ref":"#/components/schemas/Incident"}},"restricted_incident_ids":{"type":"array","items":{"type":"string"}}},"required":["result_count","total_count"],"additionalProperties":true},"Incident":{"type":"object","properties":{"incident_id":{"type":"string"},"is_blocked":{"type":"boolean"},"incident_name":{"type":"string"},"creation_time":{"type":"integer"},"modification_time":{"type":"integer"},"detection_time":{"type":"integer"},"status":{"type":"string"},"severity":{"type":"string"},"description":{"type":"string"},"assigned_user_mail":{"type":"string"},"assigned_user_pretty_name":{"type":"string"},"alert_count":{"type":"integer"},"low_severity_alert_count":{"type":"integer"},"med_severity_alert_count":{"type":"integer"},"high_severity_alert_count":{"type":"integer"},"critical_severity_alert_count":{"type":"integer"},"user_count":{"type":"integer"},"host_count":{"type":"integer"},"notes":{"type":"string"},"resolve_comment":{"type":"string"},"resolved_timestamp":{"type":"integer"},"manual_severity":{"type":"string"},"manual_description":{"type":"string"},"xdr_url":{"type":"string"},"starred":{"type":"boolean"},"starred_manually":{"type":"boolean"},"hosts":{"type":"array","items":{"type":"string"}},"incident_sources":{"type":"array","items":{"type":"string"}},"rule_based_score":{"type":"integer"},"manual_score":{"type":"number"},"aggregated_score":{"type":"integer"},"alerts_grouping_status":{"type":"string"},"alert_categories":{"type":"array","items":{"type":"string"}},"original_tags":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"xpanse_risk_score":{"type":"integer"},"xpanse_risk_explainer":{"$ref":"#/components/schemas/XpanseRiskExplainer"},"cloud_management_status":{"type":"string"},"integration_source":{"type":"string"},"ipv4_addresses":{"type":"array","items":{"type":"string"}},"ipv6_addresses":{"type":"array","items":{"type":"string"}},"domain_names":{"type":"array","items":{"type":"string"}},"port_number":{"type":"integer"},"asset_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"ip_range_ids":{"type":"array","items":{"type":"string"}},"website_ids":{"type":"array","items":{"type":"string"}},"service_ids":{"type":"array","items":{"type":"string"}},"last_observed":{"type":"integer"},"cloud_providers":{"type":"array","items":{"type":"string"}},"country_codes":{"type":"array","items":{"type":"string"}},"certificate_common_names":{"type":"array","items":{"type":"string"}},"certificate_issuers":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"XpanseRiskExplainer":{"type":"object","properties":{"cves":{"type":"array","items":{"$ref":"#/components/schemas/Cve"}},"riskFactors":{"type":"array","items":{"$ref":"#/components/schemas/RiskFactor"}},"versionMatched":{"type":"boolean"}},"additionalProperties":true},"Cve":{"type":"object","properties":{"cveId":{"type":"string"},"cvssScore":{"type":"integer"},"epssScore":{"type":"number"},"matchType":{"type":"string"},"exploitMaturity":{"type":"string"},"reportedExploitInTheWild":{"type":"boolean"},"mostRecentReportedExploitDate":{"type":"string"},"confidence":{"type":"string"}},"additionalProperties":true},"RiskFactor":{"type":"object","properties":{"attributeId":{"type":"string"},"attributeName":{"type":"string"},"issueTypes":{"type":"array","items":{"$ref":"#/components/schemas/RiskFactorIssueType"}}},"required":["attributeId","attributeName","issueTypes"],"additionalProperties":true},"RiskFactorIssueType":{"type":"object","properties":{"displayName":{"type":"string"},"issueTypeId":{"type":"string"}},"required":["displayName","issueTypeId"],"additionalProperties":true},"DefaultApiErrorResponse":{"type":"object","properties":{"reply":{"description":"The query results upon error.","allOf":[{"$ref":"#/components/schemas/GenericReply"}]}},"required":["reply"],"additionalProperties":true},"GenericReply":{"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."}},"additionalProperties":true},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors"}}},"GetIncidentsRequest":{"type":"object","properties":{"request_data":{"$ref":"#/components/schemas/GetIncidentsRequestData"}},"required":["request_data"],"additionalProperties":true},"GetIncidentsRequestData":{"type":"object","description":"A dictionary containing the API request fields. An empty dictionary returns all results.","properties":{"filters":{"type":"array","description":"Array of filter fields.","items":{"$ref":"#/components/schemas/IncidentFilter"}},"search_from":{"type":"integer","default":0,"minimum":0,"description":"Integer representing the starting offset within the query result set from which you want incidents returned. Incidents are returned as a zero-based list. Any incident indexed less than this value is not returned in the final result set and defaults to zero.\n"},"search_to":{"type":"integer","default":100,"minimum":0,"description":"Integer representing the end offset within the result set after which you do not want incidents returned. Incidents in the incident list that are indexed higher than this value are not returned in the final results set. Defaults to >100, which returns all incidents to the end of the list.\n"},"sort":{"$ref":"#/components/schemas/IncidentSort"}}},"IncidentFilter":{"type":"object","properties":{"field":{"type":"string","enum":["modification_time","description","creation_time","alert_sources","incident_id_list","status","cloud_management_status","starred","incident_id","integration_source"],"description":"Identifies the incident field the filter is matching. \n "},"operator":{"type":"string","enum":["in","contains","neq","eq","lte","gte"],"description":"Identifies the comparison operator you want to use for this filter. Valid keywords are:\n- **in**: `incident_id_list`, `alert_sources`, `cloud_management_status`, `description`, `integration_source`\n- **contains**: `description` \n- **gte** / **lte**: `modification_time`, `creation_time`: Integer in timestamp epoch milliseconds \n- **eq** / **nqe**: `status`\n"},"value":{"oneOf":[{"type":"string"},{"type":"integer"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"integer"}}],"description":"Value that this filter must match. The contents of this field will differ depending on the incident field that you specified for this filter:\n - alert_sources: String\n - cloud_management_status: String. Values are `Managed Cloud`, `Unmanaged Cloud`, and `Not Applicable`.\n - creation_time:`Integer in timestamp epoch milliseconds\n - description: String\n - incident_id_list: List of strings. Each item in the list must be an incident ID.\n - integration_source: List of strings. Valid values: `AWS`, `AZURE`, `GOOGLE`, `PRISMA_CLOUD`\n - modification_time: `Integer` in timestamp epoch milliseconds\n - status: Valid values: `new`, `under_investigation`, `resolved`\n"}}},"IncidentSort":{"type":"object","properties":{"field":{"type":"string","default":"modification_time","enum":["creation_time","modification_time","incident_id"],"description":"Can be `creation_time` or `severity`."},"keyword":{"type":"string","default":"desc","enum":["ASC","asc","DESC","desc"],"description":"Can either be `ASC` (ascending order) or `DESC` (descending order)."}},"additionalProperties":true,"description":"Identifies the sort order for the result set. Default sort is defined as `creation_time`, `DESC`."}},"responses":{"UNPROCESSABLE_ENTITY":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}} ``` ## Get Extra Incident Data > Get extra data fields for a specific incident including alerts and key artifacts.\ > \ > Note: The API includes a limit rate of 10 API requests per minute.\ > \ > Required license: Cortex Xpanse Expander
```json {"openapi":"3.0.2","info":{"title":"Cortex Xpanse REST API","version":"2.12.0"},"tags":[{"name":"Incident Management","description":"APIs for managing incidents"}],"servers":[{"url":"https://api-{{fqdn}}"}],"paths":{"/public_api/v1/incidents/get_incident_extra_data/":{"post":{"parameters":[{"in":"header","name":"authorization","description":"api-key","schema":{"type":"string"},"required":true},{"in":"header","name":"x-xdr-auth-id","description":"api-key-id","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetIncidentExtraDataResponse"}}}},"400":{"description":"Bad Request. Got an invalid JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultApiErrorResponse"}}}},"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/DefaultApiErrorResponse"}}}},"402":{"description":"Unauthorized access. User does not have the required license type to run this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultApiErrorResponse"}}}},"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/DefaultApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_ENTITY"},"429":{"description":"Exceeded 10 requests in a 60-second window.\r\n\r\nIf you get this response, wait 60 seconds and retry your request. \r\n"},"500":{"description":"Internal server error. A unified status for API communication type errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultApiErrorResponse"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetIncidentExtraDataRequest"}}}},"summary":"Get Extra Incident Data","description":"Get extra data fields for a specific incident including alerts and key artifacts.\n\nNote: The API includes a limit rate of 10 API requests per minute.\n\nRequired license: Cortex Xpanse Expander\n","tags":["Incident Management"]}}},"components":{"schemas":{"GetIncidentExtraDataResponse":{"type":"object","properties":{"reply":{"$ref":"#/components/schemas/GetIncidentExtraDataReply"}},"required":["reply"],"additionalProperties":true},"GetIncidentExtraDataReply":{"type":"object","properties":{"incident":{"$ref":"#/components/schemas/Incident"},"alerts":{"$ref":"#/components/schemas/IncidentExtraDataAlerts"},"network_artifacts":{"$ref":"#/components/schemas/NetworkArtifacts"},"file_artifacts":{"$ref":"#/components/schemas/FileArtifacts"}},"additionalProperties":true},"Incident":{"type":"object","properties":{"incident_id":{"type":"string"},"is_blocked":{"type":"boolean"},"incident_name":{"type":"string"},"creation_time":{"type":"integer"},"modification_time":{"type":"integer"},"detection_time":{"type":"integer"},"status":{"type":"string"},"severity":{"type":"string"},"description":{"type":"string"},"assigned_user_mail":{"type":"string"},"assigned_user_pretty_name":{"type":"string"},"alert_count":{"type":"integer"},"low_severity_alert_count":{"type":"integer"},"med_severity_alert_count":{"type":"integer"},"high_severity_alert_count":{"type":"integer"},"critical_severity_alert_count":{"type":"integer"},"user_count":{"type":"integer"},"host_count":{"type":"integer"},"notes":{"type":"string"},"resolve_comment":{"type":"string"},"resolved_timestamp":{"type":"integer"},"manual_severity":{"type":"string"},"manual_description":{"type":"string"},"xdr_url":{"type":"string"},"starred":{"type":"boolean"},"starred_manually":{"type":"boolean"},"hosts":{"type":"array","items":{"type":"string"}},"incident_sources":{"type":"array","items":{"type":"string"}},"rule_based_score":{"type":"integer"},"manual_score":{"type":"number"},"aggregated_score":{"type":"integer"},"alerts_grouping_status":{"type":"string"},"alert_categories":{"type":"array","items":{"type":"string"}},"original_tags":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"xpanse_risk_score":{"type":"integer"},"xpanse_risk_explainer":{"$ref":"#/components/schemas/XpanseRiskExplainer"},"cloud_management_status":{"type":"string"},"integration_source":{"type":"string"},"ipv4_addresses":{"type":"array","items":{"type":"string"}},"ipv6_addresses":{"type":"array","items":{"type":"string"}},"domain_names":{"type":"array","items":{"type":"string"}},"port_number":{"type":"integer"},"asset_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"ip_range_ids":{"type":"array","items":{"type":"string"}},"website_ids":{"type":"array","items":{"type":"string"}},"service_ids":{"type":"array","items":{"type":"string"}},"last_observed":{"type":"integer"},"cloud_providers":{"type":"array","items":{"type":"string"}},"country_codes":{"type":"array","items":{"type":"string"}},"certificate_common_names":{"type":"array","items":{"type":"string"}},"certificate_issuers":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"XpanseRiskExplainer":{"type":"object","properties":{"cves":{"type":"array","items":{"$ref":"#/components/schemas/Cve"}},"riskFactors":{"type":"array","items":{"$ref":"#/components/schemas/RiskFactor"}},"versionMatched":{"type":"boolean"}},"additionalProperties":true},"Cve":{"type":"object","properties":{"cveId":{"type":"string"},"cvssScore":{"type":"integer"},"epssScore":{"type":"number"},"matchType":{"type":"string"},"exploitMaturity":{"type":"string"},"reportedExploitInTheWild":{"type":"boolean"},"mostRecentReportedExploitDate":{"type":"string"},"confidence":{"type":"string"}},"additionalProperties":true},"RiskFactor":{"type":"object","properties":{"attributeId":{"type":"string"},"attributeName":{"type":"string"},"issueTypes":{"type":"array","items":{"$ref":"#/components/schemas/RiskFactorIssueType"}}},"required":["attributeId","attributeName","issueTypes"],"additionalProperties":true},"RiskFactorIssueType":{"type":"object","properties":{"displayName":{"type":"string"},"issueTypeId":{"type":"string"}},"required":["displayName","issueTypeId"],"additionalProperties":true},"IncidentExtraDataAlerts":{"type":"object","properties":{"total_count":{"type":"integer"},"data":{"type":"array","items":{"$ref":"#/components/schemas/IncidentExtraData"}}},"required":["total_count"],"additionalProperties":true},"IncidentExtraData":{"type":"object","properties":{"category":{"type":"string"},"project":{"type":"string"},"cloud_provider":{"type":"string"},"resource_sub_type":{"type":"string"},"resource_type":{"type":"string"},"action_country":{"type":"string"},"event_type":{"type":"string"},"is_whitelisted":{"type":"boolean"},"mac":{"type":"string"},"image_name":{"type":"string"},"action_local_ip":{"type":"string"},"action_local_port":{"type":"string"},"action_external_hostname":{"type":"string"},"action_remote_ip":{"type":"array","items":{"type":"string"}},"action_remote_port":{"type":"integer"},"matching_service_rule_id":{"type":"string"},"starred":{"type":"boolean"},"external_id":{"type":"string"},"severity":{"type":"string"},"matching_status":{"type":"string"},"end_match_attempt_ts":{"type":"string"},"local_insert_ts":{"type":"integer","description":"The UNIX timestamp that this record was written to the database"},"last_modified_ts":{"type":"integer","description":"The UNIX timestamp that this record was last modified"},"case_id":{"type":"integer"},"deduplicate_tokens":{"type":"string"},"filter_rule_id":{"type":"string"},"event_id":{"type":"string"},"event_timestamp":{"type":"integer"},"action_local_ip_v6":{"type":"string"},"action_remote_ip_v6":{"type":"string"},"alert_type":{"type":"string"},"resolution_status":{"type":"string"},"resolution_comment":{"type":"string"},"dynamic_fields":{"type":"string"},"tags":{"type":"string"},"malicious_urls":{"type":"string"},"asm_alert_categories":{"type":"string"},"last_observed":{"type":"integer"},"country_codes":{"type":"string"},"cloud_providers":{"type":"string"},"ipv4_addresses":{"type":"string"},"ipv6_addresses":{"type":"string"},"domain_names":{"type":"string"},"service_ids":{"type":"string"},"website_ids":{"type":"string"},"asset_ids":{"type":"string"},"certificate":{"$ref":"#/components/schemas/IncidentCertificate"},"port_protocol":{"type":"string"},"port_number":{"type":"integer"},"business_unit_hierarchies":{"type":"array","items":{"$ref":"#/components/schemas/BusinessUnitHierarchy"}},"attack_surface_rule_name":{"type":"string"},"remediation_guidance":{"type":"string"},"attack_surface_rule_id":{"type":"string"},"asset_identifiers":{"$ref":"#/components/schemas/AssetIdentifiers"},"alert_id":{"type":"string"},"detection_timestamp":{"type":"integer"},"name":{"type":"string"},"endpoint_id":{"type":"string"},"description":{"type":"string"},"host_ip":{"type":"string"},"host_name":{"type":"string"},"source":{"type":"string"},"action":{"type":"string"},"action_pretty":{"type":"string"},"user_name":{"type":"string"},"events_length":{"type":"integer"},"mitre_tactic_id_and_name":{"type":"string"},"mitre_technique_id_and_name":{"type":"string"},"cloud_management_status":{"type":"string"}},"additionalProperties":true},"IncidentCertificate":{"type":"object","properties":{"issuerName":{"type":"string"},"subjectName":{"type":"string"},"validNotBefore":{"type":"integer"},"validNotAfter":{"type":"integer"},"serialNumber":{"type":"string"}},"additionalProperties":true},"BusinessUnitHierarchy":{"type":"object","properties":{"creation_time":{"type":"integer"},"family":{"type":"string"},"family_alias":{"type":"string"},"id":{"type":"string"},"is_active":{"type":"integer"},"name":{"type":"string"},"parent_id":{"type":"string"},"update_time":{"type":"integer"}},"additionalProperties":true},"AssetIdentifiers":{"type":"object","properties":{"domain":{"type":"string"},"certificate":{"$ref":"#/components/schemas/IncidentCertificate"},"ipv4Address":{"type":"string"},"ipv6Address":{"type":"string"},"httpPath":{"type":"string"},"portNumber":{"type":"integer"},"portProtocol":{"type":"string"},"firstObserved":{"type":"integer"},"lastObserved":{"type":"integer"}},"additionalProperties":true},"NetworkArtifacts":{"type":"object","properties":{"total_count":{"type":"integer"},"data":{"type":"array","items":{"type":"string"}}},"required":["total_count"],"additionalProperties":true},"FileArtifacts":{"type":"object","properties":{"total_count":{"type":"integer"},"data":{"type":"array","items":{"type":"string"}}},"required":["total_count"],"additionalProperties":true},"DefaultApiErrorResponse":{"type":"object","properties":{"reply":{"description":"The query results upon error.","allOf":[{"$ref":"#/components/schemas/GenericReply"}]}},"required":["reply"],"additionalProperties":true},"GenericReply":{"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."}},"additionalProperties":true},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors"}}},"GetIncidentExtraDataRequest":{"type":"object","properties":{"request_data":{"$ref":"#/components/schemas/GetIncidentExtraDataRequestData"}},"required":["request_data"],"additionalProperties":true},"GetIncidentExtraDataRequestData":{"type":"object","properties":{"incident_id":{"type":"string","description":"The ID of the incident for which you want to retrieve extra data."},"alerts_limit":{"type":"integer","description":"The maximum number of related alerts in the incident that you want to retrieve.
Default: `1000`\n"}},"required":["incident_id"],"additionalProperties":true,"description":"A dictionary containing the API request fields."}},"responses":{"UNPROCESSABLE_ENTITY":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}} ``` ## Update Alerts > Update one or more alerts. You can update up to 100 alerts per request. Missing fields are ignored. \
Required license: \*\*Cortex Xpanse Expander\*\*
```json {"openapi":"3.0.2","info":{"title":"Cortex Xpanse REST API","version":"2.12.0"},"tags":[{"name":"Incident Management","description":"APIs for managing incidents"}],"servers":[{"url":"https://api-{{fqdn}}"}],"paths":{"/public_api/v1/alerts/update_alerts/":{"post":{"parameters":[{"in":"header","name":"authorization","description":"api-key","schema":{"type":"string"},"required":true},{"in":"header","name":"x-xdr-auth-id","description":"api-key-id","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAlertsResponse"}}}},"400":{"description":"Bad Request. Got an invalid JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultApiErrorResponse"}}}},"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/DefaultApiErrorResponse"}}}},"402":{"description":"Unauthorized access. User does not have the required license type to run this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultApiErrorResponse"}}}},"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/DefaultApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_ENTITY"},"500":{"description":"Internal server error. A unified status for API communication type errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultApiErrorResponse"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAlertsRequestData"}}},"description":""},"summary":"Update Alerts","description":"Update one or more alerts. You can update up to 100 alerts per request. Missing fields are ignored.
Required license: **Cortex Xpanse Expander**\n","tags":["Incident Management"]}}},"components":{"schemas":{"UpdateAlertsResponse":{"type":"object","properties":{"reply":{"$ref":"#/components/schemas/AlertIdsList"}},"required":["reply"],"additionalProperties":true},"AlertIdsList":{"type":"object","properties":{"alerts_ids":{"type":"array","items":{"type":"integer"}}},"additionalProperties":true},"DefaultApiErrorResponse":{"type":"object","properties":{"reply":{"description":"The query results upon error.","allOf":[{"$ref":"#/components/schemas/GenericReply"}]}},"required":["reply"],"additionalProperties":true},"GenericReply":{"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."}},"additionalProperties":true},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors"}}},"UpdateAlertsRequestData":{"type":"object","properties":{"request_data":{"description":"(Required) A dictionary containing the API request fields.\r\n\r\nAn empty dictionary returns all results.\r\n","allOf":[{"$ref":"#/components/schemas/UpdateAlertsData"}]}},"required":["request_data"],"additionalProperties":true},"UpdateAlertsData":{"type":"object","properties":{"alert_id_list":{"type":"array","items":{"type":"string"}},"update_data":{"$ref":"#/components/schemas/Alerts"}},"required":["update_data"],"additionalProperties":true,"description":"(Required) A dictionary containing the API request fields. An empty dictionary returns all results.\n"},"Alerts":{"type":"object","properties":{"severity":{"type":"string","description":"Administrator-defined severity, one of the following:\n - critical\n - high\n - medium\n - low\n - unknown\n"},"status":{"type":"string","description":"Updated alert status, one of the following:\n - resolved_-_no_longer_observed\n - new\n - resolved_-_no_risk\n - resolved_-_risk_accepted\n - under_investigation\n - resolved_-_contested_asset\n - resolved_-_remediated_automatically\n - resolved\n"},"comment":{"type":"string","description":"Updated text that appears in the Resolution Comment field of the Alerts table."}}}},"responses":{"UNPROCESSABLE_ENTITY":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}} ``` ## Update an Incident > Update one or more fields of a specific incident. Missing fields are ignored. \
Note the following:\ > \- \`assigned\_user\_mail\` field is validated by Cortex Xpanse to confirm the provided assignee email address belongs to a user that exists in the same Cortex Xpanse tenant.\ > \- To unassign an incident pass \`none\` or \`”assigned\_user\_mail”: “”\`.\ > \- To remove a manually set severity pass \`none\` or \`“manual\_severity”: “”\`.
```json {"openapi":"3.0.2","info":{"title":"Cortex Xpanse REST API","version":"2.12.0"},"tags":[{"name":"Incident Management","description":"APIs for managing incidents"}],"servers":[{"url":"https://api-{{fqdn}}"}],"paths":{"/public_api/v1/incidents/update_incident/":{"post":{"parameters":[{"in":"header","name":"authorization","description":"api-key","schema":{"type":"string"},"required":true},{"in":"header","name":"x-xdr-auth-id","description":"api-key-id","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateIncidentResponse"}}}},"400":{"description":"Bad Request. Got an invalid JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultApiErrorResponse"}}}},"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/DefaultApiErrorResponse"}}}},"402":{"description":"Unauthorized access. User does not have the required license type to run this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultApiErrorResponse"}}}},"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/DefaultApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_ENTITY"},"500":{"description":"Internal server error. A unified status for API communication type errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultApiErrorResponse"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateIncidentRequest"}}},"description":""},"summary":"Update an Incident","description":"Update one or more fields of a specific incident. Missing fields are ignored.
Note the following:\n - `assigned_user_mail` field is validated by Cortex Xpanse to confirm the provided assignee email address belongs to a user that exists in the same Cortex Xpanse tenant.\n - To unassign an incident pass `none` or `”assigned_user_mail”: “”`.\n - To remove a manually set severity pass `none` or `“manual_severity”: “”`.\n","tags":["Incident Management"]}}},"components":{"schemas":{"UpdateIncidentResponse":{"type":"object","properties":{"reply":{"type":"boolean"},"warnings":{"type":"array","items":{"type":"string"}}},"required":["reply"],"additionalProperties":true},"DefaultApiErrorResponse":{"type":"object","properties":{"reply":{"description":"The query results upon error.","allOf":[{"$ref":"#/components/schemas/GenericReply"}]}},"required":["reply"],"additionalProperties":true},"GenericReply":{"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."}},"additionalProperties":true},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors"}}},"UpdateIncidentRequest":{"type":"object","properties":{"request_data":{"$ref":"#/components/schemas/UpdateIncidentRequestData"}},"required":["request_data"],"additionalProperties":true},"UpdateIncidentRequestData":{"type":"object","properties":{"incident_id":{"type":"string"},"update_data":{"$ref":"#/components/schemas/UpdateIncident"}},"required":["incident_id","update_data"],"additionalProperties":true},"UpdateIncident":{"type":"object","properties":{"assigned_user_mail":{"type":"string","description":"Updated email address of the incident assignee."},"assigned_user_pretty_name":{"type":"string","description":"Updated full name of the incident assignee. To supply a new value in this field, you must also supply a value for `assigned_user_mail` in the same request."},"manual_severity":{"type":"string","enum":["low","high","critical","medium"],"description":"Administrator-defined severity."},"status":{"type":"string","enum":["resolved","new","under_investigation"],"description":"Updated incident status."},"resolve_comment":{"type":"string","description":"Descriptive comment explaining the incident change."},"comment":{"$ref":"#/components/schemas/IncidentComment"}},"required":["assigned_user_mail","assigned_user_pretty_name","resolve_comment","status"],"additionalProperties":true},"IncidentComment":{"type":"object","properties":{"comment_action":{"type":"string","default":"add","enum":["add"]},"value":{"type":"string"}},"additionalProperties":true,"description":"Add a comment to the incident."}},"responses":{"UNPROCESSABLE_ENTITY":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/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/xpanse-api/xpanse-public-api/incident-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.