> 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/agentix-api/cortex-agentix/issues.md).
# Issues
APIs for managing issues
## Create a new issue
> This endpoint allows users to create a new issue by providing the necessary details. \
> \*\*Users can only create one issue at a time.\*\*\
> \- The request must include the following required fields:\
> \- \`name\`\
> \- \`description\`\
> \- \`observation\_time\`\
> \- \`domain\`\
> \- \`category\`
```json
{"openapi":"3.0.0","info":{"title":"Cortex AgentiX APIs","version":"Cortex AgentiX"},"tags":[{"name":"Issues","description":"APIs for managing issues"}],"servers":[{"url":"https://api-{{fqdn}}"}],"paths":{"/public_api/v1/issue":{"post":{"tags":["Issues"],"summary":"Create a new issue","description":"This endpoint allows users to create a new issue by providing the necessary details. \n**Users can only create one issue at a time.**\n- The request must include the following required fields:\n - `name`\n - `description`\n - `observation_time`\n - `domain`\n - `category`\n","operationId":"createIssue","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"request_data":{"type":"object","properties":{"issue":{"$ref":"#/components/schemas/CreateIssue"}}}}}}}},"responses":{"202":{"description":"Issue created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"external_id":{"type":"string"},"detection_method":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalError"}}}}},"components":{"schemas":{"CreateIssue":{"type":"object","properties":{"owner":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"observation_time":{"type":"integer","format":"int64"},"domain":{"type":"string"},"category":{"type":"string"},"asset_ids":{"type":"array","items":{"type":"string"}},"mitre_tactics":{"type":"array","items":{"type":"string"}},"mitre_techniques":{"type":"array","items":{"type":"string"}},"type":{"type":"string"},"extended_description":{"type":"string"},"impact":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"is_excluded":{"type":"boolean"},"is_starred":{"type":"boolean"},"assigned_to":{"type":"string"},"assigned_to_pretty":{"type":"string"},"severity":{"type":"string","enum":["INFO","LOW","MEDIUM","HIGH","CRITICAL"]},"normalized_fields":{"$ref":"#/components/schemas/NormalizedFields"},"custom_fields":{"type":"object"}},"required":["name","description","observation_time","domain","category","severity"]},"NormalizedFields":{"type":"object","properties":{"xdm.source.location.country":{"type":"string"},"xdm.source.ipv4":{"type":"string"},"xdm.source.host.ipv4_addresses":{"type":"array","items":{"type":"string"}},"xdm.source.identity.username":{"type":"string"},"xdm.source.process.causality_id":{"type":"string"},"xdm.source.process.command_line":{"type":"string"},"xdm.source.process.executable.filename":{"type":"string"},"xdm.source.process.name":{"type":"string"},"xdm.source.process.executable.path":{"type":"string"},"xdm.source.process.executable.sha256":{"type":"string"},"xdm.source.host.hostname":{"type":"string"},"xdm.source.host.os_family":{"type":"string"},"xdm.source.agent.identifier":{"type":"string"},"xdm.source.agent.installation_id":{"type":"string"},"xdm.source.host.fqdn":{"type":"string"},"xdm.source.process.executable.signature_status":{"type":"string"},"xdm.target.file.filename":{"type":"string"},"xdm.target.module.filename":{"type":"string"},"xdm.target.file.sha256":{"type":"string"},"xdm.target.module.sha256":{"type":"string"},"xdm.target.process.command_line":{"type":"string"},"xdm.target.process.executable.sha256":{"type":"string"},"xdm.target.process.executable.signature_status":{"type":"string"},"xdm.target.process.executable.signer":{"type":"array","items":{"type":"string"}},"xdm.target.process.executable.path":{"type":"array","items":{"type":"string"}},"xdm.target.ipv4":{"type":"array","items":{"type":"string"}},"xdm.target.host.ipv4_addresses":{"type":"array","items":{"type":"string"}},"xdm.target.host.ipv6_addresses":{"type":"array","items":{"type":"string"}},"xdm.target.ipv6":{"type":"array","items":{"type":"string"}},"xdm.target.port":{"type":"integer"},"xdm.target.location.country":{"type":"string"},"xdm.target.host.hostname":{"type":"string"},"xdm.target.identity.username":{"type":"string"},"xdm.target.url":{"type":"string"},"xdm.target.process.executable.filename":{"type":"string"},"xdm.target.process.name":{"type":"string"},"xdm.target.agent.identifier":{"type":"string"},"xdm.target.registry.value":{"type":"string"},"xdm.target.registry.data":{"type":"string"},"xdm.target.registry.key":{"type":"string"},"xdm.email.attachment.sha256":{"type":"string"},"xdm.email.attachment.filename":{"type":"string"},"xdm.email.sender":{"type":"string"},"xdm.event.type":{"type":"string"},"xdm.cloud.provider":{"type":"string"},"xdm.cloud.project":{"type":"string"},"xdm.cloud.project_id":{"type":"string"},"xdm.cloud.region":{"type":"string"},"xdm.cloud.function.id":{"type":"string"},"xdm.cloud.function.name":{"type":"string"},"xdm.cloud.function.version":{"type":"string"},"xdm.cloud.function.request_id":{"type":"string"},"xdm.cloud.function.runtime":{"type":"string"},"xdm.observer.unique_identifier":{"type":"string"},"xdm.observer.type":{"type":"string"},"xdm.observer.sub_type":{"type":"string"},"xdm.observer.name":{"type":"string"},"xdm.vulnerability.cve_id":{"type":"string"},"xdm.vulnerability.severity":{"type":"string","enum":["INFO","LOW","MEDIUM","HIGH","CRITICAL"]},"xdm.vulnerability.fix_versions":{"type":"array","items":{"type":"string"}},"xdm.vulnerability.cve_risk_factors":{"type":"array","items":{"type":"string"}},"xdm.vulnerability.cvss_score":{"type":"number","format":"float"},"xdm.vulnerability.cvss_vector":{"type":"string"},"xdm.software_package.version":{"type":"string"},"xdm.software_package.purl":{"type":"string"},"xdm.software_package.layer_id":{"type":"string"},"xdm.software_package.type":{"type":"string"},"xdm.software_package.installation_type":{"type":"string"},"xdm.software_package.package_manager":{"type":"string"},"xdm.software_package.dependency_type":{"type":"string"},"xdm.software_package.language":{"type":"string"},"xdm.malware.verdict":{"type":"string"},"xdm.malware.virus_total_link":{"type":"string"},"xdm.malware.layer_id":{"type":"string"},"xdm.secret.secret_type":{"type":"string"},"xdm.secret.unique_identifier":{"type":"string"},"xdm.secret.snippet":{"type":"string"},"xdm.secret.layer_id":{"type":"string"},"xdm.file.filename":{"type":"string"},"xdm.file.path":{"type":"string"},"xdm.file.sha256":{"type":"string"},"xdm.file.size":{"type":"integer"},"xdm.file.last_modified":{"type":"integer"},"xdm.file.metadata_change_time":{"type":"integer"},"xdm.file.owner_id":{"type":"string"},"xdm.file.owner_name":{"type":"string"},"xdm.file.group_id":{"type":"string"},"xdm.file.group_name":{"type":"string"},"xdm.file.permissions.owner":{"type":"array","items":{"type":"string"}},"xdm.file.permissions.group":{"type":"array","items":{"type":"string"}},"xdm.file.permissions.others":{"type":"array","items":{"type":"string"}},"xdm.file.position.start.line":{"type":"integer"},"xdm.file.position.start.character":{"type":"integer"},"xdm.file.position.end.line":{"type":"integer"},"xdm.file.position.end.character":{"type":"integer"},"xdm.url":{"type":"string"},"xdm.domain":{"type":"string"},"xdm.application_protocol":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"Unauthorized":{"description":"Unauthorized access","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"InternalError":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}
```
## Retrieve issues based on filters
> This endpoint retrieves a list of issues that match the specified filter criteria. It supports filtering by \`issue\_id\`, \`external\_id\`, \`detection\_method\`, \`domain\`, \`source\`, \`severity\`, and \`\_insert\_time\`, along with sorting and pagination.\
> \
> Request Body:\
> \- \`request\_data\`: Object containing filter criteria\
> \- \`filters\`: Array of filter objects\
> \- \`field\`: String (enum: 'issue\_id', 'external\_id', 'detection\_method', 'domain', 'severity', '\_insert\_time', 'status')\
> \- \`operator\`: String (enum: 'in', 'gte', 'lte')\
> \- \`value\`: Array of integers/strings or single integer\
> \- \`search\_from\`: Integer (default: 0) - Starting index for pagination\
> \- \`search\_to\`: Integer (default: 100) - Ending index for pagination\
> \- \`sort\`: Object for sorting results\
> \- \`field\`: String (enum: '\_insert\_time', 'severity', 'issue\_id')\
> \- \`keyword\`: String (enum: 'asc', 'desc') - Sort order\
> \- \`include\_fields\`: Array of strings (enum: 'normalized\_fields', 'custom\_fields', default: \[]) - Fields to include in response
```json
{"openapi":"3.0.0","info":{"title":"Cortex AgentiX APIs","version":"Cortex AgentiX"},"tags":[{"name":"Issues","description":"APIs for managing issues"}],"servers":[{"url":"https://api-{{fqdn}}"}],"paths":{"/public_api/v1/issue/search":{"post":{"tags":["Issues"],"summary":"Retrieve issues based on filters","description":"This endpoint retrieves a list of issues that match the specified filter criteria. It supports filtering by `issue_id`, `external_id`, `detection_method`, `domain`, `source`, `severity`, and `_insert_time`, along with sorting and pagination.\n\nRequest Body:\n- `request_data`: Object containing filter criteria\n - `filters`: Array of filter objects\n - `field`: String (enum: 'issue_id', 'external_id', 'detection_method', 'domain', 'severity', '_insert_time', 'status')\n - `operator`: String (enum: 'in', 'gte', 'lte')\n - `value`: Array of integers/strings or single integer\n- `search_from`: Integer (default: 0) - Starting index for pagination\n- `search_to`: Integer (default: 100) - Ending index for pagination\n- `sort`: Object for sorting results\n - `field`: String (enum: '_insert_time', 'severity', 'issue_id')\n - `keyword`: String (enum: 'asc', 'desc') - Sort order\n- `include_fields`: Array of strings (enum: 'normalized_fields', 'custom_fields', default: []) - Fields to include in response\n","operationId":"getIssues","parameters":[{"name":"Authorization","in":"header","description":"{api_key}","required":true,"schema":{"type":"string"}},{"name":"x-xdr-auth-id","in":"header","description":"{api_key_id}","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"request_data":{"type":"object","properties":{"filters":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["issue_id","external_id","detection_method","domain","severity","_insert_time","status"],"description":"Specifies the field to filter issues by."},"operator":{"type":"string","enum":["in","gte","lte"],"description":"Comparison operator to use with the filter."},"value":{"description":"Value(s) for filtering the issues.","oneOf":[{"type":"array","items":{"type":"integer"}},{"type":"array","items":{"type":"string"}},{"type":"integer"}]}}}},"search_from":{"type":"integer","description":"Starting index for pagination."},"search_to":{"type":"integer","description":"Ending index for pagination."},"sort":{"type":"object","properties":{"field":{"type":"string","enum":["id","severity","observation_time"]},"keyword":{"type":"string","enum":["asc","desc"],"description":"Sort order (ascending or descending)."}}},"include_fields":{"type":"array","description":"A list of fields to include in the response.\n- `normalized_fields`: Includes normalized fields in the response.\n- `custom_fields`: Includes custom user-defined fields in the response.\n- By default these fields will not be part of response payload.\n","items":{"type":"string","enum":["normalized_fields","custom_fields"]}}}}}}}}},"responses":{"200":{"description":"Successful response with issues","content":{"application/json":{"schema":{"type":"object","properties":{"reply":{"type":"object","properties":{"total_count":{"type":"integer"},"result_count":{"type":"integer"},"issues":{"type":"array","items":{"$ref":"#/components/schemas/Issue"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalError"}}}}},"components":{"schemas":{"Issue":{"type":"object","properties":{"_insert_time":{"type":"string","format":"date-time"},"owner":{"type":"string"},"external_id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"observation_time":{"type":"integer","format":"int64"},"domain":{"type":"string"},"detection_method":{"type":"string"},"detection_rule_id":{"type":"string"},"category":{"type":"string"},"finding_ids":{"type":"array","items":{"type":"string"}},"asset_ids":{"type":"array","items":{"type":"string"}},"mitre_tactics":{"type":"array","items":{"type":"string"}},"mitre_techniques":{"type":"array","items":{"type":"string"}},"type":{"type":"string"},"remediation":{"type":"string"},"extended_description":{"type":"string"},"impact":{"type":"string"},"issue_id":{"type":"integer"},"last_modified":{"type":"integer","format":"int64"},"tags":{"type":"array","items":{"type":"string"}},"is_excluded":{"type":"boolean"},"is_starred":{"type":"boolean"},"assigned_to":{"type":"string"},"assigned_to_pretty":{"type":"string"},"status":{"type":"string","enum":["New","In Progress","Resolved"]},"status_resolution_reason":{"type":"string","enum":["RESOLVED_KNOWN_ISSUE","RESOLVED_DUPLICATE","RESOLVED_FALSE_POSITIVE","RESOLVED_OTHER","RESOLVED_TRUE_POSITIVE","RESOLVED_SECURITY_TESTING","RESOLVED_FIXED","RESOLVED_DISMISSED"]},"status_resolution_comment":{"type":"string"},"severity":{"type":"string","enum":["INFO","LOW","MEDIUM","HIGH","CRITICAL"]},"resolution_time":{"type":"integer","format":"int64"},"normalized_fields":{"$ref":"#/components/schemas/NormalizedFields"},"custom_fields":{"type":"object"}}},"NormalizedFields":{"type":"object","properties":{"xdm.source.location.country":{"type":"string"},"xdm.source.ipv4":{"type":"string"},"xdm.source.host.ipv4_addresses":{"type":"array","items":{"type":"string"}},"xdm.source.identity.username":{"type":"string"},"xdm.source.process.causality_id":{"type":"string"},"xdm.source.process.command_line":{"type":"string"},"xdm.source.process.executable.filename":{"type":"string"},"xdm.source.process.name":{"type":"string"},"xdm.source.process.executable.path":{"type":"string"},"xdm.source.process.executable.sha256":{"type":"string"},"xdm.source.host.hostname":{"type":"string"},"xdm.source.host.os_family":{"type":"string"},"xdm.source.agent.identifier":{"type":"string"},"xdm.source.agent.installation_id":{"type":"string"},"xdm.source.host.fqdn":{"type":"string"},"xdm.source.process.executable.signature_status":{"type":"string"},"xdm.target.file.filename":{"type":"string"},"xdm.target.module.filename":{"type":"string"},"xdm.target.file.sha256":{"type":"string"},"xdm.target.module.sha256":{"type":"string"},"xdm.target.process.command_line":{"type":"string"},"xdm.target.process.executable.sha256":{"type":"string"},"xdm.target.process.executable.signature_status":{"type":"string"},"xdm.target.process.executable.signer":{"type":"array","items":{"type":"string"}},"xdm.target.process.executable.path":{"type":"array","items":{"type":"string"}},"xdm.target.ipv4":{"type":"array","items":{"type":"string"}},"xdm.target.host.ipv4_addresses":{"type":"array","items":{"type":"string"}},"xdm.target.host.ipv6_addresses":{"type":"array","items":{"type":"string"}},"xdm.target.ipv6":{"type":"array","items":{"type":"string"}},"xdm.target.port":{"type":"integer"},"xdm.target.location.country":{"type":"string"},"xdm.target.host.hostname":{"type":"string"},"xdm.target.identity.username":{"type":"string"},"xdm.target.url":{"type":"string"},"xdm.target.process.executable.filename":{"type":"string"},"xdm.target.process.name":{"type":"string"},"xdm.target.agent.identifier":{"type":"string"},"xdm.target.registry.value":{"type":"string"},"xdm.target.registry.data":{"type":"string"},"xdm.target.registry.key":{"type":"string"},"xdm.email.attachment.sha256":{"type":"string"},"xdm.email.attachment.filename":{"type":"string"},"xdm.email.sender":{"type":"string"},"xdm.event.type":{"type":"string"},"xdm.cloud.provider":{"type":"string"},"xdm.cloud.project":{"type":"string"},"xdm.cloud.project_id":{"type":"string"},"xdm.cloud.region":{"type":"string"},"xdm.cloud.function.id":{"type":"string"},"xdm.cloud.function.name":{"type":"string"},"xdm.cloud.function.version":{"type":"string"},"xdm.cloud.function.request_id":{"type":"string"},"xdm.cloud.function.runtime":{"type":"string"},"xdm.observer.unique_identifier":{"type":"string"},"xdm.observer.type":{"type":"string"},"xdm.observer.sub_type":{"type":"string"},"xdm.observer.name":{"type":"string"},"xdm.vulnerability.cve_id":{"type":"string"},"xdm.vulnerability.severity":{"type":"string","enum":["INFO","LOW","MEDIUM","HIGH","CRITICAL"]},"xdm.vulnerability.fix_versions":{"type":"array","items":{"type":"string"}},"xdm.vulnerability.cve_risk_factors":{"type":"array","items":{"type":"string"}},"xdm.vulnerability.cvss_score":{"type":"number","format":"float"},"xdm.vulnerability.cvss_vector":{"type":"string"},"xdm.software_package.version":{"type":"string"},"xdm.software_package.purl":{"type":"string"},"xdm.software_package.layer_id":{"type":"string"},"xdm.software_package.type":{"type":"string"},"xdm.software_package.installation_type":{"type":"string"},"xdm.software_package.package_manager":{"type":"string"},"xdm.software_package.dependency_type":{"type":"string"},"xdm.software_package.language":{"type":"string"},"xdm.malware.verdict":{"type":"string"},"xdm.malware.virus_total_link":{"type":"string"},"xdm.malware.layer_id":{"type":"string"},"xdm.secret.secret_type":{"type":"string"},"xdm.secret.unique_identifier":{"type":"string"},"xdm.secret.snippet":{"type":"string"},"xdm.secret.layer_id":{"type":"string"},"xdm.file.filename":{"type":"string"},"xdm.file.path":{"type":"string"},"xdm.file.sha256":{"type":"string"},"xdm.file.size":{"type":"integer"},"xdm.file.last_modified":{"type":"integer"},"xdm.file.metadata_change_time":{"type":"integer"},"xdm.file.owner_id":{"type":"string"},"xdm.file.owner_name":{"type":"string"},"xdm.file.group_id":{"type":"string"},"xdm.file.group_name":{"type":"string"},"xdm.file.permissions.owner":{"type":"array","items":{"type":"string"}},"xdm.file.permissions.group":{"type":"array","items":{"type":"string"}},"xdm.file.permissions.others":{"type":"array","items":{"type":"string"}},"xdm.file.position.start.line":{"type":"integer"},"xdm.file.position.start.character":{"type":"integer"},"xdm.file.position.end.line":{"type":"integer"},"xdm.file.position.end.character":{"type":"integer"},"xdm.url":{"type":"string"},"xdm.domain":{"type":"string"},"xdm.application_protocol":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"Unauthorized":{"description":"Unauthorized access","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"InternalError":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}
```
## Update existing issue
> Update an existing issue in the system. \*\*Users can only update one issue at a time.\*\* \
> \- At least one of the following fields is \*\*mandatory\*\*: \
> \- severity\
> \- status
```json
{"openapi":"3.0.0","info":{"title":"Cortex AgentiX APIs","version":"Cortex AgentiX"},"tags":[{"name":"Issues","description":"APIs for managing issues"}],"servers":[{"url":"https://api-{{fqdn}}"}],"paths":{"/public_api/v1/issue/{issue-id}":{"post":{"tags":["Issues"],"summary":"Update existing issue","description":"Update an existing issue in the system. **Users can only update one issue at a time.** \n- At least one of the following fields is **mandatory**: \n - severity\n - status\n","operationId":"updateIssue","parameters":[{"name":"issue-id","in":"path","description":"Numeric ID of the user to get","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"request_data":{"type":"object","properties":{"update_data":{"$ref":"#/components/schemas/UpdateIssue"}}}}}}}},"responses":{"204":{"description":"Issues updated successfully"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalError"}}}}},"components":{"schemas":{"UpdateIssue":{"type":"object","properties":{"severity":{"type":"string","enum":["INFO","LOW","MEDIUM","HIGH","CRITICAL"]},"status":{"type":"string","enum":["New","In Progress","Resolved"]},"status_resolution_reason":{"type":"string","enum":["RESOLVED_KNOWN_ISSUE","RESOLVED_DUPLICATE","RESOLVED_FALSE_POSITIVE","RESOLVED_OTHER","RESOLVED_TRUE_POSITIVE","RESOLVED_SECURITY_TESTING","RESOLVED_FIXED","RESOLVED_DISMISSED"]},"status_resolution_comment":{"type":"string"}},"required":["severity","status"]}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"Unauthorized":{"description":"Unauthorized access","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"InternalError":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}
```
## Create a new issue exception
> This endpoint allows users to create a new issue exception by providing the necessary details.\
> \*\*Users can only create one exception at a time.\*\*\
> \- The request must include the following required fields:\
> \- \`name\`\
> \- \`rule\`\
> \- \`justification\_text\`\
> \- \`justification\_category\`\
> \- \`expiration\_ts\`\
> \- \`approver\_email\`\
> \
> \- Optional fields:\
> \- \`external\_exception\_id\`\
> \
> If the tenant has approval required enabled, the \`approver\_email\` field is mandatory and the exception will be created with \`Pending Status\` status. Otherwise, the exception is \`Self Approved\` automatically.\
> \
> The \`requestor\_name\` and \`requestor\_email\` fields are automatically populated from the API key context.\
> \
> \*\*Required permission:\*\* \`Exception Management Admin View/Edit\`, \`Exception Approver Admin View/Edit\`\
> \
> For the complete list of fields you can use as \`SEARCH\_FIELD\` in the \`rule\` parameter, see \[Issue exception supported fields]\(
> \
> Required license: \*\*Cortex AgentiX Enterprise\*\* or \*\*Cortex AgentiX Base\*\*
```json
{"openapi":"3.0.0","info":{"title":"Cortex AgentiX APIs","version":"Cortex AgentiX"},"tags":[{"name":"Issues","description":"APIs for managing issues"}],"servers":[{"url":"https://api-{{fqdn}}"}],"paths":{"/public_api/v1/issue_exceptions/":{"post":{"summary":"Create a new issue exception","description":"This endpoint allows users to create a new issue exception by providing the necessary details.\n**Users can only create one exception at a time.**\n- The request must include the following required fields:\n - `name`\n - `rule`\n - `justification_text`\n - `justification_category`\n - `expiration_ts`\n - `approver_email`\n\n- Optional fields:\n - `external_exception_id`\n\nIf the tenant has approval required enabled, the `approver_email` field is mandatory and the exception will be created with `Pending Status` status. Otherwise, the exception is `Self Approved` automatically.\n\nThe `requestor_name` and `requestor_email` fields are automatically populated from the API key context.\n\n**Required permission:** `Exception Management Admin View/Edit`, `Exception Approver Admin View/Edit`\n\nFor the complete list of fields you can use as `SEARCH_FIELD` in the `rule` parameter, see [Issue exception supported fields](https://app.gitbook.com/s/ZuJbX2x7VQJhNovscCwE/issues-apis/issues-papi-tables#supported-fields-for-issue-exception-filters).\n\nRequired license: **Cortex AgentiX Enterprise** or **Cortex AgentiX Base**","operationId":"createIssueException","parameters":[{"name":"Authorization","in":"header","description":"{api_key}","required":true,"schema":{"type":"string"}},{"name":"x-xdr-auth-id","in":"header","description":"{api_key_id}","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"request_data":{"$ref":"#/components/schemas/CreateIssueException"}}}}}},"responses":{"200":{"description":"Exception created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"reply":{"type":"object","properties":{"exception_id":{"type":"integer","description":"ID of the newly created exception"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalError"}},"tags":["Issues"]}}},"components":{"schemas":{"CreateIssueException":{"type":"object","description":"Request data for creating a new issue exception.","required":["name","rule","justification_text","justification_category","approver_email","expiration_ts"],"properties":{"name":{"type":"string","description":"Human-readable name for the exception"},"external_exception_id":{"type":"string","nullable":true,"description":"Optional external tracking ID for the exception"},"rule":{"type":"string","description":"JSON-encoded filter rule defining which issues this exception applies to. Uses the standard Cortex filter format with `AND`/`OR` structure. The value of each `SEARCH_FIELD` must be one of the supported field names — see [Issue exception supported fields](https://app.gitbook.com/s/ZuJbX2x7VQJhNovscCwE/issues-apis/issues-papi-tables#supported-fields-for-issue-exception-filters) for the complete list."},"justification_text":{"type":"string","description":"Free-text justification explaining why this exception is needed"},"justification_category":{"type":"string","enum":["COMPENSATING_CONTROL","PLANNED_REMEDIATION","RISK_ACCEPTED","VENDOR_DEPENDENCY"],"description":"Category of justification for the exception"},"approval_justification":{"type":"string","description":"Free-text justification explaining why this exception is approved or rejected"},"approver_email":{"type":"string","description":"Email of the designated approver. Required when the tenant has approval workflow enabled. Must match a registered approver."},"expiration_ts":{"type":"string","format":"date-time","description":"Expiration date/time for the exception. Accepts ISO 8601 date-time or date-only format. Date-only values are normalized to end-of-day UTC (23:59:59)."}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"Unauthorized":{"description":"Unauthorized access","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"InternalError":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}
```
## Disable an issue exception
> This endpoint allows users to disable an existing issue exception. This will trigger a reversion scan to restore matching issues that were previously suppressed by this exception. \*\*A disabled exception cannot be reactivated.\*\*\
> \
> \*\*Required permission:\*\* \`Exception Management Admin View/Edit\`, \`Exception Approver Admin View/Edit\`\
> \
> \
> Required license: \*\*Cortex AgentiX Enterprise\*\* or \*\*Cortex AgentiX Base\*\*
```json
{"openapi":"3.0.0","info":{"title":"Cortex AgentiX APIs","version":"Cortex AgentiX"},"tags":[{"name":"Issues","description":"APIs for managing issues"}],"servers":[{"url":"https://api-{{fqdn}}"}],"paths":{"/public_api/v1/issue_exceptions/disable/":{"post":{"summary":"Disable an issue exception","description":"This endpoint allows users to disable an existing issue exception. This will trigger a reversion scan to restore matching issues that were previously suppressed by this exception. **A disabled exception cannot be reactivated.**\n\n**Required permission:** `Exception Management Admin View/Edit`, `Exception Approver Admin View/Edit`\n\n\nRequired license: **Cortex AgentiX Enterprise** or **Cortex AgentiX Base**","operationId":"disableIssueException","parameters":[{"name":"Authorization","in":"header","description":"{api_key}","required":true,"schema":{"type":"string"}},{"name":"x-xdr-auth-id","in":"header","description":"{api_key_id}","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"request_data":{"type":"object","required":["exception_id"],"properties":{"exception_id":{"type":"integer","description":"ID of the issue exception to disable"}}}}}}}},"responses":{"200":{"description":"Exception disabled successfully","content":{"application/json":{"schema":{"type":"object","properties":{"reply":{"type":"object","properties":{"rows_affected":{"type":"integer","description":"Number of database rows affected"},"status":{"type":"string","description":"New status of the exception"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalError"}},"tags":["Issues"]}}},"components":{"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"Unauthorized":{"description":"Unauthorized access","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"InternalError":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}
```
## Retrieve issue exceptions based on filters
> This endpoint retrieves a list of issue exceptions that match the specified filter criteria. It supports filtering along with sorting and pagination. \
> \
> \*\*Required permission:\*\* \`Exception Management Admin View\`, \`Exception Approver Admin View\`\
> \
> \
> Required license: \*\*Cortex AgentiX Enterprise\*\* or \*\*Cortex AgentiX Base\*\*
```json
{"openapi":"3.0.0","info":{"title":"Cortex AgentiX APIs","version":"Cortex AgentiX"},"tags":[{"name":"Issues","description":"APIs for managing issues"}],"servers":[{"url":"https://api-{{fqdn}}"}],"paths":{"/public_api/v1/issue_exceptions/search/":{"post":{"summary":"Retrieve issue exceptions based on filters","description":"This endpoint retrieves a list of issue exceptions that match the specified filter criteria. It supports filtering along with sorting and pagination. \n\n**Required permission:** `Exception Management Admin View`, `Exception Approver Admin View`\n\n\nRequired license: **Cortex AgentiX Enterprise** or **Cortex AgentiX Base**","operationId":"searchIssueExceptions","parameters":[{"name":"Authorization","in":"header","description":"{api_key}","required":true,"schema":{"type":"string"}},{"name":"x-xdr-auth-id","in":"header","description":"{api_key_id}","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"request_data":{"type":"object","properties":{"filters":{"type":"object","description":"Filter criteria using AND/OR structure. Each filter condition contains SEARCH_FIELD, SEARCH_TYPE, and SEARCH_VALUE.","properties":{"SEARCH_FIELD":{"type":"string","enum":["EXCEPTION_ID","EXTERNAL_EXCEPTION_ID","NAME","STATUS","EXPIRATION_TS","IMPACTED_ISSUES_COUNT","BACKWARD_SCAN_STATUS","JUSTIFICATION_CATEGORY","REQUESTOR_NAME","APPROVER_NAME","CREATED_TS","APPROVAL_TS","JUSTIFICATION_TEXT","APPROVAL_JUSTIFICATION","REQUESTOR_EMAIL","APPROVER_EMAIL"],"description":"String that identifies the exception field the filter is matching."},"SEARCH_TYPE":{"type":"string","enum":["EQ","NEQ","GTE","LTE","GT","LT","IN","CONTAINS","CONTAINS_NOT"],"description":"Identifies the comparison operator to use for this filter. The following list shows which operators can be used for each filter field:\n\n- **EQ** / **NEQ** - use with all fields\n- **GTE** / **LTE** / **GT** / **LT** - use with `EXCEPTION_ID`, `EXPIRATION_TS`, `IMPACTED_ISSUES_COUNT`, `CREATED_TS`, `APPROVAL_TS`\n- **IN** - use with `EXCEPTION_ID`, `STATUS`, `BACKWARD_SCAN_STATUS`, `JUSTIFICATION_CATEGORY`\n- **CONTAINS** / **CONTAINS_NOT** — use with `EXTERNAL_EXCEPTION_ID`, `NAME`, `REQUESTOR_NAME`, `APPROVER_NAME`, `JUSTIFICATION_TEXT`, `APPROVAL_JUSTIFICATION`, `REQUESTOR_EMAIL`, `APPROVER_EMAIL`"},"SEARCH_VALUE":{"description":"Value that this filter must match. The contents of this field will differ depending on the field that you specified for this filter:\n\n- EXCEPTION_ID — Integer, e.g. `1`, `42`\n- EXTERNAL_EXCEPTION_ID — String, e.g. `\"EXT-001\"`\n- NAME — String, e.g. `\"CVE Exception\"`\n- STATUS — String. Values are: `APPROVED`, `DISABLED`, `EXPIRED`, `NO_DECISION_MADE`, `PENDING_DECISION`, `REJECTED`, `SELF_APPROVED`\n- EXPIRATION_TS — Epoch milliseconds, e.g. `1712448000000`\n- IMPACTED_ISSUES_COUNT — Integer, e.g. `0`, `10`, `100`\n- BACKWARD_SCAN_STATUS — String. Values are: `COMPLETED`, `FAILED`, `IN_PROGRESS`, `PENDING`\n- JUSTIFICATION_CATEGORY — String. Values are: `COMPENSATING_CONTROL`, `PLANNED_REMEDIATION`, `RISK_ACCEPTED`, `VENDOR_DEPENDENCY`\n- REQUESTOR_NAME — String, e.g. `\"John Doe\"`\n- APPROVER_NAME — String, e.g. `\"Jane Smith\"`\n- CREATED_TS — Epoch milliseconds, e.g. `1712448000000`\n- APPROVAL_TS — Epoch milliseconds, e.g. `1712448000000`\n- JUSTIFICATION_TEXT — String, e.g. `\"Risk accepted per policy\"`\n- APPROVAL_JUSTIFICATION — String, e.g. `\"Approved by security team\"`\n- REQUESTOR_EMAIL — String, e.g. `\"john@example.com\"`\n- APPROVER_EMAIL — String, e.g. `\"jane@example.com\"`","oneOf":[{"type":"string"},{"type":"integer"},{"type":"array","items":{"type":"string"}}]}}},"search_from":{"type":"integer","default":0,"description":"Starting index for pagination."},"search_to":{"type":"integer","default":100,"description":"Ending index for pagination."},"sort":{"type":"object","nullable":true,"description":"Sort configuration","properties":{"FIELD":{"type":"string","description":"Field name to sort by"},"ORDER":{"type":"string","enum":["ASC","DESC"],"description":"Sort direction"}}}}}}}}}},"responses":{"200":{"description":"Exceptions retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"reply":{"type":"object","properties":{"exceptions":{"type":"array","description":"List of matching exception objects","items":{"$ref":"#/components/schemas/IssueException"}},"filter_count":{"type":"integer","description":"Number of exceptions matching the applied filters"},"total_count":{"type":"integer","description":"Total number of exceptions (ignoring filters)"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalError"}},"tags":["Issues"]}}},"components":{"schemas":{"IssueException":{"type":"object","description":"Full issue exception object as returned by the public API","properties":{"exception_id":{"type":"integer","nullable":true,"description":"Auto-incremented exception ID"},"external_exception_id":{"type":"string","nullable":true,"description":"External tracking ID"},"name":{"type":"string","description":"Exception name"},"status":{"type":"string","enum":["APPROVED","DISABLED","EXPIRED","NO_DECISION_MADE","PENDING_DECISION","REJECTED","SELF_APPROVED"],"description":"Exception status"},"rule":{"type":"string","description":"JSON-encoded filter rule"},"pretty_rule":{"type":"string","nullable":true,"description":"Human-readable representation of the rule"},"justification_text":{"type":"string","description":"Justification text"},"justification_category":{"type":"string","enum":["COMPENSATING_CONTROL","PLANNED_REMEDIATION","RISK_ACCEPTED","VENDOR_DEPENDENCY"],"nullable":true,"description":"Justification category"},"approval_justification":{"type":"string","nullable":true,"description":"Approval decision justification"},"requestor_name":{"type":"string","description":"Name of the user who requested the exception"},"requestor_email":{"type":"string","description":"Email of the user who requested the exception"},"approver_email":{"type":"string","nullable":true,"description":"Email of the assigned approver"},"approver_name":{"type":"string","nullable":true,"description":"Name of the assigned approver"},"created_ts":{"type":"string","format":"date-time","nullable":true,"description":"Creation timestamp"},"modified_ts":{"type":"string","format":"date-time","nullable":true,"description":"Last modification timestamp"},"approval_ts":{"type":"string","format":"date-time","nullable":true,"description":"Approval decision timestamp"},"expiration_ts":{"type":"string","format":"date-time","description":"Exception expiration timestamp"},"impacted_issues_count":{"type":"integer","description":"Number of issues impacted by this exception"},"backward_scan_status":{"type":"string","enum":["COMPLETED","FAILED","IN_PROGRESS","PENDING"],"nullable":true,"description":"Status of backward scan"},"backward_scan_ts":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp of the last backward scan"},"reversion_scan_status":{"type":"string","enum":["COMPLETED","FAILED","IN_PROGRESS","PENDING"],"nullable":true,"description":"Reversion scan status"},"reversion_scan_ts":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp of the last reversion scan"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"Unauthorized":{"description":"Unauthorized access","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"InternalError":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}
```
## Insert parsed alerts
> Upload alerts from external alert sources in Cortex XDR format. Cortex XDR displays alerts that are parsed successfully in related incidents and views.\
> \
> You can send 600 alerts per minute. Each request can contain a maximum of 60 alerts.\
> \
> Required license: \*\*Cortex XDR Pro per Endpoint\*\* or \*\*Cortex XDR Pro per GB\*\*
```json
{"openapi":"3.0.0","info":{"title":"Cortex AgentiX APIs","version":"Cortex AgentiX"},"tags":[{"name":"Issues","description":"APIs for managing issues"}],"servers":[{"url":"https://api-yourfqdn"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","name":"Authorization","in":"header"}},"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."}}}}},"paths":{"/public_api/v1/alerts/insert_parsed_alerts/":{"post":{"operationId":"insertParsedAlerts","tags":["Issues"],"summary":"Insert parsed alerts","description":"Upload alerts from external alert sources in Cortex XDR format. Cortex XDR displays alerts that are parsed successfully in related incidents and views.\n\nYou can send 600 alerts per minute. Each request can contain a maximum of 60 alerts.\n\nRequired license: **Cortex XDR Pro per Endpoint** or **Cortex XDR Pro per GB**","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"request_data":{"type":"object","description":"The request payload containing the alerts to upload.","properties":{"alerts":{"type":"array","description":"The external alerts you want to upload to Cortex XDR.","items":{"type":"object","properties":{"product":{"type":"string","description":"The name of the product that generated the alert."},"vendor":{"type":"string","description":"The name of the vendor that generated the alert."},"local_ip":{"type":"string","description":"The local IPv4 address associated with the alert."},"local_port":{"type":"string","description":"The local port associated with the alert."},"remote_ip":{"type":"string","description":"The remote IPv4 address associated with the alert."},"remote_port":{"type":"string","description":"The remote port associated with the alert."},"event_timestamp":{"type":"integer","description":"The Unix timestamp (in milliseconds) of when the event occurred."},"severity":{"type":"string","description":"The severity of the alert.","enum":["Low","Medium","High","Critical"]},"alert_name":{"type":"string","description":"The name of the alert."},"alert_description":{"type":"string","description":"A description of the alert."},"action_status":{"type":"string","description":"The action status of the alert (for example, `Reported`)."},"local_ip_v6":{"type":"string","description":"The local IPv6 address associated with the alert."},"remote_ip_v6":{"type":"string","description":"The remote IPv6 address associated with the alert."}}}}}}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"boolean","description":"`true` indicates the upload was successful."}}}},"400":{"description":"Bad Request. Got an invalid JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"401":{"description":"Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"402":{"description":"Unauthorized access. User does not have the required license type to run this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"403":{"description":"Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"500":{"description":"Internal server error. A unified status for API communication type errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}}}}}}}
```
---
# 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/agentix-api/cortex-agentix/issues.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.