> 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/console.md).

# Console 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/console.md).
{% endhint %}

Sites and multi-sites as the Site Console and the Multi-Site Console manage them: the site lists of the site switchers, site details, addresses, the site image and settings, the multi-site's details, and multi-site users and their site roles. Site users, staff usernames, site tags and groups are in other groups ([related routes](#related-routes)).

* **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`; `authpy` at `https://z3.snapfix.com`. Only Android swaps hosts per site ([Services and hosts](https://docs.snapfix.com/engineering-reference/api.md#services-and-hosts)).
* **Auth:** api\_php\_live\_v2: user token (authpy JWT in `Authorization: Bearer`). The site list returns only the caller's sites, the multi-site list needs a membership of the multi-site, and the site writes need a site admin; the other site routes check nothing beyond the token (each section says which). php-apis: user token (Bearer JWT, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]). Most actions act on the `user_uuid` in the body, not on the token's user; `webcust_list_parents_v2` and `webcust_update_parent_v2` take the user from the token payload, whose signature only the dispatcher checks, and only while `JWT_AUTH_ENABLED` is on. authpy: user token (`Authorization: Bearer`). The multi-site routes need a live membership of the multi-site but no admin role \[[ASK-123](https://github.com/snapfix/docs/blob/main/ASK.md#ask-123-who-may-manage-a-multi-site-and-change-its-members-site-roles)]; the permission routes also accept a site admin.
* **Used by:** web\_app\_v2 (site switcher, Site Console, Multi-Site Console, task status changes), iOS and Android (site switcher, site details, the setup flow's name check), web\_payments (payment page), snapfix\_ai\_agent (a site's time zone and currency); 15 of the 35 endpoints have no known caller.
* **Answers and errors:** the api\_php\_live\_v2 envelope and the codes every `/v1/app` route can return are in [Tasks: common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors). php-apis and authpy answer HTTP `200` with `result` `false` and the message for their own errors ([Responses](https://docs.snapfix.com/engineering-reference/api.md#responses)). Each section lists its own errors.
* **Logs:** api\_php\_live\_v2 writes each call to its request log, with the response when it is under about 100 KB; php-apis stores each request body and each response under about 100 KB in its daily request log.

| Method | Path                                                                                               | Service            | Purpose                                                    |
| ------ | -------------------------------------------------------------------------------------------------- | ------------------ | ---------------------------------------------------------- |
| GET    | [`/v1/app/multiSites/{uuid}`](#get-v1appmultisitesuuid)                                            | api\_php\_live\_v2 | List a multi-site's sites                                  |
| GET    | [`/v1/app/parents`](#get-v1appparents)                                                             | api\_php\_live\_v2 | List the caller's sites and multi-sites                    |
| POST   | [`/v1/app/parents/get-updates`](#post-v1appparentsget-updates)                                     | api\_php\_live\_v2 | Count the updated tasks of each site                       |
| GET    | [`/v1/app/parents/{uuid}`](#get-v1appparentsuuid)                                                  | api\_php\_live\_v2 | Get a site                                                 |
| PUT    | [`/v1/app/parents/{uuid}`](#put-v1appparentsuuid)                                                  | api\_php\_live\_v2 | Change a site                                              |
| GET    | [`/v1/app/parents/{uuid}/can-change-status`](#get-v1appparentsuuidcan-change-status)               | api\_php\_live\_v2 | Check whether task statuses may change on a site           |
| GET    | `/v1/app/parents/{uuid}/metrics`                                                                   | api\_php\_live\_v2 | Get a site's Firebase counts (no caller)                   |
| POST   | `/v1/app/parents/{uuid}/settings`                                                                  | api\_php\_live\_v2 | Create a site's settings (no caller)                       |
| PUT    | `/v1/app/parents/{uuid}/settings`                                                                  | api\_php\_live\_v2 | Change a site's settings (no caller)                       |
| ANY    | `?action=create_pri_parent`                                                                        | php-apis           | Create a site (no caller)                                  |
| ANY    | `?action=delete_pri_parent`                                                                        | php-apis           | Delete sites, generic table action (no caller)             |
| ANY    | `?action=modify_pri_parent`                                                                        | php-apis           | Change sites, generic table action (no caller)             |
| ANY    | `?action=read_parent_address_basic`                                                                | php-apis           | Read a site's basic address (no caller)                    |
| ANY    | `?action=read_parent_detail`                                                                       | php-apis           | Read a site's details (no caller)                          |
| ANY    | `?action=read_pri_parent`                                                                          | php-apis           | Read sites by UUID, generic table action (no caller)       |
| ANY    | `?action=save_parent_address_basic`                                                                | php-apis           | Save a site's basic address (no caller)                    |
| ANY    | `?action=save_pri_parent`                                                                          | php-apis           | Save a site (no caller)                                    |
| POST   | [`?action=update_parent_address_basic`](#post-actionupdate_parent_address_basic)                   | php-apis           | Save a site's basic address                                |
| POST   | [`?action=update_parent_image`](#post-actionupdate_parent_image)                                   | php-apis           | Change a site's image                                      |
| POST   | [`?action=validate_parent_name`](#post-actionvalidate_parent_name)                                 | php-apis           | Check a site name                                          |
| ANY    | `?action=webcust_list_parents`                                                                     | php-apis web       | List sites (no caller)                                     |
| POST   | [`?action=webcust_list_parents_v2`](#post-actionwebcust_list_parents_v2)                           | php-apis web       | List the caller's sites, with task counts (v2)             |
| ANY    | `?action=webcust_parent_add`                                                                       | php-apis web       | Create a site (no caller)                                  |
| POST   | [`?action=webcust_parent_detail`](#post-actionwebcust_parent_detail)                               | php-apis web       | Get a site's details                                       |
| POST   | [`?action=webcust_parent_list`](#post-actionwebcust_parent_list)                                   | php-apis web       | List the sites where a user is an admin                    |
| POST   | [`?action=webcust_update_parent_v2`](#post-actionwebcust_update_parent_v2)                         | php-apis web       | Change a site (v2)                                         |
| PUT    | [`/multisite/{multisiteUUID}`](#put-multisitemultisiteuuid)                                        | authpy             | Change a multi-site's name, description and image          |
| GET    | `/multisite/{multisiteUUID}/sites`                                                                 | authpy             | List a multi-site's sites (no caller)                      |
| POST   | [`/multisite/{multisiteUUID}/user/{userUUID}`](#post-multisitemultisiteuuiduseruseruuid)           | authpy             | Add a user to a multi-site and set their site roles        |
| DELETE | [`/multisite/{multisiteUUID}/user/{userUUID}`](#delete-multisitemultisiteuuiduseruseruuid)         | authpy             | Remove a user from a multi-site, or from some of its sites |
| GET    | [`/multisite/{multisiteUUID}/user/{userUUID}/sites`](#get-multisitemultisiteuuiduseruseruuidsites) | authpy             | List a user's role on each site of a multi-site            |
| GET    | [`/multisite/{multisiteUUID}/users`](#get-multisitemultisiteuuidusers)                             | authpy             | List a multi-site's users                                  |
| GET    | [`/user/{userUUID}/site/{siteUUID}/permission`](#get-useruseruuidsitesiteuuidpermission)           | authpy             | Get a user's permissions on a site                         |
| PUT    | [`/user/{userUUID}/site/{siteUUID}/permission`](#put-useruseruuidsitesiteuuidpermission)           | authpy             | Set a user's permissions on a site                         |
| GET    | `/user/{userUUID}/sites`                                                                           | authpy             | List a user's sites (no caller)                            |

Notes on the table:

* Rows marked "(no caller)" have no caller in any client clone. The php-apis actions appear only in the iOS and Android endpoint registries, and the web's `PARENTS_METRICS` constant is never used. Whether to remove them is open \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)].
* What the uncalled routes can do: the generic table actions (`?action=*_pri_parent`) create, read, change and soft-delete any site by UUID, with no check. `GET /user/{userUUID}/sites` lists any user's multi-site sites and roles. `GET /v1/app/parents/{uuid}/metrics` answers for any site. The two settings routes need a site admin, and they can switch chat, which no screen shows \[[ASK-47](https://github.com/snapfix/docs/blob/main/ASK.md#ask-47-how-is-a-sites-chat-switched-off-and-who-should-be-able-to-do-it)]. `webcust_list_parents`, `webcust_parent_add` and `save_parent_address_basic` act on the `user_uuid` in the body; `read_parent_address_basic` takes no user and returns any site's basic address.
* The php-apis dispatchers accept any method except `OPTIONS` (php-apis @ 238ca4414e, `html/api/snapfix/index.php:231-237`); the table shows `POST`, which every caller sends. Actions that read the JSON body (`$data`) need JSON; actions that read `$_POST` need form fields. Each section says which.

## Related routes

Routes under `/v1/app/parents` that belong to other groups:

* **Site users and staff usernames:** `POST /v1/app/parents/add-user`, `GET /v1/app/parents/{uuid}/users`, and `GET` and `POST /v1/app/staff-username` are in [Users](https://docs.snapfix.com/engineering-reference/api/users.md). The Site Console's Users and Username Sites tabs use the other three; nothing calls `POST /v1/app/parents/add-user`.
* **Site tags:** `POST /v1/app/parents/tags` is in [Tags](https://docs.snapfix.com/engineering-reference/api/tags.md).
* **Site groups:** `GET /v1/app/parents/list/businesses` is in [Groups](https://docs.snapfix.com/engineering-reference/api/groups.md).
* **Packages and the billing session:** `POST /v1/app/parents/packages` (no caller) and `GET /v1/app/parents/{uuid}/create-session` are in [Billing](https://docs.snapfix.com/engineering-reference/api/billing.md).
* **Marketing popups:** `GET /v1/app/parents/{uuid}/popups` is in [Notifications](https://docs.snapfix.com/engineering-reference/api/notifications.md).
* **Room statuses:** `GET /v1/app/parents/{uuid}/room-statuses` is in [Rooms](https://docs.snapfix.com/engineering-reference/api/rooms.md).
* **Compliance defaults:** `POST /v1/app/parents/comply-defaults` is in [Compliance](https://docs.snapfix.com/engineering-reference/api/compliance.md).
* **Screens and features:** [Console screens](https://docs.snapfix.com/how-the-apps-work/screens/console.md); [Site details](https://docs.snapfix.com/product/features/console/site-details.md) and [Multi-Site Console](https://docs.snapfix.com/product/features/console/multi-site-console.md).

## Roles

* **Multi-site user:** a live row in [`tPri_MultiSiteUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_multisiteuser.md). The sites of a multi-site are its live rows in [`tPri_MultiSiteParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_multisiteparent.md). No code reads the table's `fAdmin` flag, so every multi-site user can manage the multi-site \[[ASK-123](https://github.com/snapfix/docs/blob/main/ASK.md#ask-123-who-may-manage-a-multi-site-and-change-its-members-site-roles)].
* **Site admin:** a caller whose newest live row in [`tPri_UserParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userparent.md) for the site has `user_type` `admin`. api\_php\_live\_v2 ignores the row's `blocked` flag, so a blocked admin still passes; php-apis `webcust_update_parent_v2` requires `blocked` 0.
* **Site viewer:** any other live site row. The multi-site routes call it `site-viewonly`, and the site's `settings.role` shows `User`.
* **Removal:** a user leaves a multi-site or a site when `fDeleted` is set on the row; the row stays. Site admin rows survive a removal from the whole multi-site \[[ASK-127](https://github.com/snapfix/docs/blob/main/ASK.md#ask-127-should-removing-a-user-from-a-multi-site-also-remove-the-site-admin-roles-it-gave)].

## GET /v1/app/multiSites/{uuid}

Lists the sites of one multi-site, with their task counts and the caller's role on each. The Multi-Site Console's pages, the side menu's site list and the site pickers read it.

* **Auth:** user token. The caller must be a multi-site user of the multi-site; anyone else gets `404` (api\_php\_live\_v2 @ ef3c4319f6, `app/Services/MultiSiteService.php:43-54`).
* **Used by:** web (`MultisiteConsoleHttpService.getMultiSiteList`: through `MultisiteConsoleHelperService` for My Sites, Site Details, the side menu's site list, the sites dropdown and the multi-site filter; directly from the feed list and the checklist page).

**Request**

| Name   | In   | Type   | Required | Rules          |
| ------ | ---- | ------ | -------- | -------------- |
| `uuid` | path | string | yes      | The multi-site |

**Response** `200`: `data.parents` is a list of [site objects](#site-object), each with `jobCounts`, `settings` and `siteDisabled`. `data` also has the caller's `defaultLanguage` and `showAiAgentTooltip`. `groupCount`, `assetRegCount` and `multiSites` are left out, and `isGroupAdmin` is `null`.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "parents": [
      {
        "uuid": "123",
        "name": "Riverside Hotel",
        "image": null,
        "description": "1 Quay Street",
        "isGroupAdmin": null,
        "siteDisabled": 0,
        "jobCounts": { "red": 2, "amber": 1, "green": 14 },
        "settings": { "role": "User", "createNewBusiness": 0, "manageTag": 0, "editTagHeader": 0, "manageChecklist": 0, "aiAutoAssignEnabled": 0, "region": "eu-west-1", "base_urls": { "php": "", "py": "" }, "chatEnable": 1 }
      }
    ],
    "defaultLanguage": "en",
    "showAiAgentTooltip": 0
  }
}
```

* Churned sites are left out.
* `jobCounts` count every live, unarchived task in the multi-site's groups, for every member.
* `settings.role` is the caller's role on each site, from the caller's newest live site row. The four group permission flags and `aiAutoAssignEnabled` are always `0` here.
* `siteDisabled` is `1` when the caller's newest site row there is deleted (`MultiSiteService.php:140-156`). The web leaves those sites out of its multi-site lists.

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `404` "Resource not found" when the multi-site doesn't exist or the caller is not a multi-site user of it.

**Side effects:** none.

## GET /v1/app/parents

Lists the caller's sites and multi-sites, with the caller's group counts and task counts: the web's site switcher.

* **Auth:** user token. Only the caller's own sites come back; no role is needed.
* **Used by:** web (`AccountHttpService.getAccountList`, from the side menu's site list and the planner).

**Request:** none.

**Response** `200`: `data.parents` is a list of [site objects](#site-object) with `groupCount`, `assetRegCount`, `jobCounts`, `multiSites` and `settings`. `data.multiSites` lists the caller's multi-sites as [multi-site objects](#multi-site-object). `defaultLanguage` and `showAiAgentTooltip` are the caller's.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "parents": [
      {
        "uuid": "123",
        "name": "Riverside Hotel",
        "customerType": "paying_customer",
        "isGroupAdmin": true,
        "groupCount": 3,
        "assetRegCount": 0,
        "jobCounts": { "red": 2, "amber": 1, "green": 14 },
        "multiSites": ["500"],
        "settings": { "role": "Admin", "createNewBusiness": 1, "manageTag": 1, "editTagHeader": 1, "manageChecklist": 1, "aiAutoAssignEnabled": 1, "region": "eu-west-1", "base_urls": { "php": "", "py": "" }, "chatEnable": 1 }
      }
    ],
    "multiSites": [
      { "uuid": "500", "name": "Riverside Group", "image": null, "description": null, "jobCounts": { "red": 2, "amber": 1, "green": 14 } }
    ],
    "defaultLanguage": "en",
    "showAiAgentTooltip": 0
  }
}
```

* A site is listed when the caller has a live site row there, of any role, or a live membership in one of its live groups or asset registers. It is left out when the caller's newest site row there is deleted, and when the site is deleted or churned (api\_php\_live\_v2 @ ef3c4319f6, `app/Services/UserParentService.php:21-61`, `app/Services/ParentService.php:179-184`).
* `jobCounts`: in groups where the caller is an admin or may view all tasks, every live, unarchived task counts; in other groups, only tasks the caller created, follows or is assigned to.
* A multi-site's `jobCounts` add up its sites. They count every task of the multi-site's groups, and then count the caller's own tasks in groups where the caller is not an admin a second time.

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors).

**Side effects:** none.

## POST /v1/app/parents/get-updates

Counts, for each site named, the tasks whose chat changed since the caller last opened their group: the unread dots on the web's site list.

* **Auth:** user token. The route does not check that the caller belongs to the sites named. The counts come only from the caller's own groups, but the view rows below are written for every group of the sites.
* **Used by:** web (`AccountHttpService.getAccountUpdates`, from the side menu's site list; the answer is cached until sign-out).

**Request** (JSON or form)

| Name          | In   | Type             | Required | Rules                                                                                                |
| ------------- | ---- | ---------------- | -------- | ---------------------------------------------------------------------------------------------------- |
| `parentUuids` | body | array of strings | yes      | The sites. Each item is a required string. Every site must exist and be live, and no UUID may repeat |

**Response** `200`: `data` is a list of `{ "parentUuid", "updatedJobCount" }`, one per site named that has at least one live group or asset register, in database order. A site with none is left out.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": [ { "parentUuid": "123", "updatedJobCount": 4 } ]
}
```

`updatedJobCount` adds up, over the caller's groups in the site, the unarchived tasks whose chat changed (`fJobChatModifiedTs`) after the caller's last view of the group. In groups where the caller is not an admin and may not view all tasks, only the tasks the caller created, follows or is assigned to count.

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `400` "Invalid parents!" when a UUID matches no live site or a UUID is repeated; `422` when the list is missing or empty.

**Side effects:** adds a [`tPri_Log_BusinessViewedUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_businessvieweduser.md) row, viewed now, for each live group and asset register of the named sites that has no view row for the caller yet, including groups the caller is not in (`app/Services/AssetBusinessUpdatesLogService.php:74-85`).

## GET /v1/app/parents/{uuid}

Gets one site with its addresses, admins and users, subscription, settings and meta data. The Site Console, the Multi-Site Console's Site Details, the chat's site lookup and snapfix\_ai\_agent read it.

* **Auth:** user token. The route checks neither membership nor role: any signed-in user gets any site by UUID, with its member lists and internal fields.
* **Used by:** web (`AccountHttpService.getAccountDetails`, cached per site: the Site Console, the Multi-Site Console's Site Details and the chat); snapfix\_ai\_agent (the site's time zone and default currency, after its own membership check: snapfix\_ai\_agent @ e5e18caef5, `src/snapfix/parents/__init__.py:16-20`).

**Request**

| Name     | In    | Type   | Required | Rules                                                                                                                                                                                                                                                                                                                                                                  |
| -------- | ----- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`   | path  | string | yes      | The site                                                                                                                                                                                                                                                                                                                                                               |
| `source` | query | string | no       | `site` (default) or `multisite`; anything else gives `422`. With `site`, `meta.tasksCount` counts the caller's groups in the site, by the rule of [GET /v1/app/parents](#get-v1appparents). With `multisite`, it counts every task of every group of the site, and the caller's own tasks in groups where the caller is not an admin a second time. No caller sends it |

**Response** `200`: a [site object](#site-object) with `address`, `admins`, `users`, `subscription`, `hasSubscribed`, `settings` and `meta`.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "uuid": "123",
    "name": "Riverside Hotel",
    "image": null,
    "stdCountries": "GB",
    "description": "1 Quay Street",
    "displayUserContactData": 1,
    "customerType": "paying_customer",
    "defaultCurrency": "GBP",
    "isGroupAdmin": true,
    "hasSubscribed": false,
    "address": {
      "basic": { "uuid": "300", "name": "Riverside Hotel", "address1": "1 Quay Street", "address2": null, "postalCode": "SW1A 1AA", "city": "London", "state": null, "countryCode": "GB" },
      "invoice": { "uuid": null, "name": null, "address1": null, "address2": null, "postalCode": null, "city": null, "state": null, "countryCode": null },
      "billing": { "uuid": null, "name": null, "address1": null, "address2": null, "postalCode": null, "city": null, "state": null, "countryCode": null }
    },
    "admins": [ { "uuid": "200", "username": "jane@example.com", "name": "Jane Smith", "userType": "Admin", "userParentDeleted": 0 } ],
    "users": [],
    "subscription": [],
    "meta": { "timezoneName": "Europe/London", "origin": "web", "salesPerson": "Sam Example", "riskScore": 40, "usersCount": 12, "tasksCount": 27 },
    "settings": { "role": "Admin", "createNewBusiness": 0, "manageTag": 0, "editTagHeader": 0, "manageChecklist": 0, "aiAutoAssignEnabled": 1, "region": "eu-west-1", "base_urls": { "php": "", "py": "" }, "chatEnable": 1, "aiSuggestionEnabled": 1 }
  }
}
```

* `settings.role` and `settings.aiAutoAssignEnabled` come from the caller's newest live site row; a caller with none gets `User` and `0`. `createNewBusiness`, `manageTag`, `editTagHeader` and `manageChecklist` are always `0`, because the route does not load them (api\_php\_live\_v2 @ ef3c4319f6, `app/Services/ParentService.php:278-305`).
* `hasSubscribed` is `true` when the site's latest Stripe subscription row is paid or updated and Stripe returns the subscription; `subscription` then holds it, else `[]`.

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `404` "Resource not found" for an unknown or deleted site; `422` when `source` is neither `site` nor `multisite`.

**Side effects:** none on the database. The route calls the Stripe API for the subscription when the latest subscription row is paid or updated, and it loads the site's users four times.

## PUT /v1/app/parents/{uuid}

Changes a site's name, country, basic address, currency, contact display, AI suggestion switches and image. The Site Console's and the Multi-Site Console's Site Details save through it.

* **Auth:** user token. The caller must be a site admin ([Roles](#roles)); otherwise `403` "Access denied" (api\_php\_live\_v2 @ ef3c4319f6, `app/Policies/ParentPolicy.php:19-32`, `app/Http/Controllers/v1/Versions/v1_0/App/ParentController.php:266-268`). A blocked site admin still passes.
* **Used by:** web (`AccountHttpService.updateAccount`). The web sends `POST` with `_method=PUT` in the query string and a multipart body; Laravel takes the method from the query string when the body has none.

**Request** (multipart or JSON)

| Name                                                                          | In   | Type    | Required | Rules                                                                                                                                                                                                  |
| ----------------------------------------------------------------------------- | ---- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `uuid`                                                                        | path | string  | yes      | The site                                                                                                                                                                                               |
| `name`                                                                        | body | string  | yes      | Saved as `fName`. No length limit and no uniqueness check on the server \[[ASK-125](https://github.com/snapfix/docs/blob/main/ASK.md#ask-125-must-site-names-be-unique)]; the web allows 60 characters |
| `stdCountryCode`                                                              | body | string  | yes      | Exactly 2 characters, saved as `std_countries`                                                                                                                                                         |
| `defaultCurrency`                                                             | body | string  | no       | Nullable. Saved as `default_currency` (3 characters); not checked against a currency list                                                                                                              |
| `address1`, `address2`, `state`, `city`, `postalCode`                         | body | string  | no       | Nullable. Saved on a new basic address row                                                                                                                                                             |
| `displayUserContactData`                                                      | body | integer | no       | `1` or `0`, saved as `display_user_contact_data`                                                                                                                                                       |
| `aiSuggestionEnabled`, `aiUseOnlyExistingTag`, `aiLanguageTranslationEnabled` | body | integer | no       | `1` or `0`, saved in the site's settings. The settings change only when one of them is sent. The web never sends `aiLanguageTranslationEnabled`                                                        |
| `file`                                                                        | body | file    | no       | The new image: `jpg`, `jpeg`, `png` or `gif`, up to `FILE_MAX_SIZE` (102400 KB by default)                                                                                                             |

The web sends every field except `aiLanguageTranslationEnabled`, with an empty string for a blank address field, and `file` only for a new image.

**Response** `200`: the site as [GET /v1/app/parents/{uuid}](#get-v1appparentsuuid) returns it, after the change, with three differences: `hasSubscribed` is `null` and `subscription` is `[]`, because the route reads no subscription, and `isGroupAdmin` is `null`. The four group permission flags in `settings` are `0` here too. The web stores this answer as the current site after a save.

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `403` "Access denied" when the caller is not a site admin, also for a site that doesn't exist; `404` "Resource not found" for a deleted site where the caller still has an admin row; `422` with the first failed rule's text, for example "The name field is required.".

**Side effects:**

* Adds a [`tPri_Address`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_address.md) row and a basic [`tPri_ParentAddress`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_parentaddress.md) row on every save, even when the address didn't change; readers take the newest, and the old rows stay.
* Updates [`tPri_Parent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_parent.md): `fName`, `std_countries`, `default_currency`, `display_user_contact_data`, `fCity` and `fPostalCode`, and `fImage` when a file is sent ([Files](https://docs.snapfix.com/engineering-reference/api.md#files)). The site's `fAddress` (its `description`) does not change.
* Updates the site's [`tPri_SettingsParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_settingsparent.md) row when an AI switch is sent.
* Queues a [`time_tPri_Parent`](https://docs.snapfix.com/engineering-reference/db/tables/time_tpri_parent.md) row with the site's name, customer type and dates.
* Sends no push.

## GET /v1/app/parents/{uuid}/can-change-status

Says whether task statuses may change on a site. A site whose customer type is `churn` or `0` (uncategorized) may change statuses only while it holds at most 100 tasks, counting deleted tasks and tasks in deleted groups. Any other site always may.

* **Auth:** user token. The route does not check that the caller belongs to the site.
* **Used by:** web (`AccountHttpService.isAccountTaskCanChangeStatus`), before a task's status changes from its traffic light or a drag in the workflow view, and only when the selected site's `customerType` is `churn` or `0`. On `false` the web shows the subscription dialog instead. The plan limits are an open question \[[ASK-23](https://github.com/snapfix/docs/blob/main/ASK.md#ask-23-should-plan-limits-be-enforced-on-the-web-and-the-server)].

**Request**

| Name   | In   | Type   | Required | Rules    |
| ------ | ---- | ------ | -------- | -------- |
| `uuid` | path | string | yes      | The site |

**Response** `200`

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": { "accessChangeStatus": true }
}
```

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `404` "Resource not found" for an unknown or deleted site.

**Side effects:** none.

## POST ?action=update\_parent\_address\_basic

Saves a site's basic address: the iOS site details save. Every call adds an address row.

* **Auth:** user token (Bearer JWT, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]). The action acts on the `user_uuid` in the body. It checks that the site exists and, after writing, that the user exists; it never checks membership or admin rights, so any signed-in user can change any site's address.
* **Used by:** iOS (`ManageAccountVC.addressChanged`). Android lists the action in its registry but never calls it.

**Request** (JSON body)

| Name                                                       | In   | Type   | Required | Rules                                                                                       |
| ---------------------------------------------------------- | ---- | ------ | -------- | ------------------------------------------------------------------------------------------- |
| `parent_uuid`                                              | body | string | yes      | The site                                                                                    |
| `user_uuid`                                                | body | string | yes      | The user saved as the creator. Checked only after the address is written                    |
| `fAddress1`, `fAddress2`, `fCity`, `fState`, `fPostalCode` | body | string | no       | The address lines, city, state and postal code. A missing value is saved as an empty string |
| `std_countries`                                            | body | string | no       | The country code. A missing value is saved as an empty string                               |

**Response** `200`: `data` is the [site row](#site-row-object-php-apis) after the change.

**Errors:** `200` with `result` `false`: "Data cannot be blank!" (no body); "parent\_uuid, user\_uuid must be mentioned in the request!" (naming only the missing fields); "invalid parent" (no such site; a deleted site gets the new rows first, then this message); "invalid user" (unknown or deleted user, after the address is written).

**Side effects:** inserts a [`tPri_Address`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_address.md) row named after the site and a basic [`tPri_ParentAddress`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_parentaddress.md) row on every call, with the body's user as the creator. The old rows stay, and readers take the newest by `fServerTs`. The rows are written before the user check, so an unknown `user_uuid` still changes the address (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:22701-22730`). No time log and no sync queue entry.

## POST ?action=update\_parent\_image

Sets a site's image to an image URL the app has already uploaded.

* **Auth:** user token (as above). The action acts on the `user_uuid` in the body and checks only that the user and the site exist and are not deleted, so any signed-in user can change any site's image.
* **Used by:** iOS (`ManageAccountVC.saveParentImage`) and Android (`ParentAccountDetailFragment.callUpdateParentImageAPI`), from site details, after uploading the picture.

**Request** (JSON body)

| Name          | In   | Type   | Required | Rules                                                       |
| ------------- | ---- | ------ | -------- | ----------------------------------------------------------- |
| `fImage`      | body | string | yes      | The uploaded image's URL, stored as sent                    |
| `user_uuid`   | body | string | yes      | An existing user that is not deleted; saved as the modifier |
| `parent_uuid` | body | string | yes      | An existing site that is not deleted                        |

**Response** `200`: `data` is the [site row](#site-row-object-php-apis) after the change.

**Errors:** `200` with `result` `false`: "Data cannot be blank!"; "fImage, user\_uuid, parent\_uuid must be mentioned in the request!" (naming only the missing fields); "invalid user"; "invalid parent"; "Error while updating parent record".

**Side effects:** sets `fImage`, `uuid_tUser_ModifiedBy`, `fModifiedTs` and `fServerTs` on [`tPri_Parent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_parent.md); writes a [time log row](#common-side-effects) and a [sync queue entry](#common-side-effects).

## POST ?action=validate\_parent\_name

Checks a site name in the apps' setup flow. Any non-empty name passes: the duplicate-name check is commented out \[[ASK-125](https://github.com/snapfix/docs/blob/main/ASK.md#ask-125-must-site-names-be-unique)].

* **Auth:** user token (as above). No user is read.
* **Used by:** iOS (`ChooseIndustryRoleVC`) and Android (`ChooseCompanyNameFragment`), on the [Company and role](https://docs.snapfix.com/how-the-apps-work/screens/onboarding/company-and-role.md) step of the setup flow, which the current apps do not open \[[ASK-39](https://github.com/snapfix/docs/blob/main/ASK.md#ask-39-is-the-apps-setup-flow-retired)].

**Request** (JSON body)

| Name          | In   | Type   | Required | Rules             |
| ------------- | ---- | ------ | -------- | ----------------- |
| `parent_name` | body | string | yes      | Must not be empty |

**Response** `200`

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387595000
}
```

**Errors:** `200` with `result` `false`: "Data cannot be blank!" (no body); "invalid parent\_name" (missing or empty).

**Side effects:** none.

## POST ?action=webcust\_list\_parents\_v2

Lists the caller's sites with group counts and red, amber and green task counts: the mobile site switcher and feed counts.

* **Auth:** user token. The user comes from the token payload; "invalid access!" when there is none (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/webapp.functions.php:9435-9438`).
* **Used by:** iOS (`SelectParentVC.fetchParentCount` and `AllTasksListVC.fetchParentCount`, with an empty JSON body) and Android (`ParentSwitcherBottomSheet` and `FeedViewModel`, with no body).

**Request** (JSON body, may be empty)

| Name           | In   | Type             | Required | Rules                                                                                                                                                                          |
| -------------- | ---- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `parent_uuids` | body | array of strings | no       | Only these sites. No caller sends it                                                                                                                                           |
| `user_uuid`    | body | string           | no       | When sent, the action also adds that user's live, unblocked sites and sets `parent_admin` from that user's role. No caller sends it, so the apps always get `parent_admin` `0` |

**Response** `200`: one row per site.

```json
{
  "result": true,
  "message": "Success",
  "serverTs": 1794387595000,
  "data": [
    {
      "uuid": "123",
      "fName": "Riverside Hotel",
      "fImage": null,
      "display_user_contact_data": 1,
      "fCustomerType": "paying_customer",
      "fCustomerTypeTs": 1794387595000,
      "currentTs": 1794387595000,
      "fAddress": "1 Quay Street",
      "perBusCreateNew": 1,
      "uuid_tUserType": "role-100",
      "perJobViewAll": 0,
      "uuid_tBusiness": "400",
      "parent_admin": 0,
      "region": "eu-west-1",
      "php_base_url": "https://php.example.com",
      "py_base_url": "https://py.example.com",
      "group_count": 1,
      "red": 2,
      "amber": 1,
      "green": 14,
      "groups": [ { "red": 2, "amber": 1, "green": 14, "business_uuid": "400" } ]
    }
  ]
}
```

* Each row has the site's fields, `currentTs` (the server's clock), the membership fields of the first group row found (`perBusCreateNew`, `uuid_tUserType`, `perJobViewAll`, `uuid_tBusiness`), `parent_admin`, `region` (always `eu-west-1`), the server's `php_base_url` and `py_base_url`, `group_count` (the caller's live groups in the site), the counts, and `groups` with the counts of each of those groups.
* A site is listed when it is not deleted, not blocked for the caller, and the caller has a membership in one of its task groups: a live one in a live group, or any one when the caller also has a live, unblocked site row. Churned sites stay listed, unlike in [GET /v1/app/parents](#get-v1appparents).
* Counts: in groups where the caller is an admin or may view all tasks, every live, unarchived task counts; in other groups, only tasks the caller created, follows or is assigned to.

**Errors:** `200` with `result` `false`: "invalid access!" (no user in the token); "Parent not found!" (no site left).

**Side effects:** none.

## POST ?action=webcust\_parent\_detail

Gets one site's details: the whole site row, its addresses, subscription and VAT details, and its admins and other users. The apps' site details and the payment page's business details read it.

* **Auth:** user token (as above). The action acts on the `user_uuid` in the body, who must have a live, unblocked site row of any role; otherwise "invalid user parent" (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/webapp.functions.php:5988-5997`). So every member gets the subscription and VAT details \[[ASK-124](https://github.com/snapfix/docs/blob/main/ASK.md#ask-124-should-members-who-are-not-admins-see-the-sites-billing-details)] and every column of the site row.
* **Used by:** iOS (`ManageAccountVC.fetchAdmins`, which reads the admin list), Android (`ParentAccountDetailFragment.callGetParentDetails`, which reads the admin list and the basic address), web\_payments (`ParentService.getParentDetails`, from the pay page's business details). All three send multipart form fields and also send `origin`, which the action doesn't read.

**Request** (form fields)

| Name          | In   | Type   | Required | Rules                |
| ------------- | ---- | ------ | -------- | -------------------- |
| `user_uuid`   | body | string | yes      | A member of the site |
| `parent_uuid` | body | string | yes      | The site             |

**Response** `200`: `data` is the whole [`tPri_Parent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_parent.md) row of the site, with these fields added:

* `address`: `basic`, `invoice` and `billing`, each the newest [`tPri_Address`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_address.md) row of that type, or `null`.
* `address_1`, `address_2`, `city`, `state`, `country` (the country code) and `postal_code`: the basic address, empty strings when there is none.
* `has_subscribed`: `true` whenever the site has a row in [`stripe_subscription`](https://docs.snapfix.com/engineering-reference/db/tables/stripe_subscription.md). `subscription_details` is filled only when the latest row is paid or updated: `id`, `created`, `current_period_start`, `current_period_end`, `latest_invoice`, `livemode`, `status`, `cancel_at_period_end` and `subscription_items` with their prices. Otherwise `null`.
* `vat_details`: the site's VAT IDs, read from Stripe.
* `admins` and `normal_parent_users`: the live, unblocked site rows, newest first, one per user; `normal_parent_users` holds every role that is not admin. Each has `uuid_tUser`, `fName`, `fFirstName`, `fLastName`, `fUsername`, `fCountryCode`, `fMobile`, `fImage`, `user_type` and `user_parent_deleted`.

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387595000,
  "data": {
    "uuid": "123",
    "fName": "Riverside Hotel",
    "fCustomerType": "paying_customer",
    "fRiskScore": 40,
    "fSalesName": "Sam Example",
    "address_1": "1 Quay Street",
    "address_2": "",
    "city": "London",
    "state": "",
    "country": "GB",
    "postal_code": "SW1A 1AA",
    "has_subscribed": false,
    "subscription_details": null,
    "admins": [ { "uuid_tUser": "200", "fName": "Jane Smith", "fUsername": "jane@example.com", "fCountryCode": "44", "fMobile": "7700900123", "user_type": "admin", "user_parent_deleted": 0 } ],
    "normal_parent_users": []
  }
}
```

**Errors:** `200` with `result` `false`: "Data cannot be blank!" (no form fields); "user\_uuid, parent\_uuid must be mentioned in the request!" (naming only the missing fields); "invalid user parent"; "No Parent found!".

**Side effects:** none on the database. The action calls Stripe for the VAT IDs on every call, and for the subscription when the latest subscription row is paid or updated.

## POST ?action=webcust\_parent\_list

Lists the sites where a user is an admin: the payment page's "Choose your Snapfix account" step.

* **Auth:** user token (as above). The action acts on the `user_uuid` in the body, so a signed-in user can list another user's admin sites.
* **Used by:** web\_payments (`ParentService.getUserParents`, from the pay page's site list; it sends the signed-in user's UUID).

**Request** (form fields)

| Name        | In   | Type   | Required | Rules    |
| ----------- | ---- | ------ | -------- | -------- |
| `user_uuid` | body | string | yes      | The user |

**Response** `200`: one row per site row of the user with `user_type` `admin`, sorted by site name, deleted and blocked rows included. Each has `uuid_tParent`, `uuid_tUser`, `user_parent_fNotes`, `user_parent_fDeleted`, `user_parent_created`, `user_parent_modified`, and the site's `fName`, `fCustomerType`, `fCustomerTypeTs`, `currentTs`, `fFirstInvoiceDateTs`, `fAddress`, `parent_fDeleted`, `parent_created` and `parent_modified` (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/webapp.functions.php:5968-5986`).

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387595000,
  "data": [
    { "uuid_tParent": "123", "uuid_tUser": "200", "user_parent_fDeleted": 0, "fName": "Riverside Hotel", "fCustomerType": "paying_customer", "parent_fDeleted": 0 }
  ]
}
```

**Errors:** `200` with `result` `false`: "Data cannot be blank!" (no form fields); "user\_uuid must be mentioned in the request!"; "No User Parent found!" (the user is admin of no site).

**Side effects:** none.

## POST ?action=webcust\_update\_parent\_v2

Changes a site's name, image, contact display, address and AI suggestion switches: the apps' site details save.

* **Auth:** user token. The caller comes from the token payload and must have a live, unblocked site row with `user_type` `admin`; otherwise "invalid access" (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/webapp.functions.php:9800-9817`). It is the only php-apis site write here that checks admin rights. A `user_uuid` in the body is not read.
* **Used by:** iOS (`ManageAccountVC.contactChanged`: the name, the current image, contact display and the AI switches; the address goes to [update\_parent\_address\_basic](#post-actionupdate_parent_address_basic)) and Android (`ParentAccountDetailFragment.callUpdateParentDataAPI`: every field except `fImage` and `fCountry`, plus `user_uuid`).

**Request** (JSON body)

| Name                                            | In   | Type    | Required | Rules                                                                                            |
| ----------------------------------------------- | ---- | ------- | -------- | ------------------------------------------------------------------------------------------------ |
| `parent_uuid`                                   | body | string  | yes      | The site. Missing: "invalid params"                                                              |
| `fName`                                         | body | string  | no       | Blank values are ignored. Must not match another live site's name: "account name already exists" |
| `fImage`                                        | body | string  | no       | An uploaded image's URL. Blank values are ignored                                                |
| `display_user_contact_data`                     | body | integer | no       | Stored as sent                                                                                   |
| `fAddress1`, `fAddress2`                        | body | string  | no       | Joined with ", " into the site's `fAddress`, and saved on the address row                        |
| `fCity`, `std_countries`                        | body | string  | no       | Saved on the site and on the address row                                                         |
| `fCountry`                                      | body | string  | no       | Saved on the site row only                                                                       |
| `fState`                                        | body | string  | no       | Saved on the address row only                                                                    |
| `fPostalCode`                                   | body | string  | no       | Saved on the address row only: the site row's update drops it by a typo                          |
| `fAiSuggestionEnabled`, `fAiUseOnlyExistingTag` | body | integer | no       | Saved on every settings row of the site                                                          |

At least one of `fName`, `fImage`, `display_user_contact_data`, `fAddress1`, `fAddress2`, `fCity`, `fCountry` and `std_countries` must be sent; the AI switches, `fState` or `fPostalCode` alone get "invalid data to update".

**Response** `200`, with no `data`:

```json
{
  "result": true,
  "message": "Account updated successfully",
  "serverTs": 1794387595000
}
```

**Errors:** `200` with `result` `false`: "Data cannot be blank!" (no body); "invalid access!" (no user in the token); "invalid params"; "invalid access" (not a site admin, or blocked); "invalid data to update"; "account name already exists".

**Side effects:**

* Updates [`tPri_Parent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_parent.md) with the fields above, `fModifiedTs`, `fServerTs` and `uuid_tUser_ModifiedBy`.
* Updates the AI switches on every [`tPri_SettingsParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_settingsparent.md) row of the site.
* When an address value is sent and the result differs from the current basic address (missing values keep the current ones), inserts a [`tPri_Address`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_address.md) row and points the basic [`tPri_ParentAddress`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_parentaddress.md) row at it, or adds that row when the site has none. When every address value is blank or missing, no address row is written.
* Writes a [sync queue entry](#common-side-effects). No time log.

## PUT /multisite/{multisiteUUID}

Changes a multi-site's name, description and image: the Multi-Site Console header's edit dialog.

* **Auth:** user token. The caller must be a multi-site user of the multi-site, in any role; no admin flag is checked \[[ASK-123](https://github.com/snapfix/docs/blob/main/ASK.md#ask-123-who-may-manage-a-multi-site-and-change-its-members-site-roles)] (authpy @ 5d5758661c, `model/feature_token_ops.py:2556-2570`).
* **Used by:** web (`MultisiteConsoleHttpService.updateMultisiteDetails`). The web's dialog requires a name and limits the name and description lengths; it sends all three fields, with an empty string for an empty one, which the server stores.

**Request** (JSON body)

| Name            | In   | Type   | Required         | Rules                                            |
| --------------- | ---- | ------ | ---------------- | ------------------------------------------------ |
| `multisiteUUID` | path | string | yes              | The multi-site                                   |
| `name`          | body | string | one of the three | The new name. Missing or `null`: kept            |
| `description`   | body | string | one of the three | The new description. Missing or `null`: kept     |
| `imageurl`      | body | string | one of the three | An uploaded image's URL. Missing or `null`: kept |

**Response** `200`: `data` is the multi-site after the change.

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387595000,
  "data": { "uuid": "500", "fName": "Riverside Group", "fDescription": "Riverside hotels", "fImage": null, "fModifiedTs": 1794387595000 }
}
```

**Errors:** `200` with `result` `false`: "invalid params" (no field to change); "unauthorised access" (not a multi-site user of it); "multisite not found" (unknown or deleted).

**Side effects:** updates `fName`, `fDescription`, `fImage`, `fModifiedTs`, `fServerTs` and `uuid_tUser_ModifiedBy` on [`tPri_MultiSite`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_multisite.md).

## POST /multisite/{multisiteUUID}/user/{userUUID}

Adds a user to a multi-site, or sets the user's role on sites: `site-admin` makes them a site admin with every site permission, `site-viewonly` a normal user with none.

* **Auth:** user token. The caller must be a multi-site user of the multi-site, in any role; a site-admin check is written but commented out (authpy @ 5d5758661c, `model/feature_token_ops.py:2770-2778`) \[[ASK-123](https://github.com/snapfix/docs/blob/main/ASK.md#ask-123-who-may-manage-a-multi-site-and-change-its-members-site-roles)]. The sites in `parents` are not checked to belong to the multi-site, so a multi-site user can make anyone, themselves included, an admin of any site.
* **Used by:** web: `setMultiSiteUserRole` with no body (the Multi-Site Console's Users page, "Make a Multi-site Admin"); `setParentUserRole` with one site and `site-admin` (Site Details' and the sites dropdown's admin prompt, for the caller); `setParentUserRoleFromMultiSite` with every ticked site (the user's Sites tab). The Sites tab also sends `siteName`, `siteImage` and `site-disabled` in each item, which the server ignores.

**Request** (JSON body, optional)

| Name                 | In   | Type             | Required | Rules                                                                                                             |
| -------------------- | ---- | ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `multisiteUUID`      | path | string           | yes      | The multi-site                                                                                                    |
| `userUUID`           | path | string           | yes      | The user to add or change                                                                                         |
| `parents`            | body | array of objects | no       | One item per site: `parentUUID` (required in each item) and `role` (`site-admin` or `site-viewonly`, the default) |
| `role`, `parentUUID` | body | string           | no       | Read but not used: only `parents` sets roles                                                                      |

How the roles are set (`model/feature_token_ops.py:2780-2933`):

* **The user is a multi-site user already:** `site-viewonly` demotes an admin site row to `normal` with every flag off, or adds a normal row when there is none. Any other role value makes the row `admin` with `fCreateNewBusiness`, `fManageTag`, `fEditTagHeader`, `fManageChecklist` and `fAiAutoAssignEnabled` on, or adds such a row.
* **The user is not a multi-site user:** without `parents`, the call adds the [`tPri_MultiSiteUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_multisiteuser.md) row. With `parents`, it sets the site rows (`site-admin` as above, any other value as `site-viewonly`) but adds no membership row. The web relies on two steps: ticking "Make a Multi-site Admin" sends the call without `parents`, which adds the membership, and the Sites tab later sends the site roles (web\_app\_v2 @ 0989b8e685, `src/app/pages/multisite-console/users/users.component.ts:134`, `src/app/pages/multisite-console/users/multisite-user-access/sites-tab/multisite-user-access-sites-tab.component.ts:341-345`).
* A row that already has the wanted role is left as it is.

**Response** `200`: `data` is `true`.

**Errors:** `200` with `result` `false`: "invalid params" (a missing ID, or a `parents` item with no `parentUUID`); "unauthorised access" (not a multi-site user of the multi-site).

**Side effects:** adds the [`tPri_MultiSiteUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_multisiteuser.md) row as above, and adds or updates [`tPri_UserParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userparent.md) rows, with the caller as the modifier.

## DELETE /multisite/{multisiteUUID}/user/{userUUID}

Removes a user from some sites of a multi-site, or from the whole multi-site.

* **Auth:** user token. The caller must be a multi-site user of the multi-site, in any role \[[ASK-123](https://github.com/snapfix/docs/blob/main/ASK.md#ask-123-who-may-manage-a-multi-site-and-change-its-members-site-roles)]. The sites in `parentUUIDs` are not checked to belong to the multi-site, so a multi-site user can remove anyone from any site.
* **Used by:** web: `removeMultiSiteUserRole` with no body (the Multi-Site Console's Users page, unticking "Make a Multi-site Admin"); `removeUserFromMultipleSites` with `parentUUIDs` (the sites unticked in the user's Sites tab).

**Request** (JSON body, optional)

| Name            | In   | Type             | Required | Rules                                                                                                                          |
| --------------- | ---- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `multisiteUUID` | path | string           | yes      | The multi-site                                                                                                                 |
| `userUUID`      | path | string           | yes      | The user                                                                                                                       |
| `parentUUIDs`   | body | array of strings | no       | The sites to remove the user from. Without it, the user leaves the whole multi-site. A `parentUUID` field is read but not used |

What changes (`model/feature_token_ops.py:2972-3061`):

* **With `parentUUIDs`:** the user's live site rows on those sites are marked deleted, whatever their role, also when the user is not a multi-site user.
* **Without, for a multi-site user:** the membership row is marked deleted, and so are the user's site rows on the multi-site's live sites, except admin rows: site admins keep their site access \[[ASK-127](https://github.com/snapfix/docs/blob/main/ASK.md#ask-127-should-removing-a-user-from-a-multi-site-also-remove-the-site-admin-roles-it-gave)]. When the multi-site has no live site, the user's non-admin rows on every site are marked deleted.
* **Without, for a user who is not a multi-site user:** nothing changes, and the call still answers success.

**Response** `200`: `data` is `true`.

**Errors:** `200` with `result` `false`: "invalid params" (a missing ID); "unauthorised access" (not a multi-site user of the multi-site).

**Side effects:** sets `fDeleted` on [`tPri_MultiSiteUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_multisiteuser.md) and [`tPri_UserParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userparent.md) rows as above, with the caller as the modifier.

## GET /multisite/{multisiteUUID}/user/{userUUID}/sites

Lists every live site of a multi-site with a user's role and access on it: the user's Sites tab, and Site Details' check of the caller's own role.

* **Auth:** user token. The caller must be a multi-site user of the multi-site; the named user need not be one.
* **Used by:** web (`MultisiteConsoleHttpService.getUserMultiSiteList`, from the user's Sites tab and from Site Details).

**Request**

| Name            | In   | Type   | Required | Rules          |
| --------------- | ---- | ------ | -------- | -------------- |
| `multisiteUUID` | path | string | yes      | The multi-site |
| `userUUID`      | path | string | yes      | The user       |

**Response** `200`: `data` is a list of [multi-site user site objects](#multi-site-user-site-object), one per live site of the multi-site.

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387595000,
  "data": [ { "siteName": "Riverside Hotel", "siteImage": null, "siteUUID": "123", "role": "site-admin", "site-disabled": 0 } ]
}
```

**Errors:** `200` with `result` `false`: "invalid params"; "unauthorised access" (the caller is not a multi-site user of it); "multisite not found" (the multi-site has no live site).

**Side effects:** none.

## GET /multisite/{multisiteUUID}/users

Lists the users of a multi-site's sites: group members, site users and multi-site users in one list, with search and paging. The Multi-Site Console's Users page shows it.

* **Auth:** user token. The caller must be a multi-site user of the multi-site.
* **Used by:** web (`UserHttpService.getMultisiteUserList`, from the Multi-Site Console's Users page; it sends `search`, `limit` 50 and `offset`). The Site Console's Users page uses a route of the [Users](https://docs.snapfix.com/engineering-reference/api/users.md) group instead.

**Request**

| Name            | In    | Type    | Required        | Rules                                                                                                 |
| --------------- | ----- | ------- | --------------- | ----------------------------------------------------------------------------------------------------- |
| `multisiteUUID` | path  | string  | yes             | The multi-site                                                                                        |
| `search`        | query | string  | no              | Matches the name, first or last name, username, country code, mobile number or user ID, ignoring case |
| `offset`        | query | integer | yes in practice | A row offset. Without it the handler fails with HTTP `500`                                            |
| `limit`         | query | integer | yes in practice | The page size, with no maximum. Without it the handler fails with HTTP `500`                          |

**Response** `200`: `data` is `{ "items": [...], "total": N }`, with one [multi-site user object](#multi-site-user-object) per user, ordered by first name. When no user matches, `data` is an empty list instead.

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387595000,
  "data": {
    "items": [ { "fFirstName": "Jane", "fLastName": "Smith", "fName": "Jane Smith", "fImage": null, "fUsername": "jane@example.com", "fCountryCode": "44", "fMobile": "7700900123", "uuid_tUser": "200", "sources": "userparent", "userTypes": "admin", "blocked": 0, "last_activity_ts": 0, "role": "parent-admin" } ],
    "total": 1
  }
}
```

* The sites are the multi-site's live sites, without those where the caller's newest site row is deleted.
* Left out: contractors on those sites, users who still have a temporary password and have never signed in, and the "System generated" user, which is also taken off the total. That user is a non-human account with no password that cannot sign in; it is the creator of records no person made, today automatic housekeeping tasks (api\_php\_live\_v2 @ ef3c4319f6, `app/Services/SystemUserService.php:20`). authpy leaves it out of the site user lists too (authpy @ 5d5758661c, `model/feature_token_ops.py:1698`, `:1992`, `:2328`).

**Errors:** `200` with `result` `false`: "invalid params"; "unauthorised access"; "multisite not found" (the multi-site has no live site); "no users found" (every site is left out for the caller).

**Side effects:** none.

## GET /user/{userUUID}/site/{siteUUID}/permission

Gets a user's role and site permissions on one site: the site permissions tab of the Site Console's Users page.

* **Auth:** user token. The caller must be a site admin (a live admin row), a group admin of a live group of the site, or a multi-site user of a multi-site that holds the site; otherwise "unauthorised access" (authpy @ 5d5758661c, `model/feature_token_ops.py:3820-3838`).
* **Used by:** web (`UserHttpService.getUserSitePermissions`, from the Site Console's Users page).

**Request**

| Name       | In   | Type   | Required | Rules    |
| ---------- | ---- | ------ | -------- | -------- |
| `userUUID` | path | string | yes      | The user |
| `siteUUID` | path | string | yes      | The site |

**Response** `200`: `data` is a [site permission object](#site-permission-object), from the user's newest live site row. A user with no live row gets `normal` and every flag `0`.

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387595000,
  "data": { "userType": "admin", "createNewGroup": 1, "manageTags": 1, "editTagHeader": 1, "manageChecklist": 1, "aiAutoAssignEnabled": 1 }
}
```

**Errors:** `200` with `result` `false`: "invalid params"; "unauthorised access".

**Side effects:** none.

## PUT /user/{userUUID}/site/{siteUUID}/permission

Sets a user's role and site permissions on one site.

* **Auth:** user token. The caller must be a site admin or a multi-site user of a multi-site that holds the site; group admins may read but not write. Any multi-site user, in any role, can make anyone, themselves included, a site admin \[[ASK-123](https://github.com/snapfix/docs/blob/main/ASK.md#ask-123-who-may-manage-a-multi-site-and-change-its-members-site-roles)] (`model/feature_token_ops.py:3846-3860`).
* **Used by:** web (`UserHttpService.updateUserSitePermissions`, from the Site Console's Users page: the site permissions tab, and the user header's site admin switch, which the Multi-Site Console doesn't show).

**Request** (JSON body; every field optional)

| Name                                                                                      | In   | Type    | Required | Rules                                                                                                                                                |
| ----------------------------------------------------------------------------------------- | ---- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `userUUID`                                                                                | path | string  | yes      | The user                                                                                                                                             |
| `siteUUID`                                                                                | path | string  | yes      | The site                                                                                                                                             |
| `userType`                                                                                | body | string  | no       | `admin` or `normal`. The server stores any string it gets. `admin` turns all five flags below on, but only when the user already has a live site row |
| `createNewGroup`, `manageTags`, `editTagHeader`, `manageChecklist`, `aiAutoAssignEnabled` | body | integer | no       | `1` or `0`                                                                                                                                           |

A missing field keeps its stored value, or its default (`normal`, `0`) when the user has no live site row yet.

**Response** `200`: `data` is the [site permission object](#site-permission-object) after the change.

**Errors:** `200` with `result` `false`: "invalid params"; "unauthorised access".

**Side effects:** adds a normal [`tPri_UserParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userparent.md) row when the user has no live one, then updates its flags, `user_type`, `fModifiedTs`, `fServerTs` and `uuid_tUser_ModifiedBy`.

## Site object

A site as the api\_php\_live\_v2 routes return it. Each route adds some blocks (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Resources/v1/ParentResource.php:21-90`):

* [GET /v1/app/parents](#get-v1appparents): `groupCount`, `assetRegCount`, `jobCounts`, `multiSites` and `settings`.
* [GET /v1/app/multiSites/{uuid}](#get-v1appmultisitesuuid): `siteDisabled`, `jobCounts` and `settings`.
* [GET](#get-v1appparentsuuid) and [PUT /v1/app/parents/{uuid}](#put-v1appparentsuuid): `hasSubscribed`, `settings`, `address`, `admins`, `users`, `subscription` and `meta`.

| Field                                              | Type             | Meaning                                                                                                                                                                                         |
| -------------------------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`, `name`, `image`                            | string           | The site's ID, name and image URL (`image` can be `null`)                                                                                                                                       |
| `stdCountries`                                     | string or null   | The two-letter country code                                                                                                                                                                     |
| `description`                                      | string or null   | The site's free-text address (`fAddress`)                                                                                                                                                       |
| `displayUserContactData`                           | integer          | `1` shows members' contact details to other members                                                                                                                                             |
| `customerType`, `customerTypeTs`                   | string, integer  | The customer type (`paying_customer`, `sales_trial`, `churn`, `test`, `investor_probono` or `0`) and when it was set, in ms                                                                     |
| `taskDashboardEnabled`                             | integer          | `1` shows site admins the Ops Dashboard tab on the web                                                                                                                                          |
| `createdBy`, `stripeCustomerId`, `defaultCurrency` | string or null   | The creator's user ID, the Stripe customer ID and the currency code                                                                                                                             |
| `isGroupAdmin`                                     | boolean or null  | `true` when the caller is a site admin or an admin of a group of the site. Set on the site list and on GET one site; `null` elsewhere                                                           |
| `housekeepingEnabled`                              | integer or null  | `ai_task_management_enabled` of the site's first building                                                                                                                                       |
| `hasSubscribed`                                    | boolean or null  | See [GET /v1/app/parents/{uuid}](#get-v1appparentsuuid); `null` on PUT                                                                                                                          |
| `siteDisabled`                                     | integer          | `1` when the caller's newest site row is deleted                                                                                                                                                |
| `groupCount`, `assetRegCount`                      | integer          | The caller's live groups and asset registers in the site                                                                                                                                        |
| `jobCounts`                                        | object           | `red`, `amber` and `green` task counts                                                                                                                                                          |
| `multiSites`                                       | array of strings | The IDs of the live multi-sites that hold the site, whoever's they are                                                                                                                          |
| `settings`                                         | object           | A [site settings object](#site-settings-object)                                                                                                                                                 |
| `address`                                          | object           | `basic`, `invoice` and `billing`, each a [site address object](#site-address-object)                                                                                                            |
| `admins`, `users`                                  | array            | The live site rows with type `admin`, and those with type `normal`, as [site member objects](#site-member-object). Contractors are in neither list                                              |
| `subscription`                                     | object or array  | The Stripe subscription: `id`, `created`, `currentPeriodStart`, `currentPeriodEnd`, `latestInvoice`, `livemode`, `status`, `cancelAtPeriodEnd` and `subscriptionItems`. `[]` when there is none |
| `meta`                                             | object           | `timezoneName`, `origin`, `salesPerson`, `riskScore`, `usersCount` and `tasksCount`. `salesPerson` and `riskScore` are internal fields                                                          |

## Site settings object

The caller's role and permissions on a site, and the site's switches, inside a [site object](#site-object).

| Field                                                                                                                                                                                | Type            | Meaning                                                                                                                                                                              |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `role`                                                                                                                                                                               | string          | `Admin` when the caller's newest live site row has type `admin`, else `User`                                                                                                         |
| `createNewBusiness`, `manageTag`, `editTagHeader`, `manageChecklist`                                                                                                                 | integer         | The caller's permissions to create groups, manage tags, edit tag folders and manage checklists. Real values on the site list only; always `0` on the multi-site list and on one site |
| `aiAutoAssignEnabled`                                                                                                                                                                | integer         | The caller's AI auto-assign permission. Always `0` on the multi-site list                                                                                                            |
| `region`                                                                                                                                                                             | string          | Always `eu-west-1`                                                                                                                                                                   |
| `base_urls`                                                                                                                                                                          | object          | `php` and `py`, always empty strings, so the web keeps its default hosts                                                                                                             |
| `chatEnable`, `aiImageEnable`, `aiVoiceEnable`, `aiVideoEnable`, `aiDocumentEnable`, `aiSuggestionEnabled`, `aiUseOnlyExistingTag`, `aiLanguageTranslationEnabled`, `aiAgentEnabled` | integer or null | The site's switches, from its [`tPri_SettingsParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_settingsparent.md) row                                           |

## Site member object

A user in a site's `admins` or `users` (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Resources/v1/UserResource.php:21-37`, `app/Models/ParentModel.php:117-148`).

| Field                                                                                   | Type           | Meaning                                                |
| --------------------------------------------------------------------------------------- | -------------- | ------------------------------------------------------ |
| `uuid`                                                                                  | string         | The user's ID                                          |
| `username`                                                                              | string or null | The user's sign-in email (`fUsername`)                 |
| `name`, `firstname`, `lastname`                                                         | string         | The user's names                                       |
| `countryCode`, `mobile`                                                                 | string or null | The user's mobile number                               |
| `image`                                                                                 | string or null | Photo URL                                              |
| `address`, `language`, `emailVerified`, `mobileVerified`, `notes`, `showAiAgentTooltip` | null           | Always `null` here: the member query doesn't load them |
| `userType`                                                                              | string         | `Admin` or `User`                                      |
| `userParentDeleted`                                                                     | integer        | Always `0`, since deleted rows are left out            |

The staff-only fields of the user resource are added only for the staff admin app.

## Multi-site object

A multi-site in [GET /v1/app/parents](#get-v1appparents).

| Field                  | Type           | Meaning                                               |
| ---------------------- | -------------- | ----------------------------------------------------- |
| `uuid`, `name`         | string         | The multi-site's ID and name                          |
| `image`, `description` | string or null | Its image URL and description                         |
| `jobCounts`            | object         | `red`, `amber` and `green` task counts over its sites |

## Site address object

One address of a site, in [GET](#get-v1appparentsuuid) and [PUT /v1/app/parents/{uuid}](#put-v1appparentsuuid): the newest live address of that type.

| Field                                        | Type           | Meaning                                                                                        |
| -------------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------- |
| `uuid`, `name`                               | string or null | The address row's ID and name; every field is `null` when the site has no address of that type |
| `address1`, `address2`, `postalCode`, `city` | string or null | The address lines, postal code and city. A stored text `"null"` reads as `null`                |
| `state`                                      | string or null | The state                                                                                      |
| `countryCode`                                | string or null | The two-letter country code                                                                    |

## Site row object (php-apis)

The site that [update\_parent\_address\_basic](#post-actionupdate_parent_address_basic) and [update\_parent\_image](#post-actionupdate_parent_image) return as `data` (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:2356-2426`).

| Field                                                                           | Type           | Meaning                                                                                                         |
| ------------------------------------------------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------- |
| `id`, `uuid`, `fName`, `fImage`, `fCustomerType`, `fCustomerTypeTs`, `fAddress` | mixed          | The site's [`tPri_Parent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_parent.md) columns     |
| `fDeleted`, `fCreatedTs`, `fModifiedTs`, `fServerTs`                            | integer        | Row state and times, in ms                                                                                      |
| `uuid_tUser_CreatedBy`, `uuid_tUser_ModifiedBy`                                 | string or null | Who created and last changed the site                                                                           |
| `parent_admin`                                                                  | integer        | `1` when the body's `user_uuid` has a live, unblocked admin row for the site, else `0`                          |
| `basic_address`                                                                 | object or null | The newest basic [`tPri_Address`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_address.md) row |
| `region`                                                                        | string         | `eu-west-1`, or `ap-south-1` for one hard-coded site                                                            |
| `php_base_url`, `py_base_url`                                                   | string         | The PHP and Python hosts from the server's settings                                                             |

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387700000,
  "data": {
    "id": 42,
    "uuid": "123",
    "fName": "Riverside Hotel",
    "fImage": "https://example.com/logo.png",
    "fCustomerType": "paying_customer",
    "fAddress": "1 Quay Street",
    "fDeleted": 0,
    "fModifiedTs": 1794387700000,
    "uuid_tUser_ModifiedBy": "200",
    "parent_admin": 1,
    "basic_address": { "uuid": "300", "fAddress1": "1 Quay Street", "fAddress2": "", "fPostalCode": "SW1A 1AA", "fCity": "London", "fState": "", "std_countries": "GB" },
    "region": "eu-west-1",
    "php_base_url": "https://php.example.com",
    "py_base_url": "https://py.example.com"
  }
}
```

## Multi-site user object

One user in [GET /multisite/{multisiteUUID}/users](#get-multisitemultisiteuuidusers).

| Field                              | Type           | Meaning                                                                                                                                                                                         |
| ---------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fFirstName`, `fLastName`, `fName` | string or null | The user's names                                                                                                                                                                                |
| `fImage`                           | string or null | Photo URL                                                                                                                                                                                       |
| `fUsername`                        | string or null | The sign-in email                                                                                                                                                                               |
| `fCountryCode`, `fMobile`          | string or null | The mobile number                                                                                                                                                                               |
| `uuid_tUser`                       | string         | The user's ID                                                                                                                                                                                   |
| `sources`                          | string         | Where the user was found, comma-separated: `userbusiness` (a group member), `userparent` (a site row), `usermultisite` (a multi-site user)                                                      |
| `userTypes`                        | string         | The user's types from those sources, comma-separated: the group role ID, the site row's `user_type`, `site-viewonly`                                                                            |
| `blocked`, `last_activity_ts`      | integer        | Always `0`: the queries that filled them are commented out                                                                                                                                      |
| `role`                             | string         | `site-admin` for a multi-site user with an admin site row, `site-viewonly` for another multi-site user, `parent-admin` for another user with an admin site row, `parent-user` for everyone else |

## Multi-site user site object

One site with a user's access on it, in [GET /multisite/{multisiteUUID}/user/{userUUID}/sites](#get-multisitemultisiteuuiduseruseruuidsites).

| Field                               | Type    | Meaning                                                                                                                                      |
| ----------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `siteName`, `siteImage`, `siteUUID` | string  | The site's name, image URL (can be `null`) and ID                                                                                            |
| `role`                              | string  | `site-admin` when the user's newest site row there is a live admin row, else `site-viewonly`. A disabled site always reports `site-viewonly` |
| `site-disabled`                     | integer | `1` when that newest row is deleted, or when a user who is not a multi-site user has no row there; else `0`                                  |

## Site permission object

A user's role and permissions on one site, in [GET](#get-useruseruuidsitesiteuuidpermission) and [PUT /user/{userUUID}/site/{siteUUID}/permission](#put-useruseruuidsitesiteuuidpermission).

| Field                 | Type    | Meaning                                                                                     |
| --------------------- | ------- | ------------------------------------------------------------------------------------------- |
| `userType`            | string  | The site row's `user_type`: `admin`, `normal`, or another stored value such as `contractor` |
| `createNewGroup`      | integer | `1` may create groups (`fCreateNewBusiness`)                                                |
| `manageTags`          | integer | `1` may manage tags (`fManageTag`)                                                          |
| `editTagHeader`       | integer | `1` may edit tag folders                                                                    |
| `manageChecklist`     | integer | `1` may manage checklists                                                                   |
| `aiAutoAssignEnabled` | integer | `1` may use AI auto-assign                                                                  |

## Common side effects

What the php-apis sections mean by these words.

* **Sync queue entry:** `logWebActionAsQueueEntry` adds a [`tPri_Queue`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_queue.md) row with the change. For a site, it also asks apipy to send an "API update required" push to every member of the site's groups, so their apps read the queue again. Both happen only while the server setting `WEB_QUEUE_SUPPORT` is on (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:39090-39180`, `:39257-39298`) \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)].
* **Time log row:** a [`time_tPri_Parent`](https://docs.snapfix.com/engineering-reference/db/tables/time_tpri_parent.md) row with the site's name, customer type and dates (`htmlphp/api/snapfix/class/time.parent.functions.php:9-33`).
* **Emails:** none.


---

# 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/console.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.
