# Launch a scan

POST

/projects/{projectId}/scans

```js
const url = 'https://zkao.io/api/v1/projects/example/scans';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"repositoryId":"example","creditBudget":1,"presetRef":"example","branch":"example","commitHash":"example","commitMessage":"example","baseCommit":"example","backlogRecheck":{"includeInProgress":true,"findingIds":["example"],"resumeScanId":"example"},"trigger":{"kind":"github_action","pullRequest":1,"commentId":"example"},"auditAreaKeys":["example"],"auditScope":"example","guidance":"example"}'
};


try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```sh
curl --request POST \
  --url https://zkao.io/api/v1/projects/example/scans \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "repositoryId": "example", "creditBudget": 1, "presetRef": "example", "branch": "example", "commitHash": "example", "commitMessage": "example", "baseCommit": "example", "backlogRecheck": { "includeInProgress": true, "findingIds": [ "example" ], "resumeScanId": "example" }, "trigger": { "kind": "github_action", "pullRequest": 1, "commentId": "example" }, "auditAreaKeys": [ "example" ], "auditScope": "example", "guidance": "example" }'
```

* Production`zkao.io/api/v1/projects/{projectId}/scans`
* Staging`staging.zkao.io/api/v1/projects/{projectId}/scans`

Requires scope: `scans:launch`. Reserves `creditBudget` credits from the project balance. The repo must be in the token’s allowlist (when set) and ACTIVE. Discover valid `presetRef` values via `/scan-presets`. Each scan type runs a fixed set of flows. Per-token spend limits are enforced, and the project must have enough prepaid credits to cover the budget (otherwise `402`).

A repository added moments ago may still be analyzing, in which case this returns `409 repository_initializing`. Wait for its `readiness` to be `ready` in `GET /repositories` and launch again.

A diff scan preset audits only the change from `baseCommit` to the scanned commit, and requires `baseCommit`. Every other preset refuses it. A malformed, unknown, or misplaced base is a `400` with code `diff_base_required`, `diff_base_not_allowed`, or `diff_base_invalid`. A diff scan also needs a change to audit (otherwise `422`).

The builtin presets come in two tiers. Flash runs one focused analysis, led by a flagship model when it audits the code or a change. Max runs every technique on flagship models. Each tier has a preset for the code (`builtin:Flash`, `builtin:Max`), a change (`builtin:Flash Diff`, `builtin:Max Diff`), open findings (`builtin:Flash Retriage`, `builtin:Max Retriage`) and resolved findings (`builtin:Flash Regression Check`, `builtin:Max Regression Check`). Earlier names, such as `builtin:Rapid Review`, `builtin:Deep Audit` and `builtin:Diff Scan`, still resolve.

## Authorizations

* **[bearerAuth](https://docs.staging.zkao.io/api/#bearerauth)**

## Parameters

### Path Parameters

* **projectId**

  required

  string

## Request Bodyrequired

application/json

object

* **repositoryId**

  required

  string

* **creditBudget**

  Max budget for the scan, in credits. Reserved at launch. Omit it to launch at the budget zkao recommends for this scan type and scope on this repository. A Flash or Max scan of the code is sized from the audit areas it reads: the selected areas, or every area in the repository map. One area gets the minimum, and the budget grows with the square root of the area count. With no map, or with `auditScope`, it is twice the minimum. It is half again the last budget when the last scan of the same scope ran short of it. A diff scan is sized from its change instead: the minimum for up to 500 changed lines, then in proportion, up to three times the minimum. Other scan types use the last such scan’s budget, or half again when that scan ran short of it, and a first scan starts at twice the minimum. Except for a diff, the recommendation never exceeds twice the minimum. A budget below the minimum is refused with `400` `budget_below_minimum`, whose `minimumCredits` names it.

  integer

  \>= 1

* **presetRef**

  A preset ref from /scan-presets. Defaults to the first active preset.

  string

* **branch**

  Branch to scan (resolved to its head commit server-side). Ignored if commitHash is set.

  string | null

* **commitHash**

  Pin a specific commit SHA (7-40 hex chars).

  string | null

* **commitMessage**

  string | null

* **baseCommit**

  What a diff scan’s change is measured from: a commit SHA, branch, or tag. Required by a diff scan preset and refused by every other. The scan records the merge base of this and the scanned commit. When no earlier scan of the repository built its overview, the diff scan builds one first, and its minimum and recommended budgets rise.

  string | null

* **backlogRecheck**

  Options for Recheck open findings. Omit to reassess eligible Not started findings on the selected branch. Fresh rechecks require the branch’s latest commit and reject a pinned commit or audit scope.

  object

  * **includeInProgress**

    Also include In progress findings. Defaults to false.

    boolean

  * **findingIds**

    Restrict the recheck to these findings. Eligibility is still checked against the selected repository and branch. Omit to include all eligible findings. Cannot be combined with resumeScanId.

    Array\<string>

    \>= 1 items <= 500 items

  * **resumeScanId**

    Continue a finished recheck’s unassessed findings on the same repository. Uses that scan’s branch, commit, and status selection.

    string

    \>= 1 characters

  not matching

  * **findingIds**

    required

  * **resumeScanId**

    required

* **trigger**

  One of:

  object

  Where a launch came from. References only: no URL is accepted, and the link the scan page shows is built from the scanned repository, so a token can never point that page somewhere of its own choosing.

  object

  * **kind**

    required

    What asked for the scan.

    string

    Allowed values: github_action pr_comment agent api

  * **pullRequest**

    Pull request number in the scanned repository. Its existence is not checked: a wrong number only yields a dead link in your own repository.

    integer | null

    \>= 1

  * **commentId**

    The comment that asked for the scan, so the link lands on it. Requires pullRequest.

    string | null

    /^\[0-9]{1,32}$/

  null

  null

* **auditAreaKeys**

  Area keys from /audit-areas to scope this scan to. Omit or send an empty array to scan the whole repository. A key the repository’s current map no longer names fails the launch rather than being dropped, so a scan budgeted for one subsystem never silently runs against everything.

  Array\<string>

* **auditScope**

  The code to audit, described in your own words, instead of `auditAreaKeys`. Send one or the other, not both.

  string | null

  <= 10000 characters

* **guidance**

  Guidance for this scan only, replacing the repository’s configured guidance layer (it is still layered over any committed zkao.md). Omit the field to inherit the repository’s guidance; send null to scan with no guidance layer.

  string | null

  <= 100000 characters

## Responses

### 202

Scan accepted (queued)

application/json

object

* **scanId**

  required

  string

* **queued**

  required

  boolean

* **creditBudget**

  required

  The budget the scan was launched with, in credits.

  integer

* **buildsOverview**

  required

  True when no earlier scan of the repository built its overview, so this diff scan builds one first. It takes longer, and its minimum and recommended budgets are higher.

  boolean

##### Examplegenerated

```json
{
  "scanId": "example",
  "queued": true,
  "creditBudget": 1,
  "buildsOverview": true
}
```

### 400

Invalid request

application/json

object

* **error**

  required

  object

  * **code**

    required

    string

    Allowed values: unauthorized forbidden not_found bad_request conflict insufficient_credits budget_below_minimum repository_initializing diff_base_required diff_base_not_allowed diff_base_invalid diff_empty rate_limited internal

  * **message**

    required

    string

  * **minimumCredits**

    Budget_below_minimum only: the least the launch could have reserved, in credits. A diff scan’s first scan of a repository also builds its overview, so its minimum is higher.

    integer

##### Example

```json
{
  "error": {
    "code": "unauthorized"
  }
}
```

### 401

Missing, malformed, expired, or revoked token

application/json

object

* **error**

  required

  object

  * **code**

    required

    string

    Allowed values: unauthorized forbidden not_found bad_request conflict insufficient_credits budget_below_minimum repository_initializing diff_base_required diff_base_not_allowed diff_base_invalid diff_empty rate_limited internal

  * **message**

    required

    string

  * **minimumCredits**

    Budget_below_minimum only: the least the launch could have reserved, in credits. A diff scan’s first scan of a repository also builds its overview, so its minimum is higher.

    integer

##### Example

```json
{
  "error": {
    "code": "unauthorized"
  }
}
```

### 402

The project does not have enough prepaid credits to cover the scan budget. Top up credits and retry. (code `insufficient_credits`)

application/json

object

* **error**

  required

  object

  * **code**

    required

    string

    Allowed values: unauthorized forbidden not_found bad_request conflict insufficient_credits budget_below_minimum repository_initializing diff_base_required diff_base_not_allowed diff_base_invalid diff_empty rate_limited internal

  * **message**

    required

    string

  * **minimumCredits**

    Budget_below_minimum only: the least the launch could have reserved, in credits. A diff scan’s first scan of a repository also builds its overview, so its minimum is higher.

    integer

##### Example

```json
{
  "error": {
    "code": "unauthorized"
  }
}
```

### 403

The token lacks the required scope

application/json

object

* **error**

  required

  object

  * **code**

    required

    string

    Allowed values: unauthorized forbidden not_found bad_request conflict insufficient_credits budget_below_minimum repository_initializing diff_base_required diff_base_not_allowed diff_base_invalid diff_empty rate_limited internal

  * **message**

    required

    string

  * **minimumCredits**

    Budget_below_minimum only: the least the launch could have reserved, in credits. A diff scan’s first scan of a repository also builds its overview, so its minimum is higher.

    integer

##### Example

```json
{
  "error": {
    "code": "unauthorized"
  }
}
```

### 404

Resource not in this token’s project or repo allowlist

application/json

object

* **error**

  required

  object

  * **code**

    required

    string

    Allowed values: unauthorized forbidden not_found bad_request conflict insufficient_credits budget_below_minimum repository_initializing diff_base_required diff_base_not_allowed diff_base_invalid diff_empty rate_limited internal

  * **message**

    required

    string

  * **minimumCredits**

    Budget_below_minimum only: the least the launch could have reserved, in credits. A diff scan’s first scan of a repository also builds its overview, so its minimum is higher.

    integer

##### Example

```json
{
  "error": {
    "code": "unauthorized"
  }
}
```

### 409

The repository is still being analyzed and cannot be scanned yet. The same request succeeds once `GET /repositories` reports its `readiness` as `ready`. (code `repository_initializing`)

application/json

object

* **error**

  required

  object

  * **code**

    required

    string

    Allowed values: unauthorized forbidden not_found bad_request conflict insufficient_credits budget_below_minimum repository_initializing diff_base_required diff_base_not_allowed diff_base_invalid diff_empty rate_limited internal

  * **message**

    required

    string

  * **minimumCredits**

    Budget_below_minimum only: the least the launch could have reserved, in credits. A diff scan’s first scan of a repository also builds its overview, so its minimum is higher.

    integer

##### Example

```json
{
  "error": {
    "code": "unauthorized"
  }
}
```

### 422

The diff scan has nothing to audit. Code `diff_empty`: the base and the scanned commit have no change between them.

application/json

object

* **error**

  required

  object

  * **code**

    required

    string

    Allowed values: unauthorized forbidden not_found bad_request conflict insufficient_credits budget_below_minimum repository_initializing diff_base_required diff_base_not_allowed diff_base_invalid diff_empty rate_limited internal

  * **message**

    required

    string

  * **minimumCredits**

    Budget_below_minimum only: the least the launch could have reserved, in credits. A diff scan’s first scan of a repository also builds its overview, so its minimum is higher.

    integer

##### Example

```json
{
  "error": {
    "code": "unauthorized"
  }
}
```

### 429

Rate limited. Either the token’s spend limit for the current period is reached (on launch), or the token is sending too many requests. Wait the number of seconds in the `Retry-After` header before retrying.

application/json

object

* **error**

  required

  object

  * **code**

    required

    string

    Allowed values: unauthorized forbidden not_found bad_request conflict insufficient_credits budget_below_minimum repository_initializing diff_base_required diff_base_not_allowed diff_base_invalid diff_empty rate_limited internal

  * **message**

    required

    string

  * **minimumCredits**

    Budget_below_minimum only: the least the launch could have reserved, in credits. A diff scan’s first scan of a repository also builds its overview, so its minimum is higher.

    integer

##### Example

```json
{
  "error": {
    "code": "unauthorized"
  }
}
```

#### Headers

* **Retry-After**

  integer

  Seconds to wait before retrying.
