Domains

Custom domains. Point a domain you own at a project environment: add it, create the returned CNAME record, then check until it goes active.

domains.list

List all the project’s custom domains across every environment, each annotated with the environment it routes to and its verification status.

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

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

Responses

Status	Description
`200`	Custom domains, oldest first.
`404`	No such project in this organization.

Response body (200)

An array of objects with these fields:

Field	Type	Description
`id`	string	—
`hostname`	string	Pattern: `^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,}$`.
`environment`	string	Slug of the environment this domain routes to. Pattern: `^[a-z][a-z0-9-]{0,38}$`.
`status`	string	Verification state: pending_dns until the CNAME points at the platform, pending_ssl while the certificate is issued, then active. failed is terminal. One of: `pending_dns`, `pending_ssl`, `active`, `failed`.
`verificationErrors`	string or null	Why verification is stuck, when the edge reported a reason.
`createdAt`	string	Format: `date-time`.

domains.add

Add a custom domain to a project environment (production by default) and get the CNAME record to create.

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

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
`hostname`	string	Yes	Hostname you control, e.g. “app.acme.com”. Pattern: `^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,}$`.
`environment`	string	No	Environment the domain routes to. Defaults to “production”. An environment that does not exist on the project answers 404. The preview environment answers 422: preview apps are ephemeral per-pull-request deployments, so a stable hostname can never attach to them. Pattern: `^[a-z][a-z0-9-]{0,38}$`.

Example

curl -X POST "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/domains" \
  -H "Authorization: Bearer korve_..." \
  -H "Content-Type: application/json" \
  -d '{
  "hostname": "app.acme.com",
  "environment": "example"
}'

Responses

Status	Description
`201`	Domain registered. Create the CNAME from the instructions, then check the domain until it goes active.
`402`	Organization billing is not active.
`404`	No such project or environment in this organization.
`409`	That hostname is already in use on the platform.
`422`	Invalid hostname, a managed platform hostname, or the preview environment (preview apps are per-pull-request — domains cannot attach to them).
`502`	Registering the domain at the edge failed; nothing was added.

Response body (201)

Field	Type	Description
`id`	string	—
`hostname`	string	Pattern: `^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,}$`.
`environment`	string	Slug of the environment this domain routes to. Pattern: `^[a-z][a-z0-9-]{0,38}$`.
`status`	string	Verification state: pending_dns until the CNAME points at the platform, pending_ssl while the certificate is issued, then active. failed is terminal. One of: `pending_dns`, `pending_ssl`, `active`, `failed`.
`verificationErrors`	string or null	Why verification is stuck, when the edge reported a reason.
`createdAt`	string	Format: `date-time`.
`instructions`	string	DNS setup step. Production domains target the project’s managed subdomain, e.g. “CNAME app.acme.com → my-app.korve.app”; domains on other environments target that environment’s own subdomain, e.g. “CNAME staging.acme.com → my-app-staging.korve.app”.

domains.check

Re-check the domain’s DNS and certificate verification and return its current status.

POST /v1/orgs/{orgId}/projects/{projectId}/domains/{domainId}/check

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

Example

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

Responses

Status	Description
`200`	The domain with its refreshed status.
`404`	No such domain on this project.
`502`	The edge could not be reached; the stored status is unchanged.

Response body (200)

Field	Type	Description
`id`	string	—
`hostname`	string	Pattern: `^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,}$`.
`environment`	string	Slug of the environment this domain routes to. Pattern: `^[a-z][a-z0-9-]{0,38}$`.
`status`	string	Verification state: pending_dns until the CNAME points at the platform, pending_ssl while the certificate is issued, then active. failed is terminal. One of: `pending_dns`, `pending_ssl`, `active`, `failed`.
`verificationErrors`	string or null	Why verification is stuck, when the edge reported a reason.
`createdAt`	string	Format: `date-time`.

domains.remove

Remove a custom domain. Traffic to it stops being served.

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

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

Example

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

Responses

Status	Description
`200`	Domain removed.
`404`	No such domain on this project.
`502`	Removing the domain at the edge failed; the domain was kept.

Getting started

Agents

Primitives

API reference

CLI reference

domains.list

Example

Responses

Response body (200)

domains.add

Request body

Example

Responses

Response body (201)

domains.check

Example

Responses

Response body (200)

domains.remove

Example

Responses

​domains.list

​Example

​Responses

​Response body (200)

​domains.add

​Request body

​Example

​Responses

​Response body (201)

​domains.check

​Example

​Responses

​Response body (200)

​domains.remove

​Example

​Responses

domains.list

Example

Responses

Response body (200)

domains.add

Request body

Example

Responses

Response body (201)

domains.check

Example

Responses

Response body (200)

domains.remove

Example

Responses