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

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

Calls that other Snapfix services make to api\_php\_live\_v2's `/v1/internal` API: generating a room's housekeeping tasks after a PMS reservation change, applying a housekeeping task's room effects when php-apis saves its colour, and the room, area, tag and assignee changes that authpy's QR pipeline makes. No app or web page calls this group. The two PMS room status routes, `POST /v1/internal/rooms/{uuid}/status` and `POST /v1/internal/rooms/status/multi`, are in the [Integrations group](https://docs.snapfix.com/engineering-reference/api/integrations.md). The Cloudbeds onboarding guide names a route, `POST /v1/internal/pms/onboard`, that no route serves \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)].

* **Services:** `api_php_live_v2` at `https://z4.snapfix.com` (`/v1/internal`); other hosts in [Services and hosts](https://docs.snapfix.com/engineering-reference/api.md#services-and-hosts).
* **Auth:** the scripts login, one Basic credential pair that every caller shares; see [Authentication](#authentication). No user signs in; each section says which user the call acts as.
* **Used by:** cloudbeds\_py\_server and stayntouch\_py\_server (generate-tasks), php-apis (task-completed), authpy (the four QR task routes; whether the QR pipeline should make these changes is \[[ASK-186](https://github.com/snapfix/docs/blob/main/ASK.md#ask-186-should-the-ai-add-assignees-tags-rooms-and-areas-to-qr-form-tasks)]). py\_scheduler and the apps make no call to this group. 6 of the 12 endpoints have no known caller \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)].

| Method | Path                                                                                  | Service            | Purpose                                                                                                                                                                                                    |
| ------ | ------------------------------------------------------------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| POST   | `/v1/internal/housekeeping/bulk-reassignment`                                         | api\_php\_live\_v2 | Reassign housekeeping tasks in bulk (no caller)                                                                                                                                                            |
| POST   | `/v1/internal/housekeeping/bulk-reset`                                                | api\_php\_live\_v2 | Reset housekeeping tasks in bulk (no caller)                                                                                                                                                               |
| POST   | `/v1/internal/housekeeping/reassignment/{jobUuid}`                                    | api\_php\_live\_v2 | Reassign a housekeeping task (no caller)                                                                                                                                                                   |
| POST   | `/v1/internal/otp/send`                                                               | api\_php\_live\_v2 | Send a one-time code by WhatsApp (no caller)                                                                                                                                                               |
| POST   | `/v1/internal/otp/verify`                                                             | api\_php\_live\_v2 | Check a one-time code (no caller)                                                                                                                                                                          |
| POST   | [`/v1/internal/rooms/{uuid}/generate-tasks`](#post-v1internalroomsuuidgenerate-tasks) | api\_php\_live\_v2 | Generate a room's housekeeping tasks                                                                                                                                                                       |
| POST   | [`/v1/internal/task-completed/{jobUuid}`](#post-v1internaltask-completedjobuuid)      | api\_php\_live\_v2 | Apply a housekeeping task's room effects when its colour changes                                                                                                                                           |
| POST   | [`/v1/internal/tasks/area-add`](#post-v1internaltasksarea-add)                        | api\_php\_live\_v2 | Set a task's area, for the QR pipeline                                                                                                                                                                     |
| POST   | [`/v1/internal/tasks/assign/multi`](#post-v1internaltasksassignmulti)                 | api\_php\_live\_v2 | Assign users to a task, for the QR pipeline                                                                                                                                                                |
| POST   | [`/v1/internal/tasks/room-add`](#post-v1internaltasksroom-add)                        | api\_php\_live\_v2 | Set a task's room, for the QR pipeline                                                                                                                                                                     |
| POST   | `/v1/internal/tasks/soft-freeze`                                                      | api\_php\_live\_v2 | Soft-freeze the tasks it is sent, behind the scripts login and without the staff or site check \[[ASK-7](https://github.com/snapfix/docs/blob/main/ASK.md#ask-7-should-soft-freeze-still-run)] (no caller) |
| POST   | [`/v1/internal/tasks/tag/multi`](#post-v1internaltaskstagmulti)                       | api\_php\_live\_v2 | Add and remove a task's tags, for the QR pipeline                                                                                                                                                          |

* Rows marked "(no caller)" have no caller in any cloned repo, searched by path; they have no section below. php-apis's call to `housekeeping/reassignment` is commented out (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:47741`).
* The housekeeping routes the apps call are under `/v1/app/housekeeping/` ([Housekeeping API](https://docs.snapfix.com/engineering-reference/api/housekeeping.md)), and the task routes under `/v1/app/tasks/` ([Tasks API](https://docs.snapfix.com/engineering-reference/api/tasks.md)). They are separate routes that share handlers with these.
* `tasks/soft-freeze` runs the staff soft-freeze action ([Staff API](https://docs.snapfix.com/engineering-reference/api/staff.md)) for every task UUID in its body, with no check of the caller's staff role or the task's site (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Controllers/v1/Versions/v1_0/Admin/JobController.php:384-415`). `py-soft-freeze`, which \[[ASK-7](https://github.com/snapfix/docs/blob/main/ASK.md#ask-7-should-soft-freeze-still-run)] asks about, is not in the clones, so its calls could not be searched.

## Authentication

Every route here sits behind the scripts login, checked by the `scriptsAuth.basic` middleware (api\_php\_live\_v2 @ ef3c4319f6, `routes/internal.php:28`; `app/Http/Kernel.php:53`). The group gets only the `/v1` middleware (`api`, `version.control`, `localization`): no user token, blacklist, rate limit, temporary-password or verification check (`app/Providers/RouteServiceProvider.php:34-35`, `:119-122`). For the shared rules, see [Basic logins](https://docs.snapfix.com/engineering-reference/api.md#basic-logins).

* **Header:** `Authorization: Basic` with the username and password. Laravel compares them with the server settings `AUTH_USER_SCRIPT` and `AUTH_PASS_SCRIPT` (`config/app.php:298-299`), using `===`, not a constant-time comparison (`app/Http/Middleware/AuthorizeScriptsApi.php:18-22`). One pair opens all twelve routes.
* **Who holds it:** php-apis reads `LARAVEL_BASIC_AUTH_USERNAME` and `LARAVEL_BASIC_AUTH_PASSWORD` (php-apis @ 238ca4414e, `htmlphp/api/snapfix/config/constant_dev.php:271-272`, the development config). authpy reads `LARAVEL_INTERNAL_API_USERNAME` and `LARAVEL_INTERNAL_API_PASSWORD` (authpy @ 5d5758661c, `model/feature_qrform.py:1272-1276`). cloudbeds\_py\_server and stayntouch\_py\_server read `INTERNAL_SYSTEM_BASIC_AUTH_USERNAME` and `INTERNAL_SYSTEM_BASIC_AUTH_PASSWORD` (cloudbeds\_py\_server @ 17b14a0ee2, `app/core/background_tasks.py:753-754`; stayntouch\_py\_server @ 21e55b9071, `app/core/housekeeping_hooks.py:20-21`). The values are set per deployment and are not in the repos.
* **Wrong or missing login:** `401` with `WWW-Authenticate: Basic` and the body `{"error": "Unauthorized."}`, which has no `status` or `message` field (`AuthorizeScriptsApi.php:27`).
* **Acting user:** the login shows that a Snapfix service is calling, not which user it acts for. `task-completed` acts as the `user` query value or the task's last editor, and checks only that this user is a member of the task's group. The four QR task routes act as the body's `userUuid`; their group and permission checks run only for a signed-in user, so they never test the named user. Any existing user UUID is accepted.

## Common errors

Every route here answers the envelope in [Responses](https://docs.snapfix.com/engineering-reference/api.md#responses), with these codes besides its own:

* `401` for a missing or wrong scripts login, as above.
* `403` "Access denied" when the acting user isn't allowed to change the task (each section says what is checked).
* `404` "Resource not found" for an ID in the path or body that doesn't exist (api\_php\_live\_v2 @ ef3c4319f6, `app/Exceptions/Handler.php:46-48`).
* `422` for validation: the first failed rule's message ([Responses](https://docs.snapfix.com/engineering-reference/api.md#responses)).
* `400` with the message of the business rule that refused the call, such as "The task can not be updated". Other handled errors answer `400` "Something went wrong"; with `APP_DEBUG` on, they carry the exception's message, file and trace instead (`app/Http/Responses/ApiResponse.php:39-53`).
* `500` "An unexpected error occurred. Please try again later." for fatal errors (`app/Exceptions/Handler.php:80-82`).

## POST /v1/internal/rooms/{uuid}/generate-tasks

Generates one room's housekeeping tasks for today, as a PMS reservation change requires. Only buildings with AI task management get tasks. The callers send no body and read only the status code.

* **Auth:** scripts login. The login names no site, so any room ID works.
* **Acting user:** the handler looks up the site's oldest active admin (type admin, not blocked, not deleted; api\_php\_live\_v2 @ ef3c4319f6, `app/Services/ParentService.php:615-625`) and fails without one. It sets that admin as the services' user, but the run swaps in the system user for its whole length, so the tasks and the rows written with them belong to the system user (`app/Http/Controllers/v1/Versions/v1_0/Internal/InternalController.php:431-449`; `app/Services/RoomDailyTaskGeneratorService.php:80-113`). The admin only decides whether the call may run, as in the daily generation \[[ASK-277](https://github.com/snapfix/docs/blob/main/ASK.md#ask-277-should-generate-tasks-refuse-a-site-that-has-no-active-admin)].
* **Used by:**
  * cloudbeds\_py\_server, after a building sync finds a reservation cancelled, or its checkout extended from today or shortened to today (cloudbeds\_py\_server @ 17b14a0ee2, `app/core/cloudbeds_building_sync.py:780-781`, `:903-904`, `:1909-1921`, called at `:933-936`; `app/core/background_tasks.py:741-780`). After a `200` it skips the same room for five minutes (`background_tasks.py:738`, `:748-751`, `:767-768`).
  * stayntouch\_py\_server, after a reservation is cancelled, its checkout moves from today to a later day or from a later day to today, or it moves room, in which case both rooms are sent (stayntouch\_py\_server @ 21e55b9071, `app/core/housekeeping_hooks.py:29-52`, `:151-191`; called from `app/core/guest_status_sync.py:759`, `:823`).
  * On a checkout extension, both services first soft-delete the room's housekeeping tasks for today in the database themselves (`cloudbeds_building_sync.py:1909-1911`; `housekeeping_hooks.py:179-180`). Both use a 30-second timeout and count only `200` as success.

**Request**

| Name   | In   | Type   | Required | Rules                                                                                                              |
| ------ | ---- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `uuid` | path | string | yes      | The room. An unknown room, or a room of a deleted building, answers `404` (`app/Services/RoomService.php:110-121`) |

No body or query fields are read.

**Response** `200`

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "generatedTasksCount": 2,
    "skippedCount": 0,
    "deletedCount": 1,
    "jobUuids": ["710", "711"],
    "queuePriorityJobUuid": null
  }
}
```

* `generatedTasksCount` is the number of tasks made, and `jobUuids` their IDs.
* `skippedCount` and `deletedCount` are what the run reports, or `0` when it reports none. `deletedCount` counts the tasks the run archived or deleted, linked inspections included.
* `queuePriorityJobUuid` is `null` unless the room is in the PMS reservation queue (`fReservationQueue`); then it is the task that got queue priority, or `null` when there is none (`InternalController.php:451-468`).

**Errors:** [common errors](#common-errors); `400` "AI task management is not enabled for this building" when the room's building has `ai_task_management_enabled` off (`InternalController.php:427-429`; `app/Services/Housekeeping/HousekeepingEnabled.php:25-28`); `400` "No admin user found for parent" when the site has no active admin (`InternalController.php:435-437`); `404` for an unknown room.

**Side effects:**

* Creates the room's tasks for today in [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md), with their room links in [`tPri_JobRoom`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobroom.md), following the building's room status task rules (trigger `PMS_RESERVATION_CHANGE`, `InternalController.php:444-449`).
* Archives the tasks the run replaces, such as a stale red departure clean and its linked inspection. Runs from this route archive rather than delete, because every trigger but the schedule counts as a PMS reconciliation (`RoomDailyTaskGeneratorService.php:299-321`; `app/Enums/HousekeepingGenerationTrigger.php:23-26`).
* Unlocks a still-locked linked inspection whose cleaning task was archived, and sends the unlock notification (`RoomDailyTaskGeneratorService.php:465-468`, `:1808-1816`).
* Creates or restores the system user's admin membership in [`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md) for each group that gets a task (`RoomDailyTaskGeneratorService.php:1002-1008`; `app/Services/UserAssetBusinessService.php:39-58`).
* When the room is in the reservation queue, gives its open red cleaning task high priority, creating that task first when none is open (`app/Services/Housekeeping/PmsReservationQueuePriorityService.php`, `applyQueuePriority`).
* Request log, see [common side effects](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-side-effects).

## POST /v1/internal/task-completed/{jobUuid}

Applies a housekeeping task's room effects after its colour changes in the apps. An amber cleaning, or a green one whose approval was rejected, starts the cleaning on its room. A green cleaning or inspection completes it, which moves the room's status and unlocks the linked inspection.

* **Auth:** scripts login. The `setUserForTaskCompletion` middleware signs in the `user` query value, or else the task's last editor (`uuid_tUser_ModifiedBy`) (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Middleware/SetUserForTaskCompletion.php:30-43`). The handler then requires that user to be a member of the task's group (`app/Http/Controllers/v1/Versions/v1_0/Internal/InternalController.php:503-505`). The caller names the user, so the check shows membership, not who made the change.
* **Used by:** php-apis, when [`save_job_status_log`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-actionsave_job_status_log) stores the apps' status-log rows.
  * For a row created today (server date) with colour green, amber or yellow, on a task with `enum_JobType` 45, 46 or 0 that is not deleted and has a room status rule or a room guest status, `saveJobStatusLog_furtherChecks_debug` posts with `color`, `approvalStatus`, `user` (the row's creator) and `source=mobile` in the query (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:47569-47618`; called from `saveIntoTable` at `:1088` and `:1153`).
  * The save runs inline when `LEGACY_QUEUE_SUPPORT` is off and is queued when it is on; the production value is not in any repo (`:38826-38962`) \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)].
  * A second copy, `saveJobStatusLog_furtherChecks`, posts with no query values, so the task's stored colour and approval apply (`:47648-47709`). Only the `save_job_status_log_debug` action runs it (`html/api/snapfix/index.php:550-553`), and no client calls that action.
* **Timing:** php-apis waits one second before each call and makes it synchronously, with no timeout (`class.functions.php:47619`, `:47624-47634`). `save_job_status_log` is not in the dispatcher's early-reply list, so when the save runs inline the app's request waits for the call (`index.php:4451-4474`).
* **Reply:** php-apis neither checks nor retries the answer. It passes it to a log function whose body is commented out, so nothing is kept (`class.functions.php:47558-47567`, `:47634-47640`).

**Request**

| Name             | In            | Type    | Required | Rules                                                                                                         |
| ---------------- | ------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------- |
| `jobUuid`        | path          | string  | yes      | The task. An unknown task answers `404`; the middleware looks it up first (`SetUserForTaskCompletion.php:33`) |
| `color`          | query or body | string  | no       | `red`, `amber` or `green`. Default: the task's colour. `yellow`, which php-apis forwards, answers `422`       |
| `approvalStatus` | query or body | integer | no       | `-1`, `0` (rejected), `1` or `2` (`app/Enums/ApprovalStatus.php:7-10`). Default: the task's approval status   |
| `user`           | query         | string  | no       | The acting user's UUID. Default: the task's last editor. A user that doesn't exist answers `400`              |
| `source`         | query or body | string  | no       | Only `mobile`: the self-checker inspection is then unlocked but not co-greened                                |

Validation: `InternalController.php:491-496`.

**Response** `200`

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

The reply only says the call was accepted. It is also `success` when nothing was applied, for example for `red`, or for a task type with no room effects.

**Errors:** [common errors](#common-errors); `404` for an unknown task; `400` "Something went wrong" when `user` names no user, or when neither `user` nor the task's last editor is set (with `APP_DEBUG` on, the lookup's message) (`SetUserForTaskCompletion.php:41-42`); `422` for a value outside the lists above; `403` "Access denied" when the acting user isn't a member of the task's group.

**Side effects:** none when the task's building has AI task management off (`app/Services/AssetJobService.php:4736`, `:4853`). Otherwise:

* `amber` on a cleaning task applies the "cleaning started" action of the task's room status rule, when that action sets a room status (`AssetJobService.php:4734-4760`).
* `green` with `approvalStatus` `0` and an approver recorded runs the same action, which does nothing for an inspection (`InternalController.php:520-528`).
* Any other `green` on a cleaning or inspection task completes it, once: a claim keyed on the task and its red time, held for ten minutes, makes a repeat report in that window do nothing (`AssetJobService.php:75`, `:4831-4838`; `InternalController.php:529`). The completion:
  * skips the configured cleaning-only subtypes, which move nothing (`AssetJobService.php:4861-4865`);
  * runs the PMS reservation queue handling for the room (`:4867-4868`);
  * applies the rule's completion action: the room takes the rule's status in [`tPri_Room`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_room.md), a row goes to [`tPri_Log_RoomStatusChange`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_roomstatuschange.md), and the change is pushed to the PMS services ([Integrations API](https://docs.snapfix.com/engineering-reference/api/integrations.md)) (`app/Services/TaskCompletionService.php:90-130`);
  * for a cleaning, unlocks the linked inspection and co-greens it when it is a self-checker inspection, or creates an inspection when none is linked and the rule asks for one (`AssetJobService.php:4899-4949`, `:4988-5000`). An inspection that is already unlocked or archived is left alone (`InternalController.php:533-538`). The unlock is written to the inspection's chat under the acting user (`AssetJobService.php:4969-4986`).
* With `source=mobile`, the self-checker inspection is only unlocked, never co-greened, because the app completes it (`InternalController.php:507-509`, `:541-545`).
* Other colours and other task types change nothing.
* Request log, see [common side effects](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-side-effects).

The room statuses and linked tasks these actions touch are described in [Rooms](https://docs.snapfix.com/engineering-reference/api/rooms.md) and [Housekeeping](https://docs.snapfix.com/engineering-reference/api/housekeeping.md).

## POST /v1/internal/tasks/room-add

Sets a task's room for the QR pipeline. It runs the handler of [POST /v1/app/tasks/room-add](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptasksroom-add) as the user named in the body, so this section covers only what differs.

* **Auth:** scripts login, with no user token. The body's `userUuid` is the acting user: without it the call answers `403`, and an unknown user answers `404`. Unlike the app route, this route doesn't check that the user belongs to the task's group (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Controllers/v1/Versions/v1_0/App/JobRoomController.php:90-104`).
* **Used by:** authpy's QR pipeline. It runs in the background after a QR report that names a room, or that has an image and a site (authpy @ 5d5758661c, `model/feature_qrform.py:1026-1031`). It sends one request with one room: the first suggested room, or the first room the report named, which replaces the suggestion (`:1311-1327`, `:1410-1413`). `aiSuggested` is `1` unless the suggestion says it isn't from the AI. `userUuid` is the "Snapbot QR" user, the same user Laravel's own QR form uses (`:1042`; api\_php\_live\_v2 @ ef3c4319f6, `resources/schemas/hardCodedJob.schema.v1.php:4`).
* **QR pipeline calls:** the four QR task routes are called in parallel, each with a 30-second timeout. authpy logs an exception such as a timeout, ignores an error answer, and retries nothing (`feature_qrform.py:1326-1329`, `:1394-1426`).

**Request** (authpy sends multipart form fields)

| Name          | In   | Type             | Required                       | Rules                                                                                                                                                                                                                                      |
| ------------- | ---- | ---------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `jobUuid`     | body | string           | yes                            | The task. It must be actionable: not locked, not archived, and inside its time range when it has one (`app/Services/AssetJobService.php:141-165`)                                                                                          |
| `roomUuids`   | body | array of strings | yes                            | One room is linked. Unknown rooms and rooms outside the task's site are skipped; of the rest, the first the database returns, which need not be the first listed (`JobRoomController.php:137-184`; `app/Services/RoomService.php:736-744`) |
| `userUuid`    | body | string           | yes, when no user is signed in | The acting user                                                                                                                                                                                                                            |
| `aiSuggested` | body | integer          | no                             | `0` or `1`, default `0` (`app/Http/Requests/v1/JobRoom/CreateJobRoomRequest.php:18`, `:41`)                                                                                                                                                |

**Response** `200`: the same `data` as the app route, `jobRooms` and `jobchats` (`app/Http/Resources/v1/JobRoomResource.php`).

**Errors:** [common errors](#common-errors); `403` "Access denied" when `userUuid` is missing; `400` "The task can not be updated" when the task isn't actionable; `404` for an unknown task or user.

**Side effects:** the same as the [app route](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptasksroom-add):

* Removes the task's room links before the list is checked, so a list with no usable room leaves the task without one. Links the one room in [`tPri_JobRoom`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobroom.md).
* Writes an "Added" audit line with the `userUuid` user's name, and sends the pushes and the live update.
* For a cleaning or inspection task, applies the room's status rule and guest status to the task; for a cleaning task it may create the linked inspection (`JobRoomController.php:172-182`).
* Sets the task's `fBacklog` to `1` on every call, even when the building doesn't use AI task management (`:189`) \[[ASK-16](https://github.com/snapfix/docs/blob/main/ASK.md#ask-16-should-adding-a-room-to-a-task-always-mark-it-pending)].
* Writes the AI log when the site has AI suggestions on and this link, or the one it replaced, is AI-suggested (`:194-212`).

## POST /v1/internal/tasks/area-add

Sets a task's area for the QR pipeline. It runs the handler of [POST /v1/app/tasks/area-add](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptasksarea-add) as the user named in the body.

* **Auth:** scripts login, with no user token. `userUuid` is the acting user, as for [room-add](#post-v1internaltasksroom-add), and the group check doesn't run (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Controllers/v1/Versions/v1_0/App/JobAreaController.php:85-99`).
* **Used by:** authpy's QR pipeline, once, with the first suggested area and `aiSuggested` `1` (authpy @ 5d5758661c, `model/feature_qrform.py:1332-1347`). See [room-add](#post-v1internaltasksroom-add) for how the pipeline calls.

**Request** (authpy sends multipart form fields)

| Name          | In   | Type             | Required                       | Rules                                                                                                                                                                                                                |
| ------------- | ---- | ---------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `jobUuid`     | body | string           | yes                            | The task; it must be actionable, as for room-add                                                                                                                                                                     |
| `areaUuids`   | body | array of strings | yes                            | The first area in list order that is in the task's site is linked; areas of other sites are skipped. An unknown area before it answers `404` (`JobAreaController.php:133-139`; `app/Services/AreaService.php:76-83`) |
| `userUuid`    | body | string           | yes, when no user is signed in | The acting user                                                                                                                                                                                                      |
| `aiSuggested` | body | integer          | no                             | `0` or `1`, default `0` (`app/Http/Requests/v1/JobArea/CreateJobAreaRequest.php:18`, `:41`)                                                                                                                          |

**Response** `200`: the same `data` as the app route, `jobAreas` and `jobchats` (`app/Http/Resources/v1/JobAreaResource.php`).

**Errors:** [common errors](#common-errors); `403` "Access denied" when `userUuid` is missing; `400` "The task can not be updated"; `404` for an unknown task, user or area. The task's areas are already removed by the time an unknown area is found.

**Side effects:** the same as the [app route](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptasksarea-add): the task's rows in [`tPri_JobArea`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobarea.md) are replaced (`JobAreaController.php:126`), the "Added" audit line carries the `userUuid` user's name, the task is touched, and the AI log is written when the site has AI suggestions on and this link, or the one it replaced, is AI-suggested (`:173-194`).

## POST /v1/internal/tasks/assign/multi

Assigns users to a task, and unassigns any it names, for the QR pipeline. It runs the handler of [POST /v1/app/tasks/assign/multi](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptasksassignmulti) as the user named in the body.

* **Auth:** scripts login, with no user token. `userUuid` is the acting user. The "assign user" permission check runs only for a signed-in user, so it doesn't run here (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Controllers/v1/Versions/v1_0/App/JobUserAssignController.php:296-310`).
* **Used by:** authpy's QR pipeline, once, with every suggested assignee in `addUserUuids` and `aiSuggested` `1` (authpy @ 5d5758661c, `model/feature_qrform.py:1373-1389`). See [room-add](#post-v1internaltasksroom-add) for how the pipeline calls.

**Request** (authpy sends multipart form fields)

| Name              | In   | Type             | Required                       | Rules                                                                                                                                          |
| ----------------- | ---- | ---------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `jobUuid`         | body | string           | yes                            | The task. It must be actionable for assigning: as for room-add, except that a locked inspection is allowed (`JobUserAssignController.php:303`) |
| `addUserUuids`    | body | array of strings | no                             | Users to assign. Users who aren't active members of the task's group are left out (`app/Services/UserAssetJobAssignedService.php:313-315`)     |
| `removeUserUuids` | body | array of strings | no                             | Users to unassign, under the housekeeping unassign rules (`JobUserAssignController.php:319-322`). authpy doesn't send it                       |
| `userUuid`        | body | string           | yes, when no user is signed in | The acting user                                                                                                                                |
| `aiSuggested`     | body | integer          | no                             | `0` or `1`. With `1`, the assignment pushes are queued to run a minute later (`:380-400`)                                                      |

**Response** `200`: `data` is `users`, every user now assigned to the task, not only the ones this call added, as [user objects](https://docs.snapfix.com/engineering-reference/api/tasks.md#user-object), and `jobchats`, one audit line per change (`JobUserAssignController.php:405-438`).

**Errors:** [common errors](#common-errors); `403` "Access denied" when `userUuid` is missing; `400` "The task can not be updated" when the task isn't open to assignment; `404` for an unknown task or user.

**Side effects:** the same as the [app route](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptasksassignmulti): rows in [`tPri_JobUserAssigned`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobuserassigned.md) are added, restored or deleted; the audit lines carry the `userUuid` user's name; one queued `AssignUserJob` per change sends the push and the silent assignment update.

## POST /v1/internal/tasks/tag/multi

Adds and removes a task's tags in one call, for the QR pipeline. It runs the handler of [POST /v1/app/tasks/tag/multi](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptaskstagmulti) as the user named in the body.

* **Auth:** scripts login, with no user token. `userUuid` is the acting user, and the group check doesn't run (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Controllers/v1/Versions/v1_0/App/JobTagController.php:419-433`). The tag IDs aren't checked against the task's site either.
* **Used by:** authpy's QR pipeline, once, with every suggested tag in `addTagUuids` and `aiSuggested` `1` (authpy @ 5d5758661c, `model/feature_qrform.py:1352-1368`). See [room-add](#post-v1internaltasksroom-add) for how the pipeline calls.

**Request** (authpy sends multipart form fields)

| Name             | In   | Type             | Required                       | Rules                                                                                                                                                      |
| ---------------- | ---- | ---------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `jobUuid`        | body | string           | yes                            | The task; it must be actionable, as for room-add                                                                                                           |
| `addTagUuids`    | body | array of strings | no                             | Tags to add. Unknown tag UUIDs are skipped; tags of other sites are accepted (`app/Services/JobTagService.php:45-91`; `app/Services/TagService.php:29-32`) |
| `removeTagUuids` | body | array of strings | no                             | Tags to remove. An AI-made tag that no task uses any more is deleted (`JobTagService.php:99-113`)                                                          |
| `userUuid`       | body | string           | yes, when no user is signed in | The acting user                                                                                                                                            |
| `aiSuggested`    | body | integer          | no                             | `0` or `1`; `1` marks the added tags as AI suggestions                                                                                                     |

**Response** `200`: the same `data` as the app route. `jobTagsWithHeader` lists every tag folder of the group, empty ones included, each with `uuid`, `name`, `description`, `mandatory` and the task's tags in it (`JobTagService.php:145-174`; `app/Http/Resources/v1/TagHeaderResource.php`). `jobchats` has one audit line per tag changed.

**Errors:** [common errors](#common-errors); `403` "Access denied" when `userUuid` is missing; `400` "The task can not be updated"; `404` for an unknown task or user.

**Side effects:** the same as the [app route](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptaskstagmulti): rows in [`tPri_JobTag`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtag.md) are added, restored or deleted; unused AI tags are deleted in [`tPri_Tag`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_tag.md); the audit lines carry the `userUuid` user's name; the task is touched (`JobTagController.php:510`); the AI log is written when the site has AI suggestions on and the task has an AI-suggested tag (`:517-536`).


---

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