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

Add a custom audit area

POST
/projects/{projectId}/repositories/{repositoryId}/audit-areas
curl --request POST \
  --url https://zkao.io/api/v1/projects/example/repositories/example/audit-areas \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "description": "example" }'

Requires scope: guidance:write. An area is a name and a description, never a file list: a scan resolves it against the code at the commit it runs on. The key is derived from the name and disambiguated on collision.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters”
projectId
required
string
repositoryId
required
string

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
name
required
string
<= 120 characters
description

What this part of the code does.

string | null
<= 500 characters
Examplegenerated
{
  "name": "example",
  "description": "example"
}

Responses

Section titled “ Responses ”

201

Section titled “201”

Created

Media typeapplication/json
object
area
required
object
key
required

Stable slug, unique per repository. Pass it in auditAreaKeys when launching a scan.

string
name
required
string
description
required
string | null
source
required

discovered was named by a scan’s map of the repository; custom was added through this API or the app.

string
Allowed values: discovered custom
inLatestMap
required

Whether the branch’s latest map still names this area.

boolean
files
required

Files this area covers at that map. Null when the map does not name it.

integer | null
lines
required

Lines this area covers at that map. Null when the map does not name it.

integer | null
Example
{
  "area": {
    "source": "discovered"
  }
}

400

Section titled “400”

Invalid request

Media typeapplication/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"
  }
}

401

Section titled “401”

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

Section titled “403”

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 repository_initializing diff_base_required diff_base_not_allowed diff_base_invalid diff_empty rate_limited internal
message
required
string
Example
{
  "error": {
    "code": "unauthorized"
  }
}

404

Section titled “404”

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 repository_initializing diff_base_required diff_base_not_allowed diff_base_invalid diff_empty rate_limited internal
message
required
string
Example
{
  "error": {
    "code": "unauthorized"
  }
}

409

Section titled “409”

A compare-and-set (expectedContent) missed: the guidance changed since it was read. Re-read the current guidance and retry.

Media typeapplication/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"
  }
}