# Custom Domain Short Links — Quick Start

Create branded short links on your own domain instead of `urlz.zip`.

## Prerequisites

1. A verified and active custom domain in CompactSaaS (Dashboard > Links > Custom Domains)
2. An API key (Dashboard > API Keys)

## Step 1: Verify your domain

In the dashboard, go to **Links > Custom Domains** and add your domain. You'll need to create a CNAME record pointing to the CompactSaaS routing endpoint, then verify and activate it.

Once active, your domain status will show as **active** in the dashboard and API:

```bash
curl https://api.compactsaas.com/v1/links/domains \
  -H "x-api-key: YOUR_API_KEY"
```

```json
{
  "domains": [
    {
      "domain": "links.example.com",
      "status": "verified",
      "tenantStatus": "active"
    }
  ]
}
```

## Step 2: Create a branded short link

Pass the `domain` field when creating a short link:

```bash
curl -X POST https://api.compactsaas.com/v1/links/shorten \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "targetUrl": "https://example.com/my-page",
    "domain": "links.example.com",
    "customCode": "my-link"
  }'
```

```json
{
  "link": {
    "shortCode": "my-link",
    "shortUrl": "https://links.example.com/my-link",
    "targetUrl": "https://example.com/my-page",
    "domain": "links.example.com",
    "enabled": true
  }
}
```

The short link is now live at `https://links.example.com/my-link` and redirects to `https://example.com/my-page`.

## Options

| Field | Required | Description |
|-------|----------|-------------|
| `targetUrl` | Yes | Destination URL |
| `domain` | No | Your verified custom domain. Omit to use the default (`urlz.zip`) |
| `customCode` | No | Custom short code (3-32 chars). Omit for auto-generated |
| `analyticsEnabled` | No | Track clicks in your analytics dashboard |

## Dashboard

You can also create branded short links from the dashboard. When you have an active custom domain, the **Shorten URL** dialog shows a domain dropdown.

## Wait a few seconds before sharing a brand-new link

When you create or update a short link, it takes a few seconds (usually
3–10) for the link to be available everywhere in the world. If someone
clicks during that window, the link still works — but in rare cases their
browser can briefly cache a stale result. **Wait ~10 seconds before sharing
a brand-new link** with someone likely to click immediately.

The dashboard's **Shorten URL** flow shows a 10-second "Provisioning to
edge" indicator and disables the Copy button until the link is ready. If
you're creating links via the API, build a similar wait into your client.

### Controlling how long browsers cache a redirect

Set `ttl` on the link to control how long browsers and intermediate caches
remember the redirect:

| `ttl` value | Behaviour |
|-------------|-----------|
| Omitted (default) | Short cache — updates to the target appear within ~1 minute |
| `0` | No caching — every click revalidates (use for frequently-edited links) |
| Positive integer (seconds) | Cache for exactly that long |

For most users the default is fine. Use `ttl: 0` if you frequently change
where a link points and want updates to be immediate.

## Notes

- The `domain` must be verified and active for your team. Unverified domains are rejected.
- **Apex domains (e.g., `example.com`) are not supported** — only subdomains (`links.example.com`, `go.example.com`). Domain verification requires a CNAME record, and DNS standards (RFC 1034) don't allow CNAMEs at the zone apex. Use a subdomain like `links.yourdomain.com` or `go.yourdomain.com`.
- Short codes are unique per domain — `links.example.com/abc` and `urlz.zip/abc` are independent.
- Edge redirects are sub-millisecond. New links may take a few seconds to be available everywhere (see above).
- Custom domain links work with analytics tracking (`analyticsEnabled: true`).