platform/docs/mobile-photo-sync-api.md

Phone photo auto-backup — API contract

Written 2026-08-04, for the mobile developer. This is the server-side contract for "photos taken on the phone appear on the server automatically", i.e. what the Immich app does today.

The mobile app is not built here. This document is the boundary: everything below is either already live or explicitly listed as missing, so the app can be built against it rather than reverse-engineered from the web client.

---

The short version

Almost all of this already exists. Officer proxies a self-hosted Immich through the officer-photos sidecar, and the sidecar's route allow-list already permits the assets resource for GET POST PUT DELETE (src/servers/sidecar/photos/routes.ts:22). Immich's own upload and dedupe endpoints are therefore already reachable through Officer, with Officer's auth in front and the Immich API key never leaving the sidecar.

So the work is not "build a photo ingest service". It is: use the endpoints below, and close the three gaps at the bottom.

---

Topology

  phone app                officer                     officer-photos            Immich
  ─────────                ───────                     ──────────────            ──────
  Authorization:    →   userMiddleware (JWT)     →   allow-list by first    →   x-api-key
  Bearer <platform      createSidecarProxy           path segment +             (held ONLY
  JWT>                  injects X-Officer-User       method                     in the sidecar)

The phone holds a platform JWT — the same credential monorepo-mobile/packages/core/src/services/ api.ts:58 already sends as Authorization: Bearer <token>. It never holds an Immich key and never talks to Immich directly.

Base path for everything below: /api/photos/_officer/…, which maps to <immich>/api/…. So /api/photos/_officer/assets is Immich's POST /api/assets.

---

Endpoints

1. Is the library reachable at all

GET /api/photos/_health
→ 200 { ok: true, configured: true, account: "<label>", version: "…", ms: 42 }
→ 503 { ok: false, configured: false, error: "not connected" }
→ 502 { ok: false, configured: true, error: "…" }

configured: false means the owner has not connected an Immich account in Officer yet. Show that as a setup prompt, not an error — it is not something the app can fix.

2. Ask what the server already has ← this is what makes backup cheap

POST /api/photos/_officer/assets/bulk-upload-check
Content-Type: application/json

{ "assets": [ { "id": "<deviceAssetId>", "checksum": "<base64 sha1 of the file bytes>" }, … ] }

→ 200 { "results": [ { "id": "…", "action": "accept" | "reject", "reason": "duplicate" | …,
                       "assetId": "<existing server id, when rejected as duplicate>" }, … ] }

Call this before uploading anything. It is the difference between a backup pass costing a few KB and costing the whole camera roll. Batch generously — a few hundred ids per call.

checksum is base64-encoded SHA-1 of the raw file bytes. Not SHA-256, not hex.

3. Upload one asset

POST /api/photos/_officer/assets
Content-Type: multipart/form-data

  assetData        the file bytes (required)
  deviceAssetId    stable per-device id for this photo (required)
  deviceId         stable id for this device (required)
  fileCreatedAt    ISO 8601 (required)
  fileModifiedAt   ISO 8601 (required)
  isFavorite       "true" | "false"
  duration         for video
  livePhotoVideoId when pairing a live photo's video part

→ 201 { "id": "<asset id>", "status": "created" }
→ 200 { "id": "<existing id>", "status": "duplicate" }

deviceAssetId + deviceId is the identity pair Immich dedupes on, alongside the checksum. Keep both stable across app reinstalls if you can — if they change, the checksum still prevents duplicate files, but the server will not recognise the asset as one it has already seen from this device.

4. Albums (optional, for "put my backups in an album")

GET    /api/photos/_officer/albums
POST   /api/photos/_officer/albums                  { albumName, assetIds? }
PUT    /api/photos/_officer/albums/<id>/assets      { ids: [...] }

5. Reading the library back

GET /api/photos/_officer/assets/<id>/thumbnail?size=preview|thumbnail
GET /api/photos/_officer/assets/<id>/original
POST /api/photos/_officer/search/metadata          { … }
GET /api/photos/_officer/timeline/…

Range and If-None-Match are forwarded, so thumbnails cache and videos seek properly.

---

The backup loop the app should implement

1. Enumerate new local assets since the last successful run (by creation date, per album/bucket).
2. Compute SHA-1 for each; batch into bulk-upload-check.
3. Upload only the accept ones, one at a time, honouring a user setting for "wi-fi only".
4. Record the returned server id against the local asset id so step 1 can skip it next time.
5. On failure, retry with backoff. Do not assume a failed upload means the asset is absent — re-run the check first; a request can succeed server-side and fail on the way back.

Immich's own app does essentially this, which is the reason to match it rather than invent something.

---

Gaps — what is NOT done, and who has to close it

A. Immich is not currently connected in Officer (owner action, blocks live testing)

GET /api/photos/_health returns configured: false right now. The Immich container is running (immich_server, port 2283) but Officer has no API key stored for it — the key used to live in .env as IMMICH_API_KEY and was correctly removed when credentials moved into the sidecar's own storage.

To close: in Immich, Account Settings → API Keys → new key; in Officer, /photos → connection settings → paste URL + key. Until this is done none of the endpoints above can be tested end to end, which is why this document describes them from the code rather than from a live capture.

B. Upload bodies are fully buffered, twice (server work, needs a decision)

createSidecarProxy does await ctx.req.arrayBuffer() (create-proxy.ts:103) and the photos sidecar does it again (photos/routes.ts:93). A 4K video is therefore held in memory twice per upload. Limits are generous (server 50 GB, photos sidecar 4 GB) so nothing will fail at phone-photo sizes, but a backup pass over a large video library will make the platform's memory graph unpleasant.

The fix is to stream the body through instead of buffering, which touches the shared proxy factory and so affects every sidecar. Worth doing before heavy use; not worth blocking the app on.

C. No resumable upload (server work, needs a decision)

An interrupted upload restarts from zero. On mobile data that is a real cost for videos. Immich's own app has the same limitation, so matching it is defensible for a first version — but if it turns out to matter, this is the piece that has to be designed rather than borrowed.

---

Things deliberately not exposed

The sidecar's allow-list refuses Immich's admin/*, auth/*, oauth/*, api-keys/*, sessions/*, jobs/*, system-config/*, system-metadata/* and libraries/*. A proxy that can mint its own credentials is not a proxy. If the app genuinely needs something behind that line, it should be a decision, not a widened regex.