Create a link

THE CALL, PART BY PART

method

POST

host

strait.link

version

/v1

resource

/links

POST /v1/links

Auth: secret key as Authorization: Bearer. Server-side only.

Request

Parameters

Idempotency-Key string header
Optional (ADR 0055). Retry with the same key and the same body to get the first answer back (header Idempotent-Replayed: true) instead of running again. 1 to 255 of [A-Za-z0-9_.:-], kept 24 hours per workspace and endpoint. 5xx, 429 and 402 answers are not kept.

Body (JSON)

slug required string
longUrl required string
https only. The app receives its path + query as the in-app route.
iosFallbackUrl string
iPhone without the app: this page instead of longUrl (https).
androidFallbackUrl string
Android without the app (website mode): this page instead of longUrl (https).
desktopUrl string
Desktop browsers go here instead of longUrl (https).
webTapId boolean
Taps sent to a web page (desktopUrl, the fallbacks, longUrl as a web page, a country rule, the workspace fallback) get this tap's id added as strait_click=<tap id>, the same id the app hand-off and the Play referrer carry, so @straitlink/web (and the React Native / Flutter web builds) count a web open joined to the tap. Existing query params (UTMs included) are kept as they are. On by default for the workspace. false turns it off for this link (a page that rejects unknown query params); true keeps it on even when the workspace turned it off.
variants object[]
A/B test: web taps are split across these https destinations by weight (e.g. two with weight 1 = 50/50). Each url passes the same unsafe-destination check as longUrl.
title string
Social preview title.
description string
Social preview description.
imageUrl string
Social preview image (https).
campaign string
Campaign name for analytics. Defaults to longUrl's utm_campaign when omitted (and follows it when longUrl changes).
tags string[]
expiresAt object
After this, the link stops opening its destination; expiredAction decides where taps go. Omit for never.
expiredAction "page" | "store" | "url"
Where a tap goes once the link has expired. page = the "This link has expired" page (410). store = Google Play on Android / the App Store on iPhone (302, from your app configuration; the Play install referrer carries the tap); computers, and phones whose store is not configured, get the expired-link web page, else the expired page. url = 302 to expiredUrl. Omit to use the workspace setting (default page).
expiredUrl string
https. Required with expiredAction url; with store it is where computers go. Passes the same unsafe-destination check as longUrl.
startsAt object
Scheduled go-live. Before it, taps get notLiveAction; must be before expiresAt. Omit for live now.
notLiveAction "page" | "store" | "url"
Where a tap goes BEFORE startsAt (the link is not live yet). page = a branded "Coming soon" page. store = Google Play on Android / the App Store on iPhone (302, from your app configuration); computers, and phones whose store is not configured, get notLiveUrl, else the page. url = 302 to notLiveUrl. Taps before go-live are not recorded and never billed; link-preview bots still get the preview card. Omit for page.
notLiveUrl string
https. Required with notLiveAction url; with store it is where computers go. Passes the same unsafe-destination check as longUrl.
countryRules object[]
Up to 5 rules, first match wins. When the tap's country (from Cloudflare, ISO 3166-1 alpha-2) is in a rule's countries, the rule's url replaces the web / fallback destination (iosFallbackUrl, androidFallbackUrl, desktopUrl, longUrl as a web page, the workspace fallback). Opening the app and the app-store hand-offs are unchanged. The country is also stored with the tap as its 2-letter code, for analytics (group=country).
legacyHost string
Imported from Firebase Dynamic Links: the old host (lower case, no https:// or path). Goes with legacyCode. When an app that keeps this host as an associated domain opens https://<legacyHost>/<legacyCode>, /v1/resolve finds this link by the old host + code before the slug, so the same code from two old hosts, or an old code and a newer slug, never clash. One active link per old host + code in a workspace (409 otherwise).
legacyCode string
The old Firebase short code on legacyHost, exactly as it was (case-sensitive).
referralCode string
This link's referral code: 1 to 64 letters, digits, - or _. Every tap of this link carries it, even one with ?strait_ref= (that counts only on links without a code); it comes back as referralCode in the deferred-match answer. Don't use an email address or phone number. Also accepted per item by POST /v1/links/batch; not by the update endpoint yet.
password string
Optional: visitors must enter it before the link opens (link-preview bots still get the preview card). Stored hashed, never returned; the link shows passwordProtected: true.

Response

  • 201 Created: the link, with the shortUrl to share
  • 400 Invalid field, destination_blocked (a URL failed the unsafe-destination check; field names which one, e.g. iosFallbackUrl or variants[1].url), or invalid_idempotency_key
  • 401 Missing or invalid secret key
  • 402 Plan limit reached (this month's new links, or taps over twice the plan). Existing links keep working. Body: { error, reason: "links" | "clicks", upgradeUrl } ("clicks" = the monthly tap limit).
  • 409 An active link with this slug already exists in this workspace, or idempotency_key_in_use: a request with the same Idempotency-Key is still running (Retry-After: 1)
  • 422 idempotency_key_reused: the Idempotency-Key was used in the last 24 hours with a different body
  • 429 New-account limit: a workspace younger than 24 hours can create 25 links. It lifts by itself; Retry-After says when. Body: { error: "new_account_limit", reason: "links", message, limit, resetsAt }.
Request · curl
curl -X POST https://strait.link/v1/links \
  -H "Authorization: Bearer $SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "summer",
    "longUrl": "https://shop.example.com/sale/summer?utm_source=whatsapp&utm_campaign=summer-2026",
    "title": "Summer sale",
    "tags": [
      "sale"
    ]
  }'

The response, printed

Response 201
{
  "id": "lnk_5f0c2a8e-3b1d-4f6a-9c7e-2d8b1a0e4f63",
  "tenantId": "0b8f6d2e-7a41-4c39-9e15-3f2a6c8d1b70",
  "slug": "summer",
  "shortUrl": "https://hilltop.strait.link/summer",
  "longUrl": "https://shop.example.com/sale/summer?utm_source=whatsapp&utm_campaign=summer-2026",
  "isActive": true,
  "title": "Summer sale",
  "campaign": "summer-2026",
  "tags": [
    "sale"
  ]
}