> ## Documentation Index > Fetch the complete documentation index at: https://docs.korve.dev/llms.txt > Use this file to discover all available pages before exploring further. # 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. 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. ```text theme={null} GET /v1/orgs/{orgId}/projects/{projectId}/domains ``` * **Auth:** Organization API key (`Authorization: Bearer korve_...`) or dashboard session. * **Minimum role:** `member` * **Risk:** `read` ### Example ```bash theme={null} 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. ```text theme={null} 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 ```bash theme={null} 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. ```text theme={null} 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 ```bash theme={null} 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. ```text theme={null} 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 ```bash theme={null} 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. |