OpenAPI Specification

What the spec covers

Flyn publishes an OpenAPI 3.1.0 description of its REST API at https://www.flyn.to/api/openapi.json. It is written against the same API routes these docs describe, and a build check (scripts/verify-openapi.mjs) fails if any path or method in it has no matching route. The operation and event tables further down this page are built from the same file you download.

• 29 operations on 17 paths, grouped as Links, Quick Shorten, QR Codes, Click Analytics, Domains, Retargeting Pixels, Conversion Tracking, Webhooks.
• The 5 webhook events Flyn sends to your endpoint, in the top-level webhooks object that OpenAPI 3.1 added for requests your server receives.
• The authentication scheme each operation accepts.
• 54 reusable schemas for request bodies, responses and webhook payloads.

Requests go to https://www.flyn.to, and this is version 1.0.0 of the document. The prose pages linked below remain the place for walkthroughs, limits and examples.

Loading it into your tools

Most tools that read OpenAPI 3.1 can use the spec URL or the downloaded file. A few common options, listed as examples rather than recommendations:

• Postman: choose Import and paste the spec URL into the import field. Postman builds a collection of requests from it.
• Insomnia: open the import dialog, pick the URL option, and paste the same address (or import the downloaded file).
• Swagger Editor or Redocly: load the URL or the file to browse operations, parameters and schemas as rendered reference pages.
• openapi-generator: generate a typed client for the language you work in (example below).

Support for OpenAPI 3.1 varies between tools and versions, so if one rejects the file, try another. Flyn is not affiliated with any of them. After importing, set the Authorization header to Bearer flyn_sk_live_... at the collection or environment level.

# The generator CLI downloads a Java jar, so it needs a Java runtime.
npx @openapitools/openapi-generator-cli generate \
  -i https://www.flyn.to/api/openapi.json \
  -g python \
  -o ./flyn-client

Authentication

• API key. Send Authorization: Bearer flyn_sk_live_.... Keys are created in Settings, API on the Pro, Lifetime or Team plan (members of a paying owner's team get Team access). See Authentication for creating and revoking keys.
• Dashboard session. Some routes also accept the signed-in session cookie of the Flyn dashboard, which is how the dashboard itself calls them. From a server or script, use an API key.
• MCP OAuth tokens. Access tokens issued to an MCP client through OAuth (Bearer flyn_mcp_at_...). Besides the MCP endpoint itself (/mcp), they are accepted by these operations in the spec: GET /api/links, POST /api/links, GET /api/links/{id}/clicks, GET /api/links/{id}/qr, POST /api/qr and POST /api/shorten. Every other operation in this spec that requires credentials answers 401 to them. Connecting an MCP client with OAuth works on every plan, see the MCP server page.
• No credentials. The conversion ingest routes take the click id as their credential, and quick shorten also works without an account. The operations table marks these as No auth and Auth optional.

The schemes as the spec declares them:

Errors and status codes are covered on Errors, and most per-route limits on Rate Limits; each operation's description in the spec states its own limit.

Operations

Every operation in the spec, grouped by tag. Each group links to the page that explains it in prose. Unmarked operations need credentials: an API key, or where accepted, an MCP OAuth token (the operations listed under Authentication) or a dashboard session.

Webhook events

The events below come from the spec's webhooks object. Each one is an HTTP POST Flyn sends to an endpoint you register. Signing, delivery headers and payload examples are on the Webhooks page.

SDK

Flyn's own client library is the TypeScript package flyn-sdk on npm. For any other language, generate a client from this spec with openapi-generator or a similar tool, as shown above.

npm install flyn-sdk