REST API
A small JSON API over HTTPS. Generated from the same OpenAPI description the server publishes at /v1/openapi.json.
On this page 15
Base URL
https://strait.linkEvery endpoint has its own page, with the request in curl, Node, Python, PHP, Java and Go next to the response: see 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, verify webhook signatures and send links in WhatsApp templates.
- Download the OpenAPI description (also served live at
https://strait.link/v1/openapi.json) for Insomnia or a code generator. - Download the Postman collection: in Postman, Import, pick the file, then set
secretKeyandpublishableKeyin 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 and secret keys are in Dashboard → Settings → Keys. The examples on this page read the secret key from an environment variable:
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.
Errors and limits
Every error under /v1 is JSON with an error message, never an HTML page:
{ "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.
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.
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:
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 pagePass 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.
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 |
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:
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.
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:
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:
422idempotency_key_reused. Use a new key for a new request. - Same key while the first call is still running:
409idempotency_key_in_usewithRetry-After: 1. - Replayed:
2xxand4xxanswers. Not replayed, so a retry runs again:5xx,429and402(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.
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 |
curl "https://strait.link/v1/export?part=events&from=2026-01-01" \
-H "Authorization: Bearer $SECRET_KEY" -o events.csvTaps 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:
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/linksList links - POST
/v1/linksCreate a link - POST
/v1/links/batchCreate up to 500 links in one call - GET
/v1/links/{slug}Get a link - PATCH
/v1/links/{slug}Update a link - DELETE
/v1/links/{slug}Deactivate a link - GET
/v1/links/{slug}/qrGet a branded QR code for a link - GET
/v1/qr.zipDownload every QR code of a campaign as one ZIP
Analytics (secret key)
Export (secret key)
Webhooks (secret key)
- POST
/v1/webhooks/{id}/testSend a test event to a webhook - GET
/v1/webhooks/{id}/deliveriesList a webhook's deliveries - POST
/v1/webhook-deliveries/{id}/redeliverRedeliver a webhook delivery
Custom domains (secret key)
- GET
/v1/domainsList the workspace's custom domains - POST
/v1/domainsAdd a custom domain - DELETE
/v1/domains/{hostname}Remove a custom domain
Testing (secret key)
- GET
/v1/funnelRead the journey funnel - GET
/v1/tapsList taps - GET
/v1/eventsList conversion events - GET
/v1/usageRead this month's usage - GET
/v1/workspaceWho this key is - GET
/v1/appRead the app setup - GET
/v1/app/verifyCheck the app integration - GET
/v1/simulateDry-run a tap
App and website (publishable key)
- POST
/v1/matchDeferred-match lookup - POST
/v1/handoff/claimiPhone paste handoff (opt-in): claim a one-time handoff token - POST
/v1/store-sheetRecord an in-app store sheet tap and get what keeps the deep link - POST
/v1/referrerDeferred-match resolution from Android Play Install Referrer - POST
/v1/resolveTurn a short link that opened your app into its destination - POST
/v1/lookupWhere a short link goes, without recording anything - POST
/v1/openReport that a link opened the app - POST
/v1/test-mode/matchDeferred test mode: claim a test tap - POST
/v1/eventRecord a conversion / revenue event
Public (no key)
- POST
/v1/reportReport a malicious link - GET
/v1/tools/app-linksApp Links / Universal Links checker - POST
/v1/tools/link-checkIs my app link broken? - GET
/v1/trace/{st}Live Tap Trace
Objects
WebhookDelivery
| Field | Type | Notes |
|---|---|---|
id | string | Also sent as X-Strait-Delivery |
webhookId | string | |
event | string | |
status | "pending" | "delivered" | "failed" | |
attempts | integer | |
lastStatus | integer,null | The receiver's last HTTP status |
lastError | string,null | |
nextAttemptAt | string,null | pending only |
createdAt | string | |
deliveredAt | string,null |
Domain
| Field | Type | Notes |
|---|---|---|
hostname | string | |
verified | boolean | true once Cloudflare reports the hostname and its certificate active and the ownership TXT record is in your DNS. Only then do links work on it. |
status | "live" | "pending_dns" | "issuing_certificate" | "problem" | "not_created" | "unknown" | live = serving your links. pending_dns = waiting for the CNAME and TXT records. issuing_certificate = DNS found, HTTPS certificate on its way. problem = needs attention (see message). not_created = saved while custom domains are read-only. unknown = the status could not be read right now. |
message | string | Cloudflare's own words when something needs attention. |
records | object[] | The DNS records to add at your DNS provider: one CNAME and the TXT records Cloudflare asks for. |
Link
| Field | Type | Notes |
|---|---|---|
id | string | |
slug | string | Unique among the workspace's active links (another workspace may use the same slug). |
shortUrl | string | The link to share, on your workspace link domain: https://<handle>.strait.link/<slug>. Links live on their workspace's host; the bare root only answers a slug no other workspace uses. |
longUrl | string | |
tenantId | string | The workspace the link belongs to. |
isActive | boolean | false once deactivated (DELETE /v1/links/{slug}). |
iosFallbackUrl | string | |
androidFallbackUrl | string | |
desktopUrl | string | |
webTapId | boolean | This link's override of the workspace setting for strait_click on web pages (see NewLink). Absent = the workspace setting (on unless turned off). |
description | string | |
imageUrl | string | |
campaign | string | Analytics campaign; defaults to longUrl's utm_campaign. |
health | object,null | Link health (ADR 0057): the last background check of the destinations and store listings. status ok | attention | unknown; each problem has field, url, verdict (broken | at_risk) and the checker's summary. Absent until the first check. |
variants | object[] | A/B destination variants, when set. |
passwordProtected | boolean | Present (true) when the link has a password. |
blockedReason | string | Set when the link was disabled under the Acceptable Use Policy. |
title | string,null | |
tags | string[] | |
expiresAt | integer,null | epoch ms |
expiredAction | "page" | "store" | "url" | "null" | 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. Absent/null = the workspace setting (Settings → When a link expires; default page). |
expiredUrl | string,null | This link's expired-link web page (https); absent = the workspace's. |
startsAt | integer,null | epoch ms. Scheduled go-live: before it, taps get notLiveAction. Absent = live now. |
notLiveAction | "page" | "store" | "url" | "null" | 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. Absent = page. |
notLiveUrl | string,null | This link's not-live web page (https). |
countryRules | array,null | 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 | Only in the POST /v1/links answer, and only when the code was saved. Not returned by the list, get or update endpoints yet. |
NewLink
| Field | Type | Notes |
|---|---|---|
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. |
FunnelByPlatform
| Field | Type | Notes |
|---|---|---|
android | integer | |
ios | integer | |
desktop | integer | |
other | integer |
JourneyFunnelBody
| Field | Type | Notes |
|---|---|---|
link_id | string,null | The link's id, or null for the whole workspace. |
steps | object[] | Always four, in order, never increasing: clicked, app_or_store, opened_app, reached_screen. |
phone_clicks | integer | Taps minus the computer exit: the base of step 2. |
exits | object[] | Who left before step 2, in this order: computer (sent to your website), phone_website (a phone sent to your website), in_app_browser (saw the open-in-app page inside Instagram, WhatsApp… and did not press it), other (not tracked). |
drops | object[] | store_no_open (after app_or_store: sent to the store, no app open seen) and open_failed (after opened_app: the app opened but the link did not resolve; reasons such as expired, not_found, network, no_match, unknown). |
untied_failed_opens | object | App opens that failed and name no tap (the link expired or was not found, so no tap was recorded): no step can hold them. With a filter, only those whose link fits it. |
installs | object | Installs of the period (GET /v1/analytics installs), by where the tap was. credited = from_period_clicks + from_earlier_clicks + from_link_no_click; total = credited + organic; credited = exact + estimated (estimated: an iPhone device match). from_period_clicks = steps[2].split.installed. |
match_certainty | object | The two exact / estimated numbers, each named by what it counts: installs = credited installs (exact: Play referrer, clipboard, app hand-off; estimated: an iPhone device match); reached_screen = taps that reached the screen (= steps[3]). They count different things and never add up to each other. |
website_opens | integer | Taps whose website reported the landing (web SDK reportWebOpen): they opened your website, not the app. Never an app open or an install. |
test_data_left_out | object | Taps and installs of Strait's own test links (our smoke / QA / load checks in our own workspaces) in this range, left out of every number above. Always 0 for your workspace. |
revenue | object | Revenue after a tap: POST /v1/event values in the period that carry a tap of this slice (the tap may be older), per ISO currency (never summed across currencies). |
days | array,null | Taps and reached_screen per local day (tz) of the range, every day listed (zeros included); null for a range over 400 days. The days add up to steps 1 and 4. |
did_something | integer,null | Of reached_screen, how many sent at least one event (POST /v1/event) with that tap; null when your app has never sent an event. |
unmatched_first_opens | integer,null | First opens after an install we could not connect to any tap; whole workspace only (null with a filter). |
installs_without_click | integer | Installs matched to a link but not to one tap. |
expired_taps | integer | Taps on expired links: in no step. |
FunnelInstallParts
| Field | Type | Notes |
|---|---|---|
credited | integer | |
tied_to_click | integer | |
from_period_clicks | integer | |
from_earlier_clicks | integer | |
from_link_no_click | integer | |
organic | integer | |
exact | integer | |
estimated | integer |
JourneyFunnel
AnalyticsMetrics
| Field | Type | Notes |
|---|---|---|
taps | integer | Taps on live links (not deferred-match entries, not taps on expired links). |
billableTaps | integer | Of those, the taps that count toward your plan (a repeat of the same tap within seconds is not billed). |
appOpens | integer | App opens reported by the SDKs that came from one of your links. |
installs | integer | Installs tied to one of your links (organic installs are not counted). The installs and first-open reports are merged: reports naming the same tap are one install, the same definition as the dashboard. |
conversions | integer | POST /v1/event events tied to one of your links (directly or through their tap). |
revenue | object | Event values summed per currency code (upper case; '' when an event gave none). Currencies are never added together. |
AnalyticsRow
Tap
| Field | Type | Notes |
|---|---|---|
clickId | string | |
clickedAt | string | |
linkId | string | |
slug | string,null | |
source | string,null | web (a tap in a browser) or an SDK source |
platform | string,null | |
deviceClass | "phone" | "tablet" | "desktop" | "null" | |
osMajor | integer,null | |
inAppBrowser | string,null | |
channel | string,null | |
sentTo | string,null | Where the tap was sent |
campaign | string,null | |
variant | integer,null | |
billable | boolean,null | false for a repeat within 10 seconds |
opens | integer | App opens joined to this tap |
openedAt | string,null | |
openKind | "direct" | "deferred" | "null" | |
openRoute | string,null | |
appState | string,null | |
isNewUser | boolean,null | |
installedAt | string,null | |
installMatched | boolean,null | |
matchMethod | string,null | |
appVersion | string,null | App version that first opened this tap (else its install), as the SDK reported it |
sdkVersion | string,null | Strait SDK version of that open |
ConversionEvent
| Field | Type | Notes |
|---|---|---|
id | string | |
createdAt | string | |
name | string | |
value | number,null | |
currency | string,null | |
platform | string,null | |
linkId | string,null | |
slug | string,null | |
clickId | string,null | |
channel | string,null | |
campaign | string,null | |
variant | integer,null |
AppLinksFinding
| Field | Type | Notes |
|---|---|---|
id | string | |
severity | "ok" | "warn" | "error" | |
title | string | |
detail | string | |
fix | string |
MatchInfo
| Field | Type | Notes |
|---|---|---|
method required | "install_referrer" | "clipboard" | "fingerprint" | "test" | |
confidence required | "exact" | "high" | "probable" |
MatchResult
| Field | Type | Notes |
|---|---|---|
matched | boolean | |
longUrl | string,null | |
linkId | string,null | |
matchMethod | "install_referrer" | "exact_ext" | "exact_core" | "scored" | "clipboard" | "test" | "none" | How it matched. 'clipboard' = a claimed paste-handoff token (POST /v1/handoff/claim). 'test' = test mode: a debug re-check (record:false) answered from the workspace's open test window (Dashboard -> Setup -> Test a link). 'scored' is reserved for the scored iPhone matcher, which is not enabled yet. |
confidence | "high" | "medium" | "null" | Scored matches only (matchMethod 'scored'): 'high' or 'medium'. Null for every other answer of /v1/match. |
match | object | |
clickId | string | When matched: the id of the tap this install came from. The SDKs remember it and send it with conversion events (/v1/event clickId). |
referralCode | string | Present only when matched and the tap carried a referral code: the tap's ?strait_ref=, else its link's referralCode. Absent otherwise (never null). The SDKs pass it to your app as referralCode on the deferred link. |
test | "true" | Present (true) only on a test-mode answer: a debug re-check (record:false) while the workspace's test window was open. matched:false then carries reason no_tap (no tap since the window opened; tap a link and check again), other_device (the window belongs to the first phone that checked in) or not_found. A test answer never carries clickId. Absent otherwise. |
ios | object | /v1/match with platform 'ios' only: the workspace's current iPhone deferred-link choice (device matching and/or paste handoff, the customer's choice in the dashboard; opt-in, off by default), read live on every lookup so a change in the dashboard applies without an app release. The SDKs never store it. |
ipv4Match | string | iPhone first-launch check only (platform 'ios', openId sent, record not false): present when this ask came over IPv6 and found no tap (reason no_candidate). The phone may have tapped over IPv4: the SDK sends the same request (same openId, same fields) once more to this IPv4-only URL. A match there answers exact_ext with reason ip_family (match.confidence probable, never exact) and the install recorded by the first ask becomes matched (counted once). Absent otherwise. |
reasons | string[] | Why the matcher matched or refused, as short codes (never personal data). Exact matcher: exact_ext, exact_core, no_candidate, ambiguous (two identical-looking taps for different links: Strait refuses rather than guesses), race_lost (another lookup already took this tap), device_matching_off (the workspace turned iPhone install matching off), ip_family (matched across IPv4 / IPv6: the IPv4-only probe host). Paste handoff: clipboard, handoff_unknown, handoff_used, handoff_expired. Scored matches add signal codes (e.g. ipv6_64, ip_exact, asn, lang_full, dt_42s). New codes may be added; treat unknown codes as informational. |