# Immich

> Work with your own Immich photo and video library: find photos by date, people, place or by describing them, pick random ones, download, favorite or archive them, organise albums and share them with a link.

App · 20 actions. Web page: https://docs.lodol.com/docs/integrations/immich

## Actions

### Add photos to an album

Add photos and videos to an album. Any already in it are skipped.

**Inputs**

- Album (`album`, text, required): Pick an album, or give an album's ID or link from an earlier step.
- Photos and videos (`photos`, list, required): The photos and videos: their IDs, such as the ids a search step returned, or their links in Immich.

**Outputs**

- `added_count` (number): How many were added.
- `album_id` (text): The album's ID.
- `album_name` (text): The album's name.
- `album_url` (text): Opens the album in Immich.
- `already_in_album_count` (number): How many were in the album already.
- `item_count` (number): How many photos and videos the album holds now.
- `not_added` (list): Any that couldn't be added, and why. Empty when all went in.

**Example output**

```json
{
  "added_count": 2,
  "album_id": "f0b9c2d8-e4cc-4bdb-9c36-cda764479bd0",
  "album_name": "Holiday",
  "album_url": "https://demo.immich.app/albums/f0b9c2d8-e4cc-4bdb-9c36-cda764479bd0",
  "already_in_album_count": 0,
  "item_count": 502,
  "not_added": []
}
```

### Create a shared link

Make a link that anyone can open to see an album, or chosen photos and videos, without an Immich account. Optionally add a password, an expiry date or your own link ending.

**Inputs**

- Share (`share`, text): A whole album, or chosen photos and videos. One of: `album` (An album), `photos` (Photos and videos). Default: `album`.
- Album (`album`, text): The album to share. Photos added to it later show on the link too. Only when Share is An album.
- Photos and videos (`photos`, list): The photos and videos to share, such as the ids a search step returned. Only when Share is Photos and videos.
- Description (`description`, text): A few words visitors see with the photos.
- Password (`password`, text): Visitors must type this to open the link.
- Expires at (`expires_at`, date and time): When the link stops working. Leave empty for a link that never expires.
- Allow downloads (`allow_download`, true/false): Let visitors download the photos and videos. Needs Show photo details. Default: `true`.
- Show photo details (`show_metadata`, true/false): Let visitors see when and where each was taken, and with what camera. Default: `true`.
- Let visitors add photos (`allow_upload`, true/false): Let anyone with the link add their own photos and videos to the album. Only when Share is An album. Default: `false`.
- Custom link ending (`custom_ending`, text): Your own ending for the link, such as summer-2025 for /s/summer-2025, instead of a long random code. No spaces or slashes.

**Outputs**

- `album_id` (text): The album it shares. Null for a link to chosen photos.
- `album_name` (text): That album's name. Null for a link to chosen photos.
- `allow_download` (true/false): Whether visitors can download.
- `allow_upload` (true/false): Whether visitors can add photos and videos.
- `created_at` (text): When it was made.
- `custom_ending` (text): The link's own ending, after /s/. Null when it has none.
- `description` (text): Its description. Empty when it has none.
- `expires_at` (text): When it stops working. Null when it never does.
- `id` (text): The link's ID in Immich, for Delete a shared link.
- `password_protected` (true/false): Whether visitors need a password.
- `shares` (text): What it shares: album, or photos for chosen photos and videos.
- `show_metadata` (true/false): Whether visitors see when and where each was taken.
- `url` (text): The link to send people, e.g. https://photos.example.com/share/...

**Example output**

```json
{
  "album_id": "f0b9c2d8-e4cc-4bdb-9c36-cda764479bd0",
  "album_name": "Holiday",
  "allow_download": true,
  "allow_upload": false,
  "created_at": "2026-10-16T02:25:30Z",
  "custom_ending": "holiday-2025",
  "description": "For the family",
  "expires_at": "2026-12-31T23:00:00Z",
  "id": "b3348a7b-1530-4106-aec8-93b4137cc067",
  "password_protected": false,
  "shares": "album",
  "show_metadata": true,
  "url": "https://demo.immich.app/s/holiday-2025"
}
```

### Create an album

Create an album, optionally with photos and videos in it from the start.

**Inputs**

- Name (`name`, text, required): The album's name.
- Description (`description`, text): A few words about the album.
- Photos and videos (`photos`, list): Photos and videos to put in it, such as the ids a search step returned. Leave empty for an empty album.

**Outputs**

- `cover_photo_id` (text): The ID of the photo shown as its cover.
- `created_at` (text): When it was made.
- `description` (text): Its description. Empty when it has none.
- `end_date` (text): The day its latest photo or video was taken. Null when it's empty.
- `has_shared_link` (true/false): Whether a shared link opens it.
- `id` (text): The album's ID in Immich, for later steps.
- `item_count` (number): How many photos and videos it holds.
- `name` (text): The album's name.
- `owner_email` (text): Its owner's email.
- `owner_name` (text): Who owns it.
- `shared` (true/false): Whether it's shared with other people or by a link.
- `start_date` (text): The day its earliest photo or video was taken, e.g. 2025-04-27. Null when it's empty.
- `updated_at` (text): When it last changed.
- `url` (text): Opens it in Immich, e.g. https://photos.example.com/albums/f0b9c2d8-e4cc-4bdb-9c36-cda764479bd0.

