Projects

Deployable apps. Each project gets a managed subdomain and isolated runtime.

projects.list

List the organization’s projects.

GET /v1/orgs/{orgId}/projects

Auth: Organization API key (Authorization: Bearer korve_...) or dashboard session.
Minimum role: member
Risk: read

Example

curl "https://api.korve.dev/v1/orgs/$ORG_ID/projects" \
  -H "Authorization: Bearer korve_..."

Responses

Status	Description
`200`	Projects with their public URLs.

Response body (200)

An array of objects with these fields:

Field	Type	Description
`id`	string	—
`name`	string	—
`slug`	string	Pattern: `^[a-z][a-z0-9-]{1,61}$`.
`runtimeClass`	string	One of: `scale-to-zero`, `always-on`.
`region`	string	Where the app runs: a compute region id for always-on apps, “global” for scale-to-zero apps (they run on the global edge). Immutable after creation. The catalog lives at regions.list.
`gitRepo`	string or null	Connected repository as “owner/repo” — pushes and pull requests there drive deploys and previews; null when no repository is connected.
`gitRef`	string	Production branch — pushes to it deploy automatically.
`url`	string	Public URL on the managed domain (“https://<slug>.korve.app”).
`createdAt`	string	Format: `date-time`.

projects.create

Create a project and provision its runtime.

POST /v1/orgs/{orgId}/projects

Auth: Organization API key (Authorization: Bearer korve_...) or dashboard session.
Minimum role: admin
Billing: requires active organization billing — returns 402 otherwise.
Risk: write

Request body

Field	Type	Required	Description
`name`	string	Yes	—
`slug`	string	Yes	Managed subdomain label — globally unique. Pattern: `^[a-z][a-z0-9-]{1,61}$`.
`runtimeClass`	string	Yes	One of: `scale-to-zero`, `always-on`.
`region`	string	No	Compute region id for always-on apps (see regions.list); defaults to the platform default region. Scale-to-zero apps run on the global edge and must not pick a region. Immutable after creation.
`gitRepo`	string	No	Repository to connect as “owner/repo” — enables push-to-deploy and pull-request previews. Pattern: `^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$`.
`gitRef`	string	No	Production branch for push-to-deploy. Defaults to main.

Example

curl -X POST "https://api.korve.dev/v1/orgs/$ORG_ID/projects" \
  -H "Authorization: Bearer korve_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Storefront",
  "slug": "storefront",
  "runtimeClass": "scale-to-zero",
  "region": "example",
  "gitRepo": "acme/storefront",
  "gitRef": "main"
}'

Responses

Status	Description
`201`	Project created.
`402`	Organization billing is not active.
`409`	Slug already taken.
`422`	Invalid name, slug, runtime class, or region — including any region on a scale-to-zero project.

Response body (201)

