GET POST
qr-codes/
User API Service tier
List qr codes, or create one with POST. derived from route
URL
User API https://qr.mattering.io/api/user/v1/qr-codes/
Service tier https://qr.mattering.io/api/internal/qr-codes/
Query parameters
Name Default
fieldsnone fullnone kindnone qnone searchnone space_idnone viewnone workspace_idnone
Pagination
Accepts limit and offset. The response meta carries total, limit and offset.
Responses
200 bare JSON object (no envelope)
{
"qr_codes": [
"..."
],
"meta": {
"total": 0,
"limit": 0,
"offset": 0,
"returned": 0,
"has_more": false
}
}
201 bare JSON object (no envelope)
{
"qr_code": {
"id": "...",
"short_code": "...",
"short_path": "...",
"kind": "...",
"primary_slug": "...",
"primary_short_path": "...",
"primary_url": "...",
"aliases": [
{
"slug": "...",
"is_primary": true,
"is_active": true
}
],
"title": "...",
"destination_url": "...",
"effective_destination": "...",
"utm": "...",
"starts_at": "2026-01-01T00:00:00Z",
"expires_at": "2026-01-01T00:00:00Z",
"is_password_protected": true,
"rules": {
"...": "..."
},
"is_active": true,
"scan_count": 0,
"last_scanned_at": "2026-01-01T00:00:00Z",
"workspace_id": "...",
"space_id": "...",
"file_format": "...",
"color_mode": "...",
"asset_path": "...",
"public_asset_url": "...",
"public_asset_urls": {
"png": "...",
"pdf": "..."
},
"created_at": "2026-01-01T00:00:00Z"
},
"ignored_fields": "..."
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
Status Code
401 unauthorized
Example
User API Service tier
curl -X GET "https://qr.mattering.io/api/user/v1/qr-codes/?fields=...&full=...&kind=..." \
-H "Authorization: Bearer $MATTERING_API_KEY" curl -X GET "https://qr.mattering.io/api/internal/qr-codes/?fields=...&full=...&kind=..." \
-H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
-H "X-Internal-Org-Id: $ORG_ID" \
-H "X-Internal-User-Email: you@example.com"
Source: QRCore/internal_api.py (internal_api.qr_codes)
POST
qr-codes/bulk/
User API Service tier
Create many QR codes / short links in one call (item 6 `_bulk` action).
Body: {"items": [ {title, destination_url, space_id, slug?, kind?, ...}, ... ]}. Per-item validation mirrors single create; results are returned positionally so a caller can map failures back to input rows. Partial success is allowed.
URL
User API https://qr.mattering.io/api/user/v1/qr-codes/bulk/
Service tier https://qr.mattering.io/api/internal/qr-codes/bulk/
Query parameters
Body keys (JSON)
Key Required Default
codesoptional or conditional none fulloptional or conditional none itemsoptional or conditional none kindoptional or conditional none space_idoptional or conditional none workspace_idoptional or conditional none
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Responses
201 bare JSON object (no envelope)
{
"created": 0,
"failed": "...",
"total": 0,
"results": [
{
"index": "...",
"ok": false,
"short_code": null,
"primary_url": null,
"error": "...",
"detail": "..."
}
]
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
Status Code
400 items_required400 too_many_items401 unauthorized
Example
User API Service tier
curl -X POST "https://qr.mattering.io/api/user/v1/qr-codes/bulk/" \
-H "Authorization: Bearer $MATTERING_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"codes": "...",
"full": "...",
"items": "...",
"kind": "...",
"space_id": "...",
"workspace_id": "..."
}' curl -X POST "https://qr.mattering.io/api/internal/qr-codes/bulk/" \
-H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
-H "X-Internal-Org-Id: $ORG_ID" \
-H "X-Internal-User-Email: you@example.com" \
-H "Content-Type: application/json" \
-d '{
"codes": "...",
"full": "...",
"items": "...",
"kind": "...",
"space_id": "...",
"workspace_id": "..."
}'
Source: QRCore/internal_api.py (internal_api.qr_codes_bulk)
GET POST DELETE
qr-codes/{short_code} /
User API Service tier
Get, update, or delete a single QR code / short link by its short_code.
URL
User API https://qr.mattering.io/api/user/v1/qr-codes/{short_code} /
Service tier https://qr.mattering.io/api/internal/qr-codes/{short_code} /
Path parameters
Responses
200 bare JSON object (no envelope)
{
"deleted": "..."
}
200 bare JSON object (no envelope)
{
"qr_code": {
"id": "...",
"short_code": "...",
"short_path": "...",
"kind": "...",
"primary_slug": "...",
"primary_short_path": "...",
"primary_url": "...",
"aliases": [
{
"slug": "...",
"is_primary": true,
"is_active": true
}
],
"title": "...",
"destination_url": "...",
"effective_destination": "...",
"utm": "...",
"starts_at": "2026-01-01T00:00:00Z",
"expires_at": "2026-01-01T00:00:00Z",
"is_password_protected": true,
"rules": {
"...": "..."
},
"is_active": true,
"scan_count": 0,
"last_scanned_at": "2026-01-01T00:00:00Z",
"workspace_id": "...",
"space_id": "...",
"file_format": "...",
"color_mode": "...",
"asset_path": "...",
"public_asset_url": "...",
"public_asset_urls": {
"png": "...",
"pdf": "..."
},
"created_at": "2026-01-01T00:00:00Z"
},
"updated": [
"destination_url"
],
"ignored_fields": "..."
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
Status Code
400 destination_url_empty400 invalid_color_mode400 invalid_destination400 invalid_file_format400 invalid_kind400 no_writable_fields401 unauthorized404 not_found
Example
User API Service tier
curl -X GET "https://qr.mattering.io/api/user/v1/qr-codes/SHORT_CODE/" \
-H "Authorization: Bearer $MATTERING_API_KEY" curl -X GET "https://qr.mattering.io/api/internal/qr-codes/SHORT_CODE/" \
-H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
-H "X-Internal-Org-Id: $ORG_ID" \
-H "X-Internal-User-Email: you@example.com"
Source: QRCore/internal_api.py (internal_api.qr_code_detail)
GET POST DELETE
qr-codes/{short_code} /aliases/
User API Service tier
Manage the vanity aliases of one code.
GET returns list aliases. POST returns {slug, primary?} add/promote an alias (default sets it primary). DELETE returns {slug} deactivate an alias (never hard-deleted once it has scans).
URL
User API https://qr.mattering.io/api/user/v1/qr-codes/{short_code} /aliases/
Service tier https://qr.mattering.io/api/internal/qr-codes/{short_code} /aliases/
Path parameters
Query parameters
Body keys (JSON)
Key Required Default
fulloptional or conditional none slugoptional or conditional none
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Responses
200 bare JSON object (no envelope)
{
"ok": true,
"alias": "...",
"aliases": {
"...": "..."
},
"primary_url": "...",
"qr_code": {
"id": "...",
"short_code": "...",
"short_path": "...",
"kind": "...",
"primary_slug": "...",
"primary_short_path": "...",
"primary_url": "...",
"aliases": [
{
"slug": "...",
"is_primary": true,
"is_active": true
}
],
"title": "...",
"destination_url": "...",
"effective_destination": "...",
"utm": "...",
"starts_at": "2026-01-01T00:00:00Z",
"expires_at": "2026-01-01T00:00:00Z",
"is_password_protected": true,
"rules": {
"...": "..."
},
"is_active": true,
"scan_count": 0,
"last_scanned_at": "2026-01-01T00:00:00Z",
"workspace_id": "...",
"space_id": "...",
"file_format": "...",
"color_mode": "...",
"asset_path": "...",
"public_asset_url": "...",
"public_asset_urls": {
"png": "...",
"pdf": "..."
},
"created_at": "2026-01-01T00:00:00Z"
}
}
200 bare JSON object (no envelope)
{
"aliases": {
"...": "..."
},
"short_code": "..."
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
Status Code
400 slug_required401 unauthorized404 alias_not_found404 not_found
Example
User API Service tier
curl -X POST "https://qr.mattering.io/api/user/v1/qr-codes/SHORT_CODE/aliases/" \
-H "Authorization: Bearer $MATTERING_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"full": "...",
"slug": "..."
}' curl -X POST "https://qr.mattering.io/api/internal/qr-codes/SHORT_CODE/aliases/" \
-H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
-H "X-Internal-Org-Id: $ORG_ID" \
-H "X-Internal-User-Email: you@example.com" \
-H "Content-Type: application/json" \
-d '{
"full": "...",
"slug": "..."
}'
Source: QRCore/internal_api.py (internal_api.qr_code_aliases)
GET POST DELETE
qr-codes/{short_code} /rules/
User API Service tier
Manage the device/country routing rules of one code (P2 #10).
GET returns list active rules (ordered). POST returns {match_type, match_value, destination_url, order?} add a rule. DELETE returns {rule_id} remove a rule (rules carry no history; hard delete).
URL
User API https://qr.mattering.io/api/user/v1/qr-codes/{short_code} /rules/
Service tier https://qr.mattering.io/api/internal/qr-codes/{short_code} /rules/
Path parameters
Query parameters
Body keys (JSON)
Key Required Default
destination_urloptional or conditional none fulloptional or conditional none match_typeoptional or conditional none match_valueoptional or conditional none orderoptional or conditional none rule_idoptional or conditional none
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Responses
200 bare JSON object (no envelope)
{
"ok": true,
"rule": "...",
"rules": {
"...": "..."
},
"qr_code": {
"id": "...",
"short_code": "...",
"short_path": "...",
"kind": "...",
"primary_slug": "...",
"primary_short_path": "...",
"primary_url": "...",
"aliases": [
{
"slug": "...",
"is_primary": true,
"is_active": true
}
],
"title": "...",
"destination_url": "...",
"effective_destination": "...",
"utm": "...",
"starts_at": "2026-01-01T00:00:00Z",
"expires_at": "2026-01-01T00:00:00Z",
"is_password_protected": true,
"rules": {
"...": "..."
},
"is_active": true,
"scan_count": 0,
"last_scanned_at": "2026-01-01T00:00:00Z",
"workspace_id": "...",
"space_id": "...",
"file_format": "...",
"color_mode": "...",
"asset_path": "...",
"public_asset_url": "...",
"public_asset_urls": {
"png": "...",
"pdf": "..."
},
"created_at": "2026-01-01T00:00:00Z"
}
}
200 bare JSON object (no envelope)
{
"rules": {
"...": "..."
},
"short_code": "..."
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
Status Code
400 rule_id_required401 unauthorized404 not_found404 rule_not_found
Example
User API Service tier
curl -X POST "https://qr.mattering.io/api/user/v1/qr-codes/SHORT_CODE/rules/" \
-H "Authorization: Bearer $MATTERING_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"destination_url": "...",
"full": "...",
"match_type": "...",
"match_value": "...",
"order": "...",
"rule_id": "..."
}' curl -X POST "https://qr.mattering.io/api/internal/qr-codes/SHORT_CODE/rules/" \
-H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
-H "X-Internal-Org-Id: $ORG_ID" \
-H "X-Internal-User-Email: you@example.com" \
-H "Content-Type: application/json" \
-d '{
"destination_url": "...",
"full": "...",
"match_type": "...",
"match_value": "...",
"order": "...",
"rule_id": "..."
}'
Source: QRCore/internal_api.py (internal_api.qr_code_rules)