Links

Create a link

Creates one short link with the full option set and returns it. Sends a link.create webhook to the calling user's webhooks.

Auth: API key (Bearer flyn_sk_live_...) or an MCP OAuth access token (Bearer flyn_mcp_at_...). The dashboard session cookie is not accepted.

Plan: Free accounts can create 25 links per UTC calendar month (counted per workspace), may not use a custom domain, and may not set the fields marked Pro; each returns 403 UPGRADE_REQUIRED. Pro, Lifetime or Team (a member of a paying owner's workspace has the effective plan team) have no limits here. The viewer team role gets 403.

Rate limit: 10 requests per 60 s per client IP, fixed window, in memory per server instance, checked before authentication.

An invalid JSON body returns 500, not 400.

post/api/links

Request

  • Base URL: https://www.flyn.to
  • URL: https://www.flyn.to/api/links
  • Auth: HTTP bearer

Request body

urlstring required

Destination. Trimmed; https:// is prepended unless it starts with http:, https:, mailto:, tel:, sms: or ftp:. ftp: is always refused. For http(s): the host must contain a dot, must not be a Flyn host, and must resolve in DNS to a public IP (else 400 "Private/internal URLs are not allowed"). mailto:, tel: and sms: skip host checks. Then a safety scan (422 when blocked); a deeper scan runs after the response and can disable the link later.

slugstring

Custom back-half. Not a reserved word (case-insensitive). Default: 6 random characters. Unique per domain (409 on clash).

domainstring

Short domain. Default: the current Flyn short domain; the legacy value www.flyn.to is treated as a request for that default. Any other value must exactly match (case-sensitive) a custom domain owned by the workspace, else 403. Pro for any custom domain.

titlestring

Display title. Default: the part of the URL after // up to the next / (usually the hostname, but it keeps any port or userinfo, and a query or fragment when there is no path), else "Untitled".

tagsstring[]

Pro. Tags. Default [].

passwordstring

Pro. Password gate (stored as a bcrypt hash). An empty string is ignored.

expiresAtstring date-time

Expiry (ISO 8601). Must parse as a date; past dates are accepted and stored as sent.

folderIdstring uuid

Folder in the workspace, else 404.

ogTitlestring

Social preview title.

ogDescriptionstring

Social preview description.

ogImagestring uri

Social preview image. http or https; the host must resolve to a public IP.

cloakingboolean

Pro. Cloaking.

noIndexboolean

Pro when true. Accepted and stored for compatibility. It has no effect on how the link is served: every short link is already served with a noindex robots header on every plan, whether or not this is set.

notesstring

Private notes.

abUrlBstring

Pro. Legacy A/B variant URL. http or https, not a Flyn host (400 "Cannot shorten Flyn URLs"), public IP, safety scanned (422).

abSplitnumber

Pro. Legacy A/B split, percent kept on the primary url. Clamped to 0..100; a non-finite value becomes 50.

deepLinkboolean

Pro. Serve the native-app handoff page on mobile. null returns 400.

pixelIdsstring[]

Pro. Saved pixel ids to fire. Ids outside the workspace are dropped silently. If any id is not a valid UUID, every id is dropped (no error).

forwardParamsboolean

Pass the short link's query string through to the destination.

clickLimitinteger

Pro. Maximum human clicks. null or "" is ignored.

fallbackUrlstring

Pro. Destination once the click limit is reached. https:// is prepended; http or https, not a Flyn host, public IP, safety scanned (422).

conversionTrackingboolean

Pro. Only the literal true enables it.

Response

The created link.

idstring uuid required

Link id.

slugstring required

Back-half of the short URL.

urlstring required

Destination URL.

shortUrlstring uri required

Full short URL, https://<domain>/<slug>.

domainstring required

Short domain the link lives on. New links default to the current Flyn short domain.

titlestring nullable required

Display title.

clicksinteger required

Human clicks (bots and scanners excluded). This is the headline number.

botClicksinteger required

Clicks filtered out as bots or scanners.

qrScansinteger required

Clicks that arrived from a Flyn QR code; a subset of clicks.

totalClicksinteger required

clicks + botClicks.

status'active' | 'expired' | 'archived' required

Stored status. A link past expiresAt keeps active here; the redirect checks the expiry itself.

tagsstring[] required
createdAtstring date-time required
expiresAtstring nullable required

Expiry as stored (ISO 8601), or null.

folderIdstring uuid nullable required
passwordboolean required

True when the link is password protected. The password itself is never returned.

ogTitlestring nullable required
ogDescriptionstring nullable required
ogImagestring nullable required
cloakingboolean required
noIndexboolean required

Stored value of the legacy per-link no-index flag. It has no effect on how the link is served: every short link is already served with a noindex robots header on every plan, whether or not this is set.

notesstring nullable required

Private notes.

abUrlBstring nullable required

Legacy two-way A/B view of rotation, kept for older integrations.

abSplitnumber nullable required

Legacy A/B split: percent kept on the primary url.

deepLinkboolean required

Native-app handoff mode on mobile.

pixelIdsstring[] required

Retargeting pixels fired on click.

forwardParamsboolean required

Query-string passthrough to the destination.

clickLimitinteger nullable required

Maximum human clicks. Once reached, visitors go to fallbackUrl, or to the expired-link page when no http(s) fallbackUrl is set.

fallbackUrlstring nullable required

Destination after the click limit is reached.

conversionTrackingboolean required

When true, each human click gets a flyn_id click id for conversion pings.

conversionsinteger required

Recorded conversions, net of refunds (never below 0).

conversionValueCentsinteger required

Summed conversion value in minor units.

conversionCurrencystring nullable required

Currency of the summed value.

Changes

No recorded changes to this operation across all 1 revision of this API.