{"openapi":"3.0.0","paths":{"/v1/health":{"get":{"description":"Answers 200 with {\"status\":\"ok\"} while the API can serve requests, and 503 when it cannot.\n\nNo API key needed.","operationId":"HealthController_check","parameters":[{"$ref":"#/components/parameters/X-Request-Id"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]}},"required":["status"]}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}}},"default":{"description":"Error (problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"summary":"Service health (no API key needed)","tags":["Health"],"security":[]}},"/v1/qr-codes":{"post":{"operationId":"QrCodes_create","parameters":[{"$ref":"#/components/parameters/X-Request-Id"},{"$ref":"#/components/parameters/Idempotency-Key"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateQrCodeV1Dto"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QrCode"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"ETag":{"$ref":"#/components/headers/ETag"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"links":{"GetQrCode":{"operationId":"QrCodes_get","parameters":{"id":"$response.body#/id"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/IdempotencyKeyReuse"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"default":{"description":"Error (problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"summary":"Create a QR code (URL, PHONE, WIFI, VCARD)","tags":["QR codes"],"x-required-scopes":["qr:write"],"description":"Requires the scope `qr:write`.\n\ntype TIME_BASED is refused here (400 validation-error at /type): create time-based codes with POST /v1/qr-codes/time-based."},"get":{"operationId":"QrCodes_list","parameters":[{"name":"limit","required":false,"in":"query","description":"Items per page","schema":{"minimum":1,"maximum":100,"default":25,"type":"integer"}},{"name":"cursor","required":false,"in":"query","description":"Opaque cursor from the previous page (nextCursor), passed back unchanged. A malformed cursor is refused with 400 invalid-cursor.","schema":{"maxLength":512,"type":"string"}},{"name":"type","required":false,"in":"query","schema":{"type":"string","enum":["URL","PHONE","WIFI","TIME_BASED","VCARD"]}},{"name":"updatedSince","required":false,"in":"query","description":"Only codes changed at or after this instant, for incremental sync. An RFC 3339 date-time with a time zone, e.g. 2026-11-01T00:00:00Z.","schema":{"format":"date-time","type":"string"}},{"name":"sku","required":false,"in":"query","description":"Only codes with this SKU.","schema":{"maxLength":100,"type":"string"}},{"name":"gtin","required":false,"in":"query","description":"Only GS1 codes for this GTIN, as 14 digits (pad shorter GTINs with leading zeros).","schema":{"pattern":"^\\d{14}$","type":"string"}},{"name":"departmentId","required":false,"in":"query","description":"Only codes in this department (GET /v1/departments).","schema":{"pattern":"^c[a-z0-9]{24}$","type":"string"}},{"$ref":"#/components/parameters/X-Request-Id"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/QrCode"}},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"links":{"GetQrCode":{"operationId":"QrCodes_get","parameters":{"id":"$response.body#/data/0/id"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"default":{"description":"Error (problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"summary":"List QR codes","tags":["QR codes"],"x-required-scopes":["qr:read"],"description":"Requires the scope `qr:read`."}},"/v1/qr-codes/time-based":{"post":{"operationId":"QrCodes_createTimeBased","parameters":[{"$ref":"#/components/parameters/X-Request-Id"},{"$ref":"#/components/parameters/Idempotency-Key"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTimeBasedQrCodeV1Dto"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QrCode"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"ETag":{"$ref":"#/components/headers/ETag"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"links":{"GetQrCode":{"operationId":"QrCodes_get","parameters":{"id":"$response.body#/id"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/IdempotencyKeyReuse"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"default":{"description":"Error (problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"summary":"Create a time-based QR code","tags":["QR codes"],"x-required-scopes":["qr:write"],"description":"Requires the scope `qr:write`."}},"/v1/qr-codes/{id}":{"get":{"operationId":"QrCodes_get","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"$ref":"#/components/parameters/X-Request-Id"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QrCode"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"default":{"description":"Error (problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"summary":"Get a QR code","tags":["QR codes"],"x-required-scopes":["qr:read"],"description":"Requires the scope `qr:read`."},"patch":{"operationId":"QrCodes_update","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"X-Change-Note","in":"header","description":"Why the change is made, recorded with it in the activity log (up to 500 characters; percent-encode non-ASCII text). Required when the organization requires change notes: without it the request is refused with change-note-required.","required":false,"schema":{"type":"string"}},{"name":"If-Match","in":"header","description":"The version from the ETag (or the version field) of the code you read. The write is refused with 409 conflict if the code changed since; without it, last write wins.","required":false,"schema":{"type":"string"}},{"$ref":"#/components/parameters/X-Request-Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateQrCodeV1Dto"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QrCode"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"ETag":{"$ref":"#/components/headers/ETag"}},"links":{"GetQrCode":{"operationId":"QrCodes_get","parameters":{"id":"$response.body#/id"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"429":{"$ref":"#/components/responses/TooManyRequests"},"default":{"description":"Error (problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"summary":"Update a QR code","tags":["QR codes"],"x-required-scopes":["qr:write"],"description":"Requires the scope `qr:write`."},"delete":{"operationId":"QrCodes_remove","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"X-Change-Note","in":"header","description":"Why the change is made, recorded with it in the activity log (up to 500 characters; percent-encode non-ASCII text). Required when the organization requires change notes: without it the request is refused with change-note-required.","required":false,"schema":{"type":"string"}},{"name":"If-Match","in":"header","description":"The version from the ETag (or the version field) of the code you read. The write is refused with 409 conflict if the code changed since; without it, last write wins.","required":false,"schema":{"type":"string"}},{"$ref":"#/components/parameters/X-Request-Id"}],"responses":{"204":{"description":"","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"default":{"description":"Error (problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"summary":"Delete a QR code","tags":["QR codes"],"x-required-scopes":["qr:write"],"description":"Requires the scope `qr:write`."}},"/v1/qr-codes/{id}/image":{"get":{"operationId":"QrCodes_image","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"format","required":false,"in":"query","schema":{"default":"png","type":"string","enum":["png","svg"]}},{"name":"size","required":false,"in":"query","description":"Square size in pixels (PNG). SVG scales freely, so size only sets its viewBox.","schema":{"minimum":100,"maximum":2000,"default":600,"type":"integer"}},{"$ref":"#/components/parameters/X-Request-Id"},{"$ref":"#/components/parameters/If-None-Match"}],"responses":{"200":{"description":"Success","content":{"image/png":{"schema":{"type":"string","format":"binary"}},"image/svg+xml":{"schema":{"type":"string","format":"binary"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"ETag":{"$ref":"#/components/headers/ETag"},"X-QR-Logo":{"$ref":"#/components/headers/X-QR-Logo"}}},"304":{"description":"Not modified: the image matches If-None-Match"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"default":{"description":"Error (problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"summary":"Get the styled QR image (PNG or SVG)","tags":["QR codes"],"x-required-scopes":["images:read"],"description":"Requires the scope `images:read`."}},"/v1/domains":{"get":{"operationId":"Reference_domains","parameters":[{"$ref":"#/components/parameters/X-Request-Id"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ReferenceItem"}}}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"default":{"description":"Error (problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"summary":"List verified custom domains","tags":["Reference data"],"x-required-scopes":["qr:read"],"description":"Requires the scope `qr:read`."}},"/v1/departments":{"get":{"operationId":"Reference_departments","parameters":[{"$ref":"#/components/parameters/X-Request-Id"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ReferenceItem"}}}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"default":{"description":"Error (problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"summary":"List departments visible to this key","tags":["Reference data"],"x-required-scopes":["qr:read"],"description":"Requires the scope `qr:read`."}},"/v1/groups":{"get":{"operationId":"Reference_groups","parameters":[{"$ref":"#/components/parameters/X-Request-Id"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ReferenceItem"}}}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"default":{"description":"Error (problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"summary":"List QR code groups","tags":["Reference data"],"x-required-scopes":["qr:read"],"description":"Requires the scope `qr:read`."}},"/v1/assets":{"get":{"operationId":"Reference_assets","parameters":[{"$ref":"#/components/parameters/X-Request-Id"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ReferenceItem"}}}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"default":{"description":"Error (problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"summary":"List logo assets uploaded in the dashboard","tags":["Reference data"],"x-required-scopes":["qr:read"],"description":"Requires the scope `qr:read`."}},"/v1/gs1/links":{"post":{"operationId":"Gs1_issue","parameters":[{"$ref":"#/components/parameters/X-Request-Id"},{"$ref":"#/components/parameters/Idempotency-Key"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssueGs1LinksV1Dto"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Gs1IssueResult"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/IdempotencyKeyReuse"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"default":{"description":"Error (problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"summary":"Issue serialized GS1 Digital Links (up to 1,000)","tags":["GS1 Digital Link"],"x-required-scopes":["gs1:write"],"description":"Requires the scope `gs1:write`."}},"/v1/gs1/links/register":{"post":{"operationId":"Gs1_register","parameters":[{"$ref":"#/components/parameters/X-Request-Id"},{"$ref":"#/components/parameters/Idempotency-Key"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterGs1LinksV1Dto"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Gs1RegisterResult"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/IdempotencyKeyReuse"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"default":{"description":"Error (problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"summary":"Register Digital Links created in your system (up to 1,000)","tags":["GS1 Digital Link"],"x-required-scopes":["gs1:write"],"description":"Requires the scope `gs1:write`."}},"/v1/gs1/serials":{"get":{"operationId":"Gs1_list","parameters":[{"name":"limit","required":false,"in":"query","description":"Items per page","schema":{"minimum":1,"maximum":100,"default":25,"type":"integer"}},{"name":"cursor","required":false,"in":"query","description":"Opaque cursor from the previous page (nextCursor), passed back unchanged. A malformed cursor is refused with 400 invalid-cursor.","schema":{"maxLength":512,"type":"string"}},{"name":"gtin","required":false,"in":"query","schema":{"pattern":"^\\d{14}$","type":"string"}},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["active","recalled","void"]}},{"$ref":"#/components/parameters/X-Request-Id"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Serial"}},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"default":{"description":"Error (problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"summary":"List serials","tags":["GS1 Digital Link"],"x-required-scopes":["gs1:read"],"description":"Requires the scope `gs1:read`."}},"/v1/gs1/serials/{gtin}/{serial}":{"get":{"operationId":"Gs1_get","parameters":[{"name":"gtin","required":true,"in":"path","schema":{"type":"string"}},{"name":"serial","required":true,"in":"path","schema":{"type":"string"}},{"$ref":"#/components/parameters/X-Request-Id"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Serial"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"default":{"description":"Error (problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"summary":"Get a serial","tags":["GS1 Digital Link"],"x-required-scopes":["gs1:read"],"description":"Requires the scope `gs1:read`.\n\nPath: the GTIN as 14 digits and the serial percent-encoded (a / in a serial is %2F)."},"patch":{"operationId":"Gs1_update","parameters":[{"name":"gtin","required":true,"in":"path","schema":{"type":"string"}},{"name":"serial","required":true,"in":"path","schema":{"type":"string"}},{"$ref":"#/components/parameters/X-Request-Id"},{"$ref":"#/components/parameters/X-Change-Note"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSerialV1Dto"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Serial"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"429":{"$ref":"#/components/responses/TooManyRequests"},"default":{"description":"Error (problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"summary":"Recall, void or re-activate a serial, or replace its metadata","tags":["GS1 Digital Link"],"x-required-scopes":["gs1:write"],"description":"Requires the scope `gs1:write`.\n\nRe-activating a recalled or void serial uses an active code again, so it can be refused with 402."}},"/v1/gs1/serials/{gtin}/{serial}/image":{"get":{"operationId":"Gs1_image","parameters":[{"name":"gtin","required":true,"in":"path","schema":{"type":"string"}},{"name":"serial","required":true,"in":"path","schema":{"type":"string"}},{"name":"format","required":false,"in":"query","schema":{"default":"png","type":"string","enum":["png","svg"]}},{"name":"size","required":false,"in":"query","description":"Square size in pixels (PNG). SVG scales freely, so size only sets its viewBox.","schema":{"minimum":100,"maximum":2000,"default":600,"type":"integer"}},{"$ref":"#/components/parameters/X-Request-Id"},{"$ref":"#/components/parameters/If-None-Match"}],"responses":{"200":{"description":"Success","content":{"image/png":{"schema":{"type":"string","format":"binary"}},"image/svg+xml":{"schema":{"type":"string","format":"binary"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"ETag":{"$ref":"#/components/headers/ETag"},"X-QR-Logo":{"$ref":"#/components/headers/X-QR-Logo"}}},"304":{"description":"Not modified: the image matches If-None-Match"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"default":{"description":"Error (problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"summary":"Get the QR image for a serial","tags":["GS1 Digital Link"],"x-required-scopes":["images:read"],"description":"Requires the scope `images:read`."}},"/v1/gs1/links/jobs":{"post":{"operationId":"Jobs_issueJob","parameters":[{"$ref":"#/components/parameters/X-Request-Id"},{"$ref":"#/components/parameters/Idempotency-Key"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssueGs1LinksJobV1Dto"}}}},"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"links":{"GetJob":{"operationId":"Jobs_get","parameters":{"id":"$response.body#/id"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/IdempotencyKeyReuse"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"default":{"description":"Error (problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"summary":"Issue Digital Links asynchronously (up to 100,000)","tags":["Jobs"],"x-required-scopes":["gs1:write"],"description":"Requires the scope `gs1:write`."}},"/v1/gs1/links/register/jobs":{"post":{"operationId":"Jobs_registerJob","parameters":[{"$ref":"#/components/parameters/X-Request-Id"},{"$ref":"#/components/parameters/Idempotency-Key"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterGs1LinksJobV1Dto"}}}},"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"links":{"GetJob":{"operationId":"Jobs_get","parameters":{"id":"$response.body#/id"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/IdempotencyKeyReuse"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"default":{"description":"Error (problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"summary":"Register links asynchronously (up to 100,000)","tags":["Jobs"],"x-required-scopes":["gs1:write"],"description":"Requires the scope `gs1:write`."}},"/v1/images/jobs":{"post":{"operationId":"Jobs_imagesJob","parameters":[{"$ref":"#/components/parameters/X-Request-Id"},{"$ref":"#/components/parameters/Idempotency-Key"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImagesJobV1Dto"}}}},"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"links":{"GetJob":{"operationId":"Jobs_get","parameters":{"id":"$response.body#/id"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/IdempotencyKeyReuse"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"default":{"description":"Error (problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"summary":"Export QR images as a ZIP (up to 1,000 codes)","tags":["Jobs"],"x-required-scopes":["images:read"],"description":"Requires the scope `images:read`."}},"/v1/items/jobs/import":{"post":{"description":"Creates or updates Barcode Manager items, matched by sku, then gtin, then manufacturer and item number. Not all or nothing: valid rows are saved, rows with errors are skipped, and once the item limit is reached rows that would add a unit are notProcessed while updates go on. The results are JSON Lines, one line per row: row, status (created, updated, unchanged, skipped or notProcessed), id, sku, gtin and errors (a rule error has a pointer into the job body, such as /items/3/gtin). Rows with gtin \"assign\" get numbers in row order while the prefix has them; the rest are skipped with PREFIX_FULL. The job summary counts each status and gives the batchId.\n\nRequires the scope `items:write`.","operationId":"Jobs_itemImportJob","parameters":[{"$ref":"#/components/parameters/X-Request-Id"},{"$ref":"#/components/parameters/Idempotency-Key"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemImportJobV1Dto"}}}},"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"links":{"GetJob":{"operationId":"Jobs_get","parameters":{"id":"$response.body#/id"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/IdempotencyKeyReuse"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"default":{"description":"Error (problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"summary":"Import items asynchronously (up to 10,000)","tags":["Jobs"],"x-required-scopes":["items:write"]}},"/v1/items/jobs/export":{"post":{"description":"A ZIP of files plus a spec sheet, an A4 label-sheet PDF, or a spec-sheet PDF. A ZIP or label sheet releases its items (a DRAFT becomes LIVE and its GTIN locks), so when any requested item is a DRAFT it also needs items:write; without it the request, or the job when it runs, is refused with the forbidden problem type and reason draft-release-needs-items-write. A spec sheet releases nothing and needs barcodes:read only.\n\nRequires the scope `barcodes:read`.","operationId":"Jobs_barcodeExportJob","parameters":[{"$ref":"#/components/parameters/X-Request-Id"},{"$ref":"#/components/parameters/Idempotency-Key"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BarcodeExportJobV1Dto"}}}},"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"links":{"GetJob":{"operationId":"Jobs_get","parameters":{"id":"$response.body#/id"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/IdempotencyKeyReuse"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"default":{"description":"Error (problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"summary":"Export barcode files asynchronously (up to 2,000 items)","tags":["Jobs"],"x-required-scopes":["barcodes:read"]}},"/v1/jobs":{"get":{"description":"The jobs this key submitted, newest first.\n\nRequires the scope `jobs:read`.","operationId":"Jobs_list","parameters":[{"name":"limit","required":false,"in":"query","description":"Items per page","schema":{"minimum":1,"maximum":100,"default":25,"type":"integer"}},{"name":"cursor","required":false,"in":"query","description":"Opaque cursor from the previous page (nextCursor), passed back unchanged. A malformed cursor is refused with 400 invalid-cursor.","schema":{"maxLength":512,"type":"string"}},{"name":"status","required":false,"in":"query","description":"Only jobs with this status","schema":{"type":"string","enum":["queued","running","succeeded","failed"]}},{"$ref":"#/components/parameters/X-Request-Id"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Job"}},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"links":{"GetJob":{"operationId":"Jobs_get","parameters":{"id":"$response.body#/data/0/id"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"default":{"description":"Error (problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"summary":"List jobs","tags":["Jobs"],"x-required-scopes":["jobs:read"]}},"/v1/jobs/{id}":{"get":{"description":"Poll until status is succeeded or failed. A job whose worker stopped mid-run (a crash or restart) is failed after 15 minutes without a heartbeat, with error type worker-lost and a job.failed webhook; a slow job that is still running is never failed this way. Results and the job input are deleted after their retention (see the results download); the job stays listed.\n\nRequires the scope `jobs:read`.","operationId":"Jobs_get","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"$ref":"#/components/parameters/X-Request-Id"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"default":{"description":"Error (problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"summary":"Get a job","tags":["Jobs"],"x-required-scopes":["jobs:read"]}},"/v1/jobs/{id}/results":{"get":{"operationId":"Jobs_results","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"format","required":false,"in":"query","description":"GS1 jobs: csv (default) or jsonl. Ignored for other job types: image and barcode export jobs return a file, item import jobs always JSON Lines.","schema":{"type":"string","enum":["csv","jsonl"]}},{"$ref":"#/components/parameters/X-Request-Id"}],"responses":{"200":{"description":"Success","content":{"text/csv":{"schema":{"type":"string"}},"application/x-ndjson":{"schema":{"type":"string"}},"application/zip":{"schema":{"type":"string","format":"binary"}},"application/pdf":{"schema":{"type":"string","format":"binary"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"default":{"description":"Error (problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"summary":"Download job results (CSV, JSONL or ZIP)","tags":["Jobs"],"x-required-scopes":["jobs:read"],"description":"Requires the scope `jobs:read`.\n\nDownloading results also needs gs1:read (GS1 jobs), images:read (image jobs), barcodes:read (barcode export jobs) or items:read (item import jobs). Item import results are one JSON line per input row (row, status, id, sku, gtin, errors) whatever the format. Results are kept for 7 days (barcode export artwork for 24 hours), then deleted: the download is 404 and resultsUrl becomes null; the job itself stays listed."}},"/v1/presets":{"get":{"description":"The Design Studio presets of the admin who created this API key, newest first. Presets belong to a user, so a key sees its creator's presets.\n\nRequires the scope `qr:read`.","operationId":"Presets_list","parameters":[{"name":"limit","required":false,"in":"query","description":"Items per page","schema":{"minimum":1,"maximum":100,"default":25,"type":"integer"}},{"name":"cursor","required":false,"in":"query","description":"Opaque cursor from the previous page (nextCursor), passed back unchanged. A malformed cursor is refused with 400 invalid-cursor.","schema":{"maxLength":512,"type":"string"}},{"$ref":"#/components/parameters/X-Request-Id"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Preset"}},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"links":{"GetPreset":{"operationId":"Presets_get","parameters":{"id":"$response.body#/data/0/id"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"default":{"description":"Error (problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"summary":"List design presets","tags":["Design presets"],"x-required-scopes":["qr:read"]}},"/v1/presets/{id}":{"get":{"operationId":"Presets_get","parameters":[{"name":"id","required":true,"in":"path","description":"Preset id","schema":{"type":"string"}},{"$ref":"#/components/parameters/X-Request-Id"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Preset"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"default":{"description":"Error (problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"summary":"Get a design preset","tags":["Design presets"],"x-required-scopes":["qr:read"],"description":"Requires the scope `qr:read`."}},"/v1/items":{"get":{"description":"Newest first. Filter by sku, gtin, status, kind, category or updatedSince (for sync). Deleted items do not appear: only Drafts can be deleted (in the dashboard, or by undoing a save or import), and their numbers were never printed. Discontinued items stay listed with status DISCONTINUED.\n\nRequires the scope `items:read`.","operationId":"Items_list","parameters":[{"name":"limit","required":false,"in":"query","description":"Items per page","schema":{"minimum":1,"maximum":100,"default":25,"type":"integer"}},{"name":"cursor","required":false,"in":"query","description":"Opaque cursor from the previous page (nextCursor), passed back unchanged. A malformed cursor is refused with 400 invalid-cursor.","schema":{"maxLength":512,"type":"string"}},{"name":"sku","required":false,"in":"query","schema":{"minLength":1,"maxLength":64,"type":"string"}},{"name":"gtin","required":false,"in":"query","description":"Any GTIN length","schema":{"minLength":1,"maxLength":32,"type":"string"}},{"name":"status","required":false,"in":"query","description":"Default: every status","schema":{"type":"string","enum":["DRAFT","LIVE","DISCONTINUED"]}},{"name":"kind","required":false,"in":"query","schema":{"type":"string","enum":["GTIN_ITEM","INTERNAL"]}},{"name":"category","required":false,"in":"query","schema":{"minLength":1,"maxLength":80,"type":"string"}},{"name":"updatedSince","required":false,"in":"query","description":"Only items changed at or after this instant, for incremental sync. An RFC 3339 date-time with a time zone, e.g. 2026-11-01T00:00:00Z, as for QR codes.","schema":{"format":"date-time","type":"string"}},{"$ref":"#/components/parameters/X-Request-Id"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Item"}},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"links":{"GetItem":{"operationId":"Items_get","parameters":{"id":"$response.body#/data/0/id"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"default":{"description":"Error (problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"summary":"List items","tags":["Items (Barcode Manager)"],"x-required-scopes":["items:read"]},"post":{"description":"New items are DRAFT. Send gtin \"assign\" to take the lowest free GTIN from a declared prefix (prefix chooses it); with no prefix declared the answer is 409 conflict with code NO_PREFIX, and with a full prefix code PREFIX_FULL. Rule violations are 400 validation-error with field, code and severity in errors.\n\nRequires the scope `items:write`.\n\nOnly units count toward the plan item limit (packs and cases are free); past it the answer is 403 forbidden with reason item-limit-exceeded and the shortfall.","operationId":"Items_create","parameters":[{"$ref":"#/components/parameters/X-Request-Id"},{"$ref":"#/components/parameters/Idempotency-Key"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateItemV1Dto"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Item"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"links":{"GetItem":{"operationId":"Items_get","parameters":{"id":"$response.body#/id"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/IdempotencyKeyReuse"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"default":{"description":"Error (problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"summary":"Create an item","tags":["Items (Barcode Manager)"],"x-required-scopes":["items:write"]}},"/v1/items/by-sku/{sku}":{"get":{"operationId":"Items_getBySku","parameters":[{"name":"sku","required":true,"in":"path","description":"The SKU, percent-encoded; 1 to 64 characters, matched as stored (trimmed)","schema":{"type":"string"}},{"$ref":"#/components/parameters/X-Request-Id"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Item"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"default":{"description":"Error (problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"summary":"Get an item by SKU","tags":["Items (Barcode Manager)"],"x-required-scopes":["items:read"],"description":"Requires the scope `items:read`."},"put":{"description":"Creates the item when no item has this SKU (201; name is then required), otherwise updates the fields sent, like PATCH (200). A sku in the body must match the path. The ERP sync path.\n\nRequires the scope `items:write`.\n\nNot covered by Idempotency-Key: resending the same values changes nothing, not even updatedAt.","operationId":"Items_upsertBySku","parameters":[{"name":"sku","required":true,"in":"path","description":"The SKU, percent-encoded; 1 to 64 characters, matched as stored (trimmed)","schema":{"type":"string"}},{"$ref":"#/components/parameters/X-Request-Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemFieldsV1Dto"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Item"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}}},"201":{"description":"Created: no item had this SKU","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Item"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"429":{"$ref":"#/components/responses/TooManyRequests"},"default":{"description":"Error (problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"summary":"Create or update an item by SKU","tags":["Items (Barcode Manager)"],"x-required-scopes":["items:write"]}},"/v1/items/{id}":{"get":{"operationId":"Items_get","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"$ref":"#/components/parameters/X-Request-Id"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Item"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"default":{"description":"Error (problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"summary":"Get an item","tags":["Items (Barcode Manager)"],"x-required-scopes":["items:read"],"description":"Requires the scope `items:read`."},"patch":{"description":"Absent fields are left as they are; null clears a field. The GTIN of a LIVE or DISCONTINUED item, or of one with a Digital Link, is locked (validation-error code gtinLocked): change it with change-number. gtin \"assign\" gives a number only to an item without one.\n\nRequires the scope `items:write`.","operationId":"Items_update","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"$ref":"#/components/parameters/X-Request-Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemFieldsV1Dto"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Item"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"429":{"$ref":"#/components/responses/TooManyRequests"},"default":{"description":"Error (problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"summary":"Update an item","tags":["Items (Barcode Manager)"],"x-required-scopes":["items:write"]}},"/v1/items/{id}/release":{"post":{"description":"DRAFT becomes LIVE and its GTIN locks. Downloading or exporting its barcode does this too. An item that is not a DRAFT is returned unchanged.\n\nRequires the scope `items:write`.","operationId":"Items_release","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"$ref":"#/components/parameters/X-Request-Id"},{"$ref":"#/components/parameters/Idempotency-Key"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Item"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/IdempotencyKeyReuse"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"default":{"description":"Error (problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"summary":"Mark an item as released (Live)","tags":["Items (Barcode Manager)"],"x-required-scopes":["items:write"]}},"/v1/items/{id}/discontinue":{"post":{"description":"A DRAFT or LIVE item becomes DISCONTINUED. It stays listed and downloadable, a unit frees its place in the plan item limit, and its GTIN is never handed out again. A discontinued item is returned unchanged.\n\nRequires the scope `items:write`.","operationId":"Items_discontinue","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"$ref":"#/components/parameters/X-Request-Id"},{"$ref":"#/components/parameters/Idempotency-Key"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Item"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/IdempotencyKeyReuse"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"default":{"description":"Error (problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"summary":"Discontinue an item","tags":["Items (Barcode Manager)"],"x-required-scopes":["items:write"]}},"/v1/items/{id}/reactivate":{"post":{"description":"Back to LIVE if the item was ever released, otherwise to DRAFT. An item that is not discontinued is returned unchanged.\n\nRequires the scope `items:write`.\n\nA reactivated unit needs a free place in the item limit (403 forbidden, reason item-limit-exceeded).","operationId":"Items_reactivate","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"$ref":"#/components/parameters/X-Request-Id"},{"$ref":"#/components/parameters/Idempotency-Key"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Item"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/IdempotencyKeyReuse"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"default":{"description":"Error (problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"summary":"Reactivate a discontinued item","tags":["Items (Barcode Manager)"],"x-required-scopes":["items:write"]}},"/v1/items/{id}/change-number":{"post":{"description":"The way to change a locked GTIN. Requires confirm: true (the JSON boolean); without it, or with false or a string, the answer is 400 validation-error at /confirm. The new number is checked like any GTIN (400 validation-error). For a LIVE or DISCONTINUED item the old number is retired and never assigned again. Refused with 409 conflict and code HAS_DIGITAL_LINK while the item has a Digital Link, and with 400 bad-request for an internal item or the current number.\n\nRequires the scope `items:write`.","operationId":"Items_changeNumber","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"$ref":"#/components/parameters/X-Request-Id"},{"$ref":"#/components/parameters/Idempotency-Key"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeNumberV1Dto"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Item"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/IdempotencyKeyReuse"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"default":{"description":"Error (problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"summary":"Change the GTIN of an item","tags":["Items (Barcode Manager)"],"x-required-scopes":["items:write"]}},"/v1/items/{id}/barcode":{"post":{"description":"Print-sized to GS1 specifications, returned as an attachment. Without magnification or digits, the item print settings from the dashboard apply (100% with digits when it has none). Artwork leaving QRbolt releases the item: a DRAFT becomes LIVE and its GTIN locks. barcodes:read is enough for LIVE and DISCONTINUED items; a DRAFT also needs items:write, and without it the request is refused with the forbidden problem type and reason draft-release-needs-items-write.\n\nRequires the scope `barcodes:read`.\n\nIdempotency-Key is accepted but holds nothing: the file is never kept, and the key is released when the file is sent, so a retry with the same key renders the file again (releasing a Draft twice changes nothing). A duplicate sent while the first is still rendering gets idempotency-in-progress. On a plan without Barcode Manager (read-only after a downgrade) a DRAFT is refused with reason read-only-plan.","operationId":"Items_barcode","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"format","required":false,"in":"query","schema":{"default":"svg","type":"string","enum":["svg","png","pdf"]}},{"name":"magnification","required":false,"in":"query","description":"GS1 magnification (0.8 to 2.0). Default: the item print settings, else 1","schema":{"minimum":0.8,"maximum":2,"default":1,"type":"number"}},{"name":"digits","required":false,"in":"query","description":"Human-readable digits. Default: the item print settings, else true","schema":{"default":"true","type":"string","enum":["true","false"]}},{"name":"dpi","required":false,"in":"query","description":"PNG resolution","schema":{"default":300,"type":"number","enum":[300,600]}},{"$ref":"#/components/parameters/X-Request-Id"},{"$ref":"#/components/parameters/Idempotency-Key"}],"responses":{"200":{"description":"Success","content":{"image/svg+xml":{"schema":{"type":"string","format":"binary"}},"image/png":{"schema":{"type":"string","format":"binary"}},"application/pdf":{"schema":{"type":"string","format":"binary"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/IdempotencyKeyReuse"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"default":{"description":"Error (problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"summary":"Get the barcode file (SVG, PNG or PDF)","tags":["Items (Barcode Manager)"],"x-required-scopes":["barcodes:read"]}},"/v1/prefixes":{"get":{"description":"Prefixes are declared by an admin in the dashboard. Not paginated: every prefix is listed. capacity is 10^(12 - L) for a Company Prefix of L digits and 1 for a single GTIN.\n\nRequires the scope `items:read`.\n\nremaining is an upper bound for gtin \"assign\", which also skips retired numbers and numbers being assigned in the dashboard.","operationId":"Items_prefixes","parameters":[{"$ref":"#/components/parameters/X-Request-Id"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Prefix"}}}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"default":{"description":"Error (problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"summary":"List declared GS1 prefixes with remaining capacity","tags":["Items (Barcode Manager)"],"x-required-scopes":["items:read"]}}},"info":{"title":"QRbolt API","description":"Create and manage QR codes, serialized GS1 Digital Links and Barcode Manager items with their 1D barcodes. Authenticate with an API key from the dashboard (Settings > API) as `Authorization: Bearer qrb_live_...`. Errors are RFC 9457 `application/problem+json`; branch on `type`, and on `reason` where a problem has one. POST requests accept an `Idempotency-Key` header. Each operation lists the API key scopes it needs in `x-required-scopes`.\n\nRate limits apply per API key and per account and depend on the plan. Every authenticated response carries `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` and `RateLimit-Policy`; over the limit you get `429` with `Retry-After`. Honour Retry-After and retry with exponential backoff and jitter. Contact us if you need more capacity.\n\nThe only server listed is production. Point test tools at another host explicitly.","version":"1.0.0","contact":{},"license":{"name":"Proprietary, QRbolt terms of service","url":"https://qrbolt.com/en/help/terms-and-conditions"}},"tags":[],"servers":[{"url":"https://api.qrbolt.com","description":"Production"}],"components":{"securitySchemes":{"apiKey":{"scheme":"bearer","bearerFormat":"API key","type":"http","description":"An API key from Settings > API: `qrb_live_` followed by 12 lowercase letters or digits, `_` and a 43-character secret. Keys starting with `qrb_test_` are refused."}},"schemas":{"CreateQrCodeV1Dto":{"type":"object","properties":{"name":{"type":"string","maxLength":255,"minLength":1},"customDomainId":{"type":"string","description":"A verified custom domain of the account (GET /v1/domains).","pattern":"^c[a-z0-9]{24}$"},"groupId":{"type":"string","description":"A group of the account (GET /v1/groups).","pattern":"^c[a-z0-9]{24}$"},"description":{"type":"string","maxLength":2000},"slug":{"type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_-]+$"},"showLandingPage":{"type":"boolean"},"departmentId":{"type":"string","nullable":true,"description":"The department that owns the code (GET /v1/departments). Omit it to use\nthe default: a department key's own department, otherwise the primary\n(or only) department of the key's creator, or none if they have no\ndepartment. Send null to leave the code unassigned and visible to the\nwhole organization; a department key cannot.","pattern":"^c[a-z0-9]{24}$"},"isPasswordProtected":{"type":"boolean"},"password":{"type":"string","minLength":6,"maxLength":128},"isSuspended":{"type":"boolean"},"type":{"description":"URL (default), PHONE, WIFI or VCARD. Time-based codes have their own endpoint.","enum":["URL","PHONE","WIFI","VCARD","TIME_BASED"],"type":"string"},"destinationUrl":{"type":"string","maxLength":2048},"ssid":{"type":"string","maxLength":32},"security":{"description":"WIFI codes: the network's security type.","enum":["WPA","WEP","nopass"],"type":"string"},"hidden":{"type":"boolean","description":"WIFI codes: whether the network is hidden."},"vcardFirstName":{"type":"string","maxLength":255},"vcardLastName":{"type":"string","maxLength":255},"vcardFullName":{"type":"string","maxLength":255},"vcardOrganization":{"type":"string","maxLength":255},"vcardTitle":{"type":"string","maxLength":255},"vcardEmail":{"type":"string","maxLength":254,"format":"email"},"vcardPhone":{"type":"string","maxLength":255},"vcardMobile":{"type":"string","maxLength":255},"vcardWorkPhone":{"type":"string","maxLength":255},"vcardFax":{"type":"string","maxLength":255},"vcardWebsite":{"type":"string","maxLength":2048,"format":"uri"},"vcardAddress":{"type":"string","maxLength":500},"vcardCity":{"type":"string","maxLength":255},"vcardState":{"type":"string","maxLength":255},"vcardPostalCode":{"type":"string","maxLength":255},"vcardCountry":{"type":"string","maxLength":255},"vcardNote":{"type":"string","maxLength":2000},"logoAssetId":{"type":"string","maxLength":64},"designOptions":{"type":"object","additionalProperties":true},"presetId":{"type":"string","description":"Apply a design preset saved in the dashboard (GET /v1/presets). The preset fills designOptions and logoAssetId where the request leaves them out; values sent in the request win. An id the key cannot see is a validation error on /presetId.","example":"cm3x1y2z3a4b5c6d7e8f9g0h1"}},"required":["name"],"additionalProperties":false},"TimeBasedRuleDto":{"type":"object","properties":{"url":{"type":"string","maxLength":2048,"format":"uri"},"startAt":{"type":"string","description":"When the rule starts: an ISO 8601 date-time. With Z or an offset it is\nthat instant; without one (2026-11-02T08:00) it is the wall-clock time in\nthe code's timezone.","maxLength":64},"endAt":{"type":"string","maxLength":64}},"required":["url","startAt"],"additionalProperties":false},"CreateTimeBasedQrCodeV1Dto":{"type":"object","properties":{"name":{"type":"string","maxLength":255,"minLength":1},"timezone":{"type":"string","description":"An IANA time zone name, such as Europe/Zagreb. An unknown name is refused with 409.","maxLength":64,"minLength":1},"customDomainId":{"type":"string","description":"A verified custom domain of the account (GET /v1/domains).","pattern":"^c[a-z0-9]{24}$"},"groupId":{"type":"string","description":"A group of the account (GET /v1/groups).","pattern":"^c[a-z0-9]{24}$"},"description":{"type":"string","maxLength":2000},"slug":{"type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_-]+$"},"showLandingPage":{"type":"boolean"},"departmentId":{"type":"string","nullable":true,"description":"The department that owns the code (GET /v1/departments). Omit it to use\nthe default: a department key's own department, otherwise the primary\n(or only) department of the key's creator, or none if they have no\ndepartment. Send null to leave the code unassigned and visible to the\nwhole organization; a department key cannot.","pattern":"^c[a-z0-9]{24}$"},"isPasswordProtected":{"type":"boolean"},"password":{"type":"string","description":"Password that protects the landing page (isPasswordProtected).","minLength":6,"maxLength":128},"isSuspended":{"type":"boolean"},"defaultUrl":{"type":"string","description":"Where scans go when no rule is active.","maxLength":2048,"format":"uri"},"rules":{"minItems":1,"maxItems":24,"type":"array","items":{"$ref":"#/components/schemas/TimeBasedRuleDto"}},"presetId":{"type":"string","description":"Apply a design preset saved in the dashboard (GET /v1/presets). The preset fills designOptions and logoAssetId where the request leaves them out; values sent in the request win. An id the key cannot see is a validation error on /presetId.","example":"cm3x1y2z3a4b5c6d7e8f9g0h1"}},"required":["name","timezone","defaultUrl","rules"],"additionalProperties":false},"UpdateQrCodeV1Dto":{"type":"object","properties":{"name":{"type":"string","maxLength":255,"minLength":1},"destinationUrl":{"type":"string","maxLength":2048},"description":{"type":"string","maxLength":2000},"ssid":{"type":"string","maxLength":32},"security":{"description":"WIFI codes: the network's security type.","enum":["WPA","WEP","nopass"],"type":"string"},"hidden":{"type":"boolean","description":"WIFI codes: whether the network is hidden."},"showLandingPage":{"type":"boolean"},"departmentId":{"type":"string","nullable":true,"description":"Move the code to this department (GET /v1/departments), or send null to make it unassigned and visible to the whole organization. Omit it to leave the department unchanged. A department key cannot move a code out of its department.","pattern":"^c[a-z0-9]{24}$"},"isPasswordProtected":{"type":"boolean"},"password":{"type":"string","minLength":6,"maxLength":128},"isSuspended":{"type":"boolean"},"defaultUrl":{"type":"string","maxLength":2048,"format":"uri"},"timezone":{"type":"string","maxLength":64},"timeBasedRules":{"minItems":1,"maxItems":24,"type":"array","items":{"$ref":"#/components/schemas/TimeBasedRuleDto"}},"vcardFirstName":{"type":"string","maxLength":255},"vcardLastName":{"type":"string","maxLength":255},"vcardFullName":{"type":"string","maxLength":255},"vcardOrganization":{"type":"string","maxLength":255},"vcardTitle":{"type":"string","maxLength":255},"vcardEmail":{"type":"string","maxLength":254,"format":"email"},"vcardPhone":{"type":"string","maxLength":255},"vcardMobile":{"type":"string","maxLength":255},"vcardWorkPhone":{"type":"string","maxLength":255},"vcardFax":{"type":"string","maxLength":255},"vcardWebsite":{"type":"string","maxLength":2048,"format":"uri"},"vcardAddress":{"type":"string","maxLength":500},"vcardCity":{"type":"string","maxLength":255},"vcardState":{"type":"string","maxLength":255},"vcardPostalCode":{"type":"string","maxLength":255},"vcardCountry":{"type":"string","maxLength":255},"vcardNote":{"type":"string","maxLength":2000},"customDomainId":{"type":"string","nullable":true},"slug":{"type":"string","nullable":true,"maxLength":100,"pattern":"^[a-zA-Z0-9_-]+$"},"groupId":{"type":"string","nullable":true,"pattern":"^c[a-z0-9]{24}$"},"logoAssetId":{"type":"string","nullable":true,"maxLength":64},"designOptions":{"type":"object","additionalProperties":true,"nullable":true}},"additionalProperties":false},"GenerateSerialsV1Dto":{"type":"object","properties":{"count":{"type":"integer","minimum":1,"maximum":1000},"length":{"type":"integer","description":"Characters per serial (A-Z, 0-9). 12 gives ~62 bits of randomness.","minimum":8,"maximum":20,"default":12}},"required":["count"],"additionalProperties":false},"Gs1ProductV1Dto":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"destinationUrl":{"type":"string","maxLength":2048,"format":"uri","pattern":"^[Hh][Tt][Tt][Pp][Ss]?://"},"description":{"type":"string","maxLength":1000},"showLandingPage":{"type":"boolean"},"designOptions":{"type":"object","additionalProperties":true},"logoAssetId":{"type":"string","description":"A logo asset uploaded in the dashboard (GET /v1/assets).","maxLength":64},"departmentId":{"type":"string","nullable":true,"pattern":"^c[a-z0-9]{24}$"},"groupId":{"type":"string","pattern":"^c[a-z0-9]{24}$"}},"required":["name","destinationUrl"],"additionalProperties":false},"IssueGs1LinksV1Dto":{"type":"object","properties":{"serials":{"description":"Customer serials (AI 21), the usual case. Provide these or `generate`, not both.","minItems":1,"maxItems":1000,"uniqueItems":true,"type":"array","items":{"type":"string","maxLength":20,"minLength":1}},"generate":{"$ref":"#/components/schemas/GenerateSerialsV1Dto"},"gtin":{"type":"string","description":"UPC-A (12), EAN-8, EAN-13 or GTIN-14 digits; the check digit must be right.","pattern":"^\\d{8}$|^\\d{12,14}$"},"batch":{"type":"string","description":"AI 10 lot or batch.","minLength":1,"maxLength":20},"attributes":{"type":"object","additionalProperties":{"type":"string"},"description":"Further GS1 Application Identifiers for every link, as AI code to value,\ne.g. { \"17\": \"271231\" } (expiry YYMMDD). Each value is checked against its\nAI (dates must be real dates); unknown AIs and 01, 10 or 21 are refused."},"product":{"$ref":"#/components/schemas/Gs1ProductV1Dto"},"onExisting":{"type":"string","description":"What to do with serials already registered: fail the request with 409 (default) or skip them.","enum":["error","skip"]},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form traceability references stored with every serial in this request."}},"required":["gtin"],"additionalProperties":false},"RegisterGs1LinksV1Dto":{"type":"object","properties":{"links":{"type":"array","description":"Serialized GS1 Digital Links (with AI 21) on a verified domain of the account, https only.","minItems":1,"items":{"type":"string","maxLength":2048,"pattern":"^[Hh][Tt][Tt][Pp][Ss]://"},"maxItems":1000,"uniqueItems":true},"product":{"$ref":"#/components/schemas/Gs1ProductV1Dto"},"onExisting":{"type":"string","description":"What to do with serials already registered: fail the request with 409 (default) or skip them.","enum":["error","skip"]},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form traceability references stored with every serial in this request."}},"required":["links"],"additionalProperties":false},"UpdateSerialV1Dto":{"type":"object","properties":{"status":{"type":"string","enum":["active","recalled","void"]},"metadata":{"type":"object","additionalProperties":true}},"additionalProperties":false},"GenerateSerialsJobV1Dto":{"type":"object","properties":{"count":{"type":"integer","minimum":1,"maximum":100000},"length":{"type":"integer","description":"Characters per serial (A-Z, 0-9). 12 gives ~62 bits of randomness.","minimum":8,"maximum":20,"default":12}},"required":["count"],"additionalProperties":false},"IssueGs1LinksJobV1Dto":{"type":"object","properties":{"serials":{"description":"Customer serials (AI 21), the usual case. Provide these or `generate`, not both.","minItems":1,"maxItems":100000,"uniqueItems":true,"type":"array","items":{"type":"string","maxLength":20,"minLength":1}},"generate":{"$ref":"#/components/schemas/GenerateSerialsJobV1Dto"},"gtin":{"type":"string","description":"UPC-A (12), EAN-8, EAN-13 or GTIN-14 digits; the check digit must be right.","pattern":"^\\d{8}$|^\\d{12,14}$"},"batch":{"type":"string","description":"AI 10 lot or batch.","minLength":1,"maxLength":20},"attributes":{"type":"object","additionalProperties":{"type":"string"},"description":"Further GS1 Application Identifiers for every link, as AI code to value,\ne.g. { \"17\": \"271231\" } (expiry YYMMDD). Each value is checked against its\nAI (dates must be real dates); unknown AIs and 01, 10 or 21 are refused."},"product":{"$ref":"#/components/schemas/Gs1ProductV1Dto"},"onExisting":{"type":"string","description":"What to do with serials already registered: fail the request with 409 (default) or skip them.","enum":["error","skip"]},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form traceability references stored with every serial in this request."}},"required":["gtin"],"additionalProperties":false},"RegisterGs1LinksJobV1Dto":{"type":"object","properties":{"links":{"type":"array","description":"Serialized GS1 Digital Links (with AI 21) on a verified domain of the account, https only.","minItems":1,"items":{"type":"string","maxLength":2048,"pattern":"^[Hh][Tt][Tt][Pp][Ss]://"},"maxItems":100000,"uniqueItems":true},"product":{"$ref":"#/components/schemas/Gs1ProductV1Dto"},"onExisting":{"type":"string","description":"What to do with serials already registered: fail the request with 409 (default) or skip them.","enum":["error","skip"]},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form traceability references stored with every serial in this request."}},"required":["links"],"additionalProperties":false},"ImagesJobV1Dto":{"type":"object","properties":{"ids":{"minItems":1,"description":"QR code ids to render; duplicates are rendered once.","maxItems":1000,"type":"array","items":{"type":"string","pattern":"^c[a-z0-9]{24}$"}},"format":{"enum":["png","svg"],"type":"string","default":"png"},"size":{"type":"integer","minimum":100,"maximum":2000,"default":600,"description":"Square size in pixels of each image."}},"required":["ids"],"additionalProperties":false},"ImportItemV1Dto":{"type":"object","properties":{"name":{"type":"string","maxLength":200,"description":"Product or item name"},"description":{"type":"string","nullable":true,"maxLength":2000,"description":"Free text"},"kind":{"enum":["GTIN_ITEM","INTERNAL"],"type":"string","description":"GTIN_ITEM carries a GTIN; INTERNAL is an internal code (Code 128 or Code 39) with no GTIN. Defaults from whether a gtin is given."},"gtin":{"type":"string","nullable":true,"maxLength":32,"description":"GTIN-8, -12, -13 or -14 with its check digit, or \"assign\" for the next free number from your GS1 Company Prefix (see prefix), also on update and in imports. A released (LIVE) item, or one a Digital Link carries, keeps its GTIN: change it with POST /items/{id}/change-number."},"prefix":{"type":"string","maxLength":14,"description":"With gtin \"assign\": the declared prefix to assign from (its digits). Defaults to the first declared Company Prefix, or the first single GTIN when there is none. A prefix that is not declared is refused (code unknownPrefix)."},"sku":{"type":"string","nullable":true,"maxLength":64,"description":"Your stock-keeping unit; unique in the account when set"},"manufacturerName":{"type":"string","nullable":true,"maxLength":120},"manufacturerItemNumber":{"type":"string","nullable":true,"maxLength":64,"description":"The maker or supplier item number; unique per manufacturer in the account"},"codeValue":{"type":"string","nullable":true,"maxLength":48,"description":"Barcode value of an internal item when it differs from its SKU. An internal item needs a codeValue or a sku."},"symbology":{"nullable":true,"enum":["EAN13","UPCA","UPCE","EAN8","ITF14","GS1_128","CODE128","CODE39"],"type":"string","description":"The barcode type to print, when it can carry the item (symbologyNotAllowed otherwise). Null derives it: GTIN-13 EAN13, GTIN-12 UPCA, a GTIN sent as 8 digits EAN8, a GTIN-14 with indicator 1 to 8 ITF14, internal items CODE128."},"category":{"type":"string","nullable":true,"maxLength":80},"parentId":{"type":"string","nullable":true,"maxLength":64,"description":"The unit (or pack) this packaging level belongs to, an item of your organization. null makes the item a UNIT again and clears packQuantity."},"level":{"enum":["UNIT","PACK","CASE"],"type":"string","description":"PACK or CASE under a parent; UNIT without one. A UNIT can have packs and cases below it, a PACK only cases. A parentId without a level makes a CASE."},"packQuantity":{"type":"integer","nullable":true,"minimum":1,"maximum":100000,"description":"Units in this pack or case; required when parentId is set"}},"additionalProperties":false},"ItemImportJobV1Dto":{"type":"object","properties":{"items":{"minItems":1,"description":"Items to create or update, matched to existing items by sku, then gtin, then manufacturer and item number (up to 10000)","type":"array","items":{"$ref":"#/components/schemas/ImportItemV1Dto"}}},"required":["items"],"additionalProperties":false},"BarcodeExportJobV1Dto":{"type":"object","properties":{"ids":{"minItems":1,"description":"Item ids (up to 2000). Each must be an item of your organization when you submit; items deleted before the job runs are left out.","type":"array","items":{"type":"string","maxLength":64}},"output":{"enum":["zip","labels","spec"],"type":"string","default":"zip","description":"zip: one file per item plus a spec sheet; labels: an A4 label-sheet PDF; spec: a spec-sheet PDF. zip and labels release the items, which for a DRAFT needs the items:write scope. Needs a plan with batch barcode export. The file is kept for 24 hours."},"format":{"enum":["svg","png","pdf"],"type":"string","default":"pdf","description":"File format inside a zip"},"dpi":{"type":"number","enum":[300,600],"default":300},"layout":{"type":"string","maxLength":20,"default":"a4-3x8","description":"Label layout for output labels: a4-3x8, a4-3x7, a4-4x10, a4-2x7 or custom-CxR (1 to 10 columns, 1 to 20 rows)"}},"required":["ids"],"additionalProperties":false},"ItemFieldsV1Dto":{"type":"object","properties":{"name":{"type":"string","maxLength":200,"description":"Product or item name"},"description":{"type":"string","nullable":true,"maxLength":2000,"description":"Free text"},"kind":{"enum":["GTIN_ITEM","INTERNAL"],"type":"string","description":"GTIN_ITEM carries a GTIN; INTERNAL is an internal code (Code 128 or Code 39) with no GTIN. Defaults from whether a gtin is given."},"gtin":{"type":"string","nullable":true,"maxLength":32,"description":"GTIN-8, -12, -13 or -14 with its check digit, or \"assign\" for the next free number from your GS1 Company Prefix (see prefix), also on update and in imports. A released (LIVE) item, or one a Digital Link carries, keeps its GTIN: change it with POST /items/{id}/change-number."},"prefix":{"type":"string","maxLength":14,"description":"With gtin \"assign\": the declared prefix to assign from (its digits). Defaults to the first declared Company Prefix, or the first single GTIN when there is none. A prefix that is not declared is refused (code unknownPrefix)."},"sku":{"type":"string","nullable":true,"maxLength":64,"description":"Your stock-keeping unit; unique in the account when set"},"manufacturerName":{"type":"string","nullable":true,"maxLength":120},"manufacturerItemNumber":{"type":"string","nullable":true,"maxLength":64,"description":"The maker or supplier item number; unique per manufacturer in the account"},"codeValue":{"type":"string","nullable":true,"maxLength":48,"description":"Barcode value of an internal item when it differs from its SKU. An internal item needs a codeValue or a sku."},"symbology":{"nullable":true,"enum":["EAN13","UPCA","UPCE","EAN8","ITF14","GS1_128","CODE128","CODE39"],"type":"string","description":"The barcode type to print, when it can carry the item (symbologyNotAllowed otherwise). Null derives it: GTIN-13 EAN13, GTIN-12 UPCA, a GTIN sent as 8 digits EAN8, a GTIN-14 with indicator 1 to 8 ITF14, internal items CODE128."},"category":{"type":"string","nullable":true,"maxLength":80},"parentId":{"type":"string","nullable":true,"maxLength":64,"description":"The unit (or pack) this packaging level belongs to, an item of your organization. null makes the item a UNIT again and clears packQuantity."},"level":{"enum":["UNIT","PACK","CASE"],"type":"string","description":"PACK or CASE under a parent; UNIT without one. A UNIT can have packs and cases below it, a PACK only cases. A parentId without a level makes a CASE."},"packQuantity":{"type":"integer","nullable":true,"minimum":1,"maximum":100000,"description":"Units in this pack or case; required when parentId is set"}},"additionalProperties":false},"CreateItemV1Dto":{"type":"object","properties":{"name":{"type":"string","maxLength":200,"description":"Product or item name"},"description":{"type":"string","nullable":true,"maxLength":2000,"description":"Free text"},"kind":{"enum":["GTIN_ITEM","INTERNAL"],"type":"string","description":"GTIN_ITEM carries a GTIN; INTERNAL is an internal code (Code 128 or Code 39) with no GTIN. Defaults from whether a gtin is given."},"gtin":{"type":"string","nullable":true,"maxLength":32,"description":"GTIN-8, -12, -13 or -14 with its check digit, or \"assign\" for the next free number from your GS1 Company Prefix (see prefix), also on update and in imports. A released (LIVE) item, or one a Digital Link carries, keeps its GTIN: change it with POST /items/{id}/change-number."},"prefix":{"type":"string","maxLength":14,"description":"With gtin \"assign\": the declared prefix to assign from (its digits). Defaults to the first declared Company Prefix, or the first single GTIN when there is none. A prefix that is not declared is refused (code unknownPrefix)."},"sku":{"type":"string","nullable":true,"maxLength":64,"description":"Your stock-keeping unit; unique in the account when set"},"manufacturerName":{"type":"string","nullable":true,"maxLength":120},"manufacturerItemNumber":{"type":"string","nullable":true,"maxLength":64,"description":"The maker or supplier item number; unique per manufacturer in the account"},"codeValue":{"type":"string","nullable":true,"maxLength":48,"description":"Barcode value of an internal item when it differs from its SKU. An internal item needs a codeValue or a sku."},"symbology":{"nullable":true,"enum":["EAN13","UPCA","UPCE","EAN8","ITF14","GS1_128","CODE128","CODE39"],"type":"string","description":"The barcode type to print, when it can carry the item (symbologyNotAllowed otherwise). Null derives it: GTIN-13 EAN13, GTIN-12 UPCA, a GTIN sent as 8 digits EAN8, a GTIN-14 with indicator 1 to 8 ITF14, internal items CODE128."},"category":{"type":"string","nullable":true,"maxLength":80},"parentId":{"type":"string","nullable":true,"maxLength":64,"description":"The unit (or pack) this packaging level belongs to, an item of your organization. null makes the item a UNIT again and clears packQuantity."},"level":{"enum":["UNIT","PACK","CASE"],"type":"string","description":"PACK or CASE under a parent; UNIT without one. A UNIT can have packs and cases below it, a PACK only cases. A parentId without a level makes a CASE."},"packQuantity":{"type":"integer","nullable":true,"minimum":1,"maximum":100000,"description":"Units in this pack or case; required when parentId is set"}},"additionalProperties":false},"ChangeNumberV1Dto":{"type":"object","properties":{"gtin":{"type":"string","maxLength":32,"description":"The new GTIN-8, -12, -13 or -14, with its check digit"},"confirm":{"type":"boolean","description":"Must be the JSON boolean true: anything already printed will scan as the old number. Missing, false or anything else is 400 validation-error at /confirm."}},"required":["gtin","confirm"],"additionalProperties":false},"QrCode":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["qr_code"]},"version":{"type":"integer","nullable":true,"description":"Current version of the code. Send it as If-Match (the ETag header carries it too) to make PATCH or DELETE conditional."},"type":{"type":"string","enum":["URL","PHONE","WIFI","VCARD","TIME_BASED","GS1_DIGITAL_LINK"]},"name":{"type":"string"},"description":{"type":"string","nullable":true},"url":{"type":"string","format":"uri","description":"The address encoded in the QR code","nullable":true},"shortCode":{"type":"string"},"destinationUrl":{"type":"string","description":"Where a scan goes: a URL, or the phone number of a PHONE code. Null for WIFI and VCARD.","nullable":true},"customDomainId":{"type":"string","nullable":true},"slug":{"type":"string","nullable":true},"departmentId":{"type":"string","nullable":true},"sku":{"type":"string","nullable":true},"landingPage":{"type":"object","properties":{"enabled":{"type":"boolean"}}},"security":{"type":"object","properties":{"passwordProtected":{"type":"boolean"},"suspended":{"type":"boolean"},"flaggedMalicious":{"type":"boolean","nullable":true}}},"design":{"type":"object","properties":{"designOptions":{"type":"object","nullable":true},"logoAssetId":{"type":"string","nullable":true}}},"wifi":{"type":"object","properties":{"ssid":{"type":"string","nullable":true},"security":{"type":"string","nullable":true},"hidden":{"type":"boolean"}}},"vcard":{"type":"object","additionalProperties":{"type":"string","nullable":true}},"timeBased":{"type":"object","properties":{"defaultUrl":{"type":"string"},"timezone":{"type":"string"},"rules":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"startAt":{"type":"string","format":"date-time"},"endAt":{"type":"string","format":"date-time","nullable":true}}}}}},"gs1":{"type":"object","properties":{"gtin":{"type":"string"},"attributes":{"type":"object","additionalProperties":{"type":"string"}},"status":{"type":"string","enum":["active","archived"]}}},"stats":{"type":"object","properties":{"totalScans":{"type":"integer"},"firstScannedAt":{"type":"string","format":"date-time","nullable":true},"lastScannedAt":{"type":"string","format":"date-time","nullable":true}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Serial":{"type":"object","properties":{"object":{"type":"string","enum":["gs1_serial"]},"gtin":{"type":"string"},"serial":{"type":"string"},"batch":{"type":"string","nullable":true},"status":{"type":"string","enum":["active","recalled","void"]},"source":{"type":"string","enum":["customer","generated"]},"productId":{"type":"string"},"metadata":{"type":"object","nullable":true},"stats":{"type":"object","properties":{"scanCount":{"type":"integer"},"firstScannedAt":{"type":"string","format":"date-time","nullable":true},"lastScannedAt":{"type":"string","format":"date-time","nullable":true}}},"statusChangedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"Gs1IssueResult":{"type":"object","properties":{"object":{"type":"string","enum":["gs1_issue_result"]},"product":{"$ref":"#/components/schemas/QrCode"},"productCreated":{"type":"boolean"},"issued":{"type":"array","items":{"type":"object","properties":{"serial":{"type":"string"},"uri":{"type":"string","format":"uri"},"source":{"type":"string","enum":["customer","generated"]}}}},"skipped":{"type":"array","items":{"type":"string"}}}},"Gs1RegisterResult":{"type":"object","properties":{"object":{"type":"string","enum":["gs1_register_result"]},"products":{"type":"array","items":{"$ref":"#/components/schemas/Gs1IssueResult"}}}},"Job":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["job"]},"type":{"type":"string","enum":["gs1_issue","gs1_register","images","barcode_export","item_import"]},"status":{"type":"string","enum":["queued","running","succeeded","failed"]},"progress":{"type":"object","properties":{"total":{"type":"integer"},"processed":{"type":"integer"}}},"summary":{"type":"object","nullable":true},"error":{"type":"object","nullable":true,"description":"Problem details (RFC 9457) when the job failed. type worker-lost when the process running it stopped (no heartbeat for 15 minutes); submit the job again.","allOf":[{"$ref":"#/components/schemas/Problem"}]},"resultsUrl":{"type":"string","nullable":true,"description":"Set once the job has succeeded, until its results are deleted at resultsExpireAt"},"createdAt":{"type":"string","format":"date-time"},"startedAt":{"type":"string","format":"date-time","nullable":true},"completedAt":{"type":"string","format":"date-time","nullable":true},"resultsExpireAt":{"type":"string","format":"date-time","nullable":true}}},"Preset":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["preset"]},"name":{"type":"string"},"designOptions":{"type":"object","nullable":true,"additionalProperties":true,"description":"Design Studio options, in the same shape as a QR code designOptions"},"logoAssetId":{"type":"string","description":"Logo asset of this organization; null when the preset has none or its logo is not this organization's","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Item":{"type":"object","description":"A Barcode Manager item: a product, a packaging level or an internal code, with its 1D barcode","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["item"]},"kind":{"type":"string","enum":["GTIN_ITEM","INTERNAL"]},"name":{"type":"string"},"description":{"type":"string","nullable":true},"gtin":{"type":"string","description":"GTIN-14; null for an internal item","nullable":true},"gtinDisplay":{"type":"string","description":"The GTIN as printed (8, 12, 13 or 14 digits)","nullable":true},"sku":{"type":"string","nullable":true},"manufacturerName":{"type":"string","nullable":true},"manufacturerItemNumber":{"type":"string","nullable":true},"codeValue":{"type":"string","nullable":true},"symbology":{"type":"string","enum":["EAN13","UPCA","UPCE","EAN8","ITF14","GS1_128","CODE128","CODE39"],"description":"What prints"},"symbologyOverride":{"type":"string","enum":["EAN13","UPCA","UPCE","EAN8","ITF14","GS1_128","CODE128","CODE39"],"nullable":true},"level":{"type":"string","enum":["UNIT","PACK","CASE"]},"parentId":{"type":"string","nullable":true},"packQuantity":{"type":"integer","nullable":true},"status":{"type":"string","enum":["DRAFT","LIVE","DISCONTINUED"]},"releasedAt":{"type":"string","format":"date-time","nullable":true},"discontinuedAt":{"type":"string","format":"date-time","nullable":true},"category":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Prefix":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["prefix"]},"prefix":{"type":"string","description":"A GS1 Company Prefix, or a single licensed GTIN-14"},"kind":{"type":"string","enum":["COMPANY_PREFIX","SINGLE_GTIN"]},"label":{"type":"string","nullable":true},"verified":{"type":"boolean","description":"Declared prefixes are not verified"},"capacity":{"type":"integer"},"used":{"type":"integer"},"remaining":{"type":"integer"}}},"ReferenceItem":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string"}}},"Problem":{"type":"object","description":"RFC 9457 problem details. Branch on `type`; the slugs are stable.","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri","enum":["https://qrbolt.com/developers/errors/validation-error","https://qrbolt.com/developers/errors/bad-request","https://qrbolt.com/developers/errors/invalid-cursor","https://qrbolt.com/developers/errors/change-note-required","https://qrbolt.com/developers/errors/unauthorized","https://qrbolt.com/developers/errors/insufficient-scope","https://qrbolt.com/developers/errors/feature-not-enabled","https://qrbolt.com/developers/errors/gs1-not-enabled","https://qrbolt.com/developers/errors/forbidden","https://qrbolt.com/developers/errors/not-found","https://qrbolt.com/developers/errors/conflict","https://qrbolt.com/developers/errors/idempotency-in-progress","https://qrbolt.com/developers/errors/idempotency-key-reuse","https://qrbolt.com/developers/errors/idempotency-response-unavailable","https://qrbolt.com/developers/errors/active-code-limit-exceeded","https://qrbolt.com/developers/errors/payload-too-large","https://qrbolt.com/developers/errors/unsupported-media-type","https://qrbolt.com/developers/errors/rate-limited","https://qrbolt.com/developers/errors/internal-error","https://qrbolt.com/developers/errors/worker-lost","https://qrbolt.com/developers/errors/service-unavailable"]},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"requestId":{"type":"string"},"reason":{"type":"string","description":"A stable sub-type of the problem, for example barcode-manager-not-enabled (feature-not-enabled), item-limit-exceeded, draft-release-needs-items-write, read-only-plan or batch-export-not-enabled (forbidden), not-eligible or limit-not-set (gs1-not-enabled)."},"code":{"type":"string","description":"A stable code on some conflicts: NO_PREFIX, PREFIX_FULL or HAS_DIGITAL_LINK for Barcode Manager items."},"errors":{"type":"array","description":"Validation errors (type validation-error). Every entry has `pointer`, a JSON Pointer (RFC 6901, with ~ and / escaped as ~0 and ~1) to the body member or the query or path parameter. Most endpoints add `message`; Barcode Manager item rules add `field`, `code`, `severity` and sometimes `params`.","items":{"type":"object","properties":{"pointer":{"type":"string"},"message":{"type":"string"},"field":{"type":"string","nullable":true,"description":"Barcode Manager items: the item field"},"code":{"type":"string","description":"Barcode Manager items: a stable issue code, such as gtinCheckDigit, gtinLocked or duplicateSku"},"severity":{"type":"string","enum":["error","warning"],"description":"Barcode Manager items: warnings never block a save"},"params":{"type":"object","additionalProperties":true,"description":"Barcode Manager items: details of the issue, such as corrected (the GTIN with the right check digit) or max"}}}}},"additionalProperties":true}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Id of this request; the one you sent when it was 8-64 characters of A-Z, a-z, 0-9, ., _ or -. Quote it when you contact us."},"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Size of the bucket closest to empty (key or account)."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Units left in that bucket."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until that bucket is full again."},"RateLimit-Policy":{"schema":{"type":"string"},"description":"The policy of that bucket, e.g. `<units>;w=60;burst=<size>`."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"ETag":{"schema":{"type":"string"},"description":"QR code: its version, for If-Match on PATCH and DELETE. Image: a hash of the bytes, for If-None-Match."},"Idempotent-Replayed":{"schema":{"type":"string","enum":["true"]},"description":"Present when this response is the stored response of an earlier request with the same Idempotency-Key."},"X-QR-Logo":{"schema":{"type":"string","enum":["omitted"]},"description":"The code has a logo, but it could not be rendered and this image is without it."}},"parameters":{"X-Request-Id":{"name":"X-Request-Id","in":"header","required":false,"description":"Your own id for this request (8-64 characters: A-Z, a-z, 0-9, ., _, -). It is echoed in X-Request-Id and recorded with the request; anything else is replaced by an id we make.","schema":{"type":"string","pattern":"^[A-Za-z0-9._-]{8,64}$"}},"Idempotency-Key":{"name":"Idempotency-Key","in":"header","required":false,"description":"Any unique string of 1-255 visible ASCII characters. A retry with the same key, method, path, query and body within 24 hours returns the first response with Idempotent-Replayed: true instead of doing the work again. Keys are per API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x21-\\x7e]+$"}},"If-None-Match":{"name":"If-None-Match","in":"header","required":false,"description":"The ETag of the image you have. If it is unchanged the answer is 304 with no body.","schema":{"type":"string"}},"X-Change-Note":{"name":"X-Change-Note","in":"header","required":false,"description":"Why the change is made, recorded with it in the activity log (up to 500 characters; percent-encode non-ASCII text). Required when the organization requires change notes: without it the request is refused with change-note-required.","schema":{"type":"string"}}},"responses":{"BadRequest":{"description":"validation-error (errors lists each field with a pointer; for Barcode Manager items each entry also has field, code and severity), bad-request (for example invalid JSON or a malformed Idempotency-Key or If-Match), invalid-cursor or change-note-required","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Unauthorized":{"description":"unauthorized: no key, or the key is unknown, revoked, expired, for another environment, or its creator, department or account is no longer active","headers":{"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer realm=\"api.qrbolt.com\""}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"PaymentRequired":{"description":"active-code-limit-exceeded: the request needs more active codes than the plan has left; requested, remaining, limit and shortfall give the numbers. Nothing was created.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Forbidden":{"description":"insufficient-scope (requiredScopes lists them), feature-not-enabled (reason barcode-manager-not-enabled for the items endpoints), gs1-not-enabled (reason not-eligible or limit-not-set) or forbidden (for example a department this key cannot use; reason item-limit-exceeded with limit, current, requested and shortfall when the plan has no room for more items; reason draft-release-needs-items-write when a barcode download or export would release a DRAFT item and the key lacks items:write; reason read-only-plan for the barcode of a DRAFT item after a downgrade; reason batch-export-not-enabled on a plan without batch barcode export)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"NotFound":{"description":"not-found: the resource does not exist, or this key cannot see it","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Conflict":{"description":"conflict (for Barcode Manager items, code NO_PREFIX, PREFIX_FULL or HAS_DIGITAL_LINK when there is one), idempotency-in-progress (with Retry-After) or idempotency-response-unavailable","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"PayloadTooLarge":{"description":"payload-too-large: the body is over 5 MB","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"UnsupportedMediaType":{"description":"unsupported-media-type: the request has a body whose Content-Type is not application/json (or another +json type). Nothing was changed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"IdempotencyKeyReuse":{"description":"idempotency-key-reuse: the Idempotency-Key was used in the last 24 hours for a different method, path, query or body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"TooManyRequests":{"description":"rate-limited: over the rate limit of the key or the account, or every job slot of the account is busy. Wait Retry-After seconds, then retry with backoff and jitter.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"ServiceUnavailable":{"description":"service-unavailable: a dependency is down, for example the idempotency store when Idempotency-Key is sent. Retry with backoff.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"security":[{"apiKey":[]}]}