Connect your self-hosted Immich instance to Journiv to effortlessly capture the story behind your photos and videos.

Journiv seamlessly integrates with Immich, the self-hosted photo and video management solution. This integration allows you to browse your Immich library directly within Journiv and attach memories to your journal entries without manually downloading and re-uploading files.

What You Can Do

Browse your Immich library: View your photos and videos arranged chronologically within the Journiv picker.
Attach media: One-click attachment of photos and videos to your entries either by linking or hard copy.
Smart syncing: Journiv keeps your library metadata in sync for fast browsing.
Secure connection: direct communication between your Journiv and Immich instances.

Prerequisites

To use this integration, you need:

A self-hosted Immich instance.
An API Key from your Immich account with required permissions.
Network connectivity between your Journiv instance and your Immich instance.

Setting Up or Connecting

Step 1: Get your Immich API Key

Log in to your Immich web interface.
Go to Account Settings (click your avatar in the top right).
Navigate to API Keys.
Click New API Key.
Give it a name (e.g., "Journiv Integration").
Give required permission.
Copy the generated key. Note: You won't be able to see it again!

Step 2: Configure Journiv

Open Journiv and go to Settings.
Navigate to Integrations.
Tap on Immich.
Enter your Immich Instance URL (e.g., https://photos.mydomain.com). Journiv will automatically populate with a default if a base url has been set on your instance.
Paste your API Key.
(Optional) Expand Advanced Settings to specify a custom Album ID in link mode. By default, Journiv automatically creates and uses an album named "Journiv".
Select your desired Import Mode (see below).
Click Connect.

Journiv will verify the connection and show a "Connected" status with your Immich user ID.

Import Modes

Journiv offers two ways to handle media from Immich:

1. Link Only (Default)

How it works: Journiv stores a reference (link) to the asset on your Immich server.
Storage: Uses almost no storage space on your Journiv server.
Export: Actual media files are not present in exported zip file.
Pros: Efficient, no duplication of files.
Cons: If the file is deleted from Immich, it will disappear from Journiv. Requires the Immich server to be online to view media.

2. Copy Mode

How it works: Journiv downloads a full copy of the photo or video to its own storage.
Storage: Increases storage usage on your Journiv server.
Export: Actual media files are present in exported zip file.
Pros: Permanent archive. Even if you delete the file from Immich or turn off the server, your journal entry remains complete.
Cons: Duplicates data, requires more disk space.

You can change the Import Mode or Album ID at any time in Settings. The new mode will apply to future attachments only.

Album Integration

Journiv organizes the photos and videos you use in your entries into a dedicated album on your Immich server.

Auto-Organization: Any photo or video you attach to a journal entry (in Link Mode) is automatically added to a "Journiv" album in Immich.
Easy Review: This allows you to easily view all your journaled memories in one place within Immich.
Customization: You can specify a different Album ID in Advanced Settings if you prefer to use an existing album.
Smart Cleanup: If you remove an attachment from an entry, Journiv removes it from the album (ensuring it's not removed if used in other entries).

Using the Integration

Once connected, you can start attaching media to your entries:

Create or edit a journal entry.
Tap the Media icon in toolbar in the editor toolbar.
Select Immich.
Browse your library. You can select multiple items.
Tap Done to attach them. They will be added to your entry and your Immich album.

Journiv's Immich media picker caches Immich media thumbnails. If the picker is showing stale data click reload icon on top.

Privacy & Security

Direct Connection: Journiv's backend talks directly to your Immich server. Your media never leaves your instance.
Encrypted Keys: Your Immich API Key is stored securely with encryption in the Journiv database.
Permissions: Journiv only reads your library. Creates an album and manages media addition and removal to Journiv's album only. Journiv does not require any write or delete permissions.

Permissions Reference

To function correctly, Journiv requires the following permissions from your Immich API Key.

Permission	Scope	Description
Read Profile	`user.read`	Used to verify the connection and identify the logged-in user.
View Assets	`asset.view`	Used to display thumbnails and full-size images within the Journiv picker.
Download Assets	`asset.download`	Used to download media in Copy Mode or display full-quality assets in Link Mode.
Read Albums	`album.read`	Used to check if the "Journiv" album already exists.
Create Albums	`album.create`	Used to automatically create the "Journiv" album if it doesn't exist.
Add to Album	`albumAsset.create`	Used to add your journaled photos/videos to the "Journiv" album.
Remove from Album	`albumAsset.delete`	Used to remove photos/videos from the "Journiv" album when you detach them from an entry.

Journiv does not need any other permission. It is highly recommended you only grant the minimal set of permissions.

Troubleshooting

"Connection Refused" or "Host Unreachable"

Ensure your Journiv server can resolve and reach your Immich server's address.

"Invalid API Key"

Regenerate a new API key in Immich and update it in Journiv settings. Verify you copied the entire key string.

Missing Photos

Journiv caches Immich metadata for performance. If you recently uploaded photos to Immich and don't see them, click the reload button in the Journiv Immich picker.

Immich Integration