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

Connect a GitHub repository to a project

View .md
POST
/organizations/{organizationId}/projects/{projectId}/repositories
curl --request POST \
--url https://zkao.io/api/v1/organizations/example/projects/example/repositories \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "owner": "example", "name": "example" }'

Requires an organization token with scope repositories:write. The same checks as the dashboard apply. A private repository needs the zkao GitHub App installed for it, and the member who created the token must have access to it on GitHub with a verified GitHub account. A new repository is analyzing until its first pass finishes.

organizationId
required
string

The organization’s id, as GET /token reports it.

projectId
required
string
Media typeapplication/json
object
owner
required

GitHub user or organization.

string
name
required

Repository name.

string
Examplegenerated
{
"owner": "example",
"name": "example"
}

Created

Media typeapplication/json
object
repository
required
object
id
required
string
slug
required

URL segment of the repository inside its project (/orgs/<org>/projects/<project>/repos/<slug>). 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
{
"repository": {
"readiness": "ready"
}
}

Invalid request

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: unauthorized forbidden not_found bad_request conflict insufficient_credits budget_below_minimum repository_initializing diff_base_required diff_base_not_allowed diff_base_invalid diff_empty rate_limited internal
message
required
string
minimumCredits

Budget_below_minimum only: the least the launch could have reserved, in credits. A diff scan’s first scan of a repository also builds its overview, so its minimum is higher.

integer
Example
{
"error": {
"code": "unauthorized"
}
}

Missing, malformed, expired, or revoked token

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: unauthorized forbidden not_found bad_request conflict insufficient_credits budget_below_minimum repository_initializing diff_base_required diff_base_not_allowed diff_base_invalid diff_empty rate_limited internal
message
required
string
minimumCredits

Budget_below_minimum only: the least the launch could have reserved, in credits. A diff scan’s first scan of a repository also builds its overview, so its minimum is higher.

integer
Example
{
"error": {
"code": "unauthorized"
}
}

The token is a project token, or lacks the required scope

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: unauthorized forbidden not_found bad_request conflict insufficient_credits budget_below_minimum repository_initializing diff_base_required diff_base_not_allowed diff_base_invalid diff_empty rate_limited internal
message
required
string
minimumCredits

Budget_below_minimum only: the least the launch could have reserved, in credits. A diff scan’s first scan of a repository also builds its overview, so its minimum is higher.

integer
Example
{
"error": {
"code": "unauthorized"
}
}

Resource not in this token’s project or repo allowlist

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: unauthorized forbidden not_found bad_request conflict insufficient_credits budget_below_minimum repository_initializing diff_base_required diff_base_not_allowed diff_base_invalid diff_empty rate_limited internal
message
required
string
minimumCredits

Budget_below_minimum only: the least the launch could have reserved, in credits. A diff scan’s first scan of a repository also builds its overview, so its minimum is higher.

integer
Example
{
"error": {
"code": "unauthorized"
}
}

The repository is already in the project (code conflict)

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: unauthorized forbidden not_found bad_request conflict insufficient_credits budget_below_minimum repository_initializing diff_base_required diff_base_not_allowed diff_base_invalid diff_empty rate_limited internal
message
required
string
minimumCredits

Budget_below_minimum only: the least the launch could have reserved, in credits. A diff scan’s first scan of a repository also builds its overview, so its minimum is higher.

integer
Example
{
"error": {
"code": "unauthorized"
}
}

Rate limited. Either the token’s spend limit for the current period is reached (on launch), or the token is sending too many requests. Wait the number of seconds in the Retry-After header before retrying.

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: unauthorized forbidden not_found bad_request conflict insufficient_credits budget_below_minimum repository_initializing diff_base_required diff_base_not_allowed diff_base_invalid diff_empty rate_limited internal
message
required
string
minimumCredits

Budget_below_minimum only: the least the launch could have reserved, in credits. A diff scan’s first scan of a repository also builds its overview, so its minimum is higher.

integer
Example
{
"error": {
"code": "unauthorized"
}
}
Retry-After
integer

Seconds to wait before retrying.