> 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/xsiam-api/cortex-platform/correlation-rules.md).

# Correlation Rules

APIs for managing Correlation Rules

## Get Correlation Rules

> Return a list of correlation rules. You can return all correlation rules or filter results. You can also return extended results with all details included.
> \
> \- 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:\*\* This endpoint only returns custom correlation rules, such as rules created in the UI or through the API. Correlation rules installed from content packs (Marketplace) aren't returned.
> \\
>
> \
> Requires the granular RBAC permission for this feature. <br>

```json
{"openapi":"3.0.0","info":{"title":"Cortex XSIAM Platform APIs","version":"Cortex XSIAM 3.6"},"tags":[{"name":"Correlation Rules","description":"APIs for managing Correlation Rules"}],"servers":[{"url":"https://api-yourfqdn"}],"paths":{"/public_api/v1/correlations/get":{"post":{"tags":["Correlation Rules"],"summary":"Get Correlation Rules","description":"Return a list of correlation rules. You can return all correlation rules or filter results. You can also return extended results with all details included.\r\n- The response is concatenated using AND condition (OR is not supported).\r\n- The maximum result set size is >100.\r\n- Offset is the zero-based number of incidents from the start of the result set.\r\n\r\n**Note:** This endpoint only returns custom correlation rules, such as rules created in the UI or through the API. Correlation rules installed from content packs (Marketplace) aren't returned.\r\n\r\nRequires the granular RBAC permission for this feature.\r\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":"post-public_api-v1-correlations-get","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["request_data"],"properties":{"request_data":{"type":"object","properties":{"extended_view":{"type":"boolean","description":"Whether to also return `created_by`, `insert_time`, `modify_time`, and `hits` for each correlation rule. Defaults to `false`."},"filters":{"type":"array","description":"An array of filter fields.","items":{"type":"object","properties":{"field":{"enum":["rule_id","name","severity","xql_query","is_enabled","description","alert_name","alert_category","alert_description","alert_fields","execution_mode","search_window","simple_schedule","timezone","crontab","suppression_enabled","suppression_duration","suppression_fields","dataset","user_defined_severity","user_defined_category","mitre_defs","investigation_query_link","drilldown_query_timeframe","mapping_strategy","alert_domain","alert_type","action"],"description":"Identifies the correlation rule field the filter is matching. Filters are based on the following keywords:\r\n- `rule_id`: Correlation rule ID.\r\n- `name`: Correlation rule name.\r\n- `severity`: Correlation rule severity.\r\n- `xql_query`: Correlation rule XQL query.\r\n- `is_enabled`: Whether the correlation rule is enabled or disabled.\r\n- `description`: Correlation rule description.\r\n- `alert_name`: Alert name.\r\n- `alert_category`: Alert category.\r\n- `alert_description`: Alert description.\r\n- `alert_fields`: Alert fields.\r\n- `execution_mode`: Whether execution mode is scheduled or real time.\r\n- `search_window`: Amount of time for search window.\r\n- `simple_schedule`: Correlation rule schedule.\r\n- `timezone`: Correlation rule timezone.\r\n- `crontab`: Linux scheduling for correlation rule.\r\n- `suppression_enabled`: Whether suppression is enabled for correlation rule.\r\n- `suppression_duration`: Duration of correlation rule suppression.\r\n- `suppression_fields`: Suppression fields.\r\n- `dataset`: Correlation rule dataset.\r\n- `user_defined_severity`: User-defined severity.\r\n- `user_defined_category`: User-defined category.\r\n- `mitre_defs`: MITRE definitions.\r\n- `investigation_query_link`: Investigation query link.\r\n- `drilldown_query_timeframe`: Whether the drilldown query timeframe is query or alert.\r\n- `mapping_strategy`: Whether the mapping strategy is auto or custom.\r\n- `alert_domain`: Alert domain.\r\n- `alert_type`: Alert type.\r\n- `action`: Correlation rule action."},"operator":{"enum":["EQ","NEQ","IN","GTE","LTE"],"description":"Identifies the comparison operator you want to use for this filter. Valid keywords are:\r\n`EQ` / `NEQ`\r\n- `rule_id`: Integer\r\n- `name`: String\r\n- `severity`: String\r\n- `xql_query`: String\r\n- `is_enabled`: Boolean\r\n- `description`: String\r\n- `alert_name`: String\r\n- `alert_category`: String\r\n- `alert_description`: String\r\n- `alert_fields`: String or dictionary\r\n- `execution_mode`: String\r\n- `search_window`: String\r\n- `simple_schedule`: String\r\n- `timezone`: String\r\n- `crontab`: String\r\n- `suppression_enabled`: Boolean\r\n- `suppression_duration`: String\r\n- `dataset`: String\r\n- `user_defined_severity`: String\r\n- `user_defined_category`: String\r\n- `investigation_query_link`: String\r\n- `drilldown_query_timeframe`: String\r\n- `mapping_strategy`: String\r\n- `alert_domain`: String\r\n- `alert_type`: String\r\n- `action`: String\r\n`IN`\r\n- `suppression_fields`: List of strings\r\n- `mitre_defs`: List of strings"},"value":{"oneOf":[{"type":"string"},{"type":"array","items":{}},{"type":"boolean"},{"type":"integer"}],"description":"Value that this filter must match. The contents of this field will differ depending on the correlation rule field that you specified for this filter:\r\n- `rule_id`: Integer, the correlation rule ID.\r\n- `name`, `xql_query`, `description`, `alert_name`, `alert_description`, `alert_fields`, `suppression_duration`, `dataset`, `user_defined_severity`, `user_defined_category`, `investigation_query_link`: String.\r\n- `severity`: String, can be one of the following: `SEV_010_INFO`, `SEV_020_LOW`, `SEV_030_MEDIUM`, `SEV_040_HIGH`, `SEV_050_CRITICAL`, `SEV_090_UNKNOWN`, `User Defined`.\r\n- `is_enabled`: Boolean: `true` or `false`.\r\n- `alert_category`: String, can be one of the following: `other`, `persistence`, `evasion`, `tampering`, `file_type_obfuscation`, `privilege_escalation`, `credential_access`, `lateral_movement`, `execution`, `collection`, `exfiltration`, `infiltration`, `dropper`, `file_privilege_manipulation`, `reconnaissance`, `discovery`.\r\n- `alert_fields`: Dictionary.\r\n- `execution_mode`: String, can be one of the following: `scheduled` or `real_time`.\r\n- `search_window`: String, for example: \"2 hours\".\r\n- `simple_schedule`: String, for example: \"5 minutes\".\r\n- `timezone`: String, for example: \"Asia/Jerusalem\".\r\n- `crontab`: String, for example: \"*/10 * * * *\".\r\n- `suppression_enabled`: Boolean: `true` or `false`.\r\n- `suppression_fields`: List of strings.\r\n- `mitre_defs`: List of strings or dictionary.\r\n- `drilldown_query_timeframe`: String, can be one of the following: `query` or `alert`.\r\n- `mapping_strategy`: String, can be one of the following: `auto` or `custom`.\r\n- `alert_domain`: String, for example: `DOMAIN_SECURITY`, `DOMAIN_HEALTH`, `DOMAIN_HUNTING`, `DOMAIN_IT`, or a custom domain name.\r\n- `alert_type`: String, can be one of the following: `Unclassified`, `Ingestion`, `Collection`, `Parsing`, `Event_Forwarding`, `Correlation`.\r\n- `action`: String, can be one of the following: `ALERTS`, `DATASET`, `LOOKUP_ADD`, `LOOKUP_DELETE`.","items":{}}}}},"search_from":{"type":"integer","description":"Integer representing the starting offset within the query result set from which you want correlation rules returned.\r\nCorrelation rules are returned as a zero-based list. Any correlation rule indexed less than this value is not returned in the final result set and defaults to zero."},"search_to":{"type":"integer","description":"Integer representing the end offset within the result set after which you do not want correlation rules returned.\r\nCorrelation rules that are indexed higher than this value are not returned in the final results set. Defaults to >100, which returns all correlation rules to the end of the list."}}}}}}},"required":false},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"objects_count":{"type":"integer","description":"Number of correlation rules returned."},"objects":{"type":"array","items":{"type":"object","properties":{"rule_id":{"type":"integer","description":"Correlation rule ID."},"name":{"type":"string","description":"Correlation rule name."},"severity":{"type":"string","nullable":true,"enum":["SEV_010_INFO","SEV_020_LOW","SEV_030_MEDIUM","SEV_040_HIGH","SEV_050_CRITICAL","SEV_090_UNKNOWN","User Defined"],"description":"Correlation rule severity."},"xql_query":{"type":"string","description":"Correlation rule XQL query."},"is_enabled":{"type":"boolean","description":"Whether the correlation rule is enabled."},"description":{"type":"string","nullable":true,"description":"Correlation rule description."},"alert_name":{"type":"string","nullable":true,"description":"Alert name."},"alert_category":{"type":"string","nullable":true,"enum":["OTHER","PERSISTENCE","EVASION","TAMPERING","FILE_TYPE_OBFUSCATION","PRIVILEGE_ESCALATION","CREDENTIAL_ACCESS","LATERAL_MOVEMENT","EXECUTION","COLLECTION","EXFILTRATION","INFILTRATION","DROPPER","FILE_PRIVILEGE_MANIPULATION","RECONNAISSANCE","DISCOVERY","User Defined"],"description":"Alert category."},"alert_type":{"type":"string","nullable":true,"enum":["Unclassified","Ingestion","Collection","Parsing","Event_Forwarding","Correlation"],"description":"Alert type."},"alert_description":{"type":"string","nullable":true,"description":"Alert description."},"alert_domain":{"type":"string","nullable":true,"description":"Alert domain."},"alert_fields":{"type":"object","nullable":true,"additionalProperties":{},"description":"Mapping of alert fields to fields in the XQL query results."},"execution_mode":{"type":"string","enum":["SCHEDULED","REAL_TIME"],"description":"Correlation rule execution mode."},"search_window":{"type":"string","nullable":true,"description":"Time range that each scheduled run of the rule queries."},"simple_schedule":{"type":"string","nullable":true,"description":"Correlation rule schedule."},"timezone":{"type":"string","nullable":true,"description":"Time zone for the schedule."},"crontab":{"type":"string","nullable":true,"description":"Schedule of the correlation rule, as a cron expression."},"suppression_enabled":{"type":"boolean","description":"Whether alert suppression is enabled."},"suppression_duration":{"type":"string","nullable":true,"description":"How long duplicate alerts are suppressed."},"suppression_fields":{"type":"array","nullable":true,"items":{"type":"string"},"description":"Fields whose values identify duplicate alerts for suppression."},"dataset":{"type":"string","description":"Destination of the correlation rule results."},"user_defined_severity":{"type":"string","nullable":true,"description":"Field in the XQL query results that sets the alert severity."},"user_defined_category":{"type":"string","nullable":true,"description":"Field in the XQL query results that sets the alert category."},"mitre_defs":{"type":"object","nullable":true,"additionalProperties":{},"description":"MITRE ATT&CK tactics and techniques associated with the correlation rule."},"investigation_query_link":{"type":"string","nullable":true,"description":"XQL query to use for investigating the generated alerts."},"drilldown_query_timeframe":{"type":"string","nullable":true,"enum":["QUERY","ALERT"],"description":"Time frame of the drilldown query."},"mapping_strategy":{"type":"string","nullable":true,"enum":["AUTO","CUSTOM"],"description":"How the XQL query results are mapped to alert fields."},"action":{"type":"string","nullable":true,"enum":["ALERTS","DATASET","LOOKUP_ADD","LOOKUP_DELETE"],"description":"Where the correlation rule sends its results."},"lookup_mapping":{"type":"array","nullable":true,"items":{"type":"object","properties":{"lookup_field":{"type":"string","description":"Name of the field in the lookup dataset."},"mapped_val":{"type":"string","description":"Name of the field in the XQL query results whose value is written to `lookup_field`."},"db_type":{"type":"string","description":"Data type of `lookup_field`. If it doesn't match the lookup dataset, the actual field type is used.","enum":["string","numeric","float","datetime","boolean","dict","json"]},"is_unique":{"type":"boolean","description":"Whether the field identifies a unique row. If any mapped field is unique, matching rows are updated instead of added. Defaults to `false`."}},"required":["lookup_field","mapped_val","db_type"]},"description":"Mapping of lookup dataset fields to fields in the XQL query results."},"created_by":{"type":"string","nullable":true,"description":"User or API key that created the correlation rule. Returned only when `extended_view` is `true`."},"insert_time":{"type":"integer","nullable":true,"description":"Time the correlation rule was created, in epoch milliseconds. Returned only when `extended_view` is `true`."},"modify_time":{"type":"integer","nullable":true,"description":"Time the correlation rule was last modified, in epoch milliseconds. Returned only when `extended_view` is `true`."},"hits":{"type":"integer","nullable":true,"description":"Number of times the correlation rule has generated results. Returned only when `extended_view` is `true`."}}},"description":"Correlation rules that match the filters. Each object uses the same fields as the insert request, so you can edit it and send it back to update the rule."},"objects_type":{"type":"string","description":"Type of the returned objects. Always `correlations`."}}}}}},"400":{"description":"Bad Request. Got 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":{"type":"object","title":"reply","description":"The query result upon error.","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."}}}}}}
```

