#The Custom Domain object

Captures a branded hostname that Linkbreakers provisions for a workspace so scans and shortlinks resolve under the customer's domain, including verification and certificate lifecycle state.

activatedAt

string (date-time)

Timestamp when the domain became active after passing verification and certificate checks.

certificateExpiresAt

string (date-time)

When the certificate currently serving this domain expires. While the status is STATUS_RENEWAL_PENDING the domain keeps working until this date, then stops.

cloudflareHostnameStatus

string

Raw hostname status reported by the certificate provider, recorded at the last check.

cloudflareSslStatus

string

Raw SSL status reported by the certificate provider, recorded at the last check.

createdAt

string (date-time)

Timestamp when the domain was created

string

Unique identifier for the custom domain (UUID)

lastCheckedAt

string (date-time)

Timestamp of the last verification check

lastError

string

Human-readable reason the domain is not fully active, as reported at the last check. Empty when the domain is healthy.

name

string

The domain name

rootDestination

string

URL where visitors are redirected when accessing your custom domain without a path (e.g., qr.yourdomain.com). This redirect is not tracked and serves purely for white-label purposes—preventing visitors from seeing linkbreakers.com branding. If not specified, redirects to linkbreakers.com by default.

status

string (enum)

The status of a custom domain of that certificate cannot be validated. It stops working at certificate_expires_at.

Allowed values

STATUS_UNSPECIFIED

The status is not specified

STATUS_INACTIVE

The domain is inactive. It was created but not checked yet.

STATUS_DOMAIN_PENDING

The domain is pending. Last time it was checked, it was not pointing to the correct Linkbreakers subdomain.

STATUS_VERIFICATION_PENDING

The domain is pending verification. Please verify through TXT record.

STATUS_CERTIFICATE_PENDING

The domain is pending certificate. The SSL certificate is not yet ready.

STATUS_ACTIVE

The domain is fully active

STATUS_RENEWAL_PENDING

The domain is still serving traffic on a valid certificate, but the renewal

STATUS_EXPIRED

The certificate expired or was withdrawn. The domain no longer serves HTTPS.

updatedAt

string (date-time)

Timestamp when the domain was last updated

workspaceId

string

The ID of the workspace this domain belongs to (UUID)

Learn more

Learn more about branded links in Linkbreakers.

Example object

{
  "activatedAt": "2026-10-05T03:43:09.970Z",
  "certificateExpiresAt": "2026-10-05T03:43:09.970Z",
  "cloudflareHostnameStatus": "active",
  "cloudflareSslStatus": "pending_validation",
  "createdAt": "2026-10-05T03:43:09.970Z",
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "lastCheckedAt": "2026-10-05T03:43:09.970Z",
  "lastError": "string",
  "name": "example.com",
  "rootDestination": "https://example.com",
  "status": "STATUS_ACTIVE",
  "updatedAt": "2026-10-05T03:43:09.970Z",
  "workspaceId": "d290f1ee-6c54-4b01-90e6-d701748f0851"
}

GET

/v1/custom-domains

Requires auth

#List custom domains

Retrieves the custom domains for your workspace

#Parameters

query parameters

status

string

query

Filter by the status of the custom domains to list. Optional. of that certificate cannot be validated. It stops working at certificate_expires_at.

Allowed values

STATUS_UNSPECIFIED

The status is not specified

STATUS_INACTIVE

The domain is inactive. It was created but not checked yet.

STATUS_DOMAIN_PENDING

The domain is pending. Last time it was checked, it was not pointing to the correct Linkbreakers subdomain.

STATUS_VERIFICATION_PENDING

The domain is pending verification. Please verify through TXT record.

STATUS_CERTIFICATE_PENDING

The domain is pending certificate. The SSL certificate is not yet ready.

STATUS_ACTIVE

The domain is fully active

STATUS_RENEWAL_PENDING

The domain is still serving traffic on a valid certificate, but the renewal

STATUS_EXPIRED

The certificate expired or was withdrawn. The domain no longer serves HTTPS.

pageSize

integer (int64)

query

Maximum number of custom domains to return. Defaults to 100, capped at 1000.

pageToken

string

query

Cursor from a previous response's next_page_token. Empty starts at the first page. Pages are ordered by (created_at, id), which never change, so a record cannot move between pages while a client is walking them.

#Response

200

Everything worked as expected.

customDomains

array<object>

nextPageToken

string

Cursor to continue listing custom domains. Empty on the last page.

totalCount

string (int64)

How many records exist in total, so a client can tell a complete answer from a page of one. A local-first client reads absence from this list as deletion, and may only do so when the count it was given matches what it received: without that, one page would look like the whole model and everything beyond it would be removed locally.

#Error response

400-599

All endpoints may return an unexpected error payload when a request cannot be processed.

error

object

Required

Wrapped error response.

Example request (cURL)

