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

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

Uploading files, images, videos, voice recordings and documents, and the public upload folders.

* **Services:** `api_php_live_v2` at `https://z4.snapfix.com` (`/v1/app`); `php-apis` at `https://z1.snapfix.com`: actions at `/api/snapfix/index.php?action=<name>`, pages at their own path.
* **Auth:** api\_php\_live\_v2: user token, with the checks every `/v1/app` route runs ([what a user token does not prove](https://docs.snapfix.com/engineering-reference/api.md#what-a-user-token-does-not-prove)); the upload routes check no site or group, and the routes that take `parentUuid` don't check that the caller belongs to that site. php-apis: a Bearer user token when `JWT_AUTH_ENABLED` is on, and the shared Basic login when it is off ([basic logins](https://docs.snapfix.com/engineering-reference/api.md#basic-logins)) \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. When `SNAPFIX_AUTH_ENABLED` is on, the dispatcher also wants a `Snapfix` header that holds a token from [`api_token_auth`](https://docs.snapfix.com/engineering-reference/db/tables/api_token_auth.md) (php-apis @ 238ca4414e, `html/api/snapfix/index.php:356-381`). None of the file actions is on the open list (`:355`). Beyond those gates, no file action checks the caller; `save_sqlite` files its log under the `uuid_tUser` in the body. The banner pages need no login.
* **Used by:** web\_app\_v2, iOS, Android, webadmin\_angular. 8 of the 20 endpoints have a caller; the other 12 are marked "(no caller)" \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)].
* **Errors:** the envelope and codes every `/v1/app` route can return are in [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); the php-apis envelope is in [Responses](https://docs.snapfix.com/engineering-reference/api.md#responses). Each section lists its own.
* **Fields:** the multipart field for the file is `file` on `/v1/app`, `uploaded_file` on the php-apis save actions, and `mzip` on `sync_cts`.
* **Logs:** api\_php\_live\_v2 keeps each response under about 100 KB in its request log; php-apis stores each request body and each response under about 100 KB in its daily request log ([Logging](https://docs.snapfix.com/engineering-reference/api.md#blocking-and-rate-limits)).
* **Related:** the shared upload rules are in [Files](https://docs.snapfix.com/engineering-reference/api.md#files). The same `store` action as `POST /v1/app/upload` also answers `POST /v1/admin/upload` ([Staff](https://docs.snapfix.com/engineering-reference/api/staff.md)); the customer APIs have their own upload routes ([Open API](https://docs.snapfix.com/engineering-reference/api/open-api.md)). The voice task upload, `?action=upload_voice_task_file`, is in the [AI API](https://docs.snapfix.com/engineering-reference/api/ai.md#post-actionupload_voice_task_file).

| Method | Path                                                 | Service            | Purpose                                                                               |
| ------ | ---------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------- |
| POST   | [`/v1/app/upload`](#post-v1appupload)                | api\_php\_live\_v2 | Upload a file; no AI step                                                             |
| POST   | `/v1/app/upload-log`                                 | api\_php\_live\_v2 | Upload a log file; older copy of `/v1/app/upload/log` (no caller)                     |
| POST   | `/v1/app/upload-voice`                               | api\_php\_live\_v2 | Upload a voice recording without AI; older copy of `/v1/app/upload/voice` (no caller) |
| POST   | `/v1/app/upload/document`                            | api\_php\_live\_v2 | Upload a document, with the AI step when the site's document switch is on (no caller) |
| POST   | [`/v1/app/upload/image`](#post-v1appuploadimage)     | api\_php\_live\_v2 | Upload an image; AI step when the site's image switch is on                           |
| POST   | `/v1/app/upload/log`                                 | api\_php\_live\_v2 | Upload a log file (no caller)                                                         |
| POST   | `/v1/app/upload/video`                               | api\_php\_live\_v2 | Upload a video, with the AI step when the site's video switch is on (no caller)       |
| POST   | [`/v1/app/upload/voice`](#post-v1appuploadvoice)     | api\_php\_live\_v2 | Upload a voice recording; AI step when the site's voice switch is on                  |
| GET    | `/api/snapfix/email_log/`                            | php-apis           | Banner page on the `email_log` folder (no caller)                                     |
| GET    | `/api/snapfix/email_tasks_attachments/`              | php-apis           | Banner page on the `email_tasks_attachments` folder (no caller)                       |
| GET    | `/api/snapfix/qr_tasks_attachments/`                 | php-apis           | Banner page on the `qr_tasks_attachments` folder (no caller)                          |
| GET    | `/api/snapfix/report_temp_images/`                   | php-apis           | Banner page on the `report_temp_images` folder (no caller)                            |
| GET    | `/api/snapfix/reports/`                              | php-apis           | Banner page on the `reports` folder (no caller)                                       |
| ANY    | `?action=download_firebase_files`                    | php-apis           | Disabled: always answers with a fixed error (no caller)                               |
| POST   | [`?action=save_document`](#post-actionsave_document) | php-apis           | Upload a document                                                                     |
| POST   | [`?action=save_image`](#post-actionsave_image)       | php-apis           | Upload an image                                                                       |
| POST   | [`?action=save_sqlite`](#post-actionsave_sqlite)     | php-apis           | Upload a zip of the app's database with a JSON log                                    |
| POST   | [`?action=save_video`](#post-actionsave_video)       | php-apis           | Upload a video                                                                        |
| POST   | [`?action=sync_cts`](#post-actionsync_cts)           | php-apis           | Upload the phone's contacts as a zip                                                  |
| ANY    | `?action=upload_file`                                | php-apis           | Upload a file to the images bucket (no caller)                                        |

Notes on the rows with no caller (each path and action was searched for in every client and service repo):

* `upload-log` and `upload/log` take a `.txt` or `.log` file named `<user UUID>_<device UUID>_<YYYY-MM-DD>.log`, read the user and device from that name, and write the file to `mobile/<user>/<device>/<date>.log` on the private log disk (`s3-log`), replacing that day's file. They answer `data: null` (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Requests/v1/LogFileUploadRequest.php:27-47`, `app/Http/Controllers/v1/Versions/v1_0/App/FileUploadController.php:228-257`).
* `upload-voice` converts the file to M4A and answers the [file object](#file-object) with `ai` (`FileUploadController.php:208-221`).
* `upload/document` and `upload/video` work like [`/v1/app/upload/image`](#post-v1appuploadimage), with the site switches `fAiDocumentEnable` and `fAiVideoEnable` (`FileUploadController.php:86-117`, `:170-201`).
* The five banner pages print one fixed line and stop (php-apis @ 238ca4414e, `html/api/snapfix/reports/index.php:8-10`). `download_firebase_files` answers `{"result": false, "message": "Backend Operation cannot be executed!"}` (`html/api/snapfix/index.php:3117-3121`).
* `upload_file` reads the field `upload_file` and stores it like [`save_image`](#post-actionsave_image), but the dispatcher drops the result, so the answer has no link (`html/api/snapfix/index.php:3069-3070`).

What the code writes into the banner folders is in [Public folders](#public-folders).

## POST /v1/app/upload

Stores one file of an allowed type and returns its link. No AI step runs. The web app uses it for files attached in chat, tasks and account forms.

* **Auth:** user token. Any signed-in user; no site is read.
* **Used by:** web\_app\_v2, through `UploadFileHttpService.upload` and `uploadAndGetUrl` (web\_app\_v2 @ 0989b8e685, `src/app/services/upload-file/upload-file-http/upload-file-http.service.ts:23-31`, `:51-61`). Paths below are under `src/app/`:
  * `components/upload-file-dialog/upload-file-dialog.component.ts:117`
  * `pages/chat/chat-info-panel/chat-info-panel.component.ts:455`
  * `pages/chat/create-group-dialog/create-group-dialog.component.ts:287`
  * `pages/account-settings/account-settings-manage-users/account-settings-manage-user-create-dialog/account-settings-manage-user-create-dialog.component.ts:196`
  * `pages/task/task-checklist/task-checklist-details/task-checklist-media-dialog/task-checklist-media-dialog.component.ts:84`
  * `pages/chat/chat-message-box/chat-message-box.component.ts:372`, and `pages/plan/planned-task/planned-task.component.ts:268` and `:276` (both through `uploadAndGetUrl`)

**Request** (multipart)

| Name   | In   | Type | Required | Rules                                                                                                            |
| ------ | ---- | ---- | -------- | ---------------------------------------------------------------------------------------------------------------- |
| `file` | body | file | yes      | One file of a type listed below, at most `FILE_MAX_SIZE` KB (default 102400, about 100 MB; `config/app.php:341`) |

Allowed types: `jpg`, `jpeg`, `png`, `gif`; `mp4`, `mov`, `avi`, `ogg`; `webm`, `m4a`, `mp3`; `txt`, `doc`, `docx`, `xls`, `xlsx`, `pdf`, `md`, `epub`, `csv`, `json`, `eml` (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Requests/v1/FileUploadRequest.php:15-25`). The type is checked from the file's content. Any zip file also passes, because the `docx` and `xlsx` entries each allow `zip`.

**Response** `200`

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "url": "https://files.example.com/doc/3f2a9c1e4b7d8a6f.pdf"
  }
}
```

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

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `422` with the first failed rule's message, for example "The file field is required.", when the file is missing, of another type or too big.

**Side effects:**

* Stores the file on the default disk, in the folder for its extension ([File object](#file-object)). The link is a plain bucket link with no signature; whether the bucket allows reads is \[[ASK-115](https://github.com/snapfix/docs/blob/main/ASK.md#ask-115-can-compliance-documents-report-files-and-the-comply-report-be-opened-from-their-link-without-signing-in)].
* Runs no AI step and writes no database rows.

## POST /v1/app/upload/image

Stores one image sent in chat. When the site's image AI switch is on, it also runs the AI step and returns tags, a transcript and a summary. The answer waits for the AI calls.

* **Auth:** user token, as for [`/v1/app/upload`](#post-v1appupload). `parentUuid` is not checked against the caller's sites.
* **Used by:**
  * iOS: `APILaravelCall.uploadImageApicall` with the registry name `upload-laravel` and `image` added to the path (ios @ aa31967ac8, `SnapFix/Chat/ChatVC/ChatVC+Image.swift:70`, `APIManagers/APIManager.swift:2764-2800`), called from `SnapFix/Chat/Helper/ChatTaskService.swift:112` for chat photos.
  * Android: `ChatMediaUploadService.uploadImageToServer` (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/service/ChatMediaUploadService.kt:212-232`, called from `:190`), through `network/ApiService.java:601`. It also sends a `filename` part, which the route does not read.

**Request** (multipart)

| Name             | In   | Type    | Required | Rules                                                                                                                           |
| ---------------- | ---- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `file`           | body | file    | yes      | `jpg`, `jpeg`, `png` or `gif` (checked from the content); at most `FILE_MAX_SIZE` KB                                            |
| `parentUuid`     | body | string  | yes      | The site. Its `fAiImageEnable` switch decides whether the AI step runs; an unknown site skips it, and the image is still stored |
| `withTags`       | body | integer | no       | `0` or `1`. Default `1`                                                                                                         |
| `withSummary`    | body | integer | no       | `0` or `1`. Default `1`                                                                                                         |
| `withTranscript` | body | integer | no       | `0` or `1`. Default `1`                                                                                                         |

The apps send no flags. iOS sends only `file` and `parentUuid`, and Android has the flag parts commented out (`service/ChatMediaUploadService.kt:227-229`), so the defaults apply (`app/Http/Requests/v1/ImageUploadRequest.php:30-39`) \[[ASK-237](https://github.com/snapfix/docs/blob/main/ASK.md#ask-237-should-chat-photos-and-voice-notes-from-the-apps-go-to-ai-when-the-sites-switch-is-on)].

**Response** `200`, with the AI step on:

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "url": "https://files.example.com/img/9c1e4b7d8a6f0e5c.jpg",
    "metaData": {
      "originalFileName": "IMG_0042.jpg",
      "tags": ["ladder", "Room 101"],
      "transcript": "",
      "summary": "A ladder against a wall in Room 101."
    },
    "metaUrl": "https://files.example.com/img/meta/9c1e4b7d8a6f0e5c.json"
  }
}
```

`data` is a [file object](#file-object). With the AI step off, `metaData` holds only `originalFileName` and `metaUrl` is `""`. If the AI step fails, the upload still succeeds: `metaData` is `null` and `metaUrl` is `""` (`app/Http/Controllers/v1/Versions/v1_0/App/FileUploadController.php:268-306`).

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `422` when `file` or `parentUuid` is missing, the file is of another type or too big, or a flag is not `0` or `1`. An AI failure is not an error.

**Side effects:**

* Stores the image in `img/` on the default disk ([File object](#file-object)).
* Reads `fAiImageEnable` from [`tPri_SettingsParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_settingsparent.md). When it is on, sends the image to the AI provider set by `AI_PROVIDER` (default `openai`, `config/ai.php:14`) \[[ASK-176](https://github.com/snapfix/docs/blob/main/ASK.md#ask-176-which-ai-suggestion-settings-and-logins-does-production-use)]: one call each for the tags, the transcript and the summary, in that order, each only when its flag is `1` (`app/Services/AI/AIService.php:17-31`). The OpenAI provider returns an empty transcript for a file that is neither audio nor video (`app/Services/AI/Providers/OpenAIService.php:92-100`). Whether the customer terms cover sending photos to AI providers is \[[ASK-177](https://github.com/snapfix/docs/blob/main/ASK.md#ask-177-do-the-customer-terms-cover-sending-task-text-photos-recordings-and-chats-to-ai-providers)].
* Writes `img/meta/<name>.json` with `originalFileName`, the tags, the transcript and the summary, only when the AI step succeeds (`FileUploadController.php:314-337`).
* Writes no database rows. The request log keeps the answer when it is under about 100 KB.

## POST /v1/app/upload/voice

Stores one voice recording. WebM is converted to M4A first. When the site's voice AI switch is on, it runs the same AI step as the image route, using `fAiVoiceEnable`.

* **Auth:** user token, as for [`/v1/app/upload`](#post-v1appupload). `parentUuid` is not checked against the caller's sites.
* **Used by:**
  * web\_app\_v2: `components/voice-recording-dialog/voice-recording-dialog.component.ts:198` and `components/media-sketch-tool/media-sketch-tool-audio/media-sketch-tool-audio.component.ts:241` (under `src/app/`), through `UploadFileHttpService.uploadAudio` (`services/upload-file/upload-file-http/upload-file-http.service.ts:33-49`), which sends the three flags as `1`.
  * iOS: `SnapFix/Chat/ChatVC/ChatVC+VoiceChat.swift:133`, through `uploadFileApicall` with `upload-laravel` and `voice` added to the path (`APIManagers/APIManager.swift:2684-2725`), which sends `file` and `parentUuid` and no flags.
  * Android: `ChatMediaUploadService.uploadVoiceToServer` (`service/ChatMediaUploadService.kt:266-290`, called from `:189`), through `network/ApiService.java:605`; its flag parts are commented out.

**Request** (multipart)

| Name                                        | In   | Type    | Required | Rules                                                                                                                                      |
| ------------------------------------------- | ---- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `file`                                      | body | file    | yes      | `webm`, `m4a`, `mp3` or `mp4` (checked from the content); at most `FILE_MAX_SIZE` KB (`app/Http/Requests/v1/AudioUploadRequest.php:12-22`) |
| `parentUuid`                                | body | string  | yes      | The site. Its `fAiVoiceEnable` switch decides whether the AI step runs                                                                     |
| `withTags`, `withSummary`, `withTranscript` | body | integer | no       | `0` or `1`. Default `1` each                                                                                                               |

**Response** `200`, with the AI step on:

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "url": "https://files.example.com/aud/2f6e1d0c9b8a7f6e.m4a",
    "metaData": {
      "originalFileName": "voice-note.m4a",
      "tags": ["store room"],
      "transcript": "The ladder is back in the store room.",
      "summary": "Ladder returned to the store room."
    },
    "metaUrl": "https://files.example.com/aud/meta/2f6e1d0c9b8a7f6e.json"
  }
}
```

`metaData` and `metaUrl` behave as on [`/v1/app/upload/image`](#post-v1appuploadimage). For a WebM upload, `originalFileName` is the name the converter gave the M4A file, not the name the client sent (`app/Services/MediaService.php:45-56`).

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `422` when `file` or `parentUuid` is missing, the file is of another type or too big, or a flag is not `0` or `1`.

**Side effects:**

* A file with the `webm` extension or the `audio/webm` type is converted to M4A (AAC) inside the request, before the AI step and the upload (`FileUploadController.php:143-145`, `app/Services/MediaService.php:25-28`). The converted copy is written to `storage/app/public/` and never deleted (`MediaService.php:49-55`).
* Stores the file in `aud/` (`webm`, `m4a`, `mp3`) or `vid/` (`mp4`) ([File object](#file-object)).
* Reads `fAiVoiceEnable` from [`tPri_SettingsParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_settingsparent.md). When it is on, runs the AI step before it answers, as on the image route \[[ASK-177](https://github.com/snapfix/docs/blob/main/ASK.md#ask-177-do-the-customer-terms-cover-sending-task-text-photos-recordings-and-chats-to-ai-providers)], and writes the metadata file under the folder's `meta/`.
* Writes no database rows. The request log keeps the answer when it is under about 100 KB.

## POST ?action=save\_image

Stores one image in the images bucket and returns its public link. No AI step and no metadata. The apps use it for task, profile, site, schedule, wallboard and chat group photos; the staff app uses it for marketing popup images.

* **Auth:** the php-apis gates in the intro. The action names no user and checks none.
* **Used by:**
  * iOS (ios @ aa31967ac8): `Managers/TaskManager.swift:4076`, `:4141`, `:4216`, `:4260`, `:4316`, `:4374`; `SnapFix/New Profile/Profile/ViewModels/ProfileViewModel.swift:267`; `SnapFix/ParentSwither/Edit Parent/ManageAccountVC.swift:261`; `SnapFix/CreateScheduleVC.swift:3314`; `SnapFix/WallboardVC.swift:706`; `SnapFix/MySettingsVC.swift:1589`; and `SnapFix/Chat/ChatVC/ChatVC+Image.swift:78` (chat group pictures, the `withMetaData: false` branch). All send `POST` through `URLConnectionHandler.postMultiPart` (`SVProgressHUD/URLConnectionHandler.swift:74-97`).
  * Android (android @ 86068bfeea, paths under `app/src/main/java/gmail/com/snapfixapp/`): `viewModels/ChatGroupViewModel.kt:578-590` (through `network/ApiService.java:393`); `activity/MyProfileActivity.kt:1878-1881`, `activity/ScheduleTaskActivity.java:3988-3994`, `fragment/JobChatFragment.java:6722-6726` and `fragment/ParentAccountDetailFragment.kt:450-457`; `data/remote/api/SyncRemoteDataSource.kt:65`, called by `data/repository/ImageSyncCoordinator.kt:215`, `:393` and `:421`.
  * webadmin\_angular: `ImageService.saveImage` (webadmin\_angular @ db972390b8, `src/app/services/image/image.service.ts:18-20`), called from `src/app/pages/marketing-popup/components/marketing-popup-modal/marketing-popup-modal.component.ts:279`.

**Request** (multipart)

| Name            | In   | Type | Required | Rules                                                                                                                                                                                                                                                                                  |
| --------------- | ---- | ---- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uploaded_file` | body | file | yes      | Any file type; no type check runs. At most `MAX_UPLOADERSIZE` bytes, a value set in each server's environment (`htmlphp/api/snapfix/config/constant_dev.php:43`) \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)] |

Other fields are ignored.

**Response** `200`

```json
{
  "success": "1",
  "message": "File uploaded successfully!",
  "image_url": "https://images.example.com/image/5f8d0c3e-9a1b-4c2d-8e7f-6a5b4c3d2e1f.jpg",
  "serverTs": 1731628800123
}
```

`success` is the string `"1"`, and there is no `result` key. `image_url` is present only on success.

**Errors:** this action answers `200` with `"success": "0"` and a message (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:3041-3066`; `html/api/snapfix/index.php:4353-4355`):

* a missing `uploaded_file`: "Something wrong with the parameters!";
* a file over the limit: "Max upload size of N bytes reached!", where N is `MAX_UPLOADERSIZE` (`htmlphp/api/snapfix/config/constant_dev.php:63`);
* an empty file: "Access denied, upload a file to process!"; any other exception: its message.

The token and login failures use the dispatcher's own answer with `result` `false` (see [Authentication](https://docs.snapfix.com/engineering-reference/api.md#authentication)).

**Side effects:**

* Stores the file in the images bucket as `image/<random UUID>.<ext>`, keeping the client's extension, with the `public-read` ACL (`html/api/snapfix/s3.php:82-157`). Anyone with the link can open it. Whether these links are meant to be public is \[[ASK-235](https://github.com/snapfix/docs/blob/main/ASK.md#ask-235-should-photos-documents-and-device-database-copies-uploaded-through-php-apis-be-readable-by-anyone-with-the-link)].
* Writes no database rows and runs no AI step.

## POST ?action=save\_document

Stores one document in the documents bucket under a new random folder and returns its public link. The apps use it for task and scheduled-task attachments.

* **Auth:** as for [`?action=save_image`](#post-actionsave_image).
* **Used by:**
  * iOS: `Managers/TaskManager.swift:3871` (`postFileToServer`); `SnapFix/CreateScheduleVC.swift:3328`.
  * Android (paths under `app/src/main/java/gmail/com/snapfixapp/`): `activity/ScheduleTaskActivity.java:4056-4070`; `data/repository/ImageSyncCoordinator.kt:546-549`. Both post through `utils/MultipartUtility.java`.

**Request** (multipart)

| Name            | In   | Type | Required | Rules                                                                                                                                                                                     |
| --------------- | ---- | ---- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uploaded_file` | body | file | yes      | Any file type; no type check runs. At most `MAX_UPLOADERSIZE` bytes \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)] |

**Response** `200`

```json
{
  "success": "1",
  "message": "File uploaded successfully!",
  "doc_url": "https://documents.example.com/file/0b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e/room-101-check.pdf",
  "serverTs": 1731628800123
}
```

**Errors:** the same shape and messages as [`?action=save_image`](#post-actionsave_image) (`htmlphp/api/snapfix/class/class.functions.php:2978-3008`).

**Side effects:**

* Stores the file as `file/<new folder UUID>/<file name>` in the documents bucket with the `public-read` ACL (`html/api/snapfix/s3.php:82-157`). The file name is the one the client sent, unchanged \[[ASK-235](https://github.com/snapfix/docs/blob/main/ASK.md#ask-235-should-photos-documents-and-device-database-copies-uploaded-through-php-apis-be-readable-by-anyone-with-the-link)].
* Writes no database rows and runs no AI step.

## POST ?action=save\_video

Stores one video in the back-office bucket and returns its link. The apps use it when they sync task media.

* **Auth:** as for [`?action=save_image`](#post-actionsave_image).
* **Used by:**
  * iOS: `Managers/TaskManager.swift:4045-4048` (`uploadVideo`, called from `:3948` and `:4014`).
  * Android: `data/remote/api/SyncRemoteDataSource.kt:78`, called by `data/repository/ImageSyncCoordinator.kt:260` and `:306`, through `network/ApiService.java:533`. It also sends a `filename` part, which the action does not read.

**Request** (multipart)

| Name            | In   | Type | Required | Rules                                                                                                                                                                                     |
| --------------- | ---- | ---- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uploaded_file` | body | file | yes      | Any file type; no type check runs. At most `MAX_UPLOADERSIZE` bytes \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)] |

**Response** `200`

```json
{
  "result": true,
  "message": "File uploaded successfully!",
  "data": {
    "video_url": "https://bo.example.com/vid/1731628800_walkthrough.mp4"
  },
  "serverTs": 1731628800123
}
```

This action answers with `result` (a boolean), not `success`.

**Errors:** `200` with `"result": false` and a message: "Something wrong with the parameters!" for a missing file, the size message for an oversized file, or the exception text (an empty file, a failed bucket write) (`htmlphp/api/snapfix/class/class.functions.php:3010-3039`).

**Side effects:**

* Stores the file as `vid/<server time in seconds>_<file name>` in the back-office bucket (`html/api/snapfix/s3.php:159-182`). The object has no ACL, so the bucket's own settings decide whether its link opens \[[ASK-115](https://github.com/snapfix/docs/blob/main/ASK.md#ask-115-can-compliance-documents-report-files-and-the-comply-report-be-opened-from-their-link-without-signing-in)].
* Writes no database rows and runs no AI step.

## POST ?action=save\_sqlite

The apps send a zip they build from their local database, with a JSON device log, so the team can diagnose problems. The server stores the zip and writes one log row. The answer has no link.

* **Auth:** as for [`?action=save_image`](#post-actionsave_image). The action takes the user from the body (`uuid_tUser`), not from the token, so a caller can file an upload under another user's ID.
* **Used by:**
  * iOS: `SnapFix/New Profile/Profile/ProfileVC+Version.swift:39`, which calls `sendDBToServer` and `saveAPICall` (`:61-99`); `SnapFix/SideMenuVC.swift:387-411`; `SnapFix/MySettingsVC+Sidemenu.swift:172-213`.
  * Android (paths under `app/src/main/java/gmail/com/snapfixapp/`): `activity/MyProfileActivity.kt:2399-2402`; `activity/BusinessListingActivity.java:1189-1193`.

**Request** (multipart)

| Name            | In   | Type   | Required | Rules                                                                                                                                                                                      |
| --------------- | ---- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `uploaded_file` | body | file   | yes      | The zip. Any file type is accepted. At most `MAX_UPLOADERSIZE` bytes \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)] |
| `uuid_tUser`    | body | string | yes      | The user the log is filed under. Must not be blank; not checked against the token                                                                                                          |
| `json_log`      | body | string | yes      | JSON text with the device details. It must decode to a non-empty object or list                                                                                                            |

**Response** `200`

```json
{
  "result": true,
  "message": "File uploaded successfully!",
  "serverTs": 1731628800123
}
```

**Errors:** `200` with `"result": false` and one of: "invalid parameters" (a field is missing or blank), "invalid json\_log" (the JSON is not a non-empty object or list), the size message, or the exception text (an empty file, a failed bucket write) (`htmlphp/api/snapfix/class/class.functions.php:13417-13459`).

**Side effects:**

* Stores the zip as `sqlite/<random UUID>.<ext>` in the documents bucket with the `public-read` ACL (`html/api/snapfix/s3.php:82-157`). Anyone with the link can download the copy of the database \[[ASK-235](https://github.com/snapfix/docs/blob/main/ASK.md#ask-235-should-photos-documents-and-device-database-copies-uploaded-through-php-apis-be-readable-by-anyone-with-the-link)].
* Inserts one row in [`tPri_Log`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log.md): a new `uuid`; `uuid_tUser`, `uuid_tUser_CreatedBy` and `uuid_tUser_ModifiedBy` from the body; `fLogMessage`, the `json_log` fields plus `uuid_tUser` and `file_url` (the zip's link); `fDeleted` `0`; and the created, modified and server times (`class.functions.php:13440-13443`).

## POST ?action=sync\_cts

Stores the phone's contacts as a zip in the contacts bucket. The apps send it every 30 days once contacts access is allowed.

* **Auth:** as for [`?action=save_image`](#post-actionsave_image). The action names no user and checks none.
* **Used by:**
  * iOS: `APIManager.uploadContactZipWith` (`APIManagers/APIManager.swift:2339-2341`), called from `Managers/ContactManager.swift:204`.
  * Android: `service/UserDataUploadService.java:292-303`, through `network/ApiService.java:428`.

**Request** (multipart)

| Name    | In    | Type    | Required | Rules                                                                                                                                                                                      |
| ------- | ----- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `mzip`  | body  | file    | yes      | The zip. Any file type is accepted. At most `MAX_UPLOADERSIZE` bytes \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)] |
| `debug` | query | integer | no       | `1` adds `url` to the answer                                                                                                                                                               |

**Response** `200`

```json
{
  "result": true,
  "message": "File uploaded successfully!",
  "serverTs": 1731628800123
}
```

With `?debug=1` the answer also has `url`, which holds the object's key (the zip's file name), not a link (`html/api/snapfix/s3.php:468-477`).

**Errors:** `200` with `"result": false` and "Something wrong with the parameters!" for a missing `mzip`, the size message for an oversized file, or the exception text (`htmlphp/api/snapfix/class/class.functions.php:40705-40729`).

**Side effects:**

* Stores the zip in the contacts bucket under the file name the client sent, with no prefix and no ACL (the ACL line is commented out), so the object is private unless the bucket says otherwise (`html/api/snapfix/s3.php:451-478`). A later upload with the same name replaces it.
* Writes no database rows and runs no AI step.

## File object

The `data` of the `/v1/app` upload routes (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Resources/v1/FileResource.php:14-26`).

| Field      | Type             | Meaning                                                                                                                                                                                                                                                       |
| ---------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `url`      | string           | Link to the stored file                                                                                                                                                                                                                                       |
| `metaData` | object or `null` | On the image, voice, video and document routes. Has `originalFileName`; adds `tags` (an array), `transcript` and `summary` (strings, empty when their flag is `0`) when the AI step ran; `null` when the AI step failed. Not present on `POST /v1/app/upload` |
| `metaUrl`  | string           | Link to the metadata JSON file; `""` when there is none. Not present on `POST /v1/app/upload`                                                                                                                                                                 |
| `ai`       | object           | Only on the old `POST /v1/app/upload-voice` (no caller): `image`, `title` and `transcript`, all `""`                                                                                                                                                          |

Where the file goes (`app/Helpers/common.php:160-191`):

| Extension (the one the client sent) | Folder                                                 |
| ----------------------------------- | ------------------------------------------------------ |
| `jpg`, `jpeg`, `png`, `gif`         | `img/`                                                 |
| `mp4`, `mov`, `avi`, `ogg`          | `vid/`; an `mp4` sent to the voice route goes here too |
| `mp3`, `m4a`, `webm`                | `aud/`                                                 |
| anything else, including zip files  | `doc/`                                                 |

The file name is a random name plus the extension. Files go to the default disk, `s3-bo` unless `FILESYSTEM_DISK` says otherwise. Its visibility is `private` in the config (`config/filesystems.php:16`, `:49-61`), but the link is a plain bucket link, `https://<bucket>/<folder>/<name>.<ext>`. Whether the bucket allows reads is \[[ASK-115](https://github.com/snapfix/docs/blob/main/ASK.md#ask-115-can-compliance-documents-report-files-and-the-comply-report-be-opened-from-their-link-without-signing-in)].

## Public folders

The folders below sit under the php-apis web root (`html/api/snapfix/`). Each holds an `index.php` that prints a banner and stops, which is what the GET rows in the table return. The code writes files into some of them:

* `email_log/`: only `html/api/snapfix/phpmailer_helper.php:21` writes here, and the mail helper's call to it is commented out (`html/api/snapfix/seshelper.php:23-24`).
* `email_tasks_attachments/`: `createJobFromEmail` (the `email_task` action) saves each mail attachment here, uploads it to S3, then deletes the folder (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:22871-22906`). If an error stops it before the delete, the attachment stays.
* `qr_tasks_attachments/`: `createJobFromQR` (the `qr_task` action) does the same with each decoded photo (`class.functions.php:23212-23275`).
* `report_temp_images/`: the report classes write temporary images here, for example `htmlphp/api/snapfix/class/business_job_report_v4.php:16`.
* `reports/`: report files are written here, uploaded, and kept. The bucket copies are public.


---

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