API Reference

This reference describes the FreeQR API: endpoints, request and response formats, and shared conventions. Use the links below to jump to a topic or resource.

Quick start

Base URL: All requests use this base (endpoints are relative to it).

https://v1.freeqr.io/api

Authentication: Most endpoints require a Bearer token. Send it in the Authorization header:

Authorization: Bearer your-api-key-here

Get and manage tokens in the Authentication guide.

---

Conventions

Request and response

• Headers: Use Content-Type: application/json and Accept: application/json for POST/PATCH and when expecting JSON.
• Success: Responses use 200 OK, 201 Created, or 204 No Content where appropriate.
• Errors: 400 invalid request, 401 unauthorized, 403 forbidden, 404 not found, 422 validation error, 500 server error.

Pagination

List endpoints support:

• page — Page number (default: 1)
• limit — Items per page (default: 10, max: 100)

Maximum offset is 10,000; if (page - 1) * limit > 10000 the request returns 400.

Response shape:

{
  "data": [...],
  "meta": { "total": 150 }
}

Filtering and sorting

• Filter: filters[field] (e.g. filters[search], filters[type], filters[resource_id]).
• Sort: sort with optional - for descending (e.g. sort=id, sort=-id).

Rate limiting

Responses include X-RateLimit-Limit and X-RateLimit-Remaining.

---

Documentation

Getting started

Page	Description
Authentication	Obtain and use Bearer tokens

API resources

Resource	Description
Projects	Projects CRUD, users, attach/detach user
Pages	Pages CRUD, public page, unlock
QR Codes	QR codes CRUD within projects
Components	Page components, list/create/update/delete, bulk store/update
Component types	form_data structures for each component type (sub-page of Components)
Templates	Design templates and template versions
Domains	List platform domains
Files	Upload, download, listing
Form Submissions	Submit and manage form submissions

Utilities

Page	Description
QR Code Generator	Public QR image generation (GET/POST)
Scanner	Scan QR from image or URL

Reference (data types)

Page	Description
Color formats	Colors and gradients in requests