Skip to content

Export printable labels ​

Use this when the codes already exist and you want printable files in the label style set up in the console.

If you only need the QR code images without a label style, skip this flow: the creation endpoints and the bulk creation results already include an image URL.

Prerequisites ​

  • A personal API key. Reading the configuration and previewing work at the Read-only level. Creating an export task needs Read/write or Full. Organization keys cannot call these endpoints.
  • The target codes have a label style linked in the console.
  • Every endpoint is POST https://open.cli.im/api/v2/rpc/{path} with a JSON body. Successful results are in data.

Call sequence ​

StepEndpointPurpose
1labels/getConfigRead the current label style, size and supported export formats
2labels/previewPreview with a few real codes to confirm the result
3labelExports/createCreate the export task
4labelExports/getCheck the task and get the download link

Step 1: Read the configuration ​

bash
curl -sS -X POST 'https://open.cli.im/api/v2/rpc/labels/getConfig' \
  -H "Authorization: Bearer ${CAOLIAO_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{"qrcode_id": "<qrcode_id>"}'

qrcode_id can be a standard code, a sub-code or a batch template. The response has the linked style, the fields on the label, supported_formats and the maximum number of codes per export. This call only reads; it does not change the default style.

Step 2: Preview ​

json
{"qrcode_ids": ["<qrcode_id_1>", "<qrcode_id_2>"]}

Send this to labels/preview with at most 3 codes. Check the names, fields and QR codes in the preview before exporting the whole batch.

Step 3: Create the export task ​

json
{
  "qrcode_ids": ["<qrcode_id_1>", "<qrcode_id_2>", "<qrcode_id_3>"],
  "format": "a4_pdf",
  "idempotency_key": "label-export-20261118-01"
}

Send this to labelExports/create. It returns a task_id. Pick format from supported_formats in step 1:

formatContent
png_zipOne image per label
a4_pdfSeveral labels laid out on A4 pages
a4_pdf_singleOne label per A4 page, one page per code

All three formats download as a ZIP file.

If a request times out or the outcome is unclear, retry with the same idempotency_key and the same parameters. The task is not queued twice.

json
{"task_id": "<task_id>"}

Send this to labelExports/get. When the task finishes it returns the file link, or the reason if it failed. The link expires, so download the file soon.

Common responses ​

ResponseWhat to do
LABEL_FIELD_PERMISSION_DENIEDThe label uses a field whose original value the member cannot view. Create the key as a member who can, or change the label style in the console
HTTP 403 credential_type_not_allowedYou are using an organization key. Switch to a personal API key
HTTP 429See rate limits