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.

Actions

Action	What it does
Add photos to an album	Add photos and videos to an album.
Create a shared link	Make a link that anyone can open to see an album, or chosen photos and videos, without an Immich account.
Create an album	Create an album, optionally with photos and videos in it from the start.
Delete a shared link	Turn off a shared link so it no longer opens.
Delete an album	Delete an album and any shared links to it.
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.
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.
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.
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.
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.
Get random photos	Pick photos or videos at random from your library, optionally only of certain people, from one album, place or time.
List albums	List your albums and the albums shared with you, with how many photos and videos each holds and a link to each.
List people	List the people Immich has recognised in your photos and you've named, with a link to each one's photos.
List shared links	List the shared links you've made, with what each shares, whether it has a password and when it expires.
Move photos or videos to the trash	Move photos or videos to Immich's trash.
Remove photos from an album	Take photos and videos out of an album.
Restore photos or videos from the trash	Bring photos or videos back from Immich's trash to where they were.
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.
Update a photo or video	Favorite or archive a photo or video, or change its description, star rating or the date it was taken.
Update an album	Rename an album, change its description or choose its cover photo.

Add photos to an album

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

Inputs

AlbumalbumtextRequired: Pick an album, or give an album's ID or link from an earlier step.
Photos and videosphotoslistRequired: The photos and videos: their IDs, such as the ids a search step returned, or their links in Immich.

Outputs

added_countnumber: How many were added.
album_idtext: The album's ID.
album_nametext: The album's name.
album_urltext: Opens the album in Immich.
already_in_album_countnumber: How many were in the album already.
item_countnumber: How many photos and videos the album holds now.
not_addedlist: Any that couldn't be added, and why. Empty when all went in.

Example output

