> 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/application-security/code-security/api-workflows-for-code-security-issues.md).

# API workflows for Code Security issues

The Code Security public APIs enable programmatic access to security issues and findings generated by the scan engine. Automate issue triage, verify shift-left enforcement, build posture dashboards, and feed findings into ticketing systems, all through scan-scoped REST endpoints.

**API reference**: For request and response schemas, parameters, and errors, see [Scan Management](/cortex-cloud-api/aspm-cicd-and-application-security/scan-management.md).

**Scope**: This guide covers issue and finding retrieval. For scan orchestration, see [Manage scans through public APIs](/application-security/code-security/application-security-scans-management/manage-scans-through-public-apis.md). For application summaries, see [Manage applications via public APIs](/application-security/application-security-posture-management-aspm/applications/manage-applications-via-public-apis.md).

## Base URL and authentication

**Base URL**: `https://<your-tenant>.xdr.us.paloaltonetworks.com/public_api/appsec/v1`

Replace `<your-tenant>` with your tenant identifier. The region-specific domain varies by deployment.

### Authentication headers

| Header          | Value          |
| --------------- | -------------- |
| `x-xdr-auth-id` | API Key ID     |
| `Authorization` | API Key Secret |

Generate an API key pair from **Settings** → **Configurations** → **API Keys** in the Cortex Cloud console. The API key role must grant read access to scan results and application resources in the ASPM module.

## Available endpoints

| Endpoint                                                  | Method | Returns                                                                                                                                           | Granularity              |
| --------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
| `/scans/periodic`                                         | GET    | Periodic scan results with issue type breakdowns (`issuesTypesBreakdown`) and severity breakdowns                                                 | Scan-level summary       |
| `/scans/pr`                                               | GET    | PR scan results with blocking policy details and issue type breakdowns (`issuesTypesBreakdown`)                                                   | Scan-level summary       |
| `/scans/ci`                                               | GET    | CI/CD scan results with blocking status and issue type breakdowns (`issuesTypesBreakdown`)                                                        | Scan-level summary       |
| `/scans/{scanId}/issues`                                  | GET    | Individual issue records found during the specific scan, including severity level, detection method (issue type), resolution status, and assignee | Issue-level detail       |
| `/scans/{scanId}/findings`                                | GET    | Raw scanner findings with finding category (issue type), detection method, file path, git user, suppression type, timestamps                      | Finding-level detail     |
| `/application/{applicationId}/issues/{issueType}/summary` | GET    | Issue count breakdown by severity for a specific application and issue type                                                                       | Application-level count  |
| `/scans/unscanned-repositories`                           | GET    | Repositories without a recent scan                                                                                                                | Repository-level summary |
| `/scan/repository/{repositoryId}`                         | POST   | A rerun of a repository scan                                                                                                                      | Scan request             |

## Issue retrieval pattern

