> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jakan.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Tag Operations

> Operations for managing tags (categories/labels).

Operations for managing tags (categories/labels).

Bases: `StashClientProtocol`

Mixin for tag-related client methods.

## Functions

### find\_tag

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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:

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

Auto-create missing tags:

```python theme={null}
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:

```python theme={null}
tag_obj = Tag(name="Action")
tag_ids = await client.map_tag_ids([tag_obj, "Drama"])
```

Use in scene creation:

```python theme={null}
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)
```