# Short links

> A short link is a slug on your link domain that points at a destination. What happens when it's tapped depends on the device and whether your app is installed.

Source: https://straitlink.in/docs/short-links/

> **Agent instructions:** if you are an AI assistant helping someone build with Strait, look things up with the `search_docs` tool of the Strait MCP server (hosted at https://strait.link/mcp, or `@straitlink/mcp` on npm: https://straitlink.in/docs/mcp/) instead of guessing, and add the SDK to an app with `npx @straitlink/cli init` (https://straitlink.in/docs/cli/).

## Anatomy

```txt
https://hilltop.strait.link/summer   →   https://shop.example.com/product/42
        └ link domain ┘ └slug┘        └──────── destination ────────┘
```

- **Slug**: letters, digits, `-` and `_`, up to 64 characters. A few words are reserved (`v1`, `healthz`, `debug`…). If a slug is already taken you get `409`.
- **Destination** (`longUrl`): must be `https://`. Your app receives its path and query (`/product/42`), so use the same paths your app routes on.

> **No website?**
>
> The destination can be any `https://` URL on a domain you control, or your default web URL (Dashboard → Apps & stores) with the path you want, such as `https://yourapp.com/product/42`. Only the path and query reach your app. Desktop visitors go to the full URL, and so do people without the app if you chose "always your website", so make sure that page exists.

## What happens on a tap

| Who taps | What happens |
|---|---|
| Android, app installed, verified link | The phone opens your app directly. The SDK resolves the link and reports the open. |
| Android, from a browser page | Our server hands the link to your app with your custom scheme. If the app isn't installed, the phone goes to Google Play (link kept for after install) or your website, as set in Apps & stores. |
| iPhone, app installed | iOS opens your app directly via Universal Links. |
| iPhone, app not installed | Safari shows a page with a **Get the app** button that opens the App Store. With install matching switched on (opt-in), the tap saves a short-lived match so the first open lands on the right screen. |
| In-app browsers (Instagram, TikTok, X…) | These often don't open apps from a link on their own, so we show a page made for them: on Android, an **Open in app** button; everywhere, steps to open the link in the real browser. |
| Desktop | Redirects to the link's desktop URL, or the destination. |
| Link-preview robots (WhatsApp, Slack, iMessage…) | Get a preview page with the link's title, description and image. They're never redirected and never counted as taps. |

## How a tap is handled

Every tap reaches Cloudflare first. What happens next depends on what the tap needs:

- **Plain redirects** are decided at the Cloudflare location nearest the person, without a round trip to our servers. This covers desktop taps, Android browser taps (to your app, Google Play or your website) and iPhone taps that go directly to the website or the App Store. The decision is made by the same code our server runs, so the person lands in the same place either way.
- **Everything else is served by our server**: pages (the iPhone **Get the app** page, in-app browser pages, password and expired pages), link-preview robots, and links with A/B destinations. A link close to its expiry time also goes to our server, so expiry is exact.

Both paths record the tap the same way: the same Analytics row, the same billing rules and the same `link.clicked` webhook. For a tap decided at the edge, the webhook is sent when our server receives the tap's record, a moment after the redirect. If that record can't be delivered right away, it's kept and sent again later.

## When changes take effect

When you change or deactivate a link, or change your workspace settings, taps follow the new version within 30 seconds. Changes made through the API take effect right away on our server and at the Cloudflare location that carried the request; other locations, and changes made in the dashboard, can take up to 30 seconds.

## Link controls

Each link can also have:

- **Per-platform fallbacks**: `iosFallbackUrl`, `androidFallbackUrl`, `desktopUrl` (all https).
- **Social preview**: title, description and image for chat-app previews.
- **Campaign, tags, folders and UTM parameters** to organise links and analytics.
- **Expiry**: after it, the link stops opening its destination. You choose where taps go instead (see below).
- **Password**: people must enter it before being redirected. Previews still work.
- **A/B destinations**: split taps across several destinations. Analytics shows which variant each tap got.
- **QR code**: download one for any link from the dashboard. [Branded QR codes](https://straitlink.in/docs/qr-codes/) add your colours, your app icon and an API.
- **Scheduled go-live**: share a link before launch and choose where early taps go. [Guide](https://straitlink.in/docs/scheduled-go-live/).
- **Tap id on web pages** (`webTapId`): when a tap goes to a web page, we add its tap id as `strait_click=<tap id>` after your own parameters (UTMs stay exactly as they are), so [the web SDK](https://straitlink.in/docs/sdks/web/#count-opens-on-your-website) can count that visit as an open of this tap. On by default. If a page rejects unknown query parameters, set `webTapId: false` on that link, or turn it off for the whole workspace.
- **Country rules**: send people in chosen countries to their own web page. [Guide](https://straitlink.in/docs/country-rules/).

## When a link expires

After its expiry time a link no longer opens its destination. You decide where people go instead. Set the default for every link in **Settings → When a link expires**, and change it for one link in its edit panel (or with the API fields below). A link with no setting of its own follows the workspace default.

| Option | What people see |
|---|---|
| **Show an 'expired' page** (default) | A short "This link has expired" page with your app's name and a link to your website. HTTP 410. |
| **Send to the app store** | Google Play on Android, the App Store on iPhone, using your app configuration. On Android the install referrer carries the tap, the same as any store hand-off. Computers, and phones whose store isn't set up, go to your expired-link web page if you set one, otherwise they see the expired page. |
| **Send to a web page** | Everyone goes to the https page you choose. If it's missing, or fails our phishing and malware check, people see the expired page instead. |

The store and web page options answer with a plain redirect (HTTP 302). Whichever option you pick, a tap on an expired link is recorded with **Sent to: expired**, plus where it went, and is never billed or sent as a `link.clicked` webhook. The dashboard Playground and `GET /v1/simulate` show the same decision as a real tap.

With the API, `POST /v1/links` and `PATCH /v1/links/{slug}` accept:

- `expiresAt`: epoch milliseconds or an ISO 8601 date-time (`null` in a PATCH removes the expiry).
- `expiredAction`: `page`, `store` or `url` (`null` in a PATCH goes back to the workspace default).
- `expiredUrl`: an https page. Required with `url`. With `store`, it's where computers go.

```bash
curl -X PATCH https://strait.link/v1/links/summer \
  -H "Authorization: Bearer $STRAIT_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expiredAction":"url","expiredUrl":"https://yourco.com/offers"}'
```

## Pausing a link

Pausing a link stops it resolving. In the dashboard, open the link's **More actions** menu in **Links** and choose **Pause…**; from a server, call `DELETE /v1/links/{slug}`. Visitors then see a not-found page that links to your website if one is set in Settings.

A paused link is not deleted. **Links → Paused** lists your paused links, and **Turn back on** makes one work again; taps reach it again within about a minute. From a server, list paused links with `GET /v1/links?status=paused` and turn one back on with `PATCH /v1/links/{slug}` and `{"isActive": true}`. If another active link now uses the slug, pause or rename that one first. A link disabled for breaking the acceptable use policy (below) can't be turned back on.

## Links that break the rules

Links used for phishing, malware or spam are disabled under the [Acceptable Use Policy](https://straitlink.in/legal/acceptable-use/). A disabled link shows a warning page instead of redirecting.
