Client API
These routes support browser and mobile integrations with a publishable key. Prefer an SDK to manage consent, installation identity, stored tokens, and retries. Never put a server key in a device or page.
Resolve a link
POST /v1/resolve accepts url, consent: true, and optional platform (web, ios, android, tvos, or androidtv; default web). The URL must be an actual active LinkRunway link in the key's workspace, with the correct host and /l/<key> or configured /r/<key> path.
# LINKRUNWAY_LINK_URL is the actual shortUrl returned for your link.
curl --fail-with-body https://api.linkrunway.com/v1/resolve \
-H "Authorization: Bearer $LINKRUNWAY_PUBLISHABLE_KEY" \
-H 'Content-Type: application/json' \
--data "{\"url\":\"$LINKRUNWAY_LINK_URL\",\"platform\":\"web\",\"consent\":true}"For production code, use a JSON serializer instead of shell interpolation. A response contains clickId, optional clickToken, path, url, and metadata. Route only to application paths you allow. A bot, privacy signal, or blocked source may receive no eligible attribution token.
When the click allowance is exhausted, routing can still succeed with untracked: true and an empty clickId. Treat routing success and attribution as separate outcomes.
Create a share
POST /v1/shares accepts required linkId (1–100 characters), optional externalUserId (1–200), and optional channel (at most 80). It returns { shareId, url } for an active link in the workspace.
A share ID identifies this share; it is not a verified customer or a payment. Repeating the POST can create a new share. The SDK requires consent before calling this method even though this route's JSON shape does not include a consent field.
Explicit referral codes
POST /v1/deferred accepts { clickToken, consent: true } and returns { code, expiresAt }. The token must reference an eligible click. The generated 12-character code expires after 24 hours.
POST /v1/deferred/claim accepts { code, claimId, consent: true }. claimId is a UUID generated and persisted by the claiming installation. A successful claim returns the resolved link, metadata, and click token. Retry using the same claim ID. Another claimant, expiration, or an unavailable link returns 410.
Let the person explicitly copy or enter a referral code. Do not silently read the clipboard or promise deterministic deferred attribution where the platform provides no signal.
Match an install
POST /v1/installs/match accepts:
| Field | Value |
|---|---|
installId | Required UUID, stable for this consented installation |
platform | ios, android, tvos, or androidtv |
consent | Required true |
osVersion | Optional 1–3 numeric components, each 1–3 digits |
language | Optional language tag, at most 35 characters |
referrer | Optional installation referrer, at most 4,000 characters |
The response has matched and method (REFERRER, PROBABILISTIC, VIEW_THROUGH, or NONE) plus optional clickId, clickToken, path, url, and metadata. A no-match result is valid. Network-based matching depends on workspace policy and privacy signals; it is not guaranteed.
Ad-network evidence
POST /v1/claims/apple-ads accepts installId (UUID), token (20–4,000 characters), and consent: true. Obtain the token using Apple's supported device API; the server verifies it.
POST /v1/claims/referrer accepts installId (UUID), appId (the registered LinkRunway app ID, 1–100 characters), referrer (1–8,000 characters), and consent: true. Use actual install-referrer evidence from the device.
These routes submit evidence, not verified payment events. Use the iOS, Android, and mobile SDK guides for collection and platform setup. Never invent a network token or assume a claim guarantees attribution.