Custom Domains API Reference

#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.

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

name

string

The domain name

status

string (enum)

The status of a custom domain

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

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": "2025-10-30T16:02:51.633Z",
  "createdAt": "2025-10-30T16:02:51.633Z",
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "lastCheckedAt": "2025-10-30T16:02:51.633Z",
  "name": "example.com",
  "status": "STATUS_ACTIVE",
  "updatedAt": "2025-10-30T16:02:51.633Z",
  "workspaceId": "d290f1ee-6c54-4b01-90e6-d701748f0851"
}

GET/v1/custom-domainsRequires auth

#List custom domains

Retrieves the custom domains for your workspace

#Parameters

query parameters

status

stringquery

Filter by the status of the custom domains to list. Optional.

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

#Response

200

Everything worked as expected.

customDomains

array<object>

#Error response

400-599

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

error

objectRequired

Wrapped error response.

Example request (cURL)

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

Typical response

{
  "customDomains": [
    {
      "activatedAt": "2025-10-30T16:02:51.614Z",
      "createdAt": "2025-10-30T16:02:51.614Z",
      "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "lastCheckedAt": "2025-10-30T16:02:51.614Z",
      "name": "example.com",
      "status": "STATUS_ACTIVE",
      "updatedAt": "2025-10-30T16:02:51.614Z",
      "workspaceId": "d290f1ee-6c54-4b01-90e6-d701748f0851"
    }
  ]
}

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

stringRequiredpath

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

objectRequired

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": "2025-10-30T16:02:51.616Z",
    "createdAt": "2025-10-30T16:02:51.616Z",
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "lastCheckedAt": "2025-10-30T16:02:51.616Z",
    "name": "example.com",
    "status": "STATUS_ACTIVE",
    "updatedAt": "2025-10-30T16:02:51.616Z",
    "workspaceId": "d290f1ee-6c54-4b01-90e6-d701748f0851"
  }
}

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

GET/v1/custom-domains/{id}/validation_instructionsRequires 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

stringRequiredpath

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

objectRequired

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-domainsRequires 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

objectRequired

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": "2025-10-30T16:02:51.615Z",
    "createdAt": "2025-10-30T16:02:51.615Z",
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "lastCheckedAt": "2025-10-30T16:02:51.615Z",
    "name": "example.com",
    "status": "STATUS_ACTIVE",
    "updatedAt": "2025-10-30T16:02:51.616Z",
    "workspaceId": "d290f1ee-6c54-4b01-90e6-d701748f0851"
  }
}

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

POST/v1/custom-domains/{id}/checkRequires 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

stringRequiredpath

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

objectRequired

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": "2025-10-30T16:02:51.616Z",
    "createdAt": "2025-10-30T16:02:51.616Z",
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "lastCheckedAt": "2025-10-30T16:02:51.616Z",
    "name": "example.com",
    "status": "STATUS_ACTIVE",
    "updatedAt": "2025-10-30T16:02:51.616Z",
    "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

stringRequiredpath

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

objectRequired

Wrapped error response.