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

Create a project

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

Requires an organization token with scope projects:write. The project is created by the member who created the token. The token reaches the new project at once.

organizationId
required
string

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

Media typeapplication/json
object
name
required

Letters, numbers, dashes, and underscores. Unique in the organization.

string
description
string | null
<= 2000 characters
Examplegenerated
{
"name": "example",
"description": "example"
}

Created

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

URL segment of the project inside its organization.

string
name
required
string
description
required
string | null
createdAt
required
string format: date-time
repositoryCount
required
integer
Examplegenerated
{
"project": {
"id": "example",
"slug": "example",
"name": "example",
"description": "example",
"createdAt": "2026-04-15T12:00:00Z",
"repositoryCount": 1
}
}

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

A project with this name already exists (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.