Deploys

Deployments — build and release a project from a git ref or an uploaded source.

deploys.createSource

Create a short-lived signed URL for uploading a project’s source as a gzipped tar archive. Upload the archive with PUT, then pass the returned key to deploys.create as sourceKey to build and release it — no connected repository required. Ideal for deploying a local directory.

POST /v1/orgs/{orgId}/projects/{projectId}/deploys/sources

Auth: Organization API key (Authorization: Bearer korve_...) or dashboard session.
Minimum role: member
Billing: requires active organization billing — returns 402 otherwise.
Risk: write · sensitive (elevated blast radius)

Request body

Field	Type	Required	Description
`byteLength`	integer	Yes	Exact size of the gzipped tar archive in bytes.

Example

curl -X POST "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/deploys/sources" \
  -H "Authorization: Bearer korve_..." \
  -H "Content-Type: application/json" \
  -d '{
  "byteLength": 24576
}'

Responses

Status	Description
`201`	Signed upload. PUT the archive bytes to the URL before it expires.
`402`	Organization billing is not active.
`404`	No such project in this organization.
`422`	Invalid archive size.

Response body (201)

Field	Type	Description
`key`	string	Opaque source key — pass it to deploys.create as sourceKey.
`url`	string	—
`method`	string	One of: `PUT`.
`headers`	object	Headers that must accompany the upload request. Map of string values.
`expiresAt`	string	Format: `date-time`.

deploys.create

