> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encord.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Organization Tags
> Learn how to create, attach, and manage organization tags on Projects using Encord's SDK.
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](/sdk-documentation/projects-sdk/sdk-projects-issues-comments).
**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`.
```python Create an organization tag theme={"dark"}
# 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`.
```python List organization tags theme={"dark"}
# 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.
```python Attach an organization tag to a project theme={"dark"}
# 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.
```python Remove an organization tag from a project theme={"dark"}
# 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()`](/sdk-documentation/sdk-references/user_client#list_projects) to return only Projects that have at least one of the given tags. The filter accepts tag name strings or `OrganisationTag` instances.
```python List projects filtered by tag theme={"dark"}
# 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.
```python Delete an organization tag theme={"dark"}
# 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()`](/sdk-documentation/sdk-references/project#get_organisation_tags), [`list_organisation_tags()`](/sdk-documentation/sdk-references/user_client#list_organisation_tags), and `OrganisationTag` instead. The old names remain as aliases and return the same tags, so existing scripts continue to work.