Links

The Link Object

Every link endpoint returns the same standardized object shape:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "slug": "my-campaign",
  "url": "https://example.com/landing-page?utm_source=twitter",
  "shortUrl": "https://flyn.to/my-campaign",
  "domain": "www.flyn.to",
  "title": "example.com",
  "clicks": 1423,
  "botClicks": 187,
  "qrScans": 64,
  "totalClicks": 1610,
  "status": "active",
  "tags": ["marketing", "q1-2026"],
  "createdAt": "2026-03-15T10:30:00.000Z",
  "expiresAt": null,
  "folderId": null,
  "password": false,
  "ogTitle": "Check out our new product",
  "ogDescription": "The fastest way to manage links",
  "ogImage": "https://example.com/og-image.png",
  "targeting": null,
  "cloaking": false,
  "noIndex": false,
  "notes": null,
  "rotation": null,
  "abUrlB": null,
  "abSplit": null
}

Create a Link

Creates a new short link. If no slug is provided, a random 6-character slug is generated.

Request Body

curl -X POST https://www.flyn.to/api/links \
  -H "Authorization: Bearer flyn_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/landing-page",
    "slug": "my-campaign",
    "tags": ["marketing", "q1-2026"],
    "ogTitle": "Check out our new product"
  }'

Response (201)

Returns the full Link object. Triggers link.create webhook event.

Error Codes

List Links

Returns a paginated list of your links with optional filtering and sorting.

Query Parameters

curl "https://www.flyn.to/api/links?page=1&limit=20&status=active&tag=marketing&sort=clicks&order=desc" \
  -H "Authorization: Bearer flyn_sk_live_..."

Response (200)

{
  "links": [ /* array of Link objects */ ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 142,
    "totalPages": 8,
    "hasMore": true
  }
}

Get a Link

Retrieves a single link by ID.

Path Parameters

Returns the full Link object, or 404 if not found.

Update a Link

Updates one or more fields on an existing link. Only include the fields you want to change.

Request Body

curl -X PATCH https://www.flyn.to/api/links/a1b2c3d4-... \
  -H "Authorization: Bearer flyn_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "tags": ["marketing", "updated"], "status": "archived" }'

Returns the updated Link object. Triggers link.update webhook event.

Delete a Link

Permanently deletes a link and all associated click data. This action cannot be undone.

Path Parameters

Response (200)

{ "deleted": true, "id": "a1b2c3d4-..." }

Triggers link.delete webhook event with the full link data that was deleted.

Smart Routing (Targeting)

The targeting field lets you redirect users to different destinations based on their device type or geographic location. Pass it as a JSON object when creating or updating a link.

{
  "targeting": {
    "device": {
      "ios": "https://apps.apple.com/app/your-app",
      "android": "https://play.google.com/store/apps/details?id=your.app",
      "windows": "https://apps.microsoft.com/detail/your-app-id",
      "macos": "https://apps.apple.com/app/your-mac-app"
    },
    "geo": {
      "US": "https://yoursite.com/us",
      "DE": "https://yoursite.com/de",
      "JP": "https://yoursite.com/jp"
    }
  }
}

The shape is enforced: anything else is refused with 400 and code: "INVALID_TARGETING", naming the keys it did not accept, rather than being stored as a rule that never fires. Device targeting takes four keys, ios, android, windows and macos, and all four live under device. windows and macos must be http or https URLs, such as a Microsoft Store, Mac App Store or download page. There is no desktop key, and mac, osx, win, desktop and linux are refused with a hint: Linux, ChromeOS and any other system match no device rule and fall through to the link's other rules. Geo targeting uses ISO 3166-1 alpha-2 country codes and sits at the top level, beside device. Device rules are evaluated first, then geo, then rotation when the link has one, then the default url.

Editing targeting

A PATCH replaces the whole targeting object; nothing is merged into the rules already stored. To add or change one rule, read the link first, edit its targeting and send the whole object back. Sending only a macos rule removes every other device and country rule. Send null or {} to remove them all.

Safari on Mac and iPad

