---
title: "Start scan"
method: POST
path: "/v1/code-audit/scans"
tags: ["Code Audit"]
---

# Start scan

`POST /v1/code-audit/scans`

## Request

- Base URL: `https://api.inth.com`
- URL: `https://api.inth.com/v1/code-audit/scans`
- Auth: HTTP bearer

Starts a scan of the production branch of a connected repository. The first scan of a repository is a free preview. Answers 202 with the scan once the workflow has created it, or with the scan request to poll when that takes longer than a few seconds. Requires code-audit.write, a user token, and an admin or owner role.

## Request body

- StartCodeAuditScanRequest
  - `repositoryId` string, required: Repository ID from the connected repositories list.
  - `requestId` string: Idempotency key. Repeating a request with the same key does not start a second scan.

## Response `202`

The scan was accepted.

- object
  - `success` true, required
  - `data` union, required
    - object
      - `status` 'started', required
      - `scan` CodeAuditScan, required
        - `id` string, required
        - `organizationId` string, required
        - `repositoryId` string, required
        - `repositoryName` string, required
        - `branch` string, nullable, required
        - `headCommitSha` string, nullable, required
        - `pullRequestNumber` integer, nullable, required
        - `scope` string, required: What was scanned: repository, pull_request, and so on.
        - `trigger` string, required: What started the scan: manual, pull_request, scheduled.
        - `status` string, required
        - `access` 'full' | 'free-preview' | 'locked', required: Whether every finding is readable. A free preview shows a subset until unlocked.
        - `unlockCredits` integer, nullable, required: Credits needed to unlock a free preview.
        - `findingCount` integer, nullable, required
        - `issueCount` integer, nullable, required
        - `progress` object, nullable, required
          - `stage` string, required
          - `stageStatus` string, nullable, required
          - `completedStages` integer, nullable, required
          - `totalStages` integer, nullable, required
        - `createdAt` string, date-time, required
        - `startedAt` string, date-time, nullable, required
        - `completedAt` string, date-time, nullable, required
    - object
      - `status` 'starting', required
      - `preparationId` string, required: Poll the scan request with this ID.
      - `repositoryId` string, required

## Other responses

- `400`: The request payload or parameters are invalid.
- `401`: Authentication is missing, invalid, or expired.
- `402`: The organization does not hold enough credits. `details` carries the remaining and required amounts. Enable automatic top-ups or buy credits in the dashboard.
- `403`: The credential is valid but may not perform the operation. `INSUFFICIENT_SCOPE`: the credential was never granted the capability the operation needs. `details.requiredScope` names it, and the `WWW-Authenticate` header carries `Bearer error="insufficient_scope"`. An OAuth client fixes this by requesting the scope; an organization API key cannot gain it. `FORBIDDEN`: the capability is present but the membership behind the credential lacks the role, or the resource belongs to another organization.
- `404`: The requested resource was not found.
- `409`: A scan is already running (`SCAN_IN_PROGRESS`), the previous free preview must be unlocked first (`UNLOCK_REQUIRED`), or the repository is not linked to a project (`REPOSITORY_NOT_LINKED`).
- `413`: The request body exceeds the 1 MB limit.
- `429`: The rate limit was exceeded. API key limits are set by plan tier (Starter 600/min, Pro 1500/min, Enterprise 3000/min). Check the Retry-After header before retrying.
- `500`: An unexpected internal error occurred.
- `503`: The capability is temporarily paused by an operator. Retry later.

## Changes

- **2026-09-08** `66c8f6ac2730`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/inth/apis/inth-api/changes/v1/code-audit/scans/post.md)

---

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