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

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

Endpoints the apps call, one doc per group. This page holds what every group shares (step 3.2): services and base URLs, authentication, request and error format, paging, dates and time zones, file uploads.

## Groups

One group per product area where the endpoints serve one area, then seven cross-cutting groups (the last seven rows) for sign-in, users, tags, files, lookup data, the customer APIs, and calls between Snapfix services.

| Group                                                                                | Service                                                                    | What it covers                                                                                    |
| ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| [Account](https://docs.snapfix.com/engineering-reference/api/account.md)             | api\_php\_live\_v2, php-apis                                               | The user's profile, GDPR consent, on-call status, preferences and dynamic links                   |
| [Onboarding](https://docs.snapfix.com/engineering-reference/api/onboarding.md)       | api\_php\_live\_v2, php-apis, authpy                                       | Setting up a new site from templates, the onboarding form, the pre-registration survey            |
| [Tasks](https://docs.snapfix.com/engineering-reference/api/tasks.md)                 | api\_php\_live\_v2, php-apis, apipy                                        | Creating, listing and changing tasks and their details, sharing, the mobile apps' task data loads |
| [Chat](https://docs.snapfix.com/engineering-reference/api/chat.md)                   | api\_php\_live\_v2, php-apis                                               | Chat messages, files, reactions and transcripts                                                   |
| [Planner](https://docs.snapfix.com/engineering-reference/api/planner.md)             | php-apis, apipy                                                            | Schedules for planned and repeating tasks, calendar events                                        |
| [Checklists](https://docs.snapfix.com/engineering-reference/api/checklists.md)       | api\_php\_live\_v2, php-apis                                               | Checklist templates, folders, permissions and schedules, checklist items                          |
| [Groups](https://docs.snapfix.com/engineering-reference/api/groups.md)               | api\_php\_live\_v2, php-apis, apipy                                        | Groups, group settings and statuses                                                               |
| [Rooms](https://docs.snapfix.com/engineering-reference/api/rooms.md)                 | api\_php\_live\_v2, php-apis                                               | Rooms, areas and room status                                                                      |
| [Housekeeping](https://docs.snapfix.com/engineering-reference/api/housekeeping.md)   | api\_php\_live\_v2, php-apis, ops\_dashboard\_be                           | Housekeeping tasks, assignment, working hours, housekeeping reports                               |
| [Assets](https://docs.snapfix.com/engineering-reference/api/assets.md)               | api\_php\_live\_v2, php-apis                                               | Asset registers, assets and their attributes                                                      |
| [Compliance](https://docs.snapfix.com/engineering-reference/api/compliance.md)       | api\_php\_live\_v2, php-apis                                               | Compliance systems, contractors, documents, overviews and timelines                               |
| [Reports](https://docs.snapfix.com/engineering-reference/api/reports.md)             | api\_php\_live\_v2, php-apis, apipy, ops\_dashboard\_be                    | Dashboards, analytics, reports, exports and wallboards                                            |
| [Console](https://docs.snapfix.com/engineering-reference/api/console.md)             | api\_php\_live\_v2, php-apis, authpy                                       | Site details and settings, multi-sites and their users and permissions                            |
| [Billing](https://docs.snapfix.com/engineering-reference/api/billing.md)             | api\_php\_live\_v2, php-apis, apipy, authpy                                | Packages, Stripe subscriptions and webhooks, billing addresses, the paywall                       |
| [Integrations](https://docs.snapfix.com/engineering-reference/api/integrations.md)   | api\_php\_live\_v2, php-apis, apipy, nine PMS services, deputy\_py\_server | PMS integrations and their services, Guestline setup, the D3x inbox                               |
| [Notifications](https://docs.snapfix.com/engineering-reference/api/notifications.md) | api\_php\_live\_v2, php-apis, apipy                                        | Push notifications, reminders, device tokens, notification settings, popups and surveys           |
| [QR](https://docs.snapfix.com/engineering-reference/api/qr.md)                       | api\_php\_live\_v2, php-apis, authpy                                       | QR forms and group QR codes                                                                       |
| [AI](https://docs.snapfix.com/engineering-reference/api/ai.md)                       | api\_php\_live\_v2, php-apis, snapfix\_ai\_agent, aitask\_pyserver         | Task suggestions, the AI suggestion service, Simon, chatbot and voice tasks                       |
| [Help](https://docs.snapfix.com/engineering-reference/api/help.md)                   | api\_php\_live\_v2, php-apis                                               | Help hub articles and help entries                                                                |
| [Staff](https://docs.snapfix.com/engineering-reference/api/staff.md)                 | api\_php\_live\_v2, php-apis, apipy, authpy                                | The admin API and admin actions, company metrics, CRM links, logs, server dashboards              |
| [Auth](https://docs.snapfix.com/engineering-reference/api/auth.md)                   | api\_php\_live\_v2, php-apis, apipy, authpy                                | Sign-in, tokens, SSO, registration, passwords and verification codes                              |
| [Users](https://docs.snapfix.com/engineering-reference/api/users.md)                 | api\_php\_live\_v2, php-apis, apipy, authpy                                | Adding, inviting, blocking and listing users, site and group membership                           |
| [Tags](https://docs.snapfix.com/engineering-reference/api/tags.md)                   | api\_php\_live\_v2, php-apis                                               | Tags, tag folders and task tags                                                                   |
| [Files](https://docs.snapfix.com/engineering-reference/api/files.md)                 | api\_php\_live\_v2, php-apis                                               | Uploads and the upload folders                                                                    |
| [Reference](https://docs.snapfix.com/engineering-reference/api/reference.md)         | api\_php\_live\_v2, php-apis, authpy                                       | Countries, currencies, time zones, translations and other lookup data                             |
| [Open API](https://docs.snapfix.com/engineering-reference/api/open-api.md)           | api\_php\_live\_v2, apipy                                                  | The public API, the vendor API, apipy's task API, and `/v1/sdk`                                   |
| [Internal](https://docs.snapfix.com/engineering-reference/api/internal.md)           | api\_php\_live\_v2                                                         | api\_php\_live\_v2's `/v1/internal` routes for other Snapfix services                             |

## Services and hosts

Four backends serve the apps. Every endpoint belongs to one of them, and each group doc names the ones it uses.

| Service           | Stack                                   | Production               | Staging        | Test           |
| ----------------- | --------------------------------------- | ------------------------ | -------------- | -------------- |
| `api_php_live_v2` | Laravel 10 on PHP 8.2                   | `https://z4.snapfix.com` | `y4.s6eur.com` | `b4.s6eur.com` |
| `php-apis`        | plain PHP, one dispatcher per front end | `https://z1.snapfix.com` | `y1.s6eur.com` | `b1.s6eur.com` |
| `apipy`           | Flask 3                                 | `https://z2.snapfix.com` | `y2.s6eur.com` | `b2.s6eur.com` |
| `authpy`          | Flask 3, sign-in and tokens             | `https://z3.snapfix.com` | `y3.s6eur.com` | `b3.s6eur.com` |

* `api_php_live_v2` has no `/api` prefix. Its route groups are `/v1/app` (the apps), `/v1/admin` (staff), `/v1/guest` (no sign-in), `/v1/public` (the customer API), `/v1/xvendor` (the vendor API), `/v1/payment`, `/v1/qr`, `/v1/sdk`, `/v1/internal` (other Snapfix services) and the D3x webhook routes, plus `/docs` for the API docs (api\_php\_live\_v2 @ ef3c4319f6, `app/Providers/RouteServiceProvider.php:21-126`).
* `php-apis` has two dispatchers: `html/api/snapfix/index.php` for the mobile apps, and `html/api/snapfix/web/index.php` for the web actions. About half of the web dispatcher's action labels start with `webcust_` (126 of 242). One endpoint per `?action=` value. Both dispatchers lower-case the action name. A request without an action answers `400` "Bad request", and an unknown action answers `200` with `result: false` and "INVALID REQUEST" (php-apis @ 238ca4414e, `html/api/snapfix/index.php:50-56`, `:4344-4346`; `html/api/snapfix/web/index.php:75`, `:83`, `:2525`).
* `apipy` has no prefix. Versions are path prefixes (`/v3`, `/v4`, `/v5`, `/v1/task`) or suffixes (`-v2`), and old versions stay live next to new ones (apipy @ 0e83c85e5a, `app.py:2819` for `/v4/parents`, `:2870` and `:2907` for `/v4/` and `/v5/<user_uuid>/jobs`, `:3756` for `/v1/task`).
* A per-site host override exists only on Android. Android swaps its `apiphp` and `apipy` hosts for the selected site's `php_base_url` and `py_base_url` (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/repository/ApiEndPointsRepository.kt:51-70`). php-apis fills those from the server settings `REGION_URL_PHP` and `REGION_URL_PY`, the same for every site (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:2421-2422`); their production values are not in any repo \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. The web reads the site's `base_urls`, which api\_php\_live\_v2 always sends as empty strings, so it keeps its default hosts (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Resources/v1/ParentResource.php:60-63`; web\_app\_v2 @ 0989b8e685, `src/app/services/account/account-helper/account-helper.service.ts:236-237`). iOS has the swap commented out (ios @ aa31967ac8, `APIManagers/ApiEndpointManager.swift:36-41`).

What the staging data is and how it differs from production is in [infrastructure](https://docs.snapfix.com/engineering-reference/infra.md). Sign-in itself is in the [Auth group](https://docs.snapfix.com/engineering-reference/api/auth.md).

## Authentication

Callers authenticate in five ways. Each endpoint's doc says which one it takes.

| Kind               | How                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Used by                                                                                 |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| User token         | `Authorization: Bearer <access token>`, an authpy access token                                                                                                                                                                                                                                                                                                                                                                                                                                    | Every app and web page after sign-in                                                    |
| Refresh token      | `Authorization: Bearer <refresh token>` to `POST /refresh` or `/refresh-v2` on authpy                                                                                                                                                                                                                                                                                                                                                                                                             | The apps and the web, when an access token expires                                      |
| Admin token        | `Authorization: Bearer <JWT>` on `/v1/admin`, checked with its own setting, `ADMIN_JWT_SECRET` (api\_php\_live\_v2 @ ef3c4319f6, `config/jwt.php:16`); the user must have `fSnapfixWebAdminUser` (`app/Http/Middleware/WebAdmin.php:23`). authpy signs every token with one key, so whether the admin setting holds that same key is open \[[ASK-202](https://github.com/snapfix/docs/blob/main/ASK.md#ask-202-does-the-laravel-admin-api-check-tokens-with-the-key-that-authpy-signs-them-with)] | The staff admin app                                                                     |
| API key            | `X-API-Key` header (`app/Http/Middleware/AuthorizePublicApi.php:36-40`)                                                                                                                                                                                                                                                                                                                                                                                                                           | Customers' and vendors' own systems (`/v1/public`, `/v1/xvendor`)                       |
| Shared Basic login | `Authorization: Basic ...` with credentials that ship inside the apps, or one shared credential pair                                                                                                                                                                                                                                                                                                                                                                                              | Guest and no-login endpoints, PMS integrations, the scripts routes under `/v1/internal` |

### User tokens

* authpy issues them. `POST /login`, `/login-with-otp` and the SSO routes (`/sso-apple`, `/sso-google`, `/sso-azure`) return an `access_token` and a `refresh_token` for the user's UUID (authpy @ 5d5758661c, `app.py:390`, `:733`, `:1647`, `:1664`, `:1686`; `auth.py:105-107`). `/login-v3` returns no tokens: it answers success to any request (`app.py:451-461`).
* The token is HS256. `api_php_live_v2` checks it with the setting for the route group it arrives at, such as `APP_JWT_SECRET` for `/v1/app` (`app/Services/JwtAuthService.php:29`, `config/jwt.php:13-17`), and has separate settings for its admin, payment, QR and SDK tokens; the SDK one falls back to a fixed value written in the code. authpy and apipy use `SECRET_KEY` from their settings. The code names a fallback, but the settings helper never returns it, so a missing value stops the service at start-up (authpy @ 5d5758661c, `app.py:94`, `model/utils.py:284-288`; apipy @ 0e83c85e5a, `app.py:142`, `model/utils.py:298-302`).
* Claims: the user's UUID (`identity` or `sub`), `type` (`access` or `refresh`), `fresh` (set only on tokens from sign-in, for example authpy `app.py:425`, `:826`), and `user_claims` with `logged_in_with` (`email`, `mobile`, `sso_apple`, `sso_google`, `sso_azure`), `has_email`, `has_mobile`, `email_verified`, `mobile_verified`, `verification_required`, `temp_password`, `temp_password_required`, `admin_temp_password`, and `exc_parents` (sites the user is blocked from, also from the caller's device) when there are any (`auth.py:75-107`).
* Lifetime: set by `ACCESS_TOKEN_VALIDITY_IN_SECS` and `REFRESH_TOKEN_VALIDITY_IN_SECS` in authpy's `security.json`, which is not in any repo \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. When a setting is missing, the code uses 10 minutes for access tokens and 1 hour for refresh tokens (`auth.py:75`, `:144`).
* Refreshing: `POST /refresh` takes the refresh token and returns a new `access_token` (`app.py:171-200`). `POST /refresh-v2` returns a new access and refresh token (`app.py:217-228`). Both check the IP and abuse rules before refreshing. `/refresh-v2` first checks that the token names a user, and answers `409` "invalid user" when it does not (`app.py:224-225`). A refreshed access token is not fresh (`app.py:188`, `:196`).
* Token errors on `api_php_live_v2`: `401` for a missing, expired, badly signed, not-yet-valid or non-access token, and on `/v1/app` also for a blocked token, "Unauthorized access" (`app/Http/Middleware/VerifyTempPassword.php:46-54`, `:72-73`; `app/Services/JwtAuthService.php:31-32`; `app/Http/Middleware/BlockedToken.php:41-44`, `:50`; `app/Http/Middleware/AuthorizeAdminApi.php:45-51`, `:64-65`). A token the JWT library cannot read gets `400` "Something went wrong" instead, as does an admin token whose user lacks the staff flag (`VerifyTempPassword.php:76-77`; `AuthorizeAdminApi.php:66-67`; `app/Http/Middleware/WebAdmin.php:22-28`). The `/v1/sdk` group decodes no token at all.
* The mobile php-apis dispatcher answers `401` "The incoming token has expired" for an expired token, `401` "Wrong number of segments" for a token without three parts, `401` "invalid user!" for a token that names no valid user, and `200` with `result: false` for other token errors (php-apis @ 238ca4414e, `html/api/snapfix/index.php:383-433`). The web dispatcher answers `401` "Access token expired" for an expired token and `200` "Authentication Failed" for other errors (`html/api/snapfix/web/index.php:471-506`). Both check tokens only when `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)].
* Not checked everywhere: many `php-apis` actions take the user from the request body (`user_uuid` or `uuid_tUser`), not from the token, so for them the token only proves that someone is signed in, and a signed-in caller can act as another user by naming that user. Some actions read the user from the token instead, through `getUserUUIDFromToken` (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:27295`). The `/v1/sdk` group reads the user from a request field for the same reason. Some endpoints check nothing beyond the token.

### What a user token does not prove

`api_php_live_v2` loads the caller and their group permissions on every `/v1/app` request (`app/Http/Middleware/Authorize.php:41-48`, `app/Services/UserAssetBusinessService.php:394-412`), then each controller or policy checks the site, group or task in question. The other backends check less, and their group docs say where: `php-apis` task actions check nothing about the task or group, and `apipy`'s reminder routes work on any task. Treat "signed in" and "allowed" as different questions.

`api_php_live_v2` also stops two states before the handler runs:

* **Temporary password:** `428` with a message, except on six routes: showing and deleting the user's profile, generating and verifying a code, starting the app, and updating the password. SSO sign-ins are exempt (`app/Http/Middleware/VerifyTempPassword.php:20-27`, `:59-66`).
* **Verification required:** `409` when the site requires a verified email or phone and the user signed in with the unverified one. SSO sign-ins are exempt (`app/Http/Middleware/VerifiedUser.php:70-78`).

### Basic logins

* Guest endpoints share one Basic credential that is also in the public web bundles, so it identifies the app, not a person. A wrong one answers `401` `{"error": "Unauthorized."}` (`app/Http/Middleware/AuthorizeGuestApi.php:21-27`).
* The scripts routes under `/v1/internal` use one shared credential from `config('app.auth_user_script')` and `config('app.auth_pass_script')`, and answer a wrong one the same way (`app/Http/Middleware/AuthorizeScriptsApi.php:21-27`). The [Internal group](https://docs.snapfix.com/engineering-reference/api/internal.md) says which user those routes act as.
* `php-apis` uses one Basic credential (`AUTH_USERNAME`) for the actions on each dispatcher's no-token list, and for every action while `JWT_AUTH_ENABLED` is off \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)] (`html/api/snapfix/index.php:434-457`, `:458-465`). A wrong one answers `200` with "You are not authorised to access this API." (`htmlphp/api/snapfix/config/lang/en.php:2`).
* apipy's job bridge `/g-job/<jobToken>` checks one Basic pair, `BasicAuth_UserName` and `BasicAuth_Password`, and refuses every call when they are unset, because the settings helper raises instead of returning its fallback (apipy @ 0e83c85e5a, `auth.py:28-36`, `app.py:3280-3290`, `model/utils.py:298-302`).
* PMS integrations use the integration's own Basic credential, and the request must also name the integration.

## Requests

* **Body:** JSON, urlencoded or multipart, at the client's choice. `api_php_live_v2` validation reads the query and the body together; some request classes add the path parameters (for example `app/Http/Requests/v1/HelpHubArticlesRequest.php:18`). Send `limit`, `offset` and `sortBy` in the query string: many list handlers read them only from there (`app/Traits/Job/JobActions.php:132-135`, `app/Traits/Asset/AssetActions.php:347-350`).
* **Multipart with PUT:** send it as `POST` with `_method=PUT`, which Laravel reads.
* **Headers the backends read:**
  * `Accept-Language`: `en` or `es` on `api_php_live_v2` (`config/app.php:118`, `locales`); any other value keeps English, the default locale (`config/app.php:117`; `app/Http/Middleware/Localization.php:20-26`). The web sends its language in a `locale` header instead, which no backend reads, so the web always gets English (web\_app\_v2 @ 0989b8e685, `src/app/services/http/http.service.ts:127`).
  * `X-API-Version`: `api_php_live_v2` only. Optional; defaults to `APP_VERSION` (`config/app.php:46`, `1.0.0`). A malformed value, or a version with no matching handler, gives `400`. Handlers are named `<action>_<major>_<minor>`, and the response echoes the version in the same header (`app/Http/Middleware/VersionControl.php:22-44`).
  * `device-tz-offset`: the caller's offset from UTC, such as `GMT+0100`, which date filters use. When it is absent, the filters use `GMT+0000` (`app/Traits/Filters/DueDate.php:18`).
  * `device-type`: `web`, `ios` or `android`. php-apis sets a new task's `enum_Origin` from it, unless a `forigin` header is sent: `android` sets `1`, `ios` or `apple` set `2`, `web` sets `3`, `web-admin` sets `4`, and anything else sets `0` (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:1274-1304`).
  * `device-id`: which device is calling. php-apis (which also reads `device_id`) and authpy leave out the sites where that device is blocked (`class.functions.php:29641-29661`; authpy @ 5d5758661c, `auth.py:78`, `:89-93`).
* **Any method works on `php-apis`:** the dispatchers don't check the method, except that `OPTIONS` answers `200` with `result: false` and "invalid http method" (`html/api/snapfix/index.php:231-236`). Every origin is allowed (`index.php:3`). Group docs list the method the clients send.
* **Generic table actions on `php-apis`:** many of the mobile dispatcher's `create_*`, `save_*`, `modify_*`, `delete_*` and `read_*` actions for a single table, such as `save_user_added_to_business` and `read_asset_reg`, pass the request to shared table functions and share one request shape; others with the same prefixes have their own (`html/api/snapfix/index.php:1739-1747`, `:3269-3280`). `create_*` and `save_*` take `insert_data`, an array of row objects; `modify_*` takes `update_data`, row objects with their `uuid`; `delete_*` takes `delete_data`, an array of UUIDs. `read_*` needs `uuid_tUser` and `last_updated_ts`, then takes either `uuids` (an array) or filters: every other key in the request filters on the column of that name, such as `uuid`. `max_items`, `current_max_id` and `tbl` are not filters, `last_updated_ts` keeps the rows with `fServerTs` from 5 seconds before it, and `uuid_tUser`, `uuid_tBusiness`, `fActive`, `fDeleted`, `fArchived` and `excludeFromApi` filter only when the table has that column (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:163-165`, `:749-751`, `:1456-1463`, `:1739-1741`, `:1799-1835`, `:2607-2680`).
* **Body size:** `api_php_live_v2` runs Laravel's `ValidatePostSize` on every request (`app/Http/Kernel.php:19`), so the body limit is PHP's `post_max_size`. Upload rules allow up to `FILE_MAX_SIZE` (`config/app.php:341`, default `102400` kilobytes, about 100 MB); a few routes allow 50 MB. The other backends set no body limit in their code.

## Responses

Each backend has its own envelope. Clients read all four, so a client for the whole product needs each shape.

| Service           | Success                                                                                                                 | Error                                                                                               |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `api_php_live_v2` | `{"status": "success", "message": "...", "data": ...}`                                                                  | `{"status": "error", "message": "..."}`                                                             |
| `php-apis`        | `{"result": true, "message": "...", "data": ..., "serverTs": 1700000000000}`                                            | `{"result": false, "message": "..."}`; some older actions answer `{"success": "0", "message": ...}` |
| `apipy`           | `{"result": true, "message": "success", "serverTs": ..., "data": ...}`, with `total` or `pagination` on lists           | `{"result": false, "message": "...", "serverTs": ...}`                                              |
| `authpy`          | `{"result": true, "message": "success", "serverTs": ..., "data": ...}`, and `access_token` / `refresh_token` on sign-in | `{"result": false, "message": "...", "serverTs": ...}`                                              |

**Status codes** (api\_php\_live\_v2 @ ef3c4319f6, `app/Exceptions/Handler.php:44-85`; apipy @ 0e83c85e5a, `app.py:149-184`; php-apis @ 238ca4414e, `html/api/snapfix/index.php:4348-4370`):

| Code | Meaning                                                                                                                                                                                                                                                                                                       |
| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 200  | Success, and also many errors on `php-apis`, `apipy` and `authpy`, which put the failure in `result`                                                                                                                                                                                                          |
| 400  | Bad request, a user error, a version mismatch, or a blacklisted IP, country, phone, email or user. On `api_php_live_v2`, any other exception that is not a fatal type also answers `400`, with "Something went wrong" unless `APP_DEBUG` is on (`Handler.php:84`; `app/Http/Responses/ApiResponse.php:39-53`) |
| 401  | Not signed in, or the token is bad, expired or revoked (see [User tokens](#user-tokens)); a wrong Basic login on the guest and scripts routes                                                                                                                                                                 |
| 403  | The user may not do this (`Handler.php:54-56`)                                                                                                                                                                                                                                                                |
| 404  | No such record or route (`Handler.php:46-52`)                                                                                                                                                                                                                                                                 |
| 405  | Wrong method (`apipy` `app.py:163-165`, `authpy` `app.py:127-129`)                                                                                                                                                                                                                                            |
| 406  | A fresh access token is required: on `php-apis` from the `error-406` exception (`index.php:4357-4361`), and on `api_php_live_v2`'s user routes, which also use it for an invalid user (`Handler.php:62-64`; `app/Http/Controllers/v1/Versions/v1_0/App/UserController.php:133`, `:165`, `:196`)               |
| 409  | Email or phone verification needed (`api_php_live_v2`, `VerifiedUser.php:78`); also `apipy`'s request gate (`app.py:262`), and authpy's `/refresh-v2` when the token names no user                                                                                                                            |
| 422  | Validation failed (`Handler.php:66-68`)                                                                                                                                                                                                                                                                       |
| 428  | The user has a temporary password (`api_php_live_v2` only, `VerifyTempPassword.php:74-75`)                                                                                                                                                                                                                    |
| 429  | Rate limited. On `api_php_live_v2`, only the per-route limits and the `/v1/public` and `/v1/xvendor` limiter answer `429`; the named limits on `/v1/guest` and `/v1/sdk` answer `500`                                                                                                                         |
| 500  | Server error. On `api_php_live_v2`, a fatal type: `Error`, `RuntimeException`, `ErrorException` or `LogicException` (`Handler.php:80-82`, `:117-123`), which includes the framework's own HTTP exceptions, such as a wrong method or a named rate limit                                                       |

* **Validation errors** on `api_php_live_v2` carry the first failed rule's message, with " (and N more errors)" added when more rules fail, and no field list. `app/Exceptions/Handler.php:66-68` answers a `ValidationException` with the exception's own message, which Laravel 10 (laravel/framework 10.50.2 in `composer.lock`) builds from the errors; the response built in `app/Http/Requests/v1/BaseRequest.php:18-27` is not used. The framework code is not in the clone, so the suffix rests on that version. Some messages are a translation key instead of text.
* **Debug output:** with `APP_DEBUG` on, `api_php_live_v2` errors show the exception message and add `file`, `line` and `backtrace` to the response (`app/Http/Responses/ApiResponse.php:46-50`). `authpy` and `apipy` set Flask's `DEBUG` and `TESTING` on in their source (authpy @ 5d5758661c, `app.py:65-66`; apipy @ 0e83c85e5a, `app.py:105-106`). On `apipy` that makes an error a route does not catch go up to the web server, which answers a plain `500` without the JSON envelope; apipy's own 500 handler never runs (`app.py:170-172`). A missing or unreadable token gets the token library's own answer, and only an expired one gets apipy's envelope with `401` (`app.py:181-184`).
* **Exceptions on `php-apis`** come back as `200` with `result: false` and the exception text, which can include database errors (`index.php:4348-4352`). PHP errors that aren't exceptions, such as type errors, are not caught and give a `500` without a JSON body.
* **`serverTs`:** most `php-apis` answers carry the server clock in `serverTs`, set five seconds behind real time (`index.php:4388-4389`). The missing-action answer uses the real time (`index.php:52-53`), and the `OPTIONS` answer has none.

## Blocking and rate limits

* **The abuse check runs before the handler.** On `php-apis` it runs before the token check (`html/api/snapfix/index.php:288-297`, token check at `:383`). On `apipy` and `authpy` each route runs it itself, after any token decorator on that route (for example authpy's `/refresh`, `app.py:171-178`, and apipy's `/parents`, `app.py:284-290`). It checks the caller's IP and the blacklists, and records the request. A blocked caller gets a fake success, a reference code, or an explicit block, depending on the list. `api_php_live_v2` does the same in its `blacklist` middleware, which runs after the sign-in, API-key or Basic check on every group except `/v1/admin` and `/v1/internal` (`app/Providers/RouteServiceProvider.php:34-126`). It answers `400` "There is an issue with the service you are seeking for. …" with a reference code (`app/Http/Middleware/Blacklist.php:40-84`; `lang/en/messages.php:178`).
* **Rate limits** on `api_php_live_v2` come from the `throttling_rules` table per route and return `429`, but only while the cache flag `throttlingEnabled` is on, which staff switch from the admin API (`app/Http/Middleware/RateLimiter.php:34`, `:50`). The named limits of 60 calls a minute and 1,000 a day apply only to `/v1/sdk` and `/v1/guest` (`app/Providers/RouteServiceProvider.php:95-118`, defined at `:138-149`). `/v1/public` and `/v1/xvendor` have their own limiter (`:66`, `:77`) \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)].
* **Logging:** each backend keeps a daily request log table, `apilog_YYYY_MM_DD` in the `<mode>_api_ip_logs` database. `php-apis` stores each request body there, with only the top-level `password`, `password_new` and `password_old` masked, and each answer under about 100 KB, except the answers of the eight sync loads (`read_data_v2`, `read_data_v3`, `read_businessjob_data_v2_proxy`, `read_businessjob_data_v2`, `read_businessjob_data`, `read_parent_data`, `read_parent_room_data`, `read_parent_business_data_v2`) (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/ip.functions.v3.php:796-807`, `:1368-1382`, `:1742-1767`; `html/api/snapfix/index.php:4412-4416`). Its MongoDB request log is switched off in code: `saveLog` returns at once (`htmlphp/api/snapfix/class/mongo.functions.php:128-129`). php-apis still writes passwords to `tPri_Log`. `api_php_live_v2`, `apipy` and `authpy` store each request and every answer under about 100 KB.

## Paging

Three different schemes; a client cannot assume one.

| Service                            | Parameters                                                                                                           | Defaults                                                                                                                               | Response                                                                                                                                                                                                                                                                                           |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `api_php_live_v2`                  | `limit` (page size), `offset` (page number, from 1)                                                                  | 25 and 1 (`app/Enums/PaginatorDefault.php`)                                                                                            | `pagination` with `total`, `perPage`, `currentPage`, `lastPage`, `from`, `to` (for example `app/Http/Resources/v1/BusinessCollection.php:23-30`)                                                                                                                                                   |
| `apipy` (`/v4`, `/v5` list routes) | `offset`, `limit`                                                                                                    | `limit` 200 on the task lists (`/v4/{user_uuid}/jobs`, `/v5/{user_uuid}/jobs`); 50 on `/v4/parents`, `/v4/users` and `/v4/parent-pack` | `total` beside `data` on the task lists, holding the task counts by colour, archived and not, rather than a page count (`app.py:2898-2899`, `:2946-2947`; `model/v4/feature_job.py:617-628`); `data.total_count` on the other three (`model/v4/t_parent.py:351`, `:588`; `model/v4/t_user.py:183`) |
| `php-apis`                         | Its own scheme per action: `offset` and `limit`, or `last_updated_ts`, or `volume_of_records` and `last_fModifiedTs` | per action                                                                                                                             | per action                                                                                                                                                                                                                                                                                         |

`api_php_live_v2` sets no maximum page size, so a large `limit` returns the whole list (`app/Traits/Job/JobActions.php:132-135`).

The apipy defaults are in apipy @ 0e83c85e5a, `model/v4/feature_job.py:478` (the task lists), `model/v4/t_parent.py:26` and `:449`, and `model/v4/t_user.py:25`.

## Dates and times

* **Timestamps** are epoch milliseconds, except a few `api_php_live_v2` fields that are ISO 8601 (`2026-11-01T09:00:00Z`). `serverTs` on `php-apis`, `apipy` and `authpy` is epoch milliseconds too.
* **Dates without a time** are `Y-m-d` strings.
* **Time zone:** both `php-apis` dispatchers set PHP's time zone to `Europe/Dublin`, so server dates and times there are Irish time (php-apis @ 238ca4414e, `html/api/snapfix/index.php:71`, `html/api/snapfix/web/index.php:95`). `api_php_live_v2` date filters read a date in the caller's `device-tz-offset`. Planned tasks and reminders follow the site's own time zone (see [Planner](https://docs.snapfix.com/engineering-reference/api/planner.md)).

## Files

* **Uploads** are multipart. `api_php_live_v2` reads the field `file` (`app/Http/Requests/v1/FileUploadRequest.php:15-17`) and stores it on its default disk under `img/`, `vid/`, `aud/` or `doc/`, chosen by the file's extension (`app/Helpers/common.php:160-190`); its task image route checks only the size, not the type. The php-apis upload actions read `uploaded_file` (photos, documents, videos and device databases) or, for the contacts upload `sync_cts`, `mzip`; `upload_file` (no caller) reads a field of that name. See [Files](https://docs.snapfix.com/engineering-reference/api/files.md).
* **Images sent inline:** some `php-apis` actions take a base64 image (`encoded_image_data`) and write it to disk (`htmlphp/api/snapfix/class/class.functions.php:212`, `:892`).
* The [Files group](https://docs.snapfix.com/engineering-reference/api/files.md) has the endpoints.

## Writing these docs

How to document a group, and what to log as a finding, is in the [API build prompt](https://github.com/snapfix/docs/blob/main/prompts/build/api.md). The rules that the group docs rely on:

* **A caller is a call site.** An endpoint catalog entry that no code uses is not a caller, and neither is a screen with no route or a component that no page places. The iOS `ApiEndpointManager.swift` and Android `APIEndPointUtils.java` registries, constants and uncalled client functions are not callers. Search every client repo for the path or action before writing "(no caller)".
* **Used by.** Each endpoint section starts with a **Used by** line naming its callers. An endpoint with no caller has no section; it stays in its group's table marked "(no caller)".
* **The heading method is the clients' method.** For `php-apis`, which accepts any method, the heading and the table show the method the clients send; "ANY" means no client calls it.

| Question                          | Doc                                                                                                              |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| What does it take and return?     | Its group doc, under `## METHOD /path`                                                                           |
| How does a client sign in at all? | [Auth](https://docs.snapfix.com/engineering-reference/api/auth.md), and this page for the headers                |
| What does the data mean?          | [Database](https://docs.snapfix.com/engineering-reference/db.md), one page per table                             |
| Which screen calls it?            | The screen doc in [screens](https://docs.snapfix.com/how-the-apps-work/screens.md) links to the endpoint section |


---

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