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

Record which versions an advisory affects

View .md
PUT
/projects/{projectId}/advisories/{publicId}/affected
curl --request PUT \
--url https://zkao.io/api/v1/projects/example/advisories/example/affected \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "affected": [ { "repository": { "owner": "example", "name": "example" }, "introducedIn": "example", "fixedIn": "example" } ] }'

Requires scope: advisories:write. Replaces the whole set of affected ranges, so send what is affected now rather than a patch. Every existing and requested repository must be in the token’s allowlist. This check also applies to an empty replacement.

fixedIn is the point of this endpoint. A patch notice stays blocked until some range names a fixed version, and only the people who shipped the release know it.

Versions only. A range may name only software already on the advisory’s software, and anything else is a 400. Which software an advisory concerns decides who hears about it, and that is its own statement, made in the app: a call about versions does not change it in either direction.

This call never sends anything. It records versions and recomputes the disclosure plan: a notice blocked for want of a fix becomes eligible to go, and one that loses its fix is blocked again, dropping any approval it was carrying so nobody approves wording a later fix rewrites. When an eligible notice is actually sent is governed by the programme’s own settings, not by this call.

projectId
required
string
publicId
required
string

The advisory’s readable identifier.

Media typeapplication/json
object
affected
required
Array<object>
object
repository
required
object
owner
required
string
name
required
string
introducedIn
required

First version carrying the defect.

string
fixedIn

Version that closes the range, or null.

string | null
Examplegenerated
{
"affected": [
{
"repository": {
"owner": "example",
"name": "example"
},
"introducedIn": "example",
"fixedIn": "example"
}
]
}

OK

Media typeapplication/json
object
advisory
required
object
publicId
required

Readable identifier, e.g. ADVISORY-ADV-2026-0045.

string
title
required
string
severity
required
string
Allowed values: CRITICAL HIGH MEDIUM LOW INFO
status
required
string
Allowed values: DRAFT SCHEDULED UNDER_EMBARGO PUBLISHED WITHDRAWN
disclosureAt

When the embargo lifts. Null until a date is set.

string | null format: date-time
publishedAt
string | null format: date-time
cveId
string | null
ghsaId

The GitHub advisory, once one has been filed.

string | null
ghsaUrl
string | null
ghsaState
required

What GitHub reports. A created entry is a DRAFT, which is private and reaches no scanner; only a published one is public.

string
createdAt
required
string format: date-time
summary
required
string
description
required
string
impact
required
string
cwe
string | null
software
required

The software the advisory is about. A contact hears about it only when they run some of it.

Array<object>
object
owner
required
string
name
required
string
affected
required
Array<object>
object
id
required
string
repository
required
object
owner
required
string
name
required
string
introducedIn
required

First version carrying the defect.

string
fixedIn
required

Version that closes the range. Null while no patch exists, which is what holds a patch notice back.

string | null
notices
required
Array<object>
object
label
required
string
offsetDays
required

Days relative to disclosure. Negative is before it, 0 is the day itself.

integer
scheduledFor
required
string format: date-time
status
required
string
Allowed values: DRAFT SCHEDULED BLOCKED SENDING SENT CANCELLED
blockedReason
required

Why the plan is holding this notice back, if it is.

string | null
sentAt
required
string | null format: date-time
recipientCount
required

Contacts written to, as recorded when it went.

integer
Example
{
"advisory": {
"severity": "CRITICAL",
"status": "DRAFT",
"notices": [
{
"status": "DRAFT"
}
]
}
}

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