Skip to content

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 ​

LevelEditDelete
Read-onlyNoNo
Read/writeOnly content created through the API or MCPNo
FullAlso content that members created by hand in the consoleYes

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.

TargetRead firstThen edit
Standard and rich-content codesqrcodes/getEditStateqrcodes/edit
Redirect codesqrcodes/getEditStateqrcodes/editUrlJump
Multi-link codesqrcodes/getEditStateqrcodes/editMultiUrl
Sub-codes of a batch templateqrcodes/getEditStateqrcodeChildren/edit
Formsforms/getEditStateforms/edit
The batch template itselftemplates/getSchematemplates/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 (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:

reasonMeaning
AI_EDIT_NOT_AI_CREATEDA member created this by hand and the organization's maximum permission is below Full
AI_EDIT_SCOPE_REQUIREDA 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 ​

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

TargetPreview firstThen deleteLimits
Standard, redirect and multi-link codes, sub-codesqrcodes/previewDeleteqrcodes/deleteUp to 20 per call. Batch templates and static codes are not supported
Formsforms/previewDeleteforms/deleteUp 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 ​

ResponseWhat to do
HTTP 403 credential_type_not_allowedYou are using an organization key. Switch to a personal API key
AI_DELETE_DISABLEDThe organization's maximum permission is below Full. Ask a super administrator to change the organization policy
ACCESS_LEVEL_READ_ONLYThe organization's maximum permission is Read-only, so every write is rejected
HTTP 429See rate limits