Create a link
method
POST
host
strait.
version
/v1
resource
/
POST /v1/links
Auth: secret key as Authorization: Bearer. Server-side only.
Request
Parameters
Idempotency-Keystring 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)
slugrequired stringlongUrlrequired string- https only. The app receives its path + query as the in-app route.
iosFallbackUrlstring- iPhone without the app: this page instead of longUrl (https).
androidFallbackUrlstring- Android without the app (website mode): this page instead of longUrl (https).
desktopUrlstring- Desktop browsers go here instead of longUrl (https).
webTapIdboolean- 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.
variantsobject[]- 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.
titlestring- Social preview title.
descriptionstring- Social preview description.
imageUrlstring- Social preview image (https).
campaignstring- Campaign name for analytics. Defaults to longUrl's utm_campaign when omitted (and follows it when longUrl changes).
tagsstring[]expiresAtobject- 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).
expiredUrlstring- https. Required with expiredAction url; with store it is where computers go. Passes the same unsafe-destination check as longUrl.
startsAtobject- 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.
notLiveUrlstring- https. Required with notLiveAction url; with store it is where computers go. Passes the same unsafe-destination check as longUrl.
countryRulesobject[]- 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).
legacyHoststring- 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).
legacyCodestring- The old Firebase short code on legacyHost, exactly as it was (case-sensitive).
referralCodestring- 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
referralCodein 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. passwordstring- 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;
fieldnames which one, e.g.iosFallbackUrlorvariants[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 }.
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"
]
}'const res = await fetch('https://strait.link/v1/links', {
method: 'POST',
headers: { Authorization: `Bearer ${process.env.SECRET_KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify({
"slug": "summer",
"longUrl": "https://shop.example.com/sale/summer?utm_source=whatsapp&utm_campaign=summer-2026",
"title": "Summer sale",
"tags": [
"sale"
]
}),
});
const data = await res.json();
console.log(res.status, data);import os
import requests
res = requests.post(
"https://strait.link/v1/links",
headers={"Authorization": f"Bearer {os.environ['SECRET_KEY']}"},
json={
"slug": "summer",
"longUrl": "https://shop.example.com/sale/summer?utm_source=whatsapp&utm_campaign=summer-2026",
"title": "Summer sale",
"tags": [
"sale",
],
},
)
print(res.status_code, res.json())<?php
// Plain PHP with ext-curl, no packages. In Laravel, Http::withToken($secretKey)->post($url, $body) sends the same request.
$ch = curl_init('https://strait.link/v1/links');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('SECRET_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'slug' => 'summer',
'longUrl' => 'https://shop.example.com/sale/summer?utm_source=whatsapp&utm_campaign=summer-2026',
'title' => 'Summer sale',
'tags' => [
'sale',
],
], JSON_THROW_ON_ERROR),
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
echo $status, PHP_EOL;
print_r(json_decode($response, true));import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
// Java 17+, java.net.http only (no dependencies).
public class Main {
public static void main(String[] args) throws Exception {
String body = """
{
"slug": "summer",
"longUrl": "https://shop.example.com/sale/summer?utm_source=whatsapp&utm_campaign=summer-2026",
"title": "Summer sale",
"tags": [
"sale"
]
}
""";
HttpRequest request = HttpRequest.newBuilder(URI.create("https://strait.link/v1/links"))
.header("Authorization", "Bearer " + System.getenv("SECRET_KEY"))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(body))
.build();
HttpResponse<String> res = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.statusCode() + " " + res.body());
}
}package main
import (
"fmt"
"io"
"log"
"net/http"
"os"
"strings"
)
func main() {
body := strings.NewReader(`{
"slug": "summer",
"longUrl": "https://shop.example.com/sale/summer?utm_source=whatsapp&utm_campaign=summer-2026",
"title": "Summer sale",
"tags": [
"sale"
]
}`)
req, err := http.NewRequest(http.MethodPost, "https://strait.link/v1/links", body)
if err != nil {
log.Fatal(err)
}
req.Header.Set("Authorization", "Bearer "+os.Getenv("SECRET_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)
if err != nil {
log.Fatal(err)
}
defer res.Body.Close()
data, err := io.ReadAll(res.Body)
if err != nil {
log.Fatal(err)
}
fmt.Println(res.StatusCode, string(data))
}The response, printed
{
"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"
]
}