Connections

Check a connection's DNS now, and report what public DNS answered

Resolves every record the connection is verified against in-request, against live public DNS, and returns a per-record verdict. This is the verb behind a "check now" button, as opposed to GET /connections/{id}, which only reports what the background propagation poller last saw.

It also advances the connection: a pending or propagating connection whose records are all visible is promoted to live here rather than on the poller's next pass, and a failed connection is re-entered into verification (failed → pending) with its lifecycle timeout clock re-based off the retry. Without that re-basing the retry would re-fail immediately, since the connection is failed precisely because it aged past that window. A live connection is reported on but never transitioned: records_resolved: false on a live connection is a drift signal.

Idempotent and safe to call repeatedly.

A delegated agent token needs domains:connect, because a recheck can move a connection forward.

post/connections/{id}:recheck

Request

  • Base URL: https://api.customdomain.ai/v1
  • URL: https://api.customdomain.ai/v1/connections/{id}:recheck
  • Auth: one of:
    • HTTP bearer
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.customdomain.ai/oauth/agent/authorize, token URL https://api.customdomain.ai/oauth/agent/token, scopes: domains:connect)

Path parameters

idstring required

Response

The connection after the check, plus what the check found.

idstring required
application_idstring required
domainstring required
hoststring

subdomain label; empty means the apex

provider_idstring

detected / applied DNS provider

setup_type'automatic' | 'manual' | 'async' | 'mcp' required

How a connection reaches live.

status'pending' | 'propagating' | 'live' | 'failed' required
managedboolean

true when the connection opted into managed mode: the control plane holds a durable, encrypted async grant and can re-apply (POST /v1/connections/{id}:reapply) or revert (DELETE /v1/connections/{id}) the template server-side without re-consent. Omitted (treated as false) for the default use-once connection.

created_atstring date-time required
sandboxboolean

true when the connection belongs to a test mode application. Its DNS is simulated, nothing real is read, written or served, and it counts for nothing (no free domain, quota, billing or metering). Copied from the application at create and never changed. Omitted (treated as false) on a real connection.

last_checked_atstring date-time

When the propagation poller last examined this connection. Omitted until the first check.

www_redirectboolean

Serve an apex↔www redirect. Echoed from create.

override_spfboolean

Replace an existing SPF record instead of merging into it, where the provider supports it. Echoed from create.

validate_dmarcboolean

Stored and echoed from create; not acted on yet.

validate_caaboolean

Whether the Let's Encrypt CAA records are part of the desired record set. Echoed from create.

monitorboolean

Whether the domain is enrolled in drift monitoring. Echoed from create, where it defaults to true when omitted, and honoured: the drift watch is registered when the connection goes live only if this is true. Connections created before the flag was honoured read true (they were monitored unconditionally, and were backfilled), so this is false only where a caller explicitly opted out.

batch_idstring

The multi-domain session this connection was created in. Omitted for a standalone connect.

end_user_refstring

The integrator's own identifier for the end user who connected this domain. Omitted for a console/direct connect.

retried_atstring date-time

When a human (or the create-path resume, or real edge traffic) last asked for this connection to be re-verified. The retry clock is max(created_at, retried_at): a revived connection gets a fresh window from here, not from its original creation. Absent when it was never retried.

records_source'integrator'

Present as integrator when the connection's desired record set was supplied through PUT /v1/connections/{id}/records rather than authored by us. Omitted for the usual server-synthesized or Domain Connect template-materialized set. Such a connection cannot use the Domain Connect rail, which applies our published templates at the provider.

created_via'' | 'widget' | 'console' | 'api' | 'agent' | 'mcp'

Where the connection was created, recorded once at create and never changed. widget: an end user's connect-scoped widget token (the embedded widget in your product). console: the CustomDomain™ console. api: an API key, or an app-scoped token, from your server. agent: a delegated agent access token. mcp: the MCP server. Empty for connections created before this was recorded. A trusted server-side caller may name its surface with the X-CustomDomain-Client request header (console or mcp); the header is a label only and grants nothing.

secure_root_domainboolean

The edge also issues/secures the registrable apex alongside this subdomain connection. Omitted (treated as false) when unset.

redirect_tostring uri

URL the edge 301s this host to (Power redirect target). Omitted when the connection is not a redirect.

power_root_path_accessstring[]

URL paths the edge may static-serve at the root (Power root-path access). Omitted when none are configured.

error_codestring

The last failure reason recorded for this connection, from whichever path failed, not only the background poller. It is persisted by: the propagation poller / :recheck verification (e.g. propagation_timeout, setup_incomplete, pending_expired, domain_already_connected); the foreground apply on POST /connections/{id}/apply (e.g. dns_write_failed, ProviderAuthenticationError, spf_merge_failed, apex_not_supported, forwarding_not_supported); the OAuth callback (which also records forwarding_not_supported); and the Domain Connect async callback (both e.g. provider_unavailable, ProviderAuthenticationError, apply_failed, internal_error, or the provider's own error parameter). Rejected request validation (400) is deliberately NOT recorded here: a malformed request is not a connection failure. Omitted when healthy or never failed; cleared when the connection next verifies.

error_messagestring

Human-readable detail for error_code. Populated on the same paths and cleared alongside it. Omitted when there is none.

write_rail'api_key' | 'sign_in' | 'domain_connect' | 'domain_connect_async' | 'route53_role' | 'provider_account' | 'managed_dns'

The rail that last wrote this connection's records. Omitted when no rail wrote them (a manual setup, or a connection from before this was recorded). It decides what removing the domain can do with the records (GET /connections/{id}/removal).

provider_account_idstring

The connected provider account whose credential wrote this connection's records and, when the account's access is continuous, keeps them (repairs and removal). Omitted when none.

removal_started_atstring date-time

Set while the domain is being removed: the records are being taken out and the connection is deleted when that finishes. The domain no longer serves from this moment. Omitted otherwise.

end_user_emailstring email

The end user's email address, when one was given and the feature is on. Present only on the response of the call that created the connection with it, and on GET /connections/{id} with an API key. Never in a list, a webhook, or any read by a widget token.

ask_end_user_emailboolean

Present (true) on a create response only when the widget should offer the end user an optional email field: the feature is on, the caller is a widget token, the domain is not a test domain and the connection has no address yet. The widget then calls PUT /connections/{id}/end-user-email. Omitted otherwise.

records_resolvedboolean required

True only when EVERY entry in checked resolved. An empty checked is false: nothing to verify is not "everything verified".

retriedboolean required

True when this call re-entered a failed connection into verification (re-basing its timeout clock), rather than re-checking a connection that was already in flight.

previous_status'pending' | 'propagating' | 'live' | 'failed' required

The status the connection held when the request arrived.

Example response

{
  "records": [
    {
      "type": "CNAME"
    }
  ],
  "checked": [
    {
      "type": "CNAME"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.