# foto.hanif.app — API buat AI agent

Penyimpanan foto dengan folder. Kamu bisa bikin folder, mindahin foto,
ngambil foto terbaru, dan ngeliat isi fotonya langsung.

## Autentikasi

Semua endpoint (kecuali yang ini) butuh API key:

    Authorization: Bearer foto_xxxxxxxx

Bisa juga lewat query string `?api_key=foto_xxxxxxxx` — berguna buat
iOS Shortcuts atau tool yang susah nge-set header.

Key dibikin manusia di https://foto.hanif.app → menu API Keys. Scope-nya `read` atau
`read,write`. Key ga bisa bikin key baru (biar ga beranak kalau bocor).

## Base URL

    https://foto.hanif.app/api/v1

## Cara paling cepat: ambil foto terbaru

    GET /api/v1/photos/latest
    GET /api/v1/photos/latest?n=5
    GET /api/v1/photos/latest?folder=/Klien/Acme

Balikin `photo` (yang paling baru) dan `photos` (array). Tiap foto punya
`url`. Buat nge-liat isinya, download file-nya ke disk terus baca:

    curl -sL -H "Authorization: Bearer $FOTO_KEY" \
      "https://foto.hanif.app/api/v1/photos/<id>/raw" -o /tmp/foto.jpg

Cek `agent_readable`. Kalau `false` (biasanya HEIC), convert dulu —
di macOS: `sips -s format jpeg -Z 1600 in.heic --out out.jpg`.

## Folder

    GET    /api/v1/folders
    POST   /api/v1/folders          {"path": "/Klien/Acme/Sesi 1"}
    POST   /api/v1/folders          {"name": "Acme", "parent_id": "<id>"}
    PATCH  /api/v1/folders/<id>     {"name": "...", "parent_id": "<id>|null"}
    DELETE /api/v1/folders/<id>     (ikut ngehapus isi + subfolder)

Pakai bentuk `{"path": "..."}` kalau kamu mau bikin beberapa level sekaligus —
segmen yang belum ada otomatis dibikin, yang udah ada dibiarin.

## Foto

    GET    /api/v1/photos?folder=/Klien/Acme&limit=50
    GET    /api/v1/photos?folder_id=<id>&include_sub=1
    GET    /api/v1/photos?since=<epoch_ms>&q=<cari di nama/catatan>
    GET    /api/v1/photos/<id>
    GET    /api/v1/photos/<id>/raw        → bytes file asli
    GET    /api/v1/photos/<id>/thumb      → JPEG kecil (fallback ke asli)
    GET    /api/v1/photos/<id>/download   → sama, tapi pakai Content-Disposition
    PATCH  /api/v1/photos/<id>            {"name","folder"|"folder_id","note"}
    DELETE /api/v1/photos/<id>

`folder_id: null` atau `folder: "/"` = taruh di root.

## Upload

    POST /api/v1/upload      (multipart/form-data)

Field: `file` (wajib), `thumb` (opsional, JPEG kecil), `folder` atau
`folder_id`, `name`, `note`, `source`, `taken_at` (epoch ms),
`width`, `height`.

    curl -X POST "https://foto.hanif.app/api/v1/upload" \
      -H "Authorization: Bearer $FOTO_KEY" \
      -F "file=@foto.jpg" -F "folder=/Inbox" -F "note=struk warung"

Maks 25MB. Format: jpeg, png, webp, gif, avif, heic, heif.

## Lain-lain

    GET /api/v1/me       → user + settings + scope key ini
    GET /api/v1/stats    → jumlah foto, folder, total byte, timestamp terakhir

## Catatan buat agent

- Semua timestamp epoch milidetik (UTC).
- Error selalu `{"error": "pesan"}` dengan status HTTP yang sesuai.
- `GET /api/v1/photos` default 100 item, maks 500 (`limit` + `offset`).
- Kalau user minta "cek foto yang barusan gue ambil", pakai
  `/photos/latest` — jangan nge-list semua terus nyortir sendiri.
- Sebelum bikin folder, cek `GET /api/v1/folders` dulu supaya ga bikin
  yang mirip-mirip ("Klien" vs "klien").