{
  "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

Sharesharetext: A whole album, or chosen photos and videos.One of: album (An album), photos (Photos and videos). Default: album.
Albumalbumtext: The album to share. Photos added to it later show on the link too.Only when Share is An album.
Photos and videosphotoslist: The photos and videos to share, such as the ids a search step returned.Only when Share is Photos and videos.
Descriptiondescriptiontext: A few words visitors see with the photos.
Passwordpasswordtext: Visitors must type this to open the link.
Expires atexpires_atdate and time: When the link stops working. Leave empty for a link that never expires.
Allow downloadsallow_downloadtrue/false: Let visitors download the photos and videos. Needs Show photo details.Default: true.
Show photo detailsshow_metadatatrue/false: Let visitors see when and where each was taken, and with what camera.Default: true.
Let visitors add photosallow_uploadtrue/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 endingcustom_endingtext: 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_idtext: The album it shares. Null for a link to chosen photos.
album_nametext: That album's name. Null for a link to chosen photos.
allow_downloadtrue/false: Whether visitors can download.
allow_uploadtrue/false: Whether visitors can add photos and videos.
created_attext: When it was made.
custom_endingtext: The link's own ending, after /s/. Null when it has none.
descriptiontext: Its description. Empty when it has none.
expires_attext: When it stops working. Null when it never does.
idtext: The link's ID in Immich, for Delete a shared link.
password_protectedtrue/false: Whether visitors need a password.
sharestext: What it shares: album, or photos for chosen photos and videos.
show_metadatatrue/false: Whether visitors see when and where each was taken.
urltext: The link to send people, e.g. https://photos.example.com/share/...

Example output

{
  "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

NamenametextRequired: The album's name.
Descriptiondescriptiontext: A few words about the album.
Photos and videosphotoslist: Photos and videos to put in it, such as the ids a search step returned. Leave empty for an empty album.

Outputs

cover_photo_idtext: The ID of the photo shown as its cover.
created_attext: When it was made.
descriptiontext: Its description. Empty when it has none.
end_datetext: The day its latest photo or video was taken. Null when it's empty.
has_shared_linktrue/false: Whether a shared link opens it.
idtext: The album's ID in Immich, for later steps.
item_countnumber: How many photos and videos it holds.
nametext: The album's name.
owner_emailtext: Its owner's email.
owner_nametext: Who owns it.
sharedtrue/false: Whether it's shared with other people or by a link.
start_datetext: The day its earliest photo or video was taken, e.g. 2025-04-27. Null when it's empty.
updated_attext: When it last changed.
urltext: Opens it in Immich, e.g. https://photos.example.com/albums/f0b9c2d8-e4cc-4bdb-9c36-cda764479bd0.

Example output

{
  "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 linkshared_linktextRequired: Pick the link, or give its ID or the link itself, such as the url Create a shared link returned.

Outputs

deletedtrue/false: True once it's gone.
idtext: The link deleted.
urltext: The link, which no longer opens.

Example output

{
  "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

AlbumalbumtextRequired: Pick an album, or give an album's ID or link from an earlier step.

Outputs

deletedtrue/false: True once it's gone.
idtext: The album deleted.
nametext: Its name.

Example output

{
  "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 videophototextRequired: The photo or video: its ID from an earlier step, such as a search, or its link in Immich.
Sizesizetext: 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_typetext: Its file type, e.g. image/jpeg.
document_reftext: Reference to the saved file, for later steps.
documentslist: The saved file, in the shape steps that send or upload files expect.
filenametext: The name it was saved under.
immich_urltext: Opens the photo or video in Immich.
photo_idtext: The photo or video's ID in Immich.
size_bytesnumber: Its size in bytes.
urltext: Where to download the saved file.

Example output

{
  "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

DescriptionquerytextRequired: What's in the photos you're after, in your own words, such as birthday cake with candles.
Typemedia_typetext: Photos, videos, or both.One of: all (Photos and videos), photos (Photos only), videos (Videos only). Default: all.
Taken aftertaken_afterdate and time: Only ones taken after this moment.
Taken beforetaken_beforedate and time: Only ones taken before this moment.
Peoplepeoplelist: Only ones with all of these people in them.
Albumalbumtext: Only ones in this album.
Countrycountrytext: Only ones taken in this country.
Citycitytext: Only ones taken in this city.
Favorites onlyfavorites_onlytrue/false: Only your favorites.Default: false.
Look inlook_intext: Your timeline, or the photos and videos you've archived.One of: timeline, archive. Default: timeline.
Max resultsmax_resultsnumber: How many to get at most, up to 1,000.From 1 to 1000. Default: 25.
Pagepagenumber: 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

countnumber: How many came back.
has_moretrue/false: Whether there are more on the next page.
idslist: The IDs of the photos and videos, ready for steps that take several, such as Add photos to an album.
itemslist: The photos and videos found.
next_pagenumber: The page to ask for next. Null on the last page.

Example output

{
  "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

PersonpersontextRequired: Pick a person, or give a person's ID or link from an earlier step.

Outputs

birth_datetext: Their birthday, e.g. 1990-05-14. Null when not set.
idtext: The person's ID in Immich, for later steps.
is_favoritetrue/false: Whether they're marked as a favorite.
is_hiddentrue/false: Whether they're hidden from the People page.
nametext: Their name. Empty for someone not named yet.
photo_countnumber: How many photos and videos they're in.
urltext: Opens their photos in Immich.

Example output

{
  "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 videophototextRequired: The photo or video: its ID from an earlier step, such as a search, or its link in Immich.

Outputs

added_attext: When it was added to Immich.
cameratext: The camera or phone it was taken with, e.g. Google Pixel 9 Pro XL. Null when unknown.
citytext: The city it was taken in. Null when unknown.
countrytext: The country it was taken in. Null when unknown.
descriptiontext: Its description. Empty when it has none.
duration_secondsnumber: How long a video runs, in seconds. Null for a photo.
file_nametext: The name of the file it was added from, e.g. IMG_2041.jpg.
file_size_bytesnumber: The size of the original file, in bytes.
heightnumber: Its height in pixels.
idtext: The photo or video's ID in Immich, for later steps.
is_archivedtrue/false: Whether it's in the archive rather than the timeline.
is_favoritetrue/false: Whether it's one of your favorites.
is_trashedtrue/false: Whether it's in the trash.
latitudenumber: Where it was taken, north to south. Null when unknown.
longitudenumber: Where it was taken, east to west. Null when unknown.
peoplelist: The named people Immich recognised in it. Always empty in Find photos by description results: get the photo for them.
ratingnumber: Its star rating, 1 to 5. Null when it has none.
statetext: The state or region it was taken in. Null when unknown.
taken_attext: When it was taken, e.g. 2025-01-31T13:13:17Z.
taken_at_localtext: The time where it was taken, as the camera's clock showed it, e.g. 2025-01-31T14:13:17.
typetext: What it is: photo, video, audio or other.
urltext: Opens it in Immich, e.g. https://photos.example.com/photos/7d8fe1ec-ff44-4277-904f-fea0cfbfb7b0.
widthnumber: Its width in pixels.

Example output

{
  "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

AlbumalbumtextRequired: Pick an album, or give an album's ID or link from an earlier step.

Outputs

cover_photo_idtext: The ID of the photo shown as its cover.
created_attext: When it was made.
descriptiontext: Its description. Empty when it has none.
end_datetext: The day its latest photo or video was taken. Null when it's empty.
has_shared_linktrue/false: Whether a shared link opens it.
idtext: The album's ID in Immich, for later steps.
item_countnumber: How many photos and videos it holds.
nametext: The album's name.
owner_emailtext: Its owner's email.
owner_nametext: Who owns it.
sharedtrue/false: Whether it's shared with other people or by a link.
start_datetext: The day its earliest photo or video was taken, e.g. 2025-04-27. Null when it's empty.
updated_attext: When it last changed.
urltext: Opens it in Immich, e.g. https://photos.example.com/albums/f0b9c2d8-e4cc-4bdb-9c36-cda764479bd0.

Example output

{
  "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 manycountnumber: How many to pick, up to 100.From 1 to 100. Default: 1.
Typemedia_typetext: Photos, videos, or both.One of: all (Photos and videos), photos (Photos only), videos (Videos only). Default: photos.
Taken aftertaken_afterdate and time: Only ones taken after this moment.
Taken beforetaken_beforedate and time: Only ones taken before this moment.
Peoplepeoplelist: Only ones with all of these people in them.
Albumalbumtext: Only ones in this album.
Countrycountrytext: Only ones taken in this country.
Citycitytext: Only ones taken in this city.
Favorites onlyfavorites_onlytrue/false: Only your favorites.Default: false.
Look inlook_intext: Your timeline, or the photos and videos you've archived.One of: timeline, archive. Default: timeline.

Outputs

countnumber: How many came back.
idslist: The IDs of the photos and videos, ready for steps that take several, such as Add photos to an album.
itemslist: The photos and videos picked.

Example output

{
  "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 containsname_containstext: Only albums whose name contains this text.
Shared albums onlyshared_onlytrue/false: Only albums shared with other people or by a link.Default: false.
Max resultsmax_resultsnumber: How many to list at most, up to 1,000.From 1 to 1000. Default: 100.

Outputs

countnumber: How many came back.
has_moretrue/false: Whether more matched than Max results.
itemslist: The albums.
totalnumber: How many matched in all, including any past Max results.

Example output

{
  "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 containsname_containstext: Only people whose name contains this text.
Include unnamed peopleinclude_unnamedtrue/false: Also list the faces Immich found that nobody has named yet.Default: false.
Include hidden peopleinclude_hiddentrue/false: Also list people hidden from the People page.Default: false.
Max resultsmax_resultsnumber: How many to list at most, up to 1,000.From 1 to 1000. Default: 100.

Outputs

countnumber: How many came back.
has_moretrue/false: Whether more matched than Max results.
itemslist: The people.
totalnumber: How many matched in all, including any past Max results.

Example output

{
  "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

Albumalbumtext: Only links to this album.
Max resultsmax_resultsnumber: How many to list at most, up to 1,000.From 1 to 1000. Default: 100.

Outputs

countnumber: How many came back.
has_moretrue/false: Whether more matched than Max results.
itemslist: The shared links.
totalnumber: How many matched in all, including any past Max results.

Example output

{
  "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 videosphotoslistRequired: The photos and videos: their IDs, such as the ids a search step returned, or their links in Immich.

Outputs

days_in_trashnumber: How many days they stay in the trash before Immich deletes them for good.
idslist: The IDs of the photos and videos, ready for steps that take several, such as Add photos to an album.
trashed_countnumber: How many were moved to the trash.

Example output

{
  "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

AlbumalbumtextRequired: Pick an album, or give an album's ID or link from an earlier step.
Photos and videosphotoslistRequired: The photos and videos: their IDs, such as the ids a search step returned, or their links in Immich.

Outputs

album_idtext: The album's ID.
album_nametext: The album's name.
album_urltext: Opens the album in Immich.
item_countnumber: How many photos and videos the album holds now.
not_in_album_countnumber: How many weren't in the album to begin with.
not_removedlist: Any that couldn't be taken out, and why. Empty when all were.
removed_countnumber: How many were taken out.

Example output

{
  "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 videosphotoslistRequired: The photos and videos: their IDs, such as the ids a search step returned, or their links in Immich.

Outputs

idslist: The IDs of the photos and videos, ready for steps that take several, such as Add photos to an album.
restored_countnumber: How many were restored.

Example output

{
  "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

Typemedia_typetext: Photos, videos, or both.One of: all (Photos and videos), photos (Photos only), videos (Videos only). Default: all.
Taken aftertaken_afterdate and time: Only ones taken after this moment.
Taken beforetaken_beforedate and time: Only ones taken before this moment.
Peoplepeoplelist: Only ones with all of these people in them.
Albumalbumtext: Only ones in this album.
Countrycountrytext: Only ones taken in this country.
Citycitytext: Only ones taken in this city.
Favorites onlyfavorites_onlytrue/false: Only your favorites.Default: false.
File namefile_nametext: Only ones whose file name contains this, e.g. IMG_20.
Descriptiondescriptiontext: Only ones whose description contains this text.
Look inlook_intext: Your timeline, or the photos and videos you've archived.One of: timeline, archive. Default: timeline.
Orderordertext: Newest or oldest first, by when they were taken.One of: newest (Newest first), oldest (Oldest first). Default: newest.
Max resultsmax_resultsnumber: How many to get at most, up to 1,000.From 1 to 1000. Default: 50.
Pagepagenumber: 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

countnumber: How many came back.
has_moretrue/false: Whether there are more on the next page.
idslist: The IDs of the photos and videos, ready for steps that take several, such as Add photos to an album.
itemslist: The photos and videos found.
next_pagenumber: The page to ask for next. Null on the last page.

Example output

{
  "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 videophototextRequired: The photo or video: its ID from an earlier step, such as a search, or its link in Immich.
Favoritefavoritetext: 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.
Archivearchivetext: 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.
Descriptiondescriptiontext: A new description, replacing the old one. Leave empty to keep it.
Clear the descriptionclear_descriptiontrue/false: Remove its description altogether.Default: false.
Date takentaken_atdate and time: When it was taken. It keeps its own time zone, so Immich shows the time you pick.
Ratingratingtext: 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_attext: When it was added to Immich.
cameratext: The camera or phone it was taken with, e.g. Google Pixel 9 Pro XL. Null when unknown.
citytext: The city it was taken in. Null when unknown.
countrytext: The country it was taken in. Null when unknown.
descriptiontext: Its description. Empty when it has none.
duration_secondsnumber: How long a video runs, in seconds. Null for a photo.
file_nametext: The name of the file it was added from, e.g. IMG_2041.jpg.
file_size_bytesnumber: The size of the original file, in bytes.
heightnumber: Its height in pixels.
idtext: The photo or video's ID in Immich, for later steps.
is_archivedtrue/false: Whether it's in the archive rather than the timeline.
is_favoritetrue/false: Whether it's one of your favorites.
is_trashedtrue/false: Whether it's in the trash.
latitudenumber: Where it was taken, north to south. Null when unknown.
longitudenumber: Where it was taken, east to west. Null when unknown.
peoplelist: The named people Immich recognised in it. Always empty in Find photos by description results: get the photo for them.
ratingnumber: Its star rating, 1 to 5. Null when it has none.
statetext: The state or region it was taken in. Null when unknown.
taken_attext: When it was taken, e.g. 2025-01-31T13:13:17Z.
taken_at_localtext: The time where it was taken, as the camera's clock showed it, e.g. 2025-01-31T14:13:17.
typetext: What it is: photo, video, audio or other.
urltext: Opens it in Immich, e.g. https://photos.example.com/photos/7d8fe1ec-ff44-4277-904f-fea0cfbfb7b0.
widthnumber: Its width in pixels.

Example output

{
  "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

AlbumalbumtextRequired: Pick an album, or give an album's ID or link from an earlier step.
Namenametext: A new name. Leave empty to keep it.
Descriptiondescriptiontext: A new description. Leave empty to keep it.
Cover photocover_phototext: A photo in the album to show as its cover: its ID or its link in Immich.

Outputs

cover_photo_idtext: The ID of the photo shown as its cover.
created_attext: When it was made.
descriptiontext: Its description. Empty when it has none.
end_datetext: The day its latest photo or video was taken. Null when it's empty.
has_shared_linktrue/false: Whether a shared link opens it.
idtext: The album's ID in Immich, for later steps.
item_countnumber: How many photos and videos it holds.
nametext: The album's name.
owner_emailtext: Its owner's email.
owner_nametext: Who owns it.
sharedtrue/false: Whether it's shared with other people or by a link.
start_datetext: The day its earliest photo or video was taken, e.g. 2025-04-27. Null when it's empty.
updated_attext: When it last changed.
urltext: Opens it in Immich, e.g. https://photos.example.com/albums/f0b9c2d8-e4cc-4bdb-9c36-cda764479bd0.

Example output

{
  "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"
}

ActionsCopy Anchor Link

Add photos to an albumCopy Anchor Link

Inputs

Outputs

Create a shared linkCopy Anchor Link

Inputs

Outputs

Create an albumCopy Anchor Link

Inputs

Outputs

Delete a shared linkCopy Anchor Link

Inputs

Outputs

Delete an albumCopy Anchor Link

Inputs

Outputs

Download a photo or videoCopy Anchor Link

Inputs

Outputs

Find photos by descriptionCopy Anchor Link

Inputs

Outputs

Get a personCopy Anchor Link

Inputs

Outputs

Get a photo or videoCopy Anchor Link

Inputs

Outputs

Get an albumCopy Anchor Link

Inputs

Outputs

Get random photosCopy Anchor Link

Inputs

Outputs

List albumsCopy Anchor Link

Inputs

Outputs

List peopleCopy Anchor Link

Inputs

Outputs

List shared linksCopy Anchor Link

Inputs

Outputs

Move photos or videos to the trashCopy Anchor Link

Inputs

Outputs

Remove photos from an albumCopy Anchor Link

Inputs

Outputs

Restore photos or videos from the trashCopy Anchor Link

Inputs

Outputs

Search photos and videosCopy Anchor Link

Inputs

Outputs

Update a photo or videoCopy Anchor Link

Inputs

Outputs

Update an albumCopy Anchor Link

Inputs

Outputs

On this page

Actions

Add photos to an album

Create a shared link

Create an album

Delete a shared link

Delete an album

Download a photo or video

Find photos by description

Get a person

Get a photo or video

Get an album

Get random photos

List albums

List people

List shared links

Move photos or videos to the trash

Remove photos from an album

Restore photos or videos from the trash

Search photos and videos

Update a photo or video

Update an album