Problem
There is currently no supported way to change an item's name after it has been uploaded to a project. This is needed when migrating a naming convention on existing data, e.g., re-uploading affected items would be the only workaround, which discards their annotation status, QA progress, and assignment history.
Confirmed unavailable via:
SAClient exposes no rename_item/update_item method (rename_project exists, but is project-level only).
get_item_metadata() is read-only.
item_context() covers component values and annotations, not the item's own name/metadata.
Current behavior
The service layer already supports this at a lower level. ItemService.update() (lib/infrastructure/services/item.py) issues a generic PUT image/{item_id} with the full serialized item entity, and BaseItemEntity.name is a mutable field.
This code path is already exercised publicly today:
pin_image() mutates item.is_pinned and persists it through this same controller.items.update() call.
Suggested implementation (validated working)
Using this same path with name instead of is_pinned works as-is:
project, folder = sa.controller.get_project_folder(path)
item = next(iter(sa.controller.items.list_items(project, folder, name=old_name)), None)
item.name = new_name
sa.controller.items.update(project=project, item=item)
We tested this against a real item and confirmed: the rename persists (visible via search_items/get_item_metadata immediately after), the item ID is unchanged, and annotation_status plus every component value (tested audio_url and a JSON data_store field) are byte-for-byte unchanged: only name and updatedAt differ. This suggests the feature could be exposed with fairly low implementation risk, essentially wrapping the pattern above (or the equivalent pin_image() already uses) behind a public method.
Proposed solution
Expose an official method for this, e.g.:
sa.rename_item(project="my_project", item_name="old_name", new_name="new_name")
or allow name to be set through an existing update path (item_context, or a general update_item()). This would remove the need to depend on SAClient.controller internals, which are not part of the public API and may change without notice between versions.
Environment: superannotate (Python SDK) 4.5.3
Problem
There is currently no supported way to change an item's name after it has been uploaded to a project. This is needed when migrating a naming convention on existing data, e.g., re-uploading affected items would be the only workaround, which discards their annotation status, QA progress, and assignment history.
Confirmed unavailable via:
SAClientexposes norename_item/update_itemmethod (rename_projectexists, but is project-level only).get_item_metadata()is read-only.item_context()covers component values and annotations, not the item's own name/metadata.Current behavior
The service layer already supports this at a lower level.
ItemService.update()(lib/infrastructure/services/item.py) issues a genericPUT image/{item_id}with the full serialized item entity, andBaseItemEntity.nameis a mutable field.This code path is already exercised publicly today:
pin_image()mutatesitem.is_pinnedand persists it through this samecontroller.items.update()call.Suggested implementation (validated working)
Using this same path with
nameinstead ofis_pinnedworks as-is:We tested this against a real item and confirmed: the rename persists (visible via
search_items/get_item_metadataimmediately after), the item ID is unchanged, andannotation_statusplus every component value (testedaudio_urland a JSONdata_storefield) are byte-for-byte unchanged: onlynameandupdatedAtdiffer. This suggests the feature could be exposed with fairly low implementation risk, essentially wrapping the pattern above (or the equivalentpin_image()already uses) behind a public method.Proposed solution
Expose an official method for this, e.g.:
sa.rename_item(project="my_project", item_name="old_name", new_name="new_name")or allow
nameto be set through an existing update path (item_context, or a generalupdate_item()). This would remove the need to depend on SAClient.controller internals, which are not part of the public API and may change without notice between versions.Environment: superannotate (Python SDK) 4.5.3