UNunkeyed
domains

List domains

Changed on

List your custom domains with their verification status and DNS records. Filter by project, app, or environment using IDs or slugs, or send {} to list domains across your workspace.

Use any filter on its own or combine filters to narrow the results. Results match all supplied filters. Omitting environment includes all matching environments.

Results include only domains you have permission to read, sorted by ID. When hasMore is true, send the returned cursor to get the next page.

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

Use a root key with the environment.*.read_domain permission. A successful request returns an empty list if no matching domains are readable by your key.

post/v2/domains.listDomains

Request

  • Base URL
    https://api.unkey.com
  • URL
    https://api.unkey.com/v2/domains.listDomains
  • Auth
    HTTP bearer

Request body

projectstring

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

appstring

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

environmentstring

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 permitted domains that match every filter. Missing or mismatched filtered resources return an empty list.

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."
        }
      ],
      "domainConnect": {
        "provider": "Cloudflare",
        "url": "https://dash.cloudflare.com/domainconnect/v2/domaintemplates/apply?domain=acme.com&host=api"
      },
      "createdAt": 1704067200000,
      "updatedAt": 1704153600000
    }
  ],
  "pagination": {
    "cursor": "eyJrZXkiOiJrZXlfMTIzNCIsInRzIjoxNjk5Mzc4ODAwfQ==",
    "hasMore": true
  }
}

Changes

  • d96874293728Revision changes
    • breaking

      added to the request property allOf list

    • breaking

      added to the request property allOf list

    • breaking

      added to the request property allOf list

    • breaking

      the request property type changed from string to no type

    • breaking

      the request property type changed from string to no type

    • breaking

      the request property type changed from string to no type

    • info

      the request property became optional

    • info

      the request property became optional

    • info

      the request property became optional

    • info

      the request property's minLength was decreased from 3 to 0

    • info

      the request property's minLength was decreased from 3 to 0

    • info

      the request property's minLength was decreased from 3 to 0

    • info

      removed the pattern ^[a-zA-Z0-9_-]+$ from the request property

    • info

      removed the pattern ^[a-zA-Z0-9_-]+$ from the request property

    • info

      removed the pattern ^[a-zA-Z0-9_-]+$ from the request property

    • info

      added the non-success response with the status

  • 88223a6be548Revision changes
    • info

      added the optional property // to the response with the status