# 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](https://cli.im/open-api/en/openapi/v2/scenarios/batch-create-qrcodes.md) already include an image URL.

## Prerequisites

- A [personal API key](https://cli.im/open-api/en/openapi/v2/auth.md#create-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

| Step | Endpoint | Purpose |
|---|---|---|
| 1 | `labels/getConfig` | Read the current label style, size and supported export formats |
| 2 | `labels/preview` | Preview with a few real codes to confirm the result |
| 3 | `labelExports/create` | Create the export task |
| 4 | `labelExports/get` | Check 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:

| format | Content |
|---|---|
| `png_zip` | One image per label |
| `a4_pdf` | Several labels laid out on A4 pages |
| `a4_pdf_single` | One 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.

### Step 4: Get the download link

```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

| Response | What to do |
|---|---|
| `LABEL_FIELD_PERMISSION_DENIED` | The 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_allowed` | You are using an organization key. Switch to a personal API key |
| HTTP 429 | See [rate limits](https://cli.im/open-api/en/openapi/v2/error-codes.md#rate-limit) |
