> 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/xdr-api/yara-rules-and-scans/yara-rules.md).

# YARA Rules

Add, list, and delete YARA custom detection rules.

Add, list, and delete the YARA custom detection rules stored in your tenant.

## Add YARA rules

> Adds one or more YARA custom detection rules to your tenant.\
> \
> Submit each rule as raw YARA rule text in the \`rule\_content\` field. Cortex compiles every rule\
> before it is stored. Rules that compile successfully are returned in \`added\_rules\`, and rules that\
> fail to compile are returned in \`dropped\_rules\`. A request can therefore succeed partially: the\
> rules that compile are saved even when other rules in the same request are dropped.\
> \
> Only compilation failures are handled this way. In the following cases, Cortex rejects the whole\
> request with a \`400\` error and saves none of the rules:\
> \
> \* The request contains two or more rules with the same name.\
> \* A rule name in the request already exists in your tenant.\
> \* Saving the rules would take your tenant over 10,000 rules.\
> \* Another import of YARA rules is already in progress. Wait a few seconds, and then retry.\
> \* None of the rules in the request compile.\
> \* The combined size of all rules in the request exceeds 500 KB.\
> \
> Rules added through this endpoint are stored with the origin \`public\_api\`, which distinguishes\
> them from rules uploaded through the Cortex XDR console, which are stored with the origin \`user\_upload\`.\
> \
> {% hint style="info" %}\
> A single request accepts up to 1000 rules, with a combined size of up to 500 KB for all rules in\
> the request. A tenant can store up to 10,000 rules in total.\
> {% endhint %}\
> \
> Required licenses: Requires a Cortex XDR license that includes endpoints.\
> \
> \*\*Required permission:\*\* Detections > Rules > View/Edit<br>

```json
{"openapi":"3.0.3","info":{"title":"Cortex XDR YARA Rules and Scans API","version":"1.0.0"},"tags":[{"name":"YARA Rules","description":"Add, list, and delete the YARA custom detection rules stored in your tenant."}],"servers":[{"url":"https://api-yourfqdn"}],"security":[{"api-key-header-x-xdr-auth-id":[],"api-key-header-authorization":[]}],"components":{"securitySchemes":{"api-key-header-x-xdr-auth-id":{"type":"apiKey","name":"x-xdr-auth-id","in":"header","description":"The API key ID."},"api-key-header-authorization":{"type":"apiKey","name":"Authorization","in":"header","description":"The API key."}},"schemas":{"YaraInsertRulesRequest":{"type":"object","description":"Request to add YARA custom detection rules.","required":["request_data"],"properties":{"request_data":{"type":"object","description":"The request payload envelope.","required":["rules"],"properties":{"rules":{"type":"array","description":"The YARA rules to add. Provide at least 1 rule and no more than 1000 rules.","minItems":1,"maxItems":1000,"items":{"type":"object","required":["rule_content"],"properties":{"rule_content":{"type":"string","minLength":1,"description":"The raw text content of a YARA rule. The rule must compile successfully to be stored."}}}}}}}},"YaraInsertRulesResponse":{"type":"object","description":"The outcome of an add rules request.","properties":{"reply":{"type":"object","properties":{"added_rules":{"type":"array","description":"The names of the rules that were added successfully.","items":{"type":"string"}},"dropped_rules":{"type":"array","description":"The names of the rules that were dropped because they failed to compile. These rules were not saved.","items":{"type":"string"}}}}}},"ErrorResponse":{"type":"object","description":"Standard error response returned when a request fails.","properties":{"reply":{"type":"object","description":"Error details container.","properties":{"err_code":{"type":"integer","description":"Numeric error code identifying the type of error."},"err_msg":{"type":"string","description":"Human-readable error message describing what went wrong."},"err_extra":{"type":"string","description":"Additional context about the error, if available."}}}}}},"responses":{"BadRequest":{"description":"Bad request. The request was malformed or contained invalid parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Unauthorized. Authentication credentials are missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"PaymentRequired":{"description":"Payment required. Your tenant does not have the required license, or the YARA rules and scans\nfeature is not enabled.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Forbidden. The API key does not have the required permissions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/public_api/v1/yara/insert/":{"post":{"tags":["YARA Rules"],"summary":"Add YARA rules","operationId":"insertYaraRules","description":"Adds one or more YARA custom detection rules to your tenant.\n\nSubmit each rule as raw YARA rule text in the `rule_content` field. Cortex compiles every rule\nbefore it is stored. Rules that compile successfully are returned in `added_rules`, and rules that\nfail to compile are returned in `dropped_rules`. A request can therefore succeed partially: the\nrules that compile are saved even when other rules in the same request are dropped.\n\nOnly compilation failures are handled this way. In the following cases, Cortex rejects the whole\nrequest with a `400` error and saves none of the rules:\n\n* The request contains two or more rules with the same name.\n* A rule name in the request already exists in your tenant.\n* Saving the rules would take your tenant over 10,000 rules.\n* Another import of YARA rules is already in progress. Wait a few seconds, and then retry.\n* None of the rules in the request compile.\n* The combined size of all rules in the request exceeds 500 KB.\n\nRules added through this endpoint are stored with the origin `public_api`, which distinguishes\nthem from rules uploaded through the Cortex XDR console, which are stored with the origin `user_upload`.\n\n{% hint style=\"info\" %}\nA single request accepts up to 1000 rules, with a combined size of up to 500 KB for all rules in\nthe request. A tenant can store up to 10,000 rules in total.\n{% endhint %}\n\nRequired licenses: Requires a Cortex XDR license that includes endpoints.\n\n**Required permission:** Detections > Rules > View/Edit\n","requestBody":{"required":true,"description":"The YARA rules to add.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/YaraInsertRulesRequest"}}}},"responses":{"200":{"description":"The request was processed. Review `added_rules` and `dropped_rules` to confirm the outcome for\neach rule. Rules in `dropped_rules` failed to compile and were not saved.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/YaraInsertRulesResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Get YARA rules

> Returns the YARA custom detection rules stored in your tenant, with optional filtering, sorting,\
> and pagination.\
> \
> The response includes the rule ID that you pass to the Start a YARA scan and Delete YARA rules\
> endpoints. Use \`total\_count\` to see how many rules exist in the tenant and \`filter\_count\` to see\
> how many match your filters before pagination is applied.\
> \
> For the fields you can filter and sort on, and the operators each field supports, see\
> \[Additional References]\(table-references/yara-papi-tables.md).\
> \
> Required licenses: Requires a Cortex XDR license that includes endpoints.\
> \
> \*\*Required permission:\*\* Detections > Rules > View<br>

```json
{"openapi":"3.0.3","info":{"title":"Cortex XDR YARA Rules and Scans API","version":"1.0.0"},"tags":[{"name":"YARA Rules","description":"Add, list, and delete the YARA custom detection rules stored in your tenant."}],"servers":[{"url":"https://api-yourfqdn"}],"security":[{"api-key-header-x-xdr-auth-id":[],"api-key-header-authorization":[]}],"components":{"securitySchemes":{"api-key-header-x-xdr-auth-id":{"type":"apiKey","name":"x-xdr-auth-id","in":"header","description":"The API key ID."},"api-key-header-authorization":{"type":"apiKey","name":"Authorization","in":"header","description":"The API key."}},"schemas":{"YaraGetRulesRequest":{"type":"object","description":"Request to retrieve YARA custom detection rules.","required":["request_data"],"properties":{"request_data":{"type":"object","description":"The filtering, sorting, and pagination options.","properties":{"filters":{"type":"array","description":"The filter criteria to apply. All filters are combined with a logical AND. For the\nsupported fields and operators, see Additional References.\n","items":{"$ref":"#/components/schemas/YaraRuleFilter"}},"sort":{"$ref":"#/components/schemas/YaraRuleSort"},"search_from":{"type":"integer","minimum":0,"default":0,"description":"The zero-based index of the first result to return."},"search_to":{"type":"integer","minimum":1,"default":100,"description":"The index of the last result to return. `search_to` must be greater than `search_from`,\nand the resulting page size cannot exceed 100.\n"}}}}},"YaraRuleFilter":{"type":"object","description":"A single filter criterion.","required":["field","operator","value"],"properties":{"field":{"type":"string","description":"The field to filter by.","enum":["id","name","origin","description","author","created_by","first_seen"]},"operator":{"type":"string","description":"The comparison operator to apply. The operators available depend on the field. For the full\nmapping, see Additional References.\n","enum":["eq","neq","contains","not_contains","gte","lte"]},"value":{"description":"The value to compare the field against. Use a string for text fields and a Unix epoch\ntimestamp in milliseconds for `first_seen`.\n","oneOf":[{"type":"string"},{"type":"integer"}]}}},"YaraRuleSort":{"type":"object","description":"The sorting preference for the results.","required":["field","keyword"],"properties":{"field":{"type":"string","description":"The field to sort by. Only `name`, `origin`, `author`, `created_by`, and `first_seen` are sortable.","enum":["name","origin","author","created_by","first_seen"]},"keyword":{"type":"string","description":"The sort direction.","enum":["asc","desc"]}}},"YaraGetRulesResponse":{"type":"object","description":"The YARA rules that match the query.","properties":{"reply":{"type":"object","properties":{"data":{"type":"array","description":"The rules matching the query, after pagination is applied.","items":{"$ref":"#/components/schemas/YaraRule"}},"filter_count":{"type":"integer","minimum":0,"description":"The number of rules matching the filters, before pagination is applied."},"total_count":{"type":"integer","minimum":0,"description":"The total number of rules stored in the tenant."}}}}},"YaraRule":{"type":"object","description":"A YARA custom detection rule.","properties":{"id":{"type":"string","description":"The unique identifier of the rule. Use this value to start a scan or delete the rule."},"name":{"type":"string","description":"The name of the rule, taken from the rule definition."},"origin":{"type":"string","description":"The source the rule came from. `public_api` indicates the rule was added through this API,\nand `user_upload` indicates it was uploaded through the Cortex XDR console. When filtering on this\nfield, use these values, for example `origin` `eq` `public_api`.\n","enum":["public_api","user_upload"]},"first_seen":{"type":"integer","format":"int64","nullable":true,"description":"The time the rule was created, as a Unix epoch timestamp in milliseconds."},"description":{"type":"string","nullable":true,"description":"The description of the rule, taken from the `description` metadata field in the rule definition."},"author":{"type":"string","nullable":true,"description":"The author of the rule, taken from the `author` metadata field in the rule definition."},"created_by":{"type":"string","description":"The display name of the user who created the rule."},"rule_content":{"type":"string","description":"The raw text content of the YARA rule."}}},"ErrorResponse":{"type":"object","description":"Standard error response returned when a request fails.","properties":{"reply":{"type":"object","description":"Error details container.","properties":{"err_code":{"type":"integer","description":"Numeric error code identifying the type of error."},"err_msg":{"type":"string","description":"Human-readable error message describing what went wrong."},"err_extra":{"type":"string","description":"Additional context about the error, if available."}}}}}},"responses":{"BadRequest":{"description":"Bad request. The request was malformed or contained invalid parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Unauthorized. Authentication credentials are missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"PaymentRequired":{"description":"Payment required. Your tenant does not have the required license, or the YARA rules and scans\nfeature is not enabled.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Forbidden. The API key does not have the required permissions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/public_api/v1/yara/get/":{"post":{"tags":["YARA Rules"],"summary":"Get YARA rules","operationId":"getYaraRules","description":"Returns the YARA custom detection rules stored in your tenant, with optional filtering, sorting,\nand pagination.\n\nThe response includes the rule ID that you pass to the Start a YARA scan and Delete YARA rules\nendpoints. Use `total_count` to see how many rules exist in the tenant and `filter_count` to see\nhow many match your filters before pagination is applied.\n\nFor the fields you can filter and sort on, and the operators each field supports, see\n[Additional References](table-references/yara-papi-tables.md).\n\nRequired licenses: Requires a Cortex XDR license that includes endpoints.\n\n**Required permission:** Detections > Rules > View\n","requestBody":{"required":true,"description":"The filtering, sorting, and pagination options.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/YaraGetRulesRequest"}}}},"responses":{"200":{"description":"Successful response containing the rules that match the query.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/YaraGetRulesResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Delete YARA rules

> Deletes one or more YARA custom detection rules by rule ID.\
> \
> Use the Get YARA rules endpoint to retrieve the rule IDs. Cortex deletes every rule ID that it\
> finds and reports the rule IDs it could not find in \`failed\_deletions\`, so a request can succeed\
> partially. The \`status\` field summarizes the outcome:\
> \
> \| Status | Meaning |\
> \| --- | --- |\
> \| \`SUCCESS\` | Every requested rule was deleted. |\
> \| \`PARTIAL\` | Some rules were deleted and some rule IDs were not found. |\
> \| \`FAILED\` | None of the requested rule IDs were found. |\
> \
> {% hint style="warning" %}\
> Deleting a rule is permanent. Scans that are already running continue with the rule definitions\
> they started with, but the rule is no longer available for new scans.\
> {% endhint %}\
> \
> Required licenses: Requires a Cortex XDR license that includes endpoints.\
> \
> \*\*Required permission:\*\* Detections > Rules > View/Edit<br>

```json
{"openapi":"3.0.3","info":{"title":"Cortex XDR YARA Rules and Scans API","version":"1.0.0"},"tags":[{"name":"YARA Rules","description":"Add, list, and delete the YARA custom detection rules stored in your tenant."}],"servers":[{"url":"https://api-yourfqdn"}],"security":[{"api-key-header-x-xdr-auth-id":[],"api-key-header-authorization":[]}],"components":{"securitySchemes":{"api-key-header-x-xdr-auth-id":{"type":"apiKey","name":"x-xdr-auth-id","in":"header","description":"The API key ID."},"api-key-header-authorization":{"type":"apiKey","name":"Authorization","in":"header","description":"The API key."}},"schemas":{"YaraDeleteRulesRequest":{"type":"object","description":"Request to delete YARA custom detection rules.","required":["request_data"],"properties":{"request_data":{"type":"object","description":"The request payload envelope.","required":["rule_ids"],"properties":{"rule_ids":{"type":"array","description":"The IDs of the rules to delete. Provide at least 1 ID and no more than 1000 IDs.\nDuplicate values are rejected.\n","minItems":1,"maxItems":1000,"uniqueItems":true,"items":{"type":"string"}}}}}},"YaraDeleteRulesResponse":{"type":"object","description":"The outcome of a delete rules request.","properties":{"reply":{"type":"object","properties":{"status":{"type":"string","description":"The overall outcome of the request. `SUCCESS` means every rule was deleted, `PARTIAL`\nmeans some rule IDs were not found, and `FAILED` means none were found.\n","enum":["SUCCESS","PARTIAL","FAILED"]},"deleted_count":{"type":"integer","minimum":0,"description":"The number of rules that were deleted."},"failed_deletions":{"type":"array","description":"The rule IDs that could not be deleted because they were not found.","items":{"type":"string"}}}}}},"ErrorResponse":{"type":"object","description":"Standard error response returned when a request fails.","properties":{"reply":{"type":"object","description":"Error details container.","properties":{"err_code":{"type":"integer","description":"Numeric error code identifying the type of error."},"err_msg":{"type":"string","description":"Human-readable error message describing what went wrong."},"err_extra":{"type":"string","description":"Additional context about the error, if available."}}}}}},"responses":{"BadRequest":{"description":"Bad request. The request was malformed or contained invalid parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Unauthorized. Authentication credentials are missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"PaymentRequired":{"description":"Payment required. Your tenant does not have the required license, or the YARA rules and scans\nfeature is not enabled.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Forbidden. The API key does not have the required permissions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/public_api/v1/yara/delete/":{"post":{"tags":["YARA Rules"],"summary":"Delete YARA rules","operationId":"deleteYaraRules","description":"Deletes one or more YARA custom detection rules by rule ID.\n\nUse the Get YARA rules endpoint to retrieve the rule IDs. Cortex deletes every rule ID that it\nfinds and reports the rule IDs it could not find in `failed_deletions`, so a request can succeed\npartially. The `status` field summarizes the outcome:\n\n| Status | Meaning |\n| --- | --- |\n| `SUCCESS` | Every requested rule was deleted. |\n| `PARTIAL` | Some rules were deleted and some rule IDs were not found. |\n| `FAILED` | None of the requested rule IDs were found. |\n\n{% hint style=\"warning\" %}\nDeleting a rule is permanent. Scans that are already running continue with the rule definitions\nthey started with, but the rule is no longer available for new scans.\n{% endhint %}\n\nRequired licenses: Requires a Cortex XDR license that includes endpoints.\n\n**Required permission:** Detections > Rules > View/Edit\n","requestBody":{"required":true,"description":"The IDs of the rules to delete.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/YaraDeleteRulesRequest"}}}},"responses":{"200":{"description":"The request was processed. Review `status` and `failed_deletions` to confirm the outcome.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/YaraDeleteRulesResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```


---

# 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/xdr-api/yara-rules-and-scans/yara-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.
