REST API

Domains

Domains: 6 endpoints of the REST API.

GET/domains

List domains

The domains of this environment: its platform host first, then custom domains in the order they were added, each with status, verification times and the last check.

Secret key scope (any of): domains:write

Parameters

Field	Type	Description
`limit (query)`	`integer`	Items per page (1–100).
`cursor (query)`	`string`	`next_cursor` of the previous page; omit for the first page. A cursor only works with the sort order it was issued for.
`type (query)`	`"shared" \| "custom"`	Only shared or only custom domains.

Responses

200 A page of domains.

Field	Type	Description
`data`required	`object[]`
`data[].id`required	`string`
`data[].environment`required	`"test" \| "live"`
`data[].hostname`required	`string`	Normalized (lowercase, punycode) hostname.
`data[].type`required	`"shared" \| "custom"`	`shared` is the project host on the platform domain; `custom` is your own.
`data[].status`required	`"pending_dns" \| "verifying" \| "issuing_ssl" \| "active" \| "dns_misconfigured" \| "ssl_failed" \| "suspended"`	`pending_dns` (added, never checked), `verifying` (checked, ownership not proven yet), `issuing_ssl` (DNS is right, certificate pending), `active` (serves links), `dns_misconfigured` and `ssl_failed` (fix and re-verify), `suspended` (contact support).
`data[].dns_records`required	`object[] \| null`	The records to create for a custom domain (a CNAME to the edge host, or an A/AAAA record to its addresses, plus the ownership TXT); null for shared domains.
`data[].verified_at`required	`string (date-time) \| null`	When ownership was first proven; null until then.
`data[].last_checked_at`required	`string (date-time) \| null`
`data[].failed_check_count`required	`integer`	Consecutive failed checks.
`data[].failing_since`required	`string (date-time) \| null`
`data[].cert_expires_at`required	`string (date-time) \| null`
`data[].suspended_at`required	`string (date-time) \| null`
`data[].created_at`required	`string (date-time)`
`data[].updated_at`required	`string (date-time)`
`next_cursor`required	`string \| null`	Pass as `cursor` to get the next page; `null` on the last page.
`custom_domains_enabled`	`boolean`	Whether this deployment lets projects add custom domains. When false, adding one is a 403 `feature_disabled`, so clients can hide the action up front.

Example

Bash

curl -X GET "https://api.becklinks.com/v1/domains" \
  -H "Authorization: Bearer $SECRET_KEY"

POST/domains

Add a custom domain

Claims a domain or subdomain you own for this environment, e.g. go.acme.com. The response carries dns_records: a CNAME to the edge host and a TXT record with your verification token. Create them, then call verify.

A domain another project already holds is a 409 domain_taken, unless that claim never proved ownership and is older than 7 days. Not available unless the deployment enables custom domains (403 feature_disabled).

Secret key scope (any of): domains:write

Request body

Field	Type	Description
`hostname`required	`string`	The domain or subdomain to serve links on, e.g. `go.acme.com`. Normalized (lowercase, punycode); no scheme, path or port. Apex domains need a DNS provider with CNAME flattening (ALIAS/ANAME).

Responses

201 The pending domain.

Field	Type	Description
`id`required	`string`
`environment`required	`"test" \| "live"`
`hostname`required	`string`	Normalized (lowercase, punycode) hostname.
`type`required	`"shared" \| "custom"`	`shared` is the project host on the platform domain; `custom` is your own.
`status`required	`"pending_dns" \| "verifying" \| "issuing_ssl" \| "active" \| "dns_misconfigured" \| "ssl_failed" \| "suspended"`	`pending_dns` (added, never checked), `verifying` (checked, ownership not proven yet), `issuing_ssl` (DNS is right, certificate pending), `active` (serves links), `dns_misconfigured` and `ssl_failed` (fix and re-verify), `suspended` (contact support).
`dns_records`required	`object[] \| null`	The records to create for a custom domain (a CNAME to the edge host, or an A/AAAA record to its addresses, plus the ownership TXT); null for shared domains.
`verified_at`required	`string (date-time) \| null`	When ownership was first proven; null until then.
`last_checked_at`required	`string (date-time) \| null`
`failed_check_count`required	`integer`	Consecutive failed checks.
`failing_since`required	`string (date-time) \| null`
`cert_expires_at`required	`string (date-time) \| null`
`suspended_at`required	`string (date-time) \| null`
`created_at`required	`string (date-time)`
`updated_at`required	`string (date-time)`

Example

Bash

curl -X POST "https://api.becklinks.com/v1/domains" \
  -H "Authorization: Bearer $SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"hostname":"string"}'

GET/domains/{domain}

Get a domain

Secret key scope (any of): domains:write

Parameters

Field	Type	Description
`domain (path)`required	`string`	The ID of the domain.

Responses

200 The domain.

