Sign in

v71

latestOpenAPI 3.1.0raw.githubusercontent.com2026-08-0778281700.3 KB
domains

Create domain

Attach a custom domain to an environment and start verifying it.

The domain is created in the pending state and does not serve traffic until verification succeeds. Verification runs in the background and polls DNS, so it is eventually consistent.

The response returns dnsRecords: every record needed to finish setup, already resolved for whether this domain is an apex or a subdomain. Create every entry exactly as given. One record establishes routing and one proves ownership, and both are needed: whether ownership can be inferred from the routing record depends on how your provider publishes it, and a name another workspace has already verified can only be claimed through the ownership record. Neither is knowable before the records exist.

When your DNS provider supports Domain Connect, the response also carries a domainConnect object; opening its url applies the same records at the provider in one step. The object is absent when the shortcut is unavailable.

Domains are unique per workspace, so the same name cannot be attached to two environments. Attaching a domain that already exists in your workspace returns a 409 conflict.

How many domains you may attach is set by your plan. Attaching one beyond that allowance returns a 403; upgrade the plan or remove a domain you no longer need.

Important: verification stops after 24 hours without the required DNS records, and the domain moves to failed.

Required Permissions

Your root key must have one of the following permissions:

  • environment.*.create_domain (to attach domains to any environment)
  • environment.<environment_id>.create_domain (to attach domains to a specific environment)
post/v2/domains.createDomain

Request body

projectstring required

Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.

appstring required

Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.

environmentstring required

Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.

domainstring required

Fully qualified domain name to attach to the environment, without a scheme, port, or path. Must be unique across your entire workspace: the same name cannot be attached to two environments.

The name must sit under a registrable domain: 'api.acme.co.uk' is accepted, the public suffix 'co.uk' itself is not. Internationalized names may be sent in Unicode or Punycode form; either way the domain is stored and returned in its canonical form, lowercase ASCII with Unicode labels Punycode encoded, and the DNS records in the response use that form.

Example request

{
  "project": "proj_1234abcd",
  "app": "proj_1234abcd",
  "environment": "proj_1234abcd",
  "domain": "api.acme.com"
}

Response

Domain created and verification started. The domain is pending until the DNS records resolve.

Example response

{
  "meta": {
    "requestId": "req_123"
  },
  "data": {
    "domainId": "proj_1234abcd",
    "dnsRecords": [
      {
        "type": "CNAME",
        "name": "api.acme.com",
        "value": "a1b2c3d4e5f6g7h8.cname.unkey.com",
        "ttl": 60,
        "note": "Create as DNS-only if your provider offers the choice."
      }
    ],
    "domainConnect": {
      "provider": "Cloudflare",
      "url": "https://dash.cloudflare.com/domainconnect/v2/domaintemplates/apply?domain=acme.com&host=api"
    }
  }
}