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": 300,
      "margin": 4,
      "error_correction": "M",
      "text": "https://example.com/page",
      "created_at": "2024-01-01T00:00:00.000000Z",
      "updated_at": "2024-01-01T00:00:00.000000Z"
    }
  ],
  "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": 300,
  "margin": 4,
  "error_correction": "M",
  "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": 60,
  "frame": "none",
  "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
margin	integer	No	Margin size. Overrides template config value when qr_design_template_id is set.
error_correction	string	No	Error correction level (L, M, Q, H). 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 percentage. Overrides template config value when qr_design_template_id is set.
frame	string	No	Frame type. 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.

Response

{
  "data": {
    "id": "01arz3ndektsv4rrffq69g5fav",
    "title": "My QR Code",
    "resource_type": "page",
    "resource_id": "01arz3ndektsv4rrffq69g5fav",
    "size": 300,
    "margin": 4,
    "error_correction": "M",
    "created_at": "2024-01-01T00:00:00.000000Z",
    "updated_at": "2024-01-01T00:00:00.000000Z"
  }
}

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": 300,
    "margin": 4,
    "error_correction": "M",
    "created_at": "2024-01-01T00:00:00.000000Z",
    "updated_at": "2024-01-01T00:00:00.000000Z"
  }
}

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": "Updated QR Code",
    "resource_type": "page",
    "resource_id": "01arz3ndektsv4rrffq69g5fav",
    "size": 400,
    "margin": 4,
    "error_correction": "H",
    "created_at": "2024-01-01T00:00:00.000000Z",
    "updated_at": "2024-01-01T00:00:00.000000Z"
  }
}

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