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](data-models.md) | [Next: Local Storage](local-storage.md)