# 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_<keyId>_<secret>`. 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/<org>/projects/<project>/repos/<repo>`).

## 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_<keyId>_<secret>`.

**Security scheme type:&#x20;**&#x68;ttp