**Example output**

```json
{
  "cover_photo_id": "f10fd233-75f1-40e0-b72a-772d30a80f79",
  "created_at": "2026-01-22T11:37:44Z",
  "description": "Auto-generated album based on the query \"Holiday\"",
  "end_date": "2025-04-06",
  "has_shared_link": false,
  "id": "f0b9c2d8-e4cc-4bdb-9c36-cda764479bd0",
  "item_count": 500,
  "name": "Holiday",
  "owner_email": "demo@immich.app",
  "owner_name": "Jane Doe",
  "shared": false,
  "start_date": "2002-01-03",
  "updated_at": "2026-01-22T11:37:44Z",
  "url": "https://demo.immich.app/albums/f0b9c2d8-e4cc-4bdb-9c36-cda764479bd0"
}
```

### Delete a shared link

Turn off a shared link so it no longer opens. The album or photos it shared are kept.

**Inputs**

- Shared link (`shared_link`, text, required): Pick the link, or give its ID or the link itself, such as the url Create a shared link returned.

**Outputs**

- `deleted` (true/false): True once it's gone.
- `id` (text): The link deleted.
- `url` (text): The link, which no longer opens.

**Example output**

```json
{
  "deleted": true,
  "id": "b3348a7b-1530-4106-aec8-93b4137cc067",
  "url": "https://demo.immich.app/s/holiday-2025"
}
```

### Delete an album

Delete an album and any shared links to it. The photos and videos in it stay in your library.

**Inputs**

- Album (`album`, text, required): Pick an album, or give an album's ID or link from an earlier step.

**Outputs**

- `deleted` (true/false): True once it's gone.
- `id` (text): The album deleted.
- `name` (text): Its name.

**Example output**

```json
{
  "deleted": true,
  "id": "f0b9c2d8-e4cc-4bdb-9c36-cda764479bd0",
  "name": "Holiday"
}
```

### Download a photo or video

Save a photo or video as a file that later steps can email, upload or post: the original, or a smaller preview image. Files up to 100 MB.

**Inputs**

- Photo or video (`photo`, text, required): The photo or video: its ID from an earlier step, such as a search, or its link in Immich.
- Size (`size`, text): The original file as it was added, or a smaller JPEG or WebP image made from it. A video's preview is a still image. One of: `original` (Original file), `preview` (Large preview image), `thumbnail` (Small thumbnail image). Default: `original`.

**Outputs**

- `content_type` (text): Its file type, e.g. image/jpeg.
- `document_ref` (text): Reference to the saved file, for later steps.
- `documents` (list): The saved file, in the shape steps that send or upload files expect.
- `filename` (text): The name it was saved under.
- `immich_url` (text): Opens the photo or video in Immich.
- `photo_id` (text): The photo or video's ID in Immich.
- `size_bytes` (number): Its size in bytes.
- `url` (text): Where to download the saved file.

**Example output**

```json
{
  "content_type": "image/jpeg",
  "document_ref": "doc_5c6d7e8f90a1b2c35c6d7e8f90a1b2c3",
  "documents": [
    {
      "content_type": "image/jpeg",
      "document_ref": "doc_5c6d7e8f90a1b2c35c6d7e8f90a1b2c3",
      "filename": "afeba2e3-d40c-4a5b-81de-bfaab1b18eb6.jpg",
      "size_bytes": 9820124,
      "url": "/actions/core/serve-document/doc_5c6d7e8f90a1b2c35c6d7e8f90a1b2c3?teamId=6512a1b2c3d4e5f600000001"
    }
  ],
  "filename": "afeba2e3-d40c-4a5b-81de-bfaab1b18eb6.jpg",
  "immich_url": "https://demo.immich.app/photos/7d8fe1ec-ff44-4277-904f-fea0cfbfb7b0",
  "photo_id": "7d8fe1ec-ff44-4277-904f-fea0cfbfb7b0",
  "size_bytes": 9820124,
  "url": "/actions/core/serve-document/doc_5c6d7e8f90a1b2c35c6d7e8f90a1b2c3?teamId=6512a1b2c3d4e5f600000001"
}
```

### Find photos by description

Find photos and videos by describing what's in them, such as a dog on the beach at sunset, using Immich's smart search. The best matches come first.

**Inputs**

