QR Codes

QR code endpoints allow you to generate QR codes, manage QR code designs, and link QR codes to pages.

List QR Codes

Get a list of all QR codes in a project.

GET https://v1.freeqr.io/api/projects/{project}/qr_codes

Requires Authentication: Yes

Path Parameters

Parameter	Type	Required	Description
`project`	string (ULID)	Yes	Project ID

Query Parameters

Parameter	Type	Required	Description
`page`	integer	No	Page number (default: 1)
`limit`	integer	No	Items per page (default: 10, max: 100)
`sort`	string	No	Sort field (default: `id`; prefix with `-` for descending)
`filters[resource_id]`	string (ULID)	No	Filter by resource ID

Response

{
  "data": [
    {
      "id": "01arz3ndektsv4rrffq69g5fav",
      "title": "My QR Code",
      "resource_type": "page",
      "resource_id": "01arz3ndektsv4rrffq69g5fav",
      "size": 640,
      "margin": 4,
      "error_correction": 1,
      "text": "https://example.com/page",
      "default_block_style": "heart",
      "inner_corner_block_style": "inner-heart",
      "outer_corner_block_style": "outer-square-drop-out",
      "background_color": "255,255,255,1",
      "foreground_color": "0,0,0,1",
      "outer_corner_color": null,
      "inner_corner_color": null,
      "options": null,
      "logo_file_id": null,
      "logo_size": null,
      "frame": null,
      "freme_options": {},
      "qr_design_template_id": null,
      "index": 1,
      "view": 0,
    }
  ],
  "meta": {
    "total": 1
  },
  "included_files": []
}

Create QR Code

Create a new QR code in a project.

POST https://v1.freeqr.io/api/projects/{project}/qr_codes

Requires Authentication: Yes

Path Parameters

Parameter	Type	Required	Description
`project`	string (ULID)	Yes	Project ID

Request Body

{
  "title": "My QR Code",
  "logo_file_id": "01arz3ndektsv4rrffq69g5fav",
  "qr_design_template_id": "01arz3ndektsv4rrffq69g5fav",
  "resource_type": "page",
  "resource_id": "01arz3ndektsv4rrffq69g5fav",
  "size": 320,
  "margin": 4,
  "error_correction": 2,
  "default_block_style": "square",
  "inner_corner_block_style": "square",
  "outer_corner_block_style": "square",
  "background_color": "255,255,255,1",
  "foreground_color": "0,0,0,1",
  "outer_corner_color": "0,0,0,1",
  "inner_corner_color": "0,0,0,1",
  "logo_size": 20,
  "frame": null,
  "frame_options": {}
}

Parameters

Parameter	Type	Required	Description
`title`	string	No	QR code title (max 60 characters)
`logo_file_id`	string (ULID)	No	Logo file ID to embed
`qr_design_template_id`	string (ULID)	No	QR design template ID. When provided, the template's current version config is merged with the design fields (`margin`, `error_correction`, colors, styles, etc.), where provided values override template config values. If design fields are empty or missing, template config values are used as defaults.
`resource_type`	string	Yes	Resource type (must be `page`)
`resource_id`	string (ULID)	Yes	Resource ID (page ID)
`size`	integer	No	QR code size in pixels. Must be one of: `100`, `320`, `640`, `960`, `1280`, `1920`.
`margin`	integer	No	Margin size. Overrides template config value when `qr_design_template_id` is set.
`error_correction`	integer	No	QR code error correction level (1, 2, 3, 4). This value is mapped to Endroid's correction level when generating the QR to control data redundancy. Higher levels improve resistance to damage/occlusion, but reduce max data capacity and can make the QR denser. If omitted, the system defaults to `MEDIUM`. Overrides template config value when `qr_design_template_id` is set.
`default_block_style`	string	No	Default block style. Overrides template config value when `qr_design_template_id` is set.
`inner_corner_block_style`	string	No	Inner corner block style. Overrides template config value when `qr_design_template_id` is set.
`outer_corner_block_style`	string	No	Outer corner block style. Overrides template config value when `qr_design_template_id` is set.
`background_color`	string	No	Background color. See Color Formats for format details. Overrides template config value when `qr_design_template_id` is set.
`foreground_color`	string	No	Foreground color. See Color Formats for format details. Overrides template config value when `qr_design_template_id` is set.
`outer_corner_color`	string	No	Outer corner color. See Color Formats for format details. Overrides template config value when `qr_design_template_id` is set.
`inner_corner_color`	string	No	Inner corner color. See Color Formats for format details. Overrides template config value when `qr_design_template_id` is set.
`logo_size`	integer	No	Logo size (integer `1`–`30`, inclusive). Overrides template config value when `qr_design_template_id` is set.
`frame`	string \| null	No	Frame type (for example `basic-bottom`), or `null` for no frame. Overrides template config value when `qr_design_template_id` is set.
`frame_options`	object	No	Frame options. Overrides template config value when `qr_design_template_id` is set.

`error_correction` values

