immish/docs/api-reference.md

API Reference

The mobile app communicates with the server through a REST API and WebSocket connection. This document covers all API endpoints used by the app.

API Service Structure

The API is organized into domain-specific sub-APIs:

API	Purpose
authenticationApi	Login, logout, session management
usersApi	User profile and settings
assetsApi	Asset CRUD operations
albumsApi	Album management
searchApi	Smart search and filters
partnersApi	Partner sharing
sharedLinksApi	External share links
activitiesApi	Comments and likes
peopleApi	Face recognition and people
memoriesApi	Memory lane feature
trashApi	Trash management
serverApi	Server info and config
oauthApi	OAuth authentication
downloadApi	Asset downloads
syncApi	Data synchronization

Authentication

Login

POST /auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password123"
}

Response:
{
  "accessToken": "jwt-token",
  "userId": "user-uuid",
  "userEmail": "user@example.com",
  "name": "John Doe",
  "isAdmin": false,
  "profileImagePath": "/path/to/image"
}

Logout

POST /auth/logout
Authorization: Bearer {token}

Response: 204 No Content

Validate Token

POST /auth/validateToken
Authorization: Bearer {token}

Response:
{
  "authStatus": true
}

Change Password

POST /auth/change-password
Authorization: Bearer {token}
Content-Type: application/json

{
  "password": "current-password",
  "newPassword": "new-password"
}

OAuth

Get OAuth Config

GET /oauth/config

Response:
{
  "enabled": true,
  "autoRegister": true,
  "autoLaunch": false,
  "buttonText": "Login with SSO"
}

Start OAuth Flow

POST /oauth/authorize
Content-Type: application/json

{
  "redirectUri": "app://oauth-callback",
  "codeChallenge": "challenge-string",
  "codeChallengeMethod": "S256"
}

Response:
{
  "url": "https://oauth-provider.com/authorize?..."
}

Complete OAuth

POST /oauth/callback
Content-Type: application/json

{
  "url": "app://oauth-callback?code=auth-code",
  "codeVerifier": "verifier-string"
}

Response:
{
  "accessToken": "jwt-token",
  "userId": "user-uuid",
  ...
}

Assets

Get All Assets

GET /assets?updatedAfter={timestamp}&updatedBefore={timestamp}
Authorization: Bearer {token}

Response:
[
  {
    "id": "asset-uuid",
    "ownerId": "user-uuid",
    "checksum": "sha1-hash",
    "fileCreatedAt": "2024-01-15T10:30:00Z",
    "fileModifiedAt": "2024-01-15T10:30:00Z",
    "type": "IMAGE",
    "originalFileName": "IMG_1234.jpg",
    "isFavorite": false,
    "isArchived": false,
    "isTrashed": false,
    "thumbhash": "base64-thumbhash",
    "exifInfo": { ... }
  }
]

Upload Asset

POST /assets
Authorization: Bearer {token}
Content-Type: multipart/form-data

Form fields:
- assetData: File binary
- deviceAssetId: Device-specific ID
- deviceId: Device identifier
- fileCreatedAt: Original creation time
- fileModifiedAt: Original modification time
- duration: Video duration (if applicable)
- isFavorite: Boolean
- isArchived: Boolean
- isVisible: Boolean

Response:
{
  "id": "asset-uuid",
  "duplicate": false
}

Get Asset Info

GET /assets/{id}
Authorization: Bearer {token}

Response: Asset object

Update Asset

PUT /assets/{id}
Authorization: Bearer {token}
Content-Type: application/json

{
  "isFavorite": true,
  "isArchived": false,
  "description": "Updated description"
}

Delete Assets

DELETE /assets
Authorization: Bearer {token}
Content-Type: application/json

{
  "ids": ["asset-uuid-1", "asset-uuid-2"],
  "force": false
}

Get Asset Thumbnail

GET /assets/{id}/thumbnail?size={thumbnail|preview}
Authorization: Bearer {token}

Response: Image binary

Get Asset Original

GET /assets/{id}/original
Authorization: Bearer {token}

Response: Original file binary

Get Video Playback

GET /assets/{id}/video/playback
Authorization: Bearer {token}

Response: Video stream

Check Duplicates

POST /assets/bulk-upload-check
Authorization: Bearer {token}
Content-Type: application/json

{
  "assets": [
    {
      "id": "device-asset-id",
      "checksum": "sha1-hash"
    }
  ]
}

Response:
{
  "results": [
    {
      "id": "device-asset-id",
      "action": "accept|reject",
      "reason": "duplicate"
    }
  ]
}

Albums

Get All Albums

GET /albums?shared={true|false}
Authorization: Bearer {token}

