> ## Documentation Index > Fetch the complete documentation index at: https://semgrep-ee9d73d8-api-changelog-from-openapi.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # List scans (beta) > List the scans associated with a particular repository over the past 30 days. ## OpenAPI ````yaml /public_v1.openapi.yaml post /api/v1/deployments/{deploymentId}/scans/search openapi: 3.0.3 info: description: > Welcome to Semgrep's portal for the Semgrep AppSec Platform web API. # Introduction Semgrep is a fast, open-source, static analysis tool for finding bugs and enforcing code standards at editor, commit, and CI time. [Get started.](https://semgrep.dev/docs/getting-started/) This API is documented in the **OpenAPI format**. # Authentication The API supports authentication with an API token with the "Web API" permission, without limited scopes of access. You can provision an API token [from the Settings page](https://semgrep.dev/orgs/-/settings/tokens). # Terms of Use Please note, the materials made available herein are subject to the [Semgrep Terms of Use](https://semgrep.dev/resources/website-terms/), and your access or use of any of the same is your acknowledgment and acceptance of the such terms.
___ title: Semgrep Web App version: 1.0.0 servers: - url: https://semgrep.dev description: Semgrep AppSec Platform security: [] tags: - description: >- Deployments encapsulate your organization's security organization, with multiple projects, policies, and integrations. As the root object of the organization, they're similarly the root object of the API. name: DeploymentsService x-displayName: Deployment x-group: Deployment - description: >- Manage and retrieve code, supply chain, and AI-powered detection findings from Semgrep scans name: FindingsService x-displayName: Code, Supply Chain, and AI-powered detection x-group: Code, Supply Chain, and AI-powered detection - description: Utility endpoints. name: MiscService x-displayName: Other x-group: Other - description: >- **Deprecated.** View and manage the Policies of your organization. This API is deprecated. Use the [Policies V2 API](/api/v2/docs/#tag/PoliciesV2Service) instead. Once a deployment is migrated to the Unified Policies model, every endpoint in this service returns `410 Gone` with the error code `DEPLOYMENT_MIGRATED`. name: PoliciesService x-displayName: Policies x-group: Policies - name: ProjectsService x-displayName: Projects x-group: Projects - description: View details of scans associated with projects in your organization. name: ScansService x-displayName: Scans x-group: Scans - description: View and manage the Secrets of your organization. name: SecretsService x-displayName: Secrets x-group: Secrets - description: |- Manage the Supply Chain findings and dependencies of your organization. A request body is required, but may be an empty object. name: SupplyChainService x-displayName: Supply Chain x-group: Supply Chain - description: Create and manage external tickets name: TicketingService x-displayName: Ticketing x-group: Ticketing - description: View and manage the triage of your organization. name: TriageService x-displayName: Triage x-group: Triage paths: /api/v1/deployments/{deploymentId}/scans/search: post: tags: - ScansService summary: List scans (beta) description: >- List the scans associated with a particular repository over the past 30 days. operationId: ScansService_SearchScans parameters: - in: path name: deploymentId required: true schema: description: >- Deployment ID (numeric). Example: `123`. Can be found at `/deployments`, or in your Settings in the web UI. example: 123 format: int64 type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/protos.openapi.v1.SearchScansRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/protos.openapi.v1.SearchScansResponse' description: OK security: - SemgrepWebToken: [] components: schemas: protos.openapi.v1.SearchScansRequest: properties: branch: description: Only get scans from the specified branch type: string cursor: description: Cursor to paginate through the results type: string deploymentId: description: >- Deployment ID (numeric). Example: `123`. Can be found at `/deployments`, or in your Settings in the web UI. example: 123 format: int64 type: string is_full_scan: description: Only get scans that are full scans (if false, only get diff scans) type: integer is_partial_scan: description: >- Only get scans that ran an explicit subset of rules rather than the full rule set (if false, only get scans that ran the full rule set). Independent of `is_full_scan`: a supply chain incident scan covers the whole project but runs only the rules for that incident, so it reports `is_full_scan: true` and `is_partial_scan: true`. type: boolean limit: description: >- Page size to paginate through the results (default is 100, max is 500) type: integer products: description: |+ Only get scans that have these enabled products | value | description | |-------|---------------| | PRODUCT_SAST | | | PRODUCT_SCA | | | PRODUCT_SECRETS | | | PRODUCT_AI_SAST | | enum: - PRODUCT_SAST - PRODUCT_SCA - PRODUCT_SECRETS - PRODUCT_AI_SAST items: enum: - PRODUCT_UNSPECIFIED - PRODUCT_SAST - PRODUCT_SCA - PRODUCT_SECRETS - PRODUCT_AI_SAST format: enum type: string type: array repository_id: description: Only get scans for this repo type: integer since: description: >- Only get scans created after this time. Provide time in ISO 8601 format. format: date-time type: string statuses: description: >+ Only get scans that have one of these statuses | value | description | |-------|---------------| | SCAN_STATUS_RUNNING | The scan is currently running | | SCAN_STATUS_COMPLETED | The scan has completed successfully (0 or 1 exit code) | | SCAN_STATUS_PENDING | The scan is queued and waiting to start | | SCAN_STATUS_CANCELLED | The scan was cancelled before completion | | SCAN_STATUS_ERROR | The scan has exited with a failure (exit code not 0 or 1) | | SCAN_STATUS_NEVER_FINISHED | The scan did not report an error or success after over an hour | enum: - SCAN_STATUS_RUNNING - SCAN_STATUS_COMPLETED - SCAN_STATUS_PENDING - SCAN_STATUS_CANCELLED - SCAN_STATUS_ERROR - SCAN_STATUS_NEVER_FINISHED items: enum: - SCAN_STATUS_UNSPECIFIED - SCAN_STATUS_RUNNING - SCAN_STATUS_COMPLETED - SCAN_STATUS_PENDING - SCAN_STATUS_CANCELLED - SCAN_STATUS_ERROR - SCAN_STATUS_NEVER_FINISHED format: enum type: string type: integer total_time: $ref: '#/components/schemas/protos.common.v1.FloatRange' required: - deployment_id title: Search Scans Request type: object protos.openapi.v1.SearchScansResponse: properties: cursor: description: Cursor to retrieve the next page of results. type: string scans: description: List of scans. items: $ref: '#/components/schemas/protos.scan.v1.ScanPublic' type: array type: object protos.common.v1.FloatRange: properties: max: description: End of the range format: float type: number min: description: Start of the range format: float type: number title: Float Range type: object protos.scan.v1.ScanPublic: properties: branch: description: The scanned branch example: main type: string commit: description: The commit hash that was scanned example: 6d3de02545f820febf2af9820568fa5f697d4087 type: string completed_at: description: The timestamp when this scan completed (if it has completed). example: '2020-11-18T23:30:10.216Z' format: date-time type: string deployment_id: description: Unique identifier for the deployment of the scan. format: int64 type: string enabled_products: description: The products used when running the scan. example: - secrets items: type: string type: array exit_code: description: >- The exit_code of the scan (see https://semgrep.dev/docs/cli-reference#exit-codes) example: 0 format: int64 type: string findings_counts: $ref: '#/components/schemas/protos.scan.v1.ScanFindingsCounts' id: description: ID of the scan. format: int64 type: string is_full_scan: description: Whether the scan was a full scan (true) or a diff scan (false) example: true type: boolean is_partial_scan: description: >- Whether the scan ran an explicit subset of rules rather than the full rule set. Independent of `is_full_scan`: a supply chain incident scan covers the whole project but runs only the rules for that incident, so both are true. Findings counts for products whose rules did not run will be zero because nothing was checked, not because nothing was found. example: false type: boolean repository_id: description: Unique identifier for the repository of the scan. format: int64 type: string started_at: description: The timestamp when this scan started. example: '2020-11-18T23:28:12.391Z' format: date-time type: string status: description: >+ The current status of the scan | value | description | |-------|---------------| | SCAN_STATUS_RUNNING | The scan is currently running | | SCAN_STATUS_COMPLETED | The scan has completed successfully (0 or 1 exit code) | | SCAN_STATUS_PENDING | The scan is queued and waiting to start | | SCAN_STATUS_CANCELLED | The scan was cancelled before completion | | SCAN_STATUS_ERROR | The scan has exited with a failure (exit code not 0 or 1) | | SCAN_STATUS_NEVER_FINISHED | The scan did not report an error or success after over an hour | enum: - SCAN_STATUS_RUNNING - SCAN_STATUS_COMPLETED - SCAN_STATUS_PENDING - SCAN_STATUS_CANCELLED - SCAN_STATUS_ERROR - SCAN_STATUS_NEVER_FINISHED example: SCAN_STATUS_RUNNING format: enum type: string total_time: description: Duration of scan, in seconds example: 17.32 format: float type: number type: object protos.scan.v1.ScanFindingsCounts: properties: code: description: Total number of Code findings in the scan example: 2 format: int64 type: string secrets: description: Total number of Secrets findings in the scan example: 1 format: int64 type: string supply_chain: description: Total number of Supply Chain findings in the scan example: 1 format: int64 type: string total: description: Total number of findings in the scan example: 4 format: int64 type: string type: object securitySchemes: SemgrepWebToken: bearerFormat: string description: >- Get access to data with your API token. Example header: `Authorization: Bearer 2991e2fb4b540fe75b8f90677b0b892b6314e4961cb001fe6eb452eee248a628` The token can be provisioned from the Tokens section in your Settings, and requires explicitly enabling `Web API` access. scheme: bearer type: http ````