Immich + Home Assistant: Photo search from your dashboard

I’ve had Immich running for about eight months now, and it’s genuinely good at what it does. The facial recognition is accurate enough that I stopped worrying about it misidentifying people. The search works. But it sat there doing its job in isolation, and I kept thinking: why can’t I pull recent photos into Home Assistant? Why can’t I trigger a search from an automation? Turns out, you can. It takes some wiring, and the result is less elegant than you’d hope, but it’s useful.

The actual use case

Home Assistant is where I check on my house. It’s where I see if the front door camera caught something. It made sense to me that I should be able to pull my recent photos into a dashboard—not for real-time monitoring, but for quick “what did I take pictures of this week” without switching apps. The secondary goal was simpler: expose Immich to Home Assistant’s automation engine so I could theoretically trigger searches programmatically. Neither thing is easy because Immich’s API is real but not especially homelab-friendly.

What you need: REST sensors and templates

Immich ships with a REST API. It’s documented. The problem is authentication: Immich uses API keys, and Home Assistant’s REST sensor support is functional but not featureful. You’ll need to set up authentication headers manually, which means your API key lives in your HA config. That’s… fine if your Home Assistant instance is only accessible on your local network, which it should be.

Start by creating an API key in Immich. Go to Account Settings, then API Keys, and generate one. Give it a boring name. You’ll add it to Home Assistant like this:

rest:
  - resource: "http://immich.local:2283/api/search/smart"
    method: GET
    params:
      query: "cat"
    headers:
      x-immich-user-id: "your-user-uuid"
      Authorization: "Bearer your-api-key"
    scan_interval: 3600
    sensor:
      - name: "Immich Cat Photos"
        unique_id: immich_cat_photos
        value_template: "{{ value_json.assets | length }}"
        json_attributes:
          - assets

This will query Immich’s smart search endpoint every hour looking for “cat” and expose the count as a sensor. The catch: you can’t dynamically change the query without editing YAML and restarting. If you want to search for different things, you need different sensors. That’s tedious.

The realistic approach: thumbnails and recent assets

Rather than trying to build a powerful search interface—which Home Assistant is not—I settled on pulling recent assets and displaying them in a Markdown card. This is more useful than it sounds.

rest:
  - resource: "http://immich.local:2283/api/search/metadata"
    method: GET
    params:
      take: "5"
      order: "desc"
    headers:
      x-immich-user-id: "your-user-uuid"
      Authorization: "Bearer your-api-key"
    scan_interval: 1800
    sensor:
      - name: "Immich Recent"
        unique_id: immich_recent
        value_template: "{{ value_json.assets | length }}"
        json_attributes:
          - assets

Now you have the metadata for your five most recent photos. To display them, use a template that builds HTML:

- type: markdown
  content: |
    ## Recent Photos
    {% set assets = state_attr('sensor.immich_recent', 'assets') %}
    {% if assets %}
    {% for asset in assets %}
    [![](http://immich.local:2283/api/assets/{{ asset.id }}/thumbnail?size=preview)](http://immich.local:2283/api/assets/{{ asset.id }}/thumbnail?size=preview)
    {% endfor %}
    {% endif %}

This works. You get a grid of thumbnails that refresh every thirty minutes. Clicking them opens the full image in a new tab. It’s not Instagram, but when you walk past your Home Assistant dashboard and see the photos you took yesterday, it lands better than you’d expect.

Where the friction lives

The honest part: Immich’s API is powerful but assumes you’re building a full-featured client. It’s not designed for simple embedding. There’s no way to ask for “all photos taken in the last 24 hours” without some creative filtering. The user UUID requirement is clunky. And if you use Immich’s library feature to share albums with family members, pulling photos as the primary account owner means your family sees what you backed up, not their own backup. That’s a security quirk worth noting.

The bigger frustration: Immich changes its API between versions. I went from 1.92 to 1.106 and one of my REST endpoints broke because the response schema shifted. Nothing catastrophic—Home Assistant just stopped pulling data—but it was another reminder that integrations like this are held together with YAML and hope.

Why I keep it anyway

It’s not elegant. It doesn’t give you powerful search from your dashboard. But having recent photos visible without opening another app is genuinely nice. And knowing that Immich is just a REST call away means automations are possible if you ever need them. I haven’t built one yet, but the architecture is there: you could theoretically trigger a camera to take a photo, wait for Immich to ingest it, then alert you if it detects a person in the frame. That’s worth keeping the setup around for.

If you’re expecting a Home Assistant integration out of the box, you’ll be disappointed. If you’re comfortable with REST sensors and template cards, and you just want Immich to be a little less isolated, this works fine. The setup takes maybe thirty minutes if you’ve done Home Assistant config before, longer if you haven’t. Worth it? Depends on whether “see what I photographed today” from your HA dashboard actually changes how you use it. For me, it did.

Explore Immich in our AI Homelab Toolkit.