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 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
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
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 (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:
{
"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):componentsis 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 justname. - Sub-codes (
qrcodeChildren/edit):valuesholds only the fields to change. The template's shared fields cannot be changed here. - Forms (
forms/edit):fieldsis 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/previewEditfirst to see how many sub-codes are affected, and pass the returnedpreview_tokenwhen you save. - Static codes: the content cannot be changed. Create a new one.
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
{"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
{
"qrcode_ids": ["<qrcode_id_1>", "<qrcode_id_2>"],
"confirm_token": "<confirm_token>",
"idempotency_key": "cleanup-20261118-01"
}Send this to qrcodes/delete.
qrcode_idsmust match the preview exactly.confirm_tokenis valid for 10 minutes. Preview again if it expires or the targets change.- A
statusofsucceededmeans everything was deleted. Withpartial_success, check the deleted items and the errors separately. - If the outcome is unclear, retry with the same
idempotency_keyand 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 |
AI_DELETE_DISABLED | The organization's maximum permission is below Full. Ask a super administrator to change the organization policy |
ACCESS_LEVEL_READ_ONLY | The organization's maximum permission is Read-only, so every write is rejected |
| HTTP 429 | See rate limits |