![issue-retrieval-workflow.png](https://3701104179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8Z0RLJ1BFF5TQL8VtUeK%2Fuploads%2Fgit-blob-fb1bd9215bb7faf390b5293bc6f8d8af1c69b829%2Fba4c20fd5939d2ba7fbbd3e5ae7a4bd7784d739c248e29e04a7d5c9a02ab9977.png?alt=media)

## Retrieve issues by scan type

All scan types follow the same two-step pattern: list scans with filters, then retrieve issues or findings by `scanId`.

### Periodic scans

Periodic scans assess the security posture of your onboarded repositories. Use periodic scan issues for compliance reporting, posture trending, and remediation tracking.

**Step 1: List periodic scans**: `GET /scans/periodic` with filters for organization, repository, branch, scan health, and time range (`days`).

````programlisting
```bash
curl -X GET "https://<your-tenant>.xdr.us.paloaltonetworks.com/public_api/appsec/v1/scans/periodic?organizationName=my-org&scanHealth=COMPLETED&days=7&limit=50" \
  -H "x-xdr-auth-id: <KEY_ID>" \
  -H "Authorization: <KEY_SECRET>"
```
````

**Step 2 — Retrieve issues**: `GET /scans/{scanId}/issues` with optional `severity` filter.

{% hint style="info" %}

### Tip

Use the `issuesTypesBreakdown` and `issuesFound` fields in the scan list response to identify scans with Critical or High issues before drilling into individual records, thereby reducing API calls.
{% endhint %}

### PR scans

PR scans execute when a pull request is opened or updated. PR scan results indicate whether prevention policies blocked the merge; the primary shift-left enforcement point.

**Step 1 — List PR scans**: `GET /scans/pr` with filters for organization, repository, branch, PR ID, PR status, and time range.

**Step 2 — Retrieve issues from a blocked PR**: Use the `scanId` from the PR scan result. Key response fields include `pullRequestStatus`, `blockingPolicyName`, `blockingPolicyId`, `userEmail`, and `commitId`.

{% hint style="info" %}

### Note

Use `blockingPolicyId` and `blockingPolicyName` to identify the policy associated with the result. Evaluate `pullRequestStatus` separately.
{% endhint %}

### CI scans

CI scans execute during automated build pipelines. CI blocking is a second enforcement point after PR scans.

**Step 1 — List CI scans**: `GET /scans/ci` with filters for organization, repository, CI status, scan health, and time range.

**Step 2 — Retrieve issues from a blocked build**: Use the `scanId` from the CI scan result. Key response fields include `ciStatus`, `blockingPolicyName`, and `blockingPolicyId`.

## Retrieve findings

Raw findings provide scanner-level detail not available in issue records — git author attribution, suppression status, first/last observed timestamps, and scan source identification. Use findings for false positive investigation, suppression pattern analysis, and detailed forensics.

**Endpoint**: `GET /scans/{scanId}/findings` with optional `severity` filter.

````programlisting
```bash
curl -X GET "https://<your-tenant>.xdr.us.paloaltonetworks.com/public_api/appsec/v1/scans/scan-a1b2c3d4/findings?severity=High&limit=100" \
  -H "x-xdr-auth-id: <KEY_ID>" \
  -H "Authorization: <KEY_SECRET>"
```
````

**Key fields available in findings but not in issues**: `git_user`, `suppression_type`, `first_observed`, `last_observed`, `scan_source`, `first_hash`, `platform_id`, and `data_source`.

## Retrieve issues by type

The issue endpoint (`/scans/{scanId}/issues`) does not support server-side filtering by issue type or detection method. To retrieve issues of a specific type (for example, all IaC misconfigurations), use the `issuesTypesBreakdown` field to pre-filter scans, then apply client-side filtering on `detection_method`.

{% hint style="info" %}

### Note

The `severity` query parameter is the only server-side filter available on the issue endpoint. Filtering by detection method, resolution status, or assignee requires client-side processing.
{% endhint %}

| Step | Action                                                                                                                               |
| ---- | ------------------------------------------------------------------------------------------------------------------------------------ |
| 1    | **List Scans:** Send a `GET /scans/periodic?days=7&scanHealth=COMPLETED` to identify recent baseline scans.                          |
| 2    | **Inspect Summary:** Check the `issuesTypesBreakdown` field in the response. Skip scans where the target issue type count is zero.   |
| 3    | **Retrieve Issues:** For scans with relevant findings, call `GET /scans/{scanId}/issues` to retrieve all issues from matching scans. |
| 4    | **Filter Client-Side:** Filter by the `detection method` field (such as **IaC Security**) to isolate specific types of scan results. |

#### Mapping `issuesTypesBreakdown` keys to `detection_method` values

Use this mapping to match an `issuesTypesBreakdown` key with its `detection_method` value.

| <p>issuesTypesBreakdown key</p><p>(summary type)</p> | <p>detection\_method value</p><p>(issue type)</p> | Scanner category               |
| ---------------------------------------------------- | ------------------------------------------------- | ------------------------------ |
| Vulnerabilities                                      | `Cve Security`                                    | SCA: CVE vulnerability scanner |
| Secrets                                              | `Secrets Security`                                | Secrets scanner                |
| IaC                                                  | `IaC Security`                                    | IaC misconfiguration scanner   |

{% hint style="info" %}

### Note

License compliance (`License Security`) and package operational risk (`Operational Risk Security`) are not represented as separate keys in `issuesTypesBreakdown`. To retrieve these issue types, filter client-side by `detection_method` from the full issue set.
{% endhint %}

#### All Code Security `detection_method` values

| Value                       | Scanner                                                                   |
| --------------------------- | ------------------------------------------------------------------------- |
| `Cve Security`              | CVEs in open-source dependencies                                          |
| `Secrets Security`          | Hardcoded secrets, API keys, tokens, credentials                          |
| `IaC Security`              | IaC misconfigurations (Terraform, CloudFormation, Kubernetes, ARM, Bicep) |
| `Operational Risk Security` | Deprecated, unmaintained, or low-adoption packages                        |
| `License Security`          | Non-compliant open-source licenses                                        |

## Application-level issue summaries

Application issue summaries provide issue counts by severity for a specific application and issue type, without iterating through individual scans. Use for executive dashboards and application-level posture monitoring.

**Endpoint**: `GET /public_api/appsec/v1/application/{applicationId}/issues/{issueType}/summary`.

Supported issue types:

| Value               | Category                                     |
| ------------------- | -------------------------------------------- |
| `Vulnerabilities`   | CVE — open-source dependency vulnerabilities |
| `Secrets`           | Hardcoded secrets and credentials            |
| `Misconfigurations` | IaC misconfigurations                        |
| `CodeWeaknesses`    | Code weaknesses                              |

{% hint style="info" %}

### Note

Application issue summaries return counts only, not individual issue records. To retrieve individual records, list periodic scans for the application's repositories, then use `GET /scans/{scanId}/issues`.
{% endhint %}

## Common automation workflows

### Automated triage

Use recent periodic scans to create tickets for Critical issues.

| Step | Action                                                                  |
| ---- | ----------------------------------------------------------------------- |
| 1    | List completed periodic scans from the last day                         |
| 2    | Retrieve Critical issues for each `scanId`                              |
| 3    | Create tickets with the issue name, severity, file path, and asset name |

### Shift-left verification

Measure prevention by comparing blocked results with all PR and CI scan results.

| Step | Action                                                  |
| ---- | ------------------------------------------------------- |
| 1    | List PR scans for the reporting period                  |
| 2    | Count results by `pullRequestStatus`                    |
| 3    | List CI scans and count results by `ciStatus`           |
| 4    | Calculate the blocked proportion across both scan types |

### Posture trending

Track periodic scan results over time to identify remediation progress.

| Step | Action                                                               |
| ---- | -------------------------------------------------------------------- |
| 1    | List periodic scans for the reporting period                         |
| 2    | Use `issuesFound` for summary trends                                 |
| 3    | Retrieve issues when severity or detection-method detail is required |

### Coverage gap remediation

Identify repositories without recent scans, then request a repository scan.

| Step | Action                                                          |
| ---- | --------------------------------------------------------------- |
| 1    | Call `GET /scans/unscanned-repositories?days=14`                |
| 2    | Call `POST /scan/repository/{repositoryId}` for each repository |
| 3    | Retrieve issues after the scan completes                        |

## Operational notes

* **Issue data is scan-scoped.** Each issue belongs to a specific scan execution. Use `issuesFound` and `issuesTypesBreakdown` in scan list responses to pre-filter before retrieving individual records
* **Client-side filtering.** The issue endpoint supports only `severity` as a server-side filter. Filter by detection method, resolution status, or assignee client-side
* **Issue lifecycle management.** Resolution status updates and assignee changes are managed through the console. The APIs provide read access to current state
* **Urgency context.** Urgency classification is displayed in the console. The API issue response includes severity. For Urgency-based prioritization, use the console issue tables. Refer to [Urgency](/application-security/application-security-posture-management-aspm/urgency.md) for more details
* **Pagination.** Use `limit` and `offset` to paginate. Continue until the response returns fewer results than the requested `limit`

## Related topics

* [Manage scans through public APIs](/application-security/code-security/application-security-scans-management/manage-scans-through-public-apis.md)
* [Manage applications via public APIs](/application-security/application-security-posture-management-aspm/applications/manage-applications-via-public-apis.md)
* [Scan Management](/cortex-cloud-api/aspm-cicd-and-application-security/scan-management.md)


---

# 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/application-security/code-security/api-workflows-for-code-security-issues.md?ask=<question>&goal=<endgoal>
```

`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.