---
title: "Run scan (sync/async)"
method: POST
path: "/scans/run"
tags: ["Scans"]
---

# Run scan (sync/async)

`POST /scans/run`

## Request

- Base URL: `https://app.codethreat.com/api/v1`
- URL: `https://app.codethreat.com/api/v1/scans/run`
- Auth: API key in header `X-API-Key`

Start a scan and optionally wait for completion

## Request body

- RunScanRequest
  - `repositoryId` string, required
  - `branch` string
  - `scanTypes` string[]
  - `wait` boolean: Wait for scan completion
  - `timeout` integer: Timeout in seconds (only if wait=true)
  - `pollInterval` integer: Poll interval in seconds (only if wait=true)
  - `scanTrigger` 'manual' | 'ci/cd' | 'api'
  - `pullRequestId` string
  - `commitSha` string
  - `metadata` object

## Response `200`

Scan completed (if wait=true)

- ScanResponse
  - `success` boolean
  - `data` object
    - `id` string
    - `repositoryId` string
    - `status` 'PENDING' | 'SCANNING' | 'COMPLETED' | 'FAILED'
    - `scanTypes` string[]
    - `branch` string
    - `commit` string
    - `startedAt` string, date-time
    - `completedAt` string, date-time
    - `duration` integer
    - `violationCount` object
      - `critical` integer
      - `high` integer
      - `medium` integer
      - `low` integer
      - `info` integer
  - `pagination` Pagination
    - `page` integer
    - `limit` integer
    - `total` integer
    - `totalPages` integer
    - `hasNext` boolean
    - `hasPrev` boolean
  - `meta` ResponseMeta
    - `timestamp` string, date-time
    - `version` string
    - `requestId` string
    - `organizationId` string

## Other responses

- `202`: Scan started (if wait=false)

---

[API](https://skmtc.dev/codethreat/apis/codethreat-api.md) - [All operations](https://skmtc.dev/codethreat/apis/codethreat-api/llms.txt) - [OpenAPI document](https://skmtc.dev/codethreat/apis/codethreat-api/revisions/18f11fecbb30?raw)