curl -X GET "https://api.linkbreakers.com/v1/custom-domains?status={status}&pageSize={pageSize}&pageToken={pageToken}" \
  -H "Authorization: Bearer YOUR_TOKEN"

Typical response

{
  "customDomains": [
    {
      "activatedAt": "2026-10-05T03:43:09.969Z",
      "certificateExpiresAt": "2026-10-05T03:43:09.969Z",
      "cloudflareHostnameStatus": "active",
      "cloudflareSslStatus": "pending_validation",
      "createdAt": "2026-10-05T03:43:09.969Z",
      "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "lastCheckedAt": "2026-10-05T03:43:09.969Z",
      "lastError": "string",
      "name": "example.com",
      "rootDestination": "https://example.com",
      "status": "STATUS_ACTIVE",
      "updatedAt": "2026-10-05T03:43:09.969Z",
      "workspaceId": "d290f1ee-6c54-4b01-90e6-d701748f0851"
    }
  ],
  "nextPageToken": "string",
  "totalCount": "string"
}

Base URL: https://api.linkbreakers.com

GET

/v1/custom-domains/{id}

Requires auth

#Get custom domain details

Retrieves information about a custom domain including its verification status and timestamps.

#Parameters

path parameters

string

Required

path

The ID of the custom domain to retrieve (UUID)

#Response

200

Everything worked as expected.

customDomain

object

Captures a branded hostname that Linkbreakers provisions for a workspace so scans and shortlinks resolve under the customer's domain, including verification and certificate lifecycle state.

#Error response

400-599

All endpoints may return an unexpected error payload when a request cannot be processed.

error

object

Required

Wrapped error response.

Example request (cURL)

curl -X GET "https://api.linkbreakers.com/v1/custom-domains/{id}" \
  -H "Authorization: Bearer YOUR_TOKEN"

Typical response

{
  "customDomain": {
    "activatedAt": "2026-10-05T03:43:09.969Z",
    "certificateExpiresAt": "2026-10-05T03:43:09.969Z",
    "cloudflareHostnameStatus": "active",
    "cloudflareSslStatus": "pending_validation",
    "createdAt": "2026-10-05T03:43:09.969Z",
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "lastCheckedAt": "2026-10-05T03:43:09.969Z",
    "lastError": "string",
    "name": "example.com",
    "rootDestination": "https://example.com",
    "status": "STATUS_ACTIVE",
    "updatedAt": "2026-10-05T03:43:09.969Z",
    "workspaceId": "d290f1ee-6c54-4b01-90e6-d701748f0851"
  }
}

Base URL: https://api.linkbreakers.com

GET

/v1/custom-domains/{id}/validation_instructions

Requires auth

#Get the validation instructions

Get the instructions for validating a custom domain. There may be a delay before the instructions are available.

#Parameters

path parameters

string

Required

path

The ID of the custom domain to retrieve (UUID)

#Response

200

Everything worked as expected.

validations

array<object>

The list of validations that need to be performed

#Error response

400-599

All endpoints may return an unexpected error payload when a request cannot be processed.

error

object

Required

Wrapped error response.

Example request (cURL)

curl -X GET "https://api.linkbreakers.com/v1/custom-domains/{id}/validation_instructions" \
  -H "Authorization: Bearer YOUR_TOKEN"

Typical response

{
  "validations": [
    {
      "name": "string",
      "purpose": "PURPOSE_UNSPECIFIED",
      "type": "TYPE_UNSPECIFIED",
      "value": "string"
    }
  ]
}

Base URL: https://api.linkbreakers.com

POST

/v1/custom-domains

Requires auth

#Create a custom domain

This endpoint allows users to register a new custom domain that can be used with their Linkbreakers workspace.

#Parameters

This endpoint does not accept any parameters.

#Request body

name

string

The domain name to register. It must be a valid DNS and not already registered in Linkbreakers. Subdomains are also supported.

#Response

200

Everything worked as expected.

customDomain

object

Captures a branded hostname that Linkbreakers provisions for a workspace so scans and shortlinks resolve under the customer's domain, including verification and certificate lifecycle state.

#Error response

400-599

All endpoints may return an unexpected error payload when a request cannot be processed.

error

object

Required

Wrapped error response.

Example request (cURL)

curl -X POST "https://api.linkbreakers.com/v1/custom-domains" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"name":"my-domain.com"}'

Sample payload (application/json)

{
  "name": "my-domain.com"
}

Typical response

{
  "customDomain": {
    "activatedAt": "2026-10-05T03:43:09.969Z",
    "certificateExpiresAt": "2026-10-05T03:43:09.969Z",
    "cloudflareHostnameStatus": "active",
    "cloudflareSslStatus": "pending_validation",
    "createdAt": "2026-10-05T03:43:09.969Z",
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "lastCheckedAt": "2026-10-05T03:43:09.969Z",
    "lastError": "string",
    "name": "example.com",
    "rootDestination": "https://example.com",
    "status": "STATUS_ACTIVE",
    "updatedAt": "2026-10-05T03:43:09.969Z",
    "workspaceId": "d290f1ee-6c54-4b01-90e6-d701748f0851"
  }
}

