---
title: "Start a new scan"
method: POST
path: "/scans"
tags: ["Scans"]
---

# Start a new scan

`POST /scans`

## Request

- Base URL: `https://public.escape.tech/v3`
- URL: `https://public.escape.tech/v3/scans`
- Auth: API key in header `X-ESCAPE-API-KEY`

Start a new scan

## Request body

- object
  - `profileId` string, required: The profile ID to use
  - `commitHash` string: The commit hash to scan
  - `commitLink` string: The commit link to scan
  - `commitBranch` string: The commit branch to scan
  - `commitAuthor` string: The commit author to scan
  - `commitAuthorProfilePictureLink` string: The commit author profile picture link to scan
  - `forceLockBypass` boolean: Bypass the lock that prevents concurrent scans of the same profile
  - `configurationOverride` unknown
  - `initiator` 'CI' | 'MANUAL' | 'SCHEDULED' | 'null', nullable: The initiator of the scan

## Response `200`

OK

- object
  - `id` string, uuid, required: The id of the scan
  - `status` string, required: The status of the scan
  - `createdAt` string, required: The date and time the scan was created
  - `updatedAt` string, required: The date and time the scan was updated
  - `finishedAt` string, nullable, required: The date and time the scan was finished
  - `score` number, nullable, required: The score of the scan
  - `coverage` number, nullable, required: Aggregate API coverage ratio for this scan (0–1), when the scan has finished with coverage data
  - `duration` number, required: The duration of the scan
  - `progressRatio` number, required: The progress ratio of the scan
  - `initiator` string, required: The initiator of the scan
  - `kind` string, required: The kind of the scan
  - `profileId` string, required: The id of the profile of the scan
  - `organizationId` string, required: The id of the organization of the scan
  - `commitHash` string, nullable, required
  - `commitBranch` string, nullable, required
  - `commitAuthor` string, nullable, required
  - `commitLink` string, nullable, required
  - `commitAuthorProfilePictureLink` string, nullable, required
  - `ignored` boolean: Whether the scan is ignored. Only returned by the scan detail endpoint.
  - `executiveSummary` string, nullable: AI-generated executive summary of the scan. Credentials and secrets are redacted. Only returned by the scan detail endpoint.
  - `scopeSummary` string, nullable: AI-generated summary of the scanned scope. Credentials and secrets are redacted. Only returned by the scan detail endpoint.
  - `problems` object[]: Validation problems surfaced by the scanner during this scan. Only returned by the scan detail endpoint.
    - `id` string, uuid, required: The id of the problem
    - `code` 'AUTH_FAILURE' | 'BLOCKED_BY_CORS' | 'BLOCKED_BY_WAF' | 'CAPTCHA_HIT' | 'CONFIGURATION_IMPROVEMENT' | 'HIGH_NUMBER_OF_ERROR_ENDPOINTS' | 'INTEGRATION_ERROR' | 'NO_AUTHENTICATION_CONFIGURED' | 'NO_SCHEMA_FOUND' | 'PL_FAILURE' | 'RATE_LIMIT_EXCEEDED' | 'SCHEMA_IMPROVEMENT' | 'TIMEOUT' | 'UNEXPECTED_ERROR' | 'UNREACHABLE_ASSET', required: The problem code
    - `message` string, required: The problem message
    - `severity` 'ERROR' | 'INFO' | 'WARNING', required: The problem severity
    - `createdAt` string, required: The date and time the problem was created
  - `artefacts` object[]: Files produced by this scan, such as executive reports. Only returned by the scan detail endpoint.
    - `id` string, uuid, required: The id of the artefact
    - `kind` 'AUDITOR_REPORT' | 'EVENTS_ARCHIVE' | 'EXCHANGES_ARCHIVE' | 'EXECUTIVE_REPORT' | 'EXPORT_JOB_RESULT', required: The kind of the artefact
    - `name` string, required: The name of the artefact
    - `signedUrl` string, required: Time-limited HTTPS download URL for the artefact
    - `createdAt` string, required: The date and time the artefact was created
    - `updatedAt` string, required: The date and time the artefact was updated
  - `links` object, required
    - `scanIssues` string, required: URL to view the scan issues in the platform

## Other responses

- `400`: Bad Request

---

[API](https://skmtc.dev/escape/apis/escape-public-api.md) - [All operations](https://skmtc.dev/escape/apis/escape-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/escape/apis/escape-public-api/revisions/2eab35df40c7?raw)