Domains API, Flyn API Documentation

Add custom branded domains for your short links. Flyn handles SSL provisioning, DNS verification, and routing automatically. Pro plans include up to 3 custom domains.

How Custom Domains Work

Setting up a custom domain takes 3 steps:

Add the domain via API or dashboard. Flyn registers it with our edge infrastructure
Add DNS records at your domain registrar, a TXT record for ownership verification, and a CNAME or A record for routing
Verify, Flyn checks your DNS records and activates the domain once both are confirmed

DNS Configuration

You need to add two DNS records:

1. TXT Record (Ownership Verification)

Type	Name	Value
TXT	_flyn.yourdomain.com	flyn-verify=abc123... (provided in API response)

2. Routing Record

Domain Type	Record	Name	Value
Subdomain (e.g. go.yoursite.com)	CNAME	go	cname.flyn.to
Apex domain (e.g. yoursite.com)	A	@	76.76.21.21

DNS Propagation

DNS changes can take up to 48 hours to propagate, though most registrars update within 5-15 minutes. You can click "Verify" multiple times, it will check the current DNS state each time.

Add a Domain

Registers a new custom domain and returns DNS setup instructions.

POST/api/domains/add

Request Body

Parameter	Type	Required	Description
domain	string	Yes	The domain to add (e.g. "go.yourcompany.com"). Protocol and www prefix are stripped automatically.

Request Example

curl -X POST https://www.flyn.to/api/domains/add \
  -H "Authorization: Bearer flyn_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "domain": "go.yourcompany.com" }'

Response (200)

Response

{
  "domain": {
    "id": "domain-uuid",
    "domain": "go.yourcompany.com",
    "slug": "go-yourcompany-com",
    "status": "pending",
    "verified": false,
    "txt_record": "flyn-verify=a1b2c3d4...",
    "cname_target": "cname.flyn.to"
  },
  "dnsInstructions": {
    "txt": {
      "type": "TXT",
      "name": "_flyn.yourcompany.com",
      "value": "flyn-verify=a1b2c3d4..."
    },
    "routing": {
      "type": "CNAME",
      "name": "go",
      "value": "cname.flyn.to"
    }
  }
}

Verify a Domain

Checks DNS records and activates the domain if both TXT ownership and routing records are configured correctly.

POST/api/domains/:id/verify

Response (200)

Response

{
  "domain": { /* updated domain object */ },
  "verification": {
    "verified": true,
    "txtVerified": true,
    "configured": true,
    "misconfigured": false,
    "dnsInstructions": [],
    "message": "Domain is verified and active!"
  }
}

Verification States

TXT Verified	DNS Configured	Status	Message
Yes	Yes	active	Domain is verified and active!
Yes	No	pending	Ownership verified! Now add routing record.
No	Yes	pending	Routing set up. Add TXT record to verify ownership.
No	No	pending	Add the DNS records below, then try again.

List Domains

GET/api/domains

Returns all custom domains for your account, ordered newest first.

Update a Domain

PATCH/api/domains/:id

Request Body

Parameter	Type	Required	Description
placeholder	string \| null	No	Custom placeholder text shown on the domain root page (max 500 chars)
notFoundUrl	string \| null	No	URL to redirect to when a slug is not found on this domain

Delete a Domain

Removes a custom domain. All links using this domain are automatically reverted to the default flyn.to domain.

DELETE/api/domains/:id

Response (200)

{ "success": true }

Important

Deleting a domain does not delete your links. They are moved back to the default flyn.to domain and continue to work at their new short URL.