immish/docs/sharing.md

Sharing

This document describes sharing functionality including share links and external sharing.

Sharing Methods

1. Shared Links - Public URLs for external sharing
2. Album Sharing - Share with other Immich users
3. External Share - System share sheet (export)

Shared Links

Creating a Shared Link

For Individual Assets

POST /shared-links

Body:
{
  "type": "INDIVIDUAL",
  "assetIds": ["asset-1", "asset-2", "asset-3"],
  "description": "Vacation photos",
  "expiresAt": "2024-12-31T23:59:59Z",
  "allowDownload": true,
  "allowUpload": false,
  "showMetadata": true,
  "password": "optional-password"
}

For Albums

POST /shared-links

Body:
{
  "type": "ALBUM",
  "albumId": "album-uuid",
  "description": "Summer 2024",
  "expiresAt": null,  // Never expires
  "allowDownload": true,
  "allowUpload": true,  // Allow contributions
  "showMetadata": false,
  "password": null
}

Shared Link Options

Option	Description
description	Link description/title
expiresAt	Expiration date (null = never)
allowDownload	Recipients can download
allowUpload	Recipients can add photos (albums only)
showMetadata	Show EXIF data
password	Password protection
slug	Custom URL slug

Shared Link URL Format

https://{server}/share/{link-id}
https://{server}/share/{custom-slug}

Link Creation UI

┌─────────────────────────────────────────────────────────────┐
│  ←  Create Shared Link                                      │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Description                                                │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ Vacation photos                                      │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  Expires                                                    │
│  [Never ▼]                                                 │
│                                                             │
│  ────────────────────────────────────────────────────       │
│                                                             │
│  Allow Download                           [Toggle: ON]      │
│  Allow Upload (albums only)               [Toggle: OFF]     │
│  Show Metadata                            [Toggle: ON]      │
│                                                             │
│  ────────────────────────────────────────────────────       │
│                                                             │
│  Password Protection                                        │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ (optional)                                           │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│                                    [Create Link]            │
└─────────────────────────────────────────────────────────────┘

Managing Shared Links

List All Links

GET /shared-links

Response:
[
  {
    "id": "link-uuid",
    "description": "Vacation photos",
    "type": "INDIVIDUAL",
    "assets": [...],
    "expiresAt": "2024-12-31T23:59:59Z",
    "allowDownload": true,
    "allowUpload": false,
    "showMetadata": true,
    "createdAt": "2024-06-01T10:00:00Z"
  }
]

Update Link

PATCH /shared-links/{id}

Body:
{
  "description": "Updated description",
  "expiresAt": "2025-01-31T23:59:59Z",
  "allowDownload": false,
  "changeExpiryTime": true
}

Delete Link

DELETE /shared-links/{id}

External Sharing (Export)

Share to Other Apps

Uses system share sheet to send assets to other apps.

Share Flow

1. User selects assets
2. Tap share button
3. For local assets: Use file directly
4. For remote assets: Download to temp folder
5. Open system share sheet
6. User selects destination app
7. Clean up temp files

Share Sheet

┌─────────────────────────────────────────────────────────────┐
│  Share via                                                  │
├─────────────────────────────────────────────────────────────┤
│  [Messages] [WhatsApp] [Email] [AirDrop] [More...]         │
├─────────────────────────────────────────────────────────────┤
│  [Copy] [Save Image] [Print] [Assign to Contact]           │
└─────────────────────────────────────────────────────────────┘

Code Flow

1. Get selected assets
2. For each asset:
   - If local: get file path
   - If remote: download to temp
3. Create share data with file list
4. Present share sheet
5. Handle completion

Album Sharing

See Albums Documentation for:

• Sharing albums with users
• User roles (viewer/editor)
• Managing shared album members

Share Intent (Receiving)

Receiving Shared Content

When other apps share to Immich:

┌─────────────────────────────────────────────────────────────┐
│  Upload to Immich                                           │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  [Preview of shared content]                                │
│  3 photos ready to upload                                   │
│                                                             │
├─────────────────────────────────────────────────────────────┤
│  Add to Album (optional)                                    │
│  [Select album...                               ▼]         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  [Cancel]                              [Upload]             │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Share Intent Flow

1. Receive share intent from system
2. Extract shared files/URIs
3. Show upload preview screen
4. User confirms upload
5. Upload assets to server
6. Optionally add to album
7. Return to source app

---

Previous: Download | Next: Partners