Tag Operations - Stash Tools & Scrapers

Operations for managing tags (categories/labels). Bases: StashClientProtocol Mixin for tag-related client methods.

Functions

find_tag

find_tag(id: str) -> Tag | None

Find a tag by its ID. Parameters:

Name	Type	Description	Default
`id`	`str`	The ID of the tag to find	required

Returns:

Type	Description
`Tag \| None`	Tag object if found, None otherwise

find_tags

find_tags(
    filter_: dict[str, Any] | None = None,
    tag_filter: dict[str, Any] | None = None,
    q: str | None = None,
) -> FindTagsResultType

Find tags matching the given filters. Parameters:

Name	Type	Description	Default
`filter_`	`dict[str, Any] \| None`	Optional general filter parameters: - q: str (search query) - direction: SortDirectionEnum (ASC/DESC) - page: int - per_page: int - sort: str (field to sort by)	`None`
`tag_filter`	`dict[str, Any] \| None`	Optional tag-specific filter	`None`
`q`	`str \| None`	Optional search query (alternative to filter_[“q”])	`None`

Returns:

Type	Description
`FindTagsResultType`	FindTagsResultType.

create_tag

create_tag(tag: Tag) -> Tag

Create a new tag in Stash. Parameters:

Name	Type	Description	Default
`tag`	`Tag`	Tag object with the data to create. Required fields: - name: Tag name	required

Returns:

Type	Description
`Tag`	Created Tag object with ID and any server-generated fields

Raises:

Type	Description
`ValueError`	If the tag data is invalid
`TransportError`	If the request fails

tags_merge

tags_merge(source: list[str], destination: str) -> Tag

Merge multiple tags into one. Parameters:

Name	Type	Description	Default
`source`	`list[str]`	List of source tag IDs to merge	required
`destination`	`str`	Destination tag ID	required

Returns:

Type	Description
`Tag`	Updated destination Tag object

Raises:

Type	Description
`ValueError`	If the tag data is invalid
`TransportError`	If the request fails

bulk_tag_update

bulk_tag_update(
    ids: list[str],
    description: str | None = None,
    aliases: list[str] | None = None,
    favorite: bool | None = None,
    parent_ids: list[str] | None = None,
    child_ids: list[str] | None = None,
) -> list[Tag]

Update multiple tags at once. Parameters:

Name	Type	Description	Default
`ids`	`list[str]`	List of tag IDs to update	required
`description`	`str \| None`	Optional description to set	`None`
`aliases`	`list[str] \| None`	Optional list of aliases to set	`None`
`favorite`	`bool \| None`	Optional favorite flag to set	`None`
`parent_ids`	`list[str] \| None`	Optional list of parent tag IDs to set	`None`
`child_ids`	`list[str] \| None`	Optional list of child tag IDs to set	`None`

Returns:

Type	Description
`list[Tag]`	List of updated Tag objects

Raises:

Type	Description
`ValueError`	If the tag data is invalid
`TransportError`	If the request fails

update_tag

update_tag(tag: Tag) -> Tag

Update an existing tag in Stash. Parameters:

Name	Type	Description	Default
`tag`	`Tag`	Tag object with updated data. Required fields: - id: Tag ID to update Any other fields that are set will be updated. Fields that are None will be ignored.	required

Returns:

Type	Description
`Tag`	Updated Tag object with any server-generated fields

Raises:

Type	Description
`ValueError`	If the tag data is invalid
`TransportError`	If the request fails

tag_destroy

tag_destroy(
    input_data: TagDestroyInput | dict[str, Any],
) -> bool

Delete a tag. Parameters:

Name	Type	Description	Default
`input_data`	`TagDestroyInput \| dict[str, Any]`	TagDestroyInput object or dictionary.	required

Returns:

Type	Description
`bool`	True if the tag was successfully deleted

Raises:

Type	Description
`ValueError`	If the tag ID is invalid
`TransportError`	If the request fails

tags_destroy

tags_destroy(ids: list[str]) -> bool

Delete multiple tags. Parameters:

Name	Type	Description	Default
`ids`	`list[str]`	List of tag IDs to delete	required

Returns:

Type	Description
`bool`	True if the tags were successfully deleted

Raises:

Type	Description
`ValueError`	If any tag ID is invalid
`TransportError`	If the request fails

map_tag_ids

map_tag_ids(
    tags: list[str | dict[str, Any] | Tag],
    create: bool = False,
) -> list[str]

Convert tag names/objects to IDs, optionally creating missing tags. This is a convenience method to resolve tag references to their IDs, reducing boilerplate when working with tag relationships. Parameters:

Name	Type	Description	Default
`tags`	`list[str \| dict[str, Any] \| Tag]`	List of tag references, can be: - str: Tag name (searches for exact match) - dict: Tag filter criteria (e.g., {“name”: “Action”}) - Tag: Tag object (extracts ID if present, otherwise searches by name)	required
`create`	`bool`	If True, create tags that don’t exist. Default is False.	`False`

Returns:

Type	Description
`list[str]`	List of tag IDs. Skips tags that aren’t found (unless create=True).

Examples: Map tag names to IDs:

tag_ids = await client.map_tag_ids(["Action", "Drama", "Comedy"])
# Returns: ["1", "2", "3"] (IDs of existing tags)

Auto-create missing tags:

tag_ids = await client.map_tag_ids(
    ["Action", "NewTag", "Drama"],
    create=True
)
# Creates "NewTag" if it doesn't exist

Mix of strings and Tag objects:

tag_obj = Tag(name="Action")
tag_ids = await client.map_tag_ids([tag_obj, "Drama"])

Use in scene creation:

scene = Scene(
    title="My Scene",
    tags=[]  # Will populate with tag IDs
)
scene.tags = await client.map_tag_ids(
    ["Action", "Drama"],
    create=True
)
created_scene = await client.create_scene(scene)

​Functions

​find_tag

​find_tags

​create_tag

​tags_merge

​bulk_tag_update

​update_tag

​tag_destroy

​tags_destroy

​map_tag_ids

Functions

find_tag

find_tags

create_tag

tags_merge

bulk_tag_update

update_tag

tag_destroy

tags_destroy

map_tag_ids