Source: https://docs.zkao.io/api/ # Overview ## zkao Project API 1.0.0 Project-scoped REST API for programmatically controlling a single zkao project with a bearer **API token** (created under Project Settings → Integrations, or approved through the CLI’s `zkao login`). ## Authentication Send the token in the `Authorization` header: `Authorization: Bearer zkao_proj__`. The token is shown once at creation and never again. Passing the token in the query string is rejected. ## Scoping (what a token can do) Every token belongs to exactly one project and carries a subset of these **scopes**: * `read` — list/show repositories, scans, findings, presets * `findings:write` — comment, change severity, change resolution, pin a note * `guidance:write` — read and update a repository’s guidance, and manage its audit areas * `scans:launch` — start a scan * `regression-tests:write`: generate regression tests and create their pull requests * `publish` — publish a finding or a scan * `advisories:write` — record which versions an advisory affects * `contacts:read` — read the advisory contact list * `contacts:write` — add an advisory contact * `automations:write` controls Continuous Security schedules, analyses, and budgets * `reports:write` — submit a vulnerability report to the programme `GET /token` tells a token which project, and which organization, it belongs to. A token may also be restricted to a subset of the project’s repositories (a repo allowlist). Any resource outside the token’s project or repo allowlist responds `404` (never confirmed to exist). Launching a scan requires the project’s organization to have prepaid credits. ## Organizations Every project belongs to an **organization**, which holds the prepaid credit balance shared by all of its projects. Tokens stay project-scoped: the billing endpoints report the organization’s balance as seen from this project, and usage attributed to this project. Projects and repositories also carry a `slug`, the readable segment used in app URLs (`/orgs//projects//repos/`). ## Errors All errors share the envelope `{ "error": { "code": "...", "message": "..." } }`. Identity failures (bad/expired/revoked token) collapse to a generic `401`. ## Polling and rate limits When polling a scan, honor the advisory `Retry-After` header on the scan response rather than polling in a tight loop. A token that sends too many requests receives `429` with a `Retry-After` header; back off until then. The official SDK’s `waitForScan` does this for you. Information * OpenAPI version: `3.1.0` ## Operations GET [/token](https://docs.zkao.io/api/operations/gettokeninfo/) GET [/projects/{projectId}/repositories](https://docs.zkao.io/api/operations/listrepositories/) GET [/projects/{projectId}/repositories/{repositoryId}/guidance](https://docs.zkao.io/api/operations/getrepositoryguidance/) PUT [/projects/{projectId}/repositories/{repositoryId}/guidance](https://docs.zkao.io/api/operations/setrepositoryguidance/) GET [/projects/{projectId}/repositories/{repositoryId}/audit-areas](https://docs.zkao.io/api/operations/listauditareas/) POST [/projects/{projectId}/repositories/{repositoryId}/audit-areas](https://docs.zkao.io/api/operations/createauditarea/) DELETE [/projects/{projectId}/repositories/{repositoryId}/audit-areas/{areaKey}](https://docs.zkao.io/api/operations/deleteauditarea/) GET [/projects/{projectId}/repositories/{repositoryId}/continuous-testing](https://docs.zkao.io/api/operations/getcontinuoustesting/) PUT [/projects/{projectId}/repositories/{repositoryId}/continuous-testing](https://docs.zkao.io/api/operations/setcontinuoustesting/) DELETE [/projects/{projectId}/repositories/{repositoryId}/continuous-testing](https://docs.zkao.io/api/operations/removecontinuoustesting/) POST [/projects/{projectId}/repositories/{repositoryId}/continuous-testing/prepare](https://docs.zkao.io/api/operations/preparecontinuoustesting/) GET [/projects/{projectId}/scans](https://docs.zkao.io/api/operations/listscans/) POST [/projects/{projectId}/scans](https://docs.zkao.io/api/operations/launchscan/) GET [/projects/{projectId}/scans/{scanId}](https://docs.zkao.io/api/operations/getscan/) POST [/projects/{projectId}/scans/{scanId}/cancel](https://docs.zkao.io/api/operations/cancelscan/) POST [/projects/{projectId}/scans/{scanId}/triage/resume](https://docs.zkao.io/api/operations/resumetriage/) GET [/projects/{projectId}/scans/{scanId}/triage/runs/{runId}](https://docs.zkao.io/api/operations/gettriagerun/) GET [/projects/{projectId}/findings](https://docs.zkao.io/api/operations/listfindings/) GET [/projects/{projectId}/findings/details](https://docs.zkao.io/api/operations/listfindingdetails/) GET [/projects/{projectId}/findings/{findingId}](https://docs.zkao.io/api/operations/getfinding/) POST [/projects/{projectId}/findings/{findingId}/notes](https://docs.zkao.io/api/operations/addfindingnote/) GET [/projects/{projectId}/findings/{findingId}/regression-tests](https://docs.zkao.io/api/operations/listregressiontests/) POST [/projects/{projectId}/findings/{findingId}/regression-tests](https://docs.zkao.io/api/operations/createregressiontest/) GET [/projects/{projectId}/findings/{findingId}/regression-tests/readiness](https://docs.zkao.io/api/operations/getregressiontestreadiness/) GET [/projects/{projectId}/findings/{findingId}/regression-tests/{runId}](https://docs.zkao.io/api/operations/getregressiontest/) POST [/projects/{projectId}/findings/{findingId}/regression-tests/{runId}/retry-publication](https://docs.zkao.io/api/operations/retryregressiontestpublication/) POST [/projects/{projectId}/findings/{findingId}/notes/{noteId}/pin](https://docs.zkao.io/api/operations/pinfindingnote/) PATCH [/projects/{projectId}/findings/{findingId}/severity](https://docs.zkao.io/api/operations/updatefindingseverity/) PATCH [/projects/{projectId}/findings/{findingId}/resolution](https://docs.zkao.io/api/operations/updatefindingresolution/) PATCH [/projects/{projectId}/findings/{findingId}/triage](https://docs.zkao.io/api/operations/overridefindingtriage/) GET [/projects/{projectId}/agent-questions](https://docs.zkao.io/api/operations/listagentquestions/) POST [/projects/{projectId}/agent-questions/{questionId}/answer](https://docs.zkao.io/api/operations/answeragentquestion/) POST [/projects/{projectId}/findings/{findingId}/publish](https://docs.zkao.io/api/operations/publishfinding/) POST [/projects/{projectId}/scans/{scanId}/publish](https://docs.zkao.io/api/operations/publishscan/) GET [/projects/{projectId}/scan-presets](https://docs.zkao.io/api/operations/listscanpresets/) GET [/projects/{projectId}/billing/balance](https://docs.zkao.io/api/operations/getbillingbalance/) GET [/projects/{projectId}/billing/usage](https://docs.zkao.io/api/operations/getbillingusage/) GET [/projects/{projectId}/billing/summary](https://docs.zkao.io/api/operations/getbillingsummary/) POST [/projects/{projectId}/repositories/{repositoryId}/reports](https://docs.zkao.io/api/operations/submitreport/) GET [/projects/{projectId}/reports](https://docs.zkao.io/api/operations/listreports/) POST [/projects/{projectId}/reports/{publicId}/investigate](https://docs.zkao.io/api/operations/investigatereport/) GET [/projects/{projectId}/advisories](https://docs.zkao.io/api/operations/listadvisories/) GET [/projects/{projectId}/advisories/{publicId}](https://docs.zkao.io/api/operations/getadvisory/) PUT [/projects/{projectId}/advisories/{publicId}/affected](https://docs.zkao.io/api/operations/replaceadvisoryaffected/) GET [/projects/{projectId}/advisory-contacts](https://docs.zkao.io/api/operations/listadvisorycontacts/) POST [/projects/{projectId}/advisory-contacts](https://docs.zkao.io/api/operations/addadvisorycontact/) ## Authentication ### bearerAuth Project API token: `zkao_proj__`. **Security scheme type: **http --- Source: https://docs.zkao.io/api/operations/addadvisorycontact/ # Add an advisory contact POST /projects/{projectId}/advisory-contacts ```js const url = 'https://zkao.io/api/v1/projects/example/advisory-contacts'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"email":"example","organization":"example","tier":"EMBARGO","software":[{"owner":"example","name":"example"}],"name":"example","title":"example","notes":"example","tags":["example"]}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request POST \ --url https://zkao.io/api/v1/projects/example/advisory-contacts \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "email": "example", "organization": "example", "tier": "EMBARGO", "software": [ { "owner": "example", "name": "example" } ], "name": "example", "title": "example", "notes": "example", "tags": [ "example" ] }' ``` * Production`zkao.io/api/v1/projects/{projectId}/advisory-contacts` * Staging`staging.zkao.io/api/v1/projects/{projectId}/advisory-contacts` Requires scope: `contacts:write`. Puts one address on the programme’s contact list. `software` says which of the project’s repositories this contact runs, and is required. It is what every notice is matched on: a contact who runs nothing is told nothing. The contact starts `PENDING_VERIFICATION`, and an unconfirmed address receives nothing embargoed. The confirmation mail is sent from the app, not by this call, so nothing is emailed to the address you send here. There is no endpoint that reads the contact list back. It is other people’s work addresses and the record of who hears about a vulnerability early. ## Authorizations * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **projectId** required string ## Request Bodyrequired application/json object * **email** required string * **organization** required The organisation this contact speaks for. string * **tier** required How early this contact is told. `EMBARGO` hears first and alone, `DOWNSTREAM` joins once a patch exists, `ANNOUNCE` learns at public disclosure. string Allowed values: EMBARGO DOWNSTREAM ANNOUNCE * **software** required The repositories this contact runs. At least one. Array\ \>= 1 items object * **owner** required string * **name** required string * **name** string | null * **title** string | null * **notes** string | null * **tags** Array\ ## Responses ### 201 Created application/json object * **contact** required object * **id** required string * **email** required string * **organization** required string * **tier** required string * **status** required `PENDING_VERIFICATION` until the contact confirms the address. An unconfirmed address receives nothing embargoed. string * **software** required The software this contact runs, which notices are matched on. Array\ object * **owner** required string * **name** required string * **createdAt** required string format: date-time ##### Examplegenerated ```json { "contact": { "id": "example", "email": "example", "organization": "example", "tier": "example", "status": "example", "software": [ { "owner": "example", "name": "example" } ], "createdAt": "2026-04-15T12:00:00Z" } } ``` ### 400 Invalid request application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 Resource not in this token’s project or repo allowlist application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 409 That address is already on the programme’s contact list. application/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 ```json { "error": { "code": "unauthorized" } } ``` --- Source: https://docs.zkao.io/api/operations/addfindingnote/ # Add a comment (note) to a finding POST /projects/{projectId}/findings/{findingId}/notes ```js const url = 'https://zkao.io/api/v1/projects/example/findings/example/notes'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"content":"example"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request POST \ --url https://zkao.io/api/v1/projects/example/findings/example/notes \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "content": "example" }' ``` * Production`zkao.io/api/v1/projects/{projectId}/findings/{findingId}/notes` * Staging`staging.zkao.io/api/v1/projects/{projectId}/findings/{findingId}/notes` Requires scope: `findings:write`. ## Authorizations * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **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. ## Request Bodyrequired application/json object * **content** required The comment body (markdown). string \>= 1 characters ##### Examplegenerated ```json { "content": "example" } ``` ## Responses ### 201 Note created application/json object * **noteId** required string * **findingId** required string ##### Examplegenerated ```json { "noteId": "example", "findingId": "example" } ``` ### 400 Invalid request application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 Resource not in this token’s project or repo allowlist application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 409 A compare-and-set (`expectedContent`) missed: the guidance changed since it was read. Re-read the current guidance and retry. application/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 ```json { "error": { "code": "unauthorized" } } ``` --- Source: https://docs.zkao.io/api/operations/answeragentquestion/ # Answer a Continuous Security analysis's question POST /projects/{projectId}/agent-questions/{questionId}/answer ```js const url = 'https://zkao.io/api/v1/projects/example/agent-questions/example/answer'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"selectedOption":"example","note":"example"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request POST \ --url https://zkao.io/api/v1/projects/example/agent-questions/example/answer \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "selectedOption": "example", "note": "example" }' ``` * Production`zkao.io/api/v1/projects/{projectId}/agent-questions/{questionId}/answer` * Staging`staging.zkao.io/api/v1/projects/{projectId}/agent-questions/{questionId}/answer` Requires scope: `guidance:write`. Answers with one of the question’s options, a note, or both. The answer reaches the analysis’s next session. It is recorded as the answer of the member who created the token, who needs a project role of their own. Responds `409` when the question was already answered or dismissed. ## Authorizations * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **projectId** required string * **questionId** required string ## Request Bodyrequired application/json object * **selectedOption** The label of one of the question’s options. string | null * **note** string | null ##### Examplegenerated ```json { "selectedOption": "example", "note": "example" } ``` ## Responses ### 200 OK application/json object * **questionId** required string * **status** required string Allowed values: ANSWERED ##### Example ```json { "status": "ANSWERED" } ``` ### 400 Invalid request application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 Resource not in this token’s project or repo allowlist application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 409 A compare-and-set (`expectedContent`) missed: the guidance changed since it was read. Re-read the current guidance and retry. application/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 ```json { "error": { "code": "unauthorized" } } ``` --- Source: https://docs.zkao.io/api/operations/cancelscan/ # Cancel a running or queued scan POST /projects/{projectId}/scans/{scanId}/cancel ```js const url = 'https://zkao.io/api/v1/projects/example/scans/example/cancel'; const options = {method: 'POST', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request POST \ --url https://zkao.io/api/v1/projects/example/scans/example/cancel \ --header 'Authorization: Bearer ' ``` * Production`zkao.io/api/v1/projects/{projectId}/scans/{scanId}/cancel` * Staging`staging.zkao.io/api/v1/projects/{projectId}/scans/{scanId}/cancel` Requires scope: `scans:launch`. Signals any in-flight jobs to stop, marks the scan CANCELLED, and releases its reserved credits (in-flight jobs settle their actual spend as they wind down). A scan that already reached COMPLETED or FAILED cannot be cancelled (`400`). Cancellation remains available when the organization has no available credits. ## Authorizations * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **projectId** required string * **scanId** required string ## Responses ### 200 OK application/json object * **scanId** required string * **status** required Terminal status after cancellation (always CANCELLED). string Allowed values: QUEUED PROCESSING COMPLETED FAILED CANCELLED * **cancelledJobs** required Number of in-flight jobs signalled to stop. integer ##### Example ```json { "status": "QUEUED" } ``` ### 400 Invalid request application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 Resource not in this token’s project or repo allowlist application/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 ```json { "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 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 ```json { "error": { "code": "unauthorized" } } ``` #### Headers * **Retry-After** integer Seconds to wait before retrying. --- Source: https://docs.zkao.io/api/operations/createauditarea/ # Add a custom audit area POST /projects/{projectId}/repositories/{repositoryId}/audit-areas ```js const url = 'https://zkao.io/api/v1/projects/example/repositories/example/audit-areas'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"name":"example","description":"example"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request POST \ --url https://zkao.io/api/v1/projects/example/repositories/example/audit-areas \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "name": "example", "description": "example" }' ``` * Production`zkao.io/api/v1/projects/{projectId}/repositories/{repositoryId}/audit-areas` * Staging`staging.zkao.io/api/v1/projects/{projectId}/repositories/{repositoryId}/audit-areas` 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 * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **projectId** required string * **repositoryId** required string ## Request Bodyrequired application/json object * **name** required string <= 120 characters * **description** What this part of the code does. string | null <= 500 characters ##### Examplegenerated ```json { "name": "example", "description": "example" } ``` ## Responses ### 201 Created application/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 ```json { "area": { "source": "discovered" } } ``` ### 400 Invalid request application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 Resource not in this token’s project or repo allowlist application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 409 A compare-and-set (`expectedContent`) missed: the guidance changed since it was read. Re-read the current guidance and retry. application/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 ```json { "error": { "code": "unauthorized" } } ``` --- Source: https://docs.zkao.io/api/operations/createregressiontest/ # Generate a regression test and create its draft pull request POST /projects/{projectId}/findings/{findingId}/regression-tests ```js const url = 'https://zkao.io/api/v1/projects/example/findings/example/regression-tests'; const options = { method: 'POST', headers: { 'Idempotency-Key': 'example', Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: '{"creditBudget":1,"targetBranch":"example"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request POST \ --url https://zkao.io/api/v1/projects/example/findings/example/regression-tests \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: example' \ --data '{ "creditBudget": 1, "targetBranch": "example" }' ``` * Production`zkao.io/api/v1/projects/{projectId}/findings/{findingId}/regression-tests` * Staging`staging.zkao.io/api/v1/projects/{projectId}/findings/{findingId}/regression-tests` 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. ## Authorizations * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **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. ### Header Parameters * **Idempotency-Key** required string \>= 1 characters <= 128 characters /^\[!-\~]+$/ ## Request Bodyrequired application/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 ```json { "creditBudget": 1, "targetBranch": "example" } ``` ## Responses ### 202 The new or previously created attempt. application/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 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 null null * **target** required Any of: object 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 null null * **createdAt** required string format: date-time * **completedAt** required string | null format: date-time * **replayed** required boolean ##### Example ```json { "run": { "status": "QUEUED", "audited": { "outcome": "assertion_failed" }, "target": { "outcome": "assertion_failed" } } } ``` ### 400 Invalid request application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 402 The project does not have enough prepaid credits to cover the scan budget. Top up credits and retry. (code `insufficient_credits`) application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 Resource not in this token’s project or repo allowlist application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 409 A compare-and-set (`expectedContent`) missed: the guidance changed since it was read. Re-read the current guidance and retry. application/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 ```json { "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 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 ```json { "error": { "code": "unauthorized" } } ``` #### Headers * **Retry-After** integer Seconds to wait before retrying. --- Source: https://docs.zkao.io/api/operations/deleteauditarea/ # Delete a custom audit area DELETE /projects/{projectId}/repositories/{repositoryId}/audit-areas/{areaKey} ```js const url = 'https://zkao.io/api/v1/projects/example/repositories/example/audit-areas/example'; const options = {method: 'DELETE', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request DELETE \ --url https://zkao.io/api/v1/projects/example/repositories/example/audit-areas/example \ --header 'Authorization: Bearer ' ``` * Production`zkao.io/api/v1/projects/{projectId}/repositories/{repositoryId}/audit-areas/{areaKey}` * Staging`staging.zkao.io/api/v1/projects/{projectId}/repositories/{repositoryId}/audit-areas/{areaKey}` Requires scope: `guidance:write`. Only an area with `source: custom` can be deleted; a discovered one is the map’s own account of the repository and is refused with `409`. Scans that already ran keep the scope they ran with. ## Authorizations * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **projectId** required string * **repositoryId** required string * **areaKey** required string ## Responses ### 200 OK application/json object * **repositoryId** required string * **key** required string * **deleted** required boolean ##### Examplegenerated ```json { "repositoryId": "example", "key": "example", "deleted": true } ``` ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 Resource not in this token’s project or repo allowlist application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 409 A compare-and-set (`expectedContent`) missed: the guidance changed since it was read. Re-read the current guidance and retry. application/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 ```json { "error": { "code": "unauthorized" } } ``` --- Source: https://docs.zkao.io/api/operations/getadvisory/ # Get an advisory GET /projects/{projectId}/advisories/{publicId} ```js const url = 'https://zkao.io/api/v1/projects/example/advisories/example'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request GET \ --url https://zkao.io/api/v1/projects/example/advisories/example \ --header 'Authorization: Bearer ' ``` * Production`zkao.io/api/v1/projects/{projectId}/advisories/{publicId}` * Staging`staging.zkao.io/api/v1/projects/{projectId}/advisories/{publicId}` Requires scope: `read`. The advisory, the software it concerns, the versions it affects, and the notices planned for it. Every associated repository must be in the token’s allowlist. `software` is what decides the audience: a contact is notified about an advisory only when they run some of it. `affected` is a separate statement about versions, and is often empty. A notice the plan is holding back carries `blockedReason`. The commonest one is that no affected range names a fixed version, which only the people who shipped the release can supply; record it in the app and the notice becomes schedulable. ## Authorizations * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **projectId** required string * **publicId** required string The advisory’s readable identifier. ## Responses ### 200 OK application/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 * **owner** required string * **name** required string * **affected** required Array\ 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 * **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 ```json { "advisory": { "severity": "CRITICAL", "status": "DRAFT", "notices": [ { "status": "DRAFT" } ] } } ``` ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 Resource not in this token’s project or repo allowlist application/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 ```json { "error": { "code": "unauthorized" } } ``` --- Source: https://docs.zkao.io/api/operations/getbillingbalance/ # Credits available to this project GET /projects/{projectId}/billing/balance ```js const url = 'https://zkao.io/api/v1/projects/example/billing/balance'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request GET \ --url https://zkao.io/api/v1/projects/example/billing/balance \ --header 'Authorization: Bearer ' ``` * Production`zkao.io/api/v1/projects/{projectId}/billing/balance` * Staging`staging.zkao.io/api/v1/projects/{projectId}/billing/balance` Requires scope: `read`. The organization’s shared prepaid balance, available to this project and to the organization’s other projects. All amounts are in credits. ## Authorizations * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **projectId** required string ## Responses ### 200 OK application/json object * **organization** required The organization whose shared balance this is. object * **id** required string * **slug** required URL segment of the organization (`/orgs/`), unique across zkao. string * **name** required string * **balanceCredits** required The organization’s total prepaid credit balance, shared by all of its projects. integer * **availableCredits** required Balance minus credits reserved by the organization’s in-flight scans. integer * **reservedCredits** required Credits held by the organization’s queued/running scans. integer ##### Examplegenerated ```json { "organization": { "id": "example", "slug": "example", "name": "example" }, "balanceCredits": 1, "availableCredits": 1, "reservedCredits": 1 } ``` ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 Resource not in this token’s project or repo allowlist application/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 ```json { "error": { "code": "unauthorized" } } ``` --- Source: https://docs.zkao.io/api/operations/getbillingsummary/ # Monthly spend and purchase summary for this project GET /projects/{projectId}/billing/summary ```js const url = 'https://zkao.io/api/v1/projects/example/billing/summary'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request GET \ --url https://zkao.io/api/v1/projects/example/billing/summary \ --header 'Authorization: Bearer ' ``` * Production`zkao.io/api/v1/projects/{projectId}/billing/summary` * Staging`staging.zkao.io/api/v1/projects/{projectId}/billing/summary` Requires scope: `read`. Per-month net scan spend and net purchases attributed to this project, in credits, newest first. Purchases land in the organization’s shared balance. ## Authorizations * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **projectId** required string ### Query Parameters * **months** integer \>= 1 <= 24 ## Responses ### 200 OK application/json object * **organization** required The organization whose shared balance the purchases were made into. object * **id** required string * **slug** required URL segment of the organization (`/orgs/`), unique across zkao. string * **name** required string * **months** required Array\ object * **month** required YYYY-MM (UTC). string * **spentCredits** required Net scan spend (deductions less refunds), in credits. integer * **purchasedCredits** required Net purchases (purchases less clawbacks), in credits. integer ##### Examplegenerated ```json { "organization": { "id": "example", "slug": "example", "name": "example" }, "months": [ { "month": "example", "spentCredits": 1, "purchasedCredits": 1 } ] } ``` ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 Resource not in this token’s project or repo allowlist application/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 ```json { "error": { "code": "unauthorized" } } ``` --- Source: https://docs.zkao.io/api/operations/getbillingusage/ # Credit usage events attributed to this project GET /projects/{projectId}/billing/usage ```js const url = 'https://zkao.io/api/v1/projects/example/billing/usage'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request GET \ --url https://zkao.io/api/v1/projects/example/billing/usage \ --header 'Authorization: Bearer ' ``` * Production`zkao.io/api/v1/projects/{projectId}/billing/usage` * Staging`staging.zkao.io/api/v1/projects/{projectId}/billing/usage` Requires scope: `read`. Signed credit delta per ledger event attributed to this project; organization-wide movements such as a top-up made outside any project are not included. Defaults to the last 30 days; newest first; max 1000 rows. ## Authorizations * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **projectId** required string ### Query Parameters * **from** string format: date-time * **to** string format: date-time * **limit** integer \>= 1 <= 1000 ## Responses ### 200 OK application/json object * **from** required string format: date-time * **to** required string format: date-time * **events** required Array\ object * **id** required string * **at** required string format: date-time * **type** required string Allowed values: SCAN_DEDUCTION SCAN_REFUND PURCHASE STRIPE_REFUND ADMIN_ADJUSTMENT * **credits** required Signed credit delta: negative = spent/clawed back, positive = added/refunded. integer * **scanId** required string | null * **description** required string ##### Example ```json { "events": [ { "type": "SCAN_DEDUCTION" } ] } ``` ### 400 Invalid request application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 Resource not in this token’s project or repo allowlist application/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 ```json { "error": { "code": "unauthorized" } } ``` --- Source: https://docs.zkao.io/api/operations/getcontinuoustesting/ # Get a repository's Continuous Security schedule GET /projects/{projectId}/repositories/{repositoryId}/continuous-testing ```js const url = 'https://zkao.io/api/v1/projects/example/repositories/example/continuous-testing'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request GET \ --url https://zkao.io/api/v1/projects/example/repositories/example/continuous-testing \ --header 'Authorization: Bearer ' ``` * Production`zkao.io/api/v1/projects/{projectId}/repositories/{repositoryId}/continuous-testing` * Staging`staging.zkao.io/api/v1/projects/{projectId}/repositories/{repositoryId}/continuous-testing` Requires scope: `read`. Continuous Security scans one branch on a schedule paid from a monthly budget. With no schedule on the branch, `enabled` is false and the schedule fields are null. The recommended monthly budget supports ongoing analysis. The minimum funds one useful analysis step. `availableFeatures` lists the analyses this branch offers. `enabledFeatures` lists the branch’s selected analyses, including while paused. ## Authorizations * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **projectId** required string * **repositoryId** required string ### Query Parameters * **branch** string The scheduled branch. Defaults to the repository’s default branch. ## Responses ### 200 OK application/json object * **repositoryId** required string * **available** required False when Continuous Security is not offered. boolean * **enabled** required False when there is no schedule or it is paused. boolean * **state** required Why an enabled schedule is not running: `budget_reached` when the schedule’s or project’s monthly automation cap is reached, `needs_credits` when the organization’s credits cannot fund the next run (it resumes on its own once they can), `error` after repeated failures. Null with no schedule. string | null Allowed values: active converged budget_reached needs_credits error * **branch** required string * **monthlyBudgetCredits** required The configured monthly spending cap. Legacy schedules derive the budget from their cadence and per-run budget. integer | null * **cadence** required Legacy fixed cadence. Null for a custom interval or no schedule. Use intervalHours for the actual interval. string | null Allowed values: daily weekly biweekly monthly * **intervalHours** required Hours between scheduled runs. Null when no schedule exists. integer | null \>= 1 * **perRunBudgetCredits** required integer | null * **areaKeys** required Audit areas the runs rotate through, one per run, least recently scanned first. Empty means every run scans the whole repository. Array\ * **availableFeatures** required Analyses offered on this branch. Empty when Continuous Security is unavailable. Array\ unique items Allowed values: bug-hunting formal-verification dependency-analysis weak-key-analysis security-invariants * **enabledFeatures** required Selected analyses. A branch with no saved selection defaults to bug hunting when Continuous Security is available. A paused schedule keeps its selection. Array\ unique items Allowed values: bug-hunting formal-verification dependency-analysis weak-key-analysis security-invariants * **spentThisMonthCredits** required Credits the branch was charged for Continuous Security since the UTC month began, net of refunds. Counts its analysis steps, change assessments, public-key reviews, agent questions and the planning included in steps. integer * **runsThisMonth** required Runs the schedule launched since the UTC month began. integer * **lastRunAt** required string | null format: date-time * **nextRunAt** required When the next run becomes due. A past time means within the hour. Null when paused or stopped. string | null format: date-time * **defaultMonthlyCredits** required The monthly budget a new schedule gets when the request names none. It funds at least one analysis step. integer | null * **recommendedMonthlyCredits** required A monthly budget that funds about four analysis steps, within the minimum and maximum. A suggestion to pass as `monthlyBudgetCredits`. It is never applied when the request names no budget. integer | null * **minimumMonthlyCredits** required The smallest month that funds one analysis step. Less is refused. integer | null * **maximumMonthlyCredits** required The largest monthly budget currently allowed for the repository. Administrators can raise it. integer | null ##### Example ```json { "state": "active", "cadence": "daily", "availableFeatures": [ "bug-hunting" ], "enabledFeatures": [ "bug-hunting" ] } ``` ### 400 Invalid request application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 Resource not in this token’s project or repo allowlist application/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 ```json { "error": { "code": "unauthorized" } } ``` --- Source: https://docs.zkao.io/api/operations/getfinding/ # Get a single finding (full detail) GET /projects/{projectId}/findings/{findingId} ```js const url = 'https://zkao.io/api/v1/projects/example/findings/example'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request GET \ --url https://zkao.io/api/v1/projects/example/findings/example \ --header 'Authorization: Bearer ' ``` * Production`zkao.io/api/v1/projects/{projectId}/findings/{findingId}` * Staging`staging.zkao.io/api/v1/projects/{projectId}/findings/{findingId}` Requires scope: `read`. Includes description, PoC, recommended fix, and notes. ## Authorizations * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **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. ## Responses ### 200 OK application/json object * **finding** required object * **id** required string * **displayId** required integer * **title** required string * **location** required string * **severity** required Effective severity (user override if set, else AI severity). string Allowed values: CRITICAL HIGH MEDIUM LOW INFO * **category** required string * **triageStatus** required string Allowed values: PENDING NEW DUPLICATE RECURRING CONFIRMED FALSE_POSITIVE INCONCLUSIVE * **confirmationEvidence** What backs a CONFIRMED verdict. POC means a proof of concept ran and demonstrated the issue. ANALYSIS means it was confirmed by code analysis alone. Null for other statuses or when not recorded. string | null Allowed values: POC ANALYSIS * **resolutionStatus** required string Allowed values: NOT_STARTED IN_PROGRESS RESOLVED WONT_FIX MITIGATED FALSE_POSITIVE DUPLICATE * **notesCount** required integer * **source** required Where the finding was found. object * **kind** required The kind of scan that found it. One of continuous-security, pr-review, flash, max, flash-diff, max-diff, supply-chain, flash-retriage, max-retriage, flash-regression-check, max-regression-check, manual-audit, report-investigation or other. New kinds may be added, so treat an unknown kind like other. string * **branch** required The branch the scan ran on. Null when the scan recorded none, such as a scan of a pinned commit. string | null * **dismissalReason** required Why triage dismissed the finding as a false positive. Null when triage did not dismiss it or gave no reason. string | null * **triageOverriddenFrom** required One of: string string Allowed values: PENDING NEW DUPLICATE RECURRING CONFIRMED FALSE_POSITIVE INCONCLUSIVE null null * **triageOverriddenAt** required string | null format: date-time * **triageOverriddenByName** required Name, or email when there is no name, of the member who overrode triage. string | null * **description** required string * **impact** required string * **recommendation** required string * **assumptions** required Array\ * **pocReport** string | null * **recommendedFix** string | null * **scanId** required string * **commitHash** string | null * **repo** object * **owner** string * **name** string * **url** string * **createdAt** required string format: date-time * **notes** required Array\ object * **id** required string * **body** required Markdown. A page of the app the assistant names is an absolute link. string * **createdAt** required string format: date-time * **author** object * **id** string * **name** string | null * **email** string ##### Example ```json { "finding": { "severity": "CRITICAL", "triageStatus": "PENDING", "confirmationEvidence": "POC", "resolutionStatus": "NOT_STARTED", "triageOverriddenFrom": "PENDING" } } ``` ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 Resource not in this token’s project or repo allowlist application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 409 A compare-and-set (`expectedContent`) missed: the guidance changed since it was read. Re-read the current guidance and retry. application/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 ```json { "error": { "code": "unauthorized" } } ``` --- Source: https://docs.zkao.io/api/operations/getregressiontest/ # Get a regression test attempt GET /projects/{projectId}/findings/{findingId}/regression-tests/{runId} ```js const url = 'https://zkao.io/api/v1/projects/example/findings/example/regression-tests/example'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request GET \ --url https://zkao.io/api/v1/projects/example/findings/example/regression-tests/example \ --header 'Authorization: Bearer ' ``` * Production`zkao.io/api/v1/projects/{projectId}/findings/{findingId}/regression-tests/{runId}` * Staging`staging.zkao.io/api/v1/projects/{projectId}/findings/{findingId}/regression-tests/{runId}` Requires scope: `read`. Poll this run independently of the original scan. ## Authorizations * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **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. * **runId** required string ## Responses ### 200 OK application/json 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 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 null null * **target** required Any of: object 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 null null * **createdAt** required string format: date-time * **completedAt** required string | null format: date-time ##### Example ```json { "status": "QUEUED", "audited": { "outcome": "assertion_failed" }, "target": { "outcome": "assertion_failed" } } ``` ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 Resource not in this token’s project or repo allowlist application/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 ```json { "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 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 ```json { "error": { "code": "unauthorized" } } ``` #### Headers * **Retry-After** integer Seconds to wait before retrying. --- Source: https://docs.zkao.io/api/operations/getregressiontestreadiness/ # Check GitHub readiness for a regression test pull request GET /projects/{projectId}/findings/{findingId}/regression-tests/readiness ```js const url = 'https://zkao.io/api/v1/projects/example/findings/example/regression-tests/readiness'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request GET \ --url https://zkao.io/api/v1/projects/example/findings/example/regression-tests/readiness \ --header 'Authorization: Bearer ' ``` * Production`zkao.io/api/v1/projects/{projectId}/findings/{findingId}/regression-tests/readiness` * Staging`staging.zkao.io/api/v1/projects/{projectId}/findings/{findingId}/regression-tests/readiness` Requires scope: `read`. Reports missing installation, repository access, pending write permissions, or requester authorization. Installation settings links let repository owners enable the feature. ## Authorizations * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **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. ## Responses ### 200 OK application/json object * **status** required string Allowed values: ready missing unselected pending forbidden unavailable * **settingsUrl** required string | null format: uri * **message** required string * **defaultBranch** required string ##### Example ```json { "status": "ready" } ``` ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 Resource not in this token’s project or repo allowlist application/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 ```json { "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 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 ```json { "error": { "code": "unauthorized" } } ``` #### Headers * **Retry-After** integer Seconds to wait before retrying. --- Source: https://docs.zkao.io/api/operations/getrepositoryguidance/ # Get a repository's guidance GET /projects/{projectId}/repositories/{repositoryId}/guidance ```js const url = 'https://zkao.io/api/v1/projects/example/repositories/example/guidance'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request GET \ --url https://zkao.io/api/v1/projects/example/repositories/example/guidance \ --header 'Authorization: Bearer ' ``` * Production`zkao.io/api/v1/projects/{projectId}/repositories/{repositoryId}/guidance` * Staging`staging.zkao.io/api/v1/projects/{projectId}/repositories/{repositoryId}/guidance` Requires scope: `read`. Returns the per-repo guidance configured for this repository. Guidance is layered on top of any `zkao.md` committed in the repo at scan time; a per-scan `guidance` on launch replaces this layer for that one scan only. ## Authorizations * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **projectId** required string * **repositoryId** required string ## Responses ### 200 OK application/json object * **repositoryId** required string * **content** required The configured guidance, or null when none is set. string | null * **updatedAt** required When the guidance last changed. Null when the repo has no revision history (guidance never set, or set before revisions were tracked). string | null format: date-time ##### Examplegenerated ```json { "repositoryId": "example", "content": "example", "updatedAt": "2026-04-15T12:00:00Z" } ``` ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 Resource not in this token’s project or repo allowlist application/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 ```json { "error": { "code": "unauthorized" } } ``` --- Source: https://docs.zkao.io/api/operations/getscan/ # Get a single scan's status and detail GET /projects/{projectId}/scans/{scanId} ```js const url = 'https://zkao.io/api/v1/projects/example/scans/example'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request GET \ --url https://zkao.io/api/v1/projects/example/scans/example \ --header 'Authorization: Bearer ' ``` * Production`zkao.io/api/v1/projects/{projectId}/scans/{scanId}` * Staging`staging.zkao.io/api/v1/projects/{projectId}/scans/{scanId}` 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](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **projectId** required string * **scanId** required string ## Responses ### 200 OK application/json object * **scan** required object * **id** required string * **status** required string Allowed values: QUEUED PROCESSING COMPLETED FAILED CANCELLED * **failureCode** An actionable setup failure for a failed scan. Null for other statuses and internal failures. Restore a project member’s GitHub access or approve the App permissions before launching again. string | null Allowed values: NO_MEMBER_REPO_ACCESS GITHUB_APP_PERMISSIONS_PENDING * **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 * **effort** The scan’s budget measured against the levels sized for its scope at launch. `high` starts at the recommended baseline, `extra-high` at the next level, and `deep` at the highest level. The server accounts for the scan limit and any fixed setup cost when sizing these levels. `medium` records a custom budget below High or a historical scan at that level. Null for a Flash scan and for a scan with no recorded effort. string | null Allowed values: medium high extra-high deep * **createdAt** required string format: date-time * **startedAt** string | null format: date-time * **completedAt** string | null format: date-time * **progress** One of: object 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 null null * **budget** One of: object What a scan was allowed to spend, what it was charged, and whether the next scan of its type and scope should get more. Check the last scan of a type before choosing the next one’s budget. object * **limitCredits** required The most the scan could spend, in credits. integer * **spentCredits** required Credits charged for the scan. Null until it finishes. integer | null * **nextBudgetRecommendation** required Whether the next scan of this type and scope should keep this budget or raise it. A raise is half again, never above twice the scan type’s minimum. A raise can follow a scan that spent well under its limit: the limit is divided between the parts of the analysis, and one part cannot use another’s unspent share. Null until the scan completes. string | null Allowed values: keep raise null null * **triage** required Completeness of triage, independent of whether the scan succeeded. object * **status** required string Allowed values: pending running complete budget_exhausted blocked * **untriagedCount** required integer * **activeRunId** required string | null * **resume** required Any of: object object * **minCredits** required integer * **recommendedCredits** required integer * **maxCredits** required integer null null * **branch** string | null * **creditBudget** Reserved budget for the scan, in credits. integer | null * **findingsSummary** object * **total** integer * **bySeverity** object * **_key_** additional properties integer ##### Example ```json { "scan": { "status": "QUEUED", "failureCode": "NO_MEMBER_REPO_ACCESS", "effort": "medium", "budget": { "nextBudgetRecommendation": "keep" }, "triage": { "status": "pending" } } } ``` #### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 Resource not in this token’s project or repo allowlist application/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 ```json { "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 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 ```json { "error": { "code": "unauthorized" } } ``` #### Headers * **Retry-After** integer Seconds to wait before retrying. --- Source: https://docs.zkao.io/api/operations/gettokeninfo/ # The calling token and its project GET /token ```js const url = 'https://zkao.io/api/v1/token'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request GET \ --url https://zkao.io/api/v1/token \ --header 'Authorization: Bearer ' ``` * Production`zkao.io/api/v1/token` * Staging`staging.zkao.io/api/v1/token` Any valid token may call this, whatever its scopes. Use it to learn which project (and organization) a token belongs to. ## Authorizations * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Responses ### 200 OK application/json object * **id** required string * **name** required string * **scopes** required Array\ * **repositoryIds** required Repositories the token is restricted to. Empty means every repository of the project. Array\ * **expiresAt** required string | null format: date-time * **spendLimitCredits** required Credits this token may spend. Null means no limit. integer | null * **project** required object * **id** required string * **slug** required string * **name** required string * **organization** required The organization a project belongs to. Credits are held and billed at this level and shared by every project in it. object * **id** required string * **slug** required URL segment of the organization (`/orgs/`), unique across zkao. string * **name** required string ##### Examplegenerated ```json { "id": "example", "name": "example", "scopes": [ "example" ], "repositoryIds": [ "example" ], "expiresAt": "2026-04-15T12:00:00Z", "spendLimitCredits": 1, "project": { "id": "example", "slug": "example", "name": "example", "organization": { "id": "example", "slug": "example", "name": "example" } } } ``` ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` --- Source: https://docs.zkao.io/api/operations/gettriagerun/ # Get one triage run GET /projects/{projectId}/scans/{scanId}/triage/runs/{runId} ```js const url = 'https://zkao.io/api/v1/projects/example/scans/example/triage/runs/example'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request GET \ --url https://zkao.io/api/v1/projects/example/scans/example/triage/runs/example \ --header 'Authorization: Bearer ' ``` * Production`zkao.io/api/v1/projects/{projectId}/scans/{scanId}/triage/runs/{runId}` * Staging`staging.zkao.io/api/v1/projects/{projectId}/scans/{scanId}/triage/runs/{runId}` Requires scope: `read`. Follows this run independently of the scan status. A COMPLETED run can still leave findings unfinished. Check scan.triage after it ends. Failed attempts awaiting retry remain QUEUED. ## Authorizations * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **projectId** required string * **scanId** required string * **runId** required string ## Responses ### 200 OK application/json object * **run** required object * **id** required string * **scanId** required string * **status** required string Allowed values: QUEUED RUNNING COMPLETED FAILED CANCELLED * **findingCount** required Number of findings selected when this run started. integer * **createdAt** required string format: date-time * **completedAt** required string | null format: date-time * **budgetExhausted** required Whether this run reached its budget cap. Check scan.triage for remaining work. boolean ##### Example ```json { "run": { "status": "QUEUED" } } ``` #### Headers * **Retry-After** integer \>= 1 Advisory seconds before polling an active run again. ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 Resource not in this token’s project or repo allowlist application/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 ```json { "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 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 ```json { "error": { "code": "unauthorized" } } ``` #### Headers * **Retry-After** integer Seconds to wait before retrying. --- Source: https://docs.zkao.io/api/operations/investigatereport/ # Investigate an incoming report against the code POST /projects/{projectId}/reports/{publicId}/investigate ```js const url = 'https://zkao.io/api/v1/projects/example/reports/example/investigate'; const options = {method: 'POST', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request POST \ --url https://zkao.io/api/v1/projects/example/reports/example/investigate \ --header 'Authorization: Bearer ' ``` * Production`zkao.io/api/v1/projects/{projectId}/reports/{publicId}/investigate` * Staging`staging.zkao.io/api/v1/projects/{projectId}/reports/{publicId}/investigate` Requires scope: `scans:launch`. Runs the triage flow over the report’s claims: each is checked against the repository, deduplicated against the findings already confirmed there, and given a proof of concept where one can be written. Returns immediately with the scan doing the work; poll `/projects/{projectId}/scans/{scanId}` and then read its findings. Idempotent. A report already under investigation returns the existing scan with `claimsQueued: null`, so a retry costs nothing. ## Authorizations * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **projectId** required string * **publicId** required string The report’s public identifier. ## Responses ### 200 OK application/json object * **publicId** required string * **scanId** required The scan triaging this report’s claims. string * **claimsQueued** required Claims queued for triage, or null when an investigation was already running and this call started nothing. integer | null ##### Examplegenerated ```json { "publicId": "example", "scanId": "example", "claimsQueued": 1 } ``` ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 402 The project does not have enough prepaid credits to cover the scan budget. Top up credits and retry. (code `insufficient_credits`) application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 Resource not in this token’s project or repo allowlist application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 409 A compare-and-set (`expectedContent`) missed: the guidance changed since it was read. Re-read the current guidance and retry. application/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 ```json { "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 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 ```json { "error": { "code": "unauthorized" } } ``` #### Headers * **Retry-After** integer Seconds to wait before retrying. --- Source: https://docs.zkao.io/api/operations/launchscan/ # Launch a scan POST /projects/{projectId}/scans ```js const url = 'https://zkao.io/api/v1/projects/example/scans'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', '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); } ``` ```sh curl --request POST \ --url https://zkao.io/api/v1/projects/example/scans \ --header 'Authorization: Bearer ' \ --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" }' ``` * Production`zkao.io/api/v1/projects/{projectId}/scans` * Staging`staging.zkao.io/api/v1/projects/{projectId}/scans` 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 * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **projectId** required string ## Request Bodyrequired application/json object * **repositoryId** required string * **creditBudget** 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. integer \>= 1 * **presetRef** A preset ref from /scan-presets. Defaults to the first active preset. string * **branch** Branch to scan (resolved to its head commit server-side). Ignored if commitHash is set. string | null * **commitHash** Pin a specific commit SHA (7-40 hex chars). string | null * **commitMessage** string | null * **baseCommit** 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. string | null * **backlogRecheck** 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 * **includeInProgress** Also include In progress findings. Defaults to false. boolean * **findingIds** 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. Array\ \>= 1 items <= 500 items * **resumeScanId** Continue a finished recheck’s unassessed findings on the same repository. Uses that scan’s branch, commit, and status selection. string \>= 1 characters not matching * **findingIds** required * **resumeScanId** required * **trigger** One of: object 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 * **kind** required What asked for the scan. string Allowed values: github_action pr_comment agent api * **pullRequest** Pull request number in the scanned repository. Its existence is not checked: a wrong number only yields a dead link in your own repository. integer | null \>= 1 * **commentId** The comment that asked for the scan, so the link lands on it. Requires pullRequest. string | null /^\[0-9]{1,32}$/ null null * **auditAreaKeys** 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. Array\ * **auditScope** The code to audit, described in your own words, instead of `auditAreaKeys`. Send one or the other, not both. string | null <= 10000 characters * **guidance** 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. string | null <= 100000 characters ## Responses ### 202 Scan accepted (queued) application/json object * **scanId** required string * **queued** required boolean * **creditBudget** required The budget the scan was launched with, in credits. integer * **buildsOverview** required 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. boolean ##### Examplegenerated ```json { "scanId": "example", "queued": true, "creditBudget": 1, "buildsOverview": true } ``` ### 400 Invalid request application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 402 The project does not have enough prepaid credits to cover the scan budget. Top up credits and retry. (code `insufficient_credits`) application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 Resource not in this token’s project or repo allowlist application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 409 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`) application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 422 The diff scan has nothing to audit. Code `diff_empty`: the base and the scanned commit have no change between them. application/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 ```json { "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 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 ```json { "error": { "code": "unauthorized" } } ``` #### Headers * **Retry-After** integer Seconds to wait before retrying. --- Source: https://docs.zkao.io/api/operations/listadvisories/ # List advisories GET /projects/{projectId}/advisories ```js const url = 'https://zkao.io/api/v1/projects/example/advisories?page=1&limit=50&status=DRAFT'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request GET \ --url 'https://zkao.io/api/v1/projects/example/advisories?page=1&limit=50&status=DRAFT' \ --header 'Authorization: Bearer ' ``` * Production`zkao.io/api/v1/projects/{projectId}/advisories` * Staging`staging.zkao.io/api/v1/projects/{projectId}/advisories` Requires scope: `read`. The project’s coordinated-disclosure advisories, newest first. Optionally filter by `status`. A repository-restricted token sees an advisory only when every associated repository is in its allowlist. ## Authorizations * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **projectId** required string ### Query Parameters * **page** integer default: 1 >= 1 * **limit** integer default: 50 >= 1 <= 100 * **status** string Allowed values: DRAFT SCHEDULED UNDER_EMBARGO PUBLISHED WITHDRAWN Only advisories in this status. ## Responses ### 200 OK application/json object * **items** required Array\ 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 * **page** required integer * **limit** required integer * **total** required integer ##### Example ```json { "items": [ { "severity": "CRITICAL", "status": "DRAFT" } ] } ``` ### 400 Invalid request application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 Resource not in this token’s project or repo allowlist application/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 ```json { "error": { "code": "unauthorized" } } ``` --- Source: https://docs.zkao.io/api/operations/listadvisorycontacts/ # List the advisory contacts GET /projects/{projectId}/advisory-contacts ```js const url = 'https://zkao.io/api/v1/projects/example/advisory-contacts?page=1&limit=50&tier=EMBARGO&status=ACTIVE'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request GET \ --url 'https://zkao.io/api/v1/projects/example/advisory-contacts?page=1&limit=50&tier=EMBARGO&status=ACTIVE' \ --header 'Authorization: Bearer ' ``` * Production`zkao.io/api/v1/projects/{projectId}/advisory-contacts` * Staging`staging.zkao.io/api/v1/projects/{projectId}/advisory-contacts` Requires scope: `contacts:read`. The programme’s contact list, oldest first, which is the order to read it in when reconciling against a record kept elsewhere. Its own scope, not `read`: this list is other people’s work addresses and the record of who learns about a vulnerability before the public does, so a routine pipeline token does not reach it. `software` on each row is what notices are matched on. A project with no security programme reads as an empty list. ## Authorizations * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **projectId** required string ### Query Parameters * **page** integer default: 1 >= 1 * **limit** integer default: 50 >= 1 <= 100 * **tier** string Allowed values: EMBARGO DOWNSTREAM ANNOUNCE * **status** string Allowed values: ACTIVE PENDING_VERIFICATION BOUNCED UNSUBSCRIBED ## Responses ### 200 OK application/json object * **items** required Array\ object * **id** required string * **email** required string * **organization** required string * **tier** required string * **status** required `PENDING_VERIFICATION` until the contact confirms the address. An unconfirmed address receives nothing embargoed. string * **software** required The software this contact runs, which notices are matched on. Array\ object * **owner** required string * **name** required string * **createdAt** required string format: date-time * **page** required integer * **limit** required integer * **total** required integer ##### Examplegenerated ```json { "items": [ { "id": "example", "email": "example", "organization": "example", "tier": "example", "status": "example", "software": [ { "owner": "example", "name": "example" } ], "createdAt": "2026-04-15T12:00:00Z" } ], "page": 1, "limit": 1, "total": 1 } ``` ### 400 Invalid request application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` --- Source: https://docs.zkao.io/api/operations/listagentquestions/ # List the open questions Continuous Security analyses asked GET /projects/{projectId}/agent-questions ```js const url = 'https://zkao.io/api/v1/projects/example/agent-questions'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request GET \ --url https://zkao.io/api/v1/projects/example/agent-questions \ --header 'Authorization: Bearer ' ``` * Production`zkao.io/api/v1/projects/{projectId}/agent-questions` * Staging`staging.zkao.io/api/v1/projects/{projectId}/agent-questions` Requires scope: `read`. The open questions the project’s continuous analyses asked its members, oldest first, at most 200. ## Authorizations * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **projectId** required string ## Responses ### 200 OK application/json object * **questions** required Array\ object * **id** required string * **repositoryId** required string * **branch** required The branch the analysis runs on. Null is the repository’s default branch. string | null * **text** required string * **options** required Array\ object * **label** required string * **description** required string | null * **askedAt** required string format: date-time * **asker** required The analysis that asked. string ##### Examplegenerated ```json { "questions": [ { "id": "example", "repositoryId": "example", "branch": "example", "text": "example", "options": [ { "label": "example", "description": "example" } ], "askedAt": "2026-04-15T12:00:00Z", "asker": "example" } ] } ``` ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 Resource not in this token’s project or repo allowlist application/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 ```json { "error": { "code": "unauthorized" } } ``` --- Source: https://docs.zkao.io/api/operations/listauditareas/ # List a repository's audit areas GET /projects/{projectId}/repositories/{repositoryId}/audit-areas ```js const url = 'https://zkao.io/api/v1/projects/example/repositories/example/audit-areas'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request GET \ --url https://zkao.io/api/v1/projects/example/repositories/example/audit-areas \ --header 'Authorization: Bearer ' ``` * Production`zkao.io/api/v1/projects/{projectId}/repositories/{repositoryId}/audit-areas` * Staging`staging.zkao.io/api/v1/projects/{projectId}/repositories/{repositoryId}/audit-areas` Requires scope: `read`. Audit areas are the named subsystems a scan can be scoped to (`auditAreaKeys` on launch). Each scan that maps the repository keeps the list current; sizes come from one branch’s map, so an area that map no longer names is returned without one. ## Authorizations * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **projectId** required string * **repositoryId** required string ### Query Parameters * **branch** string Branch whose map the sizes come from. Defaults to the repository’s default branch. ## Responses ### 200 OK application/json object * **repositoryId** required string * **branch** required Branch the sizes were read from. string | null * **mapped** required Whether that branch has a stored map at all. boolean * **totalFiles** required integer | null * **totalLines** required integer | null * **areas** required The map’s own audit order first, then the areas it no longer names. Array\ 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 ```json { "areas": [ { "source": "discovered" } ] } ``` ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 Resource not in this token’s project or repo allowlist application/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 ```json { "error": { "code": "unauthorized" } } ``` --- Source: https://docs.zkao.io/api/operations/listfindingdetails/ # Get many findings (full detail) GET /projects/{projectId}/findings/details ```js const url = 'https://zkao.io/api/v1/projects/example/findings/details?page=1&limit=25'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request GET \ --url 'https://zkao.io/api/v1/projects/example/findings/details?page=1&limit=25' \ --header 'Authorization: Bearer ' ``` * Production`zkao.io/api/v1/projects/{projectId}/findings/details` * Staging`staging.zkao.io/api/v1/projects/{projectId}/findings/details` Requires scope: `read`. The full detail of a scan’s findings, of a set of findings, or both, in one call. Returns the findings shown in the app: confirmed or inconclusive, on scans the project can see. ## Authorizations * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **projectId** required string ### Query Parameters * **page** integer default: 1 >= 1 * **limit** integer default: 25 >= 1 <= 50 * **scanId** string Only findings belonging to this scan. * **ids** string Comma-separated finding ids or `ZK-` labels, at most 50. Ids that match nothing are listed in `missing`. ## Responses ### 200 OK application/json object * **items** required Array object * **id** required string * **displayId** required integer * **title** required string * **location** required string * **severity** required Effective severity (user override if set, else AI severity). string Allowed values: CRITICAL HIGH MEDIUM LOW INFO * **category** required string * **triageStatus** required string Allowed values: PENDING NEW DUPLICATE RECURRING CONFIRMED FALSE_POSITIVE INCONCLUSIVE * **confirmationEvidence** What backs a CONFIRMED verdict. POC means a proof of concept ran and demonstrated the issue. ANALYSIS means it was confirmed by code analysis alone. Null for other statuses or when not recorded. string | null Allowed values: POC ANALYSIS * **resolutionStatus** required string Allowed values: NOT_STARTED IN_PROGRESS RESOLVED WONT_FIX MITIGATED FALSE_POSITIVE DUPLICATE * **notesCount** required integer * **source** required Where the finding was found. object * **kind** required The kind of scan that found it. One of continuous-security, pr-review, flash, max, flash-diff, max-diff, supply-chain, flash-retriage, max-retriage, flash-regression-check, max-regression-check, manual-audit, report-investigation or other. New kinds may be added, so treat an unknown kind like other. string * **branch** required The branch the scan ran on. Null when the scan recorded none, such as a scan of a pinned commit. string | null * **dismissalReason** required Why triage dismissed the finding as a false positive. Null when triage did not dismiss it or gave no reason. string | null * **triageOverriddenFrom** required One of: string string Allowed values: PENDING NEW DUPLICATE RECURRING CONFIRMED FALSE_POSITIVE INCONCLUSIVE null null * **triageOverriddenAt** required string | null format: date-time * **triageOverriddenByName** required Name, or email when there is no name, of the member who overrode triage. string | null * **description** required string * **impact** required string * **recommendation** required string * **assumptions** required Array\ * **pocReport** string | null * **recommendedFix** string | null * **scanId** required string * **commitHash** string | null * **repo** object * **owner** string * **name** string * **url** string * **createdAt** required string format: date-time * **notes** required Array\ object * **id** required string * **body** required Markdown. A page of the app the assistant names is an absolute link. string * **createdAt** required string format: date-time * **author** object * **id** string * **name** string | null * **email** string * **page** required integer * **limit** required integer * **total** required integer * **missing** required The requested `ids` that matched no finding. Array\ ##### Example ```json { "items": [ { "severity": "CRITICAL", "triageStatus": "PENDING", "confirmationEvidence": "POC", "resolutionStatus": "NOT_STARTED", "triageOverriddenFrom": "PENDING" } ] } ``` ### 400 Invalid request application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 Resource not in this token’s project or repo allowlist application/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 ```json { "error": { "code": "unauthorized" } } ``` --- Source: https://docs.zkao.io/api/operations/listfindings/ # List findings GET /projects/{projectId}/findings ```js const url = 'https://zkao.io/api/v1/projects/example/findings?page=1&limit=50'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request GET \ --url 'https://zkao.io/api/v1/projects/example/findings?page=1&limit=50' \ --header 'Authorization: Bearer ' ``` * Production`zkao.io/api/v1/projects/{projectId}/findings` * Staging`staging.zkao.io/api/v1/projects/{projectId}/findings` Requires scope: `read`. Optionally filter by `scanId`. ## Authorizations * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **projectId** required string ### Query Parameters * **page** integer default: 1 >= 1 * **limit** integer default: 50 >= 1 <= 100 * **scanId** string Only findings belonging to this scan. ## Responses ### 200 OK application/json object * **items** required Array\ object * **id** required string * **displayId** required integer * **title** required string * **location** required string * **severity** required Effective severity (user override if set, else AI severity). string Allowed values: CRITICAL HIGH MEDIUM LOW INFO * **category** required string * **triageStatus** required string Allowed values: PENDING NEW DUPLICATE RECURRING CONFIRMED FALSE_POSITIVE INCONCLUSIVE * **confirmationEvidence** What backs a CONFIRMED verdict. POC means a proof of concept ran and demonstrated the issue. ANALYSIS means it was confirmed by code analysis alone. Null for other statuses or when not recorded. string | null Allowed values: POC ANALYSIS * **resolutionStatus** required string Allowed values: NOT_STARTED IN_PROGRESS RESOLVED WONT_FIX MITIGATED FALSE_POSITIVE DUPLICATE * **notesCount** required integer * **source** required Where the finding was found. object * **kind** required The kind of scan that found it. One of continuous-security, pr-review, flash, max, flash-diff, max-diff, supply-chain, flash-retriage, max-retriage, flash-regression-check, max-regression-check, manual-audit, report-investigation or other. New kinds may be added, so treat an unknown kind like other. string * **branch** required The branch the scan ran on. Null when the scan recorded none, such as a scan of a pinned commit. string | null * **dismissalReason** required Why triage dismissed the finding as a false positive. Null when triage did not dismiss it or gave no reason. string | null * **triageOverriddenFrom** required One of: string string Allowed values: PENDING NEW DUPLICATE RECURRING CONFIRMED FALSE_POSITIVE INCONCLUSIVE null null * **triageOverriddenAt** required string | null format: date-time * **triageOverriddenByName** required Name, or email when there is no name, of the member who overrode triage. string | null * **page** required integer * **limit** required integer * **total** required integer ##### Example ```json { "items": [ { "severity": "CRITICAL", "triageStatus": "PENDING", "confirmationEvidence": "POC", "resolutionStatus": "NOT_STARTED", "triageOverriddenFrom": "PENDING" } ] } ``` ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 Resource not in this token’s project or repo allowlist application/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 ```json { "error": { "code": "unauthorized" } } ``` --- Source: https://docs.zkao.io/api/operations/listregressiontests/ # List regression test attempts for a finding GET /projects/{projectId}/findings/{findingId}/regression-tests ```js const url = 'https://zkao.io/api/v1/projects/example/findings/example/regression-tests'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request GET \ --url https://zkao.io/api/v1/projects/example/findings/example/regression-tests \ --header 'Authorization: Bearer ' ``` * Production`zkao.io/api/v1/projects/{projectId}/findings/{findingId}/regression-tests` * Staging`staging.zkao.io/api/v1/projects/{projectId}/findings/{findingId}/regression-tests` Requires scope: `read`. Returns the latest 20 attempts. ## Authorizations * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **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. ## Responses ### 200 OK application/json object * **runs** required Array\ 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 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 null null * **target** required Any of: object 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 null null * **createdAt** required string format: date-time * **completedAt** required string | null format: date-time ##### Example ```json { "runs": [ { "status": "QUEUED", "audited": { "outcome": "assertion_failed" }, "target": { "outcome": "assertion_failed" } } ] } ``` ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 Resource not in this token’s project or repo allowlist application/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 ```json { "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 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 ```json { "error": { "code": "unauthorized" } } ``` #### Headers * **Retry-After** integer Seconds to wait before retrying. --- Source: https://docs.zkao.io/api/operations/listreports/ # List incoming reports GET /projects/{projectId}/reports ```js const url = 'https://zkao.io/api/v1/projects/example/reports?page=1&limit=50&status=NEW'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request GET \ --url 'https://zkao.io/api/v1/projects/example/reports?page=1&limit=50&status=NEW' \ --header 'Authorization: Bearer ' ``` * Production`zkao.io/api/v1/projects/{projectId}/reports` * Staging`staging.zkao.io/api/v1/projects/{projectId}/reports` Requires scope: `read`. Vulnerability reports the programme has received, newest first. Optionally filter by `status`. `publicId` is what `investigateReport` takes. `intakeState` says whether the report has been read and split into claims yet: an investigation waits for `COMPLETE`, so a `PENDING` or `RUNNING` report is one to come back to rather than one to retry. ## Authorizations * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **projectId** required string ### Query Parameters * **page** integer default: 1 >= 1 * **limit** integer default: 50 >= 1 <= 100 * **status** string Allowed values: NEW TRIAGING NEEDS_INFO ACCEPTED DUPLICATE REJECTED Only reports in this triage status. ## Responses ### 200 OK application/json object * **items** required Array\ object * **publicId** required The identifier `investigateReport` takes. string * **title** required string * **source** required How it arrived, including GitHub private reports, API submissions, and file imports. string * **claimedSeverity** One of: string string Allowed values: CRITICAL HIGH MEDIUM LOW INFO null null * **status** required string Allowed values: NEW TRIAGING NEEDS_INFO ACCEPTED DUPLICATE REJECTED * **intakeState** required Whether the report has been read and split into claims. An investigation waits for COMPLETE. string Allowed values: PENDING RUNNING REVIEW COMPLETE FAILED * **evaluationState** How the investigation is going, or null if none has run. string | null Allowed values: QUEUED RUNNING COMPLETE FAILED * **reporterName** string | null * **reporterGithubLogin** string | null * **githubUrl** The GitHub advisory it arrived as. string | null * **acknowledgedAt** string | null format: date-time * **createdAt** required string format: date-time * **page** required integer * **limit** required integer * **total** required integer ##### Example ```json { "items": [ { "claimedSeverity": "CRITICAL", "status": "NEW", "intakeState": "PENDING", "evaluationState": "QUEUED" } ] } ``` ### 400 Invalid request application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 Resource not in this token’s project or repo allowlist application/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 ```json { "error": { "code": "unauthorized" } } ``` --- Source: https://docs.zkao.io/api/operations/listrepositories/ # List repositories in the project GET /projects/{projectId}/repositories ```js const url = 'https://zkao.io/api/v1/projects/example/repositories'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request GET \ --url https://zkao.io/api/v1/projects/example/repositories \ --header 'Authorization: Bearer ' ``` * Production`zkao.io/api/v1/projects/{projectId}/repositories` * Staging`staging.zkao.io/api/v1/projects/{projectId}/repositories` Requires scope: `read`. Limited to the token’s repo allowlist when set. ## Authorizations * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **projectId** required string ## Responses ### 200 OK application/json object * **repositories** required Array\ object * **id** required string * **slug** required URL segment of the repository inside its project (`/orgs//projects//repos/`). Unique per project. string * **owner** required string * **name** required string * **url** required string * **defaultBranch** string | null * **status** required ACTIVE | MARKED_FOR_DELETION string * **readiness** required Whether a scan can start on this repository. A newly added repository is `analyzing` until a one-time pass over it finishes; launching a scan meanwhile fails with `repository_initializing`. Poll this endpoint rather than retrying the launch blind. string Allowed values: ready analyzing ##### Example ```json { "repositories": [ { "readiness": "ready" } ] } ``` ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 Resource not in this token’s project or repo allowlist application/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 ```json { "error": { "code": "unauthorized" } } ``` --- Source: https://docs.zkao.io/api/operations/listscanpresets/ # List the scan presets (scan types) the project can launch GET /projects/{projectId}/scan-presets ```js const url = 'https://zkao.io/api/v1/projects/example/scan-presets'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request GET \ --url https://zkao.io/api/v1/projects/example/scan-presets \ --header 'Authorization: Bearer ' ``` * Production`zkao.io/api/v1/projects/{projectId}/scan-presets` * Staging`staging.zkao.io/api/v1/projects/{projectId}/scan-presets` Requires scope: `read`. Use a preset’s `ref` as `presetRef` when launching. ## Authorizations * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **projectId** required string ## Responses ### 200 OK application/json object * **presets** required Array\ object * **ref** required Pass as `presetRef` when launching. string * **name** required string * **description** string | null * **minCredits** required Minimum budget for a launch. 0 = use the default floor. integer * **modelTier** required string ##### Examplegenerated ```json { "presets": [ { "ref": "example", "name": "example", "description": "example", "minCredits": 1, "modelTier": "example" } ] } ``` ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 Resource not in this token’s project or repo allowlist application/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 ```json { "error": { "code": "unauthorized" } } ``` --- Source: https://docs.zkao.io/api/operations/listscans/ # List scans (most recent first) GET /projects/{projectId}/scans ```js const url = 'https://zkao.io/api/v1/projects/example/scans?page=1&limit=50'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request GET \ --url 'https://zkao.io/api/v1/projects/example/scans?page=1&limit=50' \ --header 'Authorization: Bearer ' ``` * Production`zkao.io/api/v1/projects/{projectId}/scans` * Staging`staging.zkao.io/api/v1/projects/{projectId}/scans` Requires scope: `read`. ## Authorizations * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **projectId** required string ### Query Parameters * **page** integer default: 1 >= 1 * **limit** integer default: 50 >= 1 <= 100 ## Responses ### 200 OK application/json object * **items** required Array\ object * **id** required string * **status** required string Allowed values: QUEUED PROCESSING COMPLETED FAILED CANCELLED * **failureCode** An actionable setup failure for a failed scan. Null for other statuses and internal failures. Restore a project member’s GitHub access or approve the App permissions before launching again. string | null Allowed values: NO_MEMBER_REPO_ACCESS GITHUB_APP_PERMISSIONS_PENDING * **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 * **effort** The scan’s budget measured against the levels sized for its scope at launch. `high` starts at the recommended baseline, `extra-high` at the next level, and `deep` at the highest level. The server accounts for the scan limit and any fixed setup cost when sizing these levels. `medium` records a custom budget below High or a historical scan at that level. Null for a Flash scan and for a scan with no recorded effort. string | null Allowed values: medium high extra-high deep * **createdAt** required string format: date-time * **startedAt** string | null format: date-time * **completedAt** string | null format: date-time * **progress** One of: object 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 null null * **budget** One of: object What a scan was allowed to spend, what it was charged, and whether the next scan of its type and scope should get more. Check the last scan of a type before choosing the next one’s budget. object * **limitCredits** required The most the scan could spend, in credits. integer * **spentCredits** required Credits charged for the scan. Null until it finishes. integer | null * **nextBudgetRecommendation** required Whether the next scan of this type and scope should keep this budget or raise it. A raise is half again, never above twice the scan type’s minimum. A raise can follow a scan that spent well under its limit: the limit is divided between the parts of the analysis, and one part cannot use another’s unspent share. Null until the scan completes. string | null Allowed values: keep raise null null * **page** required integer * **limit** required integer * **total** required integer ##### Example ```json { "items": [ { "status": "QUEUED", "failureCode": "NO_MEMBER_REPO_ACCESS", "effort": "medium", "budget": { "nextBudgetRecommendation": "keep" } } ] } ``` ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 Resource not in this token’s project or repo allowlist application/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 ```json { "error": { "code": "unauthorized" } } ``` --- Source: https://docs.zkao.io/api/operations/overridefindingtriage/ # Override a finding's triage verdict PATCH /projects/{projectId}/findings/{findingId}/triage ```js const url = 'https://zkao.io/api/v1/projects/example/findings/example/triage'; const options = { method: 'PATCH', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"triageStatus":"CONFIRMED","note":"example"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request PATCH \ --url https://zkao.io/api/v1/projects/example/findings/example/triage \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "triageStatus": "CONFIRMED", "note": "example" }' ``` * Production`zkao.io/api/v1/projects/{projectId}/findings/{findingId}/triage` * Staging`staging.zkao.io/api/v1/projects/{projectId}/findings/{findingId}/triage` Requires scope: `findings:write`. Replaces the AI triage verdict with `CONFIRMED` or `FALSE_POSITIVE`. The override keeps the first AI verdict it replaced. Setting that verdict again clears the override. A `note` is added to the finding as a comment from the member who created the token. ## Authorizations * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **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. ## Request Bodyrequired application/json object * **triageStatus** required string Allowed values: CONFIRMED FALSE_POSITIVE * **note** string \>= 1 characters ## Responses ### 200 OK application/json object * **findingId** required string * **triageStatus** required string Allowed values: PENDING NEW DUPLICATE RECURRING CONFIRMED FALSE_POSITIVE INCONCLUSIVE * **previousTriageStatus** required string Allowed values: PENDING NEW DUPLICATE RECURRING CONFIRMED FALSE_POSITIVE INCONCLUSIVE * **noteId** required The comment the override added, or null without a note. string | null ##### Example ```json { "triageStatus": "PENDING", "previousTriageStatus": "PENDING" } ``` ### 400 Invalid request application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 Resource not in this token’s project or repo allowlist application/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 ```json { "error": { "code": "unauthorized" } } ``` --- Source: https://docs.zkao.io/api/operations/pinfindingnote/ # Pin a note as the resolution note POST /projects/{projectId}/findings/{findingId}/notes/{noteId}/pin ```js const url = 'https://zkao.io/api/v1/projects/example/findings/example/notes/example/pin'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"kind":"resolution"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request POST \ --url https://zkao.io/api/v1/projects/example/findings/example/notes/example/pin \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "kind": "resolution" }' ``` * Production`zkao.io/api/v1/projects/{projectId}/findings/{findingId}/notes/{noteId}/pin` * Staging`staging.zkao.io/api/v1/projects/{projectId}/findings/{findingId}/notes/{noteId}/pin` Requires scope: `findings:write`. ## Authorizations * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **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. * **noteId** required string ## Request Bodyrequired application/json object * **kind** required string Allowed values: resolution ## Responses ### 200 OK application/json object * **findingId** required string * **noteId** required string | null ##### Examplegenerated ```json { "findingId": "example", "noteId": "example" } ``` ### 400 Invalid request application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 Resource not in this token’s project or repo allowlist application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 409 A compare-and-set (`expectedContent`) missed: the guidance changed since it was read. Re-read the current guidance and retry. application/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 ```json { "error": { "code": "unauthorized" } } ``` --- Source: https://docs.zkao.io/api/operations/preparecontinuoustesting/ # Prepare a branch's next Continuous Security analysis POST /projects/{projectId}/repositories/{repositoryId}/continuous-testing/prepare ```js const url = 'https://zkao.io/api/v1/projects/example/repositories/example/continuous-testing/prepare'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"branch":"example"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request POST \ --url https://zkao.io/api/v1/projects/example/repositories/example/continuous-testing/prepare \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "branch": "example" }' ``` * Production`zkao.io/api/v1/projects/{projectId}/repositories/{repositoryId}/continuous-testing/prepare` * Staging`staging.zkao.io/api/v1/projects/{projectId}/repositories/{repositoryId}/continuous-testing/prepare` Requires scope: `automations:write`. Plans the branch’s next analysis without running it. It works whether automatic analysis is on or off. Preparing spends no credits. A preparation already in progress on the branch is reused. When nothing has changed since the plan was last prepared, the branch’s conversation with zkao says so and the plan stays as it is. Responds `400` when the branch does not exist or has no active Continuous Security, and `409` while the repository is still being prepared. ## Authorizations * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **projectId** required string * **repositoryId** required string ## Request Bodyrequired application/json object * **branch** required string <= 255 characters ##### Examplegenerated ```json { "branch": "example" } ``` ## Responses ### 200 OK application/json object * **preparing** required boolean ##### Example ```json { "preparing": true } ``` ### 400 Invalid request application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 Resource not in this token’s project or repo allowlist application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 409 A compare-and-set (`expectedContent`) missed: the guidance changed since it was read. Re-read the current guidance and retry. application/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 ```json { "error": { "code": "unauthorized" } } ``` --- Source: https://docs.zkao.io/api/operations/publishfinding/ # Publish a finding as a public artifact POST /projects/{projectId}/findings/{findingId}/publish ```js const url = 'https://zkao.io/api/v1/projects/example/findings/example/publish'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"noteId":"example","withPassword":true}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request POST \ --url https://zkao.io/api/v1/projects/example/findings/example/publish \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "noteId": "example", "withPassword": true }' ``` * Production`zkao.io/api/v1/projects/{projectId}/findings/{findingId}/publish` * Staging`staging.zkao.io/api/v1/projects/{projectId}/findings/{findingId}/publish` Requires scope: `publish`. Pin a note as the published note via `noteId`. An omitted body uses defaults. A nonempty body must be valid JSON or the request returns 400 without publishing. ## Authorizations * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **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. ## Request Body application/json object * **noteId** A note id on the finding to pin as the published note. string * **withPassword** True generates a new access password. False removes password protection. Omission preserves an existing password. boolean ##### Examplegenerated ```json { "noteId": "example", "withPassword": true } ``` ## Responses ### 200 OK application/json object * **artifactId** required string * **publicId** required Slug in /public/{scans,findings}/. string * **accessPassword** The artifact’s current access password, or null when it has no password. string | null ##### Examplegenerated ```json { "artifactId": "example", "publicId": "example", "accessPassword": "example" } ``` ### 400 Invalid request application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 Resource not in this token’s project or repo allowlist application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 409 A compare-and-set (`expectedContent`) missed: the guidance changed since it was read. Re-read the current guidance and retry. application/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 ```json { "error": { "code": "unauthorized" } } ``` --- Source: https://docs.zkao.io/api/operations/publishscan/ # Publish a scan as a public artifact POST /projects/{projectId}/scans/{scanId}/publish ```js const url = 'https://zkao.io/api/v1/projects/example/scans/example/publish'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"withPassword":true}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request POST \ --url https://zkao.io/api/v1/projects/example/scans/example/publish \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "withPassword": true }' ``` * Production`zkao.io/api/v1/projects/{projectId}/scans/{scanId}/publish` * Staging`staging.zkao.io/api/v1/projects/{projectId}/scans/{scanId}/publish` Requires scope: `publish`. The scan must be COMPLETED. An omitted body uses defaults. A nonempty body must be valid JSON or the request returns 400 without publishing. ## Authorizations * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **projectId** required string * **scanId** required string ## Request Body application/json object * **withPassword** True generates a new access password. False removes password protection. Omission preserves an existing password. boolean ##### Examplegenerated ```json { "withPassword": true } ``` ## Responses ### 200 OK application/json object * **artifactId** required string * **publicId** required Slug in /public/{scans,findings}/. string * **accessPassword** The artifact’s current access password, or null when it has no password. string | null ##### Examplegenerated ```json { "artifactId": "example", "publicId": "example", "accessPassword": "example" } ``` ### 400 Invalid request application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 Resource not in this token’s project or repo allowlist application/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 ```json { "error": { "code": "unauthorized" } } ``` --- Source: https://docs.zkao.io/api/operations/removecontinuoustesting/ # Remove a repository's Continuous Security schedule DELETE /projects/{projectId}/repositories/{repositoryId}/continuous-testing ```js const url = 'https://zkao.io/api/v1/projects/example/repositories/example/continuous-testing'; const options = {method: 'DELETE', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request DELETE \ --url https://zkao.io/api/v1/projects/example/repositories/example/continuous-testing \ --header 'Authorization: Bearer ' ``` * Production`zkao.io/api/v1/projects/{projectId}/repositories/{repositoryId}/continuous-testing` * Staging`staging.zkao.io/api/v1/projects/{projectId}/repositories/{repositoryId}/continuous-testing` Requires scope: `automations:write`. Scans the schedule already ran stay. Responds `404` when the branch has no schedule. ## Authorizations * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **projectId** required string * **repositoryId** required string ### Query Parameters * **branch** string The scheduled branch. Defaults to the repository’s default branch. ## Responses ### 200 OK application/json object * **repositoryId** required string * **branch** required string * **removed** required boolean ##### Examplegenerated ```json { "repositoryId": "example", "branch": "example", "removed": true } ``` ### 400 Invalid request application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 Resource not in this token’s project or repo allowlist application/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 ```json { "error": { "code": "unauthorized" } } ``` --- Source: https://docs.zkao.io/api/operations/replaceadvisoryaffected/ # Record which versions an advisory affects PUT /projects/{projectId}/advisories/{publicId}/affected ```js const url = 'https://zkao.io/api/v1/projects/example/advisories/example/affected'; const options = { method: 'PUT', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"affected":[{"repository":{"owner":"example","name":"example"},"introducedIn":"example","fixedIn":"example"}]}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request PUT \ --url https://zkao.io/api/v1/projects/example/advisories/example/affected \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "affected": [ { "repository": { "owner": "example", "name": "example" }, "introducedIn": "example", "fixedIn": "example" } ] }' ``` * Production`zkao.io/api/v1/projects/{projectId}/advisories/{publicId}/affected` * Staging`staging.zkao.io/api/v1/projects/{projectId}/advisories/{publicId}/affected` 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. ## Authorizations * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **projectId** required string * **publicId** required string The advisory’s readable identifier. ## Request Bodyrequired application/json object * **affected** required Array\ 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 ```json { "affected": [ { "repository": { "owner": "example", "name": "example" }, "introducedIn": "example", "fixedIn": "example" } ] } ``` ## Responses ### 200 OK application/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 * **owner** required string * **name** required string * **affected** required Array\ 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 * **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 ```json { "advisory": { "severity": "CRITICAL", "status": "DRAFT", "notices": [ { "status": "DRAFT" } ] } } ``` ### 400 Invalid request application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 Resource not in this token’s project or repo allowlist application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 409 A compare-and-set (`expectedContent`) missed: the guidance changed since it was read. Re-read the current guidance and retry. application/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 ```json { "error": { "code": "unauthorized" } } ``` --- Source: https://docs.zkao.io/api/operations/resumetriage/ # Resume triage after a budget stop POST /projects/{projectId}/scans/{scanId}/triage/resume ```js const url = 'https://zkao.io/api/v1/projects/example/scans/example/triage/resume'; const options = { method: 'POST', headers: { 'Idempotency-Key': 'example', Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: '{"creditBudget":1}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request POST \ --url https://zkao.io/api/v1/projects/example/scans/example/triage/resume \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: example' \ --data '{ "creditBudget": 1 }' ``` * Production`zkao.io/api/v1/projects/{projectId}/scans/{scanId}/triage/resume` * Staging`staging.zkao.io/api/v1/projects/{projectId}/scans/{scanId}/triage/resume` Requires scope: `scans:launch`. The scan must be completed and settled, with unfinished findings and a latest triage run that stopped on budget. Uses the scan’s settings and reserves the explicit budget in credits. The token’s repository restrictions and spend allowance apply. Reusing the same idempotency key and budget returns the original run, including after it finishes, without reserving or spending again. A different budget with the same key returns 409. A new attempt requires a new key. Poll getTriageRun because the parent scan remains COMPLETED. ## Authorizations * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **projectId** required string * **scanId** required string ### Header Parameters * **Idempotency-Key** required string \>= 1 characters <= 128 characters /^\[!-\~]+$/ Stable request key. Reuse it with the same budget when retrying. ## Request Bodyrequired application/json object * **creditBudget** required integer \>= 1 ##### Examplegenerated ```json { "creditBudget": 1 } ``` ## Responses ### 200 The new or previously created triage run. application/json object * **run** required object * **id** required string * **scanId** required string * **status** required string Allowed values: QUEUED RUNNING COMPLETED FAILED CANCELLED * **findingCount** required Number of findings selected when this run started. integer * **createdAt** required string format: date-time * **completedAt** required string | null format: date-time * **budgetExhausted** required Whether this run reached its budget cap. Check scan.triage for remaining work. boolean * **replayed** required boolean ##### Example ```json { "run": { "status": "QUEUED" } } ``` ### 400 Invalid request application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 402 The project does not have enough prepaid credits to cover the scan budget. Top up credits and retry. (code `insufficient_credits`) application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 Resource not in this token’s project or repo allowlist application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 409 A compare-and-set (`expectedContent`) missed: the guidance changed since it was read. Re-read the current guidance and retry. application/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 ```json { "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 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 ```json { "error": { "code": "unauthorized" } } ``` #### Headers * **Retry-After** integer Seconds to wait before retrying. --- Source: https://docs.zkao.io/api/operations/retryregressiontestpublication/ # Retry opening a generated regression test pull request POST /projects/{projectId}/findings/{findingId}/regression-tests/{runId}/retry-publication ```js const url = 'https://zkao.io/api/v1/projects/example/findings/example/regression-tests/example/retry-publication'; const options = {method: 'POST', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request POST \ --url https://zkao.io/api/v1/projects/example/findings/example/regression-tests/example/retry-publication \ --header 'Authorization: Bearer ' ``` * Production`zkao.io/api/v1/projects/{projectId}/findings/{findingId}/regression-tests/{runId}/retry-publication` * Staging`staging.zkao.io/api/v1/projects/{projectId}/findings/{findingId}/regression-tests/{runId}/retry-publication` Requires scope: `regression-tests:write` and current GitHub write access. Retries a failed publication using the saved test. Does not rerun the agent or reserve another generation budget. Generation failures require a new paid attempt. ## Authorizations * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **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. * **runId** required string ## Responses ### 202 Publication queued. application/json 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 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 null null * **target** required Any of: object 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 null null * **createdAt** required string format: date-time * **completedAt** required string | null format: date-time ##### Example ```json { "status": "QUEUED", "audited": { "outcome": "assertion_failed" }, "target": { "outcome": "assertion_failed" } } ``` ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 Resource not in this token’s project or repo allowlist application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 409 A compare-and-set (`expectedContent`) missed: the guidance changed since it was read. Re-read the current guidance and retry. application/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 ```json { "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 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 ```json { "error": { "code": "unauthorized" } } ``` #### Headers * **Retry-After** integer Seconds to wait before retrying. --- Source: https://docs.zkao.io/api/operations/setcontinuoustesting/ # Turn Continuous Security on, change it, or pause it PUT /projects/{projectId}/repositories/{repositoryId}/continuous-testing ```js const url = 'https://zkao.io/api/v1/projects/example/repositories/example/continuous-testing'; const options = { method: 'PUT', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"branch":"main","enableFeatures":["formal-verification"]}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request PUT \ --url https://zkao.io/api/v1/projects/example/repositories/example/continuous-testing \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "branch": "main", "enableFeatures": [ "formal-verification" ] }' ``` * Production`zkao.io/api/v1/projects/{projectId}/repositories/{repositoryId}/continuous-testing` * Staging`staging.zkao.io/api/v1/projects/{projectId}/repositories/{repositoryId}/continuous-testing` Requires scope: `automations:write`. Every field is optional. To start a schedule, send `enabled: true` with the branch and its authorized monthly budget. A new schedule uses `defaultMonthlyCredits` when no budget is given. The default is a low limit that funds at least one analysis step. When a month’s budget is used, automatic analysis waits until the budget is raised or the month resets. The budget sets the interval smoothly from once a month to twice a day. A budget outside the returned minimum and maximum is refused with `400`. Administrators can raise the maximum monthly budget. `areaKeys` replaces the audit areas runs rotate through, one per run. Use `enableFeatures` to add analyses or `enabledFeatures` to replace the selection. Omit both to keep it. A selection sent without `enabled` or `monthlyBudgetCredits` requires an existing schedule and returns `409` if none exists. The resulting selection must include at least one analysis that can run on its own. `enabled: false` pauses the schedule and keeps it. A change re-arms a schedule that had stopped. Each run still needs spendable credits when it launches. ## Authorizations * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **projectId** required string * **repositoryId** required string ## Request Bodyrequired application/json object * **enabled** False pauses the schedule; true turns it on or resumes it. boolean * **monthlyBudgetCredits** Re-plans the interval and the per-run budget within the returned minimum and maximum. integer \>= 1 * **areaKeys** Replaces the rotation set. An empty array scans the whole repository every run. Array\ <= 20 items * **enableFeatures** Adds the listed analyses to the current selection. Mutually exclusive with enabledFeatures. Array\ \>= 1 items unique items Allowed values: bug-hunting formal-verification dependency-analysis weak-key-analysis security-invariants * **enabledFeatures** Replaces the selection with exactly these analyses. Mutually exclusive with enableFeatures. Array\ \>= 1 items unique items Allowed values: bug-hunting formal-verification dependency-analysis weak-key-analysis security-invariants * **branch** The scheduled branch. Defaults to the repository’s default branch. string not matching * **enableFeatures** required * **enabledFeatures** required ##### Examples addFormalVerification Add formal verification to an existing schedule ```json { "branch": "main", "enableFeatures": [ "formal-verification" ] } ``` formalVerificationOnly Start or resume formal verification alone with an approved monthly budget ```json { "branch": "main", "enabled": true, "monthlyBudgetCredits": 50000, "enabledFeatures": [ "formal-verification" ] } ``` ## Responses ### 200 OK application/json object * **repositoryId** required string * **available** required False when Continuous Security is not offered. boolean * **enabled** required False when there is no schedule or it is paused. boolean * **state** required Why an enabled schedule is not running: `budget_reached` when the schedule’s or project’s monthly automation cap is reached, `needs_credits` when the organization’s credits cannot fund the next run (it resumes on its own once they can), `error` after repeated failures. Null with no schedule. string | null Allowed values: active converged budget_reached needs_credits error * **branch** required string * **monthlyBudgetCredits** required The configured monthly spending cap. Legacy schedules derive the budget from their cadence and per-run budget. integer | null * **cadence** required Legacy fixed cadence. Null for a custom interval or no schedule. Use intervalHours for the actual interval. string | null Allowed values: daily weekly biweekly monthly * **intervalHours** required Hours between scheduled runs. Null when no schedule exists. integer | null \>= 1 * **perRunBudgetCredits** required integer | null * **areaKeys** required Audit areas the runs rotate through, one per run, least recently scanned first. Empty means every run scans the whole repository. Array\ * **availableFeatures** required Analyses offered on this branch. Empty when Continuous Security is unavailable. Array\ unique items Allowed values: bug-hunting formal-verification dependency-analysis weak-key-analysis security-invariants * **enabledFeatures** required Selected analyses. A branch with no saved selection defaults to bug hunting when Continuous Security is available. A paused schedule keeps its selection. Array\ unique items Allowed values: bug-hunting formal-verification dependency-analysis weak-key-analysis security-invariants * **spentThisMonthCredits** required Credits the branch was charged for Continuous Security since the UTC month began, net of refunds. Counts its analysis steps, change assessments, public-key reviews, agent questions and the planning included in steps. integer * **runsThisMonth** required Runs the schedule launched since the UTC month began. integer * **lastRunAt** required string | null format: date-time * **nextRunAt** required When the next run becomes due. A past time means within the hour. Null when paused or stopped. string | null format: date-time * **defaultMonthlyCredits** required The monthly budget a new schedule gets when the request names none. It funds at least one analysis step. integer | null * **recommendedMonthlyCredits** required A monthly budget that funds about four analysis steps, within the minimum and maximum. A suggestion to pass as `monthlyBudgetCredits`. It is never applied when the request names no budget. integer | null * **minimumMonthlyCredits** required The smallest month that funds one analysis step. Less is refused. integer | null * **maximumMonthlyCredits** required The largest monthly budget currently allowed for the repository. Administrators can raise it. integer | null ##### Example ```json { "state": "active", "cadence": "daily", "availableFeatures": [ "bug-hunting" ], "enabledFeatures": [ "bug-hunting" ] } ``` ### 400 Invalid request application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 Resource not in this token’s project or repo allowlist application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 409 A compare-and-set (`expectedContent`) missed: the guidance changed since it was read. Re-read the current guidance and retry. application/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 ```json { "error": { "code": "unauthorized" } } ``` --- Source: https://docs.zkao.io/api/operations/setrepositoryguidance/ # Set or clear a repository's guidance PUT /projects/{projectId}/repositories/{repositoryId}/guidance ```js const url = 'https://zkao.io/api/v1/projects/example/repositories/example/guidance'; const options = { method: 'PUT', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"content":"example","expectedContent":"example"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request PUT \ --url https://zkao.io/api/v1/projects/example/repositories/example/guidance \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "content": "example", "expectedContent": "example" }' ``` * Production`zkao.io/api/v1/projects/{projectId}/repositories/{repositoryId}/guidance` * Staging`staging.zkao.io/api/v1/projects/{projectId}/repositories/{repositoryId}/guidance` Requires scope: `guidance:write`. Sets `content` as the repository’s guidance (or clears it with `null`), recording a revision. Writing the same content that is already stored is a no-op (`unchanged: true`, no revision). Pass `expectedContent` for an optimistic compare-and-set: omit it for last-writer-wins, or send the content you last read (or `null` for “currently cleared”) to get a `409` instead of clobbering a concurrent change. ## Authorizations * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **projectId** required string * **repositoryId** required string ## Request Bodyrequired application/json object * **content** required New guidance content; null clears it. string | null <= 100000 characters * **expectedContent** Optional compare-and-set. Omit for last-writer-wins. Send the content you last read (or null for “currently cleared”) to receive a 409 if the guidance changed underneath you instead of overwriting it. string | null ##### Examplegenerated ```json { "content": "example", "expectedContent": "example" } ``` ## Responses ### 200 OK application/json object * **repositoryId** required string * **revisionId** required The recorded revision id, or null on a no-op write. string | null * **unchanged** required True when the content already matched (no revision recorded). boolean ##### Examplegenerated ```json { "repositoryId": "example", "revisionId": "example", "unchanged": true } ``` ### 400 Invalid request application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 Resource not in this token’s project or repo allowlist application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 409 A compare-and-set (`expectedContent`) missed: the guidance changed since it was read. Re-read the current guidance and retry. application/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 ```json { "error": { "code": "unauthorized" } } ``` --- Source: https://docs.zkao.io/api/operations/submitreport/ # File a vulnerability report against a repository POST /projects/{projectId}/repositories/{repositoryId}/reports ```js const url = 'https://zkao.io/api/v1/projects/example/repositories/example/reports'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"title":"example","body":"example","claimedSeverity":"CRITICAL","reporter":{"name":"example","email":"example","githubLogin":"example"}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request POST \ --url https://zkao.io/api/v1/projects/example/repositories/example/reports \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "title": "example", "body": "example", "claimedSeverity": "CRITICAL", "reporter": { "name": "example", "email": "example", "githubLogin": "example" } }' ``` * Production`zkao.io/api/v1/projects/{projectId}/repositories/{repositoryId}/reports` * Staging`staging.zkao.io/api/v1/projects/{projectId}/repositories/{repositoryId}/reports` Requires scope: `reports:write`. Files a report into this project’s security programme for an active repository belonging to the project. GitHub private-report intake setup and repository admin access are not required. The report arrives as prose and is read and split into claims by the same step as an imported GitHub report. Returns with `intakeState: PENDING`. `investigateReport` refuses a report until that reaches `COMPLETE`, so poll `/projects/{projectId}/reports` before asking for an investigation. Idempotent on content: the same title and body against the same repository name the same report, so a retried call returns the original with `200` rather than filing a second copy. Free. The reading that follows is charged to the project, and the investigation is charged when someone asks for it. ## Authorizations * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **projectId** required string * **repositoryId** required string ## Request Bodyrequired application/json object * **title** required One line naming the flaw. string <= 500 characters * **body** required What the flaw is, how to reach it, and what it costs. Prose: this is read and split into claims, so write it for a reader rather than as fields. Anything past the limit would be stored and never read. string <= 80000 characters * **claimedSeverity** What the reporter claims, which is not an assessment. It decides how closely the report is read, so an inflated claim costs the programme more. string | null Allowed values: CRITICAL HIGH MEDIUM LOW INFO * **reporter** Who found it, all self-asserted. Used for attribution on the advisory, never for authorization. object * **name** string | null * **email** string | null * **githubLogin** string | null ## Responses ### 200 Already filed, by an identical earlier call application/json object * **publicId** required The identifier `investigateReport` takes. string * **intakeState** required Always PENDING here. The report is queued to be read and split into claims, and an investigation waits for COMPLETE. string ##### Examplegenerated ```json { "publicId": "example", "intakeState": "example" } ``` ### 201 Filed application/json object * **publicId** required The identifier `investigateReport` takes. string * **intakeState** required Always PENDING here. The report is queued to be read and split into claims, and an investigation waits for COMPLETE. string ##### Examplegenerated ```json { "publicId": "example", "intakeState": "example" } ``` ### 400 Invalid request application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 Resource not in this token’s project or repo allowlist application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 409 A compare-and-set (`expectedContent`) missed: the guidance changed since it was read. Re-read the current guidance and retry. application/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 ```json { "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 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 ```json { "error": { "code": "unauthorized" } } ``` #### Headers * **Retry-After** integer Seconds to wait before retrying. --- Source: https://docs.zkao.io/api/operations/tags/advisories/ # Overview ## Advisories Coordinated disclosure advisories and their notification plan ## Operations GET [/projects/{projectId}/advisories](https://docs.zkao.io/api/operations/listadvisories/) GET [/projects/{projectId}/advisories/{publicId}](https://docs.zkao.io/api/operations/getadvisory/) PUT [/projects/{projectId}/advisories/{publicId}/affected](https://docs.zkao.io/api/operations/replaceadvisoryaffected/) GET [/projects/{projectId}/advisory-contacts](https://docs.zkao.io/api/operations/listadvisorycontacts/) POST [/projects/{projectId}/advisory-contacts](https://docs.zkao.io/api/operations/addadvisorycontact/) --- Source: https://docs.zkao.io/api/operations/tags/billing/ # Overview ## Billing The organization’s prepaid credit balance, and this project’s usage ## Operations GET [/projects/{projectId}/billing/balance](https://docs.zkao.io/api/operations/getbillingbalance/) GET [/projects/{projectId}/billing/usage](https://docs.zkao.io/api/operations/getbillingusage/) GET [/projects/{projectId}/billing/summary](https://docs.zkao.io/api/operations/getbillingsummary/) --- Source: https://docs.zkao.io/api/operations/tags/discovery/ # Overview ## Discovery Scan presets for launching ## Operations GET [/projects/{projectId}/scan-presets](https://docs.zkao.io/api/operations/listscanpresets/) --- Source: https://docs.zkao.io/api/operations/tags/findings/ # Overview ## Findings Read and triage findings ## Operations GET [/projects/{projectId}/findings](https://docs.zkao.io/api/operations/listfindings/) GET [/projects/{projectId}/findings/details](https://docs.zkao.io/api/operations/listfindingdetails/) GET [/projects/{projectId}/findings/{findingId}](https://docs.zkao.io/api/operations/getfinding/) POST [/projects/{projectId}/findings/{findingId}/notes](https://docs.zkao.io/api/operations/addfindingnote/) GET [/projects/{projectId}/findings/{findingId}/regression-tests](https://docs.zkao.io/api/operations/listregressiontests/) POST [/projects/{projectId}/findings/{findingId}/regression-tests](https://docs.zkao.io/api/operations/createregressiontest/) GET [/projects/{projectId}/findings/{findingId}/regression-tests/readiness](https://docs.zkao.io/api/operations/getregressiontestreadiness/) GET [/projects/{projectId}/findings/{findingId}/regression-tests/{runId}](https://docs.zkao.io/api/operations/getregressiontest/) POST [/projects/{projectId}/findings/{findingId}/regression-tests/{runId}/retry-publication](https://docs.zkao.io/api/operations/retryregressiontestpublication/) POST [/projects/{projectId}/findings/{findingId}/notes/{noteId}/pin](https://docs.zkao.io/api/operations/pinfindingnote/) PATCH [/projects/{projectId}/findings/{findingId}/severity](https://docs.zkao.io/api/operations/updatefindingseverity/) PATCH [/projects/{projectId}/findings/{findingId}/resolution](https://docs.zkao.io/api/operations/updatefindingresolution/) PATCH [/projects/{projectId}/findings/{findingId}/triage](https://docs.zkao.io/api/operations/overridefindingtriage/) GET [/projects/{projectId}/agent-questions](https://docs.zkao.io/api/operations/listagentquestions/) POST [/projects/{projectId}/agent-questions/{questionId}/answer](https://docs.zkao.io/api/operations/answeragentquestion/) --- Source: https://docs.zkao.io/api/operations/tags/publishing/ # Overview ## Publishing Publish findings and scans as public artifacts ## Operations POST [/projects/{projectId}/findings/{findingId}/publish](https://docs.zkao.io/api/operations/publishfinding/) POST [/projects/{projectId}/scans/{scanId}/publish](https://docs.zkao.io/api/operations/publishscan/) --- Source: https://docs.zkao.io/api/operations/tags/reports/ # Overview ## Reports Incoming vulnerability reports, and investigating them ## Operations POST [/projects/{projectId}/repositories/{repositoryId}/reports](https://docs.zkao.io/api/operations/submitreport/) GET [/projects/{projectId}/reports](https://docs.zkao.io/api/operations/listreports/) POST [/projects/{projectId}/reports/{publicId}/investigate](https://docs.zkao.io/api/operations/investigatereport/) --- Source: https://docs.zkao.io/api/operations/tags/repositories/ # Overview ## Repositories Project repositories ## Operations GET [/projects/{projectId}/repositories](https://docs.zkao.io/api/operations/listrepositories/) GET [/projects/{projectId}/repositories/{repositoryId}/guidance](https://docs.zkao.io/api/operations/getrepositoryguidance/) PUT [/projects/{projectId}/repositories/{repositoryId}/guidance](https://docs.zkao.io/api/operations/setrepositoryguidance/) GET [/projects/{projectId}/repositories/{repositoryId}/audit-areas](https://docs.zkao.io/api/operations/listauditareas/) POST [/projects/{projectId}/repositories/{repositoryId}/audit-areas](https://docs.zkao.io/api/operations/createauditarea/) DELETE [/projects/{projectId}/repositories/{repositoryId}/audit-areas/{areaKey}](https://docs.zkao.io/api/operations/deleteauditarea/) GET [/projects/{projectId}/repositories/{repositoryId}/continuous-testing](https://docs.zkao.io/api/operations/getcontinuoustesting/) PUT [/projects/{projectId}/repositories/{repositoryId}/continuous-testing](https://docs.zkao.io/api/operations/setcontinuoustesting/) DELETE [/projects/{projectId}/repositories/{repositoryId}/continuous-testing](https://docs.zkao.io/api/operations/removecontinuoustesting/) POST [/projects/{projectId}/repositories/{repositoryId}/continuous-testing/prepare](https://docs.zkao.io/api/operations/preparecontinuoustesting/) --- Source: https://docs.zkao.io/api/operations/tags/scans/ # Overview ## Scans Launch, list, and poll scans ## Operations GET [/projects/{projectId}/scans](https://docs.zkao.io/api/operations/listscans/) POST [/projects/{projectId}/scans](https://docs.zkao.io/api/operations/launchscan/) GET [/projects/{projectId}/scans/{scanId}](https://docs.zkao.io/api/operations/getscan/) POST [/projects/{projectId}/scans/{scanId}/cancel](https://docs.zkao.io/api/operations/cancelscan/) POST [/projects/{projectId}/scans/{scanId}/triage/resume](https://docs.zkao.io/api/operations/resumetriage/) GET [/projects/{projectId}/scans/{scanId}/triage/runs/{runId}](https://docs.zkao.io/api/operations/gettriagerun/) --- Source: https://docs.zkao.io/api/operations/tags/token/ # Overview ## Token The calling token and the project it belongs to ## Operations GET [/token](https://docs.zkao.io/api/operations/gettokeninfo/) --- Source: https://docs.zkao.io/api/operations/updatefindingresolution/ # Change a finding's resolution status PATCH /projects/{projectId}/findings/{findingId}/resolution ```js const url = 'https://zkao.io/api/v1/projects/example/findings/example/resolution'; const options = { method: 'PATCH', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"resolutionStatus":"NOT_STARTED","note":{"content":"example","existingNoteId":"example"},"reason":"fixed_in_code"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request PATCH \ --url https://zkao.io/api/v1/projects/example/findings/example/resolution \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "resolutionStatus": "NOT_STARTED", "note": { "content": "example", "existingNoteId": "example" }, "reason": "fixed_in_code" }' ``` * Production`zkao.io/api/v1/projects/{projectId}/findings/{findingId}/resolution` * Staging`staging.zkao.io/api/v1/projects/{projectId}/findings/{findingId}/resolution` Requires scope: `findings:write`. On a finding triage dismissed (`triageStatus` `FALSE_POSITIVE`), any status other than `FALSE_POSITIVE` or `DUPLICATE` reopens it: its `triageStatus` becomes `CONFIRMED` and the override fields record who did it. `NOT_STARTED` reopens it even when that is already its resolution. Setting `FALSE_POSITIVE` on a reopened finding undoes the reopen: the triage verdict comes back, the override is cleared, and the resolution returns to `NOT_STARTED`. The response carries the stored statuses. ## Authorizations * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **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. ## Request Bodyrequired application/json object * **resolutionStatus** required string Allowed values: NOT_STARTED IN_PROGRESS RESOLVED WONT_FIX MITIGATED FALSE_POSITIVE DUPLICATE * **note** Optionally attach or reuse a note alongside a resolution change. object * **content** Create a new note with this body. string * **existingNoteId** Reuse an existing note by id. string * **reason** Short code for why a finding is being closed, chosen from the set offered for the `resolutionStatus` it is sent with; a code belonging to a different status is rejected with 400. Ignored for the open statuses (`NOT_STARTED`, `IN_PROGRESS`) and when `note` is also given. It is not stored as a field: it is recorded as a comment on the finding stating what was chosen, which is returned by the notes endpoints. Codes per status. `RESOLVED`: fixed_in_code, fixed_upstream, code_removed. `MITIGATED`: compensating_control, limited_exposure, monitored. `FALSE_POSITIVE`: not_reachable, guarded_elsewhere, intended_behavior, misread_code, bad_assumption. `WONT_FIX`: risk_accepted, out_of_scope, not_worth_fixing, code_being_removed. `DUPLICATE`: duplicate_of_finding, same_root_cause. string Allowed values: fixed_in_code fixed_upstream code_removed compensating_control limited_exposure monitored not_reachable guarded_elsewhere intended_behavior misread_code bad_assumption risk_accepted out_of_scope not_worth_fixing code_being_removed duplicate_of_finding same_root_cause ##### Example ```plaintext not_reachable ``` ## Responses ### 200 OK application/json object * **findingId** required string * **resolutionStatus** required string Allowed values: NOT_STARTED IN_PROGRESS RESOLVED WONT_FIX MITIGATED FALSE_POSITIVE DUPLICATE * **triageStatus** required The triage status after the change. It moves when the change reopens a finding triage dismissed, or undoes that reopen. string Allowed values: PENDING NEW DUPLICATE RECURRING CONFIRMED FALSE_POSITIVE INCONCLUSIVE ##### Example ```json { "resolutionStatus": "NOT_STARTED", "triageStatus": "PENDING" } ``` ### 400 Invalid request application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 Resource not in this token’s project or repo allowlist application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 409 A compare-and-set (`expectedContent`) missed: the guidance changed since it was read. Re-read the current guidance and retry. application/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 ```json { "error": { "code": "unauthorized" } } ``` --- Source: https://docs.zkao.io/api/operations/updatefindingseverity/ # Override (or clear) a finding's severity PATCH /projects/{projectId}/findings/{findingId}/severity ```js const url = 'https://zkao.io/api/v1/projects/example/findings/example/severity'; const options = { method: 'PATCH', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"severity":"CRITICAL"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request PATCH \ --url https://zkao.io/api/v1/projects/example/findings/example/severity \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "severity": "CRITICAL" }' ``` * Production`zkao.io/api/v1/projects/{projectId}/findings/{findingId}/severity` * Staging`staging.zkao.io/api/v1/projects/{projectId}/findings/{findingId}/severity` Requires scope: `findings:write`. Set `severity` to null to clear the override. ## Authorizations * **[bearerAuth](https://docs.zkao.io/api/#bearerauth)** ## Parameters ### Path Parameters * **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. ## Request Bodyrequired application/json object * **severity** required One of: string string Allowed values: CRITICAL HIGH MEDIUM LOW INFO null null ## Responses ### 200 OK application/json object * **findingId** required string * **userSeverity** One of: string string Allowed values: CRITICAL HIGH MEDIUM LOW INFO null null * **effectiveSeverity** required string Allowed values: CRITICAL HIGH MEDIUM LOW INFO ##### Example ```json { "userSeverity": "CRITICAL", "effectiveSeverity": "CRITICAL" } ``` ### 400 Invalid request application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 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 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 ```json { "error": { "code": "unauthorized" } } ``` ### 403 The token lacks the required scope application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 Resource not in this token’s project or repo allowlist application/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 ```json { "error": { "code": "unauthorized" } } ``` ### 409 A compare-and-set (`expectedContent`) missed: the guidance changed since it was read. Re-read the current guidance and retry. application/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 ```json { "error": { "code": "unauthorized" } } ``` --- Source: https://docs.zkao.io/authentication/ # Authentication Every call to the zkao API uses a **project API token**. A token belongs to exactly one project. It carries a set of scopes and can be narrowed further to some repositories, an expiry date, and a spend limit. There are two ways to get one: approve the CLI in your browser, or create a token by hand. ## Browser approval ```bash zkao login ``` The CLI starts a device authorization flow: 1. It prints a URL and a short code, and opens the URL in your browser. 2. On the **Authorize a CLI** page, you confirm that the code matches the one in your terminal. 3. You pick a project, review the requested scopes, and approve. You can also set a repository allowlist, an expiry, and a spend limit there. 4. The CLI receives the token and saves it to `~/.zkao/config.json`. Only approve a login you started yourself. Approving mints a real token for the project you select. By default the CLI requests `read`, `scans:launch`, `findings:write`, and `guidance:write`. The approval page pre-ticks them, and the approver can change them. To request other scopes, pass `--scope`: ```bash zkao login --scope read publish ``` `zkao login --project ` preselects a project on the approval page. You can approve several projects in one login. Each gets its own saved token, and the first becomes the active project. Use `--no-browser` to print the URL without opening a browser. ### Agents and CI A bare `zkao login` blocks until someone approves in the browser. That can take minutes and trip a command timeout. Non-interactive callers split it in two: ```bash zkao login --no-wait --no-browser # prints the URL and code, then exits # a person opens the URL and approves zkao login --resume # polls once and exits ``` Repeat `zkao login --resume` until it prints `Authorized`. `Still waiting for approval` means nobody has approved yet. `--resume --timeout ` waits up to that long instead of polling once. Several logins can be pending at once. `--resume` finishes whichever is approved first and keeps the rest. A pending login expires after a while. Start a new one when `--resume` reports that it expired. ## Tokens created by hand A project admin can create a token under **Project Settings → Integrations** in the zkao app. Choose a name, the scopes, and optionally a repository allowlist, an expiry, and a spend limit. The token is shown once, together with the project id. It looks like this: ```plaintext zkao_proj__ ``` Store it as a secret. zkao cannot show it again. Hand it to the CLI or SDK through environment variables: ```bash export ZKAO_API_TOKEN=zkao_proj_... export ZKAO_PROJECT_ID= ``` Or save it to the config file: ```bash zkao config set --token zkao_proj_... --project ``` ## Scopes A token carries a subset of these scopes: | Scope | Allows | | ------------------------ | --------------------------------------------------------------------------------------------------------------- | | `read` | List and read repositories, scans, findings, presets, and billing. | | `findings:write` | Comment on findings, change severity and resolution, override the triage verdict, pin a note. | | `guidance:write` | Update a repository’s guidance, manage its audit areas, and answer questions from Continuous Security analyses. | | `scans:launch` | Launch and cancel scans. | | `regression-tests:write` | Generate regression tests and create or retry their pull requests. | | `publish` | Publish a finding or a scan as a public page. | | `advisories:write` | Record which versions a security advisory affects. | | `contacts:read` | Read the advisory contact list. | | `contacts:write` | Add an advisory contact. | | `automations:write` | Select Continuous Security analyses, configure schedules and budgets, and prepare a branch’s next analysis. | A call that needs a scope the token lacks returns `403 forbidden`. The two contact scopes are held apart from the others. That list is who learns about a vulnerability before the public does, so neither `read` nor `advisories:write` reaches it. ## Limits on a token * **Repository allowlist.** The token only sees the listed repositories. An empty list means every repository in the project. * **Expiry.** The token stops working after this date. * **Spend limit.** The most credits the token may commit to scans, triage resumptions, and regression tests in the current billing period. A request past the limit returns `429`. Regression test requests require a token whose creator remains a project admin with verified GitHub write access. The GitHub App must have Contents and Pull requests write permissions for that repository. The default CLI login does not request `regression-tests:write`. Grant it explicitly when you want to create test pull requests. `zkao whoami` (or `GET /token`) returns the token’s project, organization, scopes, allowlist, expiry, and spend limit. Any valid token can call it, whatever its scopes. ## Errors | Status | Meaning | | ------------------ | ---------------------------------------------------------------------------------------------------------- | | `401 unauthorized` | The token is missing, malformed, expired, or revoked. The response does not say which. | | `403 forbidden` | The token is valid but lacks the scope this call needs. | | `404 not_found` | The resource is outside the token’s project or repository allowlist. zkao does not confirm that it exists. | A token used against another project’s id gets a `404` whose message names the token’s own project. Send the token only in the `Authorization: Bearer` header. A token passed in the query string is rejected with `400`. ## Where the CLI stores credentials The CLI writes `~/.zkao/config.json` with owner-only permissions. It keeps one token per project, so logging in to a second project does not drop the first. ```bash zkao config show # active settings and every saved project (tokens masked) zkao config use # switch the active project ``` Settings resolve in this order, highest first: 1. Flags: `--token`, `--project`, `--base-url`. 2. Environment: `ZKAO_API_TOKEN`, `ZKAO_PROJECT_ID`, `ZKAO_URL`. 3. The saved config file. ## Revoking a token Revoke a token under **Project Settings → Integrations**. It stops working at once. A token also stops working when its project or organization is archived. Caution Never commit a token to a repository or paste it into a log. If one leaks, revoke it and create a new one. --- Source: https://docs.zkao.io/environments/ # Environments zkao runs two public environments: | Environment | App | API base | Docs | | ----------- | ----------------- | -------------------------------- | ------------------------------------------------------- | | Production | `zkao.io` | `https://zkao.io/api/v1` | [`docs.zkao.io`](https://docs.zkao.io/) | | Staging | `staging.zkao.io` | `https://staging.zkao.io/api/v1` | [`docs.staging.zkao.io`](https://docs.staging.zkao.io/) | The CLI and SDK target production by default. Staging runs ahead of production and gets new features first. Its data and tokens are separate: a production token does not work on staging. ## `ZKAO_URL` One environment variable, `ZKAO_URL`, points the CLI and SDK at an environment. It accepts any of these forms: ```bash ZKAO_URL=staging.zkao.io ZKAO_URL=https://staging.zkao.io ZKAO_URL=https://staging.zkao.io/api/v1 ``` All three resolve to `https://staging.zkao.io/api/v1`. A bare host gets `https://`. A value that already ends in `/api/v1` is used as is. The CLI’s `--base-url` flag and the SDK’s `baseUrl` option are used verbatim, with no normalization. They win over `ZKAO_URL`. ## The `next` release channel The CLI and SDK ship on two npm dist-tags: * `latest` matches production. * `next` matches staging. Its versions look like `X.Y.Z-next.N`. Install the staging channel when you work against staging: ```bash npm install -g @zksecurity/zkao-cli@next ``` Or pass `--next` to the install script: ```bash curl -fsSL https://raw.githubusercontent.com/zksecurity/zkao-sdk/main/install.sh | bash -s -- --next ``` A CLI from the `next` channel checks the `next` tag for updates, and a `latest` CLI checks `latest`. ## Logging in to staging Set `ZKAO_URL` when you log in: ```bash ZKAO_URL=staging.zkao.io zkao login --project ``` Each saved project remembers the base URL it was approved on. After that, you no longer need `ZKAO_URL` for that project. ## Switching between projects and environments ```bash zkao config show # every saved project, with its base URL zkao config use # make another saved project active ``` Switching to a staging project points the CLI at staging. Switching back to a production project points it at production. To log in to the other environment, pass `ZKAO_URL` again. Without it, `zkao login` targets the active project’s environment. --- Source: https://docs.zkao.io/guides/agents/ # AI agents The zkao skill teaches an agent to drive a project through MCP, the CLI, or HTTP. It covers login, scopes, scans, triage, guidance, credits, and publishing. Claude Code and Codex plugins share the same skill and MCP connection. An agent with the skill can handle requests like “enable formal verification on the main branch with a monthly budget of 500 credits” or “run a diff scan of this change”. ## Install the skill Claude Code The repository is a Claude Code plugin marketplace. Add it, then install the plugin: ```text /plugin marketplace add zksecurity/zkao-sdk /plugin install zkao@zkao ``` Codex Add the repository as a plugin marketplace: ```bash codex plugin marketplace add zksecurity/zkao-sdk ``` Install `zkao` from that marketplace in the desktop app’s Plugins directory. The portable plugin uses the same skill as Claude Code. Other agents Save the skill into your agent’s skills directory: ```bash curl -fsSL https://docs.zkao.io/skill.md -o SKILL.md ``` Agents without a skills system can read the same URL as context. Shell-based agents can use the CLI from the [Quickstart](https://docs.zkao.io/quickstart/). ## Connect with MCP Add `https://zkao.io/api/mcp` as a remote MCP server in your client. It uses Streamable HTTP and OAuth. Follow the client’s sign-in flow to approve a project and its permissions. The plugin manifests configure this endpoint for Claude Code and Codex. You do not need to copy an API token into the plugin. The connection belongs to one project. Use its identity tool to check the project before acting. CLI login and MCP authorization are separate. For staging, configure `https://staging.zkao.io/api/mcp` instead. ## Complete the review After analysis finishes, the agent reads the scan’s `triage` completeness. A `COMPLETED` scan can still have unreviewed findings. Those findings are withheld from results. When triage stopped on budget, the scan offers allowed resumption budgets. The agent can resume within the spending limit you authorized. It reuses the same request key and budget when retrying. It tracks the returned triage run, then checks the scan’s completeness again. See [Resume unfinished triage](https://docs.zkao.io/guides/scans/#resume-unfinished-triage). For fixes, the agent reads the finding’s evidence and verifies the change with a scan or recheck. Further scans and triage require an authorized credit budget. ## Docs for agents Every page on this site has a plain Markdown version for agents. | URL | What it holds | | ---------------------------------------------------------- | -------------------------------------------------------------------------------- | | [`/llms.txt`](https://docs.zkao.io/llms.txt) | An index of the docs, following the [llms.txt](https://llmstxt.org/) convention. | | [`/llms-full.txt`](https://docs.zkao.io/llms-full.txt) | All guides and API reference pages in one file. | | [`/llms-small.txt`](https://docs.zkao.io/llms-small.txt) | A shorter bundle of guides. | | `.md` pages | One page as Markdown. Replace the trailing slash with `.md`. | | [`/openapi/v1.yaml`](https://docs.zkao.io/openapi/v1.yaml) | The full API contract. | Each page also has a **Copy as Markdown** button next to its title. Requests with `Accept: text/markdown` receive Markdown at the normal page URL. ## Logging in from an agent A bare `zkao login` waits for browser approval for minutes. Most agent tool calls time out first. Split the login instead, so no command blocks. 1. Start the login. It prints a URL and a code, then exits. ```bash zkao login --no-wait --no-browser --project ``` `--project` is optional. It preselects the project on the approval page. 2. The agent gives the URL and code to you. You open the URL, check the code, pick the project, and approve. 3. The agent finishes the login. ```bash zkao login --resume ``` Each call returns at once. `Still waiting for approval` means try again later. `Authorized` means the token is saved. Pass `--timeout ` to wait up to that long in one call. You can approve several projects in one login. Each one gets its own saved token. `zkao config use ` switches between them. Caution Only approve a login you started. Approving mints a real API token for the project you pick. Revoke it any time under **Project Settings → Integrations**. For unattended agents, create a token by hand instead and pass it through `ZKAO_API_TOKEN` and `ZKAO_PROJECT_ID`. See [Authentication](https://docs.zkao.io/authentication/). ## Keeping the skill current The CLI checks npm for a newer release at most once a day. When one exists, every command prints a notice on stderr: ```text zkao: version X.Y.Z is available (running A.B.C). Update with `npm install -g @zksecurity/zkao-cli`. If you are an agent working from a zkao skill file, update that too: it may describe fewer commands than the API now offers. ``` The notice never touches stdout, so piping output to `jq` keeps working. An agent that sees it should update the CLI and fetch the skill again. Set `ZKAO_NO_UPDATE_CHECK=1` to turn the check off. --- Source: https://docs.zkao.io/guides/credits/ # Credits and usage zkao is pay as you go. You buy credits, and scans spend them. Credits are the only unit the API uses. ## Where the balance lives Every project belongs to an organization. The organization holds one prepaid balance. All of its projects share it. A project token still sees one project. The billing endpoints report the organization’s balance as seen from that project. Usage and monthly spend cover only that project’s activity. Credits are bought in the zkao app, not over the API. ## What a scan reserves A launch reserves the scan’s full budget from the balance. The scan then spends only what its analysis uses, never more than the budget. When it finishes, the unused part is released. A cancelled scan releases its reservation too. So the balance has three numbers: | Field | Meaning | | ------------------ | -------------------------------------------------------------------- | | `balanceCredits` | The organization’s total prepaid balance. | | `reservedCredits` | Credits held by the organization’s queued and running scans. | | `availableCredits` | The balance minus reservations. This is what a new scan can reserve. | Active scans in other projects of the organization reduce `availableCredits` too. ## Check the balance CLI ```bash zkao billing balance ``` TypeScript ```ts const { availableCredits, organization } = await zkao.getBillingBalance(); ``` curl ```bash curl -H "Authorization: Bearer $ZKAO_API_TOKEN" \ https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/billing/balance ``` The response names the organization that owns the balance. Check `availableCredits` before choosing a budget. ## When credits run out A launch whose budget the balance cannot cover fails with `402 insufficient_credits`. Add credits in the app, or launch with a smaller budget. Reading the balance and usage keeps working with an empty balance. A token can also carry its own spend limit, set when it was created. `zkao whoami` shows it as `spendLimitCredits`. A launch past that limit fails with `429 rate_limited`. ## Read the usage ledger The ledger lists every credit movement attributed to the project. Each event has a signed `credits` value. Negative means spent, positive means added or refunded. | Type | Meaning | | ------------------ | -------------------------------------------- | | `SCAN_DEDUCTION` | Credits a scan spent. | | `SCAN_REFUND` | Credits returned to the balance from a scan. | | `PURCHASE` | Credits bought. | | `STRIPE_REFUND` | A purchase refunded. | | `ADMIN_ADJUSTMENT` | A manual adjustment by zkao. | CLI ```bash zkao billing usage zkao billing usage --from 2026-09-01 --to 2026-10-01 --limit 200 ``` TypeScript ```ts const { from, to, events } = await zkao.getBillingUsage({ from: "2026-09-01T00:00:00Z", }); ``` curl ```bash curl -H "Authorization: Bearer $ZKAO_API_TOKEN" \ "https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/billing/usage?from=2026-09-01T00:00:00Z" ``` The default range is the last 30 days. The response echoes the range it used. Events come newest first, up to 1,000. Movements made outside any project, such as an organization top-up, are not listed. ## Monthly summary The summary gives net credits spent on scans and net credits purchased, per calendar month in UTC. Months come newest first, and quiet months show zeros. Ask for up to 24 months. CLI ```bash zkao billing summary --months 6 ``` TypeScript ```ts const months = await zkao.getBillingSummary({ months: 6 }); ``` curl ```bash curl -H "Authorization: Bearer $ZKAO_API_TOKEN" \ "https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/billing/summary?months=6" ``` Note All billing endpoints need only the `read` scope. --- Source: https://docs.zkao.io/guides/diff-scans/ # Diff scans A diff scan audits one change instead of the whole repository. It reads the code that changed between a base and a head commit. The rest of the repository is context, not a target. That makes it cheap and fast. ## How the change is measured * The **head** is the commit you scan. Set it with `commitHash` or `branch`, as for any scan. * The **base** is what the change is measured from. It can be a commit SHA, a branch, or a tag. zkao compares the two on GitHub and audits the change from their merge base to the head. The scan records that merge base SHA as its `baseCommit`. So a base branch that moved on since you branched off does not pull its new commits into the diff. ## Launch a diff scan 1. Push the head commit to GitHub. zkao reads both commits from there. 2. Launch with a diff preset and a base. `builtin:Flash Diff` is the cheap one. `builtin:Max Diff` runs every technique on flagship models. 3. Wait for it, as for any scan. See [Run scans](https://docs.zkao.io/guides/scans/#follow-a-scan). CLI ```bash zkao scans launch --repo --preset "builtin:Flash Diff" \ --base main --commit zkao scans wait ``` TypeScript ```ts const { scanId } = await zkao.launchScan({ repositoryId: repoId, presetRef: "builtin:Flash Diff", baseCommit: "main", commitHash: headSha, }); const scan = await zkao.waitForScan(scanId); ``` curl ```bash curl -X POST -H "Authorization: Bearer $ZKAO_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"repositoryId":"","presetRef":"builtin:Flash Diff","baseCommit":"main","commitHash":""}' \ https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/scans ``` Confirm the preset ref with `zkao presets`. The budget works as for any scan. Leave it out to use the recommended budget. It is sized from the change, up to three times the preset’s minimum. When no earlier scan of the repository built its overview, the diff scan builds one first. That scan takes longer, and its minimum and recommended budgets are higher. The launch response then sets `buildsOverview` to `true`. You can also give a diff scan per-scan guidance. ## Diff scan errors Only a diff scan preset takes a base, and it always needs one. | Status | Code | Cause | | ------ | ----------------------- | --------------------------------------------------------------------------------- | | `400` | `diff_base_required` | A diff scan was launched without a base. | | `400` | `diff_base_not_allowed` | A base was sent with a preset that is not a diff scan. | | `400` | `diff_base_invalid` | The base is not a valid name, does not exist, or shares no history with the head. | | `422` | `diff_empty` | The head changes nothing since the base. There is nothing to audit. | The message says which case applies. A failed comparison on GitHub’s side returns `400 bad_request`. That one is transient, so retry it later. ## Run diff scans in CI Diff scans fit pull requests. Use the pull request’s base branch as the base and its head commit as the head. The [zkao GitHub Action](https://docs.zkao.io/guides/github-action/) does this for you with `scan: flash` or `scan: max`. It picks the pull request’s base, or the commit before a push. It can also fail the job when the scan finds issues above a severity. Tip After a complex change to cryptographic code, a diff scan is a cheap second look before merging. --- Source: https://docs.zkao.io/guides/findings/ # Triage findings A finding is one issue a scan reported. Each finding carries two separate statuses. * `triageStatus` is zkao’s own verdict on the finding. You can [override it](https://docs.zkao.io/guides/findings/#override-the-triage-verdict) when you disagree. * `resolutionStatus` is your team’s decision about it. You set it. Reading findings needs the `read` scope. Review decisions need `findings:write`. Regression test requests need `regression-tests:write`. ## List findings The list holds every finding in the project, most severe first. Filter it to one scan with its id. CLI ```bash zkao findings list zkao findings list --scan --limit 100 ``` TypeScript ```ts const { items, total } = await zkao.listFindings({ scanId, limit: 100 }); ``` curl ```bash curl -H "Authorization: Bearer $ZKAO_API_TOKEN" \ "https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/findings?scanId=&limit=100" ``` The list paginates with `page` and `limit`. The default limit is 50 and the maximum is 100. Each item has these fields. | Field | Meaning | | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `title`, `location`, `category` | What the issue is and where. | | `severity` | The effective severity: your override if set, otherwise zkao’s. | | `triageStatus` | zkao’s verdict, such as `CONFIRMED`, `FALSE_POSITIVE` or `DUPLICATE`. | | `confirmationEvidence` | For a `CONFIRMED` finding, `POC` when a proof of concept ran, or `ANALYSIS` when code analysis alone confirmed it. | | `resolutionStatus` | Your team’s decision. New findings start at `NOT_STARTED`. | | `notesCount` | How many comments the finding has. | | `source` | Where the finding was found: `kind` names the kind of scan, such as `continuous-security`, `pr-review` or `max`, and `branch` is the branch it scanned. Treat an unknown `kind` like `other`. | See [List findings](https://docs.zkao.io/api/operations/listfindings/) for the full schema. ## Read one finding The detail view adds the description, impact, recommendation, commit, repository, and comments. CLI ```bash zkao findings get ``` TypeScript ```ts const finding = await zkao.getFinding(findingId); console.log(finding.description, finding.recommendation, finding.notes); ``` curl ```bash curl -H "Authorization: Bearer $ZKAO_API_TOKEN" \ https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/findings/ ``` ### `ZK-` labels A finding page on zkao shows a short label such as `ZK-3f9a2c1b`. It is the last eight characters of the finding id. Every finding endpoint accepts it in place of the full id, with or without the `ZK-` prefix. A label is unique within a project in practice, but not by construction. A label that matches two findings returns `409`. Use the full id then. ## Regression tests Request a minimal regression test for a confirmed finding. The test replays a fixed counterexample using the repository’s own test framework. It asserts the intended secure behavior, so it fails against vulnerable code. If the target revision still has the bug, the test-only pull request needs a fix before it can pass. The token needs `read` for readiness and status calls. It needs `regression-tests:write` to request a test or retry publication. Its creator must remain a project admin with verified GitHub write access. The GitHub App must have Contents and Pull requests write permissions for the repository. The readiness response names missing setup and provides an installation settings link when available. ```ts const readiness = await zkao.getRegressionTestReadiness(findingId); if (readiness.status !== "ready") throw new Error(readiness.message); const { run } = await zkao.createRegressionTest( findingId, { creditBudget: 100, targetBranch: "main" }, { idempotencyKey: "one-regression-test-request" }, ); const current = await zkao.getRegressionTest(findingId, run.id); console.log(current.status, current.pullRequestUrl); ``` The equivalent HTTP request is: ```bash curl -X POST -H "Authorization: Bearer $ZKAO_API_TOKEN" \ -H "Content-Type: application/json" -H "Idempotency-Key: one-regression-test-request" \ -d '{"creditBudget":100,"targetBranch":"main"}' \ "https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/findings/$FINDING_ID/regression-tests" ``` Launch returns `202` with `run` and `replayed`. Omit `targetBranch` to use the repository’s default branch. The request pins that branch’s commit and reserves its own credit budget. Project and token spending limits include this budget. Reuse the same key, budget, and branch after an uncertain response. The API returns the original attempt without another reservation. Follow the run with `getRegressionTest`, separately from its source scan. `listRegressionTests(findingId)` returns the latest attempts. `PUBLISHED` includes the draft pull request URL. `BLOCKED` means a suitable test could not be verified. `FAILED` means generation failed. `PUBLICATION_FAILED` means the generated test was retained but opening its pull request failed. Retry that publication without another generation budget: ```ts await zkao.retryRegressionTestPublication(findingId, run.id); ``` The HTTP endpoint is `POST /projects/{projectId}/findings/{findingId}/regression-tests/{runId}/retry-publication`. It takes no body and returns `202` with the run. Generation failures require a new paid attempt. ## Comment A comment is a Markdown note on the finding. Your team sees it on zkao. CLI ```bash zkao findings comment "Reproduced on the release branch." ``` TypeScript ```ts const { noteId } = await zkao.addFindingNote(findingId, "Reproduced on the release branch."); ``` curl ```bash curl -X POST -H "Authorization: Bearer $ZKAO_API_TOKEN" -H "Content-Type: application/json" \ -d '{"content":"Reproduced on the release branch."}' \ https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/findings//notes ``` The response returns the new `noteId`. You can pin that note as the finding’s resolution note with [Pin a note](https://docs.zkao.io/api/operations/pinfindingnote/) or the SDK’s `pinFindingNote`. ## Override severity The levels are `CRITICAL`, `HIGH`, `MEDIUM`, `LOW` and `INFO`. Clearing the override restores zkao’s severity. CLI ```bash zkao findings severity LOW zkao findings severity none # clear the override ``` TypeScript ```ts await zkao.setFindingSeverity(findingId, "LOW"); await zkao.setFindingSeverity(findingId, null); // clear the override ``` curl ```bash curl -X PATCH -H "Authorization: Bearer $ZKAO_API_TOKEN" -H "Content-Type: application/json" \ -d '{"severity":"LOW"}' \ https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/findings//severity ``` ## Override the triage verdict Replace zkao’s verdict with `CONFIRMED` or `FALSE_POSITIVE`. Setting the AI’s own verdict again clears the override. A note is added to the finding as a comment. CLI ```bash zkao findings triage false-positive \ --note "The caller checks the length before this point." ``` TypeScript ```ts await zkao.overrideFindingTriage(findingId, "FALSE_POSITIVE", { note: "The caller checks the length before this point.", }); ``` curl ```bash curl -X PATCH -H "Authorization: Bearer $ZKAO_API_TOKEN" -H "Content-Type: application/json" \ -d '{"triageStatus":"FALSE_POSITIVE","note":"The caller checks the length before this point."}' \ https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/findings//triage ``` The response returns `triageStatus`, `previousTriageStatus`, and the comment’s `noteId`. The triage verdict is separate from the resolution status. Set the resolution to record what your team does about the finding. ## Set a resolution | Status | Meaning | | ---------------- | ----------------------------------- | | `NOT_STARTED` | Nobody has looked at it yet. | | `IN_PROGRESS` | Someone is working on it. | | `RESOLVED` | Fixed. | | `MITIGATED` | Not fixed, but its risk is reduced. | | `WONT_FIX` | Accepted as is. | | `FALSE_POSITIVE` | Not a real issue. | | `DUPLICATE` | Already covered by another finding. | A status alone records the outcome, not the reason. Attach the reason in the same call, in one of two ways. * `note` is free text. It becomes a comment on the finding. * `reason` is a short code from a fixed catalog. It is also recorded as a comment. Pass one or the other. When both are present, the note wins. Both are ignored for `NOT_STARTED` and `IN_PROGRESS`. CLI ```bash zkao findings resolution FALSE_POSITIVE \ --note "The caller checks the length before this point." zkao findings resolution WONT_FIX --reason risk_accepted ``` TypeScript ```ts await zkao.setFindingResolution(findingId, "FALSE_POSITIVE", { note: { content: "The caller checks the length before this point." }, }); await zkao.setFindingResolution(findingId, "WONT_FIX", { reason: "risk_accepted" }); ``` curl ```bash curl -X PATCH -H "Authorization: Bearer $ZKAO_API_TOKEN" -H "Content-Type: application/json" \ -d '{"resolutionStatus":"WONT_FIX","reason":"risk_accepted"}' \ https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/findings//resolution ``` Over HTTP, `note` can also reuse an existing comment: `{"existingNoteId": ""}`. ### Reason codes Each status offers its own codes. A code from another status returns `400` with the valid list. | Status | Codes | | ---------------- | ------------------------------------------------------------------------------------------- | | `RESOLVED` | `fixed_in_code`, `fixed_upstream`, `code_removed` | | `MITIGATED` | `compensating_control`, `limited_exposure`, `monitored` | | `FALSE_POSITIVE` | `not_reachable`, `guarded_elsewhere`, `intended_behavior`, `misread_code`, `bad_assumption` | | `WONT_FIX` | `risk_accepted`, `out_of_scope`, `not_worth_fixing`, `code_being_removed` | | `DUPLICATE` | `duplicate_of_finding`, `same_root_cause` | Tip Prefer a note when the reasoning has any detail worth keeping. A code alone loses it. ## A triage pass 1. Find the latest completed scan. ```bash zkao scans list ``` 2. List its findings. ```bash zkao findings list --scan ``` 3. Read each one in full, including the proof of concept. ```bash zkao findings get ``` 4. Record the verdict, with the reason. ```bash zkao findings severity MEDIUM zkao findings resolution RESOLVED --reason fixed_in_code ``` Some knowledge applies to the whole repository, not one finding. A known non-issue is one example. A comment does not carry it into future scans. Put it in the [repository guidance](https://docs.zkao.io/guides/guidance/) instead. --- Source: https://docs.zkao.io/guides/github-action/ # GitHub Action The [`zksecurity/zkao-action`](https://github.com/zksecurity/zkao-action) action scans the commit a workflow runs on. By default it starts the scan and returns. It can also wait, write the findings to the job summary, and fail the job on severe findings. The action needs no checkout. zkao reads the commit from GitHub itself. ## Before you start 1. Add the repository to a zkao project. A scan needs at least one project member with GitHub access to the repository. 2. Create a project API token with the `read` and `scans:launch` scopes. See [Authentication](https://docs.zkao.io/authentication/). 3. In the GitHub repository settings, store the token as the secret `ZKAO_API_TOKEN`. Store the project id as the variable `ZKAO_PROJECT_ID`. 4. Keep credits on the organization. A scan reserves its budget at launch. See [Credits](https://docs.zkao.io/guides/credits/). ## Scan every push to main ```yaml name: zkao on: push: branches: [main] jobs: scan: runs-on: ubuntu-latest steps: - uses: zksecurity/zkao-action@v1 with: token: ${{ secrets.ZKAO_API_TOKEN }} project: ${{ vars.ZKAO_PROJECT_ID }} ``` This launches a Flash scan of the change in each push and moves on. The results are on zkao when the scan finishes. Tip `@v1` follows every `v1.x` release. To pin an exact version, use a full commit SHA instead. ## Gate pull requests on a diff scan `scan: flash` audits only the change a pull request makes, with one focused analysis led by a flagship model. It is cheap and fast. `scan: max` runs every technique on the change, on flagship models. In `gate` mode, the job fails when open findings reach `fail-on`. ```yaml name: zkao on: pull_request: jobs: scan: runs-on: ubuntu-latest steps: - uses: zksecurity/zkao-action@v1 with: token: ${{ secrets.ZKAO_API_TOKEN }} project: ${{ vars.ZKAO_PROJECT_ID }} scan: flash mode: gate fail-on: high ``` The diff runs from the merge base of `base` to the scanned commit. `base` defaults to the pull request’s base, or to the commit before a push. The rest of the repository is context, not a target. See [Diff scans](https://docs.zkao.io/guides/diff-scans/). On `pull_request` and `pull_request_target` events, the action scans the head of the pull request. On every other event it scans `github.sha`. ## Comment on the pull request `comment: true` posts to the pull request twice: once when the scan starts, and again with the result when the job waits for it. Both carry a link to the scan. The job needs `pull-requests: write`. ```yaml name: zkao on: pull_request: permissions: contents: read pull-requests: write jobs: scan: runs-on: ubuntu-latest steps: - uses: zksecurity/zkao-action@v1 with: token: ${{ secrets.ZKAO_API_TOKEN }} project: ${{ vars.ZKAO_PROJECT_ID }} scan: flash mode: wait comment: true ``` The result comment carries counts and a link, never the findings themselves. On a public repository, spelling them out would disclose unfixed vulnerabilities to anyone who can read the pull request. Comments are posted by `github-actions[bot]`, since the action uses the workflow’s own token. To post under your own bot, mint a GitHub App installation token in an earlier step and pass it as `github-token`. Note A push carries no pull request. When the pushed branch has one open, the action finds it and comments there anyway. ## Run a scan from a comment Trigger on `issue_comment` and the action takes commands from the pull request itself. ```yaml name: zkao on: issue_comment: types: [created] permissions: contents: read pull-requests: write jobs: scan: if: github.event.issue.pull_request && contains(github.event.comment.body, '/zkao') runs-on: ubuntu-latest steps: - uses: zksecurity/zkao-action@v1 with: token: ${{ secrets.ZKAO_API_TOKEN }} project: ${{ vars.ZKAO_PROJECT_ID }} scan: flash mode: wait comment: true ``` | Comment | What happens | | ---------------- | ------------------------------------------------------------------------ | | `/zkao scan` | Audits the pull request’s change, with the kind the workflow configures. | | `/zkao scan max` | Audits it as `flash` or `max` instead. | | `/zkao help` | Posts the usage. No scan. | | `/zkao` | Posts the usage, rather than scanning. | The handle is slash-prefixed rather than `@zkao`, because GitHub turns an `@handle` into a link to whoever owns that account and notifies them, and `zkao` belongs to someone else. A leading slash on the command itself is optional, so `/zkao scan` and `/zkao /scan` mean the same thing. A word after `scan` that is not a kind is ignored, so `/zkao scan this one` runs the workflow’s own kind rather than failing over a word nobody meant as a preset. Set `mention` to an `@handle` you own and it still works. There an unrecognised word after the handle is left alone rather than answered, since it may be ordinary prose. Caution A workflow triggered by `issue_comment` only ever runs from the repository’s **default branch**. On any other branch GitHub never dispatches it, and nothing happens with no error to explain it. The default branch is also where the comment event reads the workflow from, so the commit under test comes from the pull request, not from `github.sha`. Only the repository’s owner, members and collaborators can start a scan this way. Comments from anyone else are ignored, so a passer-by cannot spend the project’s credits. Change the handle with the `mention` input. ## Modes | `mode` | What happens | | ------------------ | ----------------------------------------------------------------------------------------------------------- | | `launch` (default) | Starts the scan and returns. The job never waits or fails on findings. | | `wait` | Waits for the scan and writes the findings to the job summary. The job fails only if the scan itself fails. | | `gate` | Waits, reports, and fails the job when open findings reach `fail-on`. | ## What to run | `scan` | Runs | | ----------------- | ------------------------------------------------------------------------------------------------------------ | | `flash` (default) | Only the change since `base`, with one focused analysis led by a flagship model. | | `max` | Only the change since `base`, with every technique on flagship models. | | a preset ref | That preset, such as `builtin:Max` for the whole repository, or a custom one. List refs with `zkao presets`. | The older words still work. `diff` runs `flash`. `rapid-review` and `quick-look` run `builtin:Flash`. `deep-audit` runs `builtin:Max`. ## Inputs | Input | Default | What it does | | --------------- | ----------------- | ------------------------------------------------------------------------------------------------------------- | | `token` | required | Project API token. Use a secret. | | `project` | required | The zkao project id. | | `budget` | recommended | Credit budget for the scan. Defaults to what zkao recommends for this scan type on this repository. | | `mode` | `launch` | `launch`, `wait`, or `gate`. | | `scan` | `flash` | `flash`, `max`, or a preset ref. | | `base` | see above | For `scan: flash` or `scan: max`, the commit the change is measured from. | | `fail-on` | `high` | For `mode: gate`, the severity that fails the job: `critical`, `high`, `medium`, `low`, or `info`. | | `repository` | matched by name | The zkao repository id. By default, the project repository whose owner and name match this GitHub repository. | | `commit` | see above | Commit to scan. | | `branch` | workflow branch | Branch the commit is on. | | `areas` | whole repository | Comma-separated audit area keys to scope a scan of the code to. A scan of a change takes none. | | `guidance-file` | none | A file whose content replaces the repository’s guidance for this scan. | | `timeout` | `10800` | Seconds to wait in `wait` and `gate` modes. The scan keeps running on zkao after a timeout. | | `summary` | `true` | Write the scan link, and the findings once waited for, to the job summary. | | `comment` | `false` | Comment on the pull request when the scan starts and when it finishes. Needs `pull-requests: write`. | | `mention` | `/zkao` | What a comment says to reach zkao. | | `github-token` | the workflow’s | Token used to comment, and to read the pull request on an `issue_comment` event. | | `base-url` | `https://zkao.io` | The zkao instance. | | `cli-version` | pinned | Version of `@zksecurity/zkao-cli` the action runs. | ## Outputs | Output | Meaning | | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | `scan-id` | Id of the launched scan. | | `scan-url` | The scan on zkao. | | `status` | `QUEUED` in `launch` mode. `COMPLETED`, `FAILED` or `CANCELLED` once waited for. | | `findings-total` | Open findings, excluding false positives and duplicates. Empty in `launch` mode. | | `findings-critical`, `findings-high`, `findings-medium`, `findings-low`, `findings-info` | Open findings by severity. | Use them in later steps: ```yaml - uses: zksecurity/zkao-action@v1 id: zkao with: token: ${{ secrets.ZKAO_API_TOKEN }} project: ${{ vars.ZKAO_PROJECT_ID }} mode: wait - run: echo "${{ steps.zkao.outputs.findings-total }} open findings at ${{ steps.zkao.outputs.scan-url }}" ``` ## Keeping the cost in check A full scan on every push adds up. These keep it down. * Run on `pull_request`, or on `main` only. * Use `scan: flash` for pull requests. * Pass `areas` to scan only the audit areas a change touches. List area keys with `zkao areas list `. * Set `budget` to cap each scan. A scan of a repository zkao is still analyzing waits for that analysis to finish first. ## How it works The action is a composite step. It runs the published [`@zksecurity/zkao-cli`](https://www.npmjs.com/package/@zksecurity/zkao-cli) against the public API. The runner needs `node` and `jq`, which every GitHub-hosted runner has. --- Source: https://docs.zkao.io/guides/guidance/ # Repository guidance Guidance tells zkao what matters in your code. It covers scope, attacker powers, trusted components, security properties, severity expectations, and accepted risks. Good guidance makes scans sharper and cuts false positives. ## Three layers Guidance can come from three places. They stack, and a later layer can refine an earlier one. 1. **A committed `zkao.md`** at the repository root. It ships with your code and is read at the scanned commit. It changes only when you commit a change. 2. **Repository guidance**, stored in zkao. It applies to every scan of the repository without touching the code. This page is about this layer. 3. **Scan guidance**, sent with one launch. It replaces repository guidance for that scan only. See [Guide one scan](https://docs.zkao.io/guides/scans/#guide-one-scan). Repository guidance is the right home for a repository you do not control. It also suits knowledge you do not want to commit. Guidance is a strong steer, not an access-control boundary or a guaranteed file filter. To limit what a scan audits, scope it to [audit areas](https://docs.zkao.io/guides/scans/#scope-a-scan-to-audit-areas). ## Read guidance CLI ```bash zkao guidance get ``` TypeScript ```ts const { content, updatedAt } = await zkao.getRepositoryGuidance(repoId); ``` curl ```bash curl -H "Authorization: Bearer $ZKAO_API_TOKEN" \ https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/repositories//guidance ``` `content` is `null` when no guidance is set. Reading needs the `read` scope. The committed `zkao.md` is not part of this response. ## Set or clear guidance Writing needs the `guidance:write` scope. Each change records a revision. Writing the content already stored is a no-op that returns `unchanged: true`. Guidance is limited to 100,000 characters. CLI ```bash zkao guidance set guidance.md cat guidance.md | zkao guidance set - zkao guidance clear ``` TypeScript ```ts const current = await zkao.getRepositoryGuidance(repoId); await zkao.setRepositoryGuidance(repoId, newContent, { expectedContent: current.content, }); // Clear it. await zkao.setRepositoryGuidance(repoId, null); ``` curl ```bash curl -X PUT -H "Authorization: Bearer $ZKAO_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"content":"# Scope\nAudit src/verifier only.","expectedContent":null}' \ https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/repositories//guidance ``` ### Avoid overwriting a concurrent edit Teammates, and accepted suggestions in the app, also edit guidance. `expectedContent` protects you from clobbering their change. * Send the content you last read, or `null` if none was set. * If the stored guidance changed since then, the write fails with `409 conflict`. * Read it again, merge your change, and retry. * Leave `expectedContent` out for last writer wins. The CLI does the compare-and-set for you. `zkao guidance set` and `zkao guidance clear` read the current guidance first and send it as `expectedContent`. Pass `--force` to skip that check and overwrite. Note Edit guidance rather than replace it. Read the current text, add your note, and write the merged result back. ## Keep it lean Every line is read on every scan. A short file the analysis takes in beats a long one it skims. Use repository-relative paths. Never include credentials or secrets. Put durable facts in repository guidance or `zkao.md`. Put a one-off focus in scan guidance instead. Triage often surfaces knowledge that applies to the whole repository, such as a known non-issue. A comment on one finding does not carry it forward, but guidance does. --- Source: https://docs.zkao.io/guides/publishing/ # Publish results Publishing creates a public page on zkao for one finding or one scan. Anyone with the link can read it. Nothing else in the project becomes visible. Publishing needs the `publish` scope. `zkao login` does not request it by default. Ask for it when you log in: ```bash zkao login --scope read scans:launch findings:write guidance:write publish ``` ## Publish a finding A published finding shows its title, severity, repository, commit, description, impact, and recommendation. You can also attach one of its comments as the team’s public response. Pass that comment’s id as the note. CLI ```bash zkao findings publish zkao findings publish --note --password ``` TypeScript ```ts const { publicId, accessPassword } = await zkao.publishFinding(findingId, { noteId, withPassword: true, }); ``` curl ```bash curl -X POST -H "Authorization: Bearer $ZKAO_API_TOKEN" -H "Content-Type: application/json" \ -d '{"noteId":"","withPassword":true}' \ https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/findings//publish ``` The note must belong to the finding. Another finding’s note returns `400`. The finding id also accepts a [`ZK-` label](https://docs.zkao.io/guides/findings/#zk--labels). ## Publish a scan A published scan lists the scan’s reported findings, most severe first. It covers the findings zkao confirmed, and those it marked as needing review. Only a `COMPLETED` scan can be published. CLI ```bash zkao scans publish zkao scans publish --password ``` TypeScript ```ts const { publicId, accessPassword } = await zkao.publishScan(scanId, { withPassword: true }); ``` curl ```bash curl -X POST -H "Authorization: Bearer $ZKAO_API_TOKEN" -H "Content-Type: application/json" \ -d '{"withPassword":true}' \ https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/scans//publish ``` ## The result Both calls return the same shape. ```json { "artifactId": "…", "publicId": "…", "accessPassword": null } ``` The public page lives at one of these URLs. * `https://zkao.io/public/findings/` * `https://zkao.io/public/scans/` ## Password protection With `withPassword`, zkao generates a password and returns it as `accessPassword`. Visitors must enter it to read the page. Share it separately from the link. Caution Publishing again keeps the same link, but resets the options. A call without `withPassword` removes the password. A call with it generates a new one. For a finding, a call without a note removes the public response. ## Unpublishing The API publishes but does not unpublish. Unpublish a page from the finding or scan on zkao. See [Publish a finding](https://docs.zkao.io/api/operations/publishfinding/) and [Publish a scan](https://docs.zkao.io/api/operations/publishscan/) for the full schemas. --- Source: https://docs.zkao.io/guides/scans/ # Run scans A scan audits one commit of one repository. You choose the scan type and a credit budget. zkao reserves the budget, runs the analysis, and records findings on the project. The TypeScript examples use a client created as shown in the [SDK reference](https://docs.zkao.io/reference/sdk/). The curl examples assume `ZKAO_API_TOKEN` and `ZKAO_PROJECT_ID` are set. ## The flow 1. Find the repository and check that it is ready. 2. Pick a scan type (a preset). 3. Launch the scan with a budget. 4. Wait for it to finish. 5. Read its findings. See [Triage findings](https://docs.zkao.io/guides/findings/). ## Find a repository List the repositories in the project. A token restricted to some repositories only sees those. CLI ```bash zkao repos ``` TypeScript ```ts const repositories = await zkao.listRepositories(); ``` curl ```bash curl -H "Authorization: Bearer $ZKAO_API_TOKEN" \ https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/repositories ``` Each repository has a `readiness` field. A repository added moments ago is `analyzing`. zkao makes a one-time pass over it first, and that pass costs no credits. A launch during that pass fails with `409 repository_initializing`. Wait for `ready` instead of retrying the launch. CLI ```bash zkao repos:wait ``` TypeScript ```ts await zkao.waitForRepositoryReady(repoId); ``` curl ```bash # Poll until the repository reports "readiness": "ready". curl -H "Authorization: Bearer $ZKAO_API_TOKEN" \ https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/repositories ``` The SDK waits up to 30 minutes by default. It backs off between polls and honors `Retry-After`. ## Pick a scan type A preset is a scan type. Each one runs a fixed set of analyses. Broader types run more analysis and need a larger budget. CLI ```bash zkao presets ``` TypeScript ```ts const presets = await zkao.listScanPresets(); ``` curl ```bash curl -H "Authorization: Bearer $ZKAO_API_TOKEN" \ https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/scan-presets ``` 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 still resolve. Each preset has a `ref`, a `name`, a `description`, and a `minCredits` floor. Pass the `ref` when you launch. Without one, the launch uses the first active preset. ## Choose a budget The budget is the most a scan may spend, in credits. zkao reserves it at launch and never charges more. Credits the scan does not use go back to the balance. You can leave the budget out. zkao then picks the budget it recommends for this scan type and scope on this repository. The recommendation follows what past scans of the repository spent. The first scan of a repository starts at the scan type’s minimum. A diff scan is sized from its change instead, up to three times the minimum. The launch response tells you which budget was used. A scan that runs short of budget stops early, so treat its coverage as partial. See [Credits and usage](https://docs.zkao.io/guides/credits/) for how reservations affect the balance. ## Launch a scan CLI ```bash zkao scans launch --repo --preset --budget 500 ``` TypeScript ```ts const { scanId, creditBudget } = await zkao.launchScan({ repositoryId: repoId, presetRef: ref, creditBudget: 500, }); ``` curl ```bash curl -X POST -H "Authorization: Bearer $ZKAO_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"repositoryId":"","presetRef":"","creditBudget":500}' \ https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/scans ``` The API answers `202` with `scanId`, `queued`, `creditBudget`, and `buildsOverview`. Launching needs the `scans:launch` scope. ### Choose the commit By default a scan runs on the head of the repository’s default branch. * `branch` scans the head of that branch, resolved when the scan launches. * `commitHash` pins one commit (7 to 40 hex characters). It wins over `branch`. * `commitMessage` is optional metadata shown with the scan. The CLI flags are `--branch`, `--commit`, and `--message`. The commit must be pushed to GitHub, because zkao reads it from there. ### Scope a scan to audit areas An audit area is a named subsystem of the repository. zkao discovers areas when it maps the code. You can add your own. Scoping a scan to a few areas keeps a large repository affordable. CLI ```bash zkao areas list zkao scans launch --repo --preset "builtin:Max" --area --area ``` TypeScript ```ts const { areas } = await zkao.listAuditAreas(repoId); await zkao.launchScan({ repositoryId: repoId, presetRef: "builtin:Max", auditAreaKeys: [areas[0].key], }); ``` curl ```bash curl -H "Authorization: Bearer $ZKAO_API_TOKEN" \ https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/repositories//audit-areas ``` Each area reports its size in files and lines from one branch’s map. Pass `--branch` (or `branch`) to read another branch’s sizes. Leave the area list out to scan the whole repository. Or describe the code to audit in your own words with `--scope` (or `auditScope`). A key the current map no longer names fails the launch. zkao never drops it silently, so a budget sized for one area never runs against everything. An area is a name and a description, never a file list. Each scan resolves it against the code at its own commit. CLI ```bash zkao areas add "Proof verifier" --description "On-chain verifier and its key loading" zkao areas rm ``` TypeScript ```ts const area = await zkao.createAuditArea( repoId, "Proof verifier", "On-chain verifier and its key loading", ); await zkao.deleteAuditArea(repoId, area.key); ``` curl ```bash curl -X POST -H "Authorization: Bearer $ZKAO_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"name":"Proof verifier","description":"On-chain verifier and its key loading"}' \ https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/repositories//audit-areas ``` Adding and deleting areas needs the `guidance:write` scope. Only custom areas can be deleted. Deleting a discovered area returns `409`. ### Guide one scan Guidance tells a scan what matters: scope, threat model, and accepted risks. A launch can carry guidance for that scan only. It replaces the repository’s stored guidance for this run. A `zkao.md` committed in the repository still applies underneath. CLI ```bash zkao scans launch --repo --guidance focus.md cat focus.md | zkao scans launch --repo --guidance - ``` TypeScript ```ts await zkao.launchScan({ repositoryId: repoId, guidance: "Focus on the proof verifier. The prover is trusted.", }); ``` curl ```bash curl -X POST -H "Authorization: Bearer $ZKAO_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"repositoryId":"","guidance":"Focus on the proof verifier."}' \ https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/scans ``` In the API, the `guidance` field has three states: * Left out: the scan uses the repository’s stored guidance. * A string: that text replaces it for this scan. * `null` or an empty string: the scan runs with no stored guidance layer. Guidance is limited to 100,000 characters. See [Repository guidance](https://docs.zkao.io/guides/guidance/) for the standing layer. ## Follow a scan A scan moves through these statuses: | Status | Meaning | | ------------ | -------------------------------------------------------- | | `QUEUED` | Accepted and waiting to start. | | `PROCESSING` | Running. | | `COMPLETED` | Analysis finished. Check `triage` for unfinished review. | | `FAILED` | Stopped on an error. | | `CANCELLED` | Cancelled before it finished. | The last three are terminal. While a scan runs, its `progress` field reports `phasesCompleted`, `phasesTotal`, and a weighted `percent`. There is no time estimate. How long a scan takes depends on the repository and its guidance. A finished scan carries a `findingsSummary` with counts by severity. The easiest way to follow a scan is to wait on it. CLI ```bash zkao scans wait zkao scans wait --timeout 7200 ``` TypeScript ```ts const scan = await zkao.waitForScan(scanId, { onPoll: (s) => console.log(s.status, s.progress?.percent), }); ``` curl ```bash curl -i -H "Authorization: Bearer $ZKAO_API_TOKEN" \ https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/scans/ ``` `zkao scans wait` prints each poll on stderr and the final scan as JSON on stdout. Its `--timeout` is in seconds. The SDK’s `waitForScan` gives up after one hour by default. Set `timeoutMs` for longer scans, and pass a `signal` to abort. ### Poll politely If you poll by hand, read the `Retry-After` header on the scan response. It says how many seconds to wait before the next poll. It is present only while the scan is not terminal. A token that polls too fast gets `429 rate_limited`, also with `Retry-After`. Wait that long before the next request. The CLI and SDK do this for you. Tip Prefer `zkao scans wait` or `waitForScan` over your own loop. They back off with jitter and treat `429` as a signal to slow down, not as an error. ## Resume unfinished triage A completed scan can have findings that triage did not review. Unreviewed findings are withheld from results. Read `triage` on the scan detail before treating it as a complete review. | Field | Meaning | | ---------------- | ------------------------------------------------------------------- | | `status` | `pending`, `running`, `complete`, `budget_exhausted`, or `blocked`. | | `untriagedCount` | Findings still awaiting review. | | `activeRunId` | Active triage run, or `null`. | | `resume` | Allowed credit budgets after a budget stop, or `null`. | Resumption is available after a budget stop on a completed scan whose billing has settled. Unfinished findings must remain and no triage run may be active. Choose a budget within the offer and your authorized spending limit. Resumed triage uses the scan’s settings and only reviews the findings left over. It reserves a separate budget and returns unused credits. CLI ```bash zkao scans get zkao scans resume-triage --budget --idempotency-key zkao scans triage-wait zkao scans get ``` TypeScript ```ts const { run } = await zkao.resumeTriage( scanId, { creditBudget: authorizedCredits }, { idempotencyKey: requestKey }, ); await zkao.waitForTriageRun(scanId, run.id); const scan = await zkao.getScan(scanId); console.log(scan.triage); ``` curl ```bash curl -X POST -H "Authorization: Bearer $ZKAO_API_TOKEN" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: " \ -d '{"creditBudget":250}' \ https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/scans//triage/resume ``` Resumption needs `scans:launch` and respects the token’s repository and spending limits. Keep the same key and budget when retrying the same request. That returns the original run without reserving another budget. A different budget with that key returns `409`. Use a new key only for another authorized run. The parent scan stays `COMPLETED` while resumed triage runs. Poll the returned run with `getTriageRun` or its CLI counterpart. Read the scan’s `triage` again after the run finishes. A run can finish at its budget cap with findings still awaiting review. For a `blocked` triage status, contact support with a link to the scan. ## List scans Scans are listed newest first. The list is paginated with `page` and `limit` (at most 100, default 50). CLI ```bash zkao scans list --limit 20 zkao scans get ``` TypeScript ```ts const { items, total } = await zkao.listScans({ limit: 20 }); const detail = await zkao.getScan(items[0].id); ``` curl ```bash curl -H "Authorization: Bearer $ZKAO_API_TOKEN" \ "https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/scans?limit=20" ``` ## Cancel a scan You can cancel a queued or running scan. zkao stops its work, marks it `CANCELLED`, and releases its reserved credits. Work already in flight settles what it actually spent as it winds down. CLI ```bash zkao scans cancel ``` TypeScript ```ts await zkao.cancelScan(scanId); ``` curl ```bash curl -X POST -H "Authorization: Bearer $ZKAO_API_TOKEN" \ https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/scans//cancel ``` Cancelling needs the `scans:launch` scope. A scan that already reached `COMPLETED` or `FAILED` cannot be cancelled and returns `400`. ## Launch errors | Status | Code | What to do | | ------ | ------------------------- | ----------------------------------------------------------------------------------------- | | `400` | `bad_request` | Fix the request. The message names the problem. | | `400` | `diff_base_*` | See [Diff scans](https://docs.zkao.io/guides/diff-scans/). | | `402` | `insufficient_credits` | Add credits, or launch with a smaller budget. | | `403` | `forbidden` | The token lacks `scans:launch`. | | `404` | `not_found` | The repository is outside the token’s project or repository allowlist. | | `409` | `repository_initializing` | Wait for the repository to be `ready`. | | `422` | `diff_empty` | The diff scan has nothing to audit. | | `429` | `rate_limited` | The token’s spend limit is reached, or it sent too many requests. Wait for `Retry-After`. | The full contract is in the API reference for [launchScan](https://docs.zkao.io/api/operations/launchscan/) and [getScan](https://docs.zkao.io/api/operations/getscan/). --- Source: https://docs.zkao.io/ # Build on zkao zkao audits code for security bugs, with a focus on cryptography and zero-knowledge circuits. Everything you can do on a project in the app, you can also do through its API. ```bash npm install -g @zksecurity/zkao-cli zkao login zkao scans launch --repo --budget 500 ``` ## Pick your tool [CLI](https://docs.zkao.io/reference/cli/) The zkao command. JSON on stdout, built for shells and scripts. [TypeScript SDK](https://docs.zkao.io/reference/sdk/) A typed client generated from the OpenAPI spec, with helpers to wait on scans. [REST API](https://docs.zkao.io/api/) Every endpoint, request body, and response shape. [GitHub Action](https://docs.zkao.io/guides/github-action/) Scan every pull request's diff, or the whole repository on a schedule. [AI agents](https://docs.zkao.io/guides/agents/) A skill that teaches Claude Code and other agents to drive your project. [Authentication](https://docs.zkao.io/authentication/) Log in from a browser, or mint a scoped token for CI. ## Made for agents too llms.txt An index of these docs at [`/llms.txt`](https://docs.zkao.io/llms.txt), and all of them in one file at [`/llms-full.txt`](https://docs.zkao.io/llms-full.txt). Markdown pages Every page has a Markdown version. Replace its trailing slash with `.md`, or request it with `Accept: text/markdown`. Agent skill The skill lives at [`/skill.md`](https://docs.zkao.io/skill.md). Point your agent at it. OpenAPI spec The contract the SDK is generated from, at [`/openapi/v1.yaml`](https://docs.zkao.io/openapi/v1.yaml). --- Source: https://docs.zkao.io/quickstart/ # Quickstart This page takes you from nothing to your first findings in a terminal. You need Node 18 or later and a zkao project with at least one repository. 1. **Install the CLI.** ```bash npm install -g @zksecurity/zkao-cli ``` This installs the `zkao` command. For a one-off run without installing, prefix commands with `npx @zksecurity/zkao-cli`. You can also use the install script: ```bash curl -fsSL https://raw.githubusercontent.com/zksecurity/zkao-sdk/main/install.sh | bash ``` 2. **Authorize it for a project.** ```bash zkao login ``` The CLI opens a browser page and prints a short code. Check that the page shows the same code. Pick a project, review the permissions, and approve. The CLI saves the token for that project. There is nothing to copy. Confirm which project you are connected to: ```bash zkao whoami ``` See [Authentication](https://docs.zkao.io/authentication/) for tokens, scopes, and non-interactive logins. 3. **Find a repository.** ```bash zkao repos ``` Note the `id` of the repository to scan. Its `readiness` must be `ready`. A repository added moments ago is `analyzing` for a short while. `zkao repos:wait ` blocks until it is ready. 4. **Pick a scan preset.** ```bash zkao presets ``` Each preset is a scan type. Note the `ref` of the one you want. 5. **Launch the scan.** ```bash zkao scans launch --repo --preset ``` The response carries the `scanId` and the budget the scan reserved, in credits. Without `--budget`, zkao picks the budget it recommends for this scan type on this repository. Pass `--budget ` to set your own ceiling. `zkao billing balance` shows the credits available to the project. 6. **Wait for it to finish.** ```bash zkao scans wait ``` The scan moves from `QUEUED` to `PROCESSING` to `COMPLETED`. Scans take minutes. `wait` polls at the pace the server asks for, so you do not need your own loop. 7. **Read the findings.** ```bash zkao findings list --scan zkao findings get ``` `get` returns the full finding, including the description, proof of concept, and recommended fix. Every command prints JSON on stdout, so it pipes cleanly into `jq` or a script. `zkao --help` lists every command. ## Launch without the CLI The same launch over plain HTTP or the TypeScript SDK: curl ```bash curl -X POST "https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/scans" \ -H "Authorization: Bearer $ZKAO_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"repositoryId":"","presetRef":""}' ``` TypeScript ```ts import { ZkaoClient } from "@zksecurity/zkao-sdk"; const zkao = new ZkaoClient({ token: process.env.ZKAO_API_TOKEN!, projectId: process.env.ZKAO_PROJECT_ID!, }); const { scanId } = await zkao.launchScan({ repositoryId: "", presetRef: "" }); await zkao.waitForScan(scanId); const { items } = await zkao.listFindings({ scanId }); ``` Note A `402 insufficient_credits` response means the organization’s balance cannot cover the budget. See [Credits and billing](https://docs.zkao.io/guides/credits/). ## Next steps * [Scans](https://docs.zkao.io/guides/scans/) covers presets, budgets, branches, areas, and per-scan guidance. * [Triage findings](https://docs.zkao.io/guides/findings/) covers severity, resolution, and notes. * [CLI reference](https://docs.zkao.io/reference/cli/) lists every command and flag. --- Source: https://docs.zkao.io/reference/api-conventions/ # API conventions These rules apply to every endpoint in the [API reference](https://docs.zkao.io/api/). The machine-readable contract is the OpenAPI spec at [`/openapi/v1.yaml`](https://docs.zkao.io/openapi/v1.yaml). ## Base URL ```plaintext https://zkao.io/api/v1 ``` Project resources live under `/projects/{projectId}`, for example `/projects/{projectId}/scans`. The one exception is `GET /token`, which needs no project id. Staging uses `https://staging.zkao.io/api/v1`. See [Environments](https://docs.zkao.io/environments/). ## Authentication Send a project API token in the `Authorization` header: ```plaintext Authorization: Bearer zkao_proj__ ``` A token in the query string is rejected with `400`. See [Authentication](https://docs.zkao.io/authentication/) for how to get a token and what its scopes allow. ## Requests and responses Request and response bodies are JSON. Send `Content-Type: application/json` with a body. Timestamps are ISO 8601 strings. ## Errors Every error uses one envelope: ```json { "error": { "code": "not_found", "message": "Not found" } } ``` Branch on `code`. The `message` is for people and can change. | Status | Code | Meaning | | ------ | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | `bad_request` | The request is invalid. The message says why. | | `400` | `budget_below_minimum` | The budget is below the scan’s minimum. `minimumCredits` names it. A repository’s first diff scan also builds its overview, so its minimum is higher. | | `400` | `diff_base_required`, `diff_base_not_allowed`, `diff_base_invalid` | A diff scan’s base is missing, given to a preset that refuses it, or malformed. | | `401` | `unauthorized` | The token is missing, malformed, expired, or revoked. | | `402` | `insufficient_credits` | The organization’s credits cannot cover the scan. | | `403` | `forbidden` | The token lacks the scope this call needs. | | `404` | `not_found` | The resource does not exist, or is outside the token’s project or repository allowlist. | | `409` | `conflict` | A concurrent change, such as guidance edited since you read it, or an ambiguous `ZK-` label. | | `409` | `repository_initializing` | The repository is still being analyzed. Retry once its `readiness` is `ready`. | | `422` | `diff_empty` | A diff scan has no change to audit between the base and the head. | | `429` | `rate_limited` | Too many requests, or the token’s spend limit is reached. | | `500` | `internal` | Something failed on zkao’s side. | zkao answers `404`, not `403`, for anything outside a token’s reach. That way a token cannot probe which ids exist. The SDK throws `ZkaoApiError` for any non-2xx response, with `.status`, `.code`, and `.message`. The CLI prints `Error (): ` on stderr and exits with code 1. ## Pagination List endpoints for scans and findings take `page` and `limit` query parameters: ```bash curl -H "Authorization: Bearer $ZKAO_API_TOKEN" \ "https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/findings?page=2&limit=100" ``` * `page` starts at 1. * `limit` defaults to 50 and is capped at 100. They return: ```json { "items": [], "page": 2, "limit": 100, "total": 312 } ``` Keep requesting pages until `page * limit >= total`. Other lists, such as repositories and presets, return everything in one response. ## Rate limits and polling Each token has a request ceiling per time window. Normal use never reaches it. Past it, the API returns `429 rate_limited` with a `Retry-After` header in seconds. Wait that long before retrying. While a scan is still running, `GET /scans/{scanId}` returns an advisory `Retry-After` header. It says how long to wait before polling again. Honor it instead of polling in a tight loop. The SDK’s `waitForScan` and the CLI’s `zkao scans wait` do this for you. A launch that would push a token past its spend limit also returns `429`. ## Identifiers Ids are opaque strings. Treat them as such. A finding also has a `ZK-` label, shown on its page. The label is the id’s last eight characters. Every endpoint that takes a `findingId` also accepts the label, with or without the `ZK-` prefix. A label that matches more than one finding in the project returns `409 conflict`. Use the full id then. Projects, organizations, and repositories also carry a `slug`. Slugs form the readable app URLs, such as `/orgs//projects//repos/`. API paths use ids, not slugs. ## Credits Every budget, balance, and spend in the API is in credits. Credits are the only unit the API reports. See [Credits and billing](https://docs.zkao.io/guides/credits/). ## Versioning The major version is part of the path: `/api/v1`. New endpoints and new response fields can appear within v1. Ignore fields your client does not recognize. --- Source: https://docs.zkao.io/reference/cli/ # CLI reference The `zkao` command ships in the `@zksecurity/zkao-cli` package. It needs Node 18 or later. ```bash npm install -g @zksecurity/zkao-cli ``` To run a single command without installing, use `npx @zksecurity/zkao-cli `. `zkao --help` and `zkao --help` always list the commands of the version you run. ## Output and exit codes * Commands that call the API print their result as JSON on stdout. Pipe it to `jq` or parse it. * Progress lines, warnings, and the update notice go to stderr. They never mix into the JSON. * `login`, `config set`, and `config use` print plain status lines instead of JSON. * The exit code is `0` on success and `1` on any failure. * An API error prints `Error (): ` on stderr. The codes are listed in [API conventions](https://docs.zkao.io/reference/api-conventions/). Pass `--json-errors` for API errors as JSON on stderr. The envelope is `{ "error": { "status": 409, "code": "conflict", "message": "..." } }`. Set `ZKAO_NO_UPDATE_CHECK=1` when parsing stderr. ## Global options These options work with every command. | Option | Meaning | | ------------------ | ------------------------------------------------------------------------------------------- | | `--token ` | Project API token. Overrides `ZKAO_API_TOKEN` and saved credentials. | | `--project ` | Project id. Overrides `ZKAO_PROJECT_ID` and the active project. | | `--base-url ` | API base URL, used exactly as given. Prefer `ZKAO_URL` unless you need a non-standard base. | | `--json-errors` | Print API errors as JSON on stderr. | | `-V, --version` | Print the CLI version. | | `-h, --help` | Show help for the CLI or a command. | ## Settings and environment Each setting is taken from the first source that has it. 1. The command-line flag. 2. The environment variable. 3. The config file, `~/.zkao/config.json`. | Variable | Meaning | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ZKAO_API_TOKEN` | Project API token (`zkao_proj_...`). | | `ZKAO_PROJECT_ID` | Project id. Picks that project’s saved token when no token is given. | | `ZKAO_URL` | Environment to target. Accepts a host, an origin, or a full API URL, such as `staging.zkao.io`. See [Environments](https://docs.zkao.io/environments/). | | `ZKAO_NO_UPDATE_CHECK` | Set to any value to turn off the update notice. | | `ZKAO_DEBUG` | Set to any value to log update-check failures on stderr. | The config file stores one token per project and remembers which project is active. Each saved project keeps its own base URL, so staging and production projects can live side by side. The file is written with owner-only permissions. A login started with `--no-wait` is kept in `~/.zkao/pending-login.json` until it resolves. ## Update notice At most once a day, after a command has printed its output, the CLI asks the npm registry for the newest version. When a newer one exists, later commands print one line on stderr: ```plaintext zkao: version X.Y.Z is available (running A.B.C). Update with `npm install -g @zksecurity/zkao-cli`. ... ``` A prerelease install (`X.Y.Z-next.N`) follows the `next` channel and suggests `@zksecurity/zkao-cli@next`. The check never delays a command or changes its output. ## Authentication ### `zkao login` Authorize the CLI in your browser. The CLI prints a URL and a short code. You open the URL, confirm the code matches, pick one or more projects, and approve. The CLI saves a token for each approved project and makes the first one active. | Option | Meaning | | --------------------- | ------------------------------------------------------------------------------------------------------------------ | | `--no-browser` | Print the URL instead of opening a browser. | | `--no-wait` | Start the login, print the URL and code, and exit. Finish it with `--resume`. | | `--resume` | Poll a login started with `--no-wait`. Polls once by default. | | `--timeout ` | With `--resume`, keep polling up to this long. | | `--scope ` | Scopes to request. The default is `read scans:launch findings:write guidance:write`. The approver can change them. | The global `--project ` preselects that project on the approval page. For agents and CI, split the login so no call blocks: ```bash zkao login --no-wait --no-browser # prints the URL and code, then exits zkao login --resume # repeat until it prints "Authorized" ``` `--resume` prints `Still waiting for approval` while the login is pending. Several logins can be pending at once, and `--resume` finishes whichever is approved. See [Authentication](https://docs.zkao.io/authentication/). ### `zkao whoami` Print the token’s id, name, scopes, repository allowlist, expiry, and spend limit, plus the project and organization it belongs to. Warns on stderr when the token belongs to a different project than the configured one. ## Config ### `zkao config set` Save settings to `~/.zkao/config.json`. | Option | Meaning | | ------------------ | -------------------------------- | | `--token ` | Token to save. | | `--project ` | Project id to save or switch to. | | `--base-url ` | API base URL to save. | A token given without `--project` is looked up with the API and saved under the project it belongs to. A project id given alone switches to that project’s saved token. ### `zkao config show` Print the resolved settings with the token masked. Also lists every saved project with its name, organization, base URL, and whether it is active. ### `zkao config use ` Make a project with saved credentials the active one. Fails when no token is saved for it. ## Repositories ### `zkao repos` List the project’s repositories. Each has an `id` and a `readiness` of `ready` or `analyzing`. ### `zkao repos:wait ` Wait until a repository is ready to scan, then print it. A newly added repository is `analyzing` for a while, and a scan launched on it fails with `repository_initializing`. | Option | Meaning | | ---------------- | ---------------------------------------------------------------- | | `--timeout ` | Give up after this many milliseconds. The default is 30 minutes. | ## Presets ### `zkao presets` List the scan presets the project can launch. Pass a preset’s `ref` to `zkao scans launch --preset`. ## Scans ### `zkao scans launch` Launch a scan and print its id. Needs the `scans:launch` scope. | Option | Meaning | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `--repo ` | Repository id. Required. | | `--budget ` | Maximum budget in credits, reserved at launch. Omit it to use the budget zkao recommends for this scan type on this repository. | | `--preset ` | Scan preset ref from `zkao presets`. Defaults to the first active preset. | | `--branch ` | Branch to scan, resolved to its head commit. Ignored when `--commit` is set. | | `--commit ` | Commit to scan. | | `--base ` | Base commit, branch, or tag of a diff scan. The scan audits only the change from it. Requires a diff preset. | | `--message ` | Commit message to record with the scan. | | `--guidance ` | Guidance for this scan only, from a file or `-` for stdin. Replaces the repository’s guidance for this run. | | `--area ` | Audit area to scope the scan to. Repeat it for several. See `zkao areas list`. | | `--scope ` | The code to audit, in your own words, instead of `--area`. | See [Scans](https://docs.zkao.io/guides/scans/) and [Diff scans](https://docs.zkao.io/guides/diff-scans/). ### `zkao scans list` List scans, most recent first. | Option | Meaning | | ------------- | --------------------- | | `--page ` | Page number. | | `--limit ` | Page size, up to 100. | ### `zkao scans get ` Print one scan’s status and detail. The status is `QUEUED`, `PROCESSING`, `COMPLETED`, `FAILED`, or `CANCELLED`. ### `zkao scans wait ` Poll a scan until it is `COMPLETED`, `FAILED`, or `CANCELLED`, then print the final detail. It backs off between polls and honors the server’s `Retry-After`. Each poll prints a progress line on stderr. Ctrl-C stops waiting. The command exits `0` whichever final status the scan reaches. Read `status` in the output. | Option | Meaning | | --------------------- | --------------------------------------------------------- | | `--timeout ` | Give up after this many seconds. The default is one hour. | ### `zkao scans cancel ` Cancel a running or queued scan. Needs the `scans:launch` scope. The reserved credits not yet spent are released. A completed or failed scan cannot be cancelled. ### `zkao scans resume-triage ` Resume triage after its budget cap left findings unreviewed. Needs the `scans:launch` scope. Read the scan’s `triage.resume` offer before choosing a budget. | Option | Meaning | | ------------------------- | ------------------------------------------------------------------- | | `--budget ` | Explicit credit budget within the offer. Required. | | `--idempotency-key ` | Stable request key of up to 128 visible ASCII characters. Required. | The result contains `run` and `replayed`. Reuse the same key and budget when retrying the request. The same request returns its original run even after that run finishes. A different budget with that key fails with `409`. ### `zkao scans triage-get ` Read one resumed triage run. It reports `status`, `findingCount`, and `budgetExhausted`. ### `zkao scans triage-wait ` Wait for that triage run to finish. It honors `Retry-After` and prints progress on stderr. `--timeout ` defaults to one hour. Ctrl-C stops waiting. The parent scan stays `COMPLETED` during resumed triage. Read its `triage` again after the run finishes. A completed triage run can still leave findings unreviewed. ### `zkao scans publish ` Publish a completed scan as a public page. Needs the `publish` scope. The output’s `publicId` names the page, at `https://zkao.io/public/scans/`. | Option | Meaning | | ------------ | ------------------------------------------------------------------------- | | `--password` | Protect the page with a generated password, returned as `accessPassword`. | See [Publishing](https://docs.zkao.io/guides/publishing/). ## Findings The read commands need the `read` scope. Commands that change a finding say which scope they need. `` accepts a finding’s full id or the `ZK-` label shown on its page. A label that matches more than one finding is refused. Use the full id then. ### `zkao findings list` List findings across the project, or for one scan. | Option | Meaning | | ------------- | ----------------------------- | | `--scan ` | Only findings from this scan. | | `--page ` | Page number. | | `--limit ` | Page size, up to 100. | ### `zkao findings get ` Print a finding’s full detail, including its proof of concept and notes. ### `zkao findings details` Print the full detail of a scan’s findings, of a set of findings, or both, in one call. It returns the findings shown in the app. It fetches every page unless `--page` is given. | Option | Meaning | | ------------- | -------------------------------------------------------------------------------------------------------- | | `--scan ` | Only findings from this scan. | | `--ids ` | Comma-separated finding ids or `ZK-` labels, at most 50. Ids that match nothing are listed in `missing`. | | `--page ` | Fetch only this page. | | `--limit ` | Page size, up to 50. | ### `zkao findings comment ` Add a comment to a finding. Needs the `findings:write` scope. ### `zkao findings severity ` Override a finding’s severity with `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, or `INFO`. Pass `none` to clear the override. Case does not matter. Needs the `findings:write` scope. ### `zkao findings resolution ` Set a finding’s resolution status: `NOT_STARTED`, `IN_PROGRESS`, `RESOLVED`, `WONT_FIX`, `MITIGATED`, `FALSE_POSITIVE`, or `DUPLICATE`. Needs the `findings:write` scope. | Option | Meaning | | ----------------- | --------------------------------------------------------------------------------------------------------------------------- | | `--note ` | Record the reason as a comment in the same call. | | `--reason ` | Record the reason as a catalog code instead. Valid codes depend on the status. A wrong one is rejected with the valid list. | `--note` wins when both are given. Both are ignored for `NOT_STARTED` and `IN_PROGRESS`. See [Triage findings](https://docs.zkao.io/guides/findings/) for the reason codes. ### `zkao findings triage ` Override zkao’s triage verdict with `confirmed` or `false-positive`. Needs the `findings:write` scope. Setting the AI’s own verdict again clears the override. | Option | Meaning | | --------------- | ------------------------------------------------ | | `--note ` | Record the reason as a comment in the same call. | The result has `triageStatus`, `previousTriageStatus`, and the comment’s `noteId`, or `null` without a note. ### `zkao findings publish ` Publish a finding as a public page. Needs the `publish` scope. The output’s `publicId` names the page, at `https://zkao.io/public/findings/`. | Option | Meaning | | ----------------- | ------------------------------------------------------------------------- | | `--note ` | Note to show as the published note. | | `--password` | Protect the page with a generated password, returned as `accessPassword`. | ## Guidance Guidance is text that every scan of a repository reads. See [Repository guidance](https://docs.zkao.io/guides/guidance/). ### `zkao guidance get ` Print a repository’s guidance. ### `zkao guidance set ` Set a repository’s guidance from a file, or from stdin with `-`. Needs the `guidance:write` scope. By default the CLI reads the current guidance first and sends it along. If someone changed it in between, the write fails with a conflict instead of overwriting their edit. | Option | Meaning | | --------- | ---------------------------------------------- | | `--force` | Overwrite without the concurrent-change check. | ### `zkao guidance clear ` Remove a repository’s guidance. It takes the same check and `--force` option as `set`. ## Audit areas An audit area is a named subsystem of a repository. A scan can be scoped to one or more areas instead of the whole repository. ### `zkao areas list ` List a repository’s audit areas and their keys. | Option | Meaning | | ------------------- | ------------------------------------------------------------------------------------ | | `--branch ` | Read area sizes from this branch’s map. Defaults to the repository’s default branch. | ### `zkao areas add ` Add a custom area. Its key is derived from the name. Needs the `guidance:write` scope. | Option | Meaning | | ---------------------- | -------------------------------- | | `--description ` | What this part of the code does. | ### `zkao areas rm ` Delete a custom area. An area that a scan’s map named is refused. Needs the `guidance:write` scope. ## Continuous Security Continuous Security analyzes a branch on its own, paid from a monthly budget. `get` needs the `read` scope. The other commands need `automations:write`. Each command takes `--branch `. It defaults to the repository’s default branch. ### `zkao continuous get ` Print the branch’s schedule, what it spent this month, and its monthly budget bounds. `availableFeatures` lists the analysis IDs the branch offers. `enabledFeatures` lists the selected IDs. The schedule runs when `enabled` is true. ### `zkao continuous on ` Turn automatic analysis on, or resume it. A new schedule starts at the default monthly budget unless `--budget` is given. | Option | Meaning | | ------------------------ | ---------------------------------------------------------------------------------------- | | `--budget ` | Monthly budget in credits, within the minimum and maximum that `get` reports. | | `--area ` | Audit area to rotate through, one per run. Repeat it for several. See `zkao areas list`. | | `--whole-repo` | Scan the whole repository every run. It cannot be combined with `--area`. | | `--enable-analysis ` | Add an analysis to the branch’s selection. Repeat to add several. | | `--only-analysis ` | Replace the whole selection. Repeat for each analysis to keep. | This command enables formal verification (FV) alongside the other analyses on `main`. ```bash zkao continuous on --branch main --budget --enable-analysis formal-verification ``` ### `zkao continuous set ` Change the selected analyses, monthly budget or audit areas. It takes the same options as `on`. To switch an existing schedule to FV alone at its current budget, run `zkao continuous set --branch main --only-analysis formal-verification`. If the branch has no schedule, use `on` to create one. ### `zkao continuous off ` Pause automatic analysis. The schedule and its settings are kept. ### `zkao continuous prepare ` Plan the branch’s next analysis without running it, as **Prepare next analysis** does in the app. Preparing spends no credits. It works whether automatic analysis is on or off. A preparation already in progress on the branch is reused. It fails with `400` when the branch has no active Continuous Security, and with `409` while the repository is still being prepared. ### `zkao continuous rm ` Remove the schedule. Scans it already ran are kept. ## Questions A Continuous Security analysis can ask the project’s members a question. ### `zkao questions list` List the open questions, oldest first. Each has an `id`, its `repositoryId` and `branch`, the question `text`, the `options` it offers, and the analysis that asked it. ### `zkao questions answer ` Answer a question with one of its options, a note, or both. Needs the `guidance:write` scope. The analysis reads the answer in its next session. The answer counts as that of the member who created the token, who needs a project role of their own. A question that was already answered or dismissed fails with `409`. | Option | Meaning | | ------------------ | ------------------------------------------------------------ | | `--option