These docs describe staging.zkao.io and the @zksecurity/zkao-cli@next release. For production, see docs.zkao.io.

Get a single scan's status and detail

GET

/projects/{projectId}/scans/{scanId}

const url = 'https://zkao.io/api/v1/projects/example/scans/example';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

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

curl --request GET \
  --url https://zkao.io/api/v1/projects/example/scans/example \
  --header 'Authorization: Bearer <token>'

Requires scope: read. Use for polling a launched scan. While the scan is not yet terminal the response carries an advisory Retry-After header telling you how long to wait before polling again; respect it (and back off on 429) instead of polling in a tight loop.

Authorizations

bearerAuth

Parameters

Path Parameters

projectId

required

string

scanId

required

string

Responses

200

application/json

object

scan

required

object

required

string

status

required

string

Allowed values: QUEUED PROCESSING COMPLETED FAILED CANCELLED

repositoryId

required

string

commitHash

string | null

baseCommit

A diff scan’s base, as the merge base SHA its change is measured from. Null for other scans.

string | null

commitMessage

string | null

presetName

string | null

createdAt

required

string format: date-time

startedAt

string | null format: date-time

completedAt

string | null format: date-time

progress

One of:

object
null

How far a running scan has got through its phases. Deliberately not a time estimate: a phase’s duration moves with the guidance it was given, the repository, and the model that ran it.

object

phasesCompleted

required

Phases that reached a terminal state (completed, failed, or skipped).

integer

phasesTotal

required

Phases this scan will run, fixed when it was dispatched.

integer

percent

required

Weighted completion. Each phase counts for its share of the scan budget, so this does not simply equal phasesCompleted / phasesTotal.

integer

<= 100

branch

string | null

creditBudget

Reserved budget for the scan, in credits.

integer | null

findingsSummary

object

total

integer

bySeverity

object

key

additional properties

integer

Example

{
  "scan": {
    "status": "QUEUED"
  }
}

Headers

Retry-After

integer

Advisory seconds to wait before polling again. Present only while the scan is still running (not for terminal scans).

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 repository_initializing diff_base_required diff_base_not_allowed diff_base_invalid diff_empty rate_limited internal

message

required

string

Example

{
  "error": {
    "code": "unauthorized"
  }
}

403

The token lacks the required scope

application/json

object

error

required

object

code

required

string

message

required

string

Example

{
  "error": {
    "code": "unauthorized"
  }
}

404

Resource not in this token’s project or repo allowlist

application/json

object

error

required

object

code

required

string

message

required

string

Example

{
  "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

message

required

string

Example

{
  "error": {
    "code": "unauthorized"
  }
}

Headers

Retry-After

integer

Seconds to wait before retrying.