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

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

Asset registers, the assets in them, their attribute rules and values, and the tasks linked to an asset.

An asset register is a group whose type is `asset`: a row of [`tPri_Business`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_business.md) with `enum_BusinessType` `asset`. An asset is a task in such a group: a row of [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md), so the task fields, permissions, side effects and errors of the [Tasks API](https://docs.snapfix.com/engineering-reference/api/tasks.md) apply to it, and this page links to them instead of repeating them. Linking assets to a task is in the Tasks API ([`POST /v1/app/tasks/asset-link`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptasksasset-link), [`asset-unlink`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptasksasset-unlink)). The two iOS-only `parent_asset_*` actions read the legacy asset tables ([`assetReg`](https://docs.snapfix.com/engineering-reference/db/tables/assetreg.md), [`assetMain`](https://docs.snapfix.com/engineering-reference/db/tables/assetmain.md), [`assetAttribute`](https://docs.snapfix.com/engineering-reference/db/tables/assetattribute.md)), not the task tables.

* **Services:** `api_php_live_v2` at `https://z4.snapfix.com` (`/v1/app/asset-regs`, `/v1/app/assets`); `php-apis` at `https://z1.snapfix.com/api/snapfix/index.php`; `php-apis web` at `https://z1.snapfix.com/api/snapfix/web/index.php` (the `webcust_*` actions, none with a caller)
* **Auth:** api\_php\_live\_v2: user token (authpy access JWT in `Authorization: Bearer`). Most endpoints then check the caller's membership and permissions in the register, as their sections say ([task permissions](https://docs.snapfix.com/engineering-reference/api/tasks.md#task-permissions)). Some check only the token: the attribute rules, saving attribute values, copying and moving within one register, and the bulk priority changes. The bulk actions by ID take assets from any register. The register view checks let in a member of any multi-site. php-apis: user token, if `JWT_AUTH_ENABLED` is on; when it is off, every action takes the shared Basic login instead ([Basic logins](https://docs.snapfix.com/engineering-reference/api.md#basic-logins)) \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. Actions use the user UUID in the request, not the token's user, and don't check that the caller may read or change the register, asset or row they name.
* **Used by:** web\_app\_v2 (every `api_php_live_v2` route); iOS (`parent_asset_rules` and `parent_asset_details`, and the sync of `save_pri_jobattribute` and `save_pri_businessjobattributerule`); Android (the same sync); snapfix\_ai\_agent (Simon, the AI assistant: `GET /v1/app/asset-regs`, `POST /v1/app/assets/list`, `GET /v1/app/assets/{uuid}`). The apps call no `api_php_live_v2` route of this group. 13 of the 46 endpoints have no known caller.
* **Answers:** `api_php_live_v2` answers `{status, message, data}`; with no message of its own, `message` is "Operation was successful". The codes every route can give are the [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors) of the Tasks API. php-apis answers `200` with `result` true or false ([API conventions](https://docs.snapfix.com/engineering-reference/api.md#responses)).

The screens are in [assets](https://docs.snapfix.com/how-the-apps-work/screens/assets.md); the product is [Asset registers](https://docs.snapfix.com/product/features/assets/asset-registers.md).

| Method | Path                                                                                         | Service            | Purpose                                                                    |
| ------ | -------------------------------------------------------------------------------------------- | ------------------ | -------------------------------------------------------------------------- |
| GET    | [`/v1/app/asset-regs`](#get-v1appasset-regs)                                                 | api\_php\_live\_v2 | List a site's asset registers                                              |
| POST   | [`/v1/app/asset-regs`](#post-v1appasset-regs)                                                | api\_php\_live\_v2 | Create an asset register                                                   |
| GET    | [`/v1/app/asset-regs/{uuid}`](#get-v1appasset-regsuuid)                                      | api\_php\_live\_v2 | Get an asset register                                                      |
| PUT    | [`/v1/app/asset-regs/{uuid}`](#put-v1appasset-regsuuid)                                      | api\_php\_live\_v2 | Change an asset register                                                   |
| DELETE | [`/v1/app/asset-regs/{uuid}`](#delete-v1appasset-regsuuid)                                   | api\_php\_live\_v2 | Delete an asset register                                                   |
| POST   | [`/v1/app/asset-regs/{uuid}/attribute-rule`](#post-v1appasset-regsuuidattribute-rule)        | api\_php\_live\_v2 | Add attribute rules to an asset register                                   |
| PUT    | [`/v1/app/asset-regs/{uuid}/attribute-rule`](#put-v1appasset-regsuuidattribute-rule)         | api\_php\_live\_v2 | Change an asset register's attribute rules, or their order                 |
| DELETE | [`/v1/app/asset-regs/{uuid}/attribute-rule`](#delete-v1appasset-regsuuidattribute-rule)      | api\_php\_live\_v2 | Delete an attribute rule                                                   |
| GET    | [`/v1/app/asset-regs/{uuid}/attribute-rules`](#get-v1appasset-regsuuidattribute-rules)       | api\_php\_live\_v2 | List an asset register's attribute rules                                   |
| GET    | [`/v1/app/asset-regs/{uuid}/users`](#get-v1appasset-regsuuidusers)                           | api\_php\_live\_v2 | List an asset register's members                                           |
| POST   | [`/v1/app/assets`](#post-v1appassets)                                                        | api\_php\_live\_v2 | Create an asset                                                            |
| POST   | [`/v1/app/assets/all/archive`](#post-v1appassetsallarchive)                                  | api\_php\_live\_v2 | Archive or unarchive all of a register's assets of one colour              |
| POST   | [`/v1/app/assets/all/delete`](#post-v1appassetsalldelete)                                    | api\_php\_live\_v2 | Delete all of a register's assets of one colour                            |
| POST   | [`/v1/app/assets/all/lock`](#post-v1appassetsalllock)                                        | api\_php\_live\_v2 | Lock or unlock all of a register's assets of one colour                    |
| POST   | [`/v1/app/assets/all/priority`](#post-v1appassetsallpriority)                                | api\_php\_live\_v2 | Set the priority of all of a register's assets of one colour               |
| POST   | [`/v1/app/assets/all/status`](#post-v1appassetsallstatus)                                    | api\_php\_live\_v2 | Set the status of all of a register's assets of one colour                 |
| POST   | [`/v1/app/assets/copy`](#post-v1appassetscopy)                                               | api\_php\_live\_v2 | Copy an asset, within its register or to another one                       |
| POST   | [`/v1/app/assets/list`](#post-v1appassetslist)                                               | api\_php\_live\_v2 | List a register's assets                                                   |
| POST   | [`/v1/app/assets/move`](#post-v1appassetsmove)                                               | api\_php\_live\_v2 | Move an asset, within its register or to another one                       |
| POST   | [`/v1/app/assets/multi/archive`](#post-v1appassetsmultiarchive)                              | api\_php\_live\_v2 | Archive or unarchive several assets                                        |
| POST   | [`/v1/app/assets/multi/delete`](#post-v1appassetsmultidelete)                                | api\_php\_live\_v2 | Delete several assets                                                      |
| POST   | [`/v1/app/assets/multi/lock`](#post-v1appassetsmultilock)                                    | api\_php\_live\_v2 | Lock or unlock several assets                                              |
| POST   | [`/v1/app/assets/multi/priority`](#post-v1appassetsmultipriority)                            | api\_php\_live\_v2 | Set the priority of several assets                                         |
| POST   | [`/v1/app/assets/multi/status`](#post-v1appassetsmultistatus)                                | api\_php\_live\_v2 | Set the status of several assets                                           |
| POST   | [`/v1/app/assets/save-attributes`](#post-v1appassetssave-attributes)                         | api\_php\_live\_v2 | Save an asset's attribute values                                           |
| GET    | [`/v1/app/assets/{uuid}`](#get-v1appassetsuuid)                                              | api\_php\_live\_v2 | Get an asset                                                               |
| PUT    | [`/v1/app/assets/{uuid}`](#put-v1appassetsuuid)                                              | api\_php\_live\_v2 | Change one field of an asset                                               |
| DELETE | [`/v1/app/assets/{uuid}`](#delete-v1appassetsuuid)                                           | api\_php\_live\_v2 | Delete an asset                                                            |
| GET    | [`/v1/app/assets/{uuid}/jobs`](#get-v1appassetsuuidjobs)                                     | api\_php\_live\_v2 | List the tasks linked to an asset                                          |
| ANY    | `?action=asset_details`                                                                      | php-apis           | Get legacy assets by UUID, with their registers (no caller)                |
| POST   | [`?action=parent_asset_details`](#post-actionparent_asset_details)                           | php-apis           | Get legacy registers with their assets and attribute values                |
| POST   | [`?action=parent_asset_rules`](#post-actionparent_asset_rules)                               | php-apis           | Get a user's sites with their legacy attribute rules and registers         |
| ANY    | `?action=read_asset_main`                                                                    | php-apis           | Read legacy assets by UUID, generic table action (no caller)               |
| ANY    | `?action=read_asset_reg`                                                                     | php-apis           | Read legacy asset registers by UUID, generic table action (no caller)      |
| POST   | [`?action=save_pri_businessjobattributerule`](#post-actionsave_pri_businessjobattributerule) | php-apis           | Save attribute rules (`tPri_BusinessJobAttributeRule`) from the apps' sync |
| POST   | [`?action=save_pri_jobattribute`](#post-actionsave_pri_jobattribute)                         | php-apis           | Save attribute values (`tPri_JobAttribute`) from the apps' sync            |
| ANY    | `?action=webcust_asset_reg_create_permission`                                                | php-apis web       | Check whether the user may create an asset register (no caller)            |
| ANY    | `?action=webcust_business_attribute_delete`                                                  | php-apis web       | Delete an asset register's attribute rule (no caller)                      |
| ANY    | `?action=webcust_business_attribute_save`                                                    | php-apis web       | Save an asset register's attribute rules (no caller)                       |
| ANY    | `?action=webcust_business_attributes`                                                        | php-apis web       | List an asset register's attribute rules (no caller)                       |
| ANY    | `?action=webcust_jobattribute_save`                                                          | php-apis web       | Save a task attribute (no caller)                                          |
| ANY    | `?action=webcust_list_asset_groups`                                                          | php-apis web       | List a user's asset registers on a site, with asset counts (no caller)     |
| ANY    | `?action=webcust_list_assets`                                                                | php-apis web       | List assets (`getAssetJobs`) (no caller)                                   |
| ANY    | `?action=webcust_nfc_scan`                                                                   | php-apis web       | Post an NFC scan line to a task's chat (no caller)                         |
| ANY    | `?action=webcust_select_asset`                                                               | php-apis web       | Link legacy assets to a task (`tPri_JobAsset`) (no caller)                 |
| ANY    | `?action=webcust_unselect_asset`                                                             | php-apis web       | Unlink legacy assets from a task (`tPri_JobAsset`) (no caller)             |

Notes on the table:

* The method is the one the clients send. The iOS and Android clients send `POST` for every php-apis action they call. `ANY` stays on the rows no client calls.
* `asset_details` had one Android caller, which now sits inside a block comment (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/fragment/JobChatFragment.java:4545`). `read_asset_main` and `read_asset_reg` appear only in iOS's endpoint registry. No client calls the web dispatcher's asset actions. The three `webcust_business_attribute*` actions work on the current rule table, [`tPri_BusinessJobAttributeRule`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_businessjobattributerule.md).
* `?action=read_pri_job_asset` and `?action=save_pri_job_asset`, the task–asset link actions, are in the [Tasks API](https://docs.snapfix.com/engineering-reference/api/tasks.md#any-actionsave_pri_job_asset). `?action=admin_create_assets` is used by the staff admin app only and is in the [Staff API](https://docs.snapfix.com/engineering-reference/api/staff.md).

## GET /v1/app/asset-regs

Lists the asset registers of one site that the caller belongs to, with search, paging and asset counts per colour.

* **Auth:** user token. No permission check: the list holds only registers where the caller has a live membership. A multi-site user of the site gets the same list with `source` `site`; with `source` `multisite` they get every register of the site except those they were removed from (api\_php\_live\_v2 @ ef3c4319f6, `app/Services/AssetBusinessService.php:67-71`) \[[ASK-100](https://github.com/snapfix/docs/blob/main/ASK.md#ask-100-should-a-multi-site-member-see-every-asset-register-and-asset-of-the-multi-sites-sites)].
* **Used by:** web\_app\_v2 (`GroupHttpService.getGroupList` with the asset flag: the registers page, its filter drawer and the register pickers); snapfix\_ai\_agent (`AssetsApi.list_registers`, with `withJobsCount` 0).

**Request** (query string)

| Name            | In    | Type       | Required | Rules                                                                                                                                           |
| --------------- | ----- | ---------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `parent`        | query | string     | yes      | The site's UUID. Missing, or not a site: `422`                                                                                                  |
| `source`        | query | string     | no       | `site` (default) or `multisite`; see Auth. The web sends `multisite` while a multi-site is selected                                             |
| `search`        | query | string     | no       | Matches the register's name or description (`fAddress`), in any letter case                                                                     |
| `archived`      | query | integer    | no       | `1`: only archived registers; `0`: only active ones; without it, both. The web sends `0` unless its filter asks for archived registers          |
| `sortBy`        | query | string     | no       | `name`, `created` or `modified`. Without it, the register with the latest activity (its own change or its assets' last chat change) comes first |
| `orderBy`       | query | string     | no       | `asc` or `desc`, upper case accepted. Read only with `sortBy`; default `desc`                                                                   |
| `withJobsCount` | query | `0` or `1` | no       | Default `1`. `0` leaves out `statuses` and their counts                                                                                         |
| `limit`         | query | integer    | no       | Page size. Without it, every register comes back                                                                                                |
| `offset`        | query | integer    | no       | Page number from 1; used with `limit`                                                                                                           |

**Response** `200`

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "assetregs": [
      {
        "uuid": "register-200",
        "name": "Plant room",
        "image": null,
        "address": "Level 2",
        "inActive": 0,
        "notificationDisabled": 0,
        "parent": { "uuid": "site-100", "name": "Example Site", "image": null },
        "statuses": { "red": { "uuid": "status-1", "name": "red", "count": 2, "definition": "New assets" } },
        "settings": { "role": "Admin", "onboard": "Active", "jobToDoNfcAllowManualOverride": 0, "blockGalleryPhoto": 0 }
      }
    ],
    "createPermission": true,
    "totalCount": 3,
    "filterCount": 1,
    "pagination": { "total": 1, "perPage": 25, "currentPage": 1, "lastPage": 1, "from": 1, "to": 1 }
  }
}
```

* `assetregs` are [asset register objects](#asset-register-object) with `parent`, `settings` and, unless `withJobsCount` is `0`, `statuses`.
* `createPermission` is true when the caller may create registers on the site: the create flag (`fCreateNewBusiness`) of their site membership (`app/Policies/BusinessPolicy.php:65-74`).
* `totalCount` counts the caller's registers on the site, ignoring `search` and `archived`. `filterCount` counts the caller's task groups on the site that match `archived`, not registers; the web shows it in the registers tab total while a search is active.
* `pagination` comes only with `limit`.

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `422` for a missing or unknown `parent`, or a bad `source`, `sortBy`, `orderBy` or `archived`.

**Side effects:** none. Each register on the page costs its own queries for the caller's membership and, with `withJobsCount`, for the colour counts.

## POST /v1/app/asset-regs

Creates an asset register on a site from a template, with its statuses, settings and default attribute rules, and makes the caller its admin.

* **Auth:** user token. The caller's site membership needs its create flag (`fCreateNewBusiness`), else `403` "Access denied". An unknown `parent_uuid` gives `403` too.
* **Used by:** web\_app\_v2 (`AssetHttpService.createAssetRegister`, from the create register dialog on the registers page; it sends `parent_uuid` and `name` only).

**Request** (JSON or form body)

| Name            | In   | Type   | Required | Rules                                                                             |
| --------------- | ---- | ------ | -------- | --------------------------------------------------------------------------------- |
| `parent_uuid`   | body | string | yes      | The site                                                                          |
| `name`          | body | string | yes      | Unique among the site's asset registers that aren't deleted                       |
| `template_uuid` | body | string | no       | One of the built-in templates; default the blank template. Any other value: `422` |
| `address`       | body | string | no       | Validated, then not saved: the register's description is always "New Asset"       |

**Response** `200`, with the message "Asset Register created successfully": `data` is the new [asset register object](#asset-register-object) with `parent`, `statuses`, `settings`, `users` and `invited`.

```json
{
  "status": "success",
  "message": "Asset Register created successfully",
  "data": {
    "uuid": "register-201",
    "name": "Boiler room",
    "image": null,
    "address": "New Asset",
    "inActive": 0,
    "parent": { "uuid": "site-100", "name": "Example Site", "image": null }
  }
}
```

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `403` "Access denied" without the flag; `422` for a missing `parent_uuid` or `name`, a name already taken, or an unknown template; `404` only when a built-in template's own row is missing.

**Side effects:**

* Adds the register to [`tPri_Business`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_business.md) with the type `asset` and the origin from the `fOrigin` header. Copies the template's settings into [`tPri_SettingsBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_settingsbusiness.md), its statuses into [`tPri_Status`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_status.md) and its sub-statuses into [`tPri_StatusSub`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_statussub.md). Tag folders are not copied.
* Adds ten default attribute rules to [`tPri_BusinessJobAttributeRule`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_businessjobattributerule.md), none mandatory: "Asset ID", "Description", "Type", "Manufacturer", "Model", "Location" and "Notes" of type `text`, and "NFC", "QR" and "Barcode" of types `nfc`, `qr` and `barcode` in the category "Tracking" (`resources/other/default_attribute_rules.php`).
* Makes the caller an active admin of the register in [`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md) and refreshes their cached permissions. No push.

## GET /v1/app/asset-regs/{uuid}

Gets one asset register with its settings, statuses, invitations, and by default its members and attribute rules.

* **Auth:** user token. The caller must have a live membership of the register, or be a member of any multi-site: the check names no site, so a member of any multi-site passes for every register (`app/Http/Controllers/v1/Versions/v1_0/App/AssetRegController.php:143-147`, `app/Policies/BusinessPolicy.php:22-25`).
* **Used by:** web\_app\_v2 (`GroupHttpService.getGroupDetails` with `assets`: the register's asset list and asset pages, and its settings page).

**Request**

| Name                 | In    | Type       | Required | Rules                                                                                                                                              |
| -------------------- | ----- | ---------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`               | path  | string     | yes      | The register                                                                                                                                       |
| `withUsers`          | query | `0` or `1` | no       | Default `1`. `0` leaves out `users`                                                                                                                |
| `withTags`           | query | `0` or `1` | no       | Accepted and not used: registers return no tag folders                                                                                             |
| `withAttributeRules` | query | `0` or `1` | no       | Default `1`. `0` leaves out `attributeRules`. The web sends `withAttributes` instead, which the server doesn't read, so the rules always come back |

**Response** `200`: `data` is an [asset register object](#asset-register-object) with `parent`, `statuses`, `settings`, `invited`, and `users` and `attributeRules` unless switched off.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "uuid": "register-200",
    "name": "Plant room",
    "image": null,
    "address": "Level 2",
    "inActive": 0,
    "purpose": "",
    "instructions": "",
    "notificationDisabled": 0,
    "parent": { "uuid": "site-100", "name": "Example Site", "image": null },
    "users": [],
    "invited": [],
    "attributeRules": [{ "uuid": "rule-400", "category": null, "key": "Asset ID", "mandatory": 0, "valueType": "text", "sortOrder": 1000 }]
  }
}
```

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `403` "Access denied" for a caller who passes neither check; `404` when the register doesn't exist, is deleted or isn't an asset register.

**Side effects:** none.

## PUT /v1/app/asset-regs/{uuid}

Changes an asset register's name, description, guide texts, labels, image and settings.

* **Auth:** user token. `BusinessPolicy::update` lets in a register admin, a member with the settings permission (`perBusSettingsScreenAccess`), or any member who isn't read-only. So a member who can't open the settings page can still change the register through the API \[[ASK-97](https://github.com/snapfix/docs/blob/main/ASK.md#ask-97-who-may-change-and-delete-an-asset-register)]. A caller with no membership gets `403` with the text `messages.access_denied`.
* **Used by:** web\_app\_v2 (`GroupHttpService.updateGroup` with `assets`, from the register settings page and its drawer, which the web shows to users with `perBusSettingsScreenAccess`). It sends form data as `POST` with `_method=PUT` in the query string, which Laravel reads as `PUT`.

**Request** (form data or JSON; multipart with a photo)

| Name                                                                                                                                                                                                                                                                                                                                         | In   | Type       | Required | Rules                                                                                                                                                                                                                                                  |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `uuid`                                                                                                                                                                                                                                                                                                                                       | path | string     | yes      | The register                                                                                                                                                                                                                                           |
| `name`                                                                                                                                                                                                                                                                                                                                       | body | string     | yes      | Unique among the site's asset registers that aren't deleted                                                                                                                                                                                            |
| `address`                                                                                                                                                                                                                                                                                                                                    | body | string     | yes      | The description                                                                                                                                                                                                                                        |
| `inActive`                                                                                                                                                                                                                                                                                                                                   | body | boolean    | no       | Archives the register (`fInActive`)                                                                                                                                                                                                                    |
| `purpose`, `instructions`                                                                                                                                                                                                                                                                                                                    | body | string     | no       | Nullable. The register's guide texts                                                                                                                                                                                                                   |
| `redDefinition`, `amberDefinition`, `greenDefinition`                                                                                                                                                                                                                                                                                        | body | string     | no       | Nullable. What each colour means in this register                                                                                                                                                                                                      |
| `jobToDoNfcAllowManualOverride`, `dailyGroupEmailAndReport`, `tag1Required`, `tag2Required`, `tag3Required`, `roomRequired`, `assetRequired`, `assigneeRequired`, `taskApprovalRequired`, `blockGreenWhenChecklistNotComplete`, `autoYellowWhenChecklistStart`, `autoGreenWhenChecklistCompleted`, `autoArchiveEnabled`, `blockGalleryPhoto` | body | boolean    | no       | Settings flags, as on groups: manual NFC checks, the daily email, required tags, room, asset and assignee, approval for green, green blocked until the checklist is done, the checklist moving the colour itself, auto-archive, and camera-only photos |
| `tagsRequired`                                                                                                                                                                                                                                                                                                                               | body | string     | no       | The required tag folders, as JSON text                                                                                                                                                                                                                 |
| `autoArchivePeriodEnum`                                                                                                                                                                                                                                                                                                                      | body | string     | no       | Nullable; `week` is the only value                                                                                                                                                                                                                     |
| `autoArchiveInterval`, `areaAssociatedTask`, `areaOrRoomAssociatedTask`                                                                                                                                                                                                                                                                      | body | integer    | no       | Nullable. The auto-archive interval is in weeks                                                                                                                                                                                                        |
| `file`                                                                                                                                                                                                                                                                                                                                       | body | image file | no       | `jpg`, `jpeg`, `png` or `gif`, up to the `fileMaxSize` setting                                                                                                                                                                                         |

`purpose`, `instructions` and the three definitions are written on every call: one left out is saved empty.

**Response** `200`, with the message "Asset Register updated successfully": `data` is the [asset register object](#asset-register-object) with `parent`, `statuses`, `settings`, `users` and `invited`.

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `403` "Access denied"; `404` for an unknown register; `422` for a missing or taken `name`, a missing `address`, or a bad file.

**Side effects:** updates the register's row in [`tPri_Business`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_business.md) (name, description, archived flag, guide texts and origin) and its flags in [`tPri_SettingsBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_settingsbusiness.md). A new photo goes to file storage and the old one is deleted. No push.

## DELETE /v1/app/asset-regs/{uuid}

Deletes an asset register. The row is marked deleted, not removed.

* **Auth:** user token. The same rule as [PUT](#put-v1appasset-regsuuid), so any member who isn't read-only can delete the register. Whether only admins should delete is open \[[ASK-97](https://github.com/snapfix/docs/blob/main/ASK.md#ask-97-who-may-change-and-delete-an-asset-register)].
* **Used by:** web\_app\_v2 (`GroupHttpService.deleteGroup` with `assets`, from "Delete This Asset Register" in the settings drawer). The web's confirmation, 'Are you sure you want to delete the "{name}" asset register?', doesn't say what happens to the assets \[[ASK-99](https://github.com/snapfix/docs/blob/main/ASK.md#ask-99-what-should-deleting-an-asset-register-do-to-its-assets)].

**Request:** `uuid` in the path. No body.

**Response** `200`, with the message "Asset Register deleted successfully" and `data` `null`.

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `403` "Access denied"; `404` for an unknown register.

**Side effects:** sets `fDeleted` on the register's row in [`tPri_Business`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_business.md). Its assets, attribute rules and memberships are left as they are \[[ASK-99](https://github.com/snapfix/docs/blob/main/ASK.md#ask-99-what-should-deleting-an-asset-register-do-to-its-assets)].

## POST /v1/app/asset-regs/{uuid}/attribute-rule

Adds attribute rules to an asset register. A rule is one field every asset of the register can have, such as a serial number, a QR code or an NFC tag.

* **Auth:** user token. No membership or permission check: any signed-in user can add rules to any register by its UUID.
* **Used by:** web\_app\_v2 (`AssetHttpService.saveAttributes` with `isUpdate` false, from the attribute dialog on the register settings page).

**Request** (JSON body)

| Name                                                 | In   | Type       | Required | Rules                                                                                                                                                       |
| ---------------------------------------------------- | ---- | ---------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`                                               | path | string     | yes      | The register                                                                                                                                                |
| `attributes`                                         | body | array      | yes      | One or more rules                                                                                                                                           |
| `attributes.*.key`                                   | body | string     | yes      | The attribute's name. Not checked for duplicates, so a register can hold two rules with the same key; the web dialog checks against the rules it has loaded |
| `attributes.*.category`                              | body | string     | no       | Nullable. The section the rule sits in, such as "Tracking"                                                                                                  |
| `attributes.*.sortOrder`                             | body | number     | yes      | Position in the list                                                                                                                                        |
| `attributes.*.valueType`                             | body | string     | yes      | `text`, `number`, `date`, `barcode`, `qr` or `nfc`; the web offers all six                                                                                  |
| `attributes.*.mandatory`                             | body | `0` or `1` | yes      | Whether assets must have a value                                                                                                                            |
| `attributes.*.keyUnique`, `attributes.*.valueUnique` | body | `0` or `1` | no       | Default `0`                                                                                                                                                 |
| `ignoreWarning`                                      | body | `0` or `1` | no       | Accepted, not read on create                                                                                                                                |
| `origin`                                             | body | string     | no       | Validated, then not used. The stored origin always comes from the `fOrigin` header, even when a rule carries its own `origin`                               |

**Response** `200`: `data` is every rule of the register, new ones included, as [attribute rule objects](#attribute-rule-object).

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": [
    { "uuid": "rule-401", "category": null, "key": "Serial number", "mandatory": 1, "valueType": "text", "sortOrder": 100 }
  ]
}
```

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `404` for an unknown register; `422` for a missing or bad field.

**Side effects:** adds one row per rule to [`tPri_BusinessJobAttributeRule`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_businessjobattributerule.md). No push.

## PUT /v1/app/asset-regs/{uuid}/attribute-rule

Changes attribute rules of an asset register. The web also reorders rules with it.

* **Auth:** user token. No membership or permission check. Each rule must belong to the register in the path.
* **Used by:** web\_app\_v2 (`AssetHttpService.saveAttributes` with `isUpdate` true, from the attribute dialog and from drag and drop on the register settings page; a reorder sends the section's rules with `sortOrder` 100, 200, 300 and so on, and `ignoreWarning` 1).

**Request** (JSON body)

| Name                                                                                                                                                        | In   | Type       | Required | Rules                                                 |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- | ---------- | -------- | ----------------------------------------------------- |
| `uuid`                                                                                                                                                      | path | string     | yes      | The register                                          |
| `attributes`                                                                                                                                                | body | array      | yes      | One or more rules                                     |
| `attributes.*.uuid`                                                                                                                                         | body | string     | yes      | The rule to change                                    |
| `attributes.*.key`                                                                                                                                          | body | string     | yes      | The attribute's name. Not checked for duplicates      |
| `attributes.*.category`, `attributes.*.sortOrder`, `attributes.*.valueType`, `attributes.*.mandatory`, `attributes.*.keyUnique`, `attributes.*.valueUnique` | body |            | no       | As on create. A field left out keeps its stored value |
| `ignoreWarning`                                                                                                                                             | body | `0` or `1` | no       | Must be `1` to change a rule that has stored values   |
| `origin`                                                                                                                                                    | body | string     | no       | Validated, then not used                              |

**Response** `200`: `data` is every rule of the register, as [attribute rule objects](#attribute-rule-object).

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `400` "The attribute rule is not art of the asset reg." (sic) for a rule of another register; `400` "There are N active asset(s) using this attribute. Changes to this attribute rule will impact with the existing assets. Are you sure to apply the changes?" when the rule has stored values and `ignoreWarning` isn't `1` (N is counted as on [delete](#delete-v1appasset-regsuuidattribute-rule)); `404` for an unknown rule or register; `422` for a bad field.

**Side effects:** updates the rules' rows in [`tPri_BusinessJobAttributeRule`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_businessjobattributerule.md), one at a time. The assets' values in [`tPri_JobAttribute`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobattribute.md) are not changed. No push.

## DELETE /v1/app/asset-regs/{uuid}/attribute-rule

Deletes one attribute rule.

* **Auth:** user token. No membership or permission check, and the rule isn't checked against the register in the path: any signed-in user can delete any rule by its UUID, with any register's UUID in the path.
* **Used by:** web\_app\_v2 (`AssetHttpService.deleteAttribute`, from the register settings page; after the in-use warning, it sends the call again with `ignoreWarning` 1 when the user confirms).

**Request** (JSON body)

| Name                | In   | Type       | Required | Rules                                                   |
| ------------------- | ---- | ---------- | -------- | ------------------------------------------------------- |
| `uuid`              | path | string     | yes      | A register; it only picks the rule list that comes back |
| `attributeRuleUuid` | body | string     | yes      | The rule to delete                                      |
| `ignoreWarning`     | body | `0` or `1` | no       | Must be `1` to delete a rule that has stored values     |

**Response** `200`: `data` is the remaining rules of the register in the path, as [attribute rule objects](#attribute-rule-object).

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `400` "There are N active asset(s) using this attribute. Deleting this attribute rule will impact the existing assets. Are you sure to delete the attribute?" when the rule has stored values and `ignoreWarning` isn't `1`; `404` for an unknown rule or register. N counts the rule's values that aren't deleted, also those of deleted assets, so a register whose assets are all deleted can still warn.

**Side effects:** marks the rule deleted (`fDeleted`) in [`tPri_BusinessJobAttributeRule`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_businessjobattributerule.md). The values in [`tPri_JobAttribute`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobattribute.md) stay; asset answers stop listing values whose register rule is deleted. The web's warning says the delete "will remove the attribute from any assets that are currently using it" \[[ASK-102](https://github.com/snapfix/docs/blob/main/ASK.md#ask-102-should-deleting-an-attribute-rule-remove-its-values-from-the-assets)]. No push.

## GET /v1/app/asset-regs/{uuid}/attribute-rules

Lists an asset register's attribute rules.

* **Auth:** user token. The same check as [GET /v1/app/asset-regs/{uuid}](#get-v1appasset-regsuuid).
* **Used by:** web\_app\_v2 (`AssetHttpService.getAttributes`: the asset's attribute section and dialog, and the add asset dialog). The web keeps one copy of the answer, whichever register it was for, until the asset attribute section closes.

**Request:** `uuid` in the path. No body.

**Response** `200`: `data` is a list of [attribute rule objects](#attribute-rule-object), deleted rules left out, in the order the database returns them (no sort is set).

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `403` "Access denied"; `404` for an unknown register.

**Side effects:** none.

## GET /v1/app/asset-regs/{uuid}/users

Lists an asset register's members, with their roles, onboarding states and permissions.

* **Auth:** user token. The same check as [GET /v1/app/asset-regs/{uuid}](#get-v1appasset-regsuuid). Every member who passes sees every other member's mobile number and home address.
* **Used by:** web\_app\_v2 (`UserHttpService.getGroupUserList` with `assets`: the users dialog of an asset, and the asset list's user filter).

**Request:** `uuid` in the path. No body.

**Response** `200`: `data` is a list of [register member objects](#register-member-object): every member whose membership isn't deleted, read-only members included; user accounts marked deleted are left out. On the QA site the list held two deleted profiles whose names start with "DEL-DEL-"; their emails have no prefix.

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `403` "Access denied"; `404` for an unknown register.

**Side effects:** none.

## POST /v1/app/assets

Creates an asset in a register from a title and a photo or a large text, and optionally a voice note.

* **Auth:** user token. The caller must be allowed to create tasks in the register: an admin, or a member with the "create task" permission who isn't read-only ([task permissions](https://docs.snapfix.com/engineering-reference/api/tasks.md#task-permissions)).
* **Used by:** web\_app\_v2 (`TaskHttpService.createTask` with the asset flag, from the asset list's "Add an Asset" dialog, always as form data). The web creates the asset first, then saves the register's mandatory attribute values with [save-attributes](#post-v1appassetssave-attributes) in a second call.

**Request** (form data; multipart with a file)

| Name                                                | In   | Type       | Required             | Rules                                                             |
| --------------------------------------------------- | ---- | ---------- | -------------------- | ----------------------------------------------------------------- |
| `businessUuid`                                      | body | string     | yes                  | The register                                                      |
| `title`                                             | body | string     | yes                  | At most 255 characters. `titleValueAi` replaces it when sent      |
| `largeTitle`                                        | body | string     | without `file`       | Nullable. A large text shown in place of a photo                  |
| `file`                                              | body | image file | without `largeTitle` | `jpg`, `jpeg`, `png` or `gif`, up to the `fileMaxSize` setting    |
| `description`                                       | body | string     | no                   | Nullable                                                          |
| `imageUrl`                                          | body | string     | no                   | Stored as the asset's photo when no file is sent, with no check   |
| `voiceFileUrl`                                      | body | URL        | with `voiceDuration` | Makes a voice asset and posts the voice note in its chat          |
| `voiceDuration`                                     | body | string     | with `voiceFileUrl`  | `HH:MM`                                                           |
| `titleValueAi`, `imageValueAi`, `transcriptValueAi` | body | string     | no                   | Nullable. Values the AI suggested; they mark the asset as AI-made |

The request class also accepts `jobType`, `assetUuid`, `chatId` and `messageId` (together), `aiTitle`, `aiBusinessUuid`, `aiTitleSuggestion`, `aiBusinessSuggestion`, `priorityLevel`, and the housekeeping fields `cleaningType`, `cleaningSubType` and `jobDuration`, which fail unless `jobType` is a cleaning (or, for `jobDuration`, inspection) task. This action reads none of them. A `search_text` is dropped too: the search text is always built from the colour, reference, title and description.

The new asset has `enum_JobType` 43 (44 for a voice asset), is green with the sub-status "New" \[[ASK-103](https://github.com/snapfix/docs/blob/main/ASK.md#ask-103-should-a-new-asset-start-green)], is unlocked and unarchived, has no priority and no signature requirement, gets an eight-digit reference number, and takes its origin from the `fOrigin` header.

**Response** `200`: `data` is `{ "asset": ..., "jobchat": ... }`: the new asset ([asset object](#asset-object)) with `business`, `status`, `subStatus`, `attributes` and `users`, and the "created" line as a [chat item](https://docs.snapfix.com/engineering-reference/api/tasks.md#chat-item-object).

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "asset": {
      "uuid": "asset-300",
      "title": "Boiler 3",
      "color": "green",
      "reference": "38760012",
      "business": { "uuid": "register-200", "name": "Plant room", "image": null },
      "status": { "uuid": "status-3", "name": "green" },
      "subStatus": { "uuid": "substatus-1", "name": "New" }
    },
    "jobchat": { "uuid": "chat-500", "text": "<b>Jane Smith</b> created Asset", "type": 6 }
  }
}
```

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `403` "Access denied" without the permission; `404` for an unknown register; `422` for validation, such as neither `largeTitle` nor `file`, or a title over 255 characters.

**Side effects:** adds the asset to [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md) and the creator as a follower in [`tPri_JobUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobuser.md); stores the photo in file storage; adds the "created" audit line to [`tPri_JobChat`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobchat.md), and the voice note line for a voice asset; writes viewed rows for the asset and the register; sends a silent update and a "created" push to the register ([common side effects](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-side-effects)). The Firebase task counter is not updated: that call is commented out (`app/Http/Controllers/v1/Versions/v1_0/App/AssetController.php:267-271`).

## POST /v1/app/assets/all/archive

Archives or unarchives every asset of one colour in a register that the caller can see and that matches the filters.

* **Auth:** user token. A register admin, or a member with the "archive task" permission who isn't read-only.
* **Used by:** web\_app\_v2 (`TaskHttpService.taskMultiAction` with `archive`, `all` and the asset flag, from the asset list's multi-select when the selection covers more assets than are loaded; the web always sends `value` "1").

**Request** (JSON body)

| Name           | In   | Type   | Required | Rules                                                                                                                                                                                            |
| -------------- | ---- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `businessUuid` | body | string | yes      | The register                                                                                                                                                                                     |
| `color`        | body | string | yes      | `red`, `amber` or `green`: the colour whose assets change; amber includes the old yellow                                                                                                         |
| `value`        | body | string | yes      | "1" archives, "0" unarchives                                                                                                                                                                     |
| filters        | body |        | no       | The [task list filters](https://docs.snapfix.com/engineering-reference/api/tasks.md#task-list-filters) of `POST /v1/app/tasks/list`: this route reads them through the task list's request class |

Only the assets the caller can see are reached ([task permissions](https://docs.snapfix.com/engineering-reference/api/tasks.md#task-permissions)). Assets already in that state, locked assets and assets outside their time range are skipped. To unarchive, the body must also send `archivedTasks` 1: without it, the default filter keeps only current assets, nothing matches, and the call answers `403` "Assets not found".

**Response** `200`: `data` is a [bulk result](#bulk-result-object). The total also counts a linked inspection task that a cleaning asset archives with it.

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `403` "Access denied" without the permission; `403` "Assets not found" when no asset matches; `404` for an unknown register; `422` for a bad field.

**Side effects:** for each changed asset, sets `fArchived`, `fArchivedTs` and `uuid_tUser_ArchivedBy` in [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md) (unarchiving also ends a snooze), adds an audit line and writes viewed rows, one asset at a time; then a viewed row for the register and one silent update push to the register's devices.

## POST /v1/app/assets/all/delete

Deletes every asset of one colour in a register that the caller can see.

* **Auth:** user token. A register admin, or a member with the "delete task" permission who isn't read-only.
* **Used by:** web\_app\_v2 (`TaskHttpService.taskMultiAction` with `delete` and `all`; the web sends `value` "1").

**Request** (JSON body): `businessUuid` and `color` as in [all/archive](#post-v1appassetsallarchive), and `value`, which is required and not read. The filter fields are validated but not applied: every visible asset of the colour is deleted.

**Response** `200`: `data` is a [bulk result](#bulk-result-object) with the number of assets deleted.

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `403` "Access denied"; `403` "Assets not found" when the register has no visible asset of that colour; `404` for an unknown register.

**Side effects:** marks each asset deleted (`fDeleted`) in [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md), one at a time. No audit line, no viewed rows, and no per-asset delete push: one silent update push goes to the register's devices.

## POST /v1/app/assets/all/lock

Locks or unlocks every asset of one colour in a register that the caller can see.

* **Auth:** user token. No permission check on the register, but the caller must be a member of it. Each asset must then pass `operateAsAdminOrCreator`: the caller is an admin of its register or created it. Other assets are skipped without an error.
* **Used by:** web\_app\_v2 (`TaskHttpService.taskMultiAction` with `lock` and `all`; the web always sends `value` "1").

**Request** (JSON body): `businessUuid` and `color` as in [all/archive](#post-v1appassetsallarchive), and `value`: "1" locks, "0" unlocks. The filter fields are validated but not applied: every visible asset of the colour that isn't in that state already is reached.

Archived assets and assets outside their time range are skipped.

**Response** `200`: `data` is a [bulk result](#bulk-result-object) with the number of assets changed.

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `403` "Assets not found" when no asset matches, which is also what a non-member gets; `404` for an unknown register, or a multi-site user of the site who isn't a member.

**Side effects:** for each changed asset, sets `fLocked` in [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md), adds an audit line and writes viewed rows; then a viewed row for the register and one silent update push to the register's devices.

## POST /v1/app/assets/all/priority

Sets the priority of every asset of one colour in a register that the caller can see. `0` removes it.

* **Auth:** user token. No permission check: any member who can see an asset, read-only members included, can change its priority. The task route has the same gap.
* **Used by:** web\_app\_v2 (`TaskHttpService.taskMultiAction` with `priority` and `all`, from the priority dialog).

**Request** (JSON body): `businessUuid` and `color` as in [all/archive](#post-v1appassetsallarchive), and `value`: a priority level, `0`, `1`, `5`, `10`, `20` or `30`; `1` is stored as `20`. The filter fields are validated but not applied.

Setting a level reaches only assets that have no priority, and removing one reaches only assets that have one. Archived and locked assets, and assets outside their time range, are skipped.

**Response** `200`: `data` is a [bulk result](#bulk-result-object).

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `403` "Assets not found" when no asset matches, which is also what a non-member gets; `404` for an unknown register, or a multi-site user of the site who isn't a member; `422` "The selected update priority level is invalid." for another value.

**Side effects:** for each changed asset, sets `fPriority` and `fPriorityLevel` in [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md), adds an audit line and writes viewed rows; then a viewed row for the register and one silent update push to the register's devices.

## POST /v1/app/assets/all/status

Sets the colour (status) of every asset of one colour in a register that the caller can see and that matches the filters.

* **Auth:** user token. A register admin, or a member with the "move to" permission for the new colour, who isn't read-only.
* **Used by:** web\_app\_v2 (`TaskHttpService.taskMultiAction` with `status` and `all`, from the status dialog).

**Request** (JSON body): `businessUuid`, `color` and the filters as in [all/archive](#post-v1appassetsallarchive), and `value`: the new colour, `red`, `amber` or `green`.

Archived and locked assets, assets outside their time range, and, when the register blocks green until the checklist is done, assets with an unfinished checklist are skipped.

**Response** `200`: `data` is a [bulk result](#bulk-result-object).

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `403` "Access denied" without the permission; `403` "Jobs not found" when no asset matches; `404` for an unknown register; `422` "The selected update color is invalid." for another value.

**Side effects:** changes each asset's colour as [PUT /v1/app/assets/{uuid}](#put-v1appassetsuuid) does with `color`, with a status line and viewed rows, one asset at a time; then a viewed row for the register and one silent update push to the register's devices.

## POST /v1/app/assets/copy

Copies an asset within its register or into another register of the same site, once or once per day, week or month.

* **Auth:** user token. Into another register: the caller must be an admin of the asset's register and a member of the target, and both must be on one site. Within the asset's own register nothing is checked, so any signed-in user who knows an asset's UUID can copy it. A task copy within its group at least needs membership; the asset copy is attributed to the asset's creator's membership instead. Task copies have a related gap.
* **Used by:** web\_app\_v2 (`TaskHttpService.copyMoveTask` with `copy` and the asset flag: the asset copy and move dialog, which sends `copyJobChat` 1, and the duplicate action on an asset, which names the asset's own register).

**Request** (JSON body)

| Name                      | In   | Type       | Required        | Rules                                                                                                                                                          |
| ------------------------- | ---- | ---------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `jobUuid`                 | body | string     | yes             | The asset. It must be in an asset register                                                                                                                     |
| `targetBusinessUuid`      | body | string     | yes             | The target register; the asset's own register copies within it                                                                                                 |
| `copyJobChat`             | body | `0` or `1` | no              | Default `1`: copy the chat, its reactions and the status history                                                                                               |
| `createUserBusiness`      | body | `0` or `1` | no              | Default `0`. `1` makes the asset's followers who aren't members of the target register members there, with their role and permissions from the source register |
| `planType`                | body | string     | no              | `single`, `day`, `week` or `month`: one copy, or one per day, week or month between the dates                                                                  |
| `startDate`, `endDate`    | body | integer    | with `planType` | `YYYYMMDD`                                                                                                                                                     |
| `createTags`, `chatTypes` | body |            | no              | Accepted, not used for assets                                                                                                                                  |

What a copy gets:

* The title with " Copy" added, a new reference number, and no time range. A copy within the register also loses its due date.
* The colour of the same name in the target register, and the sub-status of the same name. Without `copyJobChat`, the copy starts green, with the caller as the user who made it green; its approval fields are kept.
* The checklist (unchecked, and without its media, within the register), the checklist template link, the asset links, the attribute values (across registers matched by key to the target's rules), the schedules, time and cost entries, followers who are members of the target, and assignees.

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

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `403` "Access denied" when the caller isn't an admin of the asset's register or a member of the target; `403` with the text `messages.access_denied` when the caller has no membership of the asset's register at all; `400` "Source and Target businesses belongs to different accounts" for a target on another site; `404` for an unknown asset or register, or an asset that isn't in an asset register.

**Side effects:**

* Adds each copy to [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md) and its copied rows to the task tables ([`tPri_JobChat`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobchat.md), [`tPri_JobTodo`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtodo.md), [`tPri_JobAttribute`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobattribute.md), [`tPri_JobJobLink`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobjoblink.md), [`schedule_v3`](https://docs.snapfix.com/engineering-reference/db/tables/schedule_v3.md), [`tPri_JobTimeCost`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtimecost.md), [`tPri_JobUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobuser.md) and the assignees), and with `createUserBusiness` the new memberships to [`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md).
* Audit lines on each copy: "Duplicate Asset - all messages" or "Duplicate Asset - no messages" within the register, or "Asset copied from ''. " across registers. Without `copyJobChat`, also a "created" line that names the type "Task". With `planType`, also the plan's line.
* One silent update push to the target register's devices.

## POST /v1/app/assets/list

Lists the assets of a register, with paging, search, filters and counts per colour.

* **Auth:** user token. The register's membership is not checked as such, but only the assets the caller can see are listed: they need a live membership of the register and to be its admin, have "view all tasks", or have created, follow or be assigned to the asset ([task permissions](https://docs.snapfix.com/engineering-reference/api/tasks.md#task-permissions)). A caller with no membership gets an empty list. Multi-site users of the register's site see every asset.
* **Used by:** web\_app\_v2 (`TaskHttpService.getTaskList` with `assets`, from the asset list and grid; `businessUuid`, `limit`, `offset`, `sortBy` and `orderBy` go in the query string); snapfix\_ai\_agent (`AssetsApi.list_assets`).

**Request** (query string for the register and paging, form or JSON body for the filters)

| Name                                                                       | In            | Type              | Required | Rules                                                                                                                                       |
| -------------------------------------------------------------------------- | ------------- | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `businessUuid`                                                             | query or body | string            | yes      | The register. Missing: `422`                                                                                                                |
| `limit`                                                                    | query         | integer           | no       | Page size. Without it, every match comes back                                                                                               |
| `offset`                                                                   | query         | integer           | no       | Page number from 1; used with `limit`                                                                                                       |
| `sortBy`                                                                   | query         | string            | no       | `created`, `lastActivity`, `title`, `priorityLevel` or `dueDate` (assets without a due date last). Default: the last change (`fModifiedTs`) |
| `orderBy`                                                                  | query         | string            | no       | `asc` or `desc`; default `desc`. Read from the query string only, so `priorityLevel` sorts as sent                                          |
| `searchText`                                                               | body          | string            | no       | Matches the search text (colour, reference, title and description), the exact reference, a text chat message, or an attribute value         |
| `colors`                                                                   | body          | array of strings  | no       | `red`, `amber`, `green`; amber includes the old yellow                                                                                      |
| `normalTasks`, `archivedTasks`                                             | body          | boolean           | no       | Only `archivedTasks`: archived assets only; both: archived and current; neither: current only                                               |
| `unreadTasks`                                                              | body          | boolean           | no       | Only assets with activity since the caller last viewed them                                                                                 |
| `priority`                                                                 | body          | boolean           | no       | The old priority flag `fPriority`                                                                                                           |
| `priorityLevel`                                                            | body          | array of integers | no       | `0`, `1`, `5`, `10`, `20`, `30`; `20` also matches old assets with only `fPriority`                                                         |
| `withCost`                                                                 | body          | boolean           | no       | Only assets with time or cost entries                                                                                                       |
| `createdBy`, `assignedTo`                                                  | body          | array of strings  | no       | User UUIDs                                                                                                                                  |
| `createdStartDate`, `createdEndDate`, `updatedStartDate`, `updatedEndDate` | body          | `Y-m-d`           | no       | Each pair comes together, the end on or after the start; read in the `device-tz-offset` time zone                                           |
| `attributeValue`                                                           | body          | string            | no       | Only assets with an attribute value containing this                                                                                         |

The web also sends `color`, `tags`, `rooms`, `areas`, `assets`, due date and approval filters; this list reads none of them. Assets whose creation or task time is in the future are left out.

**Response** `200`

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "assets": [
      { "uuid": "asset-300", "title": "Boiler 3", "color": "green", "reference": "38760012", "status": { "uuid": "status-3", "name": "green" }, "checklistPercent": 100, "jobCounts": { "red": 1, "amber": 0, "green": 2 } }
    ],
    "totalCount": { "red": 4, "amber": 1, "green": 9 },
    "filterCount": { "red": 1, "amber": 0, "green": 0 },
    "pagination": { "total": 1, "perPage": 25, "currentPage": 1, "lastPage": 1, "from": 1, "to": 1 }
  }
}
```

`assets` are [asset objects](#asset-object) with `status`, `checklistPercent`, `checklistCount`, `users` and `jobCounts`. `totalCount` counts the register's visible assets per colour without the filters, archived assets left out unless `archivedTasks` is sent; `filterCount` counts them with the filters. `pagination` comes only with `limit`.

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `404` for an unknown register; `422` for validation, such as a missing `businessUuid` or a date without its pair.

**Side effects:** a viewed row for the register.

## POST /v1/app/assets/move

Moves an asset within its register or into another register of the same site. A move makes a new asset and deletes the original, so the asset always gets a new UUID and reference number.

* **Auth:** as [copy](#post-v1appassetscopy). Within the asset's own register nothing is checked, and the move deletes the original.
* **Used by:** web\_app\_v2 (`TaskHttpService.copyMoveTask` with `move` and the asset flag, from the asset copy and move dialog).

**Request:** as [copy](#post-v1appassetscopy). `planType` is accepted here too: it makes one moved copy per date and deletes the original.

What differs from a copy: the title stays as it is (no " Copy") and so does the time range; an approval setting of `-1` (inherit) is resolved from the asset's own register's approval setting; and across registers the audit line reads "Asset moved from ''. ". Within the register the audit lines are the same "Duplicate Asset" lines as a copy's, and the checklist is reset and its media are not copied.

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

**Errors:** as [copy](#post-v1appassetscopy).

**Side effects:** as [copy](#post-v1appassetscopy), then the original is marked deleted in [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md).

## POST /v1/app/assets/multi/archive

Archives or unarchives the assets listed by UUID.

* **Auth:** user token. The "archive task" permission (or admin) is checked in the register named by `businessUuid`, and the caller must be a member of it, but the assets in `uuids` aren't limited to that register, so an asset in any register can be changed.
* **Used by:** web\_app\_v2 (`TaskHttpService.taskMultiAction` with `archive` and `multi`, from the asset list's multi-select; the web sends `value` "1").

**Request** (JSON body)

| Name           | In   | Type             | Required | Rules                                     |
| -------------- | ---- | ---------------- | -------- | ----------------------------------------- |
| `businessUuid` | body | string           | yes      | The register the permission is checked in |
| `uuids`        | body | array of strings | yes      | The assets. No maximum                    |
| `value`        | body | string           | yes      | "1" archives, "0" unarchives              |

Assets already in that state, locked assets and assets outside their time range are skipped.

**Response** `200`: `data` is a [bulk result](#bulk-result-object) with the number of assets changed.

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `403` "Access denied" without the permission; `404` for an unknown register; `422` for a missing field.

**Side effects:** as [all/archive](#post-v1appassetsallarchive), for the listed assets; the push goes to the devices of `businessUuid`.

## POST /v1/app/assets/multi/delete

Deletes the assets listed by UUID.

* **Auth:** user token. The "delete task" permission (or admin) is checked in the register named by `businessUuid`, but the UUIDs are loaded with no register filter, so any task or asset in Snapfix can be deleted.
* **Used by:** web\_app\_v2 (`TaskHttpService.taskMultiAction` with `delete` and `multi`).

**Request** (JSON body): `businessUuid` (string, required), `uuids` (array of strings, required, no maximum) and `value` (required, not read; the web sends "1").

**Response** `200`: `data` is a [bulk result](#bulk-result-object) with the number deleted.

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `403` "Access denied" without the permission; `404` for an unknown register; `422` for a missing field.

**Side effects:** marks each listed row deleted (`fDeleted`) in [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md), one at a time. No audit line and no viewed rows; one silent update push to the devices of `businessUuid`.

## POST /v1/app/assets/multi/lock

Locks or unlocks the assets listed by UUID.

* **Auth:** user token. The caller must be a member of `businessUuid`, else `404`. There is no other check on that register. Each listed asset must then pass `operateAsAdminOrCreator` for its own register: the caller is an admin of that register or created the asset. A member who is neither is skipped. An asset of a register the caller isn't a member of stops the whole call with `403` and the text `messages.access_denied`.
* **Used by:** web\_app\_v2 (`TaskHttpService.taskMultiAction` with `lock` and `multi`; the web sends `value` "1").

**Request** (JSON body): `businessUuid` (string, required), `uuids` (array of strings, required) and `value` ("1" locks, "0" unlocks; required).

Assets already in that state, archived assets and assets outside their time range are skipped.

**Response** `200`: `data` is a [bulk result](#bulk-result-object).

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `404` for an unknown register or a caller who isn't a member of it; `403` as above; `422` for a missing field.

**Side effects:** as [all/lock](#post-v1appassetsalllock), for the listed assets; the push goes to the devices of `businessUuid`.

## POST /v1/app/assets/multi/priority

Sets the priority of the assets listed by UUID. `0` removes it.

* **Auth:** user token. The caller must be a member of `businessUuid`, else `404`. No permission is checked, and the UUIDs aren't limited to that register, so a member of any register can change the priority of any asset or task in Snapfix.
* **Used by:** web\_app\_v2 (`TaskHttpService.taskMultiAction` with `priority` and `multi`, from the priority dialog).

**Request** (JSON body): `businessUuid` (string, required), `uuids` (array of strings, required) and `value` (a priority level, `0`, `1`, `5`, `10`, `20` or `30`, required; `1` is stored as `20`).

`0` reaches only assets that have a priority, and `1` only those that have none; the other levels reach every listed asset. Archived and locked assets, and assets outside their time range, are skipped.

**Response** `200`: `data` is a [bulk result](#bulk-result-object).

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `404` for an unknown register or a caller who isn't a member of it; `422` "The selected update priority level is invalid." for another value.

**Side effects:** as [all/priority](#post-v1appassetsallpriority), for the listed assets; the push goes to the devices of `businessUuid`.

## POST /v1/app/assets/multi/status

Sets the colour (status) of the assets listed by UUID.

* **Auth:** user token. The "move to" permission for the new colour (or admin) is checked in `businessUuid`, and the caller must be a member of it, but the UUIDs aren't limited to that register. The task route limits them to the group; this one doesn't.
* **Used by:** web\_app\_v2 (`TaskHttpService.taskMultiAction` with `status` and `multi`, from the status dialog).

**Request** (JSON body): `businessUuid` (string, required), `uuids` (array of strings, required) and `value` (the new colour, `red`, `amber` or `green`, required).

Assets already in that colour aren't counted. The other skips are those of [all/status](#post-v1appassetsallstatus).

**Response** `200`: `data` is a [bulk result](#bulk-result-object).

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `403` "Access denied" without the permission; `404` for an unknown register; `422` "The selected update color is invalid." for another value.

**Side effects:** as [all/status](#post-v1appassetsallstatus), for the listed assets; the push goes to the devices of `businessUuid`.

## POST /v1/app/assets/save-attributes

Saves an asset's attribute values: adds new ones, changes existing ones, and deletes one whose value is emptied.

* **Auth:** user token. No membership or permission check: the asset is loaded by the UUID in the body, and existing values by their own UUIDs, with no check that they belong to that asset. Any signed-in user can change any asset's values, and the asset may even be a task.
* **Used by:** web\_app\_v2 (`AssetHttpService.saveAssetAttributes`, from the asset's attribute dialog, the code dialog's remove action, and the add asset dialog).

**Request** (JSON body)

| Name                                               | In   | Type             | Required                   | Rules                                                                                                                                 |
| -------------------------------------------------- | ---- | ---------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `assetUuid`                                        | body | string           | yes                        | The asset                                                                                                                             |
| `attributes`                                       | body | array            | yes                        | One or more values                                                                                                                    |
| `attributes.*.key`                                 | body | string           | yes                        | The attribute's name                                                                                                                  |
| `attributes.*.value`                               | body | string or number | yes, unless `uuid` is sent | The value. The web sends dates as epoch milliseconds. An empty value on an existing value that names its rule deletes it; so does `0` |
| `attributes.*.uuid`                                | body | string           | no                         | The stored value to change or delete. Without it, a new value is added                                                                |
| `attributes.*.businessJobAttributeRuleUuid`        | body | string           | no                         | The register rule the value fills                                                                                                     |
| `attributes.*.parentJobAttributeRuleUuid`          | body | string           | no                         | The legacy site rule the value fills; it wins over the register rule                                                                  |
| `attributes.*.sortOrder`, `attributes.*.valueType` | body | number, string   | no                         | For a new value; taken from the rule when left out                                                                                    |
| `origin`                                           | body | string           | no                         | Validated, then not used; the stored origin comes from the `fOrigin` header                                                           |

* When the rule marks values as unique (`atValueUnique`), a value already stored for that rule fails with `422` "The attribute must be unqiue" (sic). The check counts every stored value of the rule, also this asset's own and those of deleted assets.
* When the value has a rule, a value starting with `[` or `"` fails with `422` "Asset attribute ('') value should not be array or list".
* The server doesn't check that mandatory attributes have values; the web and the apps check that on the device \[[ASK-98](https://github.com/snapfix/docs/blob/main/ASK.md#ask-98-should-the-server-refuse-an-asset-save-that-leaves-a-mandatory-attribute-empty)].

**Response** `200`: `data` is all the asset's values, as [attribute objects](#attribute-object).

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `404` for an unknown asset, value or rule; `422` for the rules above or a missing field.

**Side effects:** adds, changes or marks deleted rows in [`tPri_JobAttribute`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobattribute.md). No audit line, no viewed rows and no push.

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

Gets one asset with its register, status, users, signature, last viewers, attributes, and time and cost entries, and records the view.

* **Auth:** user token. Multi-site users of the register's site pass without a check \[[ASK-100](https://github.com/snapfix/docs/blob/main/ASK.md#ask-100-should-a-multi-site-member-see-every-asset-register-and-asset-of-the-multi-sites-sites)]. Others need a live membership of the asset's register, else `404`, and the view rule: register admin, "view all tasks", the asset's creator, a follower or an assignee, else `403` ([task permissions](https://docs.snapfix.com/engineering-reference/api/tasks.md#task-permissions)).
* **Used by:** web\_app\_v2 (`TaskHttpService.getTaskDetails` with the asset flag, from the asset detail page and from the planned task editor when it is opened from an asset); snapfix\_ai\_agent (`AssetsApi.get`).

**Request:** `uuid` in the path: the asset. A task's UUID gives `404`, because its group isn't an asset register.

**Response** `200`: `data` is `{ "asset": ... }`, an [asset object](#asset-object) with `business`, `status`, `subStatus`, `users` (with `lastViewed`), `signature`, `time` and `cost`, and `attributes`. There is no `jobchat` key.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "asset": {
      "uuid": "asset-300",
      "title": "Boiler 3",
      "color": "green",
      "isArchived": 0,
      "isLocked": 0,
      "business": { "uuid": "register-200", "name": "Plant room", "image": null },
      "users": { "lastViewed": [], "following": [] },
      "attributes": [{ "uuid": "value-600", "key": "Model", "value": "DX-9", "valueType": "text" }],
      "time": [],
      "cost": []
    }
  }
}
```

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `403` "Access denied" without the view rule; `404` for an unknown asset, an asset outside an asset register, or a caller with no membership of its register.

**Side effects:** viewed rows for the asset and its register.

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

Changes one field of an asset, chosen by `action`.

* **Auth:** user token. The caller must have a live membership of the asset's register, else `404`. Then each action has its rule (table below). The asset must also be editable for the action: not locked (except to `lock`), not archived (except to `lock` or `archive`), and with no time range or inside it now, else `400` "The asset can not be updated".
* **Used by:** web\_app\_v2 (`TaskHttpService.updateTask` with `assets`, from the asset's title, note, photo, colour, priority, reminder, lock, archive, snooze and approval controls). It sends JSON as `PUT`, or form data as `POST` with `_method=PUT` when a file is sent; the `assetUuid` it adds to the query string isn't read.

**Request**

| Name            | In   | Type       | Required                                 | Rules                                                                        |
| --------------- | ---- | ---------- | ---------------------------------------- | ---------------------------------------------------------------------------- |
| `uuid`          | path | string     | yes                                      | The asset                                                                    |
| `action`        | body | string     | yes                                      | One of the actions below. Anything else: `422`                               |
| `value`         | body |            | per action                               | See below                                                                    |
| `autoColor`     | body | `0` or `1` | with `color`                             | `1` when the app changes the colour itself (a checklist started or finished) |
| `file`          | body | file       | with `image`; optional with `largeTitle` | Up to 51200 KB. The type isn't checked                                       |
| `snoozedNotes`  | body | string     | no                                       | With `snooze`; nullable                                                      |
| `rejectionNote` | body | string     | when rejecting                           | Required, at least one character, when `approvalStatus` is set to `0`        |

| `action`           | `value`                           | Who may                                                                                                                                                                               | What changes                                                                                       |
| ------------------ | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `title`            | text, at most 255 characters      | can change the asset                                                                                                                                                                  | `fTitle`; clears the AI-suggested flag                                                             |
| `description`      | text or empty                     | can change the asset                                                                                                                                                                  | `fDescription`                                                                                     |
| `largeTitle`       | text                              | can change the asset                                                                                                                                                                  | `fLargeTextTitle`; the photo becomes `file`, or none without one                                   |
| `image`            | none                              | can change the asset                                                                                                                                                                  | The photo becomes `file`; clears the large text                                                    |
| `color`            | `red`, `amber` or `green`         | register admin or the "move to" permission for that colour, and not read-only; the permission is skipped for `autoColor` 1 when the register's automatic amber or green setting is on | The colour, status, sub-status, timestamps and status log                                          |
| `priority`         | `0`, `1`, `5`, `10`, `20` or `30` | can change the asset                                                                                                                                                                  | `fPriority` and `fPriorityLevel`                                                                   |
| `reminder`         | boolean                           | can change the asset                                                                                                                                                                  | `fEnableTaskReminder`                                                                              |
| `lock`             | boolean                           | can change the asset, and register admin or the asset's creator                                                                                                                       | `fLocked`                                                                                          |
| `archive`          | boolean                           | can change the asset, and admin or the "archive task" permission                                                                                                                      | `fArchived`                                                                                        |
| `snooze`           | `DND`, `DNS`, `Delay` or `Other`  | can change the asset                                                                                                                                                                  | `fSnoozed`, the reason and `snoozedNotes`                                                          |
| `approvalRequired` | `0` or `1`                        | can change the asset                                                                                                                                                                  | `fApprovalRequired`; turning it off approves a green asset waiting for approval                    |
| `approvalStatus`   | `-1`, `0`, `1` or `2`             | can change the asset                                                                                                                                                                  | `fApprovalStatus` and `fApprovedTs`; `0` (rejected) with `rejectionNote` adds the note to the chat |

"Can change the asset" is the update rule of the [task permissions](https://docs.snapfix.com/engineering-reference/api/tasks.md#task-permissions): the caller can see the asset and isn't read-only.

**Response** `200`: `data` is `{ "asset": ..., "jobchat": ... }`: the changed [asset object](#asset-object) with `business`, `status` and `subStatus`, and the audit line for the change as a [chat item](https://docs.snapfix.com/engineering-reference/api/tasks.md#chat-item-object).

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "asset": { "uuid": "asset-300", "title": "Boiler 3", "status": { "uuid": "status-1", "name": "red" } },
    "jobchat": { "uuid": "chat-501", "text": "status-1,,<b>Jane Smith</b> changed Status to Red", "type": 19 }
  }
}
```

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `403` "Access denied" without the action's permission; `400` "The asset can not be updated" when the asset isn't editable; `404` for an unknown asset, an asset outside an asset register, or a caller with no membership of its register; `422` for a bad `action` or `value`.

**Side effects:**

* Updates [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md) as in the table, and adds the audit line to [`tPri_JobChat`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobchat.md).
* `color` adds rows to [`tPri_Job_StatusLog`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job_statuslog.md), and green deletes the asset's due date reminders in [`schedule_v3`](https://docs.snapfix.com/engineering-reference/db/tables/schedule_v3.md).
* `image` and `largeTitle` store the new file and delete the old photo.
* Viewed rows for the asset and its register; a push to the asset's assignees and followers, and a silent update ([common side effects](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-side-effects)).

## DELETE /v1/app/assets/{uuid}

Deletes an asset. The row is marked deleted, not removed.

* **Auth:** user token. A register admin, or a member with the "delete task" permission who isn't read-only. A caller with no membership of the register gets `403` with the text `messages.access_denied`.
* **Used by:** web\_app\_v2 (`TaskHttpService.deleteTask` with `assets`, from the asset's menu).

**Request:** `uuid` in the path. No body.

**Response** `200`, with the message "Asset deleted successfully" and `data` `null`.

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `403` "Access denied" without the permission; `404` for an unknown asset.

**Side effects:** marks the asset deleted (`fDeleted`) in [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md); its values and links stay. Writes a viewed row for the register and sends a silent "deleted" push to the register's devices.

## GET /v1/app/assets/{uuid}/jobs

Lists the tasks linked to an asset, with counts per colour and totals of time and cost.

* **Auth:** user token. The caller needs a live membership of the asset's register, else `404`, and the view rule for the asset without its creator clause: register admin, "view all tasks", a follower or an assignee, else `403`. Only linked tasks the caller can see in each task's own group are listed: admin or "view all tasks" there, the task's creator, an assignee or a follower. A member of any multi-site sees every linked task.
* **Used by:** web\_app\_v2 (`AssetHttpService.getAssetTaskList`, from the Tasks tab of the asset detail page, 20 at a time).

**Request** (query string)

| Name         | In    | Type    | Required | Rules                                                                                                                                |
| ------------ | ----- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `uuid`       | path  | string  | yes      | The asset                                                                                                                            |
| `limit`      | query | integer | no       | Page size. Without it, every linked task comes back                                                                                  |
| `offset`     | query | integer | no       | Page number from 1; used with `limit`                                                                                                |
| `searchText` | query | string  | no       | Matches the task's search text (colour, reference, title and description) or its exact reference. The value is put into the SQL text |

**Response** `200`

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "jobs": [{ "uuid": "task-700", "title": "Fix boiler", "status": { "uuid": "status-9", "name": "red" } }],
    "totalCount": { "red": 1, "amber": 0, "green": 2 },
    "filterCount": { "red": 1, "amber": 0, "green": 2 },
    "totalCost": { "EUR": 45.5 },
    "totalTime": 3600000,
    "pagination": { "total": 3, "perPage": 20, "currentPage": 1, "lastPage": 1, "from": 1, "to": 3 }
  }
}
```

* `jobs` are [task objects](https://docs.snapfix.com/engineering-reference/api/tasks.md#task-object) with `status`, `users`, `tags`, `business` and `rooms`.
* `totalCount` and `filterCount` count tasks per colour, amber including the old yellow. `totalCost` sums the time and cost entries per currency, and `totalTime` the time entries, in ms. All four are worked out from the tasks of the returned page, after the search, so `totalCount` always equals `filterCount` and the totals leave out the other pages.
* `pagination` comes only with `limit`.

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `403` "Access denied" without the view rule; `404` for an unknown asset, or a caller with no membership of its register.

**Side effects:** none.

## POST ?action=parent\_asset\_details

Gets legacy asset registers with their assets and attribute values. iOS has client code for it in the legacy asset picker, which nothing opens.

* **Auth:** php-apis user token, as in the header. The action reads no user and checks no membership, so any legacy register and its assets can be read by UUID.
* **Used by:** no reachable client. iOS `SelectAssetVC.getAssets` sends it, but its load call is commented out and only the picker's "no internet" retry calls it; the picker itself cannot be opened, because the bottom menu that holds its button never shows (ios @ aa31967ac8, `SnapFix/AssetManagement/SelectAssetVC.swift:54`, `:139`, `:182-185`; `SnapFix/MessagesVC/MessagesVC.swift:6568-6569`).

**Request** (JSON body)

| Name             | In   | Type                       | Required | Rules                                                                                                                                         |
| ---------------- | ---- | -------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid_assetReg`  | body | string or array of strings | yes      | Legacy register UUIDs ([`assetReg`](https://docs.snapfix.com/engineering-reference/db/tables/assetreg.md)). Missing: "invalid uuid\_assetReg" |
| `uuid_assetMain` | body | string or array of strings | no       | Only these legacy assets. With it, each register also carries its rules                                                                       |
| `uuid_tUser`     | body | string                     | no       | Sent by iOS; not read                                                                                                                         |

The assets come from the legacy [`assetMain`](https://docs.snapfix.com/engineering-reference/db/tables/assetmain.md) table. Assets made through the current API are task rows, so they never appear here.

**Response** `200` with `result` true: `data` is a list of [legacy register details objects](#legacy-register-details-object-php-apis), only for registers that have matching assets.

```json
{
  "result": true,
  "message": "success",
  "data": [
    {
      "uuid": "legacy-register-1",
      "name": "Plant room",
      "address": "Level 2",
      "image": "",
      "sortorder": 1000,
      "createdts": 1794387600000,
      "assets": [
        {
          "uuid": "legacy-asset-1",
          "name": "Boiler 3",
          "sortorder": 1000,
          "createdts": 1794387600000,
          "attributes": [{ "uuid": "legacy-value-1", "name": "Model", "category": null, "key": "Model", "value": "DX-9", "sortorder": 5000, "createdts": 1794387600000, "type": "text" }]
        }
      ]
    }
  ],
  "serverTs": 1794387605000
}
```

**Errors:** `200` with `result` false: "invalid uuid\_assetReg"; "no assets found" when the registers have no (matching) assets.

**Side effects:** none.

## POST ?action=parent\_asset\_rules

Gets the user's sites with their legacy site-level attribute rules \[[ASK-101](https://github.com/snapfix/docs/blob/main/ASK.md#ask-101-are-site-level-attribute-rules-still-meant-to-apply-to-asset-registers)] and every legacy asset register of each site. iOS has client code for it in the first step of the legacy asset picker, which nothing opens.

The registers come from the old [`assetReg`](https://docs.snapfix.com/engineering-reference/db/tables/assetreg.md) table, not the registers that [GET /v1/app/asset-regs](#get-v1appasset-regs) returns (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:24619-24621`). In the staging copy that table was last written on 2022-11-10, and its memberships table [`assetUserReg`](https://docs.snapfix.com/engineering-reference/db/tables/assetuserreg.md) is empty.

* **Auth:** php-apis user token, as in the header. The sites come from `uuid_tUser` in the body, which isn't compared with the token. Every legacy register of those sites comes back, with no membership filter.
* **Used by:** no reachable client. iOS `SelectAssetRegisterVC.getAssetRegisters` sends it, but the picker opens only from "Add Asset to Task" in the task screen's old bottom menu, which never shows (ios @ aa31967ac8, `SnapFix/MessagesVC/MessagesVC.swift:6568-6569`, `SnapFix/Storyboards/MessageSB2.storyboard:1514`). "Add Assets" in the task's "+" menu opens the current picker, so the legacy tables never limit what a task can link ([Select asset register](https://docs.snapfix.com/how-the-apps-work/screens/assets/select-asset.md#old-ios-picker)).

**Request** (JSON body)

| Name         | In   | Type   | Required | Rules                                                                      |
| ------------ | ---- | ------ | -------- | -------------------------------------------------------------------------- |
| `uuid_tUser` | body | string | yes      | The user. Missing, blank, or not a user that isn't deleted: "invalid user" |

**Response** `200` with `result` true: `data` is a list of [parent rules objects](#parent-rules-object-php-apis), one per site where the user has a membership in a group that isn't deleted. Each site's rules come back twice.

```json
{
  "result": true,
  "message": "success",
  "data": [
    {
      "parent_uuid": "site-100",
      "parent_name": "Example Site",
      "rules": [{ "uuid": "legacy-rule-1", "atCategory": null, "atKey": "Asset ID", "atKeyUnique": 0, "atValueUnique": 0, "atMandatory": 0, "sort_order": 1000, "fDeleted": 0, "fCreatedTs": 1794387600000, "fModifiedTs": 1794387600000 }],
      "assetreg": [{ "uuid": "legacy-register-1", "uuid_tParent": "site-100", "fName": "Plant room", "fAddress": "Level 2", "fImage": "", "sort_order": 1000, "fDeleted": 0, "fCreatedTs": 1794387600000, "fModifiedTs": 1794387600000, "rules": [] }]
    }
  ],
  "serverTs": 1794387605000
}
```

**Errors:** `200` with `result` false: "invalid user"; "invalid parents" when the user has no such membership.

**Side effects:** none.

## POST ?action=save\_pri\_businessjobattributerule

Saves a batch of attribute rule rows: the apps' sync sends the rules changed on the device. Android creates a new register's default rules on the device and sends them this way (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/activity/CreateAssetGroupActivity.kt:327-338`); registers made through [POST /v1/app/asset-regs](#post-v1appasset-regs) get theirs on the server.

* **Auth:** php-apis user token, as in the header. Any signed-in user can write any rule row, for any register, and the rows reach the SQL as sent.
* **Used by:** iOS (`TaskManager.getPendingBusinessRule`, the sync; ios @ aa31967ac8, `Managers/TaskManager.swift:990`); Android (`SyncRepository`, the sync of the rule table; `app/src/main/java/gmail/com/snapfixapp/data/repository/SyncRepository.kt:589`).

**Request** (JSON body)

| Name          | In   | Type                                                                                                                                       | Required | Rules                                                                                                                                                                                                                                                                                                                      |
| ------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `insert_data` | body | array of [`tPri_BusinessJobAttributeRule`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_businessjobattributerule.md) rows | yes      | `uuid`, `uuid_tBusiness`, `atCategory`, `atKey`, `atKeyUnique`, `atValueUnique`, `atMandatory`, `valType`, `sort_order`, `fOrigin`, `fInActive`, `fDeleted`, timestamps and author UUIDs. A row without `uuid` gets a new one. The code checks no foreign key; the database only refuses an unknown `uuid_tUser_CreatedBy` |

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

**Errors:** `200` with `result` false and "Data cannot be blank!" for an empty body; the other errors of the [save result object](https://docs.snapfix.com/engineering-reference/api/tasks.md#save-result-object-php-apis).

**Side effects:** with the legacy queue on, one row per rule goes into [`tPri_Queue`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_queue.md), and apipy is asked to send an "API update required" push to the members of the rows' registers \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. Otherwise the rules are inserted or updated in [`tPri_BusinessJobAttributeRule`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_businessjobattributerule.md) at once.

## POST ?action=save\_pri\_jobattribute

Saves a batch of attribute value rows of assets (and tasks): the apps' sync sends the values changed on the device.

* **Auth:** as [save\_pri\_businessjobattributerule](#post-actionsave_pri_businessjobattributerule).
* **Used by:** iOS (`TaskManager.getAttribute`, the sync; `Managers/TaskManager.swift:2430`); Android (`SyncRepository`, the sync of the value table; `SyncRepository.kt:557`).

**Request** (JSON body)

| Name          | In   | Type                                                                                                               | Required | Rules                                                                                                                                                                                                                                                                                                                                                     |
| ------------- | ---- | ------------------------------------------------------------------------------------------------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `insert_data` | body | array of [`tPri_JobAttribute`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobattribute.md) rows | yes      | `uuid`, `uuid_tJob`, `fName`, `atCategory`, `atKey`, `atValue`, `sort_order`, `valType`, `uuid_tBusinessJobAttributeRule`, `uuid_tParentJobAttributeRule`, `fOrigin`, `fInActive`, `fDeleted`, timestamps and author UUIDs. A row without `uuid` gets a new one; a new row without `uuid_tBusiness` takes it from its task. The table has no foreign keys |

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

**Errors:** as [save\_pri\_businessjobattributerule](#post-actionsave_pri_businessjobattributerule).

**Side effects:** as [save\_pri\_businessjobattributerule](#post-actionsave_pri_businessjobattributerule), for [`tPri_JobAttribute`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobattribute.md).

## Asset register object

An asset register (`AssetBusinessResource`), as an item of `data.assetregs` or as `data`.

| Field                     | Type            | Meaning                                                                                                                                                                                                                                       |
| ------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`                    | string          | The register                                                                                                                                                                                                                                  |
| `name`                    | string          | The register's name, unique on its site                                                                                                                                                                                                       |
| `image`                   | string or null  | Photo URL                                                                                                                                                                                                                                     |
| `address`                 | string          | The description                                                                                                                                                                                                                               |
| `inActive`                | integer         | `1` when the register is archived                                                                                                                                                                                                             |
| `purpose`, `instructions` | string or null  | The guide texts; null in the list                                                                                                                                                                                                             |
| `notificationDisabled`    | integer or null | `1` when the caller muted the register                                                                                                                                                                                                        |
| `parent`                  | object          | When included: the site's `uuid`, `name` and `image`                                                                                                                                                                                          |
| `statuses`                | object          | When included: `red`, `amber` and `green`, each with `uuid`, `name`, `count` (the caller's visible assets of that colour that aren't archived; amber includes the old yellow) and `definition` (the register's label for the colour)          |
| `settings`                | object          | When included: the caller's `relationUuid`, `role`, `onboard` and `permissions` in the register, and the register's `jobToDoNfcAllowManualOverride` and `blockGalleryPhoto`. The other settings that groups return are left out for registers |
| `users`                   | array           | When included: [register member objects](#register-member-object)                                                                                                                                                                             |
| `invited`                 | array           | When included: pending invitations                                                                                                                                                                                                            |
| `attributeRules`          | array           | When included: [attribute rule objects](#attribute-rule-object)                                                                                                                                                                               |

Registers never return the `tagHeaders` that groups can.

## Asset object

An asset, as `data.asset` or an item of `data.assets`. Assets use the task resource (`AssetJobResource`), so the fields are those of the [task object](https://docs.snapfix.com/engineering-reference/api/tasks.md#task-object), with the includes each endpoint names. `business` is the register's `uuid`, `name` and `image`. `attributes` is always there: the asset's values, as [attribute objects](#attribute-object), except values whose register rule is deleted. `jobCounts` (the list only) counts the asset's linked tasks per colour.

## Attribute rule object

One attribute of a register (`AttributeRuleResource`).

| Field       | Type           | Meaning                                                                                 |
| ----------- | -------------- | --------------------------------------------------------------------------------------- |
| `uuid`      | string         | The rule                                                                                |
| `category`  | string or null | The section the rule sits in, such as "Tracking"; null shows as "Attributes" on the web |
| `key`       | string         | The attribute's name                                                                    |
| `mandatory` | integer        | `1` when assets must have a value                                                       |
| `valueType` | string         | `text`, `number`, `date`, `barcode`, `qr` or `nfc`                                      |
| `sortOrder` | number         | Position in the list                                                                    |

The stored unique flags (`atKeyUnique`, `atValueUnique`) are not returned.

## Attribute object

One value on an asset (`AttributeResource`).

| Field                          | Type           | Meaning                                   |
| ------------------------------ | -------------- | ----------------------------------------- |
| `uuid`                         | string         | The value's row                           |
| `category`                     | string or null | The rule's category, else the value's own |
| `key`                          | string         | The attribute's name                      |
| `value`                        | string or null | The value; dates are epoch ms             |
| `deleted`                      | integer        | `1` when the value is deleted             |
| `name`                         | string         | The name stored with the value            |
| `sortOrder`                    | number         | Position                                  |
| `businessJobAttributeRuleUuid` | string or null | The register rule the value fills         |
| `parentJobAttributeRuleUuid`   | string or null | The legacy site rule the value fills      |
| `valueType`                    | string         | The rule's type, else the value's own     |

## Register member object

A member of an asset register (`UserAssetBusinessResource`). It carries each member's phone number and home address to every member who can list them.

| Field                                | Type    | Meaning                                                            |
| ------------------------------------ | ------- | ------------------------------------------------------------------ |
| `uuid`                               | string  | The user                                                           |
| `isSystem`                           | boolean | Whether the user is a system account                               |
| `relationUuid`                       | string  | The membership row                                                 |
| `name`, `firstname`, `lastname`      | string  | The user's name and its parts                                      |
| `address`                            | string  | The user's postal address                                          |
| `mobile`, `countryCode`              | string  | The user's phone number and its country code                       |
| `username`, `staffUsername`, `image` | string  | Sign-in name, staff user name and photo                            |
| `role`                               | string  | The member's role in the register, such as `Admin`                 |
| `user_type`                          | string  | The user's type on the site; `normal` when there is none           |
| `onboard`                            | string  | The membership's onboarding state; an inactive member is read-only |
| `active`, `relationDeleted`          | integer | The membership's active and deleted flags                          |
| `notificationDisabled`               | integer | `1` when the member muted the register                             |
| `tempUser`                           | integer | `1` for a user with a temporary password who has never signed in   |
| `permissions`                        | object  | The membership's permissions                                       |

On the staff admin platform the object also has `createdTs`, `createdBy`, `modifiedTs` and `modifiedBy`.

## Bulk result object

`data` of the `all/*` and `multi/*` routes (`GeneralResource`): `total`, the number of assets the call changed or deleted.

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

## Parent rules object (php-apis)

One site of the user, as `parent_asset_rules` returns it. Field names are the table columns.

| Field         | Type   | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parent_uuid` | string | The site                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `parent_name` | string | The site's name                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `rules`       | array  | The site's legacy rules, from [`assetParentCatKey`](https://docs.snapfix.com/engineering-reference/db/tables/assetparentcatkey.md): `uuid`, `atCategory`, `atKey`, `atKeyUnique`, `atValueUnique`, `atMandatory`, `sort_order`, `fDeleted`, `fCreatedTs`, `fModifiedTs`. Each rule is listed twice                                                                                                                                                                                                                  |
| `assetreg`    | array  | Every legacy register of the site, from [`assetReg`](https://docs.snapfix.com/engineering-reference/db/tables/assetreg.md): `uuid`, `uuid_tParent`, `fName`, `fAddress`, `fImage`, `sort_order`, `fDeleted`, `fCreatedTs`, `fModifiedTs`, each with its `rules` from [`assetRegCatKey`](https://docs.snapfix.com/engineering-reference/db/tables/assetregcatkey.md). The user's links to legacy registers ([`assetUserReg`](https://docs.snapfix.com/engineering-reference/db/tables/assetuserreg.md)) are not read |

## Legacy register details object (php-apis)

A legacy register with its assets, as `parent_asset_details` returns it.

| Field                              | Type    | Meaning                                                                                                                                                                                                                                                                                                       |
| ---------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`, `name`, `address`, `image` | string  | The register, from [`assetReg`](https://docs.snapfix.com/engineering-reference/db/tables/assetreg.md)                                                                                                                                                                                                         |
| `sortorder`, `createdts`           | integer | Sort position, and creation time in epoch ms                                                                                                                                                                                                                                                                  |
| `parent_rules`                     | array   | Only with `uuid_assetMain`: the site's rules, from [`assetParentCatKey`](https://docs.snapfix.com/engineering-reference/db/tables/assetparentcatkey.md)                                                                                                                                                       |
| `asset_reg_rules`                  | array   | Only with `uuid_assetMain`: the register's rules, from [`assetRegCatKey`](https://docs.snapfix.com/engineering-reference/db/tables/assetregcatkey.md)                                                                                                                                                         |
| `assets`                           | array   | The register's assets, from [`assetMain`](https://docs.snapfix.com/engineering-reference/db/tables/assetmain.md): `uuid`, `name`, `sortorder`, `createdts` and `attributes`                                                                                                                                   |
| `assets[].attributes`              | array   | The asset's values, from [`assetAttribute`](https://docs.snapfix.com/engineering-reference/db/tables/assetattribute.md): `uuid`, `name`, `category`, `key`, `value`, `sortorder`, `createdts`, `type`. When a key's rule isn't key-unique, the key appears once and `value` is a list of every value under it |


---

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