- Description (`query`, text, required): What's in the photos you're after, in your own words, such as birthday cake with candles.
- Type (`media_type`, text): Photos, videos, or both. One of: `all` (Photos and videos), `photos` (Photos only), `videos` (Videos only). Default: `all`.
- Taken after (`taken_after`, date and time): Only ones taken after this moment.
- Taken before (`taken_before`, date and time): Only ones taken before this moment.
- People (`people`, list): Only ones with all of these people in them.
- Album (`album`, text): Only ones in this album.
- Country (`country`, text): Only ones taken in this country.
- City (`city`, text): Only ones taken in this city.
- Favorites only (`favorites_only`, true/false): Only your favorites. Default: `false`.
- Look in (`look_in`, text): Your timeline, or the photos and videos you've archived. One of: `timeline`, `archive`. Default: `timeline`.
- Max results (`max_results`, number): How many to get at most, up to 1,000. From 1 to 1000. Default: `25`.
- Page (`page`, number): Which page of results to get, for more than Max results. The first page is 1; a step's next_page says which comes next. From 1 to 100000. Default: `1`.

**Outputs**

- `count` (number): How many came back.
- `has_more` (true/false): Whether there are more on the next page.
- `ids` (list): The IDs of the photos and videos, ready for steps that take several, such as Add photos to an album.
- `items` (list): The photos and videos found.
- `next_page` (number): The page to ask for next. Null on the last page.

**Example output**

```json
{
  "count": 2,
  "has_more": true,
  "ids": [
    "11b84a96-f89e-4059-988f-67cb50a807dd",
    "7d8fe1ec-ff44-4277-904f-fea0cfbfb7b0"
  ],
  "items": [
    {
      "added_at": "2026-01-20T15:20:31Z",
      "camera": "FUJIFILM X-S10",
      "city": "Monterosso al Mare",
      "country": "Italy",
      "description": "",
      "duration_seconds": null,
      "file_name": "343b1fad-53d2-4fdc-a2db-4b435bad9141.jpg",
      "file_size_bytes": 4457475,
      "height": 6198,
      "id": "11b84a96-f89e-4059-988f-67cb50a807dd",
      "is_archived": false,
      "is_favorite": false,
      "is_trashed": false,
      "latitude": 44.146094,
      "longitude": 9.643879,
      "people": [],
      "rating": null,
      "state": "Liguria",
      "taken_at": "2025-04-27T09:22:02Z",
      "taken_at_local": "2025-04-27T11:22:02",
      "type": "photo",
      "url": "https://demo.immich.app/photos/11b84a96-f89e-4059-988f-67cb50a807dd",
      "width": 4132
    },
    {
      "added_at": "2026-01-20T15:22:56Z",
      "camera": "Google Pixel 9 Pro XL",
      "city": "Ixelles",
      "country": "Belgium",
      "description": "",
      "duration_seconds": null,
      "file_name": "afeba2e3-d40c-4a5b-81de-bfaab1b18eb6.jpg",
      "file_size_bytes": 9820124,
      "height": 6144,
      "id": "7d8fe1ec-ff44-4277-904f-fea0cfbfb7b0",
      "is_archived": false,
      "is_favorite": false,
      "is_trashed": false,
      "latitude": 50.8392361111111,
      "longitude": 4.37657222222222,
      "people": [
        {
          "id": "a109aeb4-8dc0-4366-9276-a5c5a9303560",
          "name": "The 11x Developer"
        }
      ],
      "rating": null,
      "state": "Brussels Capital",
      "taken_at": "2025-01-31T13:13:17Z",
      "taken_at_local": "2025-01-31T14:13:17",
      "type": "photo",
      "url": "https://demo.immich.app/photos/7d8fe1ec-ff44-4277-904f-fea0cfbfb7b0",
      "width": 8160
    }
  ],
  "next_page": 2
}
```

### Get a person

Get a person's name, birthday and how many photos and videos they're in, with a link to their photos in Immich.

**Inputs**

- Person (`person`, text, required): Pick a person, or give a person's ID or link from an earlier step.

**Outputs**

- `birth_date` (text): Their birthday, e.g. 1990-05-14. Null when not set.
- `id` (text): The person's ID in Immich, for later steps.
- `is_favorite` (true/false): Whether they're marked as a favorite.
- `is_hidden` (true/false): Whether they're hidden from the People page.
- `name` (text): Their name. Empty for someone not named yet.
- `photo_count` (number): How many photos and videos they're in.
- `url` (text): Opens their photos in Immich.

**Example output**

```json
{
  "birth_date": null,
  "id": "a109aeb4-8dc0-4366-9276-a5c5a9303560",
  "is_favorite": false,
  "is_hidden": false,
  "name": "The 11x Developer",
  "photo_count": 80,
  "url": "https://demo.immich.app/people/a109aeb4-8dc0-4366-9276-a5c5a9303560"
}
```

### Get a photo or video

Get one photo or video's details: when and where it was taken, who is in it, its description, camera and size, and a link to open it in Immich.

**Inputs**

- Photo or video (`photo`, text, required): The photo or video: its ID from an earlier step, such as a search, or its link in Immich.

**Outputs**

- `added_at` (text): When it was added to Immich.
- `camera` (text): The camera or phone it was taken with, e.g. Google Pixel 9 Pro XL. Null when unknown.
- `city` (text): The city it was taken in. Null when unknown.
- `country` (text): The country it was taken in. Null when unknown.
- `description` (text): Its description. Empty when it has none.
- `duration_seconds` (number): How long a video runs, in seconds. Null for a photo.
- `file_name` (text): The name of the file it was added from, e.g. IMG_2041.jpg.
- `file_size_bytes` (number): The size of the original file, in bytes.
- `height` (number): Its height in pixels.
- `id` (text): The photo or video's ID in Immich, for later steps.
- `is_archived` (true/false): Whether it's in the archive rather than the timeline.
- `is_favorite` (true/false): Whether it's one of your favorites.
- `is_trashed` (true/false): Whether it's in the trash.
- `latitude` (number): Where it was taken, north to south. Null when unknown.
- `longitude` (number): Where it was taken, east to west. Null when unknown.
- `people` (list): The named people Immich recognised in it. Always empty in Find photos by description results: get the photo for them.
- `rating` (number): Its star rating, 1 to 5. Null when it has none.
- `state` (text): The state or region it was taken in. Null when unknown.
- `taken_at` (text): When it was taken, e.g. 2025-01-31T13:13:17Z.
- `taken_at_local` (text): The time where it was taken, as the camera's clock showed it, e.g. 2025-01-31T14:13:17.
- `type` (text): What it is: photo, video, audio or other.
- `url` (text): Opens it in Immich, e.g. https://photos.example.com/photos/7d8fe1ec-ff44-4277-904f-fea0cfbfb7b0.
- `width` (number): Its width in pixels.

**Example output**

```json
{
  "added_at": "2026-01-20T15:22:56Z",
  "camera": "Google Pixel 9 Pro XL",
  "city": "Ixelles",
  "country": "Belgium",
  "description": "",
  "duration_seconds": null,
  "file_name": "afeba2e3-d40c-4a5b-81de-bfaab1b18eb6.jpg",
  "file_size_bytes": 9820124,
  "height": 6144,
  "id": "7d8fe1ec-ff44-4277-904f-fea0cfbfb7b0",
  "is_archived": false,
  "is_favorite": false,
  "is_trashed": false,
  "latitude": 50.8392361111111,
  "longitude": 4.37657222222222,
  "people": [
    {
      "id": "a109aeb4-8dc0-4366-9276-a5c5a9303560",
      "name": "The 11x Developer"
    }
  ],
  "rating": null,
  "state": "Brussels Capital",
  "taken_at": "2025-01-31T13:13:17Z",
  "taken_at_local": "2025-01-31T14:13:17",
  "type": "photo",
  "url": "https://demo.immich.app/photos/7d8fe1ec-ff44-4277-904f-fea0cfbfb7b0",
  "width": 8160
}
```

### Get an album

Get an album's name, description, how many photos and videos it holds, who owns it, the dates they span, and its link.

**Inputs**

- Album (`album`, text, required): Pick an album, or give an album's ID or link from an earlier step.

**Outputs**

- `cover_photo_id` (text): The ID of the photo shown as its cover.
- `created_at` (text): When it was made.
- `description` (text): Its description. Empty when it has none.
- `end_date` (text): The day its latest photo or video was taken. Null when it's empty.
- `has_shared_link` (true/false): Whether a shared link opens it.
- `id` (text): The album's ID in Immich, for later steps.
- `item_count` (number): How many photos and videos it holds.
- `name` (text): The album's name.
- `owner_email` (text): Its owner's email.
- `owner_name` (text): Who owns it.
- `shared` (true/false): Whether it's shared with other people or by a link.
- `start_date` (text): The day its earliest photo or video was taken, e.g. 2025-04-27. Null when it's empty.
- `updated_at` (text): When it last changed.
- `url` (text): Opens it in Immich, e.g. https://photos.example.com/albums/f0b9c2d8-e4cc-4bdb-9c36-cda764479bd0.

**Example output**

```json
{
  "cover_photo_id": "f10fd233-75f1-40e0-b72a-772d30a80f79",
  "created_at": "2026-01-22T11:37:44Z",
  "description": "Auto-generated album based on the query \"Holiday\"",
  "end_date": "2025-04-06",
  "has_shared_link": false,
  "id": "f0b9c2d8-e4cc-4bdb-9c36-cda764479bd0",
  "item_count": 500,
  "name": "Holiday",
  "owner_email": "demo@immich.app",
  "owner_name": "Jane Doe",
  "shared": false,
  "start_date": "2002-01-03",
  "updated_at": "2026-01-22T11:37:44Z",
  "url": "https://demo.immich.app/albums/f0b9c2d8-e4cc-4bdb-9c36-cda764479bd0"
}
```

### Get random photos

Pick photos or videos at random from your library, optionally only of certain people, from one album, place or time. Good for a photo of the day.

**Inputs**

- How many (`count`, number): How many to pick, up to 100. From 1 to 100. Default: `1`.
- Type (`media_type`, text): Photos, videos, or both. One of: `all` (Photos and videos), `photos` (Photos only), `videos` (Videos only). Default: `photos`.
- Taken after (`taken_after`, date and time): Only ones taken after this moment.
- Taken before (`taken_before`, date and time): Only ones taken before this moment.
- People (`people`, list): Only ones with all of these people in them.
- Album (`album`, text): Only ones in this album.
- Country (`country`, text): Only ones taken in this country.
- City (`city`, text): Only ones taken in this city.
- Favorites only (`favorites_only`, true/false): Only your favorites. Default: `false`.
- Look in (`look_in`, text): Your timeline, or the photos and videos you've archived. One of: `timeline`, `archive`. Default: `timeline`.

**Outputs**

- `count` (number): How many came back.
- `ids` (list): The IDs of the photos and videos, ready for steps that take several, such as Add photos to an album.
- `items` (list): The photos and videos picked.

**Example output**

```json
{
  "count": 1,
  "ids": [
    "7d8fe1ec-ff44-4277-904f-fea0cfbfb7b0"
  ],
  "items": [
    {
      "added_at": "2026-01-20T15:22:56Z",
      "camera": "Google Pixel 9 Pro XL",
      "city": "Ixelles",
      "country": "Belgium",
      "description": "",
      "duration_seconds": null,
      "file_name": "afeba2e3-d40c-4a5b-81de-bfaab1b18eb6.jpg",
      "file_size_bytes": 9820124,
      "height": 6144,
      "id": "7d8fe1ec-ff44-4277-904f-fea0cfbfb7b0",
      "is_archived": false,
      "is_favorite": false,
      "is_trashed": false,
      "latitude": 50.8392361111111,
      "longitude": 4.37657222222222,
      "people": [
        {
          "id": "a109aeb4-8dc0-4366-9276-a5c5a9303560",
          "name": "The 11x Developer"
        }
      ],
      "rating": null,
      "state": "Brussels Capital",
      "taken_at": "2025-01-31T13:13:17Z",
      "taken_at_local": "2025-01-31T14:13:17",
      "type": "photo",
      "url": "https://demo.immich.app/photos/7d8fe1ec-ff44-4277-904f-fea0cfbfb7b0",
      "width": 8160
    }
  ]
}
```

### List albums

List your albums and the albums shared with you, with how many photos and videos each holds and a link to each.

**Inputs**

- Name contains (`name_contains`, text): Only albums whose name contains this text.
- Shared albums only (`shared_only`, true/false): Only albums shared with other people or by a link. Default: `false`.
- Max results (`max_results`, number): How many to list at most, up to 1,000. From 1 to 1000. Default: `100`.

**Outputs**

- `count` (number): How many came back.
- `has_more` (true/false): Whether more matched than Max results.
- `items` (list): The albums.
- `total` (number): How many matched in all, including any past Max results.

**Example output**

```json
{
  "count": 1,
  "has_more": false,
  "items": [
    {
      "cover_photo_id": "f10fd233-75f1-40e0-b72a-772d30a80f79",
      "created_at": "2026-01-22T11:37:44Z",
      "description": "Auto-generated album based on the query \"Holiday\"",
      "end_date": "2025-04-06",
      "has_shared_link": false,
      "id": "f0b9c2d8-e4cc-4bdb-9c36-cda764479bd0",
      "item_count": 500,
      "name": "Holiday",
      "owner_email": "demo@immich.app",
      "owner_name": "Jane Doe",
      "shared": false,
      "start_date": "2002-01-03",
      "updated_at": "2026-01-22T11:37:44Z",
      "url": "https://demo.immich.app/albums/f0b9c2d8-e4cc-4bdb-9c36-cda764479bd0"
    }
  ],
  "total": 1
}
```

### List people

List the people Immich has recognised in your photos and you've named, with a link to each one's photos.

**Inputs**

- Name contains (`name_contains`, text): Only people whose name contains this text.
- Include unnamed people (`include_unnamed`, true/false): Also list the faces Immich found that nobody has named yet. Default: `false`.
- Include hidden people (`include_hidden`, true/false): Also list people hidden from the People page. Default: `false`.
- Max results (`max_results`, number): How many to list at most, up to 1,000. From 1 to 1000. Default: `100`.

**Outputs**

- `count` (number): How many came back.
- `has_more` (true/false): Whether more matched than Max results.
- `items` (list): The people.
- `total` (number): How many matched in all, including any past Max results.

**Example output**

```json
{
  "count": 1,
  "has_more": false,
  "items": [
    {
      "birth_date": null,
      "id": "a109aeb4-8dc0-4366-9276-a5c5a9303560",
      "is_favorite": false,
      "is_hidden": false,
      "name": "The 11x Developer",
      "url": "https://demo.immich.app/people/a109aeb4-8dc0-4366-9276-a5c5a9303560"
    }
  ],
  "total": 1
}
```

### List shared links

List the shared links you've made, with what each shares, whether it has a password and when it expires.

**Inputs**

- Album (`album`, text): Only links to this album.
- Max results (`max_results`, number): How many to list at most, up to 1,000. From 1 to 1000. Default: `100`.

**Outputs**

- `count` (number): How many came back.
- `has_more` (true/false): Whether more matched than Max results.
- `items` (list): The shared links.
- `total` (number): How many matched in all, including any past Max results.

**Example output**

```json
{
  "count": 2,
  "has_more": false,
  "items": [
    {
      "album_id": "f0b9c2d8-e4cc-4bdb-9c36-cda764479bd0",
      "album_name": "Holiday",
      "allow_download": true,
      "allow_upload": false,
      "created_at": "2026-10-16T02:25:30Z",
      "custom_ending": "holiday-2025",
      "description": "For the family",
      "expires_at": "2026-12-31T23:00:00Z",
      "id": "b3348a7b-1530-4106-aec8-93b4137cc067",
      "password_protected": false,
      "shares": "album",
      "show_metadata": true,
      "url": "https://demo.immich.app/s/holiday-2025"
    },
    {
      "album_id": null,
      "album_name": null,
      "allow_download": true,
      "allow_upload": false,
      "created_at": "2026-10-16T02:00:39Z",
      "custom_ending": null,
      "description": "",
      "expires_at": "2026-10-17T02:00:35Z",
      "id": "8b12df6c-daef-4988-beb7-fbb6db3fe4ab",
      "password_protected": false,
      "shares": "photos",
      "show_metadata": true,
      "url": "https://demo.immich.app/share/9Fjfpuz1paPXI-gnWBr5Tbqoic5bTsN6zPolsVHpLuCA2nLAna16AkrfNVYIupYGikk"
    }
  ],
  "total": 2
}
```

### Move photos or videos to the trash

Move photos or videos to Immich's trash. They can be restored until the trash empties itself, after 30 days unless your server is set otherwise. On a server with the trash turned off, nothing is deleted.

**Inputs**

- Photos and videos (`photos`, list, required): The photos and videos: their IDs, such as the ids a search step returned, or their links in Immich.

**Outputs**

- `days_in_trash` (number): How many days they stay in the trash before Immich deletes them for good.
- `ids` (list): The IDs of the photos and videos, ready for steps that take several, such as Add photos to an album.
- `trashed_count` (number): How many were moved to the trash.

**Example output**

```json
{
  "days_in_trash": 30,
  "ids": [
    "11b84a96-f89e-4059-988f-67cb50a807dd"
  ],
  "trashed_count": 1
}
```

### Remove photos from an album

Take photos and videos out of an album. They stay in your library.

**Inputs**

- Album (`album`, text, required): Pick an album, or give an album's ID or link from an earlier step.
- Photos and videos (`photos`, list, required): The photos and videos: their IDs, such as the ids a search step returned, or their links in Immich.

**Outputs**

- `album_id` (text): The album's ID.
- `album_name` (text): The album's name.
- `album_url` (text): Opens the album in Immich.
- `item_count` (number): How many photos and videos the album holds now.
- `not_in_album_count` (number): How many weren't in the album to begin with.
- `not_removed` (list): Any that couldn't be taken out, and why. Empty when all were.
- `removed_count` (number): How many were taken out.

**Example output**

```json
{
  "album_id": "f0b9c2d8-e4cc-4bdb-9c36-cda764479bd0",
  "album_name": "Holiday",
  "album_url": "https://demo.immich.app/albums/f0b9c2d8-e4cc-4bdb-9c36-cda764479bd0",
  "item_count": 501,
  "not_in_album_count": 0,
  "not_removed": [],
  "removed_count": 1
}
```

### Restore photos or videos from the trash

Bring photos or videos back from Immich's trash to where they were.

**Inputs**

- Photos and videos (`photos`, list, required): The photos and videos: their IDs, such as the ids a search step returned, or their links in Immich.

**Outputs**

- `ids` (list): The IDs of the photos and videos, ready for steps that take several, such as Add photos to an album.
- `restored_count` (number): How many were restored.

**Example output**

```json
{
  "ids": [
    "11b84a96-f89e-4059-988f-67cb50a807dd"
  ],
  "restored_count": 1
}
```

### Search photos and videos

Find photos and videos in your Immich library by when they were taken, who is in them, where, which album they're in, or their file name or description.

**Inputs**

- Type (`media_type`, text): Photos, videos, or both. One of: `all` (Photos and videos), `photos` (Photos only), `videos` (Videos only). Default: `all`.
- Taken after (`taken_after`, date and time): Only ones taken after this moment.
- Taken before (`taken_before`, date and time): Only ones taken before this moment.
- People (`people`, list): Only ones with all of these people in them.
- Album (`album`, text): Only ones in this album.
- Country (`country`, text): Only ones taken in this country.
- City (`city`, text): Only ones taken in this city.
- Favorites only (`favorites_only`, true/false): Only your favorites. Default: `false`.
- File name (`file_name`, text): Only ones whose file name contains this, e.g. IMG_20.
- Description (`description`, text): Only ones whose description contains this text.
- Look in (`look_in`, text): Your timeline, or the photos and videos you've archived. One of: `timeline`, `archive`. Default: `timeline`.
- Order (`order`, text): Newest or oldest first, by when they were taken. One of: `newest` (Newest first), `oldest` (Oldest first). Default: `newest`.
- Max results (`max_results`, number): How many to get at most, up to 1,000. From 1 to 1000. Default: `50`.
- Page (`page`, number): Which page of results to get, for more than Max results. The first page is 1; a step's next_page says which comes next. From 1 to 100000. Default: `1`.

**Outputs**

- `count` (number): How many came back.
- `has_more` (true/false): Whether there are more on the next page.
- `ids` (list): The IDs of the photos and videos, ready for steps that take several, such as Add photos to an album.
- `items` (list): The photos and videos found.
- `next_page` (number): The page to ask for next. Null on the last page.

**Example output**

```json
{
  "count": 2,
  "has_more": true,
  "ids": [
    "11b84a96-f89e-4059-988f-67cb50a807dd",
    "7d8fe1ec-ff44-4277-904f-fea0cfbfb7b0"
  ],
  "items": [
    {
      "added_at": "2026-01-20T15:20:31Z",
      "camera": "FUJIFILM X-S10",
      "city": "Monterosso al Mare",
      "country": "Italy",
      "description": "",
      "duration_seconds": null,
      "file_name": "343b1fad-53d2-4fdc-a2db-4b435bad9141.jpg",
      "file_size_bytes": 4457475,
      "height": 6198,
      "id": "11b84a96-f89e-4059-988f-67cb50a807dd",
      "is_archived": false,
      "is_favorite": false,
      "is_trashed": false,
      "latitude": 44.146094,
      "longitude": 9.643879,
      "people": [],
      "rating": null,
      "state": "Liguria",
      "taken_at": "2025-04-27T09:22:02Z",
      "taken_at_local": "2025-04-27T11:22:02",
      "type": "photo",
      "url": "https://demo.immich.app/photos/11b84a96-f89e-4059-988f-67cb50a807dd",
      "width": 4132
    },
    {
      "added_at": "2026-01-20T15:22:56Z",
      "camera": "Google Pixel 9 Pro XL",
      "city": "Ixelles",
      "country": "Belgium",
      "description": "",
      "duration_seconds": null,
      "file_name": "afeba2e3-d40c-4a5b-81de-bfaab1b18eb6.jpg",
      "file_size_bytes": 9820124,
      "height": 6144,
      "id": "7d8fe1ec-ff44-4277-904f-fea0cfbfb7b0",
      "is_archived": false,
      "is_favorite": false,
      "is_trashed": false,
      "latitude": 50.8392361111111,
      "longitude": 4.37657222222222,
      "people": [
        {
          "id": "a109aeb4-8dc0-4366-9276-a5c5a9303560",
          "name": "The 11x Developer"
        }
      ],
      "rating": null,
      "state": "Brussels Capital",
      "taken_at": "2025-01-31T13:13:17Z",
      "taken_at_local": "2025-01-31T14:13:17",
      "type": "photo",
      "url": "https://demo.immich.app/photos/7d8fe1ec-ff44-4277-904f-fea0cfbfb7b0",
      "width": 8160
    }
  ],
  "next_page": 2
}
```

### Update a photo or video

Favorite or archive a photo or video, or change its description, star rating or the date it was taken. Only what you fill in changes.

**Inputs**

- Photo or video (`photo`, text, required): The photo or video: its ID from an earlier step, such as a search, or its link in Immich.
- Favorite (`favorite`, text): Add it to your favorites, or take it out. One of: `keep` (Leave as it is), `add` (Add to favorites), `remove` (Remove from favorites). Default: `keep`.
- Archive (`archive`, text): Move it to the archive, which hides it from the timeline, or back to the timeline. One of: `keep` (Leave as it is), `archive` (Move to the archive), `unarchive` (Move back to the timeline). Default: `keep`.
- Description (`description`, text): A new description, replacing the old one. Leave empty to keep it.
- Clear the description (`clear_description`, true/false): Remove its description altogether. Default: `false`.
- Date taken (`taken_at`, date and time): When it was taken. It keeps its own time zone, so Immich shows the time you pick.
- Rating (`rating`, text): Its star rating. One of: `keep` (Leave as it is), `1` (1 star), `2` (2 stars), `3` (3 stars), `4` (4 stars), `5` (5 stars), `none` (No rating). Default: `keep`.

**Outputs**

