Sign in

v71

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

List domains

List the custom domains attached to an environment and their verification status.

Results are paginated and sorted by their id. When hasMore is true, send the returned cursor to get the next page. An environment with no domains returns an empty array, not a 404.

status: verified means the domain is verified. Unkey has configured routing and requested a certificate. Each domain includes its full dnsRecords. Each record has a verified flag. The flag shows which records Unkey has read back, so you can see which records are still missing without a second call. Some providers hide a record from DNS lookups, for example a proxied or flattened routing record. Such a record stays false while it serves traffic.

Required Permissions

Your root key must have one of the following permissions:

  • environment.*.read_domain (to read domains in any environment)
  • environment.<environment_id>.read_domain (to read domains in a specific environment)
post/v2/domains.listDomains

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.

limitinteger

The maximum number of domains one response contains. A small limit makes the response smaller, but makes more requests necessary.

cursorstring

The pagination cursor from the response that came before. Send it to get the next page when that response has hasMore: true.

searchstring

Free-form text to filter domains. Returns domains whose ID or name contains the search string. Matching is case-insensitive.

Example request

{
  "project": "proj_1234abcd",
  "app": "proj_1234abcd",
  "environment": "proj_1234abcd",
  "cursor": "dom_1234abcd",
  "search": "acme.com"
}

Response

Successfully retrieved the environment's domains.

Example response

{
  "meta": {
    "requestId": "req_123"
  },
  "data": [
    {
      "id": "proj_1234abcd",
      "domain": "api.acme.com",
      "projectId": "proj_1234abcd",
      "appId": "app_1234abcd",
      "environmentId": "env_1234abcd",
      "status": "verified",
      "verificationError": "domain verification timed out after 24 hours",
      "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."
        }
      ],
      "createdAt": 1704067200000,
      "updatedAt": 1704153600000
    }
  ],
  "pagination": {
    "cursor": "eyJrZXkiOiJrZXlfMTIzNCIsInRzIjoxNjk5Mzc4ODAwfQ==",
    "hasMore": true
  }
}