> For the complete documentation index, see [llms.txt](https://docs.snapfix.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.snapfix.com/engineering-reference/api/tags.md).

# Tags API

{% hint style="info" %}
Draft, written by an agent and not yet checked by a person ([how to read these docs](https://docs.snapfix.com/how-to-read.md)). [Source on GitHub](https://github.com/snapfix/docs/blob/main/spec/api/tags.md).
{% endhint %}

Tags and tag folders of groups and sites, and the tags on tasks.

* **Services:** `api_php_live_v2` at `https://z4.snapfix.com` (`/v1/app`); `php-apis` at `https://z1.snapfix.com/api/snapfix/index.php`; `php-apis web` at `https://z1.snapfix.com/api/snapfix/web/index.php`
* **Auth:** api\_php\_live\_v2: user token (authpy JWT in `Authorization: Bearer`), plus the checks every `/v1/app` route runs ([What a user token does not prove](https://docs.snapfix.com/engineering-reference/api.md#what-a-user-token-does-not-prove)); each section names the policy it adds. php-apis: user token while `JWT_AUTH_ENABLED` is on, otherwise the shared Basic login \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. The folder and tag actions read the user from the token's payload without checking its signature. The generic `save_*` actions store the rows as sent, including user fields. Many folder and tag actions take folder and tag UUIDs from any site; each section says which.
* **Rights used below:** a **site admin** has a live `tPri_UserParent` row with `user_type` `admin` on the site (`hasParentAdminAccess`). A **tag manager** is a site admin, or a site member whose newest live `tPri_UserParent` row has both `fManageTag` and `fEditTagHeader` set (`hasTagManagementAccess` in php-apis, `TagPolicy::updateTag` in api\_php\_live\_v2) (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:45721-45757`; api\_php\_live\_v2 @ ef3c4319f6, `app/Policies/TagPolicy.php:39-52`). Who should edit tags is open \[[ASK-79](https://github.com/snapfix/docs/blob/main/ASK.md#ask-79-who-should-edit-a-groups-tags)].
* **Used by:** web\_app\_v2, iOS, Android, snapfix\_ai\_agent; 33 of the 56 endpoints have no known caller
* **Answers and errors:** the `/v1/app` envelope and codes are in [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); the php-apis envelope is in [Responses](https://docs.snapfix.com/engineering-reference/api.md#responses). php-apis answers `200` with `result` `false` and the message for a failed check, such as "invalid access!" or "invalid params!", and an empty body gives "Data cannot be blank!" (php-apis @ 238ca4414e, `html/api/snapfix/index.php:4348-4351`, `htmlphp/api/snapfix/config/lang/en.php:6`). Each section lists its own errors.
* **Logs:** api\_php\_live\_v2 keeps each call and its response under about 100 KB in its request log. php-apis stores each request body and each response under about 100 KB in its daily request log.
* **Paging:** `POST /v1/app/parents/tags` uses the `api_php_live_v2` scheme in [Paging](https://docs.snapfix.com/engineering-reference/api.md#paging). The php-apis folder lists take `limit` and `offset` in the body, where `offset` is a page index from 0.
* **Related:** the tag rules are in [Site tags](https://docs.snapfix.com/product/features/console/site-tags.md). A task's own tags (`POST /v1/app/tasks/tag/multi`) are in the [Tasks API](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptaskstagmulti). What the tag options do when a task is copied or moved is open \[[ASK-21](https://github.com/snapfix/docs/blob/main/ASK.md#ask-21-who-may-copy-or-move-a-task-and-what-should-the-tag-options-do)]. Staff tag routes are in the [Staff API](https://docs.snapfix.com/engineering-reference/api/staff.md); php-apis's `admin_read_group_tag_settings` and `admin_update_group_tag_settings` let any signed-in user read and change a group's tags and are not listed here. Unused routes are in \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)].

Tag folders hold tags. A folder belongs to one group (`uuid_tBusiness`) or to a site (`uuid_tParent`). A group uses a site folder only where a rule in [`tPri_BusinessTagHeaderRule`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_businesstagheaderrule.md) links the folder to it with `fExcluded` 0; the rule's `fMandatory` makes a tag from the folder required. The shapes are in [Tag folder object](#tag-folder-object) and [Tag object](#tag-object).

| Method | Path                                                                                                                      | Service            | Purpose                                                                |
| ------ | ------------------------------------------------------------------------------------------------------------------------- | ------------------ | ---------------------------------------------------------------------- |
| PUT    | [`/v1/app/businesses/{businessUuid}/tag-header/{tagHeaderUuid}`](#put-v1appbusinessesbusinessuuidtag-headertagheaderuuid) | api\_php\_live\_v2 | Rename a group's tag folder                                            |
| POST   | `/v1/app/businesses/{businessUuid}/tags`                                                                                  | api\_php\_live\_v2 | Create a tag in a group (no caller)                                    |
| POST   | [`/v1/app/businesses/{businessUuid}/tags/multiple`](#post-v1appbusinessesbusinessuuidtagsmultiple)                        | api\_php\_live\_v2 | Create several tags in a group                                         |
| PUT    | `/v1/app/businesses/{businessUuid}/tags/{tagUuid}`                                                                        | api\_php\_live\_v2 | Rename a group's tag (no caller)                                       |
| DELETE | `/v1/app/businesses/{businessUuid}/tags/{tagUuid}`                                                                        | api\_php\_live\_v2 | Delete a group's tag (no caller)                                       |
| GET    | [`/v1/app/businesses/{uuid}/tags`](#get-v1appbusinessesuuidtags)                                                          | api\_php\_live\_v2 | List a group's tag folders and their tags                              |
| POST   | [`/v1/app/parents/tags`](#post-v1appparentstags)                                                                          | api\_php\_live\_v2 | List the tag folders and tags of several groups                        |
| POST   | [`/v1/app/tag-headers/delete/multi`](#post-v1apptag-headersdeletemulti)                                                   | api\_php\_live\_v2 | Delete several tag folders of a site                                   |
| POST   | [`/v1/app/tag-headers/delete/preview`](#post-v1apptag-headersdeletepreview)                                               | api\_php\_live\_v2 | Count what deleting tag folders would remove                           |
| ANY    | `?action=create_pri_job_tag`                                                                                              | php-apis           | Create task tags, generic table action (no caller)                     |
| ANY    | `?action=create_pri_tag`                                                                                                  | php-apis           | Create tags, generic table action (no caller)                          |
| ANY    | `?action=create_pri_tag_header`                                                                                           | php-apis           | Create tag folders, generic table action (no caller)                   |
| ANY    | `?action=create_pub_tag_default`                                                                                          | php-apis           | Create default tags, generic table action (no caller)                  |
| ANY    | `?action=create_pub_tag_header_default`                                                                                   | php-apis           | Create default tag folders, generic table action (no caller)           |
| ANY    | `?action=delete_pri_job_tag`                                                                                              | php-apis           | Delete task tags, generic table action (no caller)                     |
| ANY    | `?action=delete_pri_tag`                                                                                                  | php-apis           | Delete tags, generic table action (no caller)                          |
| ANY    | `?action=delete_pri_tag_header`                                                                                           | php-apis           | Delete tag folders, generic table action (no caller)                   |
| ANY    | `?action=delete_pub_tag_default`                                                                                          | php-apis           | Delete default tags, generic table action (no caller)                  |
| ANY    | `?action=delete_pub_tag_header_default`                                                                                   | php-apis           | Delete default tag folders, generic table action (no caller)           |
| POST   | [`?action=delete_tag_folder`](#post-actiondelete_tag_folder)                                                              | php-apis           | Delete a tag folder                                                    |
| POST   | [`?action=delete_tags`](#post-actiondelete_tags)                                                                          | php-apis           | Delete tags                                                            |
| POST   | [`?action=merge_tag_folders`](#post-actionmerge_tag_folders)                                                              | php-apis           | Merge two tag folders into a new one                                   |
| ANY    | `?action=merge_tag_folders_undo`                                                                                          | php-apis           | Undo a tag folder merge (`adminOnly_undo_mergeTagFolders`) (no caller) |
| ANY    | `?action=modify_pri_job_tag`                                                                                              | php-apis           | Change task tags, generic table action (no caller)                     |
| ANY    | `?action=modify_pri_tag`                                                                                                  | php-apis           | Change tags, generic table action (no caller)                          |
| ANY    | `?action=modify_pri_tag_header`                                                                                           | php-apis           | Change tag folders, generic table action (no caller)                   |
| ANY    | `?action=modify_pub_tag_default`                                                                                          | php-apis           | Change default tags, generic table action (no caller)                  |
| ANY    | `?action=modify_pub_tag_header_default`                                                                                   | php-apis           | Change default tag folders, generic table action (no caller)           |
| POST   | [`?action=move_tags`](#post-actionmove_tags)                                                                              | php-apis           | Move tags to another folder                                            |
| POST   | [`?action=read_business_tag_folders`](#post-actionread_business_tag_folders)                                              | php-apis           | List a site's tag folders with one group's `excluded` flag             |
| POST   | [`?action=read_folder_groups`](#post-actionread_folder_groups)                                                            | php-apis           | List a site's groups with whether a tag folder is off for each         |
| POST   | [`?action=read_folder_tags`](#post-actionread_folder_tags)                                                                | php-apis           | List a tag folder's tags with their task counts                        |
| POST   | [`?action=read_parent_tag_data`](#post-actionread_parent_tag_data)                                                        | php-apis           | Read sites' tag folders, tags and rules, for the apps' local data      |
| POST   | [`?action=read_parent_tag_folders`](#post-actionread_parent_tag_folders)                                                  | php-apis           | List a site's tag folders                                              |
| ANY    | `?action=read_pri_job_tag`                                                                                                | php-apis           | Read task tags by UUID, generic table action (no caller)               |
| ANY    | `?action=read_pri_tag`                                                                                                    | php-apis           | Read tags by UUID, generic table action (no caller)                    |
| ANY    | `?action=read_pri_tag_header`                                                                                             | php-apis           | Read tag folders by UUID, generic table action (no caller)             |
| ANY    | `?action=read_pub_tag_default`                                                                                            | php-apis           | Read default tags by UUID, generic table action (no caller)            |
| ANY    | `?action=read_pub_tag_header_default`                                                                                     | php-apis           | Read default tag folders by UUID, generic table action (no caller)     |
| ANY    | `?action=read_tag_stats`                                                                                                  | php-apis           | Disabled: always answers `result` `false`, "out of scope" (no caller)  |
| POST   | [`?action=save_business_tag_header_rule`](#post-actionsave_business_tag_header_rule)                                      | php-apis           | Save group tag folder rules, for the apps' sync                        |
| POST   | [`?action=save_folder_groups`](#post-actionsave_folder_groups)                                                            | php-apis           | Set the groups a tag folder is on or off for                           |
| POST   | [`?action=save_group_folders`](#post-actionsave_group_folders)                                                            | php-apis           | Set the tag folders a group uses                                       |
| POST   | [`?action=save_pri_job_tag`](#post-actionsave_pri_job_tag)                                                                | php-apis           | Save task tags, for the apps' sync                                     |
| POST   | [`?action=save_pri_tag`](#post-actionsave_pri_tag)                                                                        | php-apis           | Save tags, for the apps' sync                                          |
| POST   | [`?action=save_pri_tag_header`](#post-actionsave_pri_tag_header)                                                          | php-apis           | Save tag folders, for the apps' sync                                   |
| ANY    | `?action=save_pub_tag_default`                                                                                            | php-apis           | Save default tags, generic table action (no caller)                    |
| ANY    | `?action=save_pub_tag_header_default`                                                                                     | php-apis           | Save default tag folders, generic table action (no caller)             |
| POST   | [`?action=save_tag_folders`](#post-actionsave_tag_folders)                                                                | php-apis           | Create or rename tag folders                                           |
| POST   | [`?action=save_tags`](#post-actionsave_tags)                                                                              | php-apis           | Create, rename or re-sort tags in a folder                             |
| ANY    | `?action=webcust_create_tag`                                                                                              | php-apis web       | Create a tag (no caller)                                               |
| ANY    | `?action=webcust_delete_tag`                                                                                              | php-apis web       | Delete a tag (no caller)                                               |
| ANY    | `?action=webcust_select_tag`                                                                                              | php-apis web       | Add tags to a task (`selectTag`) (no caller)                           |
| ANY    | `?action=webcust_unselect_tag`                                                                                            | php-apis web       | Remove a tag from a task (`unselectTag`) (no caller)                   |
| ANY    | `?action=webcust_update_tagheader`                                                                                        | php-apis web       | Rename a tag folder (no caller)                                        |
| ANY    | `?action=webcust_update_tagname`                                                                                          | php-apis web       | Rename a tag (no caller)                                               |

Endpoints with a caller have a section below. The other 33 keep their row only:

* The three single-tag Laravel routes: web\_app\_v2 defines `createTag`, `updateTag` and `deleteTag` in its tag service, but nothing calls them (web\_app\_v2 @ 0989b8e685, `src/app/services/tag/tag-http/tag-http.service.ts:89-117`).
* The 24 php-apis rows and the six `webcust_*` rows: no client sends them. Their names appear only in the iOS and Android endpoint lists (ios @ aa31967ac8, `APIManagers/ApiEndpointManager.swift`; android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/utils/APIEndPointUtils.java`) \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)].
* `read_tag_stats` always answers `result` `false` with "out of scope" (php-apis @ 238ca4414e, `html/api/snapfix/index.php:724-731`).
* `merge_tag_folders_undo` runs `adminOnly_undo_mergeTagFolders`, which checks nothing beyond the dispatcher's token check. Given a merged folder's new UUID, it restores the two old folders and their tags, reverses the task tag changes from `tPri_JobTag_Log`, and deletes the new folder, its tags and its rules (`htmlphp/api/snapfix/class/class.functions.php:47144-47233`).
* The `webcust_*` actions are on the web dispatcher (`html/api/snapfix/web/index.php:1522`, `:2206-2245`). `webcust_select_tag` adds `tPri_JobTag` rows for a task and `webcust_unselect_tag` soft-deletes one (`htmlphp/api/snapfix/class/webapp.functions.php:3384`, `:3471`). They take `user_uuid` from the request.

## PUT /v1/app/businesses/{businessUuid}/tag-header/{tagHeaderUuid}

Renames a tag folder that a group owns. Site folders and other groups' folders give `404`.

* **Auth:** user token. `TagPolicy::updateTagHeader` passes for a group admin, a member with "Edit Tag Heading" (`UPDATE_BUSINESS_TAG_HEADING`, `perBusSettingsEditTagHeading`), and a member whose membership is Inactive (`isReadOnly`). The last clause lets read-only members rename folders; the group policy has the same clause. A caller with no membership in the group gets `403` with the raw key "messages.access\_denied" (api\_php\_live\_v2 @ ef3c4319f6, `app/Policies/TagPolicy.php:60-71`, `app/Traits/Authenticated.php:20-31`, `:47-58`, `app/Enums/Permission.php:24`).
* **Used by:** web (`TagHttpService.updateTagHeader`, web\_app\_v2 @ 0989b8e685, `src/app/services/tag/tag-http/tag-http.service.ts:78-87`; called from `src/app/pages/group-settings/group-settings-tag-headers/group-settings-tag-headers.component.ts:130`).
* **Code:** api\_php\_live\_v2 @ ef3c4319f6, `routes/business.php:30`, `app/Http/Controllers/v1/Versions/v1_0/App/TagController.php:263-300`.

**Request** (JSON)

| Name            | In   | Type   | Required | Rules                                                                                                   |
| --------------- | ---- | ------ | -------- | ------------------------------------------------------------------------------------------------------- |
| `businessUuid`  | path | string | yes      | The group                                                                                               |
| `tagHeaderUuid` | path | string | yes      | A live folder the group owns (`uuid_tBusiness`)                                                         |
| `name`          | body | string | yes      | The new name, saved as `fName`; no length limit (`app/Http/Requests/v1/Tag/UpdateTagHeaderRequest.php`) |

```json
{ "name": "Room cleaning" }
```

**Response** `200`: a [tag folder object](#tag-folder-object) without `tags`. A group's own folder has no `fMandatory` column, so `mandatory` is `null`.

```json
{
  "status": "success",
  "message": "Tag header updated successfully",
  "data": {
    "uuid": "123",
    "name": "Room cleaning",
    "description": null,
    "mandatory": null
  }
}
```

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `422` when `name` is missing or isn't a string; `403` "messages.access\_denied" for a caller with no membership in the group, including an unknown group; `403` "Access denied" for a member without the rights above; `404` "Resource not found" when the folder is not a live folder of the group.

**Side effects:**

* Saves `fName` on the folder's row in [`tPri_TagHeader`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_tagheader.md).
* Queues one silent push (`TAG_HEADER_EDIT`) to the group's device tokens (`app/Services/NotificationService.php:159-172`).

## POST /v1/app/businesses/{businessUuid}/tags/multiple

Creates several tags in one call, each in the folder it names. A name already in its folder is skipped without an error. The web uses it for the CSV import in group settings, the task create dialog and the AI tag suggestions.

* **Auth:** user token. `TagPolicy::updateTag` on the group's site: a tag manager. The folder named in each item is not checked against the group or its site, so tags can be added to another site's folder. The single-tag create route checks this (`app/Http/Requests/v1/Tag/CreateTagRequest.php:15`).
* **Used by:** web (`TagHttpService.createMultipleTags`, web\_app\_v2 @ 0989b8e685, `src/app/services/tag/tag-http/tag-http.service.ts:119-126`; called from `src/app/pages/group-settings/group-settings-tag-headers/group-settings-tags-csv-dialog/group-settings-tags-csv-dialog.component.ts:102`, `src/app/pages/task/task-create-dialog/task-create-dialog.component.ts:1243` and `:1582`, `src/app/services/task/task-suggestion-helper/task-suggestion-helper.service.ts:241`). The task dialog and the suggestion helper send `aiNewTag` `1` (`task-create-dialog.component.ts:1236`, `:1579`; `task-suggestion-helper.service.ts:237`).
* **Code:** api\_php\_live\_v2 @ ef3c4319f6, `routes/business.php:27`, `app/Http/Controllers/v1/Versions/v1_0/App/TagController.php:132-186`, `app/Http/Requests/v1/Tag/CreateMultipleTagRequest.php:15-18`, `app/Services/TagService.php:197-216`.

**Request** (JSON)

| Name                   | In   | Type    | Required        | Rules                                                                      |
| ---------------------- | ---- | ------- | --------------- | -------------------------------------------------------------------------- |
| `businessUuid`         | path | string  | yes             | The group. Its site gives the rights check, and its devices get the pushes |
| `tags`                 | body | array   | yes             | One item per tag; an empty array fails. No maximum count                   |
| `tags[].name`          | body | string  | yes             | Saved as `fName`; the server sets no length limit                          |
| `tags[].tagHeaderUuid` | body | string  | yes             | The folder the tag goes in. Only checked to be a string                    |
| `aiNewTag`             | body | integer | no; default `0` | `0` or `1`. Saved on every new tag; `1` marks the tags as made up by AI    |

```json
{
  "aiNewTag": 0,
  "tags": [
    { "name": "Lobby", "tagHeaderUuid": "123" },
    { "name": "Room 101", "tagHeaderUuid": "123" }
  ]
}
```

**Response** `200`: an array of [tag objects](#tag-object), one for each tag created. Skipped names are not listed, so an empty array means nothing was created.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": [
    { "uuid": "456", "name": "Lobby", "aiNewTag": 0 }
  ]
}
```

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `422` when `tags` is missing or empty, or a name or folder UUID is missing or isn't a string; `404` when the group isn't found; `403` "Access denied" for a caller who is not a tag manager of the group's site. A `tagHeaderUuid` that is no folder breaks the foreign key on `tPri_Tag.uuid_tTagHeader`, which gives `500`.

**Side effects:**

* Inserts one row per new tag into [`tPri_Tag`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_tag.md) with `uuid_tTagHeader`, `fName` and `aiNewTag`. `uuid_tBusiness` and `fVisible` stay `NULL`. A name already live in the folder is skipped; a name repeated within the same request is created twice. The Site Console's CSV import does not say that it skipped names.
* Queues one silent `TAG_ADDED` push per new tag to the group's device tokens.
* When the site has AI suggestions on (`fAiSuggestionEnabled`) and `aiNewTag` is `1`, writes one `log_ai_job` entry with category `tag-new` and the new tag UUIDs before it answers. Tags the AI made up stay in the group when the user unticks them in the task dialog.

## GET /v1/app/businesses/{uuid}/tags

Lists the tag folders a group sees, each with its live tags: the group's own live folders, and the live folders that a live rule of the group links with `fExcluded` 0. A linked folder is kept only when it is a folder of the group's site or of the group itself. Folders come in creation order, then by `sort_order`.

* **Auth:** user token. `BusinessPolicy::view`: a member of the group. Any multi-site user also passes, for any group, because the route passes no site (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Controllers/v1/Versions/v1_0/App/BusinessController.php:662-678`, `app/Policies/BusinessPolicy.php:22-25`).
* **Used by:** web (`TagHttpService.getTagsBySingleGroups`, web\_app\_v2 @ 0989b8e685, `src/app/services/tag/tag-http/tag-http.service.ts:50-64`; called from `src/app/components/filter-drawer/filter-tags/filter-tags.component.ts:193` and `src/app/pages/task/task-tags/task-tags-dialog/task-tags-dialog.component.ts:244`). snapfix\_ai\_agent (`list_tags`, snapfix\_ai\_agent @ e5e18caef5, `src/snapfix/tags/__init__.py:49-53`, which the task tools call from `src/agent/tools/tasks/__init__.py:835`, `:864`, `:1084` and `src/agent/tools/tasks/create.py:348`, `:376`).
* **Code:** api\_php\_live\_v2 @ ef3c4319f6, `routes/business.php:17`, `app/Models/BusinessModel.php:241-248`, `:261-292`, `app/Models/TagHeaderModel.php:61-80`.

**Request:** none. The group UUID is in the path (`uuid`, string, required). The list is not paged.

**Response** `200`: an array of [tag folder objects](#tag-folder-object), each with its live `tags`.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": [
    {
      "uuid": "123",
      "name": "Room cleaning",
      "description": null,
      "mandatory": 1,
      "tags": [
        { "uuid": "456", "name": "Lobby", "aiNewTag": 0 }
      ]
    }
  ]
}
```

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `404` "Resource not found" when the group isn't found; `403` "Access denied" when the caller can't view the group.

**Side effects:** none.

## POST /v1/app/parents/tags

Lists the tag folders and tags of several groups in one call, with no repeats. The folders are each listed group's own live folders and the folders a listed group's live rule links with `fExcluded` 0. A linked folder is kept only when it is a folder of the site of the first group found, or of a listed group. Each folder comes with its live tags.

* **Auth:** user token only. No policy and no membership check runs, so any signed-in user can read the folders and tags of any group whose UUID they send.
* **Used by:** web (`TagHttpService.getTagsByGroups`, web\_app\_v2 @ 0989b8e685, `src/app/services/tag/tag-http/tag-http.service.ts:26-44`; called from `src/app/components/filter-drawer/filter-tags/filter-tags.component.ts:194` when the task filter has more than one group).
* **Code:** api\_php\_live\_v2 @ ef3c4319f6, `routes/parents.php:28`, `app/Http/Controllers/v1/Versions/v1_0/App/TagController.php:44-63`, `app/Services/TagService.php:281-347`, `app/Http/Requests/v1/Tag/GetAllTagsRequest.php`.

**Request** (JSON, with `limit` and `offset` in the query string)

| Name            | In    | Type            | Required | Rules                                                                         |
| --------------- | ----- | --------------- | -------- | ----------------------------------------------------------------------------- |
| `businessUuids` | body  | array of string | yes      | Group UUIDs; non-empty. Unknown UUIDs are dropped. No maximum count           |
| `limit`         | query | integer         | no       | Page size, over folders. The answer is paged only when it is sent; no maximum |
| `offset`        | query | integer         | no       | Page number from 1. Used only with `limit`                                    |

```json
{ "businessUuids": ["123", "124"] }
```

**Response** `200`: `tagHeaders` is a list of [folder summary objects](#folder-summary-object). `pagination` appears only when `limit` is sent.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "tagHeaders": [
      {
        "name": "Room cleaning",
        "description": null,
        "tags": [
          { "uuid": "456", "name": "Lobby", "aiNewTag": 0 }
        ]
      }
    ],
    "pagination": { "total": 1, "perPage": 10, "currentPage": 1, "lastPage": 1, "from": 1, "to": 1 }
  }
}
```

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `422` when `businessUuids` is missing or empty, or an item isn't a string. When none of the UUIDs is a group, the code reads the site of a group that doesn't exist and the request fails with `500`.

**Side effects:** none. Every call loads all live tags of the folders found and pages in memory; without `limit`, the whole list comes back in one answer.

## POST /v1/app/tag-headers/delete/multi

Soft-deletes the named tag folders of a site: the same folders that the [preview](#post-v1apptag-headersdeletepreview) counts. The web runs the preview first.

* **Auth:** user token. `ParentPolicy::operate`: a site admin of `parentUuid`. Folders outside the site are skipped, so this route cannot reach another site.
* **Used by:** web (`TagHttpService.deleteTagFoldersMulti`, web\_app\_v2 @ 0989b8e685, `src/app/services/tag/tag-http/tag-http.service.ts:254-261`; called from `src/app/pages/account-settings/account-settings-manage-tags/account-settings-manage-tags-list/account-settings-manage-tags-list.component.ts:422`).
* **Code:** api\_php\_live\_v2 @ ef3c4319f6, `routes/app.php:29`, `routes/tagHeader.php:13`, `app/Traits/Tag/TagHeaderMultiActions.php:46-62`, `app/Services/TagHeaderService.php:225-274`.

**Request** (JSON)

| Name         | In   | Type            | Required | Rules                                                                                                                                                                          |
| ------------ | ---- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `parentUuid` | body | string          | yes      | The site                                                                                                                                                                       |
| `uuids`      | body | array of string | yes      | Folder UUIDs, at least one. A UUID counts only when it is a live folder of the site (`uuid_tParent` or `uuid_tBusiness` equal to the site) or of one of the site's live groups |

```json
{ "parentUuid": "100", "uuids": ["123", "124"] }
```

**Response** `200`: `total` is the number of folders deleted.

```json
{
  "status": "success",
  "message": "2 folders deleted successfully",
  "data": { "total": 2 }
}
```

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `422` when `parentUuid` or `uuids` is missing, or `uuids` is empty; `403` "Access denied" for a caller who isn't a site admin.

**Side effects:**

* Sets `fDeleted` on each valid folder in [`tPri_TagHeader`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_tagheader.md), one update per folder. The folders' tags keep `fDeleted` 0, and no task tag or rule changes: the models have no delete hooks.
* The delete does not check the preview's `requiresConfirmation`.

## POST /v1/app/tag-headers/delete/preview

Counts what deleting the named tag folders would remove. It changes nothing.

* **Auth:** user token. `ParentPolicy::operate`: a site admin of `parentUuid`.
* **Used by:** web (`TagHttpService.deleteTagFoldersPreview`, web\_app\_v2 @ 0989b8e685, `src/app/services/tag/tag-http/tag-http.service.ts:245-252`; called from `src/app/pages/account-settings/account-settings-manage-tags/account-settings-manage-tags-list/account-settings-manage-tags-list.component.ts:381`).
* **Code:** api\_php\_live\_v2 @ ef3c4319f6, `routes/tagHeader.php:12`, `app/Traits/Tag/TagHeaderMultiActions.php:23-37`, `app/Services/TagHeaderBulkDeleteService.php:26-63`, `app/Services/JobTagService.php:191-206`.

**Request** (JSON): the same fields as [delete/multi](#post-v1apptag-headersdeletemulti).

**Response** `200`: a [delete preview object](#delete-preview-object).

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "folderCount": 2,
    "emptyFolderCount": 1,
    "tagCount": 5,
    "affectedTaskCount": 3,
    "requiresConfirmation": true
  }
}
```

**Errors:** as for [delete/multi](#post-v1apptag-headersdeletemulti).

**Side effects:** none.

## POST ?action=delete\_tag\_folder

Soft-deletes one tag folder. Its tags and group rules are not changed.

* **Auth:** user token. A site admin of `parentUUID`. The folder is found by its UUID on any site, so a site admin can delete another site's folder.
* **Used by:** web (`TagHttpService.deleteTagFolder`, web\_app\_v2 @ 0989b8e685, `src/app/services/tag/tag-http/tag-http.service.ts:173-180`; called from `src/app/pages/account-settings/account-settings-manage-tags/account-settings-manage-tags-header/account-settings-manage-tags-header.component.ts:114`). When the delete fails, the web also shows a raw translation key.
* **Code:** php-apis @ 238ca4414e, `html/api/snapfix/index.php:764`, `htmlphp/api/snapfix/class/class.functions.php:46725-46754`.

**Request** (JSON)

| Name         | In   | Type   | Required | Rules                           |
| ------------ | ---- | ------ | -------- | ------------------------------- |
| `parentUUID` | body | string | yes      | The site the caller administers |
| `folderUUID` | body | string | yes      | The folder to delete            |

**Response** `200`:

```json
{
  "result": true,
  "message": "Tag folder deleted successfully",
  "serverTs": 1794387595000
}
```

**Errors:** `200` with `result` `false`:

* "invalid params!" when `parentUUID` or `folderUUID` is missing or empty.
* "invalid access!" when the caller is not a site admin.
* "Tag folder not found" when no live folder has the UUID.

**Side effects:** sets `fDeleted` on the folder's row in [`tPri_TagHeader`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_tagheader.md).

## POST ?action=delete\_tags

Soft-deletes tags by UUID. Tags of any folder and any site can be named.

* **Auth:** user token. A site admin of `parentUUID`. The tags are found by UUID on any site, and `folderUUID` is not used.
* **Used by:** web (`TagHttpService.deleteTags`, web\_app\_v2 @ 0989b8e685, `src/app/services/tag/tag-http/tag-http.service.ts:200-207`; called from `src/app/pages/account-settings/account-settings-manage-tags/account-settings-manage-tags-dialog/account-settings-manage-tags-dialog.component.ts:1323`).
* **Code:** php-apis @ 238ca4414e, `html/api/snapfix/index.php:772`, `htmlphp/api/snapfix/class/class.functions.php:46681-46723`.

**Request** (JSON)

| Name         | In   | Type            | Required | Rules                              |
| ------------ | ---- | --------------- | -------- | ---------------------------------- |
| `parentUUID` | body | string          | yes      | The site the caller administers    |
| `folderUUID` | body | string          | yes      | Required, but not used             |
| `tags`       | body | array of string | yes      | The tag UUIDs to delete; non-empty |

```json
{ "parentUUID": "100", "folderUUID": "123", "tags": ["456"] }
```

**Response** `200`: `result` `true` and "Tags deleted successfully". No `data`.

**Errors:** `200` with `result` `false`:

* "invalid params!" when `parentUUID`, `folderUUID` or `tags` is missing, empty or not a list.
* "invalid access!" when the caller is not a site admin.
* "Tags not found" when no live tag has any of the UUIDs.

**Side effects:** sets `fDeleted` on each live tag found in [`tPri_Tag`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_tag.md). The task tag links in [`tPri_JobTag`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtag.md) are not changed, while the unused Laravel `DELETE …/tags/{tagUuid}` deletes them (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Controllers/v1/Versions/v1_0/App/TagController.php:314-346`) \[[ASK-233](https://github.com/snapfix/docs/blob/main/ASK.md#ask-233-should-deleting-a-tag-remove-its-links-to-tasks)].

## POST ?action=merge\_tag\_folders

Merges two tag folders into a new site folder. The new folder gets one tag for each distinct name in the two folders. The task tags move to the new tags in a step that runs after the response. The old folders are soft-deleted and marked for the undo.

* **Auth:** user token. A site admin of `parentUUID`. Both folders are found by UUID on any site. The unused undo action, `merge_tag_folders_undo`, checks nothing.
* **Used by:** web (`TagHttpService.mergeTagFolders`, web\_app\_v2 @ 0989b8e685, `src/app/services/tag/tag-http/tag-http.service.ts:218-225`; called from `src/app/pages/account-settings/account-settings-manage-tags/account-settings-manage-tags-dialog/account-settings-manage-tags-dialog.component.ts:998`, through the local `mergeTagFolders` at `:583`, `:586`, `:628` and `:631`).
* **Code:** php-apis @ 238ca4414e, `html/api/snapfix/index.php:788`, `:4397-4401`, `:4497-4501`, `htmlphp/api/snapfix/class/class.functions.php:46851-46979`, `:46981-47142`.

**Request** (JSON)

| Name                | In   | Type   | Required | Rules                                                           |
| ------------------- | ---- | ------ | -------- | --------------------------------------------------------------- |
| `parentUUID`        | body | string | yes      | The site the caller administers. The new folder is created here |
| `from_folderUUID`   | body | string | yes      | The source folder. Must be a live folder                        |
| `to_folderUUID`     | body | string | yes      | The destination folder. Must be a live folder                   |
| `folderName`        | body | string | no       | The new folder's name. Defaults to the destination's name       |
| `folderDescription` | body | string | no       | The new folder's description. Defaults to the destination's     |

```json
{ "parentUUID": "100", "from_folderUUID": "123", "to_folderUUID": "124", "folderName": "Room cleaning" }
```

**Response** `200`: the new folder's UUID. The function also returns `metadata` for the background step, but the dispatcher removes it before answering.

```json
{
  "result": true,
  "message": "Merging of tags initiated successfully. It will take sometime to reflect into the group tasks.",
  "data": { "new_folderUUID": "125" },
  "serverTs": 1794387595000
}
```

**Errors:** `200` with `result` `false`:

* "invalid params!" when `parentUUID`, `from_folderUUID` or `to_folderUUID` is missing or empty.
* "invalid access!" when the caller is not a site admin.
* "invalid Source Tag Folder!" or "invalid Destination Tag Folder!" when that folder is not live.

**Side effects:**

1. Inserts a new folder in [`tPri_TagHeader`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_tagheader.md): a copy of the destination row with the optional name and description, `uuid_tParent` set to `parentUUID` and no group.
2. Inserts one tag per distinct name of the two folders' live tags into [`tPri_Tag`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_tag.md), sorted by name with `sort_order` 1000, 2000 and so on, `fVisible` 1, in batches of 1000. Destination names are trimmed; source names are not. The old tags are not changed.
3. Soft-deletes both old folders and sets their `fDevComment` to the new folder's UUID, which the undo uses.
4. After the response, `mergeTagFolders_asyncTask` loads every live task tag of the old tags, points them at the new tags in [`tPri_JobTag`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtag.md), writes a row per change to [`tPri_JobTag_Log`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtag_log.md), and soft-deletes duplicate task tags. It then writes rules on the new folder for both old folders' owner groups and for every group with a live, non-excluded rule on either folder, keeping `fMandatory`.
5. The step runs inside a `try` with an empty `catch`. If it fails, the task tags stay on the old folders' tags, which are now in deleted folders, and nothing retries.

## POST ?action=move\_tags

Moves tags from one folder to another, together with their task links.

* **Auth:** user token. A site admin of `parentUUID`. Neither folder is checked against the site.
* **Used by:** web (`TagHttpService.moveTags`, web\_app\_v2 @ 0989b8e685, `src/app/services/tag/tag-http/tag-http.service.ts:209-216`; called from `src/app/pages/account-settings/account-settings-manage-tags/account-settings-manage-tags-dialog/account-settings-manage-tags-dialog.component.ts:1387`).
* **Code:** php-apis @ 238ca4414e, `html/api/snapfix/index.php:780`, `htmlphp/api/snapfix/class/class.functions.php:46756-46849`.

**Request** (JSON)

| Name              | In   | Type            | Required | Rules                                     |
| ----------------- | ---- | --------------- | -------- | ----------------------------------------- |
| `parentUUID`      | body | string          | yes      | The site the caller administers           |
| `from_folderUUID` | body | string          | yes      | The source folder                         |
| `to_folderUUID`   | body | string          | yes      | The destination folder                    |
| `tags`            | body | array of string | yes      | Tag UUIDs in the source folder; non-empty |

```json
{ "parentUUID": "100", "from_folderUUID": "123", "to_folderUUID": "124", "tags": ["456"] }
```

**Response** `200`: `result` `true` and "Tags saved successfully". No `data`.

**Errors:** `200` with `result` `false`:

* "invalid params!" when a field is missing or `tags` is empty or not a list.
* "invalid access!" when the caller is not a site admin.
* "Tags not found" when none of the UUIDs is a live tag of the source folder.

**Side effects:**

* For each tag, a destination tag with the same name is reused, and restored if it was deleted. Otherwise a new tag with that name is inserted in the destination with `fVisible` 1 and `sort_order` 1000, not the source tag's order.
* Points the live task tags of each moved tag at the destination tag in [`tPri_JobTag`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtag.md). No `tPri_JobTag_Log` row is written, so a move cannot be undone.
* Soft-deletes the source tags.

## POST ?action=read\_business\_tag\_folders

Lists every live folder of a site (the site's own folders and those of its live groups) with `excluded` for one group. The group's tag folder settings and the mobile folder picker use it.

* **Auth:** user token. A tag manager of `parentUUID`. The group is not checked against the site, so a group of another site can be named.
* **Used by:** web (`TagHttpService.getBusinessTagFolders`, web\_app\_v2 @ 0989b8e685, `src/app/services/tag/tag-http/tag-http.service.ts:227-234`; called from `src/app/pages/group-settings/group-tag-header-dialog/group-tag-header-dialog.component.ts:129`). iOS (`READ_BUSINESS_TAG_FOLDERS`, ios @ aa31967ac8, `APIManagers/APIManager.swift:371`; `SnapFix/Tagging/View Contollers/TagFolderVC.swift:700`). Android (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/viewModels/TagFolderViewModel.kt:42-52`, from `app/src/main/java/gmail/com/snapfixapp/bottomSheet/TagFolderSelectionBottomSheet.kt:176`).
* **Code:** php-apis @ 238ca4414e, `html/api/snapfix/index.php:700`, `htmlphp/api/snapfix/class/class.functions.php:45994-46144`.

**Request** (JSON)

| Name           | In   | Type    | Required | Rules                                                                                           |
| -------------- | ---- | ------- | -------- | ----------------------------------------------------------------------------------------------- |
| `parentUUID`   | body | string  | yes      | The site                                                                                        |
| `businessUUID` | body | string  | yes      | The group                                                                                       |
| `limit`        | body | integer | no       | Page size, default 100. Turns paging on when above 0                                            |
| `offset`       | body | integer | no       | Page index from 0: the answer skips `offset` × `limit` folders. Turns paging on when above 0    |
| `search`       | body | string  | no       | Matches the folder's name or description. Put into the SQL as sent, as are `limit` and `offset` |

The web and Android always send `limit` and `offset`.

**Response** `200`: with paging, `data` is `{tagFolders, totalCount}`; without it, `data` is the list. Each item is a [php-apis folder object](#php-apis-folder-object) with `excluded`. With no folders, the list is `null` instead of empty.

```json
{
  "result": true,
  "message": "Tag folders fetched successfully",
  "data": {
    "tagFolders": [
      { "folderUUID": "123", "folderName": "Room cleaning", "folderDescription": "Room 101", "sortOrder": 1000, "tagCount": 4, "excluded": 0 }
    ],
    "totalCount": 1
  },
  "serverTs": 1794387595000
}
```

**Errors:** `200` with `result` `false` and "invalid access!" when `parentUUID` or `businessUUID` is missing or empty, or the caller is not a tag manager.

**Side effects:** none.

## POST ?action=read\_folder\_groups

Lists every live task group of a site, with `groupDisabled` for one folder.

* **Auth:** user token. A site admin of `parentUUID`. The folder is found by UUID on any site.
* **Used by:** web (`TagHttpService.getFolderGroups`, web\_app\_v2 @ 0989b8e685, `src/app/services/tag/tag-http/tag-http.service.ts:155-162`; called from `src/app/pages/account-settings/account-settings-manage-tags/account-settings-manage-tag-groups/account-settings-manage-tag-groups.component.ts:169`).
* **Code:** php-apis @ 238ca4414e, `html/api/snapfix/index.php:716`, `htmlphp/api/snapfix/class/class.functions.php:46202-46257`.

**Request** (JSON)

| Name         | In   | Type   | Required | Rules                           |
| ------------ | ---- | ------ | -------- | ------------------------------- |
| `parentUUID` | body | string | yes      | The site the caller administers |
| `folderUUID` | body | string | yes      | The folder                      |

**Response** `200`: `data` is a list of [folder group objects](#folder-group-object). A folder a group owns is on for that group only. Any other folder is on for each group with a live rule that has `fExcluded` 0, and off for the rest.

```json
{
  "result": true,
  "message": "Groups fetched successfully",
  "data": [
    { "groupUUID": "456", "groupName": "Room 101", "groupImage": null, "groupDisabled": 0 }
  ],
  "serverTs": 1794387595000
}
```

**Errors:** `200` with `result` `false`:

* "invalid access!" when a field is missing or the caller is not a site admin.
* "Folder not found" when no live folder has the UUID.

**Side effects:** none.

## POST ?action=read\_folder\_tags

Lists the live tags of one folder, with the number of tasks that use each tag.

* **Auth:** user token. The code checks only that `parentUUID` and `folderUUID` are present; the rights check is commented out. Any signed-in user who sends a folder UUID gets that folder's tags and task counts, from any site.
* **Used by:** web (`TagHttpService.getFolderTags`, web\_app\_v2 @ 0989b8e685, `src/app/services/tag/tag-http/tag-http.service.ts:146-153`; called from `src/app/pages/account-settings/account-settings-manage-tags/account-settings-manage-tags-list/account-settings-manage-tags-list.component.ts:232` and `src/app/pages/account-settings/account-settings-manage-tags/account-settings-manage-tags-dialog/account-settings-manage-tags-dialog.component.ts:678`).
* **Code:** php-apis @ 238ca4414e, `html/api/snapfix/index.php:708`, `htmlphp/api/snapfix/class/class.functions.php:46146-46200`.

**Request** (JSON)

| Name         | In   | Type   | Required | Rules                        |
| ------------ | ---- | ------ | -------- | ---------------------------- |
| `parentUUID` | body | string | yes      | Must be present; not checked |
| `folderUUID` | body | string | yes      | The folder                   |

**Response** `200`: `data` is a list of [folder tag objects](#folder-tag-object), ordered by `sort_order` and then by name.

```json
{
  "result": true,
  "message": "Tags fetched successfully",
  "data": [
    { "tagUUID": "456", "tagName": "Lobby", "tagSortOrder": 1000, "jobCount": 3 }
  ],
  "serverTs": 1794387595000
}
```

**Errors:** `200` with `result` `false` and "invalid access!" when `parentUUID` or `folderUUID` is missing or empty.

**Side effects:** none.

## POST ?action=read\_parent\_tag\_data

Reads the tag folders, tags and group rules of one or more sites in one answer. The apps use it to fill their local tag data at sign-in and in the database migration.

* **Auth:** user token. Each site must pass `hasParentReadAccess`: the caller has a membership row on the site, or a live membership in one of its live groups. One site failing fails the whole request.
* **Used by:** iOS (`readTagData`, ios @ aa31967ac8, `APIManagers/APIManager.swift:314`, `:1581-1582`, run from `fetchAllParentSubData` at `:1673-1690`; `SVProgressHUD/MigrationHelper.swift:572`). Android (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/service/LoginSubDataWork.kt:141`, a sign-in step that sends no user UUID; `app/src/main/java/gmail/com/snapfixapp/viewModels/BusinessViewModel.java:688-698`; `app/src/main/java/gmail/com/snapfixapp/service/DbMigrationDataService.kt:1623-1641`).
* **Code:** php-apis @ 238ca4414e, `html/api/snapfix/index.php:675`, `htmlphp/api/snapfix/class/class.functions.php:45759-45774`, `:47303-47361`.

**Request** (JSON)

| Name           | In   | Type            | Required | Rules                                                             |
| -------------- | ---- | --------------- | -------- | ----------------------------------------------------------------- |
| `parent_uuids` | body | array of string | yes      | The sites; at least one. Duplicates are removed. No maximum count |

```json
{ "parent_uuids": ["100"] }
```

**Response** `200`: `data` holds three lists with every column of their table, from the read-only database. The whole set comes back in one answer, with no paging and no changed-since filter.

| Key                          | Rows                                                                                                                       |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `tPri_TagHeader`             | The folders of the sites and of their live groups. No filter on `fDeleted`, so deleted folders come back with `fDeleted` 1 |
| `tPri_Tag`                   | Live tags of those folders                                                                                                 |
| `tPri_BusinessTagHeaderRule` | Live rules of those folders                                                                                                |

```json
{
  "result": true,
  "message": "SUCCESS",
  "data": {
    "tPri_TagHeader": [
      { "uuid": "123", "uuid_tParent": "100", "uuid_tBusiness": null, "fName": "Room cleaning", "sort_order": 1000, "fDeleted": 0 }
    ],
    "tPri_Tag": [
      { "uuid": "456", "uuid_tTagHeader": "123", "fName": "Lobby", "fVisible": 1, "sort_order": 1000, "fDeleted": 0 }
    ],
    "tPri_BusinessTagHeaderRule": [
      { "uuid": "789", "uuid_tTagHeader": "123", "uuid_tBusiness": "200", "fExcluded": 0, "fMandatory": 1, "fDeleted": 0 }
    ]
  },
  "serverTs": 1794387595000
}
```

When no folder matches, the answer is `{"result": true, "message": "No data found"}` with no `data`.

**Errors:** `200` with `result` `false`:

* "invalid parent uuids" when `parent_uuids` is missing, not a list or empty.
* "invalid access!" when the caller can't read one of the sites.

**Side effects:** none.

## POST ?action=read\_parent\_tag\_folders

Lists a site's tag folders, newest first, for the Site Console's tag list and the folder pickers of the tag editor. A site admin gets the live folders of the site and of its live groups. Any other member gets only the live folders of the live groups they belong to, never the site's own folders.

* **Auth:** user token. A caller who is not a site admin and belongs to no live group of the site gets "invalid access!".
* **Used by:** web (`TagHttpService.getParentTagFolders`, web\_app\_v2 @ 0989b8e685, `src/app/services/tag/tag-http/tag-http.service.ts:137-144`; called from `src/app/pages/account-settings/account-settings-manage-tags/account-settings-manage-tags-list/account-settings-manage-tags-list.component.ts:161` and `src/app/pages/account-settings/account-settings-manage-tags/account-settings-manage-tags-dialog/account-settings-manage-tags-dialog.component.ts:1449`).
* **Code:** php-apis @ 238ca4414e, `html/api/snapfix/index.php:692`, `htmlphp/api/snapfix/class/class.functions.php:45776-45992`.

**Request** (JSON)

| Name         | In   | Type    | Required | Rules                                                                                                                                                   |
| ------------ | ---- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parentUUID` | body | string  | yes      | The site                                                                                                                                                |
| `limit`      | body | integer | no       | Page size, default 100. Turns paging on when above 0                                                                                                    |
| `offset`     | body | integer | no       | Page index from 0: the answer skips `offset` × `limit` folders. Turns paging on when above 0                                                            |
| `search`     | body | string  | no       | Matches the folder's name or description, or the name of the group that owns or links the folder. Put into the SQL as sent, as are `limit` and `offset` |

The web always sends `limit` and `offset`.

**Response** `200`: with paging, `data` is `{tagFolders, totalCount}`; without it, `data` is the list. Each item is a [php-apis folder object](#php-apis-folder-object) without `excluded`. With no folders, the list is `null` instead of empty.

```json
{
  "result": true,
  "message": "Tag folders fetched successfully",
  "data": {
    "tagFolders": [
      { "folderUUID": "123", "folderName": "Room cleaning", "folderDescription": "Room 101", "sortOrder": 1000, "tagCount": 4 }
    ],
    "totalCount": 1
  },
  "serverTs": 1794387595000
}
```

**Errors:** `200` with `result` `false` and "invalid access!" when `parentUUID` is missing or empty, or the caller has no access as above.

**Side effects:** none.

## POST ?action=save\_business\_tag\_header\_rule

Saves group rule rows of tag folders as the apps' sync sends them. It is the generic table save for [`tPri_BusinessTagHeaderRule`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_businesstagheaderrule.md); the three other `save_pri_*` sections below work the same way.

* **Auth:** user token. The rows are not checked against the caller's sites or groups.
* **Used by:** iOS (`SAVE_PRI_BUSINESSTAGHEADERRULE`, ios @ aa31967ac8, `APIManagers/APIManager.swift:45`; `Managers/TaskManager.swift:927`, from `:202`). Android (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/data/repository/SyncRepository.kt:730`).
* **Code:** php-apis @ 238ca4414e, `html/api/snapfix/index.php:683-690`, `htmlphp/api/snapfix/class/class.functions.php:38826-38964` (`redirectSavePriCalls`), `:749-1225` (`saveIntoTable`).

**Request** (JSON): the generic table body ([Requests](https://docs.snapfix.com/engineering-reference/api.md#requests)).

| Name          | In   | Type  | Required | Rules                                                                                                                                                                                |
| ------------- | ---- | ----- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `insert_data` | body | array | yes      | The rows, each with the columns of [`tPri_BusinessTagHeaderRule`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_businesstagheaderrule.md). Values are stored as sent |

```json
{
  "insert_data": [
    { "uuid": "789", "uuid_tTagHeader": "123", "uuid_tBusiness": "200", "fExcluded": 0, "fMandatory": 1, "fDeleted": 0 }
  ]
}
```

**Response** `200`: a [save result object](https://docs.snapfix.com/engineering-reference/api/tasks.md#save-result-object-php-apis). When `LEGACY_QUEUE_SUPPORT` is on, every row is queued and counted as inserted \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)].

**Errors:**

* An empty body answers `result` `false` with "Data cannot be blank!".
* A body without `insert_data` fails with a PHP error and a `500` with no JSON body. With `LEGACY_QUEUE_SUPPORT` on, it answers `result` `false` instead.

**Side effects:**

* Upserts the rows by `uuid`: a row whose `uuid` exists is updated with the fields sent, and any other row is inserted.
* After the response, the dispatcher processes the log queue (`shouldProcessQueue`).

## POST ?action=save\_folder\_groups

Sets which groups a folder is on or off for, with `excluded` and `mandatory` per group, and makes the folder a site folder of `parentUUID`.

* **Auth:** user token. A site admin of `parentUUID`. The folder is found by UUID on any site, so another site's folder, or another group's, can be moved into this site.
* **Used by:** web (`TagHttpService.saveFolderGroups`, web\_app\_v2 @ 0989b8e685, `src/app/services/tag/tag-http/tag-http.service.ts:182-189`; called from `src/app/pages/account-settings/account-settings-manage-tags/account-settings-manage-tag-groups/account-settings-manage-tag-groups.component.ts:94`).
* **Code:** php-apis @ 238ca4414e, `html/api/snapfix/index.php:748`, `htmlphp/api/snapfix/class/class.functions.php:46433-46556`.

**Request** (JSON)

| Name                 | In   | Type    | Required | Rules                                                                                                                                   |
| -------------------- | ---- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `parentUUID`         | body | string  | yes      | The site the caller administers                                                                                                         |
| `folderUUID`         | body | string  | yes      | A live folder                                                                                                                           |
| `groups`             | body | array   | yes      | One item per group; non-empty                                                                                                           |
| `groups[].uuid`      | body | string  | yes      | The group. Not checked against the site                                                                                                 |
| `groups[].excluded`  | body | integer | no       | `1` turns the folder off for the group, `0` on. Any other value keeps the current flag; a new rule starts at `0`                        |
| `groups[].mandatory` | body | integer | no       | `1` makes a tag from the folder required for the group, `0` clears it. Any other value keeps the current flag; a new rule starts at `0` |

```json
{ "parentUUID": "100", "folderUUID": "123", "groups": [ { "uuid": "200", "excluded": 0, "mandatory": 1 } ] }
```

**Response** `200`: `result` `true` and "Permissions saved successfully". No `data`.

**Errors:** `200` with `result` `false`:

* "invalid params!" when `parentUUID`, `folderUUID` or `groups` is missing or empty, or a group item has no `uuid`.
* "invalid access!" when the caller is not a site admin.
* "tag header not found!" when no live folder has the UUID.

**Side effects:**

* Updates each group's live rule in place in [`tPri_BusinessTagHeaderRule`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_businesstagheaderrule.md), or inserts one when the group has none.
* If a group owned the folder and had no live rule for it, inserts a rule for that owner with both flags `0`.
* Sets `uuid_tBusiness` to `NULL` and `uuid_tParent` to `parentUUID` on the folder in [`tPri_TagHeader`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_tagheader.md), whatever it was before.

## POST ?action=save\_group\_folders

Sets which tag folders a group uses, by writing the group's rules. Folders change owner on the way: a folder the group owns and excludes, and every folder the group doesn't own, become site folders of `parentUUID`.

* **Auth:** user token. A tag manager of `parentUUID`. The group and the folders are found by UUID on any site, and the folders even when deleted, so another site's folder can be taken over.
* **Used by:** web (`TagHttpService.saveBusinessTagFolders`, web\_app\_v2 @ 0989b8e685, `src/app/services/tag/tag-http/tag-http.service.ts:236-243`; called from `src/app/pages/group-settings/group-tag-header-dialog/group-tag-header-dialog.component.ts:90`).
* **Code:** php-apis @ 238ca4414e, `html/api/snapfix/index.php:756`, `htmlphp/api/snapfix/class/class.functions.php:46558-46679`.

**Request** (JSON)

| Name                 | In   | Type    | Required | Rules                                                                                                                                                                                                                |
| -------------------- | ---- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parentUUID`         | body | string  | yes      | The site                                                                                                                                                                                                             |
| `businessUUID`       | body | string  | yes      | A live group. Not checked against the site                                                                                                                                                                           |
| `folders`            | body | array   | yes      | One item per folder; non-empty                                                                                                                                                                                       |
| `folders[].uuid`     | body | string  | yes      | The folder. A UUID that is no folder still gets a rule \[[ASK-232](https://github.com/snapfix/docs/blob/main/ASK.md#ask-232-what-should-a-groups-folder-save-do-with-folders-owned-by-another-group-or-by-the-site)] |
| `folders[].excluded` | body | integer | yes      | `0` or `1`; any other value fails with "invalid params!"                                                                                                                                                             |

```json
{ "parentUUID": "100", "businessUUID": "200", "folders": [ { "uuid": "123", "excluded": 0 } ] }
```

**Response** `200`: `result` `true` and "Folder Permissions saved successfully". No `data`.

**Errors:** `200` with `result` `false`:

* "invalid params!" when `parentUUID`, `businessUUID` or `folders` is missing or empty, or a folder item lacks `uuid` or has an `excluded` other than `0` or `1`.
* "invalid access!" when the caller is not a tag manager.
* "business not found!" when no live group has the UUID.

**Side effects:**

* A folder the group owns, with `excluded` `1`: sets `uuid_tBusiness` to `NULL` and `uuid_tParent` to `parentUUID` in [`tPri_TagHeader`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_tagheader.md).
* A folder the group doesn't own: sets it to a site folder of `parentUUID` the same way, soft-deletes the old owner's live rules for it, and inserts a rule for the old owner with the `excluded` value sent for this group. For a site folder, the old owner is `NULL`, so a rule with no group is written \[[ASK-232](https://github.com/snapfix/docs/blob/main/ASK.md#ask-232-what-should-a-groups-folder-save-do-with-folders-owned-by-another-group-or-by-the-site)].
* The group's own rule in [`tPri_BusinessTagHeaderRule`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_businesstagheaderrule.md): an enabled live rule (`fExcluded` 0) with `excluded` `1` is set to excluded; an enabled rule with `0` is left as it is. Otherwise the group's live rules for the folder are soft-deleted and a new rule is inserted with the sent `excluded`.

## POST ?action=save\_pri\_job\_tag

Saves task tags, the rows of [`tPri_JobTag`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtag.md), as the apps' sync sends them. It is the generic table save described in [save\_business\_tag\_header\_rule](#post-actionsave_business_tag_header_rule).

* **Auth:** user token. The rows are not checked against the caller's tasks or groups.
* **Used by:** iOS (`SAVE_PRI_JOB_TAG`, ios @ aa31967ac8, `APIManagers/APIManager.swift:50`; `Managers/TaskManager.swift:1630`). Android (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/data/repository/SyncRepository.kt:335`).
* **Code:** php-apis @ 238ca4414e, `html/api/snapfix/index.php:4013`, `htmlphp/api/snapfix/class/class.functions.php:775`, `:1218-1222`.

**Request** (JSON): `insert_data`, rows with the columns of [`tPri_JobTag`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtag.md).

```json
{ "insert_data": [ { "uuid": "901", "uuid_tJob": "300", "uuid_tTag": "456", "fDeleted": 0 } ] }
```

**Response** `200`: a [save result object](https://docs.snapfix.com/engineering-reference/api/tasks.md#save-result-object-php-apis).

**Errors:** an empty body answers `{"success": "0", "message": "Data cannot be blank!"}`. A body without `insert_data` fails as in [save\_business\_tag\_header\_rule](#post-actionsave_business_tag_header_rule).

**Side effects:** upserts the rows by `uuid`. Foreign key checks are off while this table is saved, and back on in a `finally` block, so a row can name a task or tag that does not exist, the same pattern as task chat. The log queue runs after the response.

## POST ?action=save\_pri\_tag

Saves tags, the rows of [`tPri_Tag`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_tag.md), as the apps' sync sends them. It is the generic table save described in [save\_business\_tag\_header\_rule](#post-actionsave_business_tag_header_rule).

* **Auth:** user token. The rows are not checked against the caller's folders or site.
* **Used by:** iOS (`SAVE_PRI_TAG`, ios @ aa31967ac8, `APIManagers/APIManager.swift:46`; `Managers/TaskManager.swift:1230`). Android (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/data/repository/SyncRepository.kt:169`).
* **Code:** php-apis @ 238ca4414e, `html/api/snapfix/index.php:3712-3720`, `htmlphp/api/snapfix/class/class.functions.php:832-848`.

**Request** (JSON): `insert_data`, rows with the columns of [`tPri_Tag`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_tag.md).

```json
{ "insert_data": [ { "uuid": "456", "uuid_tTagHeader": "123", "fName": "Lobby", "sort_order": 1000, "fVisible": 1, "fDeleted": 0 } ] }
```

**Response** `200`: a [save result object](https://docs.snapfix.com/engineering-reference/api/tasks.md#save-result-object-php-apis).

**Errors:** an empty body answers `{"success": "0", "message": "Data cannot be blank!"}`. A body without `insert_data` fails as in [save\_business\_tag\_header\_rule](#post-actionsave_business_tag_header_rule).

**Side effects:** upserts the rows by `uuid`. Each row's `uuid_tBusiness` is filled from its folder. A row can move a tag into any folder, because `uuid_tTagHeader` is stored as sent. The log queue runs after the response.

## POST ?action=save\_pri\_tag\_header

Saves tag folders, the rows of [`tPri_TagHeader`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_tagheader.md), as the apps' sync sends them. It is the generic table save described in [save\_business\_tag\_header\_rule](#post-actionsave_business_tag_header_rule).

* **Auth:** user token. The rows are not checked against the caller's site or groups.
* **Used by:** iOS (`SAVE_PRI_TAG_HEADER`, ios @ aa31967ac8, `APIManagers/APIManager.swift:43`; `Managers/TaskManager.swift:1157`, from `:206` and `:813`). Android (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/data/repository/SyncRepository.kt:153`).
* **Code:** php-apis @ 238ca4414e, `html/api/snapfix/index.php:3674`.

**Request** (JSON): `insert_data`, rows with the columns of [`tPri_TagHeader`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_tagheader.md).

```json
{ "insert_data": [ { "uuid": "123", "uuid_tParent": "100", "uuid_tBusiness": null, "fName": "Room cleaning", "fDeleted": 0 } ] }
```

**Response** `200`: a [save result object](https://docs.snapfix.com/engineering-reference/api/tasks.md#save-result-object-php-apis).

**Errors:** an empty body answers `{"success": "0", "message": "Data cannot be blank!"}`. A body without `insert_data` fails as in [save\_business\_tag\_header\_rule](#post-actionsave_business_tag_header_rule).

**Side effects:** upserts the rows by `uuid`. The log queue runs after the response.

## POST ?action=save\_tag\_folders

Creates or renames site tag folders in one call. A live folder whose UUID is sent is updated; any other item with a name is created as a site folder.

* **Auth:** user token. A tag manager of `parentUUID`. Folder UUIDs are looked up and updated on any site, so a tag manager of one site can rename another site's folder.
* **Used by:** web (`TagHttpService.createTagFolder`, web\_app\_v2 @ 0989b8e685, `src/app/services/tag/tag-http/tag-http.service.ts:164-171`; called from `src/app/pages/account-settings/account-settings-manage-tags/account-settings-manage-tags-create-folder-dialog/account-settings-manage-tags-create-folder-dialog.component.ts:152`, which sends a `uuid` only when renaming).
* **Code:** php-apis @ 238ca4414e, `html/api/snapfix/index.php:732`, `htmlphp/api/snapfix/class/class.functions.php:46259-46332`.

**Request** (JSON)

| Name                    | In   | Type   | Required | Rules                                                                                                       |
| ----------------------- | ---- | ------ | -------- | ----------------------------------------------------------------------------------------------------------- |
| `parentUUID`            | body | string | yes      | The site. New folders are created here                                                                      |
| `folders`               | body | array  | yes      | One item per folder; non-empty                                                                              |
| `folders[].uuid`        | body | string | no       | A live folder is updated. Any other UUID creates a folder with it. Leave it out for a new folder            |
| `folders[].name`        | body | string | no       | Sets `fName` when non-empty. A folder is created only with a name                                           |
| `folders[].description` | body | string | no       | Sets `fDescription` on an update whenever the key is sent, even empty. A new folder gets `""` when not sent |
| `folders[].sortOrder`   | body | number | no       | Sets `sort_order` when numeric and `0` or more. A new folder gets `1000` when not sent                      |

```json
{ "parentUUID": "100", "folders": [ { "name": "Room cleaning", "description": "Rooms on floor 1" } ] }
```

**Response** `200`: `result` `true` and "Folders saved successfully". No `data`.

**Errors:** `200` with `result` `false`:

* "invalid params!" when `parentUUID` is missing or empty, or `folders` is missing, empty or not a list.
* "invalid access!" when the caller is not a tag manager.
* "Folders not found" when `uuid`s were sent and none of them is a live folder.

**Side effects:**

* Updates `fName`, `fDescription`, `sort_order` and the modified fields on each live folder found, in [`tPri_TagHeader`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_tagheader.md).
* Inserts each new folder with `uuid_tParent` set to `parentUUID`, no group, and `uuid_tUser_CreatedBy` set to the caller.

## POST ?action=save\_tags

Creates, renames or re-sorts the tags of one folder. A name already live in the folder is skipped, and the answer does not say so.

* **Auth:** user token. A tag manager of `parentUUID`. Tags are looked up and updated by UUID in any folder of any site, and new tags go into `folderUUID` with no check that the folder is in the site.
* **Used by:** web (`TagHttpService.saveTagsIntoFolder`, web\_app\_v2 @ 0989b8e685, `src/app/services/tag/tag-http/tag-http.service.ts:191-198`; called from `src/app/pages/account-settings/account-settings-manage-tags/account-settings-manage-tags-list/account-settings-manage-tags-list.component.ts:477`, `src/app/pages/account-settings/account-settings-manage-tags/account-settings-manage-tags-dialog/account-settings-manage-tags-dialog.component.ts:408` and `:1354`, `src/app/pages/group-settings/group-settings-tag-headers/group-settings-tags-dialog/group-settings-tags-dialog.component.ts:117` and `:192`, and `src/app/pages/group-settings/group-settings-tag-headers/group-settings-tags-csv-dialog/group-settings-tags-csv-dialog.component.ts:87`). The web never sends `sortOrder`.
* **Code:** php-apis @ 238ca4414e, `html/api/snapfix/index.php:740`, `htmlphp/api/snapfix/class/class.functions.php:46334-46431`.

**Request** (JSON)

| Name               | In   | Type   | Required | Rules                                                                                    |
| ------------------ | ---- | ------ | -------- | ---------------------------------------------------------------------------------------- |
| `parentUUID`       | body | string | yes      | The site                                                                                 |
| `folderUUID`       | body | string | yes      | The folder new tags go into, and whose names are checked for repeats                     |
| `tags`             | body | array  | yes      | One item per tag; non-empty                                                              |
| `tags[].uuid`      | body | string | no       | A live tag is updated. Any other UUID, or none, inserts a tag                            |
| `tags[].name`      | body | string | no       | Sets `fName`. A name already in the folder is skipped without a message; no length limit |
| `tags[].sortOrder` | body | number | no       | Sets `sort_order` when numeric and `0` or more. A new tag gets `1000` when not sent      |

An existing tag whose sent `name` is already in `folderUUID` is skipped entirely, so its `sortOrder` is not saved either, even when the name is its own current name.

```json
{ "parentUUID": "100", "folderUUID": "123", "tags": [ { "name": "Lobby" }, { "uuid": "456", "name": "Room 101" } ] }
```

**Response** `200`: when at least one tag was saved, `data` lists the saved tags that are in `folderUUID`, as [folder tag objects](#folder-tag-object). When none was saved, there is no `data`. The message is "Tags saved successfully" either way.

```json
{
  "result": true,
  "message": "Tags saved successfully",
  "data": [
    { "tagUUID": "456", "tagName": "Room 101", "tagSortOrder": 1000, "jobCount": 3 }
  ],
  "serverTs": 1794387595000
}
```

**Errors:** `200` with `result` `false`:

* "invalid params!" when `parentUUID`, `folderUUID` or `tags` is missing or empty.
* "invalid access!" when the caller is not a tag manager.
* "Tags not found" when `uuid`s were sent and none of them is a live tag.

**Side effects:**

* Updates `fName`, `sort_order` and the modified fields on each live tag found, in [`tPri_Tag`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_tag.md).
* Inserts each new tag with `uuid_tTagHeader` set to `folderUUID`, `fVisible` 1, and the caller as creator.
* Does not delete the tags that are not sent.

## Tag folder object

A tag folder as the `/v1/app` routes return it (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Resources/v1/TagHeaderResource.php`).

| Field         | Type                                | Meaning                                                                                                                                                                                                                  |
| ------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `uuid`        | string                              | The folder (`tPri_TagHeader.uuid`)                                                                                                                                                                                       |
| `name`        | string                              | `fName`                                                                                                                                                                                                                  |
| `description` | string or null                      | `fDescription`                                                                                                                                                                                                           |
| `mandatory`   | integer or null                     | For a folder linked by a rule, the rule's `fMandatory` (`0` when unset): `1` when a tag from the folder is required for the group. For a group's own folder, `null`, because `tPri_TagHeader` has no `fMandatory` column |
| `tags`        | array of [tag objects](#tag-object) | The folder's live tags. Left out of the rename answer                                                                                                                                                                    |

## Tag object

A tag as the `/v1/app` routes return it (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Resources/v1/TagResource.php`).

| Field         | Type    | Meaning                                                                                                                                                                        |
| ------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `uuid`        | string  | The tag (`tPri_Tag.uuid`). Left out when not set                                                                                                                               |
| `name`        | string  | `fName`                                                                                                                                                                        |
| `aiNewTag`    | integer | `1` when the tag was made up by AI, `0` otherwise. Defaults to `0`                                                                                                             |
| `aiSuggested` | integer | Present only when set and not `0`: `1` when the AI suggested the tag for a task. It comes from `tPri_JobTag`, so the routes on this page, which read `tPri_Tag`, never send it |
| `jobTagUuid`  | string  | Present only when set, by routes that read tags with their task link                                                                                                           |

The object has no `visible` field, although the single-tag create and update requests accept `visible`.

## Folder summary object

One folder in the `tagHeaders` list of [POST /v1/app/parents/tags](#post-v1appparentstags) (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Resources/v1/AllTagHeaderResource.php`).

| Field         | Type                                | Meaning                |
| ------------- | ----------------------------------- | ---------------------- |
| `name`        | string                              | `fName`                |
| `description` | string or null                      | `fDescription`         |
| `tags`        | array of [tag objects](#tag-object) | The folder's live tags |

It has no folder UUID; the folder is the one the tag is nested under.

## Delete preview object

What [delete/multi](#post-v1apptag-headersdeletemulti) would remove (api\_php\_live\_v2 @ ef3c4319f6, `app/Services/TagHeaderBulkDeleteService.php:26-63`). All counts are `0` when no named folder is valid.

| Field                  | Type    | Meaning                                                                 |
| ---------------------- | ------- | ----------------------------------------------------------------------- |
| `folderCount`          | integer | Valid folders that would be deleted                                     |
| `emptyFolderCount`     | integer | Of those, the folders with no live tag                                  |
| `tagCount`             | integer | Live tags in those folders                                              |
| `affectedTaskCount`    | integer | Distinct live tasks with a live task tag on a live tag of those folders |
| `requiresConfirmation` | boolean | `true` when `affectedTaskCount` is above 0                              |

## php-apis folder object

One folder from [read\_parent\_tag\_folders](#post-actionread_parent_tag_folders) and [read\_business\_tag\_folders](#post-actionread_business_tag_folders).

| Field               | Type           | Meaning                                                                                                                                                                          |
| ------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `folderUUID`        | string         | The folder                                                                                                                                                                       |
| `folderName`        | string         | `fName`                                                                                                                                                                          |
| `folderDescription` | string or null | `fDescription`; when empty and a group owns the folder, the group's name                                                                                                         |
| `sortOrder`         | integer        | `sort_order`                                                                                                                                                                     |
| `tagCount`          | integer        | Live tags in the folder                                                                                                                                                          |
| `excluded`          | integer        | Only in `read_business_tag_folders`. `0` when the group owns the folder or has a live rule with `fExcluded` 0 for it; `1` otherwise, and always `1` when a live rule excludes it |

## Folder tag object

One tag from [read\_folder\_tags](#post-actionread_folder_tags) and [save\_tags](#post-actionsave_tags).

| Field          | Type    | Meaning                                                                                                                           |
| -------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `tagUUID`      | string  | The tag                                                                                                                           |
| `tagName`      | string  | `fName`                                                                                                                           |
| `tagSortOrder` | integer | `sort_order`                                                                                                                      |
| `jobCount`     | integer | Distinct tasks with a live, unfrozen task tag on the tag. Deleted tasks are counted too, because the task filter sits in the join |

## Folder group object

One group from [read\_folder\_groups](#post-actionread_folder_groups).

| Field           | Type           | Meaning                                                     |
| --------------- | -------------- | ----------------------------------------------------------- |
| `groupUUID`     | string         | The group                                                   |
| `groupName`     | string         | `fName`                                                     |
| `groupImage`    | string or null | `fImage`                                                    |
| `groupDisabled` | integer        | `1` when the folder is off for the group, `0` when it is on |

## Related features and screens

* [Site tags](https://docs.snapfix.com/product/features/console/site-tags.md): what tags and tag folders are, and who sees them.
* [Task creation](https://docs.snapfix.com/product/features/tasks/task-creation.md): the tag folders a task must use.
* [Snapfix recommends](https://docs.snapfix.com/product/features/ai/snapfix-recommends.md): the AI tag suggestions.
* [Groups](https://docs.snapfix.com/product/features/groups/groups.md) and [QR forms](https://docs.snapfix.com/product/features/qr/qr-forms.md): where group and form tags appear.
* [Console tags screen](https://docs.snapfix.com/how-the-apps-work/screens/console/tags.md) and [Group settings](https://docs.snapfix.com/how-the-apps-work/screens/groups/group-settings.md): the screens that call these endpoints.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.snapfix.com/engineering-reference/api/tags.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