Field	Type	Description
`id`required	`string`
`environment`required	`"test" \| "live"`
`hostname`required	`string`	Normalized (lowercase, punycode) hostname.
`type`required	`"shared" \| "custom"`	`shared` is the project host on the platform domain; `custom` is your own.
`status`required	`"pending_dns" \| "verifying" \| "issuing_ssl" \| "active" \| "dns_misconfigured" \| "ssl_failed" \| "suspended"`	`pending_dns` (added, never checked), `verifying` (checked, ownership not proven yet), `issuing_ssl` (DNS is right, certificate pending), `active` (serves links), `dns_misconfigured` and `ssl_failed` (fix and re-verify), `suspended` (contact support).
`dns_records`required	`object[] \| null`	The records to create for a custom domain (a CNAME to the edge host, or an A/AAAA record to its addresses, plus the ownership TXT); null for shared domains.
`verified_at`required	`string (date-time) \| null`	When ownership was first proven; null until then.
`last_checked_at`required	`string (date-time) \| null`
`failed_check_count`required	`integer`	Consecutive failed checks.
`failing_since`required	`string (date-time) \| null`
`cert_expires_at`required	`string (date-time) \| null`
`suspended_at`required	`string (date-time) \| null`
`created_at`required	`string (date-time)`
`updated_at`required	`string (date-time)`

Example

Bash

curl -X GET "https://api.becklinks.com/v1/domains/{domain}" \
  -H "Authorization: Bearer $SECRET_KEY"

DELETE/domains/{domain}

Remove a custom domain

Removes a custom domain. Its links stop resolving at once and stay disabled while the domain can still be restored (30 days). The platform host of an environment cannot be removed (409).

Secret key scope (any of): domains:write

Parameters

Field	Type	Description
`domain (path)`required	`string`	The ID of the domain.

Responses

204 The domain is removed.

Example

Bash

curl -X DELETE "https://api.becklinks.com/v1/domains/{domain}" \
  -H "Authorization: Bearer $SECRET_KEY"

GET/domains/{domain}/diagnostics

Diagnose a domain

Expected against found DNS records and, for each configured app, whether the host serves a correct apple-app-site-association (Team ID and bundle ID) and assetlinks.json (package name and signing fingerprints). The files are fetched over HTTPS from the host with the same rules Apple and Google apply (no redirects, status 200, JSON).

Secret key scope (any of): domains:write

Parameters

Field	Type	Description
`domain (path)`required	`string`	The ID of the domain.

Responses

200 The diagnostics.

Field	Type	Description
`domain_id`required	`string`
`hostname`required	`string`
`type`required	`"shared" \| "custom"`
`status`required	`"pending_dns" \| "verifying" \| "issuing_ssl" \| "active" \| "dns_misconfigured" \| "ssl_failed" \| "suspended"`
`checked_at`required	`string (date-time)`
`dns`required	`object[]`	Empty for shared domains: their DNS is ours.
`dns[].purpose`required	`"routing" \| "ownership"`
`dns[].type`required	`"CNAME" \| "TXT"`
`dns[].name`required	`string`
`dns[].expected`required	`string[]`	What the record should hold. Routing accepts either the CNAME target or an address that belongs to it.
`dns[].found`required	`string[]`	What DNS answers right now.
`dns[].status`required	`"ok" \| "missing" \| "mismatch" \| "lookup_failed"`
`dns[].via`required	`"cname" \| "address" \| null`	For routing: how the host reaches the edge (a CNAME chain or a shared address).
`dns[].detail`required	`string \| null`	A hint when the record is not right.
`ios`required	`object`
`ios.platform`required	`"ios" \| "android"`
`ios.url`required	`string`
`ios.source`required	`"fetched" \| "generated" \| "skipped"`	`fetched` over HTTPS from the host; `generated` from the shared generators (platform hosts without a public HTTPS endpoint, i.e. local development); `skipped` when the app is not configured or the host cannot serve yet.
`ios.configured`required	`boolean`	The environment has this platform configured.
`ios.http_status`required	`integer \| null`
`ios.content_type`required	`string \| null`
`ios.valid_json`required	`boolean \| null`
`ios.expected`required	`object`
`ios.expected.identifiers`required	`string[]`	iOS: app IDs (`TEAMID.bundle.id`). Android: package names.
`ios.expected.fingerprints`required	`string[]`	Android SHA-256 signing fingerprints; empty for iOS.
`ios.found`required	`object`
`ios.found.identifiers`required	`string[]`	iOS: app IDs (`TEAMID.bundle.id`). Android: package names.
`ios.found.fingerprints`required	`string[]`	Android SHA-256 signing fingerprints; empty for iOS.
`ios.matches`required	`boolean \| null`	True when the served file names this app; null when nothing was compared.
`ios.problems`required	`object[]`
`ios.problems[].code`required	`"not_configured" \| "unreachable" \| "blocked_address" \| "not_found" \| "redirected" \| "unexpected_status" \| "wrong_content_type" \| "too_large" \| "invalid_json" \| "wrong_structure" \| "identifier_missing" \| "fingerprint_missing"`
`ios.problems[].message`required	`string`
`android`required	`object`
`android.platform`required	`"ios" \| "android"`
`android.url`required	`string`
`android.source`required	`"fetched" \| "generated" \| "skipped"`	`fetched` over HTTPS from the host; `generated` from the shared generators (platform hosts without a public HTTPS endpoint, i.e. local development); `skipped` when the app is not configured or the host cannot serve yet.
`android.configured`required	`boolean`	The environment has this platform configured.
`android.http_status`required	`integer \| null`
`android.content_type`required	`string \| null`
`android.valid_json`required	`boolean \| null`
`android.expected`required	`object`
`android.expected.identifiers`required	`string[]`	iOS: app IDs (`TEAMID.bundle.id`). Android: package names.
`android.expected.fingerprints`required	`string[]`	Android SHA-256 signing fingerprints; empty for iOS.
`android.found`required	`object`
`android.found.identifiers`required	`string[]`	iOS: app IDs (`TEAMID.bundle.id`). Android: package names.
`android.found.fingerprints`required	`string[]`	Android SHA-256 signing fingerprints; empty for iOS.
`android.matches`required	`boolean \| null`	True when the served file names this app; null when nothing was compared.
`android.problems`required	`object[]`
`android.problems[].code`required	`"not_configured" \| "unreachable" \| "blocked_address" \| "not_found" \| "redirected" \| "unexpected_status" \| "wrong_content_type" \| "too_large" \| "invalid_json" \| "wrong_structure" \| "identifier_missing" \| "fingerprint_missing"`
`android.problems[].message`required	`string`

