Organization Tags

Organization tags are labels defined once at the organization level and then attached to Projects (or to storage folders in the Encord app). Use them to group and filter Projects, for example to mark which Projects are ready for review or belong to a particular team.

Organization tags are distinct from issue tags, which are attached to individual Tasks. For issue tags, see Issues & Comments in Projects.

Permissions

Creating and deleting tags (create_organisation_tag, delete_organisation_tag) requires the caller to be an organization admin (the tags.manage permission).
Attaching and detaching tags on a Project (add_organisation_tag, remove_organisation_tag) requires project admin.

Create an Organization Tag

Create a tag once at the organization level. The name must be unique within the organization; the description is optional. Creating a tag with a name that already exists raises ResourceExistsError.

Create an organization tag

# Import dependencies
from encord import EncordUserClient

# User input
SSH_PATH = "/Users/user-encord/ssh-private-key.txt" # Replace with the file path to your SSH private key

# Create user client using access key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

# Create a new tag at the organization level.
# The name must be unique within the organization. Requires organization admin.
tag = user_client.create_organisation_tag(
    name="ready-for-review",
    description="Projects whose labels are ready for QA.",  # optional
)

print(f"Created tag: {tag.name} ({tag.uuid})")

List Organization Tags

List every tag defined in your organization. Each returned OrganisationTag has a name and a uuid.

List organization tags

# Import dependencies
from encord import EncordUserClient

# User input
SSH_PATH = "/Users/user-encord/ssh-private-key.txt" # Replace with the file path to your SSH private key

# Create user client using access key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

# List every tag defined in the organization.
# Each tag can be attached to projects or to storage folders.
for tag in user_client.list_organisation_tags():
    print(f"{tag.name}: {tag.uuid}")

Attach a Tag to a Project

Attach an existing organization tag to a Project. Identify the tag by tag_name, by tag_uuid, or by passing an OrganisationTag object as tag. Pass exactly one. Attaching a tag that is already attached is a no-op.

Attach an organization tag to a project

# Import dependencies
from encord import EncordUserClient

# User input
SSH_PATH = "/Users/user-encord/ssh-private-key.txt" # Replace with the file path to your SSH private key
PROJECT_ID = "00000000-0000-0000-0000-000000000000" # Replace with the ID of the Project

# Create user client using access key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

# Open the Project you want to work on by specifying the Project ID
project = user_client.get_project(PROJECT_ID)

# Attach an existing organization tag. Identify it by name, by UUID,
# or by passing an OrganisationTag object. Attaching a tag that is
# already attached is a no-op. Requires project admin.
project.add_organisation_tag(tag_name="ready-for-review")

# Read the organization tags currently attached to this Project
for tag in project.get_organisation_tags():
    print(f"Attached: {tag.name} ({tag.uuid})")

Remove a Tag from a Project

Detach a tag from a Project. The tag itself is not deleted and remains attached to any other Projects or folders. Detaching a tag that is not attached is a no-op.

Remove an organization tag from a project

# Import dependencies
from encord import EncordUserClient

# User input
SSH_PATH = "/Users/user-encord/ssh-private-key.txt" # Replace with the file path to your SSH private key
PROJECT_ID = "00000000-0000-0000-0000-000000000000" # Replace with the ID of the Project

# Create user client using access key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

# Open the Project you want to work on by specifying the Project ID
project = user_client.get_project(PROJECT_ID)

# Detach the tag from this Project. The tag itself is not deleted and
# stays attached to any other projects or folders. Detaching a tag that
# is not attached is a no-op. Requires project admin.
project.remove_organisation_tag(tag_name="ready-for-review")

Filter Projects by Tag

Use tags_anyof with list_projects() to return only Projects that have at least one of the given tags. The filter accepts tag name strings or OrganisationTag instances.

List projects filtered by tag

# Import dependencies
from encord import EncordUserClient

# User input
SSH_PATH = "/Users/user-encord/ssh-private-key.txt" # Replace with the file path to your SSH private key

# Create user client using access key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

# Return projects that have at least one of the given tags.
# tags_anyof accepts tag name strings or OrganisationTag instances.
for project in user_client.list_projects(tags_anyof=["ready-for-review", "priority"]):
    print(project.title)

Delete an Organization Tag

Delete a tag from the organization entirely. This detaches it from every Project and storage folder it is attached to. Identify the tag by tag_name, by tag_uuid, or by passing an OrganisationTag object.

Delete an organization tag

# Import dependencies
from encord import EncordUserClient

# User input
SSH_PATH = "/Users/user-encord/ssh-private-key.txt" # Replace with the file path to your SSH private key

# Create user client using access key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

# Delete the tag from the organization. This detaches it from every
# project and storage folder it is attached to. Identify it by name,
# by UUID, or by passing an OrganisationTag object. Requires organization admin.
user_client.delete_organisation_tag(tag_name="ready-for-review")

Deprecated (SDK v0.1.205): project.get_tags(), user_client.list_project_tags(), and the ProjectTag class are deprecated. Use get_organisation_tags(), list_organisation_tags(), and OrganisationTag instead. The old names remain as aliases and return the same tags, so existing scripts continue to work.

Get Started

General

Data

Ontologies

Projects

Labels

DICOM

Organization Tags

Create an Organization Tag

List Organization Tags

Attach a Tag to a Project

Remove a Tag from a Project

Filter Projects by Tag

Delete an Organization Tag

​Create an Organization Tag

​List Organization Tags

​Attach a Tag to a Project

​Remove a Tag from a Project

​Filter Projects by Tag

​Delete an Organization Tag

Create an Organization Tag

List Organization Tags

Attach a Tag to a Project

Remove a Tag from a Project

Filter Projects by Tag

Delete an Organization Tag