Skip to content

Feature request: allow updating an item's name after upload #878

Description

@LCapy

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions