Add a custom domain

THE CALL, PART BY PART

method

POST

host

strait.link

version

/v1

resource

/domains

POST /v1/domains

Auth: secret key as Authorization: Bearer. Server-side only.

Coming soon: custom domains aren't switched on yet. Until they are, this endpoint answers enabled: false (the list) or 503 domains_not_enabled.

Request

Adds a subdomain you own (for example links.yourcompany.com) and creates it at Cloudflare. The answer lists the DNS records to add: a CNAME to the target, a TXT record that proves you own the domain, and a TXT record for the HTTPS certificate. Owners, admins and members; Scale and Enterprise only; at most 5 per workspace. Adds and removes share a limit of 10, then 1 every 6 minutes, per workspace.

Body (JSON)

tenantId string
Required with a dashboard session
hostname required string
A subdomain, without https:// or a path

Response

  • 201 Added; add the DNS records shown
  • 400 Not a usable hostname (a bare domain, an IP, one of our hosts, or malformed)
  • 401 Missing or invalid secret key or session
  • 402 plan_required: custom domains are part of the Scale plan
  • 403 Viewers cannot add domains
  • 409 Already added to a Strait workspace, or the workspace already has 5
  • 429 Too many domain changes (Retry-After: 360)
  • 502 Cloudflare didn't answer; nothing was saved
  • 503 domains_not_enabled, or domains_read_only
Request · curl
curl -X POST https://strait.link/v1/domains \
  -H "Authorization: Bearer $SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "hostname": "links.hilltop.example"
  }'

The response, printed

Response 201
{
  "hostname": "links.hilltop.example",
  "verified": false,
  "status": "pending_dns",
  "records": [
    {
      "type": "CNAME",
      "name": "links.hilltop.example",
      "value": "fallback.strait.link",
      "purpose": "Sends your links to Strait"
    },
    {
      "type": "TXT",
      "name": "_cf-custom-hostname.links.hilltop.example",
      "value": "5cc07c04-ea62-4a5a-95f0-419334a875a4",
      "purpose": "Proves you own the domain"
    },
    {
      "type": "TXT",
      "name": "_acme-challenge.links.hilltop.example",
      "value": "ca3-574923932a82475cb8592200f1a2a23d",
      "purpose": "Lets us issue its HTTPS certificate"
    }
  ]
}