Building with the Flyn API: A Developer's Guide

If you've ever had to bulk-create 5,000 redirect URLs for a campaign, build a customer-portal feature that generates branded short links on the fly, or auto-shorten every blog URL on publish, you already know hand-crafting short links in a dashboard doesn't scale. The Flyn API is the answer: a small, well-typed REST surface that lets you do everything the dashboard does, plus a handful of things the dashboard intentionally doesn't.

This guide walks through the API end-to-end: authentication, the nine core endpoints, the TypeScript SDK, webhooks, rate limits, and the error-handling patterns we've seen production teams converge on. If you're evaluating Flyn against Bitly, Rebrandly, or Short.io specifically for API workloads, this is the document to read.

What you need before you start

Three things: a Flyn account with a Pro plan (API access is a Pro feature), an API key from Settings > API Keys, and any HTTP client. The base URL for every request is https://www.flyn.to. Endpoints live under /api/*. Responses are JSON; requests with a body must set Content-Type: application/json.

Creating an API key

Open the dashboard, navigate to Settings > API Keys, click New key, and label it descriptively (e.g. ci-deploy-bot, marketing-platform-prod). The full key is shown exactly once on creation, copy it immediately into a secrets manager. Flyn stores only the SHA-256 hash server-side, so if you lose the plaintext, you regenerate.

API keys are scoped to a single workspace. If your team uses multiple workspaces (e.g. marketing + product), generate one key per workspace and store them under separate environment variables.

Every request includes an Authorization: Bearer <your-key> header. There's no signed-request flow, no OAuth dance, keep it simple, store the key as a secret. See the full authentication doc for examples in cURL, Node, Python, and Go.

The nine endpoints you'll actually use

Most integrations only touch a handful of endpoints. Here's the cheat sheet:

For deep-link routing toggles, the deep_link boolean is set on POST /api/links, see the deep links doc for the routing matrix.

A minimal first call

Hit POST /api/links with a JSON body of {"destination": "https://example.com/long-url"} and you get back a JSON object with a short URL on flyn.to (or your branded domain if you specified one). That's the whole MVP. Everything else, custom slugs, tags, UTM parameters, expiry dates, passwords, is optional fields on the same payload.

You can call the API with raw fetch, axios, got, or whatever your runtime ships with. But the official TypeScript SDK saves real engineering time: full type coverage for every request and response shape, automatic retries on 429 and 5xx with Retry-After-aware backoff, cursor and offset pagination helpers, and edge-runtime compatibility out of the box.

Install and initialize

Run npm install flyn-sdk (or your equivalent pnpm/yarn command). Initialize once at module scope:

• Node.js / Next.js API routes: const flyn = new Flyn({ apiKey: process.env.FLYN_API_KEY })
• Cloudflare Workers: same constructor, pass env.FLYN_API_KEY from the request context
• Deno: import via npm:flyn-sdk specifier, fully ESM, no node: shims required
• Vercel Edge Functions: works on the edge runtime; the SDK uses native fetch only

The shape of an SDK call

Every method maps 1:1 to a REST endpoint. flyn.links.create({ destination, slug }) wraps POST /api/links. flyn.links.clicks(linkId, { from, to }) wraps GET /api/links/:id/clicks. Method signatures are typed via the public FlynApi namespace, your editor will autocomplete every field, including which ones are optional. No more squinting at JSON schemas at 2am.

The POST /api/links endpoint takes a single JSON body and returns the created link. The only required field is destination, the long URL to redirect to.

Optional fields you'll reach for

• slug, your custom path (e.g. q2-launch). If omitted, Flyn generates a 7-character random slug.
• domain, your branded domain (e.g. links.yoursite.com). Defaults to flyn.to.
• tags, array of tag names for filtering in the dashboard. New tags are auto-created.
• expires_at, ISO 8601 timestamp. After this moment, the link stops redirecting.
• password, string. Visitors see a password prompt before redirect. Hashed server-side.
• utm_source, utm_medium, utm_campaign, utm_term, utm_content, appended to the destination URL on every redirect.
• deep_link, boolean. Enables native-app routing for the 16+ platforms listed in the deep links guide.

Idempotency for safe retries

Pass an Idempotency-Key header (any unique string, e.g. a UUID) on creation. If the request fails halfway through (network blip, timeout, your function gets killed mid-flight), retrying with the same key returns the same link instead of creating a duplicate. The key is valid for 24 hours after the original request.

Bulk creation patterns

The API doesn't expose a bulk-create endpoint by design, every link is its own operation, billed and rate-limited individually. For high-volume work (importing 10,000 legacy URLs), throttle to ~9 requests/min and use exponential backoff on 429. For one-time imports, use the dashboard's CSV import tool, see how to migrate from Bitly to Flyn for the recommended workflow.

For UTM-heavy programmatic generation (e.g. campaign sequencing in a CMS), generate UTM values with the UTM Builder spec first, validate them with the redirect checker, then commit the cleaned URL to the API. Garbage in, garbage out.

Click data is the reason most teams pay for a link-shortener API in the first place. The GET /api/links/:id/clicks endpoint returns paginated click events with the full attribution payload Flyn captures at redirect time. See the full clicks doc for every field.

What's in a click event

• Geo: country (ISO-3166 alpha-2), region, city
• Device: device_type (mobile/desktop/tablet), os, browser, browser_version
• Network: asn, connection_type (mobile/wifi/wired)
• Referrer: full referrer URL when available, plus a parsed referrer_host for grouping
• UTM: any UTM values present on the redirect, surfaced as top-level fields
• Bot signal: is_bot boolean, Flyn classifies and excludes bot clicks from default counts (read more about click fraud prevention)
• Timestamp: created_at in ISO 8601 UTC

