Domains and Slugs

Custom domains are organization assets.

For the current client model:

acme.com
example.io

should be attached to the same tenant organization if the same admin team manages them.

Shortnd manages branded links as exact hostnames owned by an organization. That means a tenant can onboard:

an apex hostname such as acme.com
a subdomain hostname such as go.acme.com

Each hostname has its own ownership, routing, SSL, and activation lifecycle.

Recommended setup flow

Approve and review the domain in the dashboard.
Create or confirm the custom domain record with POST /api/v1/domains.
Add the TXT ownership record and the routing record returned by the API.
Trigger verification with POST /api/v1/domains/{id}/verify.
Wait for SSL activation before treating the hostname as live.
Create operational links through POST /api/v1/urls with the domain ID.

DNS model

The TXT token proves domain ownership. It does not route traffic.
Apex hostnames route through A records or provider-level ALIAS/ANAME at your DNS provider.
Subdomain hostnames route through a CNAME back to Shortnd infrastructure.
A domain is only ready when ownership verification, routing verification, and SSL activation all succeed.

Example DNS records for go.acme.com:

TXT host: _shortnd-verify.go
TXT value: <verification token>
CNAME host: go.acme.com
CNAME target: cname.shortnd.com

Custom slug behavior

Slug uniqueness depends on the namespace.

Platform-domain slugs must be globally unique.
Custom-domain slugs are unique within that specific custom domain.

That lets one tenant automate user-facing slugs for acme.com and example.io independently while keeping each domain safe from collisions.

Example

curl -X POST https://shortnd.com/api/v1/urls \
  -H "Authorization: Bearer $SHORTND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "targetUrl": "https://example.io/onboarding",
    "customSlug": "welcome",
    "domainId": "domain_uuid"
  }'

await fetch('https://shortnd.com/api/v1/urls', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SHORTND_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    targetUrl: 'https://example.io/onboarding',
    customSlug: 'welcome',
    domainId: 'domain_uuid',
  }),
});

import os, requests

requests.post(
    "https://shortnd.com/api/v1/urls",
    headers={"Authorization": f"Bearer {os.environ['SHORTND_API_KEY']}"},
    json={
        "targetUrl": "https://example.io/onboarding",
        "customSlug": "welcome",
        "domainId": "domain_uuid",
    },
).raise_for_status()

body := strings.NewReader(`{"targetUrl":"https://example.io/onboarding","customSlug":"welcome","domainId":"domain_uuid"}`)
req, _ := http.NewRequest("POST", "https://shortnd.com/api/v1/urls", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHORTND_API_KEY"))
req.Header.Set("Content-Type", "application/json")
http.DefaultClient.Do(req)

$ch = curl_init("https://shortnd.com/api/v1/urls");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("SHORTND_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "targetUrl"  => "https://example.io/onboarding",
        "customSlug" => "welcome",
        "domainId"   => "domain_uuid",
    ]),
]);
curl_exec($ch);

Recommended setup flow

DNS model

Custom slug behavior

Example

On this page