Reference

Aliases

An alias is a memorable short-link that resolves to one of your sites or to any external URL. Aliases live under /_/<name> (the resolver is a 302 redirect) and survive across site rebuilds — point /_/launch at one site today, repoint it at another tomorrow, the URL never changes for the people you shared it with.

30-second quickstart

# Use the site id returned by your Quickstart publish (id: "site_abc...").
curl -X POST https://dropfast.dev/api/v1/aliases \
  -H "Authorization: Bearer df_sk_..." \
  -H "content-type: application/json" \
  -d '{"alias":"launch","targetType":"site","targetSiteId":"site_abc..."}'
 
# → { success: true, data: { url: "https://dropfast.dev/_/launch", ... } }
# Open https://dropfast.dev/_/launch — it 302s to your site.

How /_/<name> resolves

A GET to /_/<name> (or /_/<name>/<sub/path>) looks up the alias and:

• targetType: 'site' — redirects to /s/<target-site-slug>/<sub/path>, preserving the query string. The redirect is a 302, so refreshing the shared link picks up future re-targets.
• targetType: 'external' — redirects to the saved targetUrl. If you shared /_/blog/post-1, the /post-1 segment is appended to the target URL's path, and any inbound query parameters are merged on top of the target's existing query (alias-side wins on duplicate keys).

If the alias is missing, inactive, or points at a deleted site, the resolver returns a minimal Signal Dark 404 HTML page (not the JSON envelope). The resolver also supports HEAD so monitors can probe without taking the redirect.

Every successful resolve increments the alias's hitCount asynchronously via after() — the redirect ships first, the counter updates after.

Alias names

Names are case-insensitive (we lowercase on the way in) and must match:

• 2 – 48 characters
• Lowercase letters, digits, and hyphens only
• No leading or trailing hyphen
• Not one of these reserved names: admin, api, alias, auth, dashboard, new, s, sign-in, sign-up, _, a

Names are globally unique. The dedicated ALIAS_ALREADY_EXISTS error (HTTP 409) tells you someone — possibly you — already owns it.

Endpoints

Auth is identical to the rest of the API: send Authorization: Bearer df_sk_... (the legacy x-api-key: df_sk_... header also works) or use a dashboard session.

POST /api/v1/aliases — create an alias

JSON body:

# Alias that points at one of your sites
curl -X POST https://dropfast.dev/api/v1/aliases \
  -H "Authorization: Bearer df_sk_..." \
  -H "content-type: application/json" \
  -d '{"alias":"launch","targetType":"site","targetSiteId":"site_abc..."}'
 
# Alias that points at any external URL
curl -X POST https://dropfast.dev/api/v1/aliases \
  -H "Authorization: Bearer df_sk_..." \
  -H "content-type: application/json" \
  -d '{"alias":"blog","targetType":"external","targetUrl":"https://example.com/posts"}'

Returns 201 with the saved alias plus the resolved url for the /_/<alias> short-link.

GET /api/v1/aliases — list yours

curl https://dropfast.dev/api/v1/aliases \
  -H "Authorization: Bearer df_sk_..."

GET /api/v1/aliases/{alias} — fetch one

curl https://dropfast.dev/api/v1/aliases/launch \
  -H "Authorization: Bearer df_sk_..."

PATCH /api/v1/aliases/{alias} — update or rename

Any subset of alias, targetType, targetSiteId, targetUrl, isActive. Renaming is allowed (subject to the name rules and uniqueness). Setting isActive: false makes /_/<alias> return 404 without deleting the row, which is useful for temporarily pausing a campaign link.

# Repoint the same short link at a different site
curl -X PATCH https://dropfast.dev/api/v1/aliases/launch \
  -H "Authorization: Bearer df_sk_..." \
  -H "content-type: application/json" \
  -d '{"targetSiteId":"site_xyz..."}'
 
# Pause without losing the name
curl -X PATCH https://dropfast.dev/api/v1/aliases/launch \
  -H "Authorization: Bearer df_sk_..." \
  -H "content-type: application/json" \
  -d '{"isActive":false}'

DELETE /api/v1/aliases/{alias} — delete

curl -X DELETE https://dropfast.dev/api/v1/aliases/launch \
  -H "Authorization: Bearer df_sk_..."

Cascade behavior

Aliases keep working as long as their target does:

• Deleting a site automatically flips every alias pointing at it to isActive: false so /_/<alias> starts returning 404. The alias rows stay in your account — you can PATCH them to point somewhere new.
• Deleting an alias does not touch the target site or external URL.

Errors

The validation errors above plus the global ones from the REST API reference. The alias-specific code is: