Immich Integration

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.
• Import people: Browse Immich people from Journiv and choose which ones to track as Journiv people.
• Link faces to people: Connect an Immich person identity to an existing Journiv person.
• Get people suggestions: When attached Immich assets contain recognized faces, Journiv can suggest linked people in the entry form.
• Smart syncing: Journiv keeps your library metadata in sync for fast browsing.
• Secure connection: Direct communication between your Journiv backend and Immich instances.

Prerequisites

To use this integration, you need:

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

Setting Up or Connecting

Step 1: Get your Immich API Key

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

Step 2: Configure Journiv

1. Open Journiv and go to Settings.
2. Navigate to Integrations.
3. Tap on Immich.
4. 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.
5. Paste your API Key.
6. (Optional) Expand Advanced Settings to specify a custom Album ID in link mode. By default, Journiv automatically creates and uses an album named "Journiv".
7. Select your desired Import Mode (see below).
8. 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:

1. Create or edit a journal entry.
2. Tap the Media icon in toolbar in the editor toolbar.
3. Select Immich.
4. Browse your library. You can select multiple items.
5. 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.

People and Face Integration

Journiv can use Immich's people and face recognition data to make people tracking easier.

This integration is opt-in at the Journiv people level:

• Immich remains the source of photo and face detection data.
• Journiv only creates or links the people you explicitly select.
• Journiv stores a mapping between the selected Immich person and the selected Journiv person.
• Future Immich photo attachments can use that mapping to suggest people in entries and moments.

Import Immich People Into Journiv

1. Connect Immich in Settings > Integrations.
2. Open People in Journiv.
3. Select Import people from Immich.
4. Search or scroll through people detected by Immich.
5. Optionally enable Include hidden people if you want to see people hidden in Immich.
6. Select the people you want Journiv to track.
7. Tap Import.

For each selected Immich person, Journiv creates a Journiv person and stores the Immich mapping. When available, Journiv also copies the Immich person thumbnail as the Journiv profile image.

Link Immich People to Existing Journiv People

If you already created a person in Journiv, link the Immich identity instead of importing a duplicate:

1. Open People > Import people from Immich.
2. Find the Immich person.
3. Use the link action on that person.
4. Choose the existing Journiv person.

After linking, Journiv can use Immich faces for that person without changing your existing Journiv people organization.

Automatic Suggestions From Attached Immich Photos

When you attach Immich media to an entry, Journiv checks the attached Immich assets for face data. If a face belongs to an Immich person that is linked to a Journiv person, Journiv shows that person as a suggestion in the entry form.

You stay in control:

• Suggested people are shown before saving.
• You can accept a suggestion to add the person.
• You can dismiss suggestions you do not want.
• Journiv does not create new people from face detections automatically.

Suggestions require the media to be attached from Immich. Photos uploaded directly to Journiv are not sent to Immich for face detection.

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.

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.

Missing Immich People

• Confirm the API key includes people permissions.
• Enable Include hidden people in the import sheet if the person is hidden in Immich.
• Verify that the person appears in Immich's own people view.

People Suggestions Do Not Appear

• Make sure the photo was attached from Immich, not uploaded directly to Journiv.
• Import or link the relevant Immich person from the People screen first.
• Check the asset directly in Immich and confirm Immich has detected the face and assigned it to the expected Immich person. If Immich has not recognized that person on the asset, Journiv cannot suggest them.
• Confirm the API key includes face read permissions.
• Refresh the entry media or re-open the entry form if Immich face data was recently generated.