Deploys

Deployments — build and release a project from a git ref.

deploys.create

Queue a new deployment of the project. 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
`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 '{
  "gitRepo": "acme/storefront",
  "gitRef": "main",
  "environment": "example"
}'

Responses

Status	Description
`202`	Deployment accepted.
`402`	Organization billing is not active.
`404`	No such project or environment in this organization.
`422`	Invalid gitRepo, gitRef, or environment — including deploys addressed to the preview environment.

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.

Getting started

Agents

Primitives

API reference

CLI reference

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.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.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)