API
QR codes
Draw a link's QR code as SVG or PNG, save named QR designs, and choose the documents a QR code may be placed on.
Every link has a QR code that encodes its short URL. A design sets its colours, gradient, module and eye shapes, quiet zone, error correction, centre logo, background picture and call-to-action frame. A code is drawn in the design asked for, else the link's designId, else the workspace's default design, else the built-in black-on-white design. Changing or deleting a design changes how codes look, never what they encode, so printed codes keep working.
The SVG draws every design at any size. A PNG (64 to 2048 pixels) cannot draw a logo, a background picture or a frame, and is limited per caller. Saving, changing and deleting designs needs links.manage.
Assigning a QR code to documents makes it available to place on them in the editor. Placing a code in a document, or creating one there, assigns it. A published document's scan-to-open code is assigned to it as well.
List the workspace's QR designs
GET /qr-designs qrDesigns.list
Every saved design of the workspace, sorted by name. Deleted designs are left out.
- Scopes
links.read- MCP tool
qr_designs_list
Response
200 OK. A JSON object:
Response fields (8)
| Name | Type | Description |
|---|---|---|
designs | array of objects | The designs, sorted by name. |
designs[].id | string | The design's id. |
designs[].name | string | The design's name, the same as design.name. |
designs[].design | map of anys | The full design, every default filled in. Its fields are those POST /api/v1/qr-designs takes. |
designs[].isDefault | boolean | Whether this is the workspace's default design, which a QR code without a design of its own is drawn in. At most one design is. |
designs[].createdBy | string | The id of the member who saved it; null when no member did. Can be null. |
designs[].createdAt | number | When it was saved, epoch milliseconds. |
designs[].updatedAt | number | When it last changed, epoch milliseconds. |
Example request
curl https://api.flipbird.io/api/v1/qr-designs \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" Example response
{
"designs": [
{
"id": "string",
"name": "Spring catalogue",
"design": {},
"isDefault": true,
"createdBy": "string",
"createdAt": 1767225600000,
"updatedAt": 1767225600000
}
]
} Save a named QR design
POST /qr-designs qrDesigns.create
Colours, gradient, module and eye styles, quiet zone, error correction, an optional background image, a centre logo and a call-to-action frame. Images are data: URLs. Made the default, it replaces the current default. A design with an unknown field or a bad value is refused with 400 invalid, the message naming the field; a name another design already has answers 409 conflict.
- Scopes
links.manage- Retries
- Safe with an
Idempotency-Key - MCP tool
qr_designs_create
Request body
A JSON object, at most 64 KiB.
| Name | Type | Description |
|---|---|---|
design required | map of anys | The design, as a JSON object. Every field is optional and takes its default when left out; an unknown field or a bad value is refused with 400 invalid, the message naming it. Colours are hex: #rgb, #rrggbb or #rrggbbaa. name: 1 to 80 characters, unique among the workspace's designs; default "Default". foreground: the colour of the modules, and of the eyes (the three corner squares) unless they set their own; default #000000. background: a colour, or transparent; default #ffffff. gradient: null, or an object that paints the modules instead of foreground: type linear (default) or radial, angle in degrees from -360 to 360 for a linear one, 0 running left to right and 90 top to bottom (default 0), and stops, 2 to 8 objects of offset (0 to 1, never less than the stop before) and color. moduleStyle: square (default), rounded, dots, classy, diamond, star, bars-vertical or bars-horizontal. eyeOuterStyle: square (default), rounded or circle; eyeInnerStyle: square (default), rounded, circle or diamond; both are circle or neither is. eyeOuterColor and eyeInnerColor: a colour, or null (default) to paint the eye like the modules. quietZone: light modules around the code, 0 to 16; default 4. errorCorrection: the lowest level to encode at, L, M (default), Q or H; a drawn logo raises it to Q, or to H when the logo's size is above 0.2. logo: null, or a centre picture: href a data: URL of a PNG, JPEG, GIF, WebP or SVG image of at most 524288 characters, size its width as a fraction of the code, above 0 and at most 0.3 (default 0.2), margin the modules cleared around it, 0 to 2 (default 1), backdrop a pad in the background colour behind it (default false), and enabled (default true; false keeps it without drawing it). backgroundImage: null, or a picture behind the modules: href as for the logo, opacity 0 to 1 (default 1), and enabled (default true). frame: null, or a call-to-action band around the code: kind label (default), banner, bubble, phone or arrows; text up to 24 characters (default empty, which draws no label); textEnabled (default true); textColor (default #ffffff); color (default #000000); padding 0 to 6 modules (default 2); radius 0 to 10 modules (default 3); position top or bottom (default). |
isDefault | boolean | Make it the workspace's default design, in place of the current one. Default false. |
Response
201 Created. A JSON object:
Response fields (7)
| Name | Type | Description |
|---|---|---|
id | string | The design's id. |
name | string | The design's name, the same as design.name. |
design | map of anys | The full design, every default filled in. Its fields are those POST /api/v1/qr-designs takes. |
isDefault | boolean | Whether this is the workspace's default design, which a QR code without a design of its own is drawn in. At most one design is. |
createdBy | string | The id of the member who saved it; null when no member did. Can be null. |
createdAt | number | When it was saved, epoch milliseconds. |
updatedAt | number | When it last changed, epoch milliseconds. |
Example request
curl -X POST https://api.flipbird.io/api/v1/qr-designs \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"design": {}
}' Example response
{
"id": "string",
"name": "Spring catalogue",
"design": {},
"isDefault": true,
"createdBy": "string",
"createdAt": 1767225600000,
"updatedAt": 1767225600000
} Change a QR design, or make it the default
PATCH /qr-designs/{designId} qrDesigns.update
A new design replaces the old one whole: a field left out takes its default, not its old value, and the design's name is design.name. QR codes drawn in it are drawn in the new design from then on; their short URLs do not change.
isDefault true makes it the default in place of the current one; false stops it being the default, and QR codes without a design of their own are then drawn in the built-in design (black square modules on white). A bad design answers 400 invalid, a name another design has 409 conflict, and an unknown design 404 not_found.
- Scopes
links.manage- Retries
- Safe with an
Idempotency-Key - MCP tool
qr_designs_update
Path parameters
| Name | Type | Description |
|---|---|---|
designId required | string | The design's id. An id starting qrd_. |
Request body
A JSON object, at most 64 KiB.
| Name | Type | Description |
|---|---|---|
design | map of anys | The new design, replacing the old one whole; its fields are those POST /api/v1/qr-designs takes. Omitted leaves it unchanged. |
isDefault | boolean | True makes it the workspace's default design in place of the current one; false stops it being the default. Omitted leaves it unchanged. |
Response
200 OK. A JSON object:
Response fields (7)
| Name | Type | Description |
|---|---|---|
id | string | The design's id. |
name | string | The design's name, the same as design.name. |
design | map of anys | The full design, every default filled in. Its fields are those POST /api/v1/qr-designs takes. |
isDefault | boolean | Whether this is the workspace's default design, which a QR code without a design of its own is drawn in. At most one design is. |
createdBy | string | The id of the member who saved it; null when no member did. Can be null. |
createdAt | number | When it was saved, epoch milliseconds. |
updatedAt | number | When it last changed, epoch milliseconds. |
Example request
curl -X PATCH https://api.flipbird.io/api/v1/qr-designs/qrd_7m2kq9vx4c8d1r5t6wnb \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"design": {},
"isDefault": true
}' Example response
{
"id": "string",
"name": "Spring catalogue",
"design": {},
"isDefault": true,
"createdBy": "string",
"createdAt": 1767225600000,
"updatedAt": 1767225600000
} Delete a QR design
DELETE /qr-designs/{designId} qrDesigns.delete
QR codes drawn in it are drawn in the workspace's default design afterwards, or in the built-in design when it was the default. Printed codes keep working: their short URLs do not change. An unknown design answers 404 not_found.
- Scopes
links.manage- Retries
- Safe with an
Idempotency-Key - MCP tool
qr_designs_delete
Path parameters
| Name | Type | Description |
|---|---|---|
designId required | string | The design's id. An id starting qrd_. |
Response
200 OK. An empty JSON object, {}.
Example request
curl -X DELETE https://api.flipbird.io/api/v1/qr-designs/qrd_7m2kq9vx4c8d1r5t6wnb \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" A link's QR code as SVG or PNG
GET /links/{linkId}/qr links.qr
Encodes the link's short URL, drawn in designId if given, else the link's design, else the workspace's default design, else the built-in design (black square modules on white, a quiet zone of 4, error correction M). Any link has a QR code, whatever its kind.
format=png returns a PNG size pixels square (64 to 2048, default 1024); a design with a drawn logo, a drawn background picture or a frame is drawn as SVG only, and its PNG is refused with 422 unrenderable. PNGs are limited per caller: too many at once answer 429 rate_limited with Retry-After: 60. The SVG is resolution-independent; width sets its width attribute. download=1 asks the browser to save it.
The response carries an ETag and may be kept privately (Cache-Control: private, no-cache); send If-None-Match to get 304 when nothing changed. An unknown link, or an unknown designId, answers 404 not_found.
- Scopes
links.read
Path parameters
| Name | Type | Description |
|---|---|---|
linkId required | string | The link's id. An id starting lnk_. |
Query parameters
| Name | Type | Description |
|---|---|---|
designId | string | Draw it in this saved design instead of the link's own. A design that is not one of the workspace's answers 404 not_found. An id starting qrd_. |
width | integer | SVG only: the width attribute, in CSS pixels; the height attribute follows the code's proportions, taller with a frame. Omitted, the SVG has no size of its own and fills its container. Ignored for PNG. 16 to 4,096. |
download | string | 1 sends it as an attachment named qr-{code}.svg or qr-{code}.png; 0 or omitted sends it inline. One of 0, 1. |
format | string | svg (image/svg+xml) or png (image/png). Default svg. One of svg, png. |
size | integer | PNG only: the side of the square image, in pixels. Default 1024. Ignored for SVG. 64 to 2,048. |
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/qr \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-OJ Documents a QR code is assigned to
GET /links/{linkId}/documents qrAssignments.forLink
The documents the code can be placed on in the editor, sorted by title. Documents in the trash, and those the caller cannot open, are left out. A plain link has none. An unknown link answers 404 not_found.
- Scopes
links.read- MCP tool
qr_assignments_list
Path parameters
| Name | Type | Description |
|---|---|---|
linkId required | string | The QR code's link id. An id starting lnk_. |
Response
200 OK. A JSON object:
Response fields (3)
| Name | Type | Description |
|---|---|---|
documents | array of objects | The documents, sorted by title. |
documents[].documentId | string | The document's id. |
documents[].title | string | The document's title. |
Example request
curl https://api.flipbird.io/api/v1/links/lnk_7m2kq9vx4c8d1r5t6wnb/documents \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" Example response
{
"documents": [
{
"documentId": "…",
"title": "Spring catalogue"
}
]
} Choose which documents a QR code can be added to
PUT /links/{linkId}/documents qrAssignments.set
Replaces the assignment. A code created from a document, or placed in one, is assigned to that document as it is. Each document named must be one the caller can open, else 404 not_found; each one newly added, one the caller can edit, else 403 forbidden. Assignments to documents the caller cannot see, or that are in the trash, are kept whatever the list says.
Only a QR code can be assigned: a plain link answers 404 not_found. Changing the assignment needs links.manage, or links.edit on a code the caller made, otherwise 403 forbidden; a document's scan-to-open code also needs edit access to that document. Returns the documents the code is now assigned to that the caller can see.
- Scopes
links.edit- Retries
- Safe with an
Idempotency-Key - MCP tool
qr_assignments_set
Path parameters
| Name | Type | Description |
|---|---|---|
linkId required | string | The QR code's link id. An id starting lnk_. |
Request body
A JSON object, at most 64 KiB.
| Name | Type | Description |
|---|---|---|
documentIds required | array of strings | Every document the code may be placed on. An empty list removes every assignment the caller can see. At most 200 items. |
Response
200 OK. A JSON object:
Response fields (3)
| Name | Type | Description |
|---|---|---|
documents | array of objects | The documents the code is now assigned to that the caller can see, sorted by title. |
documents[].documentId | string | The document's id. |
documents[].title | string | The document's title. |
Example request
curl -X PUT https://api.flipbird.io/api/v1/links/lnk_7m2kq9vx4c8d1r5t6wnb/documents \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"documentIds": [
"doc_7m2kq9vx4c8d1r5t6wnb"
]
}' Example response
{
"documents": [
{
"documentId": "…",
"title": "Spring catalogue"
}
]
} QR codes assigned to a document, available to place on it
GET /documents/{documentId}/qr-codes qrAssignments.forDocument
The link ids of the codes assigned to the document, the oldest assignment first, its scan-to-open code included once the document is published. Read each with GET /api/v1/links/{linkId}. A document the caller cannot open answers 404 not_found.
- Scopes
documents.read,links.read- MCP tool
document_qr_codes
Path parameters
| Name | Type | Description |
|---|---|---|
documentId required | string | The document's id. An id starting doc_. |
Response
200 OK. A JSON object:
Response fields (1)
| Name | Type | Description |
|---|---|---|
linkIds | array of strings | The QR codes' link ids, the oldest assignment first. |
Example request
curl https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb/qr-codes \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" Example response
{
"linkIds": [
"string"
]
} Errors
Besides the errors any endpoint can answer, these endpoints answer:
| Status | Code | When |
|---|---|---|
| 400 | invalid | A QR design field is not valid. |
| 409 | conflict | Another design already has that name. |
| 422 | unrenderable | A PNG of a design with a logo, background picture or frame, which only SVG draws; or an SVG the renderer refuses. |