API
Links in documents
Record where QR codes and link annotations sit in a document, and read its scan-to-open QR code.
A placement records that a link sits on a page of a document. A qr placement is a QR code drawn on the page and carries a qr link; an annotation is a clickable region and carries a plain link. Its rect is in PDF user space, in points from the page's bottom-left corner. The editor writes the PDF objects itself and records them here; recording or removing a placement never changes the PDF.
Removing a placement leaves the link working, because printed copies may still carry it; archive the link to stop it. Publishing a document gives it a scan-to-open QR code. Unpublishing archives that code and publishing again restores it. Recording placements needs edit access to the document. When the plan includes QR tracking, each placement carries its link's visit count so far.
The links placed in a document, and its scan-to-open QR
GET /documents/{documentId}/links documentLinks.list
The document's placements, by page and then oldest first, each with its link and the link's recorded visits; and its scan-to-open QR code, which publishing the document makes, unpublishing archives and publishing again restores. Removed placements are left out. A document the caller cannot open answers 404 not_found.
- Scopes
documents.read,links.read- MCP tool
document_links_list
Path parameters
| Name | Type | Description |
|---|---|---|
documentId required | string | The document's id. An id starting doc_. |
Response
200 OK. A JSON object:
Response fields (37)
| Name | Type | Description |
|---|---|---|
placements | array of objects | The placements, by page, then oldest first. |
placements[].id | string | The placement's id. |
placements[].kind | string | qr for a QR code drawn on the page, which carries a qr link; annotation for a link annotation over a region, which carries a plain link. One of qr, annotation. |
placements[].page | number | The page it is on, 1-based. |
placements[].rect | object | Where it sits, in PDF user space: points, with the origin at the page's bottom-left corner. |
placements[].rect.x | number | Its left edge, in points from the origin. |
placements[].rect.y | number | Its bottom edge, in points from the origin. |
placements[].rect.width | number | Its width, in points. |
placements[].rect.height | number | Its height, in points. |
placements[].objectRef | string | The id of the PDF object that draws it, as recorded when it was placed; null when only a position was recorded. Can be null. |
placements[].createdAt | number | When it was placed, epoch milliseconds. |
placements[].link | object | The link it carries. |
placements[].link.id | string | The link's id. |
placements[].link.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. |
placements[].link.url | string | The short URL, https://{short host}/{code}: what the QR code encodes and what visitors open. |
placements[].link.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. |
placements[].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. |
placements[].link.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. |
placements[].link.label | string | The link's name, or the recipient's on a variant; empty when it has none. |
placements[].link.campaign | string | The campaign the link is grouped under; empty when it has none. |
placements[].link.designId | string | The saved QR design its code is drawn in; null draws it in the workspace's default design. Can be null. |
placements[].link.parentId | string | On a per-recipient variant, the id of the link it follows; null on a link of its own. Can be null. |
placements[].link.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. |
placements[].link.createdAt | number | When it was made, epoch milliseconds. |
placements[].link.updatedAt | number | When it, its rules or its status last changed, epoch milliseconds. |
placements[].link.archivedAt | number | When it was archived, epoch milliseconds; null while it is active. Can be null. |
placements[].link.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. |
placements[].link.utm | object | The UTM settings added to web destinations. A variant shows the default and uses its link's settings. |
placements[].link.utm.source | string | The utm_source value the link adds, or null for none. Can be null. |
placements[].link.utm.medium | string | The utm_medium value the link adds, or null for none. Can be null. |
placements[].link.utm.campaign | string | The utm_campaign value the link adds, or null for none. Can be null. |
placements[].link.utm.term | string | The utm_term value the link adds, or null for none. Can be null. |
placements[].link.utm.content | string | The utm_content value the link adds, or null for none. Can be null. |
placements[].link.utm.passthrough | boolean | Whether the visitor's own utm_* parameters on the short URL are carried to the destination. |
placements[].hits | number | Every recorded visit to the link's short URL so far, bots left out: scans for a QR code, clicks for a link. Null when the plan does not include QR tracking; a workspace that turned tracking off still sees what was recorded before. Can be null. |
openLink | object | The document's scan-to-open QR code, whose short URL opens the published document; null until it is first published. Can be null. The same fields as placements[].link. |
openLinkHits | number | Every recorded scan of the scan-to-open code, bots left out; null without that code or when the plan does not include QR tracking. Can be null. |
Example request
curl https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb/links \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" Example response
{
"placements": [
{
"id": "string",
"kind": "qr",
"page": 1,
"rect": {
"x": 1,
"y": 1,
"width": 1,
"height": 1
},
"objectRef": "string",
"createdAt": 1767225600000,
"link": {
"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
}
},
"hits": 1
}
],
"openLink": {
"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
}
},
"openLinkHits": 1
} Record a QR code or link annotation placed in a document
POST /documents/{documentId}/links documentLinks.place
Give link to make a new link for the object, or linkId to place an existing one, not both. A qr placement carries a QR link and an annotation a plain link: an existing link of the other kind answers 400 wrong_link_kind. Placing a QR code assigns it to the document.
An existing QR code can be placed by a caller with links.manage, by its maker with links.edit, or by any caller once it is assigned to the document; otherwise 403 forbidden. A page after the current version's last page answers 400 page_out_of_range. The call needs edit access to the document: 404 not_found when the caller cannot open it, 403 forbidden when they can only view it.
The editor writes the PDF objects themselves; this call only records where they are.
- Scopes
documents.edit,links.edit- Retries
- Safe with an
Idempotency-Key
Path parameters
| Name | Type | Description |
|---|---|---|
documentId required | string | The document's id. An id starting doc_. |
Request body
A JSON object, at most 64 KiB.
| Name | Type | Description |
|---|---|---|
kind required | string | qr for a QR code drawn on the page, which carries a qr link; annotation for a link annotation over a region, which carries a plain link. One of qr, annotation. |
page required | integer | The page it is on, 1-based. It must exist in the document's current version. 1 to 100,000. |
rect required | object | Where it sits, in PDF user space: points, with the origin at the page's bottom-left corner. |
rect.x required | number | Its left edge, in points from the origin. -14,400 to 14,400. |
rect.y required | number | Its bottom edge, in points from the origin. -14,400 to 14,400. |
rect.width required | number | Its width, in points. More than 0. At most 14,400. |
rect.height required | number | Its height, in points. More than 0. At most 14,400. |
objectRef | string | The id of the PDF object that draws it, so a later save can find it again: 1 to 100 letters, digits and _:.-; anything else answers 400 invalid. Null or omitted records a position only. At most 100 characters. Can be null. |
linkId | string | An existing link to place. Give this or link. An id starting lnk_. |
link | object | A new link to make for the object, of the kind the placement carries. Give this or linkId. |
link.destination required | string | Where the link sends people, checked and stored as POST /api/v1/links does: an https:// or http:// address, an email address or mailto: link, or a tel: number. Anything else answers 400 invalid. 1 to 2,000 characters. |
link.label | string | A name for the link. Control characters become spaces and the value is trimmed. At most 200 characters. |
link.campaign | string | A campaign name that groups links. At most 80 characters. |
link.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. |
Response
201 Created. A JSON object:
Response fields (34)
| Name | Type | Description |
|---|---|---|
id | string | The placement's id. |
kind | string | qr for a QR code drawn on the page, which carries a qr link; annotation for a link annotation over a region, which carries a plain link. One of qr, annotation. |
page | number | The page it is on, 1-based. |
rect | object | Where it sits, in PDF user space: points, with the origin at the page's bottom-left corner. |
rect.x | number | Its left edge, in points from the origin. |
rect.y | number | Its bottom edge, in points from the origin. |
rect.width | number | Its width, in points. |
rect.height | number | Its height, in points. |
objectRef | string | The id of the PDF object that draws it, as recorded when it was placed; null when only a position was recorded. Can be null. |
createdAt | number | When it was placed, epoch milliseconds. |
link | object | The link it carries. |
link.id | string | The link's id. |
link.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. |
link.url | string | The short URL, https://{short host}/{code}: what the QR code encodes and what visitors open. |
link.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. |
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. |
link.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. |
link.label | string | The link's name, or the recipient's on a variant; empty when it has none. |
link.campaign | string | The campaign the link is grouped under; empty when it has none. |
link.designId | string | The saved QR design its code is drawn in; null draws it in the workspace's default design. Can be null. |
link.parentId | string | On a per-recipient variant, the id of the link it follows; null on a link of its own. Can be null. |
link.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. |
link.createdAt | number | When it was made, epoch milliseconds. |
link.updatedAt | number | When it, its rules or its status last changed, epoch milliseconds. |
link.archivedAt | number | When it was archived, epoch milliseconds; null while it is active. Can be null. |
link.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. |
link.utm | object | The UTM settings added to web destinations. A variant shows the default and uses its link's settings. |
link.utm.source | string | The utm_source value the link adds, or null for none. Can be null. |
link.utm.medium | string | The utm_medium value the link adds, or null for none. Can be null. |
link.utm.campaign | string | The utm_campaign value the link adds, or null for none. Can be null. |
link.utm.term | string | The utm_term value the link adds, or null for none. Can be null. |
link.utm.content | string | The utm_content value the link adds, or null for none. Can be null. |
link.utm.passthrough | boolean | Whether the visitor's own utm_* parameters on the short URL are carried to the destination. |
hits | number | Every recorded visit to the link's short URL so far, bots left out: scans for a QR code, clicks for a link. Null when the plan does not include QR tracking; a workspace that turned tracking off still sees what was recorded before. Can be null. |
Example request
curl -X POST https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb/links \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"kind": "qr",
"page": 1,
"rect": {
"x": 72,
"y": 72,
"width": 96,
"height": 96
},
"linkId": "lnk_7m2kq9vx4c8d1r5t6wnb"
}' Example response
{
"id": "string",
"kind": "qr",
"page": 1,
"rect": {
"x": 1,
"y": 1,
"width": 1,
"height": 1
},
"objectRef": "string",
"createdAt": 1767225600000,
"link": {
"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
}
},
"hits": 1
} Record that a link's object was taken out of a document
DELETE /documents/{documentId}/links/{placementId} documentLinks.remove
The placement no longer lists; the PDF is not changed. The link keeps working, because printed copies may still carry it. Archive it to stop it. Needs edit access to the document. An unknown placement, or one already removed, answers 404 not_found.
- Scopes
documents.edit,links.edit- Retries
- Safe with an
Idempotency-Key - MCP tool
document_links_remove
Path parameters
| Name | Type | Description |
|---|---|---|
documentId required | string | The document's id. An id starting doc_. |
placementId required | string | The placement's id. An id starting lpl_. |
Response
200 OK. An empty JSON object, {}.
Example request
curl -X DELETE https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb/links/lpl_7m2kq9vx4c8d1r5t6wnb \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" Errors
Besides the errors any endpoint can answer, these endpoints answer:
| Status | Code | When |
|---|---|---|
| 400 | invalid | The objectRef or rect is not valid. |
| 400 | wrong_link_kind | The existing link given is not the kind the placement carries. |
| 400 | page_out_of_range | The page is after the current version's last page. |