Skip to content

Generate a regression test and create its draft pull request

View .md
POST
/projects/{projectId}/findings/{findingId}/regression-tests
curl --request POST \
--url https://zkao.io/api/v1/projects/example/findings/example/regression-tests \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example' \
--data '{ "creditBudget": 1, "targetBranch": "example" }'

Requires scope: regression-tests:write. The finding must be confirmed. The token creator must remain an approved project admin with verified GitHub write access. The GitHub App must have Contents and Pull requests write permissions for this repository. The explicit credit budget is reserved and counts against project and token spending limits. Reuse the idempotency key with the same budget and target branch to retrieve the original attempt without another charge. The generated test uses a fixed counterexample and the repository’s existing test framework. A draft pull request is opened after validation.

projectId
required
string
findingId
required
string

The finding id, or the ZK- label shown on the finding page (the id’s last eight characters, prefix optional). A label that matches more than one finding in the project is refused with 409 conflict; use the full id.

Idempotency-Key
required
string
>= 1 characters <= 128 characters /^[!-~]+$/
Media typeapplication/json
object
creditBudget
required
integer
>= 1 <= 100000
targetBranch

Defaults to the repository’s default branch. Resolved to a commit at launch.

string
>= 1 characters <= 255 characters
Examplegenerated
{
"creditBudget": 1,
"targetBranch": "example"
}

The new or previously created attempt.

Media typeapplication/json
object
run
required
object
id
required
string
findingId
required
string
status
required
string
Allowed values: QUEUED RUNNING BLOCKED READY PUBLISHED PUBLICATION_FAILED FAILED CANCELLED
creditBudget
required
integer
>= 1
targetBranch
required
string
targetCommit
required
string
auditedCommit
required
string
summary
required
string | null
pullRequestUrl
required
string | null format: uri
audited
required
Any of:
object
commit
required
string
/^[a-f0-9]{40}$/
outcome
required
string
Allowed values: assertion_failed passed blocked not_run
command
required
string
summary
required
string
target
required
Any of:
object
commit
required
string
/^[a-f0-9]{40}$/
outcome
required
string
Allowed values: assertion_failed passed blocked not_run
command
required
string
summary
required
string
createdAt
required
string format: date-time
completedAt
required
string | null format: date-time
replayed
required
boolean
Example
{
"run": {
"status": "QUEUED",
"audited": {
"outcome": "assertion_failed"
},
"target": {
"outcome": "assertion_failed"
}
}
}

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

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