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

# Open 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/open-api.md).
{% endhint %}

The APIs that customers' and vendors' own systems call: the public API under `/v1/public`, the vendor API under `/v1/xvendor`, and apipy's older task API under `/v1/task`. The undocumented `/v1/sdk` routes are listed too; nothing is known to call them.

* **Services:** `api_php_live_v2` at `https://z4.snapfix.com` for `/v1/public`, `/v1/xvendor` and `/v1/sdk`. The customer docs give `https://api.snapfix.com/v1/public/` as the base address, a separate server \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)] (`api_php_live_v2 @ ef3c4319f6, app/Http/Controllers/v1/Openapi/Public/OAController.php:73`). The same page writes the task path as `/task`, while the route is `/tasks` (`OAController.php:40`, `:75`). `apipy` at `https://z2.snapfix.com` for `/v1/task`. Staging and test hosts are in [services and hosts](https://docs.snapfix.com/engineering-reference/api.md#services-and-hosts).
* **Auth:** `/v1/public` and `/v1/xvendor` take an API key in `X-API-Key` ([Keys](#keys)). `/v1/sdk` decodes no token and acts as the user named in a `jwt_identity` request field. apipy takes a different key in `x-api-key`, checked against `tPri_Parent_Api` but not against the group or task's site.
* **Used by:** customers' and vendors' own systems, outside the Snapfix repos; no repo calls these routes. 25 of the 45 endpoints have external callers:
  * The 8 public and 15 vendor routes are the published APIs: each has a Swagger entry in `api_php_live_v2 @ ef3c4319f6, app/Http/Controllers/v1/Openapi/Public/` and `app/Http/Controllers/v1/Openapi/XVendor/`, and its own key middleware in `app/Providers/RouteServiceProvider.php:61-81`. The staging database holds 72 API keys, 45 of them vendor keys and 2 deleted (`tPri_Api_Simple_SecretKey`, counted 2026-11-16). Among the 20,000 newest staging tasks, 84 carry the vendor origin and 11 the public API origin (`EnumOrigin` 11 and 7, `app/Enums/EnumOrigin.php:14`, `:18`).
  * The 2 apipy `/v1/task` routes are built for external integrations: the handler is `jobOpsForExternalIntegrations`, and it links an outside specification document (`apipy @ 0e83c85e5a, app.py:3758`, `:3761`). They are not in the Swagger docs. Staging holds 2 task keys, both past their end time, so on staging every call is refused. Whether customers still call them is \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)].
  * The 20 `/v1/sdk` routes have no known caller and are marked "(no caller)".
* **Rules:** what a key may do, its limits and how customers get one are in [Open API](https://docs.snapfix.com/product/features/integrations/open-api.md) and [Vendor API](https://docs.snapfix.com/product/features/integrations/vendor-api.md).
* **Logs:** the Laravel request log stores whole requests and responses. apipy writes every request with all its headers, the key included, to a daily log table.

| Method | Path                                                             | Service            | Purpose                                      |
| ------ | ---------------------------------------------------------------- | ------------------ | -------------------------------------------- |
| GET    | [`/v1/public/groups`](#get-v1publicgroups)                       | api\_php\_live\_v2 | List the groups of the key's site            |
| GET    | [`/v1/public/groups/{uuid}`](#get-v1publicgroupsuuid)            | api\_php\_live\_v2 | Get a group                                  |
| GET    | [`/v1/public/tasks`](#get-v1publictasks)                         | api\_php\_live\_v2 | List a group's tasks                         |
| POST   | [`/v1/public/tasks`](#post-v1publictasks)                        | api\_php\_live\_v2 | Create a task                                |
| GET    | [`/v1/public/tasks/{uuid}`](#get-v1publictasksuuid)              | api\_php\_live\_v2 | Get a task                                   |
| PUT    | [`/v1/public/tasks/{uuid}`](#put-v1publictasksuuid)              | api\_php\_live\_v2 | Change a task                                |
| DELETE | [`/v1/public/tasks/{uuid}`](#delete-v1publictasksuuid)           | api\_php\_live\_v2 | Delete a task                                |
| POST   | [`/v1/public/upload`](#post-v1publicupload)                      | api\_php\_live\_v2 | Upload a file for a task                     |
| GET    | `/v1/sdk/business`                                               | api\_php\_live\_v2 | List groups (no caller)                      |
| POST   | `/v1/sdk/business`                                               | api\_php\_live\_v2 | Create a group (no caller)                   |
| POST   | `/v1/sdk/business/copy`                                          | api\_php\_live\_v2 | Copy a group (no caller)                     |
| POST   | `/v1/sdk/business/get-updates`                                   | api\_php\_live\_v2 | Get group updates (no caller)                |
| GET    | `/v1/sdk/business/mark-as-visited/{businessUuid}`                | api\_php\_live\_v2 | Mark a group as visited (no caller)          |
| POST   | `/v1/sdk/business/multi`                                         | api\_php\_live\_v2 | Get groups by UUID (no caller)               |
| GET    | `/v1/sdk/business/{businessUuid}/job-count`                      | api\_php\_live\_v2 | Count a group's tasks (no caller)            |
| GET    | `/v1/sdk/business/{businessUuid}/job-count-to-archived`          | api\_php\_live\_v2 | Count a group's tasks to archive (no caller) |
| GET    | `/v1/sdk/business/{businessUuid}/qr`                             | api\_php\_live\_v2 | List a group's QR forms (no caller)          |
| POST   | `/v1/sdk/business/{businessUuid}/qr`                             | api\_php\_live\_v2 | Create a QR form for a group (no caller)     |
| PUT    | `/v1/sdk/business/{businessUuid}/tag-header/{tagHeaderUuid}`     | api\_php\_live\_v2 | Change a group's tag folder (no caller)      |
| POST   | `/v1/sdk/business/{businessUuid}/tags`                           | api\_php\_live\_v2 | Create a tag in a group (no caller)          |
| POST   | `/v1/sdk/business/{businessUuid}/tags/multiple`                  | api\_php\_live\_v2 | Create several tags in a group (no caller)   |
| PUT    | `/v1/sdk/business/{businessUuid}/tags/{tagUuid}`                 | api\_php\_live\_v2 | Change a group's tag (no caller)             |
| DELETE | `/v1/sdk/business/{businessUuid}/tags/{tagUuid}`                 | api\_php\_live\_v2 | Delete a group's tag (no caller)             |
| GET    | `/v1/sdk/business/{uuid}`                                        | api\_php\_live\_v2 | Get a group (no caller)                      |
| PUT    | `/v1/sdk/business/{uuid}`                                        | api\_php\_live\_v2 | Change a group (no caller)                   |
| DELETE | `/v1/sdk/business/{uuid}`                                        | api\_php\_live\_v2 | Delete a group (no caller)                   |
| GET    | `/v1/sdk/business/{uuid}/tags`                                   | api\_php\_live\_v2 | List a group's tags (no caller)              |
| GET    | `/v1/sdk/business/{uuid}/users`                                  | api\_php\_live\_v2 | List a group's users (no caller)             |
| GET    | [`/v1/xvendor/areas`](#get-v1xvendorareas)                       | api\_php\_live\_v2 | List the areas of the site's building        |
| GET    | [`/v1/xvendor/asset-regs`](#get-v1xvendorasset-regs)             | api\_php\_live\_v2 | List asset registers                         |
| GET    | [`/v1/xvendor/asset-regs/{uuid}`](#get-v1xvendorasset-regsuuid)  | api\_php\_live\_v2 | Get an asset register                        |
| GET    | [`/v1/xvendor/assets`](#get-v1xvendorassets)                     | api\_php\_live\_v2 | List a register's assets                     |
| GET    | [`/v1/xvendor/assets/{uuid}`](#get-v1xvendorassetsuuid)          | api\_php\_live\_v2 | Get an asset                                 |
| GET    | [`/v1/xvendor/groups`](#get-v1xvendorgroups)                     | api\_php\_live\_v2 | List the groups of the key's site            |
| GET    | [`/v1/xvendor/groups/{uuid}`](#get-v1xvendorgroupsuuid)          | api\_php\_live\_v2 | Get a group                                  |
| GET    | [`/v1/xvendor/groups/{uuid}/tags`](#get-v1xvendorgroupsuuidtags) | api\_php\_live\_v2 | List a group's tag folders and tags          |
| GET    | [`/v1/xvendor/rooms`](#get-v1xvendorrooms)                       | api\_php\_live\_v2 | List the rooms of the site's building        |
| GET    | [`/v1/xvendor/tasks`](#get-v1xvendortasks)                       | api\_php\_live\_v2 | List a group's tasks                         |
| POST   | [`/v1/xvendor/tasks`](#post-v1xvendortasks)                      | api\_php\_live\_v2 | Create a task                                |
| GET    | [`/v1/xvendor/tasks/{uuid}`](#get-v1xvendortasksuuid)            | api\_php\_live\_v2 | Get a task                                   |
| PUT    | [`/v1/xvendor/tasks/{uuid}`](#put-v1xvendortasksuuid)            | api\_php\_live\_v2 | Change a task                                |
| DELETE | [`/v1/xvendor/tasks/{uuid}`](#delete-v1xvendortasksuuid)         | api\_php\_live\_v2 | Delete a task                                |
| POST   | [`/v1/xvendor/upload`](#post-v1xvendorupload)                    | api\_php\_live\_v2 | Upload a file for a task                     |
| GET    | [`/v1/task`](#get-v1task)                                        | apipy              | Read one task by ID, from any site           |
| POST   | [`/v1/task`](#post-v1task)                                       | apipy              | Create a task in any group                   |

The 20 `/v1/sdk` routes are the group routes of `routes/business.php`, mounted a second time (`api_php_live_v2 @ ef3c4319f6, routes/sdk.php:11`). They run `authorize`, `blacklist`, `rate.limiter` and two `throttle` limits of 60 calls a minute and 1,000 a day (`app/Providers/RouteServiceProvider.php:95-105`, `:138-150`). A call over a limit answers `500`, not `429`.

## Keys

How keys are issued, and what a key may do, are in [Open API](https://docs.snapfix.com/product/features/integrations/open-api.md#keys) and [Vendor API](https://docs.snapfix.com/product/features/integrations/vendor-api.md#keys). This section holds what a caller of the routes needs.

* **Format:** `sk`, the mode (`test` or `live`), `_`, the app name in lower case, `_`, a random part, `_`, a CRC32 checksum in hex. For example `sktest_<app name>_<random>_<checksum>`. A key with fewer than four parts, or a wrong checksum, is refused before the database is read. Otherwise the key's SHA-256 hash is looked up in `tPri_Api_Simple_SecretKey` (`api_php_live_v2 @ ef3c4319f6, app/Services/ApiKeyAuthService.php:50-85`). The mode changes no behaviour.
* **Creation:** staff only, with `POST /v1/admin/public-simple-api` ([staff](https://docs.snapfix.com/engineering-reference/api/staff.md)), which takes `parentUuid`, `userLabel`, `mode` and `XVendor` (`0` or `1`). The key is returned once, in `secretKey`; only its hash is stored. Each key gets its own API user, which makes the key's calls (`app/Http/Controllers/v1/Versions/v1_0/Admin/PublicSimpleAPIController.php:25-75`) \[[ASK-159](https://github.com/snapfix/docs/blob/main/ASK.md#ask-159-how-do-customers-and-vendors-get-api-keys)].
* **Site:** a key acts for one site. Every group of that site is in reach, with no per-group limit \[[ASK-239](https://github.com/snapfix/docs/blob/main/ASK.md#ask-239-should-an-api-key-see-every-group-and-every-task-of-its-site)]. A group, task, register or asset of another site answers `404`, as if it did not exist.
* **Vendor flag:** a key without the flag gets `401` on `/v1/xvendor` (`app/Http/Middleware/AuthorizeXVendorApi.php:44-46`). A vendor key also passes `/v1/public`, which never reads the flag \[[ASK-160](https://github.com/snapfix/docs/blob/main/ASK.md#ask-160-should-a-vendor-key-also-open-the-open-api)] (`app/Http/Middleware/AuthorizePublicApi.php:36-61`).
* **Unused key fields:** the key's `fMinVersion` and `fAiAccessEnabled` are copied onto the request, and nothing reads them \[[ASK-241](https://github.com/snapfix/docs/blob/main/ASK.md#ask-241-should-a-keys-minimum-version-and-ai-access-flags-be-enforced-or-removed)] (`app/Services/ApiKeyAuthService.php:82-83`).
* **Permissions:** the API user gets the defaults in `resources/other/api_user_permission_defaults.php` ([what a key can do](https://docs.snapfix.com/product/features/integrations/open-api.md#what-a-key-can-do)). Create and change need `CREATE_JOB`, delete needs `DELETE_JOB`, upload needs `UPLOAD_DOCUMENTS`; without one the route answers `403` "Access denied" (`app/Policies/JobPolicy.php:212-234`). Reads check no permission, only the site.
* **Group membership:** the first list, create, change or delete on a group adds the key's API user to the group as an active member with the "User" role, or restores a deleted membership. A read of one group, task, register or asset does not \[[ASK-238](https://github.com/snapfix/docs/blob/main/ASK.md#ask-238-should-list-calls-make-the-keys-user-a-member-of-the-group)]. The membership has view-all set by default, so a task list shows every task of the group \[[ASK-239](https://github.com/snapfix/docs/blob/main/ASK.md#ask-239-should-an-api-key-see-every-group-and-every-task-of-its-site)].
* **Revocation:** a deleted key stops working. Nothing reads the disabled flag or the start and end times, and no route disables or deletes a key.
* **Limits:** each key has a daily and a per-minute limit, 50,000 a day and 60 a minute by default (`fRateLimitPerDay`, `fRateLimitPerMin`). Over a limit the route answers `429` "Daily Limit Exceeded" or "Minute Limit Exceeded" (`app/Http/Middleware/PublicRateLimiterMiddleware.php:31-62`, `app/Providers/RouteServiceProvider.php:61-81`). The product rules are in [uploads and limits](https://docs.snapfix.com/product/features/integrations/open-api.md#uploads-and-limits).
* **Blocked callers:** the `blacklist` middleware runs after the key check. A blocked caller gets `400` and a message with a reference code (`app/Http/Middleware/Blacklist.php:74`).

## Versions

The `X-API-Version` header picks the handler, and its third number is the patch. Every route here has only a version 1.0 handler. Without the header the server's `APP_VERSION` applies, `1.0.0` unless the server sets it (`api_php_live_v2 @ ef3c4319f6, config/app.php:46`); the live value is \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. The version check runs before the key check, so a bad header answers `400` even without a key ([requests](https://docs.snapfix.com/engineering-reference/api.md#requests)). Versions 1.1 and 1.2 fail on every route.

On `/v1/public` the patch switches fields and limits on. `/v1/xvendor` gates nothing on it: its `X-API-Version` only selects the handler.

| Patch | What it adds on `/v1/public`                                                                                                                               |
| ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1     | Tasks carry `createdAt`, `updatedAt`, `tags` and `users`. `detailed` takes effect.                                                                         |
| 2     | Task list date filters `createdSince`, `createdUntil`, `updatedSince` and `updatedUntil`.                                                                  |
| 3     | `limit` is checked (1 to 100) on the group and task lists. Below patch 3 any `limit` is used.                                                              |
| 4     | `priority` on a task change.                                                                                                                               |
| 5     | Task list filters `color`, `housekeepingTasks` and `inspectionTasks`. Tasks carry `room`, `cleaningType`, `cleaningSubType`, `duration` and `completedAt`. |

## Errors

These apply to every route under `/v1/public` and `/v1/xvendor`. The envelope is `{"status": "error", "message": "..."}` ([responses](https://docs.snapfix.com/engineering-reference/api.md#responses)). Each section lists only its own extra errors. apipy's errors are in its sections.

| Status | When                                                                                 | Message                                                                                                        |
| ------ | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
| 400    | Bad `X-API-Version`                                                                  | the untranslated key `validation.version_format` or `validation.version_mismatch`                              |
| 401    | No `X-API-Key` header, or an empty one                                               | "The API key is not provided"                                                                                  |
| 401    | Fewer than four parts, a wrong checksum, or no such key                              | "Provided API key is not valid"                                                                                |
| 401    | `/v1/xvendor` with a key that has no vendor flag                                     | "It looks like you don't have an active subscription. Upgrade your plan to get started."                       |
| 401    | Any other failure of the key check, for example a deleted API user                   | the exception's own text, which can name an internal model (`app/Http/Middleware/AuthorizePublicApi.php:64`)   |
| 400    | Blocked caller                                                                       | "There is an issue with the service you are seeking for. …", with a reference code                             |
| 403    | The key lacks the permission for a write                                             | "Access denied"                                                                                                |
| 404    | The group, task, register or asset does not exist, is deleted, or is in another site | "Resource not found"                                                                                           |
| 422    | A field fails validation                                                             | the first failed rule's message ([responses](https://docs.snapfix.com/engineering-reference/api.md#responses)) |
| 429    | Daily or minute limit reached                                                        | "Daily Limit Exceeded" or "Minute Limit Exceeded"                                                              |
| 500    | An unexpected error                                                                  | "An unexpected error occurred. Please try again later."                                                        |

With `APP_DEBUG` on, errors also carry `file`, `line` and `backtrace`.

## GET /v1/public/groups

List the task groups of the key's site, one page at a time, most recently changed first.

* **Auth:** API key. No permission is checked. Every task group of the site is listed, whatever the key's memberships \[[ASK-239](https://github.com/snapfix/docs/blob/main/ASK.md#ask-239-should-an-api-key-see-every-group-and-every-task-of-its-site)].
* **Used by:** customers' own systems, through the published Open API.

**Request**

| Name      | In    | Type    | Required | Rules                                                                                                                             |
| --------- | ----- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `limit`   | query | integer | no       | page size; default 25. 1 to 100 from patch 3; below patch 3 any value is used                                                     |
| `offset`  | query | integer | no       | page number, from 1; default 1                                                                                                    |
| `orderBy` | query | string  | no       | `asc` or `desc`; default `desc`. Not validated                                                                                    |
| `sortBy`  | query | string  | no       | a key of `resources/other/transformed_keys.php`, for example `name`, `address` or `created`. Unknown keys sort by the last change |
| `search`  | query | string  | no       | matches the group's name and address, ignoring case                                                                               |

**Response** `200`

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "groups": [
      {"uuid": "123", "name": "Main building", "image": null, "address": "1 Example Street"}
    ],
    "pagination": {"total": 1, "perPage": 25, "currentPage": 1, "lastPage": 1, "from": 1, "to": 1}
  }
}
```

Each group is a [group object (public)](#group-object-public). Deleted groups are not listed. After the chosen sort, groups are ordered by their last change or last chat item, whichever is later (`api_php_live_v2 @ ef3c4319f6, app/Services/AssetBusinessService.php:57-103`).

**Errors:** the [common errors](#errors); `422` for a `limit` out of range from patch 3.

**Side effects:** none.

## GET /v1/public/groups/{uuid}

Get one group of the key's site, with its site and statuses.

* **Auth:** API key. No permission is checked. The group must be in the key's site (`api_php_live_v2 @ ef3c4319f6, app/Policies/BusinessPolicy.php:126-133`).
* **Used by:** customers' own systems, through the published Open API.

**Request**

| Name   | In   | Type   | Required | Rules            |
| ------ | ---- | ------ | -------- | ---------------- |
| `uuid` | path | string | yes      | the group's UUID |

**Response** `200`

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "uuid": "123",
    "name": "Main building",
    "image": null,
    "address": "1 Example Street",
    "account": {"uuid": "45", "name": "Example Hotels"},
    "statuses": {
      "red": {"uuid": "501", "name": "red", "count": 3, "definition": "..."}
    }
  }
}
```

`data` is a [group object (public)](#group-object-public) with `account` and `statuses`.

**Errors:** the [common errors](#errors); `404` "Resource not found" when the group is missing, deleted or in another site.

**Side effects:** none.

## GET /v1/public/tasks

List the tasks of one group, one page at a time.

* **Auth:** API key. No permission is checked; the group must be in the key's site.
* **Used by:** customers' own systems, through the published Open API.

**Request**

| Name                                   | In    | Type              | Required | Rules                                                                                                                                                                                                                                           |
| -------------------------------------- | ----- | ----------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `group`                                | query | string            | yes      | the group's UUID                                                                                                                                                                                                                                |
| `archivedTasks`                        | query | `true` or `false` | no       | see the table below                                                                                                                                                                                                                             |
| `normalTasks`                          | query | `true` or `false` | no       | see the table below                                                                                                                                                                                                                             |
| `detailed`                             | query | `true` or `false` | no       | from patch 1: adds each task's assigned and following users                                                                                                                                                                                     |
| `limit`                                | query | integer           | no       | page size; default 25. 1 to 100 from patch 3; below patch 3 there is no maximum                                                                                                                                                                 |
| `offset`                               | query | integer           | no       | page number, from 1                                                                                                                                                                                                                             |
| `orderBy`, `sortBy`                    | query | string            | no       | as for [groups](#get-v1publicgroups), with task keys such as `title`, `created`, `modified`, `lastActivity`, `priorityLevel` and `dueDate`. With `sortBy=dueDate`, `orderBy` goes into the SQL unchecked                                        |
| `createdSince`, `createdUntil`         | query | integer           | no       | from patch 2. Unix seconds, on the creation time. Each needs the other. `createdSince` is compared with itself instead of `createdUntil`, so a reversed range is accepted (`app/Http/Requests/v1/Public/Job/ListAssetJobRequest.php:31`, `:33`) |
| `updatedSince`, `updatedUntil`         | query | integer           | no       | from patch 2. Unix seconds, on the time of the last chat item. Same rules                                                                                                                                                                       |
| `color`                                | query | string            | no       | from patch 5. `red`, `amber` or `green`; `amber` also matches tasks stored as `yellow`                                                                                                                                                          |
| `housekeepingTasks`, `inspectionTasks` | query | `true` or `false` | no       | from patch 5. `true` keeps cleaning tasks or inspection tasks; both `true` keeps both                                                                                                                                                           |

Which tasks come back (`app/Http/Filters/Public/PublicJobFilter.php`):

| `archivedTasks` | `normalTasks` | Tasks returned          |
| --------------- | ------------- | ----------------------- |
| not `true`      | any           | open tasks              |
| `true`          | not `true`    | archived tasks only     |
| `true`          | `true`        | archived and open tasks |

Tasks whose job time or creation time is in the future are left out (`app/Services/AssetJobService.php:1359-1363`).

**Response** `200`

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "tasks": [
      {
        "uuid": "789",
        "title": "Replace bulb",
        "largeTitle": null,
        "description": "Bathroom lamp",
        "image": "https://files.example.com/img/abc123.jpg",
        "isPriority": 0,
        "priorityLevel": 0,
        "isLocked": 0,
        "isArchived": 0,
        "createdAt": "2026-11-01T09:00:00Z",
        "updatedAt": "2026-11-02T14:30:00Z",
        "status": {"uuid": "501", "name": "Red"},
        "users": {"createdBy": {"uuid": "7", "name": "Jane Example", "date": 1761987600000}}
      }
    ],
    "pagination": {"total": 1, "perPage": 25, "currentPage": 1, "lastPage": 1, "from": 1, "to": 1}
  }
}
```

Each task is a [task object (public)](#task-object-public). In a list a task carries `status`, but not `group`, `subStatus`, `checklists` or `messages`.

**Errors:** the [common errors](#errors); `404` when the group is not in the key's site; `422` for a missing `group`, a bad flag, an out-of-range `limit` from patch 3, or a date without its pair from patch 2.

**Side effects:** adds the key's user to the group, if it is not a member yet ([Keys](#keys)). Nothing else is written.

## POST /v1/public/tasks

Create a task in a group, with optional checklist items and chat messages. With AI task suggestions on for the site, the AI can pick the group and fill in more.

* **Auth:** API key with `CREATE_JOB`. The permission is checked before the group is looked up; then the group must be in the key's site.
* **Used by:** customers' own systems, through the published Open API.

**Request** (JSON, form or multipart)

| Name          | In   | Type           | Required                                   | Rules                                                                                                                                                                                                                                |
| ------------- | ---- | -------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `groupUuid`   | body | string         | yes, unless the site has AI suggestions on | the group's UUID. With AI on and no value, the AI picks a group \[[ASK-187](https://github.com/snapfix/docs/blob/main/ASK.md#ask-187-should-open-api-and-vendor-api-tasks-without-a-group-go-to-the-closest-group-at-15-confidence)] |
| `title`       | body | string         | yes                                        | up to 255 characters                                                                                                                                                                                                                 |
| `imageUrl`    | body | URL            | yes, unless `largeTitle` is sent           | must start with the app's media domain (`bo_domain`) and end in an image type: a URL from [upload](#post-v1publicupload)                                                                                                             |
| `largeTitle`  | body | string         | yes, unless `imageUrl` is sent             | text shown in place of an image                                                                                                                                                                                                      |
| `description` | body | string or null | no                                         | free text                                                                                                                                                                                                                            |
| `color`       | body | string         | no                                         | `red` (the default), `amber` or `green`                                                                                                                                                                                              |
| `checklists`  | body | array          | no                                         | items with `name` (string) and `checked` (boolean), both required. No maximum count                                                                                                                                                  |
| `messages`    | body | array          | no                                         | chat items with `type` (`txt`, `vid`, `img` or `doc`), `value` (required) and optional `author`. A file message's `value` must start with the media domain and have an extension of its type. No maximum count                       |

**Response** `200`: the new task as a [task object (public)](#task-object-public), with `group`, `status`, `subStatus`, `checklists`, `messages` and the assigned and following users. The message is "Operation was successful".

**Errors:** the [common errors](#errors), and:

* `400` "AI could not determine a group for this task. Please provide groupUuid." when no group is sent and the AI finds none.
* `403` "Access denied" without `CREATE_JOB`.
* `404` when the group is missing or in another site.
* `422` for a field that fails its rule. A message without `type` or `value` may give `500` instead (`app/Rules/MessageFileTypeRule.php`).

**Side effects** (`app/Http/Controllers/v1/Versions/v1_0/Public/JobController.php:174-365`):

* Writes a [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md) row with origin 7, the public API, and the status and "New" sub-status of its colour. The key's user is its creator.
* Adds the key's user to the group, if it is not a member yet.
* Adds 1 to the site's `task_count` in Firebase.
* Writes a "task created" chat item, a "to do added" chat item per checklist item and one chat item per message, and sends a push notification for each. Then sends a silent task update.
* With AI on: calls the AI service to pick the group when none is sent, and afterwards queues a job that fills in tags, assignees, a room and an area. Both send the key to the AI service.

## GET /v1/public/tasks/{uuid}

Get one task with its group, statuses, checklist and chat.

* **Auth:** API key. No permission is checked; the task's group must be in the key's site.
* **Used by:** customers' own systems, through the published Open API.

**Request**

| Name   | In   | Type   | Required | Rules           |
| ------ | ---- | ------ | -------- | --------------- |
| `uuid` | path | string | yes      | the task's UUID |

**Response** `200`: a [task object (public)](#task-object-public) with `group`, `status`, `subStatus`, `checklists` and `messages`. `detailed` is on, so from patch 1 the assigned and following users are listed; below patch 1 there is no `users` field.

**Errors:** the [common errors](#errors); `404` "Resource not found" when the task is missing or deleted, or its group is in another site.

**Side effects:** none. A single read adds no membership.

## PUT /v1/public/tasks/{uuid}

Change a task. Only the fields sent change.

* **Auth:** API key with `CREATE_JOB`, the same permission as create. The site check runs first, then the permission check (`app/Http/Controllers/v1/Versions/v1_0/Public/JobController.php:405-411`).
* **Used by:** customers' own systems, through the published Open API.

**Request** (JSON, form or multipart)

| Name          | In   | Type           | Required | Rules                                                                                                                                       |
| ------------- | ---- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`        | path | string         | yes      | the task's UUID                                                                                                                             |
| `title`       | body | string         | no       | up to 255 characters                                                                                                                        |
| `imageUrl`    | body | URL            | no       | as for [create](#post-v1publictasks)                                                                                                        |
| `largeTitle`  | body | string         | no       | text in place of an image. It cannot be emptied when the task has no image: "Cannot remove large title if the task does not have an image." |
| `description` | body | string or null | no       | free text                                                                                                                                   |
| `color`       | body | string         | no       | `red`, `amber` or `green`; changes the task's status                                                                                        |
| `ts`          | body | string         | no       | the task's job time (`fJobTs`) in epoch milliseconds; default now                                                                           |
| `priority`    | body | integer        | no       | from patch 4: `0`, `1`, `5`, `10`, `20` or `30`                                                                                             |

**Response** `200`: the changed task, with the same fields as the [create](#post-v1publictasks) response.

**Errors:** the [common errors](#errors); `403` "Access denied" without `CREATE_JOB`; `404` when the task is missing or its group is in another site; `422` for a field that fails its rule.

**Side effects** (`app/Http/Controllers/v1/Versions/v1_0/Public/JobController.php:386-574`):

* Changes the [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md) row. Adds the key's user to the group, if it is not a member yet.
* A colour change sets the colour's time and user on the task, writes a status chat item, and writes a [`tPri_Job_StatusLog`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job_statuslog.md) row. A change to green on a task that needs approval (the task's own setting, or the group's when the task has none) also writes an approval chat item and logs the task as approved.
* A sent title, description, or image or large title each writes its own chat item.
* Each chat item sends a push notification to the task's assigned and following users. The final silent update goes out only when the server's `VIA_QUEUE` setting is on (`app/Services/NotificationService.php:31-33`, `:159-172`).

## DELETE /v1/public/tasks/{uuid}

Delete a task.

* **Auth:** API key with `DELETE_JOB`. The task's group must be in the key's site; that check runs first.
* **Used by:** customers' own systems, through the published Open API.

**Request**

| Name   | In   | Type   | Required | Rules           |
| ------ | ---- | ------ | -------- | --------------- |
| `uuid` | path | string | yes      | the task's UUID |

**Response** `200`

```json
{"status": "success", "message": "Task deleted successfully", "data": null}
```

**Errors:** the [common errors](#errors); `403` "Access denied" without `DELETE_JOB`; `404` when the task is missing, deleted or in another site.

**Side effects:**

* Soft-deletes the task: the row stays, with `fDeleted` set (`app/Http/Controllers/v1/Versions/v1_0/Public/JobController.php:616`).
* Adds the key's user to the group, if it is not a member yet.
* Sends a silent "task deleted" update and subtracts 1 from the site's `task_count` in Firebase.

## POST /v1/public/upload

Store one file and return its URL, for a task's `imageUrl` or a file message's `value`.

* **Auth:** API key with `UPLOAD_DOCUMENTS`.
* **Used by:** customers' own systems, through the published Open API.

**Request** (multipart)

| Name   | In   | Type | Required | Rules                                                                                                                                                                                                                                                                                                                |
| ------ | ---- | ---- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `file` | body | file | yes      | one of `jpg`, `jpeg`, `png`, `gif`, `mp4`, `mov`, `avi`, `ogg`, `webm`, `m4a`, `mp3`, `txt`, `doc`, `docx`, `zip`, `xls`, `xlsx`, `pdf`, `md`, `epub`, `csv`, `json` or `eml`. At most `FILE_MAX_SIZE` kilobytes, 102,400 (100 MB) by default ([files](https://docs.snapfix.com/engineering-reference/api.md#files)) |

**Response** `200`

```json
{"status": "success", "message": "Operation was successful", "data": {"url": "https://files.example.com/img/abc123.jpg"}}
```

`data` is a [file object](#file-object).

**Errors:** the [common errors](#errors); `403` "Access denied" without `UPLOAD_DOCUMENTS`; `422` when the file is missing, of a type not listed, or too big.

**Side effects:** stores the file in the storage bucket under `img`, `vid`, `aud` or `doc`, by its extension (`app/Helpers/common.php:160-190`). Writes no row.

## GET /v1/xvendor/areas

List the areas of the site's building. The building is the first one found for the site, so a site with several buildings lists only one \[[ASK-162](https://github.com/snapfix/docs/blob/main/ASK.md#ask-162-should-the-vendor-api-return-the-rooms-and-areas-of-every-building-of-a-site)] (`api_php_live_v2 @ ef3c4319f6, app/Services/BuildingService.php:61-65`).

* **Auth:** vendor key. No permission is checked; only the key's site is read.
* **Used by:** vendors' own systems, through the published vendor API.

**Request**

| Name     | In    | Type    | Required | Rules                                                                                      |
| -------- | ----- | ------- | -------- | ------------------------------------------------------------------------------------------ |
| `limit`  | query | integer | no       | page size. Not validated: any value is used. Without it, every area comes back in one list |
| `offset` | query | integer | no       | page number, from 1. Used only with `limit`; not validated                                 |

**Response** `200`

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "areas": [
      {"uuid": "a-101", "name": "1st floor"},
      {"uuid": "a-102", "name": "2nd floor"}
    ],
    "totalCount": 2
  }
}
```

Areas are sorted by name, numbered names first. `totalCount` counts every area of the building. `pagination` ([object](#pagination-object)) is added only when `limit` is sent. A site with no building gets an empty list and `0`, not `404`.

**Errors:** the [common errors](#errors).

**Side effects:** none.

## GET /v1/xvendor/asset-regs

List the asset registers of the key's site. A register is a group of the asset kind.

* **Auth:** vendor key. No permission is checked.
* **Used by:** vendors' own systems, through the published vendor API.

**Request**

| Name                          | In    | Type    | Required | Rules                                |
| ----------------------------- | ----- | ------- | -------- | ------------------------------------ |
| `limit`                       | query | integer | no       | 1 to 100; default 25                 |
| `offset`                      | query | integer | no       | page number, from 1                  |
| `orderBy`, `sortBy`, `search` | query | string  | no       | as for [groups](#get-v1publicgroups) |

**Response** `200`: `data` is `{"assetRegs": [...], "pagination": {...}}`. Each item is an [asset register object](#room-area-asset-and-register-objects).

**Errors:** the [common errors](#errors); `422` for a `limit` outside 1 to 100.

**Side effects:** none.

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

Get one asset register of the key's site.

* **Auth:** vendor key. The register must be in the key's site.
* **Used by:** vendors' own systems, through the published vendor API.

**Request**

| Name   | In   | Type   | Required | Rules               |
| ------ | ---- | ------ | -------- | ------------------- |
| `uuid` | path | string | yes      | the register's UUID |

**Response** `200`: `data` is an [asset register object](#room-area-asset-and-register-objects), for example `{"uuid": "ar-1", "name": "Minibar"}`.

**Errors:** the [common errors](#errors); `404` "Resource not found" when the register is missing, deleted or in another site.

**Side effects:** none.

## GET /v1/xvendor/assets

List the assets of one asset register. Each asset is a row of the register, stored as a task row in the register's group ([asset registers](https://docs.snapfix.com/product/features/assets/asset-registers.md)).

* **Auth:** vendor key. No permission is checked; the register must be in the key's site.
* **Used by:** vendors' own systems, through the published vendor API.

**Request**

| Name                                                           | In    | Type              | Required | Rules                                                                                     |
| -------------------------------------------------------------- | ----- | ----------------- | -------- | ----------------------------------------------------------------------------------------- |
| `assetReg`                                                     | query | string            | yes      | the register's UUID                                                                       |
| `archivedTasks`, `normalTasks`                                 | query | `true` or `false` | no       | as on the [public task list](#get-v1publictasks); by default archived assets are left out |
| `detailed`                                                     | query | `true` or `false` | no       | checked, but this list does not use it                                                    |
| `limit`                                                        | query | integer           | no       | 1 to 100; default 25                                                                      |
| `offset`                                                       | query | integer           | no       | page number, from 1                                                                       |
| `orderBy`, `sortBy`                                            | query | string            | no       | as for [groups](#get-v1publicgroups)                                                      |
| `createdSince`, `createdUntil`, `updatedSince`, `updatedUntil` | query | integer           | no       | read as on the [vendor task list](#get-v1xvendortasks), unchecked                         |

**Response** `200`: `data` is `{"assets": [...], "pagination": {...}}`. Each item is an [asset object](#room-area-asset-and-register-objects), for example `{"uuid": "as-1", "title": "Minibar fridge"}`.

**Errors:** the [common errors](#errors); `404` when the register is not in the key's site; `422` for a missing `assetReg`, a bad flag or a `limit` out of range.

**Side effects:** adds the key's user to the register's group, if it is not a member yet ([Keys](#keys)).

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

Get one asset.

* **Auth:** vendor key. The asset's register must be in the key's site.
* **Used by:** vendors' own systems, through the published vendor API.

**Request**

| Name   | In   | Type   | Required | Rules            |
| ------ | ---- | ------ | -------- | ---------------- |
| `uuid` | path | string | yes      | the asset's UUID |

**Response** `200`: `data` is an [asset object](#room-area-asset-and-register-objects).

**Errors:** the [common errors](#errors); `404` "Resource not found" when the asset is missing or its register is not a register of the key's site.

**Side effects:** none.

## GET /v1/xvendor/groups

List the task groups of the key's site, one page at a time.

* **Auth:** vendor key. No permission is checked. Every task group of the site is listed \[[ASK-239](https://github.com/snapfix/docs/blob/main/ASK.md#ask-239-should-an-api-key-see-every-group-and-every-task-of-its-site)].
* **Used by:** vendors' own systems, through the published vendor API.

**Request**

| Name                          | In    | Type    | Required | Rules                                |
| ----------------------------- | ----- | ------- | -------- | ------------------------------------ |
| `limit`                       | query | integer | no       | 1 to 100; default 25                 |
| `offset`                      | query | integer | no       | page number, from 1                  |
| `orderBy`, `sortBy`, `search` | query | string  | no       | as for [groups](#get-v1publicgroups) |

**Response** `200`: `data` is `{"groups": [...], "pagination": {...}}`, as on [`GET /v1/public/groups`](#get-v1publicgroups). Each group is a [group object (vendor)](#group-object-vendor) without `statuses` and `users`.

**Errors:** the [common errors](#errors); `422` for a `limit` outside 1 to 100.

**Side effects:** none.

## GET /v1/xvendor/groups/{uuid}

Get one group of the key's site, with its statuses and members.

* **Auth:** vendor key. The group must be in the key's site.
* **Used by:** vendors' own systems, through the published vendor API.

**Request**

| Name   | In   | Type   | Required | Rules            |
| ------ | ---- | ------ | -------- | ---------------- |
| `uuid` | path | string | yes      | the group's UUID |

**Response** `200`

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "uuid": "123",
    "name": "Main building",
    "image": null,
    "address": "1 Example Street",
    "statuses": {
      "red": {"uuid": "501", "name": "red", "count": 3, "definition": "..."}
    },
    "users": [
      {"uuid": "7", "name": "Jane Example"}
    ]
  }
}
```

`data` is a [group object (vendor)](#group-object-vendor). It has no `account`.

**Errors:** the [common errors](#errors); `404` "Resource not found" when the group is missing, deleted or in another site.

**Side effects:** none.

## GET /v1/xvendor/groups/{uuid}/tags

List a group's tag folders with their tags: the group's own folders, and the folders of tag rules that do not exclude the group.

* **Auth:** vendor key. The group must be in the key's site.
* **Used by:** vendors' own systems, through the published vendor API.

**Request**

| Name   | In   | Type   | Required | Rules            |
| ------ | ---- | ------ | -------- | ---------------- |
| `uuid` | path | string | yes      | the group's UUID |

**Response** `200`

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": [
    {"uuid": "th-1", "name": "Equipment", "tags": [{"uuid": "t-1", "name": "Boiler"}]}
  ]
}
```

`data` is a list of [tag folder objects (vendor)](#tag-folder-object-vendor), with no wrapper and no `pagination` (`api_php_live_v2 @ ef3c4319f6, app/Http/Resources/v1/XVendor/TagHeaderResource.php:20-22`).

**Errors:** the [common errors](#errors); `404` "Resource not found" when the group is missing, deleted or in another site.

**Side effects:** none.

## GET /v1/xvendor/rooms

List the rooms of the site's building, the first building found for the site \[[ASK-162](https://github.com/snapfix/docs/blob/main/ASK.md#ask-162-should-the-vendor-api-return-the-rooms-and-areas-of-every-building-of-a-site)].

* **Auth:** vendor key. No permission is checked; only the key's site is read.
* **Used by:** vendors' own systems, through the published vendor API.

**Request**

| Name     | In    | Type    | Required | Rules                                                         |
| -------- | ----- | ------- | -------- | ------------------------------------------------------------- |
| `limit`  | query | integer | no       | page size. Not validated, as for [areas](#get-v1xvendorareas) |
| `offset` | query | integer | no       | page number, from 1. Used only with `limit`                   |

**Response** `200`: `data` is `{"rooms": [{"uuid": "r-101", "name": "Room 101"}], "totalCount": 1}`. Each room is a [room object](#room-area-asset-and-register-objects). `pagination` is added only when `limit` is sent, and a site with no building gets an empty list, as for [areas](#get-v1xvendorareas).

**Errors:** the [common errors](#errors).

**Side effects:** none.

## GET /v1/xvendor/tasks

List the tasks of one group, one page at a time.

* **Auth:** vendor key. No permission is checked; the group must be in the key's site.
* **Used by:** vendors' own systems, through the published vendor API.

**Request**

| Name                                                           | In    | Type              | Required | Rules                                                                                                                                                                                                                                           |
| -------------------------------------------------------------- | ----- | ----------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `group`                                                        | query | string            | yes      | the group's UUID                                                                                                                                                                                                                                |
| `archivedTasks`, `normalTasks`                                 | query | `true` or `false` | no       | as on the [public task list](#get-v1publictasks)                                                                                                                                                                                                |
| `detailed`                                                     | query | `true` or `false` | no       | adds each task's assigned and following users                                                                                                                                                                                                   |
| `limit`                                                        | query | integer           | no       | 1 to 100; default 25                                                                                                                                                                                                                            |
| `offset`                                                       | query | integer           | no       | page number, from 1                                                                                                                                                                                                                             |
| `orderBy`, `sortBy`                                            | query | string            | no       | as on the [public task list](#get-v1publictasks), with the same `dueDate` flaw                                                                                                                                                                  |
| `createdSince`, `createdUntil`, `updatedSince`, `updatedUntil` | query | integer           | no       | Unix seconds, read straight from the query with no check and no version gate. As read in code, a `Since` without its `Until` matches no task, and an `Until` alone has no effect (`app/Http/Filters/XVendor/AbstractXVendorTaskListFilter.php`) |

The vendor list has no `color`, `housekeepingTasks` or `inspectionTasks` filter.

**Response** `200`: `data` is `{"tasks": [...], "pagination": {...}}`. Each task is a [task object (vendor)](#task-object-vendor). In a list a task carries `status`, `tags` and `users`, but not `group`, `subStatus`, `room`, `area`, `assets`, `checklists` or `messages`.

**Errors:** the [common errors](#errors); `404` when the group is not in the key's site; `422` for a missing `group`, a bad flag or a `limit` out of range.

**Side effects:** adds the key's user to the group, if it is not a member yet ([Keys](#keys)).

## POST /v1/xvendor/tasks

Create a task, with optional links to a room, an area, assets, tags and assignees. A link that cannot be made comes back as a warning, and the task is still created.

* **Auth:** vendor key with `CREATE_JOB`. The permission is checked before the group is looked up; then the group must be in the key's site.
* **Used by:** vendors' own systems, through the published vendor API.

**Request** (JSON, form or multipart)

| Name                                                                                             | In   | Type                     | Required | Rules                                                                                                        |
| ------------------------------------------------------------------------------------------------ | ---- | ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------ |
| `groupUuid`, `title`, `imageUrl`, `largeTitle`, `description`, `color`, `checklists`, `messages` | body |                          |          | as for [public create](#post-v1publictasks)                                                                  |
| `roomUuid`                                                                                       | body | string                   | no       | a room. Not checked against the key's site. A room that does not exist gives a warning                       |
| `areaUuid`                                                                                       | body | string                   | no       | an area. Not checked against the key's site. An area that does not exist gives a warning                     |
| `assetUuids`                                                                                     | body | array of strings         | no       | assets. Not checked against the key's site. An asset that does not exist gives a warning                     |
| `tagUuids`                                                                                       | body | array of strings or null | no       | tags. An unknown tag gives a warning. A tag from a folder the group does not have is dropped with no warning |
| `assignUserUuids`                                                                                | body | array of strings or null | no       | users to assign. A user who is not an active member of the group gives a warning                             |

**Response** `200`

```json
{
  "status": "success",
  "message": "Task created successfully, with warnings",
  "data": {
    "uuid": "791",
    "title": "Check the boiler",
    "largeTitle": null,
    "description": null,
    "image": null,
    "isPriority": 0,
    "priorityLevel": 0,
    "isLocked": 0,
    "isArchived": 0,
    "createdAt": "2026-11-15T10:05:00Z",
    "updatedAt": "2026-11-15T10:05:00Z",
    "group": {"uuid": "123", "name": "Main building"},
    "status": {"uuid": "501", "name": "Red"},
    "subStatus": {"uuid": "502", "name": "New"},
    "room": {"uuid": "r-101", "name": "Room 101"},
    "assets": [],
    "checklists": [],
    "messages": []
  },
  "warnings": [
    {"type": "tag", "uuid": "t-999", "message": "Tag not found"}
  ]
}
```

`data` is a [task object (vendor)](#task-object-vendor). The message is "Task created successfully", or "Task created successfully, with warnings" with a `warnings` list of [warning objects](#warning-object) beside `data`.

**Errors:** the [common errors](#errors), and the same `400`, `403`, `404` and `422` cases as [public create](#post-v1publictasks), including the server error for a message item without `type` or `value`.

**Side effects** (`api_php_live_v2 @ ef3c4319f6, app/Http/Controllers/v1/Versions/v1_0/XVendor/JobController.php:184-672`):

* Writes a [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md) row with origin 11, the vendor API. The origin table does not name 11.
* Adds the key's user to the group, if it is not a member yet, and adds 1 to the site's `task_count` in Firebase.
* Writes the "task created", checklist and message chat items as public create does, plus a chat item for each room, area, asset and tag linked, with a push notification for each. Each assignee gets a "user assigned" chat item and an assignment job. Then sends a silent task update.
* With AI on, as for [public create](#post-v1publictasks).

## GET /v1/xvendor/tasks/{uuid}

Get one task with its room, area, assets, checklist and chat.

* **Auth:** vendor key. No permission is checked; the task's group must be in the key's site.
* **Used by:** vendors' own systems, through the published vendor API.

**Request**

| Name   | In   | Type   | Required | Rules           |
| ------ | ---- | ------ | -------- | --------------- |
| `uuid` | path | string | yes      | the task's UUID |

**Response** `200`: a [task object (vendor)](#task-object-vendor) with `group`, `status`, `subStatus`, `checklists`, `room`, `area`, `assets`, `messages`, `tags` and the assigned and following users.

**Errors:** the [common errors](#errors); `404` "Resource not found" when the task is missing or deleted, or its group is in another site.

**Side effects:** none.

## PUT /v1/xvendor/tasks/{uuid}

Change a task and its links. Only the fields sent change.

* **Auth:** vendor key with `CREATE_JOB`. The site check runs first, then the permission check.
* **Used by:** vendors' own systems, through the published vendor API.

**Request** (JSON, form or multipart)

| Name                                                            | In   | Type           | Required | Rules                                                                                                                                                           |
| --------------------------------------------------------------- | ---- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`                                                          | path | string         | yes      | the task's UUID                                                                                                                                                 |
| `title`, `imageUrl`, `largeTitle`, `description`, `color`, `ts` | body |                | no       | as for [public change](#put-v1publictasksuuid)                                                                                                                  |
| `priority`                                                      | body | integer        | no       | `0`, `1`, `5`, `10`, `20` or `30`, with no version gate                                                                                                         |
| `roomUuid`                                                      | body | string or null | no       | a room replaces the task's room. A room that does not exist, or is in another site, gives a warning and the current link stays. An empty value removes the room |
| `areaUuid`                                                      | body | string or null | no       | the same, for the area                                                                                                                                          |
| `tags`                                                          | body | object         | no       | `addTagUuids` and `removeTagUuids`, arrays of strings. Unknown tags give warnings; a tag from a folder the group does not have is dropped with no warning       |
| `assignUsers`                                                   | body | object         | no       | `addUserUuids` and `removeUserUuids`. Adding a user who is not an active member gives a warning                                                                 |
| `assets`                                                        | body | object         | no       | `addAssetUuids` and `removeAssetUuids`. Added assets are not checked against the key's site; removing one that is not linked gives a warning                    |

**Response** `200`: the changed task, with the same fields as the [create](#post-v1xvendortasks) response. The message is "Task updated successfully", or "Task updated successfully, with warnings" with a `warnings` list.

**Errors:** the [common errors](#errors); `403` "Access denied" without `CREATE_JOB`; `404` when the task is missing or in another site; `422` for a field that fails its rule.

**Side effects** (`app/Http/Controllers/v1/Versions/v1_0/XVendor/JobController.php:703-1438`):

* Changes the task as [public change](#put-v1publictasksuuid) does, including the status log row and the approval on green. Adds the key's user to the group, if it is not a member yet.
* A new room writes a "room selected" chat item; an empty `roomUuid` removes the room and writes "room unselected" (`:897-967`). The area works the same (`:970-1028`).
* Tag, assignee and asset changes each write their "selected", "unselected", "assigned", "unassigned", "added" or "removed" chat item, with a push notification. Newly assigned users get an assignment job.
* Sends no AI call. The silent task update goes out only when the server's `VIA_QUEUE` setting is on, as for [public change](#put-v1publictasksuuid).

## DELETE /v1/xvendor/tasks/{uuid}

Delete a task.

* **Auth:** vendor key with `DELETE_JOB`. The site check runs first.
* **Used by:** vendors' own systems, through the published vendor API.

**Request**

| Name   | In   | Type   | Required | Rules           |
| ------ | ---- | ------ | -------- | --------------- |
| `uuid` | path | string | yes      | the task's UUID |

**Response** `200`: as for [public delete](#delete-v1publictasksuuid), with the message "Task deleted successfully".

**Errors:** the [common errors](#errors); `403` "Access denied" without `DELETE_JOB`; `404` when the task is missing, deleted or in another site.

**Side effects:** as for [public delete](#delete-v1publictasksuuid): adds the membership first, then soft-deletes the task, sends the silent "task deleted" update and subtracts 1 from `task_count` (`app/Http/Controllers/v1/Versions/v1_0/XVendor/JobController.php:1473-1480`).

## POST /v1/xvendor/upload

Store one file and return its URL, as the [public upload](#post-v1publicupload) does.

* **Auth:** vendor key with `UPLOAD_DOCUMENTS`.
* **Used by:** vendors' own systems, through the published vendor API.

**Request** and **Response:** as for [public upload](#post-v1publicupload).

**Errors:** the [common errors](#errors); `403` "Access denied" without `UPLOAD_DOCUMENTS`; `422` when the file is missing, of a type not allowed, or too big.

**Side effects:** stores the file as the public upload does. Writes no row.

## GET /v1/task

Read one task by ID, served by apipy. The route has its own key table and its own envelope.

* **Auth:** the `x-api-key` header. apipy accepts a key of `tPri_Parent_Api` that is not deleted or disabled and whose start and end times include now (`apipy @ 0e83c85e5a, model/t_log_ip_blocked_v3.py:761-787`). The keys are stored in plain text. A key is not tied to the task's group or site, so any key reads any task.
* **Used by:** customers' own integrations, through the handler built for them (`app.py:3756-3804`). Not in the Swagger docs \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)].

**Request**

| Name      | In    | Type   | Required | Rules           |
| --------- | ----- | ------ | -------- | --------------- |
| `task_id` | query | string | yes      | the task's UUID |

**Response** `200`

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1763200000000,
  "data": {
    "job": {
      "id": 123,
      "job_id": "789",
      "group_id": "123",
      "status": "red",
      "title": "Replace bulb",
      "description": "Bathroom lamp",
      "image_url": null,
      "image_text": null,
      "lat": null,
      "lng": null,
      "priority": 0,
      "prioritynumber": 1000,
      "jobref": "12",
      "locked": 0,
      "archived": 0,
      "created_ts": 1761987600000,
      "modified_ts": 1761987600000,
      "createdby": "Jane Example",
      "modifiedby": "Jane Example"
    },
    "assets": [],
    "tags": [],
    "users": [],
    "checklist": [],
    "assignees": [],
    "signatures": [],
    "recent_signature": null,
    "times": [],
    "costs": [],
    "last_viewed": []
  }
}
```

`job` holds the task's columns under the names above, with the creator's and last editor's names. The lists hold the linked rows (`model/ext/feature_job.py:468-711`):

| Key                              | Each item                                                                                                                        |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `assets`                         | `name`, `registrar` (the register's name)                                                                                        |
| `tags`                           | `tag`, `tagheader`                                                                                                               |
| `users` (followers), `assignees` | `user_name`, `user_image`                                                                                                        |
| `checklist`                      | `name`, `section`, `sort_order`, the NFC, choice, yes/no and note settings and values, `completed`, `completed_ts`, `created_ts` |
| `signatures`                     | `user_name`, `user_image`, `signature_url`; `recent_signature` is the first                                                      |
| `times`, `costs`                 | `user_name`, `user_image`, `currency_code`, `cost`, `title`, `description`, `created_ts`; `times` adds `time_in_ms`              |
| `last_viewed`                    | `user_name`, `user_image`, `last_viewed_ts`                                                                                      |

**Errors:** the envelope is `{"result": false, "message": "...", "serverTs": ...}`.

| Status | Message                                                                            | When                                                                                |
| ------ | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| 400    | "bad request"                                                                      | `task_id` is missing                                                                |
| 400    | "task does not exist"                                                              | no task with that ID                                                                |
| 400    | "task does not exist or it has been deleted"                                       | the task is deleted                                                                 |
| 200    | "There is an issue with the service you are seeking for. …", with a reference code | a missing or invalid key, or another block: `result` is false but the status is 200 |
| 409    | the block message                                                                  | the block asks for email or phone verification (`app.py:251-265`)                   |

**Side effects:** writes the request, with all its headers, and the response to the daily API log. A refused key is also written into the block note.

## POST /v1/task

Create a task in the group named in the query, served by apipy.

* **Auth:** the same `x-api-key` check as [GET /v1/task](#get-v1task). The key is not tied to the group in `group_id`.
* **Used by:** customers' own integrations, as for [GET /v1/task](#get-v1task) \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)].

**Request**

| Name                                                                    | In    | Type             | Required                              | Rules                                                                                                                                                       |
| ----------------------------------------------------------------------- | ----- | ---------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `group_id`                                                              | query | string           | yes                                   | the group's UUID. The group must exist, not be deleted, and have an admin                                                                                   |
| `title`                                                                 | body  | string           | yes                                   | not empty                                                                                                                                                   |
| `image_base64`                                                          | body  | string           | one of `image_base64` or `image_text` | a base64 image; it is uploaded to S3 and its URL becomes the task's image                                                                                   |
| `image_text`                                                            | body  | string           | one of `image_base64` or `image_text` | text in place of an image, used when no `image_base64` is sent                                                                                              |
| `description`                                                           | body  | string           | no                                    |                                                                                                                                                             |
| `task_ref`                                                              | body  | string           | no                                    | the task's reference. Without it the reference is two random digits                                                                                         |
| `task_ts`                                                               | body  | integer          | no                                    | the creation and job time, in epoch milliseconds; default now                                                                                               |
| `priority`, `lat`, `lng`, `search_text`, `checklist_signature_required` | body  |                  | no                                    | stored as sent                                                                                                                                              |
| `assignees`, `followers`                                                | body  | array of strings | no                                    | user UUIDs. A user who is not a member of the group is skipped with no error                                                                                |
| `tags`                                                                  | body  | array            | no                                    | items `{"tag_header": "<folder name>", "tag": ["<tag name>"]}`. An unknown folder is an error; an unknown tag name is created in the folder                 |
| `checklist_items`                                                       | body  | array            | no                                    | items with a `name`, and optional `section`, `sort_order`, `nfc_enable`, `nfc_serial`, `radio_enable`, `radio_mandatory`, `notes_enable` and `yesno_enable` |
| `messages`                                                              | body  | array            | no                                    | chat items with optional `sender_name`, `uuid_tChatItemType` (default 1), `text`, `fFileUrl` and `fThumbnailUrl`; not validated                             |

**Response** `201`: the same envelope and `data` as [GET /v1/task](#get-v1task), for the new task.

**Errors:** the envelope is `{"result": false, "message": "...", "serverTs": ...}`, with status `400` for all of these, and the block responses of [GET /v1/task](#get-v1task):

| Message                                                                                   | When                                                                                |
| ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| "bad request"                                                                             | `group_id` is missing, or the body is empty                                         |
| "invalid group"                                                                           | `group_id` is empty                                                                 |
| "we could not find the admin of the specified group. please contact our support team."    | the group has no admin. Checked first, so a missing group usually gets this message |
| "invalid task title"                                                                      | `title` is missing or empty                                                         |
| "either image\_text or image\_base64 should be mentioned"                                 | neither image field is sent                                                         |
| "group does not exist or it has been deleted"                                             | the group is deleted                                                                |
| "There is an issue with group configuration(status). Please contact our support team."    | the group has no "Red" status                                                       |
| "There is an issue with group configuration(substatus). Please contact our support team." | the group has no "New" sub-status                                                   |
| "tag\_header(...) does not exist"                                                         | a tag folder is not in the group                                                    |
| "checklist item cannot be created without a valid name"                                   | a checklist item has no name                                                        |

**Side effects** (`apipy @ 0e83c85e5a, model/ext/feature_job.py:21-466`):

* Writes a red [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md) row with the "Red" status and "New" sub-status. It has no origin (0), so it cannot be told from other tasks. Its creator and editor are the group's first admin, not the key \[[ASK-240](https://github.com/snapfix/docs/blob/main/ASK.md#ask-240-who-should-own-a-task-created-through-apipys-v1task)].
* Writes a "created task" chat item, and the assignee, follower, tag, checklist and chat rows, each in its own statement with no transaction.
* Sends no push notification and does not change the Firebase task count.
* Logs the call as [GET /v1/task](#get-v1task) does.

## Shared objects

Timestamps are ISO 8601 strings in UTC, in the form `2026-11-02T09:00:00Z`, unless a field says otherwise.

### Task object (public)

`app/Http/Resources/v1/Public/AssetJobResource.php`.

| Field                             | Type                                                             | Sent                                                                                                                                                                                                                                                                              |
| --------------------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`, `title`                   | string                                                           | always                                                                                                                                                                                                                                                                            |
| `largeTitle`                      | string or null                                                   | always. Text shown in place of an image                                                                                                                                                                                                                                           |
| `description`                     | string or null                                                   | always                                                                                                                                                                                                                                                                            |
| `image`                           | URL or null                                                      | always                                                                                                                                                                                                                                                                            |
| `isPriority`                      | integer                                                          | always. `1` when the task is marked priority                                                                                                                                                                                                                                      |
| `priorityLevel`                   | integer                                                          | always. `0`, `1`, `5`, `10`, `20` or `30`; a priority task at level `0` reads as `20`                                                                                                                                                                                             |
| `isLocked`, `isArchived`          | integer                                                          | always                                                                                                                                                                                                                                                                            |
| `createdAt`, `updatedAt`          | ISO 8601                                                         | from patch 1. `updatedAt` is the time of the last chat item                                                                                                                                                                                                                       |
| `status`                          | object `{uuid, name}`                                            | lists, and single, create and change responses. The colour status; `name` defaults to "Red"                                                                                                                                                                                       |
| `subStatus`                       | object `{uuid, name}`                                            | single, create and change responses. `name` defaults to "New"                                                                                                                                                                                                                     |
| `group`                           | object `{uuid, name}`                                            | single, create and change responses                                                                                                                                                                                                                                               |
| `tags`                            | list of [tag folder objects (public)](#tag-folder-object-public) | from patch 1, when the task has tags                                                                                                                                                                                                                                              |
| `checklists`                      | list of [checklist items](#checklist-item)                       | single, create and change responses                                                                                                                                                                                                                                               |
| `messages`                        | list of [message objects](#message-object)                       | single, create and change responses                                                                                                                                                                                                                                               |
| `users`                           | object                                                           | from patch 1. `createdBy` and `modifiedBy` when set; `assigned` and `following` lists when `detailed` is on (always on single, create and change responses). Each user is `{uuid, name, date}`, `date` in epoch milliseconds (`app/Http/Resources/v1/Public/JobUserResource.php`) |
| `room`                            | object `{uuid, name, enumRoomType}` or null                      | from patch 5. The task's first room                                                                                                                                                                                                                                               |
| `cleaningType`, `cleaningSubType` | string or null                                                   | from patch 5                                                                                                                                                                                                                                                                      |
| `duration`                        | integer                                                          | from patch 5. Minutes, always computed                                                                                                                                                                                                                                            |
| `completedAt`                     | ISO 8601 or null                                                 | from patch 5. The time the task went green                                                                                                                                                                                                                                        |

### Task object (vendor)

`app/Http/Resources/v1/XVendor/JobResource.php`. No field depends on the version.

| Field                                                                                                          | Type                                                                                         | Sent                                                                                                                               |
| -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`, `title`, `largeTitle`, `description`, `image`, `isPriority`, `priorityLevel`, `isLocked`, `isArchived` | as in the [public task object](#task-object-public)                                          | always                                                                                                                             |
| `createdAt`, `updatedAt`                                                                                       | ISO 8601                                                                                     | always                                                                                                                             |
| `status`, `subStatus`, `group`, `checklists`, `messages`                                                       | as in the [public task object](#task-object-public)                                          | as in the public task object                                                                                                       |
| `tags`                                                                                                         | list of [tag folder objects (vendor)](#tag-folder-object-vendor), each tag with `jobTagUuid` | when the task has tags                                                                                                             |
| `room`, `area`                                                                                                 | object `{uuid, name}`                                                                        | single, create and change responses, when linked                                                                                   |
| `assets`                                                                                                       | list of `{uuid, title}`                                                                      | single, create and change responses                                                                                                |
| `users`                                                                                                        | object                                                                                       | always. `createdBy` and `modifiedBy` when set; `assigned` and `following` when `detailed` is on. Each user is `{uuid, name, date}` |

### Checklist item

`app/Http/Resources/v1/TodoResource.php`.

| Field                                              | Type    | Meaning                                              |
| -------------------------------------------------- | ------- | ---------------------------------------------------- |
| `uuid`, `name`                                     | string  | the item's ID and text                               |
| `type`                                             | integer | the item type                                        |
| `sortOrder`                                        | integer | the position in the checklist                        |
| `isDone`                                           | integer | done flag                                            |
| `mandatory`, `noteMandatory`, `todoMediaMandatory` | integer | whether a choice, a note or a photo is required      |
| `completionTs`, `modifiedTs`                       | integer | completion and change times, as stored               |
| `media`, `subItems`                                | list    | only when loaded                                     |
| `settings`                                         | object  | the NFC, note, choice and rating settings and values |

### Message object

A chat item on the task (`app/Http/Resources/v1/ChatItemResource.php`).

| Field                                       | Type                                                         | Meaning                                           |
| ------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------- |
| `uuid`, `text`                              | string                                                       | the ID and text                                   |
| `type`                                      | string or integer                                            | the chat item type code, as stored                |
| `fileUrl`, `thumbnailUrl`                   | URL or null                                                  | the attached file and its thumbnail               |
| `titleValueAI`, `transcriptValueAI`         | string or null                                               | the AI title and transcript                       |
| `active`                                    | integer                                                      | active flag                                       |
| `replyUuid`                                 | string or null                                               | the item this one replies to                      |
| `jobChatTs`                                 | integer                                                      | the item's time, in epoch milliseconds            |
| `createdTs`, `modifiedTs`                   | integer                                                      | creation and change times, in epoch milliseconds  |
| `createdAt`, `updatedAt`                    | ISO 8601                                                     | the item's time (`jobChatTs`) and its change time |
| `assetUuid`, `assetRegUuid`, `taskLinkUuid` | string                                                       | only when set                                     |
| `user`                                      | object `{uuid, name, image, username, businessName}` or null | the author                                        |
| `reactions`                                 | list                                                         | only when loaded                                  |

### Group object (public)

`app/Http/Resources/v1/Public/AssetBusinessResource.php`.

| Field              | Type                  | Sent                                                                                                                                                                                                 |
| ------------------ | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`, `name`     | string                | always                                                                                                                                                                                               |
| `image`, `address` | string or null        | always                                                                                                                                                                                               |
| `account`          | object `{uuid, name}` | single responses. The group's site                                                                                                                                                                   |
| `statuses`         | object                | single responses. Keyed by colour in lower case (`red`, `amber`, `green`); each status is `{uuid, name, count, definition}`, `name` in lower case too (`app/Http/Resources/v1/StatusCollection.php`) |

### Group object (vendor)

`app/Http/Resources/v1/XVendor/BusinessResource.php`.

| Field                              | Type                                                  | Sent                                                                                                  |
| ---------------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `uuid`, `name`, `image`, `address` | as in the [public group object](#group-object-public) | always                                                                                                |
| `statuses`                         | object                                                | single responses, as in the public group object                                                       |
| `users`                            | list of `{uuid, name}`                                | single responses. The group's members (`app/Http/Resources/v1/XVendor/UserAssetBusinessResource.php`) |

### Room, area, asset and register objects

| Object         | Fields                                                    |
| -------------- | --------------------------------------------------------- |
| Room           | `{uuid, name}`                                            |
| Area           | `{uuid, name}`                                            |
| Asset          | `{uuid, title}`                                           |
| Asset register | `{uuid, name}`. The register's `uuid` is its group's UUID |

### Tag folder object (public)

On public tasks (`app/Http/Resources/v1/TagHeaderResource.php`).

| Field          | Type           | Meaning                                                                                                                                         |
| -------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`, `name` | string         | the folder's ID and name                                                                                                                        |
| `description`  | string or null | the folder's description                                                                                                                        |
| `mandatory`    | integer        | `1` when the group requires a tag from the folder                                                                                               |
| `tags`         | list           | each `{jobTagUuid, uuid, name, aiNewTag}`, plus `aiSuggested` when the AI picked the tag. `jobTagUuid` is the link between the tag and the task |

### Tag folder object (vendor)

On vendor tasks and the vendor tag list (`app/Http/Resources/v1/XVendor/TagHeaderResource.php`).

| Field          | Type                   | Meaning                                                  |
| -------------- | ---------------------- | -------------------------------------------------------- |
| `uuid`, `name` | string                 | the folder's ID and name                                 |
| `tags`         | list of `{uuid, name}` | the folder's tags. On a task, each tag adds `jobTagUuid` |

### Pagination object

| Field                     | Type    | Meaning                              |
| ------------------------- | ------- | ------------------------------------ |
| `total`                   | integer | all rows                             |
| `perPage`                 | integer | the page size used                   |
| `currentPage`, `lastPage` | integer | the page returned, and the last page |
| `from`, `to`              | integer | the first and last row on this page  |

### File object

`app/Http/Resources/v1/FileResource.php`. The upload returns only `url`: `https://<bucket>/<folder>/<file>`. The resource's `metaData`, `metaUrl` and `ai` fields are never set by these routes.

### Warning object

Sent in `warnings`, beside `data`, when a vendor create or change could not make a link. The task is still saved.

| Field     | Type   | Meaning                                                                                                                                         |
| --------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`    | string | `room`, `area`, `asset`, `tag` or `user`                                                                                                        |
| `uuid`    | string | the ID that was sent                                                                                                                            |
| `message` | string | "Room not found", "Area not found", "Asset not found", "Tag not found" or "User doesn't exist!" (`lang/en/messages.php:63`, `:109-119`, `:162`) |


---

# 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/open-api.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.