Value	Level
`1`	`LOW`
`2`	`MEDIUM`
`3`	`QUARTILE`
`4`	`HIGH`

error_correction controls how much redundant data is embedded in the QR code. The value is mapped to Endroid correction levels during generation. Higher levels are more tolerant to damage or partial obstruction, but lower the maximum encodable payload and can produce visually denser QR patterns. When not provided, MEDIUM is used.

Response

{
  "data": {
    "id": "01arz3ndektsv4rrffq69g5faa",
    "title": "My QR Code",
    "resource_type": "page",
    "resource_id": "01arz3ndektsv4rrffq69g5fav",
    "size": 320,
    "margin": 4,
    "error_correction": 2,
    "text": "https://example.com/page",
    "default_block_style": "square",
    "inner_corner_block_style": "square",
    "outer_corner_block_style": "square",
    "background_color": "255,255,255,1",
    "foreground_color": "0,0,0,1",
    "outer_corner_color": "0,0,0,1",
    "inner_corner_color": "0,0,0,1",
    "options": null,
    "logo_file_id": "01arz3ndektsv4rrffq69g5fav",
    "logo_size": 20,
    "frame": null,
    "freme_options": {},
    "qr_design_template_id": "01arz3ndektsv4rrffq69g5fav",
    "index": 1,
    "view": 0,
    "qr_design_template": {},
  }
}

Note: When qr_design_template_id is provided, the template's current version config is merged with the provided design fields (margin, error_correction, colors, styles, etc.), where provided values override template config values. This allows you to use template defaults while customizing specific design fields. If design fields are empty or missing, template config values are used as defaults.

Get QR Code

Get a specific QR code by ID.

GET https://v1.freeqr.io/api/qr_codes/{id}

Requires Authentication: Yes

Path Parameters

Parameter	Type	Required	Description
`id`	string (ULID)	Yes	QR code ID

Response

{
  "data": {
    "id": "01arz3ndektsv4rrffq69g5fav",
    "title": "My QR Code",
    "resource_type": "page",
    "resource_id": "01arz3ndektsv4rrffq69g5fav",
    "size": 640,
    "margin": 4,
    "error_correction": 1,
    "text": "https://example.com/page",
    "default_block_style": "heart",
    "inner_corner_block_style": "inner-heart",
    "outer_corner_block_style": "outer-square-drop-out",
    "background_color": "255,255,255,1",
    "foreground_color": "0,0,0,1",
    "outer_corner_color": "0,0,0,1",
    "inner_corner_color": "0,0,0,1",
    "options": null,
    "logo_file_id": null,
    "logo_size": null,
    "frame": null,
    "freme_options": {},
    "qr_design_template_id": null,
    "index": 1,
    "view": 0,
  }
}

Update QR Code

Update an existing QR code.

PATCH https://v1.freeqr.io/api/qr_codes/{id}

Requires Authentication: Yes

Path Parameters

Parameter	Type	Required	Description
`id`	string (ULID)	Yes	QR code ID

Request Body

Same parameters as Create QR Code, but all fields are optional.

Note: When qr_design_template_id is provided, the template's current version config is merged with the provided design fields, where provided values override template config values. This allows you to use template defaults while customizing specific fields.

Response

{
  "data": {
    "id": "01arz3ndektsv4rrffq69g5fav",
    "title": "My QR Code",
    "resource_type": "page",
    "resource_id": "01arz3ndektsv4rrffq69g5fav",
    "size": 640,
    "margin": 4,
    "error_correction": 1,
    "text": "https://example.com/page",
    "default_block_style": "heart",
    "inner_corner_block_style": "inner-heart",
    "outer_corner_block_style": "outer-square-drop-out",
    "background_color": "255,255,255,1",
    "foreground_color": "0,0,0,1",
    "outer_corner_color": "0,0,0,1",
    "inner_corner_color": "0,0,0,1",
    "options": null,
    "logo_file_id": null,
    "logo_size": null,
    "frame": null,
    "freme_options": {},
    "qr_design_template_id": null,
    "index": 1,
    "view": 0,
  }
}

Delete QR Code

Delete a QR code.

DELETE https://v1.freeqr.io/api/qr_codes/{id}

Requires Authentication: Yes

Path Parameters

Parameter	Type	Required	Description
`id`	string (ULID)	Yes	QR code ID

Response

Returns the deleted QR code resource (same structure as Get QR Code).

List QR Codes​

Path Parameters​

Query Parameters​

Response​

Create QR Code​

Path Parameters​

Request Body​

Parameters​

error_correction values​

Response​

Get QR Code​

Path Parameters​

Response​

Update QR Code​

Path Parameters​

Request Body​

Response​

Delete QR Code​

Path Parameters​

Response​

List QR Codes

Path Parameters

Query Parameters

Response

Create QR Code

Path Parameters

Request Body

Parameters

`error_correction` values

Response

Get QR Code

Path Parameters

Response

Update QR Code

Path Parameters

Request Body

Response

Delete QR Code

Path Parameters

Response