Response:
[
  {
    "id": "album-uuid",
    "ownerId": "user-uuid",
    "albumName": "Vacation 2024",
    "createdAt": "2024-01-15T10:30:00Z",
    "assetCount": 50,
    "shared": true,
    "albumThumbnailAssetId": "asset-uuid"
  }
]

Create Album

POST /albums
Authorization: Bearer {token}
Content-Type: application/json

{
  "albumName": "New Album",
  "assetIds": ["asset-uuid-1", "asset-uuid-2"]
}

Response: Album object

Get Album Details

GET /albums/{id}
Authorization: Bearer {token}

Response: Album object with assets

Update Album

PATCH /albums/{id}
Authorization: Bearer {token}
Content-Type: application/json

{
  "albumName": "Updated Name",
  "activityEnabled": true
}

Delete Album

DELETE /albums/{id}
Authorization: Bearer {token}

Add Assets to Album

PUT /albums/{id}/assets
Authorization: Bearer {token}
Content-Type: application/json

{
  "ids": ["asset-uuid-1", "asset-uuid-2"]
}

Remove Assets from Album

DELETE /albums/{id}/assets
Authorization: Bearer {token}
Content-Type: application/json

{
  "ids": ["asset-uuid-1", "asset-uuid-2"]
}

Add Users to Album

PUT /albums/{id}/users
Authorization: Bearer {token}
Content-Type: application/json

{
  "sharedUserIds": ["user-uuid-1"],
  "albumUserRoles": [{"userId": "user-uuid-1", "role": "editor"}]
}

Search

Smart Search

POST /search/smart
Authorization: Bearer {token}
Content-Type: application/json

{
  "query": "beach sunset",
  "page": 1,
  "size": 100,
  "type": "IMAGE"
}

Response:
{
  "assets": {
    "items": [...],
    "total": 150,
    "count": 100
  }
}

Metadata Search

POST /search/metadata
Authorization: Bearer {token}
Content-Type: application/json

{
  "originalFileName": "IMG",
  "city": "New York",
  "make": "Apple",
  "takenAfter": "2024-01-01",
  "takenBefore": "2024-12-31"
}

Get Search Suggestions

GET /search/suggestions?query={text}&type={type}
Authorization: Bearer {token}

Response:
["suggestion1", "suggestion2", ...]

Partners

Get Partners

GET /partners?direction={shared-by|shared-with}
Authorization: Bearer {token}

Response:
[
  {
    "id": "user-uuid",
    "email": "partner@example.com",
    "name": "Partner Name",
    "inTimeline": true
  }
]

Create Partnership

POST /partners/{userId}
Authorization: Bearer {token}

Response: Partner object

Update Partnership

PUT /partners/{userId}
Authorization: Bearer {token}
Content-Type: application/json

{
  "inTimeline": true
}

Remove Partnership

DELETE /partners/{userId}
Authorization: Bearer {token}

Shared Links

Create Shared Link

POST /shared-links
Authorization: Bearer {token}
Content-Type: application/json

{
  "type": "ALBUM|INDIVIDUAL",
  "albumId": "album-uuid",
  "assetIds": ["asset-uuid"],
  "allowUpload": false,
  "allowDownload": true,
  "showMetadata": true,
  "password": "optional-password",
  "expiresAt": "2024-12-31T23:59:59Z"
}

Response:
{
  "id": "link-uuid",
  "key": "share-key",
  "url": "https://server/share/share-key"
}

Get My Shared Links

GET /shared-links/me
Authorization: Bearer {token}

Response: Array of shared links

Delete Shared Link

DELETE /shared-links/{id}
Authorization: Bearer {token}

Server

Get Server Info

GET /server/info
Authorization: Bearer {token}

Response:
{
  "version": "1.2.3",
  "diskAvailable": "50 GB",
  "diskSize": "100 GB",
  "diskUsagePercentage": 50
}

Get Server Features

GET /server/features
Authorization: Bearer {token}

Response:
{
  "clipEncode": true,
  "facialRecognition": true,
  "map": true,
  "trash": true,
  "oauth": true,
  "oauthAutoLaunch": false,
  "passwordLogin": true
}

Get Server Config

GET /server/config

Response:
{
  "loginPageMessage": "Welcome",
  "trashDays": 30,
  "isInitialized": true
}

Ping Server

GET /server/ping

Response:
{
  "res": "pong"
}

Error Responses

All endpoints may return error responses:

{
  "error": "Error Type",
  "statusCode": 400,
  "message": "Detailed error message"
}

Common status codes:

• 400: Bad Request
• 401: Unauthorized
• 403: Forbidden
• 404: Not Found
• 500: Internal Server Error

---

Previous: Data Models | Next: Local Storage