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)
NameTypeDescription
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.

NameTypeDescription
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)
NameTypeDescription
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

NameTypeDescription
designId required string The design's id. An id starting qrd_.

Request body

A JSON object, at most 64 KiB.

NameTypeDescription
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)
NameTypeDescription
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

NameTypeDescription
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)"

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

NameTypeDescription
linkId required string The QR code's link id. An id starting lnk_.

Request body

A JSON object, at most 64 KiB.

NameTypeDescription
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)
NameTypeDescription
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

NameTypeDescription
documentId required string The document's id. An id starting doc_.

Response

200 OK. A JSON object:

Response fields (1)
NameTypeDescription
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:

StatusCodeWhen
400invalidA QR design field is not valid.
409conflictAnother design already has that name.
422unrenderableA PNG of a design with a logo, background picture or frame, which only SVG draws; or an SVG the renderer refuses.