## Insert or update Correlation Rules

> Insert new Correlation Rules or update existing Correlation Rules.\
> \
> \*\*Note:\*\* The correlation rule \`rule\_id\` is tenant specific and can't be used across tenants. Inserting Correlation Rules with the same \`rule\_id\` as an existing Correlation Rule on that tenant will overwrite the existing Correlation Rule.\
> \
> To create a new correlation rule, omit \`rule\_id\`. If you specify a \`rule\_id\` that doesn't exist on the tenant, the request fails for that rule.\
> \
> \*\*Note:\*\* This endpoint only applies to custom correlation rules, such as rules created in the UI or through the API. You can't create or update correlation rules installed from content packs (Marketplace).\
> \
> \*\*Note:\*\* Each correlation rule must include all required fields, even if you don't use them. For fields you don't use, send \`null\` or an empty value. The following required fields can't be empty: \`name\`, \`xql\_query\`, \`dataset\`, \`is\_enabled\`, \`suppression\_enabled\`, and \`execution\_mode\`. If a required field is missing, the request fails for that rule. The \`action\`, \`alert\_domain\`, \`alert\_type\`, \`lookup\_mapping\`, and \`rule\_id\` fields are optional.\
> \
> Some fields depend on the values of other fields. For example, \`severity\` is required when \`action\` is \`ALERTS\`, and \`crontab\` is required when \`execution\_mode\` is \`SCHEDULED\`. Fields that don't apply to the rule must be \`null\` or empty. See the field descriptions for details.\
> \
> The request returns HTTP 200 if all rules succeed, 207 if some rules fail, and 400 if all rules fail. Each failed rule is listed in \`errors\` with its index in the request and the reason it failed.\
> \
> Requires the granular RBAC permission for this feature.

```json
{"openapi":"3.0.0","info":{"title":"Cortex XSIAM Platform APIs","version":"Cortex XSIAM 3.6"},"tags":[{"name":"Correlation Rules","description":"APIs for managing Correlation Rules"}],"servers":[{"url":"https://api-yourfqdn"}],"paths":{"/public_api/v1/correlations/insert":{"post":{"tags":["Correlation Rules"],"summary":"Insert or update Correlation Rules","description":"Insert new Correlation Rules or update existing Correlation Rules.\n\n**Note:** The correlation rule `rule_id` is tenant specific and can't be used across tenants. Inserting Correlation Rules with the same `rule_id` as an existing Correlation Rule on that tenant will overwrite the existing Correlation Rule.\n\nTo create a new correlation rule, omit `rule_id`. If you specify a `rule_id` that doesn't exist on the tenant, the request fails for that rule.\n\n**Note:** This endpoint only applies to custom correlation rules, such as rules created in the UI or through the API. You can't create or update correlation rules installed from content packs (Marketplace).\n\n**Note:** Each correlation rule must include all required fields, even if you don't use them. For fields you don't use, send `null` or an empty value. The following required fields can't be empty: `name`, `xql_query`, `dataset`, `is_enabled`, `suppression_enabled`, and `execution_mode`. If a required field is missing, the request fails for that rule. The `action`, `alert_domain`, `alert_type`, `lookup_mapping`, and `rule_id` fields are optional.\n\nSome fields depend on the values of other fields. For example, `severity` is required when `action` is `ALERTS`, and `crontab` is required when `execution_mode` is `SCHEDULED`. Fields that don't apply to the rule must be `null` or empty. See the field descriptions for details.\n\nThe request returns HTTP 200 if all rules succeed, 207 if some rules fail, and 400 if all rules fail. Each failed rule is listed in `errors` with its index in the request and the reason it failed.\n\nRequires the granular RBAC permission for this feature.","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-correlations-insert","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["request_data"],"properties":{"request_data":{"type":"array","items":{"type":"object","required":["name","severity","xql_query","is_enabled","description","alert_name","alert_category","alert_description","alert_fields","execution_mode","search_window","simple_schedule","timezone","crontab","suppression_enabled","suppression_duration","suppression_fields","dataset","user_defined_severity","user_defined_category","mitre_defs","investigation_query_link","drilldown_query_timeframe","mapping_strategy"],"properties":{"rule_id":{"type":"integer","nullable":true,"description":"ID of the correlation rule to update. Omit this field, or set it to `null`, to create a new correlation rule. If you specify an ID that doesn't exist on the tenant, the request fails for that rule."},"name":{"type":"string","description":"Correlation rule name. Can't be empty."},"severity":{"type":"string","nullable":true,"enum":["SEV_010_INFO","SEV_020_LOW","SEV_030_MEDIUM","SEV_040_HIGH","SEV_050_CRITICAL","SEV_090_UNKNOWN","User Defined"],"description":"Severity of the alerts that the correlation rule generates. Required when `action` is `ALERTS`. If you set `User Defined`, you must also set `user_defined_severity`."},"xql_query":{"type":"string","description":"Correlation rule XQL query. Can't be empty."},"is_enabled":{"type":"boolean","description":"Whether the correlation rule is enabled. Can't be empty."},"description":{"type":"string","nullable":true,"description":"Correlation rule description."},"action":{"type":"string","nullable":true,"enum":["ALERTS","DATASET","LOOKUP_ADD","LOOKUP_DELETE"],"description":"Where the correlation rule sends its results:\n- `ALERTS`: Generate alerts. `dataset` must be `alerts`.\n- `DATASET`: Write the results to the dataset named in `dataset`.\n- `LOOKUP_ADD`: Add the results to the lookup dataset named in `dataset`. Requires `lookup_mapping`.\n- `LOOKUP_DELETE`: Delete matching rows from the lookup dataset named in `dataset`. Requires `lookup_mapping`.\n\nIf you omit this field or set it to `null`, the action is `ALERTS` when `dataset` is `alerts`, and `DATASET` otherwise. To write to a lookup dataset, you must set `action` explicitly."},"dataset":{"type":"string","description":"Destination of the correlation rule results. Set to `alerts` to generate alerts, or to the name of a dataset or lookup dataset to write the results to. Can't be empty."},"alert_name":{"type":"string","nullable":true,"description":"Name of the generated alert. Applies only when `action` is `ALERTS`. Otherwise, set to `null`."},"alert_category":{"type":"string","nullable":true,"enum":["OTHER","PERSISTENCE","EVASION","TAMPERING","FILE_TYPE_OBFUSCATION","PRIVILEGE_ESCALATION","CREDENTIAL_ACCESS","LATERAL_MOVEMENT","EXECUTION","COLLECTION","EXFILTRATION","INFILTRATION","DROPPER","FILE_PRIVILEGE_MANIPULATION","RECONNAISSANCE","DISCOVERY","User Defined"],"description":"Category of the generated alert. Applies only when `action` is `ALERTS`. Otherwise, set to `null`. If you set `User Defined`, you must also set `user_defined_category`. Can't be used together with `alert_type`."},"alert_type":{"type":"string","nullable":true,"enum":["Unclassified","Ingestion","Collection","Parsing","Event_Forwarding","Correlation"],"description":"Type of the generated alert. Applies only when `alert_domain` is `DOMAIN_HEALTH`, and replaces `alert_category` for that domain. Otherwise, set to `null`."},"alert_description":{"type":"string","nullable":true,"description":"Description of the generated alert. Applies only when `action` is `ALERTS`. Otherwise, set to `null`."},"alert_domain":{"type":"string","nullable":true,"description":"Domain of the generated alert. Applies only when `action` is `ALERTS`. Otherwise, set to `null`. The built-in domains are `DOMAIN_SECURITY`, `DOMAIN_HEALTH`, `DOMAIN_HUNTING`, and `DOMAIN_IT`, and your tenant can include custom domains. Domains other than `DOMAIN_SECURITY` require a Cortex XSIAM license. If you omit this field or set it to `null` when `dataset` is `alerts`, the domain is `DOMAIN_SECURITY`."},"alert_fields":{"type":"object","nullable":true,"additionalProperties":{},"description":"Mapping of alert fields to fields in the XQL query results. Applies only when `action` is `ALERTS`. Otherwise, set to `null` or `{}`."},"execution_mode":{"type":"string","enum":["SCHEDULED","REAL_TIME"],"description":"Correlation rule execution mode. Can't be empty. `REAL_TIME` rules must use `alerts` as the `dataset`, and must set `crontab`, `search_window`, and `timezone` to `null`."},"search_window":{"type":"string","nullable":true,"description":"Time range that each scheduled run of the rule queries, as a number followed by `minutes`, `hours`, or `days`. Minimum 10 minutes. Applies only when `execution_mode` is `SCHEDULED`. Otherwise, set to `null`."},"simple_schedule":{"type":"string","nullable":true,"description":"Correlation rule schedule, as shown in the UI."},"timezone":{"type":"string","nullable":true,"description":"Time zone for the schedule, as an IANA time zone name. Applies only when `execution_mode` is `SCHEDULED`. Otherwise, set to `null`."},"crontab":{"type":"string","nullable":true,"description":"Schedule of the correlation rule, as a cron expression. Required when `execution_mode` is `SCHEDULED`. Otherwise, set to `null`."},"suppression_enabled":{"type":"boolean","description":"Whether alert suppression is enabled. Can't be empty."},"suppression_duration":{"type":"string","nullable":true,"description":"How long to suppress duplicate alerts, as a number followed by `minutes`, `hours`, or `days`. Applies only when `suppression_enabled` is `true`. Otherwise, set to `null`."},"suppression_fields":{"type":"array","nullable":true,"items":{"type":"string"},"description":"Fields whose values identify duplicate alerts for suppression. Applies only when `suppression_enabled` is `true`. Otherwise, set to `null`."},"user_defined_severity":{"type":"string","nullable":true,"description":"Field in the XQL query results that sets the alert severity. Required when `severity` is `User Defined`. Otherwise, set to `null`."},"user_defined_category":{"type":"string","nullable":true,"description":"Field in the XQL query results that sets the alert category. Required when `alert_category` is `User Defined`. Otherwise, set to `null`."},"mitre_defs":{"type":"object","nullable":true,"additionalProperties":{},"description":"MITRE ATT&CK tactics and techniques associated with the correlation rule. Each key is a tactic, and each value is a list of techniques for that tactic. Write each tactic and technique as its ID followed by ` - ` and its name, for example `{\"TA0005 - Defense Evasion\": [\"T1014 - Rootkit\"]}`. Each value must be a list, which can be empty. Set to `null` or `{}` if no MITRE ATT&CK tactics apply."},"investigation_query_link":{"type":"string","nullable":true,"description":"XQL query to use for investigating the generated alerts."},"drilldown_query_timeframe":{"type":"string","nullable":true,"enum":["QUERY","ALERT"],"description":"Time frame of the drilldown query. `QUERY` uses the time frame of the correlation rule query, and `ALERT` uses the time frame of the generated alert. Applies when `action` is `ALERTS`. `REAL_TIME` rules can't use `QUERY`."},"mapping_strategy":{"type":"string","nullable":true,"enum":["AUTO","CUSTOM"],"description":"How the XQL query results are mapped to alert fields. `AUTO` maps them automatically, and `CUSTOM` uses the mapping in `alert_fields`. Defaults to `CUSTOM` when set to `null`."},"lookup_mapping":{"type":"array","nullable":true,"items":{"type":"object","properties":{"lookup_field":{"type":"string","description":"Name of the field in the lookup dataset."},"mapped_val":{"type":"string","description":"Name of the field in the XQL query results whose value is written to `lookup_field`."},"db_type":{"type":"string","description":"Data type of `lookup_field`. If it doesn't match the lookup dataset, the actual field type is used.","enum":["string","numeric","float","datetime","boolean","dict","json"]},"is_unique":{"type":"boolean","description":"Whether the field identifies a unique row. If any mapped field is unique, matching rows are updated instead of added. Defaults to `false`."}},"required":["lookup_field","mapped_val","db_type"]},"description":"Mapping of lookup dataset fields to fields in the XQL query results. Applies only when `action` is `LOOKUP_ADD` or `LOOKUP_DELETE`. Otherwise, omit it or set it to `null` or `[]`."}}},"description":"List of correlation rules to create or update."}}}}},"required":false},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"added_objects":{"type":"array","description":"List of Correlation Rule objects added.","items":{"type":"object","properties":{"id":{"type":"integer","description":"ID of the created correlation rule."},"status":{"type":"string","description":"Result message."}}}},"updated_objects":{"type":"array","description":"List of Correlation Rule objects updated.","items":{"type":"object","properties":{"id":{"type":"integer","description":"ID of the updated correlation rule."},"status":{"type":"string","description":"Result message."}}}},"errors":{"type":"array","description":"Rules that failed, with the index of each rule in the request and the reason it failed.","items":{"type":"object","properties":{"index":{"type":"integer","description":"Index of the failed rule in `request_data`, starting at 0."},"status":{"type":"string","description":"Reason the rule failed."}}}}}}}}},"400":{"description":"Bad Request. Got 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":{"type":"object","title":"reply","description":"The query result upon error.","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."}}}}}}
```

## Delete Correlation Rules

> Delete correlation rules selected by filter.\
> \
> You must specify at least one filter. Requests without filters are rejected.\
> \
> \*\*Note:\*\* This endpoint only applies to custom correlation rules, such as rules created in the UI or through the API. Correlation rules installed from content packs (Marketplace) are excluded and can't be deleted.\
> \
> Requires the granular RBAC permission for this feature.

```json
{"openapi":"3.0.0","info":{"title":"Cortex XSIAM Platform APIs","version":"Cortex XSIAM 3.6"},"tags":[{"name":"Correlation Rules","description":"APIs for managing Correlation Rules"}],"servers":[{"url":"https://api-yourfqdn"}],"paths":{"/public_api/v1/correlations/delete":{"post":{"tags":["Correlation Rules"],"summary":"Delete Correlation Rules","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-correlations-delete","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["request_data"],"properties":{"request_data":{"type":"object","required":["filters"],"properties":{"filters":{"type":"array","description":"An array of filter fields.","minItems":1,"items":{"type":"object","properties":{"field":{"type":"string","enum":["rule_id","name","severity","xql_query","is_enabled","description","alert_name","alert_category","alert_description","alert_fields","execution_mode","search_window","simple_schedule","timezone","crontab","suppression_enabled","suppression_duration","suppression_fields","dataset","user_defined_severity","user_defined_category","mitre_defs","investigation_query_link","drilldown_query_timeframe","mapping_strategy","alert_domain","alert_type","action"],"description":"Identifies the correlation rule field the filter is matching. Filters are based on the following keywords:\r\n- `rule_id`: Correlation rule ID.\r\n- `name`: Correlation rule name.\r\n- `severity`: Correlation rule severity.\r\n- `xql_query`: Correlation rule XQL query.\r\n- `is_enabled`: Whether the correlation rule is enabled or disabled.\r\n- `description`: Correlation rule description.\r\n- `alert_name`: Alert name.\r\n- `alert_category`: Alert category.\r\n- `alert_description`: Alert description.\r\n- `alert_fields`: Alert fields.\r\n- `execution_mode`: Whether execution mode is scheduled or real time.\r\n- `search_window`: Amount of time for search window.\r\n- `simple_schedule`: Correlation rule schedule.\r\n- `timezone`: Correlation rule timezone.\r\n- `crontab`: Linux scheduling for correlation rule.\r\n- `suppression_enabled`: Whether suppression is enabled for correlation rule.\r\n- `suppression_duration`: Duration of correlation rule suppression.\r\n- `suppression_fields`: Suppression fields.\r\n- `dataset`: Correlation rule dataset.\r\n- `user_defined_severity`: User-defined severity.\r\n- `user_defined_category`: User-defined category.\r\n- `mitre_defs`: MITRE definitions.\r\n- `investigation_query_link`: Investigation query link.\r\n- `drilldown_query_timeframe`: Whether the drilldown query timeframe is query or alert.\r\n- `mapping_strategy`: Whether the mapping strategy is auto or custom.\r\n- `alert_domain`: Alert domain.\r\n- `alert_type`: Alert type.\r\n- `action`: Correlation rule action."},"operator":{"type":"string","enum":["EQ","NEQ","IN","GTE","LTE"],"description":"Identifies the comparison operator you want to use for this filter. Valid keywords are:\r\n`EQ` / `NEQ`\r\n- `rule_id`: Integer\r\n- `name`: String\r\n- `severity`: String\r\n- `xql_query`: String\r\n- `is_enabled`: Boolean\r\n- `description`: String\r\n- `alert_name`: String\r\n- `alert_category`: String\r\n- `alert_description`: String\r\n- `alert_fields`: String or dictionary\r\n- `execution_mode`: String\r\n- `search_window`: String\r\n- `simple_schedule`: String\r\n- `timezone`: String\r\n- `crontab`: String\r\n- `suppression_enabled`: Boolean\r\n- `suppression_duration`: String\r\n- `dataset`: String\r\n- `user_defined_severity`: String\r\n- `user_defined_category`: String\r\n- `investigation_query_link`: String\r\n- `drilldown_query_timeframe`: String\r\n- `mapping_strategy`: String\r\n- `alert_domain`: String\r\n- `alert_type`: String\r\n- `action`: String\r\n`IN`\r\n- `suppression_fields`: List of strings\r\n- `mitre_defs`: List of strings"},"value":{"oneOf":[{"type":"string"},{"type":"array","items":{}},{"type":"boolean"},{"type":"integer"}],"description":"Value that this filter must match. The contents of this field will differ depending on the correlation rule field that you specified for this filter:\r\n- `rule_id`: Integer, the correlation rule ID.\r\n- `name`, `xql_query`, `description`, `alert_name`, `alert_description`, `alert_fields`, `suppression_duration`, `dataset`, `user_defined_severity`, `user_defined_category`, `investigation_query_link`: String.\r\n- `severity`: String, can be one of the following: `SEV_010_INFO`, `SEV_020_LOW`, `SEV_030_MEDIUM`, `SEV_040_HIGH`, `SEV_050_CRITICAL`, `SEV_090_UNKNOWN`, `User Defined`.\r\n- `is_enabled`: Boolean: `true` or `false`.\r\n- `alert_category`: String, can be one of the following: `other`, `persistence`, `evasion`, `tampering`, `file_type_obfuscation`, `privilege_escalation`, `credential_access`, `lateral_movement`, `execution`, `collection`, `exfiltration`, `infiltration`, `dropper`, `file_privilege_manipulation`, `reconnaissance`, `discovery`.\r\n- `alert_fields`: Dictionary.\r\n- `execution_mode`: String, can be one of the following: `scheduled` or `real_time`.\r\n- `search_window`: String, for example: \"2 hours\".\r\n- `simple_schedule`: String, for example: \"5 minutes\".\r\n- `timezone`: String, for example: \"Asia/Jerusalem\".\r\n- `crontab`: String, for example: \"*/10 * * * *\".\r\n- `suppression_enabled`: Boolean: `true` or `false`.\r\n- `suppression_fields`: List of strings.\r\n- `mitre_defs`: List of strings or dictionary.\r\n- `drilldown_query_timeframe`: String, can be one of the following: `query` or `alert`.\r\n- `mapping_strategy`: String, can be one of the following: `auto` or `custom`.\r\n- `alert_domain`: String, for example: `DOMAIN_SECURITY`, `DOMAIN_HEALTH`, `DOMAIN_HUNTING`, `DOMAIN_IT`, or a custom domain name.\r\n- `alert_type`: String, can be one of the following: `Unclassified`, `Ingestion`, `Collection`, `Parsing`, `Event_Forwarding`, `Correlation`.\r\n- `action`: String, can be one of the following: `ALERTS`, `DATASET`, `LOOKUP_ADD`, `LOOKUP_DELETE`.","items":{}}}}}}}}}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"objects_count":{"type":"integer"},"objects":{"type":"array","items":{"type":"integer"}}}}}}},"400":{"description":"Bad Request. Got 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"}}}}},"description":"Delete correlation rules selected by filter.\n\nYou must specify at least one filter. Requests without filters are rejected.\n\n**Note:** This endpoint only applies to custom correlation rules, such as rules created in the UI or through the API. Correlation rules installed from content packs (Marketplace) are excluded and can't be deleted.\n\nRequires the granular RBAC permission for this feature."}}},"components":{"schemas":{"reply":{"type":"object","title":"reply","description":"The query result upon error.","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."}}}}}}
```


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://cortex-docs.paloaltonetworks.com/xsiam-api/cortex-platform/correlation-rules.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.