Folders#

SAClient.search_folders(project, folder_name=None, status=None, return_metadata=False)#

Folder name based case-insensitive search for folders in project.

Parameters:

project (str) – project name
folder_name (str. If None, all the folders in the project will be returned.) – the new folder’s name
status (str or list of str) –
search folders via status. If None, all folders will be returned.

Available statuses are:
```
* NotStarted
* InProgress
* Completed
* OnHold
```
return_metadata (bool) – return metadata of folders instead of names

Returns:

folder names or metadatas

Return type:

list of strs or dicts

SAClient.set_folder_status(project, folder, status)#

Set folder status

Parameters:

project (str) – project name or ID
folder (str) – folder name or ID

status (str) –

status to set.

Available statuses are:

* NotStarted
* InProgress
* Completed
* OnHold

SAClient.assign_folder(project_name, folder_name, users)#

Assigns folder to users. With SDK, the user can be assigned to a role in the project with the share_project function.

Parameters:

project_name (str or dict) – project name of the project
folder_name (str) – folder name to assign
users (list of str) – list of user emails

SAClient.unassign_folder(project_name, folder_name)#

Removes assignment of given folder for all assignees. With SDK, the user can be assigned to a role in the project with the share_project function.

Parameters:

project_name (str) – project name
folder_name (str) – folder name to remove assignees

SAClient.get_folder_by_id(project_id, folder_id)#

Returns the folder metadata

Parameters:

project_id (int) – the ID of the project
folder_id (int) – the ID of the folder

Returns:

folder metadata

Return type:

dict

SAClient.get_folder_metadata(project, folder_name, include_contributors=False)#

Returns folder metadata. Optionally includes a list of contributors that are currently assigned to the folder.

Parameters:

project (str) – project name or ID
folder_name (str) – folder’s name
include_contributors (bool) – If True, includes a list of contributors assigned to the folder in the response. Defaults to False.

Returns:

Folder metadata

Return type:

dict

Request Example:

sa_client.get_folder_metadata(
    project="test_project",
    folder_name="test_folder",
    include_contributors=True
)

Response Example:

{
    "createdAt": "2025-10-27T06:54:09.000Z",
    "updatedAt": "2025-10-27T06:54:09.000Z",
    "id": 1487195,
    "name": "test_folder",
    "status": "NotStarted",
    "project_id": 1203397,
    "team_id": 85922,
    "contributors": [
        {
            "email": "test@superannotate.com",
            "id": 1314658,
            "role": "Annotator",
            "state": "Confirmed"
        }
    ]
}

SAClient.create_folder(project, folder_name)#

Create a new folder in the project.

Parameters:

project (str) – project name or ID
folder_name (str) – the new folder’s name

Returns:

dict object metadata the new folder

Return type:

dict

SAClient.delete_folders(project, folder_names)#

Delete folder in project.

Parameters:

project (str) – project name or ID
folder_names (list of strs) – to be deleted folders’ names

SAClient.list_folders(project, **filters)#

Search folders by filtering criteria.

Parameters:

project (Union[NotEmptyStr, int]) – The project name or project ID to search within.

filters (FolderFilters, optional) –

Filtering criteria. All conditions are combined using logical AND.If no filter operation is provided, an exact match is applied.

Supported filter operations:

__in: Value is in the provided list.
__notin: Value is not in the provided list.
__ne: Value is not equal to the given value.
__contains: Value contains the specified substring.
__starts: Value starts with the given prefix.
__ends: Value ends with the given suffix.

Filter params:

- id: int
- id__in: list[int]
- name: str
- name__in: list[str]
- name__contains: str
- name__starts: str
- name__ends: str
- status: Literal["NotStarted", "InProgress", "Completed", "OnHold"]
- status__ne: Literal["NotStarted", "InProgress", "Completed", "OnHold"]
- status__in: List[Literal["NotStarted", "InProgress", "Completed", "OnHold"]]
- status__notin: List[Literal["NotStarted", "InProgress", "Completed", "OnHold"]]

Returns:

A list of folder metadata that matches the filtering criteria.

Return type:

list of dicts

Request Example:

sa_client.list_folders(
    project="test_project",
    status="NotStarted"
)

Response Example:

[
    {
        "createdAt": "2025-10-27T06:54:09.000Z",
        "updatedAt": "2025-10-27T06:54:09.000Z",
        "id": 1487195,
        "name": "test_folder",
        "status": "NotStarted",
        "project_id": 1203397,
        "team_id": 85922,
        "is_root": False
    },
    {
        "createdAt": "2025-10-27T06:54:09.000Z",
        "updatedAt": "2025-10-27T06:54:09.000Z",
        "id": 1379813,
        "name": "root",
        "status": None,
        "project_id": 1203397,
        "team_id": 85922,
        "is_root": True
    }
]