Base URL: https://api.linkbreakers.com

POST

/v1/custom-domains/{id}/check

Requires auth

#Check a custom domain

Check a custom domain by looking up its DNS records and TLS status. This is automatically done when the domain is created. It will update the domain status.

#Parameters

path parameters

string

Required

path

The ID of the custom domain to retrieve (UUID)

#Response

200

Everything worked as expected.

customDomain

object

Captures a branded hostname that Linkbreakers provisions for a workspace so scans and shortlinks resolve under the customer's domain, including verification and certificate lifecycle state.

#Error response

400-599

All endpoints may return an unexpected error payload when a request cannot be processed.

error

object

Required

Wrapped error response.

Example request (cURL)

curl -X POST "https://api.linkbreakers.com/v1/custom-domains/{id}/check" \
  -H "Authorization: Bearer YOUR_TOKEN"

Typical response

{
  "customDomain": {
    "activatedAt": "2026-10-05T03:43:09.970Z",
    "certificateExpiresAt": "2026-10-05T03:43:09.970Z",
    "cloudflareHostnameStatus": "active",
    "cloudflareSslStatus": "pending_validation",
    "createdAt": "2026-10-05T03:43:09.970Z",
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "lastCheckedAt": "2026-10-05T03:43:09.970Z",
    "lastError": "string",
    "name": "example.com",
    "rootDestination": "https://example.com",
    "status": "STATUS_ACTIVE",
    "updatedAt": "2026-10-05T03:43:09.970Z",
    "workspaceId": "d290f1ee-6c54-4b01-90e6-d701748f0851"
  }
}

Base URL: https://api.linkbreakers.com

PATCH

/v1/custom-domains/{id}

Requires auth

#Update a custom domain

Update settings for a custom domain, such as the root destination URL.

#Parameters

path parameters

string

Required

path

The ID of the custom domain to update (UUID)

#Request body

rootDestination

string

URL where visitors are redirected when accessing your custom domain without a path (e.g., qr.yourdomain.com). This redirect is not tracked and serves purely for white-label purposes—preventing visitors from seeing linkbreakers.com branding. Leave empty to redirect to linkbreakers.com by default.

#Response

200

Everything worked as expected.

customDomain

object

Captures a branded hostname that Linkbreakers provisions for a workspace so scans and shortlinks resolve under the customer's domain, including verification and certificate lifecycle state.

#Error response

400-599

All endpoints may return an unexpected error payload when a request cannot be processed.

error

object

Required

Wrapped error response.

Example request (cURL)

curl -X PATCH "https://api.linkbreakers.com/v1/custom-domains/{id}" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"rootDestination":"https://example.com"}'

Sample payload (application/json)

{
  "rootDestination": "https://example.com"
}

Typical response

{
  "customDomain": {
    "activatedAt": "2026-10-05T03:43:09.969Z",
    "certificateExpiresAt": "2026-10-05T03:43:09.969Z",
    "cloudflareHostnameStatus": "active",
    "cloudflareSslStatus": "pending_validation",
    "createdAt": "2026-10-05T03:43:09.969Z",
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "lastCheckedAt": "2026-10-05T03:43:09.969Z",
    "lastError": "string",
    "name": "example.com",
    "rootDestination": "https://example.com",
    "status": "STATUS_ACTIVE",
    "updatedAt": "2026-10-05T03:43:09.969Z",
    "workspaceId": "d290f1ee-6c54-4b01-90e6-d701748f0851"
  }
}

Base URL: https://api.linkbreakers.com

DELETE

/v1/custom-domains/{id}

Requires auth

#Delete a custom domain

Removes a custom domain from the workspace. This operation cannot be undone.

#Parameters

path parameters

string

Required

path

The ID of the custom domain to delete (UUID)

#Response

200

Everything worked as expected.

No structured schema available for this section.

#Error response

400-599

All endpoints may return an unexpected error payload when a request cannot be processed.

error

object

Required

Wrapped error response.

Custom Domains

#The Custom Domain object

Allowed values

#List custom domains

#Parameters

query parameters

Allowed values

#Response

#Error response

#Get custom domain details

#Parameters

path parameters

#Response

#Error response

#Get the validation instructions

#Parameters

path parameters

#Response

#Error response

#Create a custom domain

#Parameters

#Request body

#Response

#Error response

#Check a custom domain

#Parameters

path parameters

#Response

#Error response

#Update a custom domain

#Parameters

path parameters

#Request body

#Response

#Error response

#Delete a custom domain

#Parameters

path parameters

#Response

#Error response