# Edit and delete codes and forms

Use this when your system needs to update existing codes, or clean up codes and forms that are no longer used.

## What each permission level allows

| Level | Edit | Delete |
|---|---|---|
| Read-only | No | No |
| Read/write | Only content created through the API or MCP | No |
| Full | Also content that members created by hand in the console | Yes |

The effective level is the lower of the [organization's maximum permission](https://cli.im/open-api/en/openapi/v2/auth.md#org-policy) and the key's level, and the member must be able to manage the target. Organization keys cannot call these endpoints.

Every endpoint is `POST https://open.cli.im/api/v2/rpc/{path}` with a JSON body. Successful results are in `data`.

## Edit {#edit}

Editing takes two calls: read the current state to get a `version`, then submit with that `version`.

| Target | Read first | Then edit |
|---|---|---|
| Standard and rich-content codes | `qrcodes/getEditState` | `qrcodes/edit` |
| Redirect codes | `qrcodes/getEditState` | `qrcodes/editUrlJump` |
| Multi-link codes | `qrcodes/getEditState` | `qrcodes/editMultiUrl` |
| Sub-codes of a batch template | `qrcodes/getEditState` | `qrcodeChildren/edit` |
| Forms | `forms/getEditState` | `forms/edit` |
| The batch template itself | `templates/getSchema` | `templates/previewEdit`, then `templates/edit` |

### Step 1: Read the current state

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

`qrcode_id` is the numeric ID from the `id` field of [List QR codes](https://cli.im/open-api/openapi/v2/api/qrcodes-list.md) (Chinese only) or from the creation response. It is not the `coding`.

The response has `kind`, `version`, `editable` and `reason`. Sub-codes include `fields`, standard codes include `components`, and link codes include their links. Do not submit when `editable` is false. Act on `reason`:

| reason | Meaning |
|---|---|
| `AI_EDIT_NOT_AI_CREATED` | A member created this by hand and the organization's maximum permission is below Full |
| `AI_EDIT_SCOPE_REQUIRED` | A member created this by hand and the current key is not at the Full level |

### Step 2: Submit the change

To change one field of a sub-code, send this to `qrcodeChildren/edit`:

```json
{
  "qrcode_id": "<qrcode_id>",
  "version": "<version>",
  "idempotency_key": "eq-001-move-20261118",
  "values": {"<field_id_location>": "Power plant, south side"}
}
```

- Fields you leave out keep their values. Do not send `null`.
- A successful edit returns a new `version`; use it for the next edit. A version mismatch means someone else changed the content: read the state again and resubmit.
- Editing content does not change the code's link, so printed codes keep working.

Differences by target:

- **Standard codes** (`qrcodes/edit`): `components` is the complete ordered list. Write `{"type": "keep", "ref": "<components[].ref>"}` for each existing component you want to keep. Components you leave out are removed. To rename only, send just `name`.
- **Sub-codes** (`qrcodeChildren/edit`): `values` holds only the fields to change. The template's shared fields cannot be changed here.
- **Forms** (`forms/edit`): `fields` is a complete snapshot. You can change the name, required flags and order, and append fields and options. You cannot remove fields or options or change a field's type.
- **Batch templates**: call `templates/previewEdit` first to see how many sub-codes are affected, and pass the returned `preview_token` when you save.
- **Static codes**: the content cannot be changed. Create a new one.

## Delete {#delete}

Deleting also takes two calls: preview to get a confirmation token, then delete with it. This requires the Full level.

| Target | Preview first | Then delete | Limits |
|---|---|---|---|
| Standard, redirect and multi-link codes, sub-codes | `qrcodes/previewDelete` | `qrcodes/delete` | Up to 20 per call. Batch templates and static codes are not supported |
| Forms | `forms/previewDelete` | `forms/delete` | Up to 5 per call. The form must not be linked to any code |

### Step 1: Preview

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

Send this to `qrcodes/previewDelete`. A preview changes nothing. It returns `items` (the name, type and other details of each target) and a `confirm_token`. Check in your system that `items` are the objects you mean to delete.

### Step 2: Delete

```json
{
  "qrcode_ids": ["<qrcode_id_1>", "<qrcode_id_2>"],
  "confirm_token": "<confirm_token>",
  "idempotency_key": "cleanup-20261118-01"
}
```

Send this to `qrcodes/delete`.

- `qrcode_ids` must match the preview exactly.
- `confirm_token` is valid for 10 minutes. Preview again if it expires or the targets change.
- A `status` of `succeeded` means everything was deleted. With `partial_success`, check the deleted items and the errors separately.
- If the outcome is unclear, retry with the same `idempotency_key` and the same parameters.

Deleted items can be restored in the console under Settings → Operation log. The API has no restore endpoint.

## Common responses

| Response | What to do |
|---|---|
| HTTP 403 `credential_type_not_allowed` | You are using an organization key. Switch to a [personal API key](https://cli.im/open-api/en/openapi/v2/auth.md#create-key) |
| `AI_DELETE_DISABLED` | The organization's maximum permission is below Full. Ask a super administrator to [change the organization policy](https://cli.im/open-api/en/openapi/v2/auth.md#org-policy) |
| `ACCESS_LEVEL_READ_ONLY` | The organization's maximum permission is Read-only, so every write is rejected |
| HTTP 429 | See [rate limits](https://cli.im/open-api/en/openapi/v2/error-codes.md#rate-limit) |
