# Add a custom domain

Source: https://straitlink.in/docs/api/add-domain/

`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`.

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.

| Field | Type | Notes |
|---|---|---|
| `tenantId` | `string` | Required with a dashboard session |
| `hostname` (required) | `string` | A subdomain, without https:// or a path |

```bash
curl -X POST https://strait.link/v1/domains \
  -H "Authorization: Bearer $SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "hostname": "links.hilltop.example"
  }'
```

Response 201:

```json
{
  "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"
    }
  ]
}
```

- `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