Launch a scan
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);}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.
Authorizations
Section titled “Authorizations”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters”Request Bodyrequired
Section titled “Request Bodyrequired”object
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.
A preset ref from /scan-presets. Defaults to the first active preset.
Branch to scan (resolved to its head commit server-side). Ignored if commitHash is set.
Pin a specific commit SHA (7-40 hex chars).
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.
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
Also include In progress findings. Defaults to false.
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.
Continue a finished recheck’s unassessed findings on the same repository. Uses that scan’s branch, commit, and status selection.
not matching
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
What asked for the scan.
Pull request number in the scanned repository. Its existence is not checked: a wrong number only yields a dead link in your own repository.
The comment that asked for the scan, so the link lands on it. Requires pullRequest.
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.
The code to audit, described in your own words, instead of auditAreaKeys. Send one or the other, not both.
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.
Responses
Section titled “ Responses ”Scan accepted (queued)
object
The budget the scan was launched with, in credits.
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.
Examplegenerated
{ "scanId": "example", "queued": true, "creditBudget": 1, "buildsOverview": true}Invalid request
object
object
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.
Example
{ "error": { "code": "unauthorized" }}Missing, malformed, expired, or revoked token
object
object
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.
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)
object
object
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.
Example
{ "error": { "code": "unauthorized" }}The token lacks the required scope
object
object
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.
Example
{ "error": { "code": "unauthorized" }}Resource not in this token’s project or repo allowlist
object
object
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.
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)
object
object
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.
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.
object
object
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.
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.
object
object
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.
Example
{ "error": { "code": "unauthorized" }}Headers
Section titled “Headers”Seconds to wait before retrying.