Filtering and pagination

Use from and to query parameters (ISO 8601) to constrain by date range. Pagination is offset-based: page (1-indexed, default 1) and limit (default 50, max 100). The response's meta object contains total, page, limit, and total_pages.

For very large queries (a year of clicks on a hot link), use the SDK's flyn.links.clicks.paginate() generator, it iterates pages lazily, respecting rate limits, and yields one event at a time so you can pipe into a database without buffering everything in memory.

Aggregates vs raw events

If you only need totals (e.g. for a customer-facing dashboard), prefer GET /api/analytics/summary, it returns pre-aggregated counts by country, device, browser, and time bucket without the per-event payload. Much cheaper than fetching raw events and aggregating client-side.

Polling the API every minute to detect new clicks is wasteful and laggy. Use webhooks instead, Flyn pushes a JSON payload to your endpoint within ~200ms of every subscribed event. Full spec is in the webhooks doc.

Subscribable events

Verifying the signature

Every delivery includes an X-Flyn-Signature header containing an HMAC-SHA256 of the raw request body, signed with the webhook secret shown when you create the subscription. Always verify it. Compute the same HMAC on your server using the raw (un-parsed) body and compare to the header value with a constant-time comparison (Node's crypto.timingSafeEqual, Go's hmac.Equal).

Retries and dead-letter behavior

If your endpoint returns a non-2xx status (or doesn't respond within 10 seconds), Flyn retries with exponential backoff: 30s, 2m, 10m, 30m, 2h, 6h, 12h. After 7 failed attempts, the event lands in your dashboard's dead-letter queue, viewable under Webhooks > Failed Deliveries. You can replay any failed delivery manually from there.

The Flyn API uses standard HTTP status codes alongside a structured JSON error body. Every non-2xx response includes a code, a human-readable message, and an errors array of field-level issues. See the errors doc for the full table.

The status codes you'll see most

Typed errors in the SDK

The TypeScript SDK throws FlynApiError for every non-2xx response. The instance carries code, message, statusCode, and a typed field property where applicable. You can narrow on error.code === 'slug_conflict' instead of regex-matching error strings.

Handling 409 slug conflicts gracefully

If your integration lets users pick a custom slug, a 409 means someone else already took it on that domain. The UX move is to show "that slug is taken, try another?" inline, not to throw an opaque error. The SDK exposes flyn.links.checkSlug({ slug, domain }) to pre-validate availability before submission.

Flyn enforces per-key rate limits to keep the platform fair: 10 mutations per minute (any POST, PATCH, or DELETE) and 60 reads per minute (any GET). Higher limits are available on the Pro and Enterprise plans and via the contact form for unusual workloads. Full breakdown in the rate-limits doc.

Reading the rate-limit headers

Every response carries three headers you should pay attention to:

• X-RateLimit-Limit, the bucket size (10 or 60)
• X-RateLimit-Remaining, requests left in the current window
• X-RateLimit-Reset, Unix timestamp when the window resets

On 429, also read Retry-After (seconds) and back off at least that long. The SDK does this automatically.

The pagination pattern that scales

For the GET /api/links and GET /api/links/:id/clicks endpoints, use offset pagination for arbitrary page-jumping (e.g. "go to page 5") and cursor pagination (via the cursor query parameter) for full-table iteration. Cursor pagination is consistent across writes that happen mid-iteration, which offset pagination isn't.

The teams that build smooth Flyn integrations have one thing in common: they treat the API as their infrastructure, not a black box. Pin SDK versions, store rate-limit metadata, log every 4xx, alert on 429 spikes. The API is well-typed and the docs are short, the wins come from how you wrap it.

The API surface is small enough that the interesting question is what teams build with it. Here are four patterns we see repeatedly in production. Inspiration, not prescription.

1. CI/CD preview-link automation

On every preview deployment (Vercel, Netlify, Cloudflare Pages), call POST /api/links with the preview URL as the destination and a slug like pr-{number}. Post the resulting flyn.to/pr-1234 to Slack as a deployment notification. The short link is readable in chat, click analytics show you who's reviewing your PR, and reviewers don't fumble with long preview URLs. Less than 30 lines of code in any CI platform.

2. Customer-facing link management feature

If you're a CMS, email tool, or social-media manager, your customers want branded short links for the content they create. Use the API to mint links on their behalf, pass the destination on save, store the returned link ID, surface analytics in your UI by calling GET /api/links/:id/clicks. Multi-tenant support is built in via workspaces; one workspace per customer keeps data isolated.

3. Internal link-management dashboard

For larger teams, a thin internal dashboard on top of the Flyn API gives you exactly the filters and reports your org needs. Front it with React + SWR (or your favorite data-fetching lib), use the SDK's SWR-compatible methods, layer in role-based permissions backed by your existing SSO. We see teams build this in a week and replace three half-broken Notion docs with it.

4. Automated webhook-driven workflows

Subscribe to link.click and pipe events into your CRM. When a high-value prospect clicks a proposal link, fire a Slack alert to the AE. When a customer clicks an in-app upgrade link, mark them for outreach. The webhook payload includes the full click context, geo, device, UTM, so you can branch on attribution. Read click fraud prevention first to filter bots before you act on events.

Where to go next

Read the docs index for the full API reference. If your project also needs in-tab link creation for your team, install the Flyn Chrome extension. If you're building anything that touches mobile, the deep links guide explains the routing behavior. And if your workload involves passwords, expiration, or compliance, see the link security guide for the API fields that map to those Pro features.

To see the API in the context of a specific marketing stack, the integration guides pair Flyn with GA4, Mailchimp, SendGrid, HubSpot, and ten more platforms, including when to reach for the API instead of the dashboard.