# REST API

> A small JSON API over HTTPS. Generated from the same OpenAPI description the server publishes at /v1/openapi.json.

Source: https://straitlink.in/docs/api/

> **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/).

## Base URL

```txt
https://strait.link
```

Every endpoint has its own page, with the request in curl, Node, Python, PHP, Java and Go next to the response: see [Endpoints](#endpoints) below. The PHP, Java and Go examples use only the standard library (ext-curl, `java.net.http`, `net/http`).

Server recipes: [create links in bulk](https://straitlink.in/docs/recipes/batch-create-links/), [verify webhook signatures](https://straitlink.in/docs/recipes/verify-webhook-signatures/) and [send links in WhatsApp templates](https://straitlink.in/docs/recipes/whatsapp-template-links/).

- **[Download the OpenAPI description](https://straitlink.in/docs/api/openapi.json)** (also served live at `https://strait.link/v1/openapi.json`) for Insomnia or a code generator.
- **[Download the Postman collection](https://straitlink.in/docs/api/postman-collection.json)**: in Postman, **Import**, pick the file, then set `secretKey` and `publishableKey` in the collection's variables.

## Authentication

| Key | Send it as | Use it for |
|---|---|---|
| Secret key `st_live_…` | `Authorization: Bearer st_live_…` header | Link endpoints, and events from your server |
| Publishable key `st_pub_live_…` | `"publishableKey"` in the JSON body | Endpoints your app or website calls |

The publishable key is in [**Dashboard → Setup → Your keys**](https://app.straitlink.in/setup#keys) and secret keys are in [**Dashboard → Settings → Keys**](https://app.straitlink.in/settings#keys). The examples on this page read the secret key from an environment variable:

```bash
export SECRET_KEY=st_live_…   # Dashboard → Settings → Keys
```

 The publishable key is safe to ship in apps; it can only resolve links, report opens, match installs and send events. Requests with a missing or wrong key get `401`.

After you rotate the publishable key, the old key keeps working for 7 days so apps already on people's phones don't break. Responses to the old key carry a `Strait-Key-Deprecated` header with the time it stops working (ISO 8601, for example `Strait-Key-Deprecated: 2026-01-08T12:00:00.000Z`); after that it gets `401`. See [Keys](https://straitlink.in/docs/keys/#rotating-keys).

## Errors and limits

Every error under `/v1` is JSON with an `error` message, never an HTML page:

```json
{ "error": "slug already exists in this workspace" }
```

| Status | When |
|---|---|
| `400` | Invalid input, including a body that isn't valid JSON (`{ "error": "malformed JSON body" }`) |
| `401` | Missing or wrong key |
| `402` | Plan limit reached when creating a link. Adds `reason` (`"links"`, or `"clicks"` for the monthly tap limit) and `upgradeUrl`; existing links keep working |
| `404` | Not found, including unknown `/v1` paths (`{ "error": "not found" }`) |
| `409` | The slug is already used by an active link in your workspace |
| `413` | Request body too large |
| `429` | Rate limited |
| `500` | Our fault: `{ "error": "internal error" }`, with no internal details |

Some errors add fields, for example a blocked destination returns `{ "error": "destination_blocked", "reason": "…" }`. The endpoints apps call are rate-limited per IP address; normal SDK traffic is far below the limit.

## Short URLs and slugs

Slugs are unique within your workspace, not across Strait: another workspace can also have `/summer` on its own link domain. Every link the API returns includes `shortUrl`, the address to share: `https://<your-handle>.strait.link/<slug>`. Always share `shortUrl`. See [Link domains](https://straitlink.in/docs/link-domains/).

Fetch one link by its slug with `GET /v1/links/{slug}`.

## When changes take effect

Link edits (`PATCH /v1/links/{slug}`) and deactivations (`DELETE /v1/links/{slug}`) and turning a link back on (`PATCH` with `isActive`) apply to taps within 30 seconds. They apply right away on our server and at the Cloudflare location that carried your request; plain redirects decided at other Cloudflare locations can follow the old version for up to 30 seconds. See [How a tap is handled](https://straitlink.in/docs/short-links/#how-a-tap-is-handled).

## Paging

`GET /v1/links` without parameters returns every active link as a plain JSON array. Add `limit` (1 to 100, default 50) or `cursor` to page through them instead, newest first:

```bash
curl "https://strait.link/v1/links?limit=50" \
  -H "Authorization: Bearer $SECRET_KEY"
# → { "links": [ … ], "nextCursor": "WyIyMDI2…" }

curl "https://strait.link/v1/links?limit=50&cursor=WyIyMDI2…" \
  -H "Authorization: Bearer $SECRET_KEY"
# → { "links": [ … ], "nextCursor": null }   ← the last page
```

Pass each `nextCursor` back as `cursor` until it is `null`. Treat the cursor as opaque; an invalid one gets `400`.

## Try a link without tapping it

`GET /v1/simulate` tells you what a tap would do, without recording a tap, sending webhooks or counting toward your plan. Pass the full short link as `url` and either a raw user agent or one of these presets as `ua`: `android`, `iphone`, `ipad`, `desktop`, `instagram-ios`, `instagram-android`, `facebook-android`, `whatsapp-android`, `bot`.

```bash
curl "https://strait.link/v1/simulate?url=https%3A%2F%2Fhilltop.strait.link%2Fsummer&ua=instagram-android" \
  -H "Authorization: Bearer $SECRET_KEY"
```

The answer has the `decision` (`redirect`, `interstitial`, `escape`, `preview`, `expired` or `blocked`), `sentTo` (the same values as Analytics, below), the `location` the visitor would be sent to (or the main button's target on a page), and a plain-English `reason`. Hand-off URLs in it carry a placeholder tap id, `00000000-0000-4000-8000-000000000000`. You can also authenticate with `publishableKey=` as a query parameter; the link must belong to the key's workspace. **Dashboard → Playground** runs the same check.

## How taps are labelled

Each tap is recorded with where we sent it, `sent_to` (in the taps export and the `sentTo` webhook field):

| `sent_to` | Meaning |
|---|---|
| `app_or_store` | Android: your app if installed, otherwise the store |
| `app_or_website` | Android: your app if installed, otherwise your website |
| `store` | Directly to Google Play or the App Store |
| `website` | Directly to the destination or fallback website |
| `app_store_page` | The iPhone "Get the app" page |
| `in_app_browser_page` | The page shown inside an in-app browser (Instagram, Facebook, WhatsApp…) with "Open in app" |
| `expired` | The link had expired: the visitor saw "This link has expired". Recorded, never billed, no webhook |

Taps decided at Cloudflare's edge and taps served by our server are recorded with the same fields and labels.

A tap's **channel** is the first of these that has a value: the tap URL's `utm_source`, the link destination's `utm_source`, the in-app browser it was tapped in (`whatsapp`, `instagram`…), then the referring site. Taps with none of these are direct.

A link's **campaign** is the `campaign` you set. If you leave it out, it's filled in from the destination's `utm_campaign`, and follows it when you change the destination.

## Extra link fields

`POST /v1/links` also accepts these optional fields (all URLs must be https):

| Field | Purpose |
|---|---|
| `iosFallbackUrl`, `androidFallbackUrl`, `desktopUrl` | Where to send people on that platform when the app can't open |
| `title`, `description`, `imageUrl` | The preview shown in chat apps and social posts |
| `campaign` | Campaign name for analytics (also passed to the App Store as the campaign token). Defaults to the destination's `utm_campaign` |
| `tags` | Labels for filtering |
| `expiresAt` | When the link expires: epoch milliseconds or an ISO 8601 date-time |
| `expiredAction`, `expiredUrl` | Where taps go after expiry: `page`, `store` or `url` (with an https `expiredUrl`). Leave out to use the workspace setting. See [When a link expires](https://straitlink.in/docs/short-links/#when-a-link-expires) |

`PATCH /v1/links/{slug}` changes `longUrl`, `title`, `tags`, `expiresAt`, `expiredAction` and `expiredUrl`. Send only what changes; `null` clears `expiresAt` (never expires) and `expiredAction` (back to the workspace setting).

## Batch create

`POST /v1/links/batch` creates up to 500 links in one call, for imports and migrations. Send `{ "links": [ … ] }`, where each item takes the same fields as `POST /v1/links`. Every item is checked the same way (slug rules, https destinations, the unsafe-destination check, plan limits) and gets its own result, so one bad item never fails the batch:

```bash
curl https://strait.link/v1/links/batch \
  -H "Authorization: Bearer $SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "links": [ { "slug": "spring", "longUrl": "https://shop.example.com/spring" },
                  { "slug": "summer", "longUrl": "https://shop.example.com/summer", "campaign": "summer_2026" } ] }'
# → { "results": [ { "index": 0, "ok": true, "status": 201, "link": { … } }, … ],
#     "summary": { "total": 2, "created": 2, "failed": 0 } }
```

The response is `200` whenever the request itself is valid; read each item's `ok` and `status` (`201`, `400`, `402` or `409`). A slug that already exists, or repeats earlier in the same batch, is a `409` for that item only, so re-running an import is safe. Items past a plan limit get `402`. See [Migrate from Branch](https://straitlink.in/docs/migrate-from-branch/).

## Link health

Every live link carries `health` once Strait has checked it in the background: we open its destination, its iPhone, Android and desktop fallbacks, its A/B variants and your app's store listings about once a day, with the same checks as our free tools, and never through the short link (no taps are counted). `status` is `ok`, `attention` (a destination or store listing is broken, or on Firebase Dynamic Links) or `unknown` (we couldn't reach it); each problem names the `field`, the `url` and what the check saw. The dashboard shows these links as **Needs attention**. Changing a destination clears the old result.

## Retry safely with Idempotency-Key

If a create times out or the connection drops, you can't tell whether it worked. Send an `Idempotency-Key` header with `POST /v1/links` and `POST /v1/links/batch`, and retry with the same key and the same body. The second call gets the first call's answer instead of running again:

```bash
curl https://strait.link/v1/links \
  -H "Authorization: Bearer $SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1001-link" \
  -d '{ "slug": "summer", "longUrl": "https://shop.example.com/product/42" }'
# first call  → 201 { "slug": "summer", … }
# retry       → 201 { "slug": "summer", … } with the header Idempotent-Replayed: true (not 409)
```

- **The key:** 1 to 255 letters, digits or `. _ : -`. An order id or a UUID works. Each key belongs to your workspace and to the endpoint, and is kept for 24 hours.
- **Same key, different body:** `422` `idempotency_key_reused`. Use a new key for a new request.
- **Same key while the first call is still running:** `409` `idempotency_key_in_use` with `Retry-After: 1`.
- **Replayed:** `2xx` and `4xx` answers. **Not replayed**, so a retry runs again: `5xx`, `429` and `402` (a plan limit can lift).
- **Without the header,** nothing changes: a second create with the same slug is a `409`.

## Export

Export everything in your workspace at any time, on every plan. It gives you what you need to leave, or to keep your links running if Strait ever shuts down. Send your secret key; a publishable key gets `401`.

```txt
GET https://strait.link/v1/export?part=links|taps|events|webhooks|worker
Authorization: Bearer st_live_…
```

| `part` | What you get |
|---|---|
| `links` | NDJSON, one link per line: slug, destination, platform fallbacks and whether it is active |
| `taps` | CSV of every tap, joined to the app opens and installs that came from it. No date cap; add optional `from` and `to` (ISO dates) to narrow it |
| `events` | CSV of every conversion event (signups, purchases, revenue): `created_at, name, value, currency, platform, link_id, slug, click_id, channel, campaign, variant`. `channel`, `campaign` and `variant` come from the tap the event is attributed to, when it has a `click_id`. Oldest first, no date cap; optional `from` and `to` |
| `webhooks` | JSON of your webhook settings: `url`, `events`, `active` and `createdAt` for each one. Signing secrets are never exported; make new ones when you recreate a webhook |
| `worker` | A single-file Cloudflare Worker with the Android, iPhone and desktop fallbacks built in. Deploy it on your own account and route a link domain you own to it, and links on that domain keep redirecting. It can't serve `strait.link` links (that domain is ours), and on Starter and up your links can also live on a [custom domain](https://straitlink.in/docs/custom-domains/) |

```bash
curl "https://strait.link/v1/export?part=events&from=2026-01-01" \
  -H "Authorization: Bearer $SECRET_KEY" -o events.csv
```

Taps and events are streamed page by page, so an export of millions of rows starts right away and never times out on our side.

### Download from the dashboard

Owners and admins can download every part from **Dashboard → Settings → Download everything**: one button per file, no secret key needed. Members and viewers can't, because an export contains all of the workspace's data. The same section keeps the commands above under **Or from your server**.

Each button asks for a one-time download link, then your browser saves the file directly, however large:

```txt
POST https://strait.link/v1/export/token      {"part": "events"}
→ 201 {"token": "stx_…", "expiresAt": "…", "path": "/v1/export?part=events&token=stx_…"}
GET  https://strait.link/v1/export?part=events&token=stx_…
```

The token works once, for 60 seconds, for that part (and its `from` / `to`) only. Only a hash of it is stored. A used or expired token gets `401`.

The SDKs call the publishable-key endpoints for you; you only need those if you're writing your own client.


## Endpoints

### Links (secret key)

- [`GET /v1/links`](https://straitlink.in/docs/api/list-links/): List links
- [`POST /v1/links`](https://straitlink.in/docs/api/create-link/): Create a link
- [`POST /v1/links/batch`](https://straitlink.in/docs/api/batch-create-links/): Create up to 500 links in one call
- [`GET /v1/links/{slug}`](https://straitlink.in/docs/api/get-link/): Get a link
- [`PATCH /v1/links/{slug}`](https://straitlink.in/docs/api/update-link/): Update a link
- [`DELETE /v1/links/{slug}`](https://straitlink.in/docs/api/deactivate-link/): Deactivate a link
- [`GET /v1/links/{slug}/qr`](https://straitlink.in/docs/api/get-link-qr/): Get a branded QR code for a link
- [`GET /v1/qr.zip`](https://straitlink.in/docs/api/get-campaign-qr-zip/): Download every QR code of a campaign as one ZIP

### Analytics (secret key)

- [`GET /v1/analytics`](https://straitlink.in/docs/api/get-analytics/): Read analytics
- [`GET /v1/referrals`](https://straitlink.in/docs/api/get-referrals/): Read the referral report

### Export (secret key)

- [`GET /v1/export`](https://straitlink.in/docs/api/export/): Export everything
- [`POST /v1/export/token`](https://straitlink.in/docs/api/create-export-token/): Get a one-time export download link

### Webhooks (secret key)

- [`POST /v1/webhooks/{id}/test`](https://straitlink.in/docs/api/test-webhook/): Send a test event to a webhook
- [`GET /v1/webhooks/{id}/deliveries`](https://straitlink.in/docs/api/list-webhook-deliveries/): List a webhook's deliveries
- [`POST /v1/webhook-deliveries/{id}/redeliver`](https://straitlink.in/docs/api/redeliver-webhook-delivery/): Redeliver a webhook delivery

### Custom domains (secret key)

- [`GET /v1/domains`](https://straitlink.in/docs/api/list-domains/): List the workspace's custom domains
- [`POST /v1/domains`](https://straitlink.in/docs/api/add-domain/): Add a custom domain
- [`DELETE /v1/domains/{hostname}`](https://straitlink.in/docs/api/remove-domain/): Remove a custom domain

### Testing (secret key)

- [`GET /v1/funnel`](https://straitlink.in/docs/api/get-funnel/): Read the journey funnel
- [`GET /v1/taps`](https://straitlink.in/docs/api/list-taps/): List taps
- [`GET /v1/events`](https://straitlink.in/docs/api/list-events/): List conversion events
- [`GET /v1/usage`](https://straitlink.in/docs/api/get-usage/): Read this month's usage
- [`GET /v1/workspace`](https://straitlink.in/docs/api/get-workspace/): Who this key is
- [`GET /v1/app`](https://straitlink.in/docs/api/get-app-setup/): Read the app setup
- [`GET /v1/app/verify`](https://straitlink.in/docs/api/verify-app-setup/): Check the app integration
- [`GET /v1/simulate`](https://straitlink.in/docs/api/simulate-tap/): Dry-run a tap

### App and website (publishable key)

- [`POST /v1/match`](https://straitlink.in/docs/api/match-install/): Deferred-match lookup
- [`POST /v1/handoff/claim`](https://straitlink.in/docs/api/claim-handoff/): iPhone paste handoff (opt-in): claim a one-time handoff token
- [`POST /v1/store-sheet`](https://straitlink.in/docs/api/open-store-sheet/): Record an in-app store sheet tap and get what keeps the deep link
- [`POST /v1/referrer`](https://straitlink.in/docs/api/resolve-install-referrer/): Deferred-match resolution from Android Play Install Referrer
- [`POST /v1/resolve`](https://straitlink.in/docs/api/resolve-link/): Turn a short link that opened your app into its destination
- [`POST /v1/lookup`](https://straitlink.in/docs/api/lookup-link/): Where a short link goes, without recording anything
- [`POST /v1/open`](https://straitlink.in/docs/api/report-open/): Report that a link opened the app
- [`POST /v1/test-mode/match`](https://straitlink.in/docs/api/match-test-mode/): Deferred test mode: claim a test tap
- [`POST /v1/event`](https://straitlink.in/docs/api/send-event/): Record a conversion / revenue event

### Public (no key)

- [`POST /v1/report`](https://straitlink.in/docs/api/report-link/): Report a malicious link
- [`GET /v1/tools/app-links`](https://straitlink.in/docs/api/check-app-links/): App Links / Universal Links checker
- [`POST /v1/tools/link-check`](https://straitlink.in/docs/api/check-link/): Is my app link broken?
- [`GET /v1/trace/{st}`](https://straitlink.in/docs/api/get-tap-trace/): Live Tap Trace
