API
Links
Make short links and QR codes, change where they send people, route them by rules, and make variants per recipient.
A link is a short URL, https://{short host}/{code}, that sends visitors to its destination: a web address, an email (mailto:) or a phone number (tel:). Its kind is qr for a QR code or link for a plain short link. Both work the same way, but visits to a QR code count as scans and visits to a link as clicks. The code never changes, so a destination can change after the code is printed, and each destination is kept in the link's history.
Routing rules send some visitors elsewhere, by device, operating system, country, language or a time window. The first rule that holds decides; when none does, the destination is served. UTM settings add utm_* parameters to web destinations. An archived link, or one past its expiresAt, answers HTTP 410 instead of sending visitors on.
A per-recipient variant is a link with its own code and visit count that follows its parent's destination, rules and UTM settings. Every member with links.read can read every link. Changing one needs links.manage, or links.edit on a link the member made. A CSV batch makes up to 100 links at once, and a batch of QR codes costs credits.
List links and QR codes, newest first
GET /links links.list
Newest first, by createdAt. Per-recipient variants are left out: read them with GET /api/v1/links/{linkId}/variants. Each filter left out matches everything. A page holds at most limit links (default 50); to read the next, pass nextCursor as cursor.
- Scopes
links.read- MCP tool
links_list
Query parameters
| Name | Type | Description |
|---|---|---|
campaign | string | Only links in this campaign, matched exactly after trimming. An empty value lists links with no campaign. At most 80 characters. |
status | string | Only active or only archived links. One of active, archived. |
kind | string | Only QR codes (qr) or only plain links (link). One of qr, link. |
cursor | string | nextCursor from the previous page, to read the next one. Matches ^\d{1,16}(\.[A-Za-z0-9_-]{1,64}){1,2}$. |
before | integer | The older way to page: only links made before this time, epoch milliseconds. It skips links that share the last one's createdAt, as a CSV batch's do; use cursor. Ignored when cursor is given. More than 0. |
limit | integer | Most links to return. Default 50. 1 to 200. |
Response
200 OK. A JSON object:
Response fields (24)
| Name | Type | Description |
|---|---|---|
links | array of objects | The links, newest first. |
links[].id | string | The link's id. |
links[].code | string | The short code, the last part of url: upper-case letters and digits without 0, O, 1 or I, usually 6 of them. It never changes. |
links[].url | string | The short URL, https://{short host}/{code}: what the QR code encodes and what visitors open. |
links[].kind | string | qr for a QR code, whose visits are counted as scans; link for a plain short link, whose visits are counted as clicks. One of qr, link. |
links[].status | string | active sends visitors on; archived answers with a "no longer active" page (HTTP 410) until it is restored. An expired link stays active: see expiresAt. One of active, archived. |
links[].destination | string | Where the link sends a visitor no routing rule matches, in canonical form. On a variant this is a copy taken when the variant was made; a variant always goes where its link goes now. |
links[].label | string | The link's name, or the recipient's on a variant; empty when it has none. |
links[].campaign | string | The campaign the link is grouped under; empty when it has none. |
links[].designId | string | The saved QR design its code is drawn in; null draws it in the workspace's default design. Can be null. |
links[].parentId | string | On a per-recipient variant, the id of the link it follows; null on a link of its own. Can be null. |
links[].createdBy | string | The id of the member who made it, or who made the API key that did; null when no member did, as for a document's scan-to-open QR code. Can be null. |
links[].createdAt | number | When it was made, epoch milliseconds. |
links[].updatedAt | number | When it, its rules or its status last changed, epoch milliseconds. |
links[].archivedAt | number | When it was archived, epoch milliseconds; null while it is active. Can be null. |
links[].expiresAt | number | When the short URL expires, epoch milliseconds: from then on a visit gets a "this link has expired" page (HTTP 410). Null when it never does. A variant also expires when its link does. Can be null. |
links[].utm | object | The UTM settings added to web destinations. A variant shows the default and uses its link's settings. |
links[].utm.source | string | The utm_source value the link adds, or null for none. Can be null. |
links[].utm.medium | string | The utm_medium value the link adds, or null for none. Can be null. |
links[].utm.campaign | string | The utm_campaign value the link adds, or null for none. Can be null. |
links[].utm.term | string | The utm_term value the link adds, or null for none. Can be null. |
links[].utm.content | string | The utm_content value the link adds, or null for none. Can be null. |
links[].utm.passthrough | boolean | Whether the visitor's own utm_* parameters on the short URL are carried to the destination. |
nextCursor | string | Pass as cursor to read the next page. Null at the end. A page can hold fewer than limit links, or none, and still have a nextCursor: it leaves out "Scan to open" codes for documents the caller cannot see. A full page may be followed by an empty one. Can be null. |
Example request
curl https://api.flipbird.io/api/v1/links \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" Example response
{
"links": [
{
"id": "string",
"code": "string",
"url": "https://example.com/privacy",
"kind": "qr",
"status": "active",
"destination": "https://example.com/spring",
"label": "Spring campaign",
"campaign": "spring-26",
"designId": "…",
"parentId": "…",
"createdBy": "string",
"createdAt": 1767225600000,
"updatedAt": 1767225600000,
"archivedAt": 1767225600000,
"expiresAt": 1767225600000,
"utm": {
"source": "string",
"medium": "string",
"campaign": "spring-26",
"term": "string",
"content": "string",
"passthrough": true
}
}
],
"nextCursor": "string"
} A link, with its routing rules
GET /links/{linkId} links.get
Every member with links.read can read every link in the workspace. An unknown link answers 404 not_found.
- Scopes
links.read- MCP tool
links_get
Path parameters
| Name | Type | Description |
|---|---|---|
linkId required | string | The link's id. An id starting lnk_. |
Response
200 OK. A JSON object:
Response fields (30)
| Name | Type | Description |
|---|---|---|
id | string | The link's id. |
code | string | The short code, the last part of url: upper-case letters and digits without 0, O, 1 or I, usually 6 of them. It never changes. |
url | string | The short URL, https://{short host}/{code}: what the QR code encodes and what visitors open. |
kind | string | qr for a QR code, whose visits are counted as scans; link for a plain short link, whose visits are counted as clicks. One of qr, link. |
status | string | active sends visitors on; archived answers with a "no longer active" page (HTTP 410) until it is restored. An expired link stays active: see expiresAt. One of active, archived. |
destination | string | Where the link sends a visitor no routing rule matches, in canonical form. On a variant this is a copy taken when the variant was made; a variant always goes where its link goes now. |
label | string | The link's name, or the recipient's on a variant; empty when it has none. |
campaign | string | The campaign the link is grouped under; empty when it has none. |
designId | string | The saved QR design its code is drawn in; null draws it in the workspace's default design. Can be null. |
parentId | string | On a per-recipient variant, the id of the link it follows; null on a link of its own. Can be null. |
createdBy | string | The id of the member who made it, or who made the API key that did; null when no member did, as for a document's scan-to-open QR code. Can be null. |
createdAt | number | When it was made, epoch milliseconds. |
updatedAt | number | When it, its rules or its status last changed, epoch milliseconds. |
archivedAt | number | When it was archived, epoch milliseconds; null while it is active. Can be null. |
expiresAt | number | When the short URL expires, epoch milliseconds: from then on a visit gets a "this link has expired" page (HTTP 410). Null when it never does. A variant also expires when its link does. Can be null. |
utm | object | The UTM settings added to web destinations. A variant shows the default and uses its link's settings. |
utm.source | string | The utm_source value the link adds, or null for none. Can be null. |
utm.medium | string | The utm_medium value the link adds, or null for none. Can be null. |
utm.campaign | string | The utm_campaign value the link adds, or null for none. Can be null. |
utm.term | string | The utm_term value the link adds, or null for none. Can be null. |
utm.content | string | The utm_content value the link adds, or null for none. Can be null. |
utm.passthrough | boolean | Whether the visitor's own utm_* parameters on the short URL are carried to the destination. |
rules | array of objects | The routing rules, in the order they are tried. Empty on a variant, which follows its link's rules. |
rules[].destination | string | Where a visitor this rule matches is sent, in canonical form. |
rules[].devices | array of strings | Device classes it matches, sorted. Empty matches any device. |
rules[].os | array of strings | Operating systems it matches, sorted. Empty matches any. |
rules[].countries | array of strings | Countries it matches, as upper-case ISO 3166-1 alpha-2 codes, sorted. Empty matches any. |
rules[].locales | array of strings | Languages it matches, normalised (en, en-AU) and sorted. Empty matches any. |
rules[].startsAt | number | When it starts to hold, epoch milliseconds, inclusive; null when the start is open. Can be null. |
rules[].endsAt | number | When it stops holding, epoch milliseconds, exclusive; null when the end is open. Can be null. |
Example request
curl https://api.flipbird.io/api/v1/links/lnk_7m2kq9vx4c8d1r5t6wnb \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" Example response
{
"id": "string",
"code": "string",
"url": "https://example.com/privacy",
"kind": "qr",
"status": "active",
"destination": "https://example.com/spring",
"label": "Spring campaign",
"campaign": "spring-26",
"designId": "…",
"parentId": "…",
"createdBy": "string",
"createdAt": 1767225600000,
"updatedAt": 1767225600000,
"archivedAt": 1767225600000,
"expiresAt": 1767225600000,
"utm": {
"source": "string",
"medium": "string",
"campaign": "spring-26",
"term": "string",
"content": "string",
"passthrough": true
},
"rules": [
{
"destination": "https://example.com/spring",
"devices": [
"string"
],
"os": [
"string"
],
"countries": [
"string"
],
"locales": [
"string"
],
"startsAt": 1767225600000,
"endsAt": 1767225600000
}
]
} Make a short link or QR code
POST /links links.create
Makes a link with a new short code, which never changes, and records its destination as the first entry of its history. The destination is an https:// or http:// address, an email address or mailto: link, or a tel: number. Addresses carrying a user name or password, addresses on the short-link host, and every other scheme are refused with 400 invalid.
expiresAt (epoch milliseconds, in the future) makes the short URL answer "this link has expired" (HTTP 410) from then on. utm adds utm_source, utm_medium, utm_campaign, utm_term and utm_content to a web destination that does not set them; the visitor's own utm_* parameters on the short URL are carried too, unless utm.passthrough is false.
A designId that is not one of the workspace's designs is refused with 400 invalid. Returns the link, with no routing rules yet.
- Scopes
links.edit- Retries
- Safe with an
Idempotency-Key - MCP tool
links_create
Request body
A JSON object, at most 64 KiB.
| Name | Type | Description |
|---|---|---|
kind required | string | qr for a QR code, whose visits are counted as scans; link for a plain short link, whose visits are counted as clicks. One of qr, link. |
destination required | string | Where the link sends people: an https:// or http:// address on a domain, an email address or mailto: link (at most 10 addresses, with an optional subject and body), or a tel: number. It is stored in a canonical form: a bare email address becomes a mailto: link, and a phone number keeps only its digits and a leading +. A web address with a user name or password, one on the short-link host, and any other scheme are refused with 400 invalid. 1 to 2,000 characters. |
label | string | A name for the link, shown in lists and as the title of its QR image. Control characters become spaces and the value is trimmed. At most 200 characters. |
campaign | string | A campaign name that groups links; GET /api/v1/links can filter on it. Control characters become spaces and the value is trimmed. At most 80 characters. |
designId | string | The saved QR design its code is drawn in. Null or omitted draws it in the workspace's default design. An id starting qrd_. Can be null. |
expiresAt | integer | When the short URL stops working, epoch milliseconds; it must be in the future. From then on a visit gets a "this link has expired" page (HTTP 410). Null or omitted never expires. More than 0. Can be null. |
utm | object | UTM parameters to add to web destinations (never to email or phone ones), and whether the visitor's own utm_* parameters are carried. The destination's own parameters always win. Null or omitted is the default: no values, passthrough on. Can be null. |
utm.source | string | The value of utm_source. It is added only where neither the destination nor, with passthrough, the visitor's own parameters set it already. Null, omitted or empty adds none. At most 200 characters. Can be null. |
utm.medium | string | The value of utm_medium. It is added only where neither the destination nor, with passthrough, the visitor's own parameters set it already. Null, omitted or empty adds none. At most 200 characters. Can be null. |
utm.campaign | string | The value of utm_campaign. It is added only where neither the destination nor, with passthrough, the visitor's own parameters set it already. Null, omitted or empty adds none. At most 200 characters. Can be null. |
utm.term | string | The value of utm_term. It is added only where neither the destination nor, with passthrough, the visitor's own parameters set it already. Null, omitted or empty adds none. At most 200 characters. Can be null. |
utm.content | string | The value of utm_content. It is added only where neither the destination nor, with passthrough, the visitor's own parameters set it already. Null, omitted or empty adds none. At most 200 characters. Can be null. |
utm.passthrough | boolean | Whether the visitor's own utm_* parameters on the short URL are carried to the destination: at most 10 of them, each value cut to 200 characters. Nothing else on the short URL's query is carried. Default true. |
Response
201 Created. A JSON object:
Response fields (30)
| Name | Type | Description |
|---|---|---|
id | string | The link's id. |
code | string | The short code, the last part of url: upper-case letters and digits without 0, O, 1 or I, usually 6 of them. It never changes. |
url | string | The short URL, https://{short host}/{code}: what the QR code encodes and what visitors open. |
kind | string | qr for a QR code, whose visits are counted as scans; link for a plain short link, whose visits are counted as clicks. One of qr, link. |
status | string | active sends visitors on; archived answers with a "no longer active" page (HTTP 410) until it is restored. An expired link stays active: see expiresAt. One of active, archived. |
destination | string | Where the link sends a visitor no routing rule matches, in canonical form. On a variant this is a copy taken when the variant was made; a variant always goes where its link goes now. |
label | string | The link's name, or the recipient's on a variant; empty when it has none. |
campaign | string | The campaign the link is grouped under; empty when it has none. |
designId | string | The saved QR design its code is drawn in; null draws it in the workspace's default design. Can be null. |
parentId | string | On a per-recipient variant, the id of the link it follows; null on a link of its own. Can be null. |
createdBy | string | The id of the member who made it, or who made the API key that did; null when no member did, as for a document's scan-to-open QR code. Can be null. |
createdAt | number | When it was made, epoch milliseconds. |
updatedAt | number | When it, its rules or its status last changed, epoch milliseconds. |
archivedAt | number | When it was archived, epoch milliseconds; null while it is active. Can be null. |
expiresAt | number | When the short URL expires, epoch milliseconds: from then on a visit gets a "this link has expired" page (HTTP 410). Null when it never does. A variant also expires when its link does. Can be null. |
utm | object | The UTM settings added to web destinations. A variant shows the default and uses its link's settings. |
utm.source | string | The utm_source value the link adds, or null for none. Can be null. |
utm.medium | string | The utm_medium value the link adds, or null for none. Can be null. |
utm.campaign | string | The utm_campaign value the link adds, or null for none. Can be null. |
utm.term | string | The utm_term value the link adds, or null for none. Can be null. |
utm.content | string | The utm_content value the link adds, or null for none. Can be null. |
utm.passthrough | boolean | Whether the visitor's own utm_* parameters on the short URL are carried to the destination. |
rules | array of objects | The routing rules, in the order they are tried. Empty on a variant, which follows its link's rules. |
rules[].destination | string | Where a visitor this rule matches is sent, in canonical form. |
rules[].devices | array of strings | Device classes it matches, sorted. Empty matches any device. |
rules[].os | array of strings | Operating systems it matches, sorted. Empty matches any. |
rules[].countries | array of strings | Countries it matches, as upper-case ISO 3166-1 alpha-2 codes, sorted. Empty matches any. |
rules[].locales | array of strings | Languages it matches, normalised (en, en-AU) and sorted. Empty matches any. |
rules[].startsAt | number | When it starts to hold, epoch milliseconds, inclusive; null when the start is open. Can be null. |
rules[].endsAt | number | When it stops holding, epoch milliseconds, exclusive; null when the end is open. Can be null. |
Example request
curl -X POST https://api.flipbird.io/api/v1/links \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"kind": "qr",
"destination": "https://example.com/spring"
}' Example response
{
"id": "string",
"code": "string",
"url": "https://example.com/privacy",
"kind": "qr",
"status": "active",
"destination": "https://example.com/spring",
"label": "Spring campaign",
"campaign": "spring-26",
"designId": "…",
"parentId": "…",
"createdBy": "string",
"createdAt": 1767225600000,
"updatedAt": 1767225600000,
"archivedAt": 1767225600000,
"expiresAt": 1767225600000,
"utm": {
"source": "string",
"medium": "string",
"campaign": "spring-26",
"term": "string",
"content": "string",
"passthrough": true
},
"rules": [
{
"destination": "https://example.com/spring",
"devices": [
"string"
],
"os": [
"string"
],
"countries": [
"string"
],
"locales": [
"string"
],
"startsAt": 1767225600000,
"endsAt": 1767225600000
}
]
} Change where a link sends people, or its label or campaign
PATCH /links/{linkId} links.update
Changes only the fields given. The code and its printed QR stay the same. Each new destination is kept in the link's history (GET /api/v1/links/{linkId}/targets). expiresAt null removes the expiry; utm null restores the default.
A variant takes its own label, campaign, designId and expiresAt, but it goes where its link goes and follows its link's utm: a destination or utm for a variant is refused with 400 invalid. Changing a link needs links.manage, or links.edit on a link the caller made (with an API key, one made by the member who made the key); otherwise 403 forbidden.
A document's scan-to-open QR code also needs edit access to that document. An unknown link answers 404 not_found.
- Scopes
links.edit- Retries
- Safe with an
Idempotency-Key - MCP tool
links_update
Path parameters
| Name | Type | Description |
|---|---|---|
linkId required | string | The link's id. An id starting lnk_. |
Request body
A JSON object, at most 64 KiB.
| Name | Type | Description |
|---|---|---|
destination | string | Where the link sends people: an https:// or http:// address on a domain, an email address or mailto: link (at most 10 addresses, with an optional subject and body), or a tel: number. It is stored in a canonical form: a bare email address becomes a mailto: link, and a phone number keeps only its digits and a leading +. A web address with a user name or password, one on the short-link host, and any other scheme are refused with 400 invalid. Omitted leaves it unchanged. 1 to 2,000 characters. |
label | string | A new name for the link; empty clears it. Control characters become spaces and the value is trimmed. At most 200 characters. |
campaign | string | A new campaign name; empty clears it. Control characters become spaces and the value is trimmed. At most 80 characters. |
designId | string | The saved QR design its code is drawn in; null switches it back to the workspace's default design. A design that is not one of the workspace's is refused with 400 invalid. An id starting qrd_. Can be null. |
expiresAt | integer | A new expiry, epoch milliseconds, in the future; the current value may be sent again even after it has passed. Null removes the expiry. More than 0. Can be null. |
utm | object | New UTM settings, replacing the old ones whole: a value left out is cleared. Null restores the default (no values, passthrough on). Omitted leaves them unchanged. Can be null. |
utm.source | string | The value of utm_source. It is added only where neither the destination nor, with passthrough, the visitor's own parameters set it already. Null, omitted or empty adds none. At most 200 characters. Can be null. |
utm.medium | string | The value of utm_medium. It is added only where neither the destination nor, with passthrough, the visitor's own parameters set it already. Null, omitted or empty adds none. At most 200 characters. Can be null. |
utm.campaign | string | The value of utm_campaign. It is added only where neither the destination nor, with passthrough, the visitor's own parameters set it already. Null, omitted or empty adds none. At most 200 characters. Can be null. |
utm.term | string | The value of utm_term. It is added only where neither the destination nor, with passthrough, the visitor's own parameters set it already. Null, omitted or empty adds none. At most 200 characters. Can be null. |
utm.content | string | The value of utm_content. It is added only where neither the destination nor, with passthrough, the visitor's own parameters set it already. Null, omitted or empty adds none. At most 200 characters. Can be null. |
utm.passthrough | boolean | Whether the visitor's own utm_* parameters on the short URL are carried to the destination: at most 10 of them, each value cut to 200 characters. Nothing else on the short URL's query is carried. Default true. |
Response
200 OK. A JSON object:
Response fields (30)
| Name | Type | Description |
|---|---|---|
id | string | The link's id. |
code | string | The short code, the last part of url: upper-case letters and digits without 0, O, 1 or I, usually 6 of them. It never changes. |
url | string | The short URL, https://{short host}/{code}: what the QR code encodes and what visitors open. |
kind | string | qr for a QR code, whose visits are counted as scans; link for a plain short link, whose visits are counted as clicks. One of qr, link. |
status | string | active sends visitors on; archived answers with a "no longer active" page (HTTP 410) until it is restored. An expired link stays active: see expiresAt. One of active, archived. |
destination | string | Where the link sends a visitor no routing rule matches, in canonical form. On a variant this is a copy taken when the variant was made; a variant always goes where its link goes now. |
label | string | The link's name, or the recipient's on a variant; empty when it has none. |
campaign | string | The campaign the link is grouped under; empty when it has none. |
designId | string | The saved QR design its code is drawn in; null draws it in the workspace's default design. Can be null. |
parentId | string | On a per-recipient variant, the id of the link it follows; null on a link of its own. Can be null. |
createdBy | string | The id of the member who made it, or who made the API key that did; null when no member did, as for a document's scan-to-open QR code. Can be null. |
createdAt | number | When it was made, epoch milliseconds. |
updatedAt | number | When it, its rules or its status last changed, epoch milliseconds. |
archivedAt | number | When it was archived, epoch milliseconds; null while it is active. Can be null. |
expiresAt | number | When the short URL expires, epoch milliseconds: from then on a visit gets a "this link has expired" page (HTTP 410). Null when it never does. A variant also expires when its link does. Can be null. |
utm | object | The UTM settings added to web destinations. A variant shows the default and uses its link's settings. |
utm.source | string | The utm_source value the link adds, or null for none. Can be null. |
utm.medium | string | The utm_medium value the link adds, or null for none. Can be null. |
utm.campaign | string | The utm_campaign value the link adds, or null for none. Can be null. |
utm.term | string | The utm_term value the link adds, or null for none. Can be null. |
utm.content | string | The utm_content value the link adds, or null for none. Can be null. |
utm.passthrough | boolean | Whether the visitor's own utm_* parameters on the short URL are carried to the destination. |
rules | array of objects | The routing rules, in the order they are tried. Empty on a variant, which follows its link's rules. |
rules[].destination | string | Where a visitor this rule matches is sent, in canonical form. |
rules[].devices | array of strings | Device classes it matches, sorted. Empty matches any device. |
rules[].os | array of strings | Operating systems it matches, sorted. Empty matches any. |
rules[].countries | array of strings | Countries it matches, as upper-case ISO 3166-1 alpha-2 codes, sorted. Empty matches any. |
rules[].locales | array of strings | Languages it matches, normalised (en, en-AU) and sorted. Empty matches any. |
rules[].startsAt | number | When it starts to hold, epoch milliseconds, inclusive; null when the start is open. Can be null. |
rules[].endsAt | number | When it stops holding, epoch milliseconds, exclusive; null when the end is open. Can be null. |
Example request
curl -X PATCH https://api.flipbird.io/api/v1/links/lnk_7m2kq9vx4c8d1r5t6wnb \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"destination": "https://example.com/spring",
"label": "Spring campaign"
}' Example response
{
"id": "string",
"code": "string",
"url": "https://example.com/privacy",
"kind": "qr",
"status": "active",
"destination": "https://example.com/spring",
"label": "Spring campaign",
"campaign": "spring-26",
"designId": "…",
"parentId": "…",
"createdBy": "string",
"createdAt": 1767225600000,
"updatedAt": 1767225600000,
"archivedAt": 1767225600000,
"expiresAt": 1767225600000,
"utm": {
"source": "string",
"medium": "string",
"campaign": "spring-26",
"term": "string",
"content": "string",
"passthrough": true
},
"rules": [
{
"destination": "https://example.com/spring",
"devices": [
"string"
],
"os": [
"string"
],
"countries": [
"string"
],
"locales": [
"string"
],
"startsAt": 1767225600000,
"endsAt": 1767225600000
}
]
} Archive a link, or restore it
PUT /links/{linkId}/status links.setStatus
An archived link shows a "no longer active" page (HTTP 410) until it is restored. Archiving a link stops every variant of it too; archiving a variant stops only that variant. Setting the status a link already has changes nothing. Returns the link. Changing a link needs links.manage, or links.edit on a link the caller made (with an API key, one made by the member who made the key); otherwise 403 forbidden.
A document's scan-to-open QR code also needs edit access to that document. An unknown link answers 404 not_found.
- Scopes
links.edit- Retries
- Safe with an
Idempotency-Key - MCP tool
links_set_status
Path parameters
| Name | Type | Description |
|---|---|---|
linkId required | string | The link's id. An id starting lnk_. |
Request body
A JSON object, at most 64 KiB.
| Name | Type | Description |
|---|---|---|
status required | string | archived stops the short URL; active restores it. One of active, archived. |
Response
200 OK. A JSON object:
Response fields (30)
| Name | Type | Description |
|---|---|---|
id | string | The link's id. |
code | string | The short code, the last part of url: upper-case letters and digits without 0, O, 1 or I, usually 6 of them. It never changes. |
url | string | The short URL, https://{short host}/{code}: what the QR code encodes and what visitors open. |
kind | string | qr for a QR code, whose visits are counted as scans; link for a plain short link, whose visits are counted as clicks. One of qr, link. |
status | string | active sends visitors on; archived answers with a "no longer active" page (HTTP 410) until it is restored. An expired link stays active: see expiresAt. One of active, archived. |
destination | string | Where the link sends a visitor no routing rule matches, in canonical form. On a variant this is a copy taken when the variant was made; a variant always goes where its link goes now. |
label | string | The link's name, or the recipient's on a variant; empty when it has none. |
campaign | string | The campaign the link is grouped under; empty when it has none. |
designId | string | The saved QR design its code is drawn in; null draws it in the workspace's default design. Can be null. |
parentId | string | On a per-recipient variant, the id of the link it follows; null on a link of its own. Can be null. |
createdBy | string | The id of the member who made it, or who made the API key that did; null when no member did, as for a document's scan-to-open QR code. Can be null. |
createdAt | number | When it was made, epoch milliseconds. |
updatedAt | number | When it, its rules or its status last changed, epoch milliseconds. |
archivedAt | number | When it was archived, epoch milliseconds; null while it is active. Can be null. |
expiresAt | number | When the short URL expires, epoch milliseconds: from then on a visit gets a "this link has expired" page (HTTP 410). Null when it never does. A variant also expires when its link does. Can be null. |
utm | object | The UTM settings added to web destinations. A variant shows the default and uses its link's settings. |
utm.source | string | The utm_source value the link adds, or null for none. Can be null. |
utm.medium | string | The utm_medium value the link adds, or null for none. Can be null. |
utm.campaign | string | The utm_campaign value the link adds, or null for none. Can be null. |
utm.term | string | The utm_term value the link adds, or null for none. Can be null. |
utm.content | string | The utm_content value the link adds, or null for none. Can be null. |
utm.passthrough | boolean | Whether the visitor's own utm_* parameters on the short URL are carried to the destination. |
rules | array of objects | The routing rules, in the order they are tried. Empty on a variant, which follows its link's rules. |
rules[].destination | string | Where a visitor this rule matches is sent, in canonical form. |
rules[].devices | array of strings | Device classes it matches, sorted. Empty matches any device. |
rules[].os | array of strings | Operating systems it matches, sorted. Empty matches any. |
rules[].countries | array of strings | Countries it matches, as upper-case ISO 3166-1 alpha-2 codes, sorted. Empty matches any. |
rules[].locales | array of strings | Languages it matches, normalised (en, en-AU) and sorted. Empty matches any. |
rules[].startsAt | number | When it starts to hold, epoch milliseconds, inclusive; null when the start is open. Can be null. |
rules[].endsAt | number | When it stops holding, epoch milliseconds, exclusive; null when the end is open. Can be null. |
Example request
curl -X PUT https://api.flipbird.io/api/v1/links/lnk_7m2kq9vx4c8d1r5t6wnb/status \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"status": "active"
}' Example response
{
"id": "string",
"code": "string",
"url": "https://example.com/privacy",
"kind": "qr",
"status": "active",
"destination": "https://example.com/spring",
"label": "Spring campaign",
"campaign": "spring-26",
"designId": "…",
"parentId": "…",
"createdBy": "string",
"createdAt": 1767225600000,
"updatedAt": 1767225600000,
"archivedAt": 1767225600000,
"expiresAt": 1767225600000,
"utm": {
"source": "string",
"medium": "string",
"campaign": "spring-26",
"term": "string",
"content": "string",
"passthrough": true
},
"rules": [
{
"destination": "https://example.com/spring",
"devices": [
"string"
],
"os": [
"string"
],
"countries": [
"string"
],
"locales": [
"string"
],
"startsAt": 1767225600000,
"endsAt": 1767225600000
}
]
} Every destination a link has had, newest first
GET /links/{linkId}/targets links.targets
Starts with the destination the link was made with; a change that sets the same destination again adds nothing. Routing rule destinations are not included, and a variant has no history of its own. An unknown link answers 404 not_found.
- Scopes
links.read- MCP tool
links_targets
Path parameters
| Name | Type | Description |
|---|---|---|
linkId required | string | The link's id. An id starting lnk_. |
Response
200 OK. A JSON object:
Response fields (4)
| Name | Type | Description |
|---|---|---|
targets | array of objects | The destinations, newest first: the first is the current one. |
targets[].destination | string | A destination the link had, in canonical form. |
targets[].changedBy | string | The id of the member who set it; null when no member did. Can be null. |
targets[].changedAt | number | When it was set, epoch milliseconds. |
Example request
curl https://api.flipbird.io/api/v1/links/lnk_7m2kq9vx4c8d1r5t6wnb/targets \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" Example response
{
"targets": [
{
"destination": "https://example.com/spring",
"changedBy": "string",
"changedAt": 1767225600000
}
]
} Replace a link's routing rules
PUT /links/{linkId}/rules links.setRules
Replaces every rule. Rules are tried in order and the first whose every condition holds decides where the visitor goes; when none holds, the link's destination is served. Conditions: devices (mobile, tablet, desktop), os, countries (ISO 3166-1 alpha-2), locales (a language such as en, or en-AU) and a startsAt/endsAt window in epoch milliseconds.
Within one condition any listed value matches, and a condition left empty matches everything; a condition on something the visit does not reveal, such as an unknown country, does not hold. A rule with no condition, one that ends before it starts, or a value a condition cannot match is refused with 400 invalid, and so is any rule for a variant, which follows its link's rules.
Variants of the link follow the new rules at once. Returns the rules as stored: values normalised, de-duplicated and sorted. Changing a link needs links.manage, or links.edit on a link the caller made (with an API key, one made by the member who made the key); otherwise 403 forbidden. A document's scan-to-open QR code also needs edit access to that document. An unknown link answers 404 not_found.
- Scopes
links.edit- Retries
- Safe with an
Idempotency-Key - MCP tool
links_set_rules
Path parameters
| Name | Type | Description |
|---|---|---|
linkId required | string | The link's id. An id starting lnk_. |
Request body
A JSON object, at most 64 KiB.
| Name | Type | Description |
|---|---|---|
rules required | array of objects | The new rules, in the order they are tried. An empty list removes every rule. At most 20 items. |
rules[].destination required | string | Where a visitor this rule matches is sent. Checked and stored like the link's own destination. 1 to 2,000 characters. |
rules[].devices | array of strings | Device classes the rule matches, read from the visitor's user agent. Omitted or empty matches any device. At most 50 items. |
rules[].os | array of strings | Operating systems the rule matches, read from the visitor's user agent; Chrome OS counts as linux. Omitted or empty matches any. At most 50 items. |
rules[].countries | array of strings | Countries the rule matches, as ISO 3166-1 alpha-2 codes in either case, where the visit comes from as Cloudflare sees it. Omitted or empty matches any. At most 50 items. |
rules[].locales | array of strings | Languages the rule matches against the visitor's most preferred language (Accept-Language). A language such as en matches every region of it; a tag with a region such as en-AU matches only that region. Omitted or empty matches any. At most 50 items. |
rules[].startsAt | integer | When the rule starts to hold, epoch milliseconds, inclusive. Null or omitted leaves the start open. At least 0. Can be null. |
rules[].endsAt | integer | When the rule stops holding, epoch milliseconds, exclusive. It must be after startsAt. Null or omitted leaves the end open. At least 0. Can be null. |
Response
200 OK. A JSON object:
Response fields (8)
| Name | Type | Description |
|---|---|---|
rules | array of objects | The rules as stored, in the order they are tried. |
rules[].destination | string | Where a visitor this rule matches is sent, in canonical form. |
rules[].devices | array of strings | Device classes it matches, sorted. Empty matches any device. |
rules[].os | array of strings | Operating systems it matches, sorted. Empty matches any. |
rules[].countries | array of strings | Countries it matches, as upper-case ISO 3166-1 alpha-2 codes, sorted. Empty matches any. |
rules[].locales | array of strings | Languages it matches, normalised (en, en-AU) and sorted. Empty matches any. |
rules[].startsAt | number | When it starts to hold, epoch milliseconds, inclusive; null when the start is open. Can be null. |
rules[].endsAt | number | When it stops holding, epoch milliseconds, exclusive; null when the end is open. Can be null. |
Example request
curl -X PUT https://api.flipbird.io/api/v1/links/lnk_7m2kq9vx4c8d1r5t6wnb/rules \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"rules": [
{
"destination": "https://example.com/spring"
}
]
}' Example response
{
"rules": [
{
"destination": "https://example.com/spring",
"devices": [
"string"
],
"os": [
"string"
],
"countries": [
"string"
],
"locales": [
"string"
],
"startsAt": 1767225600000,
"endsAt": 1767225600000
}
]
} Make links or QR codes from CSV
POST /links/batch links.batch
A header row, then 1 to 100 rows. Columns, named in the header in any order and either case: destination (required), label and campaign, each at most once; any other column is refused. The CSV is RFC 4180: comma-separated, a field optionally in double quotes with "" for a quote inside it, CRLF or LF line ends; a leading byte-order mark and blank lines are skipped.
A malformed CSV, a bad header, no rows or too many answer 400 invalid_csv. Every row is checked first; if any is refused (a row whose number of fields differs from the header's, or a destination, label or campaign a single link would be refused), none is made, and the 400 invalid_request lists each problem in details.issues, its path body.csv.rowN counting the header as row 1.
kind and designId apply to every link, and campaign to every row whose own campaign cell is empty; a designId that is not one of the workspace's designs is refused with 400 invalid. A batch of QR codes costs 5 credits per 100 codes or part of 100; a batch of plain links costs nothing. A workspace whose credits are throttled is refused a batch of QR codes with 402 credits_required, not one of links.
- Scopes
links.edit- Credits
- Some requests spend credits, as the description says: 5 credits per 100 QR codes, or part of 100.
- Retries
- Safe with an
Idempotency-Key - MCP tool
links_batch_create
Request body
A JSON object, at most 64 KiB.
| Name | Type | Description |
|---|---|---|
kind required | string | qr for a QR code, whose visits are counted as scans; link for a plain short link, whose visits are counted as clicks. Every link in the batch is of this kind. One of qr, link. |
csv required | string | The CSV text: a header row naming the columns (destination, and optionally label and campaign), then one row per link. 1 to 60,000 characters. |
campaign | string | The campaign of every row whose campaign cell is empty or missing. At most 80 characters. |
designId | string | The saved QR design every link is drawn in. Omitted draws them in the workspace's default design. An id starting qrd_. |
Response
201 Created. A JSON object:
Response fields (23)
| Name | Type | Description |
|---|---|---|
links | array of objects | The links made, in the CSV's row order. |
links[].id | string | The link's id. |
links[].code | string | The short code, the last part of url: upper-case letters and digits without 0, O, 1 or I, usually 6 of them. It never changes. |
links[].url | string | The short URL, https://{short host}/{code}: what the QR code encodes and what visitors open. |
links[].kind | string | qr for a QR code, whose visits are counted as scans; link for a plain short link, whose visits are counted as clicks. One of qr, link. |
links[].status | string | active sends visitors on; archived answers with a "no longer active" page (HTTP 410) until it is restored. An expired link stays active: see expiresAt. One of active, archived. |
links[].destination | string | Where the link sends a visitor no routing rule matches, in canonical form. On a variant this is a copy taken when the variant was made; a variant always goes where its link goes now. |
links[].label | string | The link's name, or the recipient's on a variant; empty when it has none. |
links[].campaign | string | The campaign the link is grouped under; empty when it has none. |
links[].designId | string | The saved QR design its code is drawn in; null draws it in the workspace's default design. Can be null. |
links[].parentId | string | On a per-recipient variant, the id of the link it follows; null on a link of its own. Can be null. |
links[].createdBy | string | The id of the member who made it, or who made the API key that did; null when no member did, as for a document's scan-to-open QR code. Can be null. |
links[].createdAt | number | When it was made, epoch milliseconds. |
links[].updatedAt | number | When it, its rules or its status last changed, epoch milliseconds. |
links[].archivedAt | number | When it was archived, epoch milliseconds; null while it is active. Can be null. |
links[].expiresAt | number | When the short URL expires, epoch milliseconds: from then on a visit gets a "this link has expired" page (HTTP 410). Null when it never does. A variant also expires when its link does. Can be null. |
links[].utm | object | The UTM settings added to web destinations. A variant shows the default and uses its link's settings. |
links[].utm.source | string | The utm_source value the link adds, or null for none. Can be null. |
links[].utm.medium | string | The utm_medium value the link adds, or null for none. Can be null. |
links[].utm.campaign | string | The utm_campaign value the link adds, or null for none. Can be null. |
links[].utm.term | string | The utm_term value the link adds, or null for none. Can be null. |
links[].utm.content | string | The utm_content value the link adds, or null for none. Can be null. |
links[].utm.passthrough | boolean | Whether the visitor's own utm_* parameters on the short URL are carried to the destination. |
Example request
curl -X POST https://api.flipbird.io/api/v1/links/batch \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"kind": "qr",
"csv": "string"
}' Example response
{
"links": [
{
"id": "string",
"code": "string",
"url": "https://example.com/privacy",
"kind": "qr",
"status": "active",
"destination": "https://example.com/spring",
"label": "Spring campaign",
"campaign": "spring-26",
"designId": "…",
"parentId": "…",
"createdBy": "string",
"createdAt": 1767225600000,
"updatedAt": 1767225600000,
"archivedAt": 1767225600000,
"expiresAt": 1767225600000,
"utm": {
"source": "string",
"medium": "string",
"campaign": "spring-26",
"term": "string",
"content": "string",
"passthrough": true
}
}
]
} Make one tracked variant of a link per recipient
POST /links/{linkId}/variants links.createVariants
Up to 100 labels per call, each different from the others in the call. Every variant has its own code and counts its own visits, and goes wherever the link goes, by the link's rules and UTM settings; it copies the link's kind, campaign and design when it is made. Archiving the link stops every variant; archiving a variant stops only it. A variant expires when it or its link does.
A variant cannot have variants of its own: asking for them, or giving the same label twice, is refused with 400 invalid. The variants are made together or not at all. Changing a link needs links.manage, or links.edit on a link the caller made (with an API key, one made by the member who made the key); otherwise 403 forbidden. A document's scan-to-open QR code also needs edit access to that document.
An unknown link answers 404 not_found.
- Scopes
links.edit- Retries
- Safe with an
Idempotency-Key - MCP tool
links_create_variants
Path parameters
| Name | Type | Description |
|---|---|---|
linkId required | string | The link's id. An id starting lnk_. |
Request body
A JSON object, at most 64 KiB.
| Name | Type | Description |
|---|---|---|
labels required | array of strings | One label per variant, such as the recipient's name. Control characters become spaces and each label is trimmed. 1 to 100 items. |
Response
201 Created. A JSON object:
Response fields (23)
| Name | Type | Description |
|---|---|---|
variants | array of objects | The variants made, in the order of labels. |
variants[].id | string | The link's id. |
variants[].code | string | The short code, the last part of url: upper-case letters and digits without 0, O, 1 or I, usually 6 of them. It never changes. |
variants[].url | string | The short URL, https://{short host}/{code}: what the QR code encodes and what visitors open. |
variants[].kind | string | qr for a QR code, whose visits are counted as scans; link for a plain short link, whose visits are counted as clicks. One of qr, link. |
variants[].status | string | active sends visitors on; archived answers with a "no longer active" page (HTTP 410) until it is restored. An expired link stays active: see expiresAt. One of active, archived. |
variants[].destination | string | Where the link sends a visitor no routing rule matches, in canonical form. On a variant this is a copy taken when the variant was made; a variant always goes where its link goes now. |
variants[].label | string | The link's name, or the recipient's on a variant; empty when it has none. |
variants[].campaign | string | The campaign the link is grouped under; empty when it has none. |
variants[].designId | string | The saved QR design its code is drawn in; null draws it in the workspace's default design. Can be null. |
variants[].parentId | string | On a per-recipient variant, the id of the link it follows; null on a link of its own. Can be null. |
variants[].createdBy | string | The id of the member who made it, or who made the API key that did; null when no member did, as for a document's scan-to-open QR code. Can be null. |
variants[].createdAt | number | When it was made, epoch milliseconds. |
variants[].updatedAt | number | When it, its rules or its status last changed, epoch milliseconds. |
variants[].archivedAt | number | When it was archived, epoch milliseconds; null while it is active. Can be null. |
variants[].expiresAt | number | When the short URL expires, epoch milliseconds: from then on a visit gets a "this link has expired" page (HTTP 410). Null when it never does. A variant also expires when its link does. Can be null. |
variants[].utm | object | The UTM settings added to web destinations. A variant shows the default and uses its link's settings. |
variants[].utm.source | string | The utm_source value the link adds, or null for none. Can be null. |
variants[].utm.medium | string | The utm_medium value the link adds, or null for none. Can be null. |
variants[].utm.campaign | string | The utm_campaign value the link adds, or null for none. Can be null. |
variants[].utm.term | string | The utm_term value the link adds, or null for none. Can be null. |
variants[].utm.content | string | The utm_content value the link adds, or null for none. Can be null. |
variants[].utm.passthrough | boolean | Whether the visitor's own utm_* parameters on the short URL are carried to the destination. |
Example request
curl -X POST https://api.flipbird.io/api/v1/links/lnk_7m2kq9vx4c8d1r5t6wnb/variants \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"labels": [
"string"
]
}' Example response
{
"variants": [
{
"id": "string",
"code": "string",
"url": "https://example.com/privacy",
"kind": "qr",
"status": "active",
"destination": "https://example.com/spring",
"label": "Spring campaign",
"campaign": "spring-26",
"designId": "…",
"parentId": "…",
"createdBy": "string",
"createdAt": 1767225600000,
"updatedAt": 1767225600000,
"archivedAt": 1767225600000,
"expiresAt": 1767225600000,
"utm": {
"source": "string",
"medium": "string",
"campaign": "spring-26",
"term": "string",
"content": "string",
"passthrough": true
}
}
]
} A link's per-recipient variants, oldest first
GET /links/{linkId}/variants links.listVariants
Every variant, archived ones included. A link without variants has an empty list. An unknown link answers 404 not_found.
- Scopes
links.read- MCP tool
links_list_variants
Path parameters
| Name | Type | Description |
|---|---|---|
linkId required | string | The link's id. An id starting lnk_. |
Response
200 OK. A JSON object:
Response fields (23)
| Name | Type | Description |
|---|---|---|
variants | array of objects | The variants, oldest first. |
variants[].id | string | The link's id. |
variants[].code | string | The short code, the last part of url: upper-case letters and digits without 0, O, 1 or I, usually 6 of them. It never changes. |
variants[].url | string | The short URL, https://{short host}/{code}: what the QR code encodes and what visitors open. |
variants[].kind | string | qr for a QR code, whose visits are counted as scans; link for a plain short link, whose visits are counted as clicks. One of qr, link. |
variants[].status | string | active sends visitors on; archived answers with a "no longer active" page (HTTP 410) until it is restored. An expired link stays active: see expiresAt. One of active, archived. |
variants[].destination | string | Where the link sends a visitor no routing rule matches, in canonical form. On a variant this is a copy taken when the variant was made; a variant always goes where its link goes now. |
variants[].label | string | The link's name, or the recipient's on a variant; empty when it has none. |
variants[].campaign | string | The campaign the link is grouped under; empty when it has none. |
variants[].designId | string | The saved QR design its code is drawn in; null draws it in the workspace's default design. Can be null. |
variants[].parentId | string | On a per-recipient variant, the id of the link it follows; null on a link of its own. Can be null. |
variants[].createdBy | string | The id of the member who made it, or who made the API key that did; null when no member did, as for a document's scan-to-open QR code. Can be null. |
variants[].createdAt | number | When it was made, epoch milliseconds. |
variants[].updatedAt | number | When it, its rules or its status last changed, epoch milliseconds. |
variants[].archivedAt | number | When it was archived, epoch milliseconds; null while it is active. Can be null. |
variants[].expiresAt | number | When the short URL expires, epoch milliseconds: from then on a visit gets a "this link has expired" page (HTTP 410). Null when it never does. A variant also expires when its link does. Can be null. |
variants[].utm | object | The UTM settings added to web destinations. A variant shows the default and uses its link's settings. |
variants[].utm.source | string | The utm_source value the link adds, or null for none. Can be null. |
variants[].utm.medium | string | The utm_medium value the link adds, or null for none. Can be null. |
variants[].utm.campaign | string | The utm_campaign value the link adds, or null for none. Can be null. |
variants[].utm.term | string | The utm_term value the link adds, or null for none. Can be null. |
variants[].utm.content | string | The utm_content value the link adds, or null for none. Can be null. |
variants[].utm.passthrough | boolean | Whether the visitor's own utm_* parameters on the short URL are carried to the destination. |
Example request
curl https://api.flipbird.io/api/v1/links/lnk_7m2kq9vx4c8d1r5t6wnb/variants \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" Example response
{
"variants": [
{
"id": "string",
"code": "string",
"url": "https://example.com/privacy",
"kind": "qr",
"status": "active",
"destination": "https://example.com/spring",
"label": "Spring campaign",
"campaign": "spring-26",
"designId": "…",
"parentId": "…",
"createdBy": "string",
"createdAt": 1767225600000,
"updatedAt": 1767225600000,
"archivedAt": 1767225600000,
"expiresAt": 1767225600000,
"utm": {
"source": "string",
"medium": "string",
"campaign": "spring-26",
"term": "string",
"content": "string",
"passthrough": true
}
}
]
} A link's variants as CSV: label, code, short URL, status, created
GET /links/{linkId}/variants/export links.exportVariants
A CSV file (text/csv, UTF-8, CRLF line ends) named variants-{code}.csv, the oldest variant first, after a header row with the columns label, code, url (the short URL), status (active or archived) and created (ISO 8601, UTC). Cells a spreadsheet would run as a formula (starting with =, +, -, @, a tab or a carriage return) are prefixed with an apostrophe.
An unknown link answers 404 not_found.
- Scopes
links.read
Path parameters
| Name | Type | Description |
|---|---|---|
linkId required | string | The link's id. An id starting lnk_. |
Response
200 OK. The file itself, with its own Content-Type. A refusal is a JSON error, as everywhere else.
Example request
curl https://api.flipbird.io/api/v1/links/lnk_7m2kq9vx4c8d1r5t6wnb/variants/export \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-OJ Errors
Besides the errors any endpoint can answer, these endpoints answer:
| Status | Code | When |
|---|---|---|
| 400 | invalid | A value the link cannot take: a bad destination, a label or campaign too long, an expiry not in the future, a design that is not the workspace's, a rule with no condition or one that ends before it starts, or a variant given its own destination, rules or a duplicate label. |
| 400 | invalid_csv | The CSV is malformed, its header is wrong, or it has no rows or more than 100. |
| 400 | bad_cursor | The cursor was not given by this list. |