Skip to content

Launch a scan

View .md
POST
/projects/{projectId}/scans
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" }'

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.

projectId
required
string
Media typeapplication/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:

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}$/
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

Scan accepted (queued)

Media typeapplication/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
{
"scanId": "example",
"queued": true,
"creditBudget": 1,
"buildsOverview": true
}

Invalid request

Media typeapplication/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
{
"error": {
"code": "unauthorized"
}
}

Missing, malformed, expired, or revoked token

Media typeapplication/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
{
"error": {
"code": "unauthorized"
}
}

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

Media typeapplication/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
{
"error": {
"code": "unauthorized"
}
}

The token lacks the required scope

Media typeapplication/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
{
"error": {
"code": "unauthorized"
}
}

Resource not in this token’s project or repo allowlist

Media typeapplication/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
{
"error": {
"code": "unauthorized"
}
}

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)

Media typeapplication/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
{
"error": {
"code": "unauthorized"
}
}

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

Media typeapplication/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
{
"error": {
"code": "unauthorized"
}
}

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.

Media typeapplication/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
{
"error": {
"code": "unauthorized"
}
}
Retry-After
integer

Seconds to wait before retrying.