Safari on an iPad usually sends the same user agent as Safari on a Mac, so the server alone cannot tell them apart. On a link with a macos rule, Safari on a Mac or an iPad first loads a blank check page that tells a Mac from an iPad, then continues at once. With JavaScript off the browser continues as a Mac. The check page records no click; the click is counted once, when the browser continues to the short link with the reserved query parameters flyn_os and flyn_ref, which are never passed to your destination. Chrome, Edge and Firefox on a Mac skip the check page, and a link without a macos rule never shows it. Device and country rules, including the Safari check page, do not apply to password-protected links, to a link that has reached its click limit, or to mailto, tel and sms links.

Link Rotation

The rotation field turns one short link into a weighted split across up to 12 destinations. It is available on Pro, Lifetime and Team; a free account gets 403 with code: "UPGRADE_REQUIRED" and premiumFields: ["rotation"].

Destination Object

curl -X POST https://www.flyn.to/api/links \
  -H "Authorization: Bearer flyn_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/offer-a",
    "rotation": [
      { "url": "https://example.com/offer-a", "weight": 3, "label": "Offer A" },
      { "url": "https://example.com/offer-b", "weight": 1, "label": "Offer B" }
    ]
  }'

The response echoes the stored rotation with an id filled in on every destination:

"rotation": [
  { "id": "V1StGXR8", "url": "https://example.com/offer-a", "weight": 3, "label": "Offer A" },
  { "id": "Z_Rk7bQ2", "url": "https://example.com/offer-b", "weight": 1, "label": "Offer B" }
]

How the split works

• Weights are relative, not percentages. They are normalised across the list, so 3 and 1 send roughly three quarters of clicks to the first destination, and equal weights give an even split.
• The destination is drawn per click in proportion to its weight, so the split settles over volume rather than following a strict repeating order.
• Maximum 12 destinations. Sending more returns a 400 rather than silently keeping the first twelve.
• If every weight is 0 there is nothing left to serve, so no rotation is stored and the link keeps serving the primary url.
• Bots and crawlers are never sampled into a rotation: they always receive the primary url, which is why it stays required.
• A matching targeting rule wins. Rotation only applies to visitors that smart routing did not already place.
• Every destination is safety scanned before the link is saved. A blocked one returns 422 with code: "DESTINATION_BLOCKED".

Editing a rotation

Each destination's id is what its clicks are recorded against, so it is the join key between a destination and its history. A PATCH replaces the whole list: read the link first, send every destination you are keeping back with the id it already has, and leave the id off only for genuinely new ones. Changing an id detaches that destination's past clicks, and reusing one merges two destinations' stats. Never derive ids from list position. Send an empty array to stop rotating and serve the single url again.

curl -X PATCH https://www.flyn.to/api/links/a1b2c3d4-... \
  -H "Authorization: Bearer flyn_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "rotation": [
      { "id": "V1StGXR8", "url": "https://example.com/offer-a", "weight": 3 },
      { "id": "Z_Rk7bQ2", "url": "https://example.com/offer-b", "weight": 1 },
      { "url": "https://example.com/offer-c", "weight": 1 }
    ]
  }'

A/B fields (compatibility view)

abUrlB and abSplit are the older two-destination form of the same idea, where abSplit is the percentage of traffic kept on the primary url. They remain accepted on create and update and are still returned on every link, so existing integrations keep working unchanged. Links that already used them were migrated into rotation under the ids A and B, so their click history stayed attached. When a link carries both, rotation is what the redirect serves. New integrations should use rotation: it is the full picture, and it is the only one of the two that goes past two destinations.

Slug Rules

• Allowed characters: a-z A-Z 0-9 - _
• Maximum length: 100 characters
• Must be unique per domain (you can reuse slugs across different domains)
• Reserved slugs (e.g. api, login, docs) cannot be used
• If omitted, a random 6-character slug is generated using nanoid. How many links a code of that length can hold, and when random codes start to collide, is worked out in How Long Should a Short URL Be?

SDK Examples

const link = await flyn.links.create({
  url: 'https://example.com/my-long-url',
  slug: 'my-campaign',
  domain: 'go.yourcompany.com',
  tags: ['marketing', 'q1-2026'],
  ogTitle: 'Check out our product',
});

console.log(link.shortUrl);
// → https://go.yourcompany.com/my-campaign

async function getUrlWithClicks() {
  const res = await flyn.links.list({
    status: 'active',
    tag: 'marketing',
    sort: 'clicks',
    order: 'desc',
    limit: 20,
  });

  res.data.forEach(l => console.log(l.shortUrl, l.clicks));
}

getUrlWithClicks();