Domains API

Domain endpoints require a session cookie (authenticated browser session), not an upload token. These are used by the dashboard and not typically needed for external integrations.

Endpoints

Method	Path	Description
`GET`	`/api/domains`	List your domains
`POST`	`/api/domains`	Add a new domain
`POST`	`/api/domains/[id]/cf-check`	Trigger DNS verification
`PATCH`	`/api/domains/[id]`	Update a domain (set primary etc.)
`DELETE`	`/api/domains/[id]`	Remove a domain

List Domains

`GET /api/domains`

Returns all your custom domains and your usage limits.

Response (200):

{
  "domains": [
    {
      "id": "dom_abc123",
      "domain": "files.example.com",
      "verified": true,
      "isPrimary": true,
      "cfStatus": "active",
      "createdAt": "2026-01-15T10:00:00Z"
    }
  ],
  "domainLimit": {
    "allowed": 3,
    "base": 1,
    "purchased": 1,
    "perkBonus": 1,
    "used": 1,
    "remaining": 2
  }
}

domainLimit.allowed = base + purchased + perkBonus
perkBonus comes from GitHub contributor and Discord booster perks.

Add a Domain

`POST /api/domains`

{ "domain": "files.example.com" }

Responses:

Status	Meaning
`200`	Domain created — add CNAME to verify
`400`	Invalid domain format
`403`	Domain slot limit reached
`409`	Domain already registered

A new domain is created with cfStatus: "awaiting_cname". You must add a CNAME before verifying.

Verify a Domain

`POST /api/domains/[id]/cf-check`

Triggers a DNS check and Cloudflare provisioning attempt.

Responses:

Status	Meaning
`202`	Verification started — check again in a moment
`200`	Verification complete — `status` field shows new state
`409`	CNAME missing or incorrect — `expected` field shows required target
`429`	Too many attempts (10 per 10 minutes)

curl -X POST \
  -b cookies.txt -c cookies.txt \
  https://embrly.ca/api/domains/dom_abc123/cf-check

Update a Domain

`PATCH /api/domains/[id]`

Set as primary domain:

{ "action": "setPrimary" }

The domain must be verified before it can be set as primary.

Rename the domain:

{ "action": "update", "domain": "new.example.com" }

Returns 204 No Content.

Delete a Domain

`DELETE /api/domains/[id]`

Returns 204 No Content. If the domain was primary, no domain becomes primary — you must set a new one.

Example: Full Setup Flow

# 1. Add domain
curl -s -X POST \
  -H "Content-Type: application/json" \
  -b cookies.txt -c cookies.txt \
  -d '{"domain":"files.example.com"}' \
  https://embrly.ca/api/domains
 
# 2. Add CNAME in your DNS panel:
#    files.example.com → CNAME → cname.embrly.ca
 
# 3. Trigger verification
curl -s -X POST \
  -b cookies.txt -c cookies.txt \
  https://embrly.ca/api/domains/dom_abc123/cf-check
 
# 4. Set as primary
curl -s -X PATCH \
  -H "Content-Type: application/json" \
  -b cookies.txt -c cookies.txt \
  -d '{"action":"setPrimary"}' \
  https://embrly.ca/api/domains/dom_abc123

See the Custom Domains user guide for full setup instructions including Cloudflare and DNS configuration.

On this page