Domains

Model

Fields

Field

Type

Description
object
"domain"
id
string Unique identifier, prefixed with dom_.
team_id
string
domain
string The hostname the customer added, stored lowercase.
ownership_type
The record proving the customer controls this hostname. Always a TXT at _tailglow-verify.{domain}, required even for a domain with no purpose, which needs nothing else. Verification is per-hostname: it proves nothing about the parent domain or a sibling.
ownership_name
string
ownership_value
string
ownership_status
What the last lookup found. unchecked means no lookup has run yet, which is different from missing (looked up, definitively not there).
ownership_actual
string | null What DNS actually returned. Null when the record is absent or has not been looked up.
ownership_checked_at
| null
ownership_verified
boolean Whether Tailglow currently treats the ownership record as good. True while it resolves, and it stays true for 24 hours after it stops so a brief DNS problem does not unverify a working domain.
ownership_failed_at
| null When the ownership record had been missing long enough that Tailglow stops serving the domain. Null while ownership holds, including during the grace period that follows a failed check.
routing_type
| null The record routing traffic to Tailglow, or null while the domain has no purpose and so asks for no record. Always a CNAME at the hostname itself.
routing_name
string | null
routing_value
string | null
routing_status
What the last lookup found. A routing record whose target has since moved reads as unchecked: the stored answer described the old target, so it says nothing about the current one.
routing_actual
string | null
routing_checked_at
| null
routing_verified
boolean Whether Tailglow currently treats the routing record as good. True while it resolves, and it stays true for seven days after it stops so a DNS change in progress does not take a live domain out of service.
certificate_status
Progress of the TLS certificate Tailglow provisions once routing is verified.
certificate_error
string | null Why the last certificate attempt failed; null unless certificate_status is failed.
certificate_provisioned_at
| null When the current certificate was issued.
purpose
| null What this domain serves, or null when it serves nothing yet. A domain serves ingest traffic or status pages, never both.
is_sso_enabled
boolean Whether members with an email at this domain sign in through SSO. Adds no DNS record.
lifecycle_action
| null Infrastructure work Tailglow is currently doing for this domain; null when idle.
lifecycle_status
| null How that work is progressing.
lifecycle_error
string | null Why the last attempt failed. Tailglow retries automatically.
last_checked_at
| null When this domain was last checked. A domain can be checked once every 30 seconds; per-record timing lives on ownership_checked_at and routing_checked_at.
created_at
updated_at
updated_by
string | null The user who last changed this domain.

List Domains

Endpoint

Retrieve a list of custom domains for the current team.

domains:read
GET
/v1/domains

Query Parameters

Field

Type

Description
order_by
string Field used to order the domains. Defaults to "created_at". Accepted values: "created_at","domain","certificate_status".
ownership_verified
string Filter domains by ownership verification state. Accepted values: "true","false".
certificate_status
Filter domains by the status of their TLS certificate.
limit
number Maximum number of items to return. Defaults to 25. Minimum: 1. Maximum: 200.
after
string Cursor from pagination.next_cursor of a previous response. Returns the resources after that page.
before
string Cursor from pagination.prev_cursor of a previous response. Returns the resources before that page.
sort
string Sort direction for the result set. Defaults to "desc". Accepted values: "asc","desc".

Comments

  • ownership_verified accepts the strings true and false. Any other value is rejected.
  • after and before are mutually exclusive.

Response

200 
{
  message: string;
  data: Domain[];
  status: 200;
  error: null;
  pagination: Pagination;
  endpoint: string;
}

Retrieve Domain

Endpoint

Retrieve a single custom domain, including the DNS records needed to verify and route it.

domains:read
GET
/v1/domains/:domain_id

Path Parameters

Field

Type

Description
domain_id
string Unique identifier of the domain.

Response

200 
{
  message: string;
  data: Domain;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Create Domain

Endpoint

Add a custom domain to the current team.

domains:write
POST
/v1/domains

Request Body

Field

Type

Requirement

Description
domain
string
Required
The custom domain to add, for example analytics.example.com. Stored in lowercase. Minimum length: 1. Maximum length: 255.
purpose
Optional
Traffic purpose to configure for this domain. Use ingest to receive analytics data, or pages to serve status pages. Leave it out to add the domain without a purpose and choose one later.

Comments

  • The number of custom domains a team can add is limited by its billing plan.
  • A hostname can only be registered once. Adding one that already exists returns a conflict.
  • Some hostnames are reserved and cannot be added.
  • domain cannot contain a wildcard (*). Add each hostname you want to serve as its own domain.
  • domain must be a valid hostname such as analytics.example.com. Labels may contain letters, digits and hyphens, cannot start or end with a hyphen, and the top level domain must be at least two letters.

Response

201 
{
  message: string;
  data: Domain;
  status: 201;
  error: null;
  pagination: null;
  endpoint: string;
}

Check Domain DNS

Endpoint

Look up every DNS record this domain needs and report what is currently there.

domains:write
POST
/v1/domains/:domain_id/check

Path Parameters

Field

Type

Description
domain_id
string Unique identifier of the domain.

Comments

  • A check that completes always returns 200. A record that does not resolve is a result, not an error, so read the outcome from ownership_status and routing_status rather than the status code.
  • Ownership is checked first. Routing is only checked once ownership has been verified and the domain has a traffic purpose enabled.
  • A record that has never been looked up reports unchecked, which is not the same as missing.
  • A domain can be checked at most once every 30 seconds.

Response

200 
{
  message: string;
  data: Domain;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Update Domain

Endpoint

Update a domain's traffic purpose or SSO assignment.

domains:write
POST
/v1/domains/:domain_id

Path Parameters

Field

Type

Description
domain_id
string Unique identifier of the domain.

Request Body

Field

Type

Requirement

Description
purpose
Optional
What this domain serves. Ownership must be verified before a purpose can be set, and null takes the domain out of service. Omit to leave it unchanged.
is_sso_enabled
boolean
Optional
Whether SSO is assigned to this domain.

Comments

  • Domain ownership must be verified before a purpose can be set.
  • A domain serves either ingest traffic or pages. Send purpose: null to take it out of service before setting the other, rather than switching between them directly.
  • Setting purpose to null queues infrastructure teardown. The domain keeps reporting its old purpose until that work completes.
  • Only one lifecycle operation runs at a time. If another is in progress, retry shortly.

Response

200 
{
  message: string;
  data: Domain;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Delete Domain

Endpoint

Delete a custom domain from the current team.

domains:delete
DELETE
/v1/domains/:domain_id

Path Parameters

Field

Type

Description
domain_id
string Unique identifier of the domain.

Comments

  • Deletion runs in the background. The domain remains listed with a pending lifecycle state until its edge configuration has been removed.

Response

202 
{
  message: string;
  data: null;
  status: 202;
  error: null;
  pagination: null;
  endpoint: string;
}

Referenced Types

ISODateString

An ISO 8601 date-time string returned at the JSON API boundary.

DnsRecordType

txt
cname

DnsRecordStatus

unchecked
valid
invalid
missing
unavailable

CertificateStatus

none
provisioning
active
failed

DomainTrafficPurpose

ingest
pages

What a domain serves. Stored on the domain.

DomainLifecycleAction

attach
reconcile
disable_ingest
disable_pages
delete_domain
delete_team

DomainLifecycleStatus

pending
processing
failed