- `added_at` (text): When it was added to Immich.
- `camera` (text): The camera or phone it was taken with, e.g. Google Pixel 9 Pro XL. Null when unknown.
- `city` (text): The city it was taken in. Null when unknown.
- `country` (text): The country it was taken in. Null when unknown.
- `description` (text): Its description. Empty when it has none.
- `duration_seconds` (number): How long a video runs, in seconds. Null for a photo.
- `file_name` (text): The name of the file it was added from, e.g. IMG_2041.jpg.
- `file_size_bytes` (number): The size of the original file, in bytes.
- `height` (number): Its height in pixels.
- `id` (text): The photo or video's ID in Immich, for later steps.
- `is_archived` (true/false): Whether it's in the archive rather than the timeline.
- `is_favorite` (true/false): Whether it's one of your favorites.
- `is_trashed` (true/false): Whether it's in the trash.
- `latitude` (number): Where it was taken, north to south. Null when unknown.
- `longitude` (number): Where it was taken, east to west. Null when unknown.
- `people` (list): The named people Immich recognised in it. Always empty in Find photos by description results: get the photo for them.
- `rating` (number): Its star rating, 1 to 5. Null when it has none.
- `state` (text): The state or region it was taken in. Null when unknown.
- `taken_at` (text): When it was taken, e.g. 2025-01-31T13:13:17Z.
- `taken_at_local` (text): The time where it was taken, as the camera's clock showed it, e.g. 2025-01-31T14:13:17.
- `type` (text): What it is: photo, video, audio or other.
- `url` (text): Opens it in Immich, e.g. https://photos.example.com/photos/7d8fe1ec-ff44-4277-904f-fea0cfbfb7b0.
- `width` (number): Its width in pixels.

**Example output**

```json
{
  "added_at": "2026-01-20T15:22:56Z",
  "camera": "Google Pixel 9 Pro XL",
  "city": "Ixelles",
  "country": "Belgium",
  "description": "",
  "duration_seconds": null,
  "file_name": "afeba2e3-d40c-4a5b-81de-bfaab1b18eb6.jpg",
  "file_size_bytes": 9820124,
  "height": 6144,
  "id": "7d8fe1ec-ff44-4277-904f-fea0cfbfb7b0",
  "is_archived": false,
  "is_favorite": false,
  "is_trashed": false,
  "latitude": 50.8392361111111,
  "longitude": 4.37657222222222,
  "people": [
    {
      "id": "a109aeb4-8dc0-4366-9276-a5c5a9303560",
      "name": "The 11x Developer"
    }
  ],
  "rating": null,
  "state": "Brussels Capital",
  "taken_at": "2025-01-31T13:13:17Z",
  "taken_at_local": "2025-01-31T14:13:17",
  "type": "photo",
  "url": "https://demo.immich.app/photos/7d8fe1ec-ff44-4277-904f-fea0cfbfb7b0",
  "width": 8160
}
```

### Update an album

Rename an album, change its description or choose its cover photo. Only what you fill in changes.

**Inputs**

- Album (`album`, text, required): Pick an album, or give an album's ID or link from an earlier step.
- Name (`name`, text): A new name. Leave empty to keep it.
- Description (`description`, text): A new description. Leave empty to keep it.
- Cover photo (`cover_photo`, text): A photo in the album to show as its cover: its ID or its link in Immich.

**Outputs**

- `cover_photo_id` (text): The ID of the photo shown as its cover.
- `created_at` (text): When it was made.
- `description` (text): Its description. Empty when it has none.
- `end_date` (text): The day its latest photo or video was taken. Null when it's empty.
- `has_shared_link` (true/false): Whether a shared link opens it.
- `id` (text): The album's ID in Immich, for later steps.
- `item_count` (number): How many photos and videos it holds.
- `name` (text): The album's name.
- `owner_email` (text): Its owner's email.
- `owner_name` (text): Who owns it.
- `shared` (true/false): Whether it's shared with other people or by a link.
- `start_date` (text): The day its earliest photo or video was taken, e.g. 2025-04-27. Null when it's empty.
- `updated_at` (text): When it last changed.
- `url` (text): Opens it in Immich, e.g. https://photos.example.com/albums/f0b9c2d8-e4cc-4bdb-9c36-cda764479bd0.

**Example output**

```json
{
  "cover_photo_id": "f10fd233-75f1-40e0-b72a-772d30a80f79",
  "created_at": "2026-01-22T11:37:44Z",
  "description": "Auto-generated album based on the query \"Holiday\"",
  "end_date": "2025-04-06",
  "has_shared_link": false,
  "id": "f0b9c2d8-e4cc-4bdb-9c36-cda764479bd0",
  "item_count": 500,
  "name": "Holiday",
  "owner_email": "demo@immich.app",
  "owner_name": "Jane Doe",
  "shared": false,
  "start_date": "2002-01-03",
  "updated_at": "2026-01-22T11:37:44Z",
  "url": "https://demo.immich.app/albums/f0b9c2d8-e4cc-4bdb-9c36-cda764479bd0"
}
```