How to use immich API for dummies?

[aisbergde]

The feature

immich administrators can automate external libraries to be rescanned in the GUI. This is great, but it is limited.
On the other side, the API has needed functionality:
https://immich.app/docs/api/scan-library/
contains some code, how to refreshAllFiles
https://immich.app/docs/api/remove-offline-files

I want to call this and automate. But how?
There are cURL examples, but I have no idea, what to do and how to use them. I even don't know what cURL is.

Could this be explained in the docs for dummies like me? Some first steps, how to start
Or maybe some links to existing docs. Just to get a point, where to start. I have no idea, how to use the API at all. https://immich.app/docs/api/introduction is empty, and the next page starts with code examples.

And I would like to know if these library commands can be used also with the default library, especially to remove offline files.
How to mark assets as offline, I found a manual way from the maintenance page to export JSON over a script into the database. I can't automate, but at least it is a way.

Platform

• Server
• Web
• Mobile

[aviv926]

I can try to explain about the use of Curl here, but I think it is less relevant because as you mentioned it is something that should be in the documentation.
In fact I would be happy to document everything the thing is I still don't understand everything 100% so it requires help from the development team, I guess in Discord or after there is a PR (even a draft) it will be easier to start making things happen.

[aisbergde]

At least a starting point would be fine. I don't know where to start. It looks like, there are so many possibilities. I am fine to start with databases, because they are my daily business. But I am a typical Windows guy, using GUI and so on :-)

[jrasm91]

We have an http API, so using it implies some level of understanding around http requests and responses. If you aren't a programmer or have no experience with sending and receiving http requests, educating you on those topics is a bit out of scope for Immich and our documentation pages. Something we could do, is publish python and typescript modules/packages that would make it easier to use. Something like "install python" and then "copy paste this code". But, again, writing code still implies some level of programming or technical background.

[aisbergde]

I have some experience. I used the Service Now API to access it, using Phyton, to get data and to import into SQL Server. But the Service Now API is well documented and I found Python scripts, I could use and adapt. There was a starting point and I could start and solved all requirements.

Here I have no idea, where even to start. And I think, it should be even easier to use the API, if I don't want to import data, but if I only want to trigger some actions.

The main issue, normally I work on Windows. But my Windows knowledge is not helpful here, because immich is running on docker on my Synology. Synology is running an Unix / Linux

So, I am a developer for decades, but I am a BI developer, and I am restricted to Windows, because I use Microsoft software, which requires Windows: Visual Studio, SQL Server Management Studio. Even, if I wanted to switch from Windows, I couldn't.

I think, there should be some cron jobs, and these cron jobs need to call the API from time to to time.

[aviv926]

You can view example of python code by using example section:

[MysterSoldier]

We definitely need a step by step for beginners. I meen like break it down Barney level. 1st day of 6th grade type step by step

[aisbergde]

My desired API usage job is currently limited to the question:
How to setup a cron job inside the immich installation to rescan libraries using the API, if the GUI accessible cron job doesn't work or doesn't do enough?

[martabal]

FYI, automatic scanning does not work but should be back in the next release

[aisbergde]

I changed it from feature request into Q&A. To avoid it to be closed.
Still hope to learn, how to use the API.

[TechSupport26]

Based on what has been shown here I realised that I had to change the url to include the name of the API key.

http://192.168.1.10:2283/api_key_name/

Some context. I was setting up Heimdall and wanted to get the API for Immich to work.
Thanks.

[alextran1502]

@TechSupport26 if you are talking about connecting on your mobile app it is literal http://localip:2283/api not api key

[TechSupport26]

Perhaps my comment is not in the right place? No I am not talking about my mobile app.

I was just referring to the url including the name of the API that was made. Perhaps saying api_key_name is not accurate?
Perhaps I am wrong as Heimdall is not showing any additional information with the API in place.

not api key

I mean the name of the API key not the key itself.

Maybe I am still missing something.

[bo0tzz]

It should just literally be the text api

[TechSupport26]

I see.

When I use the name of the key, I just get html
What I needed was http://localip:2283/api/api-keys or something like that.
Heimdall still does not work but that is probably not for here.

Thanks for repeating yourselves.

[njobrien1006]

I wasn't able to find documentation either (how to authorize with an API key).

Appears you need another header item x-api-key with a user's API key.

Example Windows Curl:

curl -L "192.168.1.245:30041/api/assets/bulk-upload-check" -H "Content-Type: application/json" -H "Accept: application/json" -H "x-api-key: YoUrReAlYLonGUserAPIKeYFroMWeBui" -d "{\"assets\": [{\"checksum\": \"string\", \"id\": \"string\"}]}"

Edit..........the documentation does have the info. However, is not displayed by default and you must hit Authorize at API Docs for it to appear.

[seajean]

Has the same issue, I wanna call the api with the api key to get the album and image data, but don't want to dive info the immich code, I can not find a way to do this

[jrasm91]

You can add the query param ?apiKey=<key> or the header x-api-key: <key>

[Zelnes]

Have a look at this answer

[profucius]

For anyone struggling to get a API call working to trigger the library scan, here is what I did:

First you need to create an API key by clicking your user icon at the top-right. Then click API Keys, and create a new one. Name it whatever, I named mine Automations. Copy the key to a Notepad.

In that same Notepad, a few lines down, paste this, then move the API key to where it says "APIKEYHERE"

curl -L -X GET "192.168.1.x:PORT/api/libraries" -H "Content-Type: application/json" -H "Accept: application/json" -H "x-api-key: APIKEYHERE"

Change the x in the IP address to your Immich IP address. Change the PORT to whatever the port number is.

Then open a CMD window on your Windows computer (if using CURL). Copy and paste the line from Notepad and hit enter to run it.

You'll get a response with a bunch of code looking stuff. The very first one looks like "id":"LONGIDCODE". You want to copy the LONGIDCODE from here, between the quote marks.

If you only created one library in your Immich, you should see only one ID. If you created multiple libraries, then you'll get multiple IDs. When you trigger a scan via the API, you have to do this for each library/ID individually. So the below steps, you may have to do it multiple times if you have multiple libraries.

Copy the ID(s) from above into your Notepad.

curl -L -X POST "192.168.1.x:PORT/api/libraries/IDCODE/scan" -H "Content-Type: application/json" -H "Accept: application/json" -H "x-api-key: APIKEYHERE"

Change the x and PORT and APIKEYHERE again, like you did in the first command. This time you also need to change the IDCODE to the new ID you just pasted into Notepad.

Now copy that whole line and paste into the CMD window and hit enter. It should call Immich and trigger the library scan. If it worked, your command result wont show any responses. Now go into Immich>Jobs and refresh the page, you should see it scanning Active.

If this worked, you're good to go! You can create a .bat file with the contents of your last command and save it to the desktop or somewhere else. Now you can just double click this file, and it will trigger Immich to update immediately. If you had multiple libraries, just put each of these commands on a new line and change the IDs in each one (leave all the API keys etc the same). Running the file will trigger all the libraries at once.

This is a crude guide, there are many ways you can clean this up and automate it further. For example I am using an automation script to dynamically get the IDs of each library and run the commands for them, within a deeper photo syncing script that I tie into Syncthing. The sky's the limit.