Field	Type	Description
`id`	string	—
`name`	string	—
`slug`	string	Pattern: `^[a-z][a-z0-9-]{1,61}$`.
`runtimeClass`	string	One of: `scale-to-zero`, `always-on`.
`region`	string	Where the app runs: a compute region id for always-on apps, “global” for scale-to-zero apps (they run on the global edge). Immutable after creation. The catalog lives at regions.list.
`gitRepo`	string or null	Connected repository as “owner/repo” — pushes and pull requests there drive deploys and previews; null when no repository is connected.
`gitRef`	string	Production branch — pushes to it deploy automatically.
`url`	string	Public URL on the managed domain (“https://<slug>.korve.app”).
`createdAt`	string	Format: `date-time`.

projects.get

Get one project with its latest deployment.

GET /v1/orgs/{orgId}/projects/{projectId}

Auth: Organization API key (Authorization: Bearer korve_...) or dashboard session.
Minimum role: member
Risk: read

Example

curl "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID" \
  -H "Authorization: Bearer korve_..."

Responses

Status	Description
`200`	The project.
`404`	No such project in this organization.

Response body (200)

Field	Type	Description
`id`	string	—
`name`	string	—
`slug`	string	Pattern: `^[a-z][a-z0-9-]{1,61}$`.
`runtimeClass`	string	One of: `scale-to-zero`, `always-on`.
`region`	string	Where the app runs: a compute region id for always-on apps, “global” for scale-to-zero apps (they run on the global edge). Immutable after creation. The catalog lives at regions.list.
`gitRepo`	string or null	Connected repository as “owner/repo” — pushes and pull requests there drive deploys and previews; null when no repository is connected.
`gitRef`	string	Production branch — pushes to it deploy automatically.
`url`	string	Public URL on the managed domain (“https://<slug>.korve.app”).
`createdAt`	string	Format: `date-time`.
`latestDeployment`	object or null	—
`latestDeployment.id`	string	—
`latestDeployment.status`	string	One of: `queued`, `building`, `deploying`, `ready`, `failed`.
`latestDeployment.environment`	string or null	Slug of the environment the deployment targets. Null only for deployments that predate environment tracking.
`latestDeployment.trigger`	object or null	What queued the deployment. Null for deployments that predate trigger tracking.
`latestDeployment.trigger.kind`	string	push = a push to a connected branch, pr = a pull-request preview, manual = the API/CLI, rollback = a redeploy of an earlier successful deployment. One of: `push`, `pr`, `manual`, `rollback`.
`latestDeployment.trigger.actor`	object	Who triggered it — present for repository-driven deploys.
`latestDeployment.trigger.actor.login`	string	—
`latestDeployment.trigger.actor.avatarUrl`	string or null	—
`latestDeployment.gitRepo`	string or null	Source repository as “owner/repo”; null for non-git deploys.
`latestDeployment.gitRef`	string	—
`latestDeployment.commitSha`	string or null	—
`latestDeployment.createdAt`	string	Format: `date-time`.
`latestDeployment.finishedAt`	string or null	Format: `date-time`.
`latestDeployment.error`	string or null	—

projects.update

Update project settings: rename it, connect or disconnect a repository, or change the production branch. Renaming never changes the slug or the public URL.

PATCH /v1/orgs/{orgId}/projects/{projectId}

Auth: Organization API key (Authorization: Bearer korve_...) or dashboard session.
Minimum role: admin
Risk: write

Request body

Field	Type	Required	Description
`name`	string	No	New display name, 1-100 characters.
`gitRepo`	string or null	No	Repository to connect as “owner/repo” — pushes and pull requests there drive deploys and previews. Send null to disconnect. Pattern: `^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$`.
`gitRef`	string	No	Production branch for push-to-deploy, 1-100 characters.

Example

curl -X PATCH "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID" \
  -H "Authorization: Bearer korve_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Storefront",
  "gitRepo": "acme/storefront",
  "gitRef": "main"
}'

Responses

Status	Description
`200`	The updated project.
`404`	No such project in this organization.
`422`	Invalid name, gitRepo, or gitRef — or no fields to update.

Response body (200)

Field	Type	Description
`id`	string	—
`name`	string	—
`slug`	string	Pattern: `^[a-z][a-z0-9-]{1,61}$`.
`runtimeClass`	string	One of: `scale-to-zero`, `always-on`.
`region`	string	Where the app runs: a compute region id for always-on apps, “global” for scale-to-zero apps (they run on the global edge). Immutable after creation. The catalog lives at regions.list.
`gitRepo`	string or null	Connected repository as “owner/repo” — pushes and pull requests there drive deploys and previews; null when no repository is connected.
`gitRef`	string	Production branch — pushes to it deploy automatically.
`url`	string	Public URL on the managed domain (“https://<slug>.korve.app”).
`createdAt`	string	Format: `date-time`.

projects.checkRepoAccess

Check whether the platform can reach a repository for deploys and previews. Answers that are not accessible include the URL where access can be granted.

GET /v1/orgs/{orgId}/projects/{projectId}/repo-access

Auth: Organization API key (Authorization: Bearer korve_...) or dashboard session.
Minimum role: member
Risk: read

Query parameters

Name	Type	Required	Description
`repo`	string	Yes	Pattern: `^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$`.

Example

curl "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/repo-access?repo=acme%2Fstorefront" \
  -H "Authorization: Bearer korve_..."

Responses

Status	Description
`200`	The access check result.
`404`	No such project in this organization.

Response body (200)

Field	Type	Description
`accessible`	boolean	—
`reason`	string	Present when not accessible: the Korve GitHub App is not installed on that repository, or repo is not a valid “owner/repo” value. One of: `not_installed`, `invalid`.
`installUrl`	string	Where to grant the platform access to repositories.

projects.delete

Delete a project, its deployments, env vars, and runtime.

DELETE /v1/orgs/{orgId}/projects/{projectId}

Auth: Organization API key (Authorization: Bearer korve_...) or dashboard session.
Minimum role: owner
Risk: destructive · sensitive (elevated blast radius)

Example

curl -X DELETE "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID" \
  -H "Authorization: Bearer korve_..."

Responses

Status	Description
`200`	Project deleted.
`404`	No such project in this organization.
`502`	Runtime teardown failed; the project was kept.

Getting started

Agents

Primitives

API reference

CLI reference

projects.list

Example

Responses

Response body (200)

projects.create

Request body

Example

Responses

Response body (201)

projects.get

Example

Responses

Response body (200)

projects.update

Request body

Example

Responses

Response body (200)

projects.checkRepoAccess

Query parameters

Example

Responses

Response body (200)

projects.delete

Example

Responses

​projects.list

​Example

​Responses

​Response body (200)

​projects.create

​Request body

​Example

​Responses

​Response body (201)

​projects.get

​Example

​Responses

​Response body (200)

​projects.update

​Request body

​Example

​Responses

​Response body (200)

​projects.checkRepoAccess

​Query parameters

​Example

​Responses

​Response body (200)

​projects.delete

​Example

​Responses

projects.list

Example

Responses

Response body (200)

projects.create

Request body

Example

Responses

Response body (201)

projects.get

Example

Responses

Response body (200)

projects.update

Request body

Example

Responses

Response body (200)

projects.checkRepoAccess

Query parameters

Example

Responses

Response body (200)

projects.delete

Example

Responses