Example

Bash

curl -X GET "https://api.becklinks.com/v1/domains/{domain}/diagnostics" \
  -H "Authorization: Bearer $SECRET_KEY"

POST/domains/{domain}/verify

Re-verify a domain

Checks the domain now: the ownership TXT record, the CNAME (or address) to the edge and, while the certificate is pending, HTTPS. The status moves accordingly: verifying, dns_misconfigured, issuing_ssl, active or ssl_failed. A lookup that fails (DNS temporarily unavailable) changes nothing (inconclusive). A domain can be checked once every 30 seconds (429 with Retry-After). Shared platform hosts are always active.

Secret key scope (any of): domains:write

Parameters

Field	Type	Description
`domain (path)`required	`string`	The ID of the domain.

Responses

200 The domain after the check, and what the check found.

Field	Type	Description
`domain`required	`object`
`domain.id`required	`string`
`domain.environment`required	`"test" \| "live"`
`domain.hostname`required	`string`	Normalized (lowercase, punycode) hostname.
`domain.type`required	`"shared" \| "custom"`	`shared` is the project host on the platform domain; `custom` is your own.
`domain.status`required	`"pending_dns" \| "verifying" \| "issuing_ssl" \| "active" \| "dns_misconfigured" \| "ssl_failed" \| "suspended"`	`pending_dns` (added, never checked), `verifying` (checked, ownership not proven yet), `issuing_ssl` (DNS is right, certificate pending), `active` (serves links), `dns_misconfigured` and `ssl_failed` (fix and re-verify), `suspended` (contact support).
`domain.dns_records`required	`object[] \| null`	The records to create for a custom domain (a CNAME to the edge host, or an A/AAAA record to its addresses, plus the ownership TXT); null for shared domains.
`domain.verified_at`required	`string (date-time) \| null`	When ownership was first proven; null until then.
`domain.last_checked_at`required	`string (date-time) \| null`
`domain.failed_check_count`required	`integer`	Consecutive failed checks.
`domain.failing_since`required	`string (date-time) \| null`
`domain.cert_expires_at`required	`string (date-time) \| null`
`domain.suspended_at`required	`string (date-time) \| null`
`domain.created_at`required	`string (date-time)`
`domain.updated_at`required	`string (date-time)`
`check`required	`object`
`check.outcome`required	`"passed" \| "pending" \| "failed" \| "inconclusive" \| "not_applicable"`	`passed` (active), `pending` (DNS is right, the certificate is being issued), `failed` (see the probes), `inconclusive` (a DNS lookup failed; nothing changed, retry), `not_applicable` (shared domains need no checks).
`check.ownership`required	`"ok" \| "fail" \| "unknown" \| "not_checked"`	The TXT record holds the token.
`check.routing`required	`"ok" \| "fail" \| "unknown" \| "not_checked"`	The CNAME or the addresses point at the edge.
`check.certificate`required	`"ok" \| "fail" \| "unknown" \| "not_checked"`	HTTPS answers with a valid certificate; only probed while issuing it.
`check.checked_at`required	`string (date-time)`

Example

Bash

curl -X POST "https://api.becklinks.com/v1/domains/{domain}/verify" \
  -H "Authorization: Bearer $SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)"