Queue a new deployment of the project from a git ref or an uploaded source archive (sourceKey). Defaults to the production environment; custom environments deploy to their own managed subdomain (“https://<project-slug>-<environment>.korve.app”).

POST /v1/orgs/{orgId}/projects/{projectId}/deploys

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

Request body (optional)

Field	Type	Required	Description
`sourceKey`	string	No	Key of an uploaded source archive from deploys.createSource. Builds that uploaded source instead of a repository; takes precedence over gitRepo.
`gitRepo`	string	No	Source repository as “owner/repo”. Pattern: `^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$`.
`gitRef`	string	No	Branch, tag, or commit. Defaults to main.
`environment`	string	No	Environment to deploy to. Defaults to “production”. An environment that does not exist on the project answers 404. Preview deployments are created from pull requests, never here. Pattern: `^[a-z][a-z0-9-]{0,38}$`.

Example

curl -X POST "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/deploys" \
  -H "Authorization: Bearer korve_..." \
  -H "Content-Type: application/json" \
  -d '{}'

Responses

Status	Description
`202`	Deployment accepted.
`402`	Organization billing is not active.
`404`	No such project or environment in this organization.
`422`	Invalid sourceKey, gitRepo, gitRef, or environment — including deploys addressed to the preview environment or repositories outside this organization’s installation.
`502`	Repository access could not be verified — try again.

Response body (202)

Field	Type	Description
`id`	string	—
`status`	string	One of: `queued`, `building`, `deploying`, `ready`, `failed`.

deploys.rollback

Roll back to an earlier successful deployment. Queues a new deployment to the same environment the target deployed to, pinned to the target’s exact commit (not its branch), and builds it through the normal pipeline. Only deployments that are “ready” and carry a recorded commit can be rolled back to.

POST /v1/orgs/{orgId}/projects/{projectId}/deploys/{deployId}/rollback

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

Example

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

Responses

Status	Description
`202`	Rollback deployment accepted.
`402`	Organization billing is not active.
`404`	No such deployment in this project.
`422`	Only successful deployments with a recorded commit can be rolled back to.

Response body (202)

Field	Type	Description
`id`	string	—
`status`	string	One of: `queued`, `building`, `deploying`, `ready`, `failed`.

deploys.list

List the project’s deployments, newest first.

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

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/deploys" \
  -H "Authorization: Bearer korve_..."

Responses

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

Response body (200)

An array of objects with these fields:

Field	Type	Description
`id`	string	—
`status`	string	One of: `queued`, `building`, `deploying`, `ready`, `failed`.
`environment`	string or null	Slug of the environment the deployment targets. Null only for deployments that predate environment tracking.
`trigger`	object or null	What queued the deployment. Null for deployments that predate trigger tracking.
`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`.
`trigger.actor`	object	Who triggered it — present for repository-driven deploys.
`trigger.actor.login`	string	—
`trigger.actor.avatarUrl`	string or null	—
`gitRepo`	string or null	Source repository as “owner/repo”; null for non-git deploys.
`gitRef`	string	—
`commitSha`	string or null	—
`createdAt`	string	Format: `date-time`.
`finishedAt`	string or null	Format: `date-time`.
`error`	string or null	—

deploys.get

Get one deployment including its build log.

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

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/deploys/$DEPLOY_ID" \
  -H "Authorization: Bearer korve_..."

Responses

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

Response body (200)

Field	Type	Description
`id`	string	—
`status`	string	One of: `queued`, `building`, `deploying`, `ready`, `failed`.
`environment`	string or null	Slug of the environment the deployment targets. Null only for deployments that predate environment tracking.
`trigger`	object or null	What queued the deployment. Null for deployments that predate trigger tracking.
`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`.
`trigger.actor`	object	Who triggered it — present for repository-driven deploys.
`trigger.actor.login`	string	—
`trigger.actor.avatarUrl`	string or null	—
`gitRepo`	string or null	Source repository as “owner/repo”; null for non-git deploys.
`gitRef`	string	—
`commitSha`	string or null	—
`createdAt`	string	Format: `date-time`.
`finishedAt`	string or null	Format: `date-time`.
`error`	string or null	—
`buildLog`	string	Accumulated build output.

deploys.diagnose

Ask the platform agent to diagnose a failed deployment. The diagnosis is cached after the first call; only failed deployments are diagnosable.

POST /v1/orgs/{orgId}/projects/{projectId}/deploys/{deployId}/diagnosis

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

Example

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

Responses

Status	Description
`200`	The diagnosis — freshly produced or served from the cache.
`402`	Organization billing is not active.
`404`	No such deployment in this project.
`409`	The deployment did not fail, so there is nothing to diagnose.
`502`	The platform agent could not analyze this deploy — try again.

Response body (200)

Field	Type	Description
`diagnosis`	object	Structured failure diagnosis produced by the platform agent.
`diagnosis.summary`	string	1-2 sentence plain-language explanation of what went wrong.
`diagnosis.probableCause`	string	—
`diagnosis.suggestedFix`	object	—
`diagnosis.suggestedFix.kind`	string	One of: `env`, `code`, `config`, `retry`.
`diagnosis.suggestedFix.title`	string	—
`diagnosis.suggestedFix.detail`	string	—
`diagnosis.suggestedFix.commands`	string[]	Optional shell commands to apply the fix.
`diagnosis.confidence`	string	One of: `low`, `medium`, `high`.
`cached`	boolean	True when a previously stored diagnosis was returned.

Start

Core concepts

Agents

Build

Data and work

Operate

CLI reference

API reference

deploys.createSource

Request body

Example

Responses

Response body (201)

deploys.create

Request body (optional)

Example

Responses

Response body (202)

deploys.rollback

Example

Responses

Response body (202)

deploys.list

Example

Responses

Response body (200)

deploys.get

Example

Responses

Response body (200)

deploys.diagnose

Example

Responses

Response body (200)

​deploys.createSource

​Request body

​Example

​Responses

​Response body (201)

​deploys.create

​Request body (optional)

​Example

​Responses

​Response body (202)

​deploys.rollback

​Example

​Responses

​Response body (202)

​deploys.list

​Example

​Responses

​Response body (200)

​deploys.get

​Example

​Responses

​Response body (200)

​deploys.diagnose

​Example

​Responses

​Response body (200)

deploys.createSource

Request body

Example

Responses

Response body (201)

deploys.create

Request body (optional)

Example

Responses

Response body (202)

deploys.rollback

Example

Responses

Response body (202)

deploys.list

Example

Responses

Response body (200)

deploys.get

Example

Responses

Response body (200)

deploys.diagnose

Example

Responses

Response body (200)