# Automation decisions and trigger API

Markdown version of <https://sam-dumont.github.io/immich-memories/docs/reference/automation-contract/>.

`immich-memories auto run` is the single daily entry point. It looks at your library, decides which one memory
is worth making today (a trip that ended last week, a birthday two days ago, last month's highlights, a year
nobody cut yet), makes it, and exits. Schedule it once a day and the films arrive on their own.

```bash
immich-memories auto suggest            # what would it make today, and why
immich-memories auto run --dry-run      # the decision, without the render
immich-memories auto run                # decide and do it
```

It works on a plain NAS, and makes the same cuts you would get by hand there; a GPU or a model makes them better.

**Diagram: Once a day it checks what's due and makes one film at most.** [(image)](https://sam-dumont.github.io/immich-memories/diagrams/seq-scheduled-run.svg)

```text
┌──────────────────────────────────┐
│          A timer fires           │
│      in-process, auto run,       │
│       or POST /api/trigger       │
└─────────────────┬────────────────┘
                  │
                  │
                  │
                  │
                  ▼
┌──────────────────────────────────┐
│                                  │
│           Another run            │
│         holds the lock?          │
└──────────────────────────────────┘
                  │
                  │
                  ├──────────────────────────────────────┐
                  │                                      │
                  ▼                                      ▼
┌──────────────────────────────────┐  ┌─────────────────────────────────────┐
│                                  │  │                                     │
│                                  │  │               Cooldown              │
│              stops               │  │            still active?            │
│  HTTP: 409; no attempt written   │  │24 h by default, skipped when forced;│
│                                  │  │    pending uploads retried first    │
└──────────────────────────────────┘  └─────────────────────────────────────┘
                                                         │
                                                         │
                  ┌──────────────────────────────────────┤
                  │                                      │
                  ▼                                      ▼
┌──────────────────────────────────┐  ┌─────────────────────────────────────┐
│                                  │  │             Nothing due?            │
│             skipped              │  │ month, trip, season, holiday, album,│
│         cooldown active          │  │ person month, or a month never made │
└──────────────────────────────────┘  └─────────────────────────────────────┘
                                                         │
                                                         │
                  ┌──────────────────────────────────────┤
                  │                                      │
                  ▼                                      ▼
┌──────────────────────────────────┐  ┌─────────────────────────────────────┐
│                                  │  │                                     │
│             skipped              │  │             The film run            │
│     no eligible candidates,      │  │                fails?               │
│rare: old months fill quiet nights│  │        generate --source=auto       │
│                                  │  │              2 h limit              │
└──────────────────────────────────┘  └─────────────────────────────────────┘
                                                         │
                                                         │
                  ┌──────────────────────────────────────┤
                  │                                      │
                  ▼                                      ▼
┌──────────────────────────────────┐  ┌─────────────────────────────────────┐
│              failed              │  │              Completed              │
│     from the second failure:     │  │          one film, uploaded         │
│       24 h, 3 days, 7 days       │  │             if you asked            │
└──────────────────────────────────┘  └──────────────────┬──────────────────┘
                                                         │
                                                         │
                                                         │
                                                         │
                                                         │
┌──────────────────────────────────┐                     │
│           Notification           │                     │
│       success or failure,        │◄────────────────────┘
│     if notifications are on      │
└──────────────────────────────────┘
```

Arrows:

- A timer fires → Another run holds the lock?
- Another run holds the lock? → stops
- Another run holds the lock? → Cooldown still active?
- Cooldown still active? → skipped
- Cooldown still active? → Nothing due?
- Nothing due? → skipped
- Nothing due? → The film run fails?
- The film run fails? → failed
- The film run fails? → Completed
- Completed → Notification

## Docker: switch on the built-in timer

In Docker the container's only process is the web UI, so the timer lives there. One setting:

```yaml
advanced:
  automation:
    enabled: true        # default false
    daily_at: "09:00"    # the container's local time (set TZ=)
```

Or put `IMMICH_MEMORIES_AUTOMATION__ENABLED: "true"` and `IMMICH_MEMORIES_AUTOMATION__DAILY_AT: "09:00"`
in the app's Compose `environment:` block. A line in `.env` alone does not reach the container. Recreate
with `docker compose up -d`. While those Compose lines are absent, **Settings > Automation** shows
`enabled` and `daily_at` too.

`upload.enabled: true` delivers manual and automatic films to Immich, into `upload.album_name`. The film
gets the same description and tags a manual upload gets, a retry included
([What Immich sees](https://sam-dumont.github.io/immich-memories/docs/run/privacy.md#what-immich-sees)). Confirmed delivery removes the local copy.

The UI process then runs the same `auto run` decision once a day, with the same lock, history, upload
retry and notifications as the CLI. A container that was down at `daily_at` catches up when it starts.
If the day's run already happened, it waits for tomorrow.

### What counts as the day's run

| Attempt | Counts as the day's run |
| - | - |
| made a film, or tried and failed | yes |
| decided nothing is worth a film (`skipped`, reason `no eligible candidates` or `nothing worth a film: …`) | yes |
| an unforced `auto run` from the shell, the installed job or an HTTP trigger without `?force=true` | yes: they can't be told apart from the timer |
| a forced one: `auto run --force`, `POST /api/trigger?force=true`, **Run this suggestion** in the web UI | no: it's an extra film you asked for |
| a dry run (**Check eligibility**, `auto run --dry-run`), finished or still running | no |
| a `cooldown active` skip (what most HTTP triggers get back) | no |
| a **Run this suggestion** whose candidate was gone by then | no |
| an attempt whose process died | no |

When the timer waits, the log says which run it counted. A period the child read and judged empty ends
as one `skipped` attempt with no completed run behind it: the 24 h cooldown is untouched, and that
candidate sits out for 7 days.

A manual `auto run` in progress holds the automation lock: the timer's attempt comes back `skipped`
("automation already running") before it records anything, so `auto history` and `auto status` never show
it, and the timer tries again at its next poll (every 30 seconds). When the timer's own run is skipped for
the cooldown (it caught up at 14:00 yesterday, say), it tries again once the cooldown ends, the same day.

A manual `generate` in progress holds a different lock, the pipeline lock. The timer's attempt does start,
its child `generate` can't get the pipeline lock, and the attempt ends `failed`, not `skipped`.

An attempt whose process died mid-run (a killed container, a reboot) reads `failed`, reason
`interrupted: …`, everywhere status is shown. The next run, the web server's timer or
`immich-memories auto status` ends it for good, with one failure notification. A status read such as
`/health/ready` only reports it and changes nothing.

`/health/ready` shows the timer under `in_process_scheduler`. After a restart it starts from the last
attempt in the store, so `last_fired_at`, `last_outcome` and `last_reason` are filled in.

## Bare metal: auto install

```bash
immich-memories auto install --hour 9
```

This writes a launcher at `~/.immich-memories/bin/immich-memories-auto` and the scheduler files: a launchd
plist on macOS, a systemd user timer on Linux, or a crontab line to paste elsewhere. It prints
**Activate:** and **Deactivate:** commands and runs neither: run the activation command to start the
schedule. The launcher looks `immich-memories` up on every fire, so an upgrade in place needs no
reinstall.

The installed job reads `automation.cooldown_hours` on every run; `--cooldown N` pins a number into the
scheduler command instead. An older install: [Upgrading](https://sam-dumont.github.io/immich-memories/docs/run/maintenance/upgrading.md#scheduled-runs).

There is one managed launcher per operating-system user, and one launchd job or systemd timer.
Installing with another `--config` replaces that user's existing schedule; it does not add a
second one. Use separate operating-system users or containers for independent schedules.
The launcher stays under `~/.immich-memories/bin` even with an explicit config.

On headless Linux, enable lingering so the user timer survives logout:

```bash
loginctl enable-linger "$USER"
```

Uninstall deletes the launcher and scheduler files without unloading a running schedule, so run the
printed deactivation command first: `launchctl unload` on macOS, `systemctl --user disable --now
immich-memories-auto.timer` on Linux. Then `immich-memories auto install --uninstall`, and on Linux
`systemctl --user daemon-reload`. For cron, remove the pasted line before deleting its launcher.

Three things a scheduled job does differently from your shell:

- it does not inherit your environment. `auto install` copies `PATH` and the ACE-Step and torch variables it
  knows, nothing else, so credentials belong in the config file;
- it refuses a git worktree or a checkout behind its upstream, because a nightly job on stale code looks fine
  in the logs (`--force` overrides);
- `--config` goes before `auto`, and the installed job keeps the resolved path.

On macOS a missed job runs when the Mac wakes; launchd does not wake it.

The launchd job writes its wrapper output to `auto.log` and `auto-error.log` in `~/.immich-memories/logs/`
(next to the config file when you installed with `--config`). The systemd unit sets no `StandardOutput`,
so its output goes to the user journal, which a user outside `systemd-journal` may not be allowed to read.
The per-attempt transcript under the cache is always readable by its owner: see [where a scheduled run's logs go](https://sam-dumont.github.io/immich-memories/docs/make/automate.md#where-a-scheduled-runs-logs-go).

## How it picks one memory

Fifteen detectors propose candidates, hard rotation rules reject some, the rest are scored, and the top one is
made. The score ranks memories against each other and never touches which pictures go in a film. That is
the editor's job: see [How it chooses](https://sam-dumont.github.io/immich-memories/docs/how-it-chooses/overview.md).

| Detector | Proposes | Score |
| - | - | - |
| Yearly | past years with content, after 15 January | 0.8, 10 % off per year of age, floor 0.24 |
| Birthday | a person whose birthday was 2 to 60 days ago, with at least 50 pictures on 3 days in the film's windows | 0.75 × [closeness](#closeness) × their pictures against the busiest person's (floor 0.5) |
| Monthly | the latest completed month, if not made yet | 0.7, and it never looks further back |
| Activity burst | a month, once it has ended, with more than 2× the rolling 12-month average | 0.7 once over the threshold |
| Trip | trips in the trailing year, 7 days after coming home | up to 0.75, by length (14 days) × pictures (200) |
| Person spotlight | the five most-pictured people | 0.6 × their share of the top person's count (floor 0.2) × closeness |
| Multi-person | pairs who appear together on at least 10 pictures last year, the year the film reads | 0.55, by shared pictures up to 500, × the pair's average closeness |
| On this day | today, when its month has content in 5+ prior years | 0.35 × prior years / 10, capped at 0.35; month counts do not prove pictures exist on this exact date |
| Special day | a catalogued day whose anniversary is within 3 days | 0.8, ×1.0 for a decade, ×0.85 for a half-decade, ×0.6 otherwise |
| Saved group | last year's film of each [saved group](https://sam-dumont.github.io/immich-memories/docs/run/multi-account.md#saved-groups), once | 0.65 × the group's average closeness, counted as multi-person |
| Season | the season that just ended, from 3 to 30 days after its end, once per season-year. At least 40 pictures on 6 days. Needs the home base: without one there is no hemisphere and no season film | 0.6 |
| Holiday | Christmas, New Year's Day, Easter, a holiday of the home base's country, or one you list in `extra_holidays`, from 3 days after it, up to a year back, and only when your pictures show you kept it: in at least 3 years, the day holds 10 pictures or more and at least twice the median of the 4 days around it. The date alone never qualifies. The film reads every year back to 30. Once per holiday-year, however many years a film of it was made over | 0.6 × (0.5 + 0.5 × years the day stood out, up to 5 / 5) |
| Album | one of your albums never filmed (20 pictures or more), or one that grew by 30 pictures and to 1.5× the size it had at its last film. Albums spanning more than six months (a phone's Recents, Favorites, Live Photos) are left out. Shared albums only with `include_shared_albums` | 0.55 |
| Backfill | a month of this year or last with 20 pictures or more and no film, newest first. The latest completed month is the monthly detector's | 0.35 |
| Person month | the last completed month of each close person, at least 15 pictures on 4 days. The two months before it are backfill | 0.6, and 0.35 for the two earlier months |

Then, in order: a 1.2× boost for a memory that does not exist yet, recency (linear decay over 365 days from
when the memory is timely, floor 0.5), content richness (up to 30 % of the score, log scale), and a same-type
cooldown (0.3× for 7 days, 0.7× for 30 days). Per-type caps: 3 per type, 1 for on-this-day, special day,
season, holiday, album, backfill and person month, 2 for multi-person. Backfill and person months render as a
monthly film, but each has a category, a cap and a cooldown of its own, so they never use up the monthly's.

The rotation rules are hard. If every candidate is rejected the run is skipped; nothing relaxes a rule to get
another video out:

- a monthly review cannot run twice in the same calendar month (backfill and person months are not monthly reviews, so a month film of either does not count); the monthly detector proposes only the latest completed month, while activity bursts can propose months from the trailing year;
- the previous category cannot repeat, except backfill, which fills quiet nights and may follow itself (anything fresher still outscores it);
- a category cannot appear more than twice in the last six completed automatic runs, except backfill, which runs every quiet night;
- a person cannot come back if they were in either of the last two person runs.

Birthdays fire 2 days after the date and trips 7 days after coming home, so the phone has uploaded.
Trips need `trips.homebase_latitude` and `trips.homebase_longitude` (see
[Home and people](https://sam-dumont.github.io/immich-memories/docs/get-started/who-is-who.md)). Special days come from the catalogue `discover-days`
writes. A birth date you gave the people store wins over the one Immich holds. Automation passes that resolved month and day explicitly to `generate --birthday`, including a leap-day birthday.

`auto suggest` prints eligible candidates in rank order with their reasons, then why a detector proposed
nothing where it could have: no home base for a season, a birthday under 50 pictures, a close person with
too little last month, albums left out for spanning more than six months. It also names failure-backoff
skips. It does not list candidates the rotation rules rejected: `auto status` shows those.

A candidate that failed twice in a row waits before it comes back: 24 hours, then 3 days after a third
failure, then 7 days. One failure never counts, and a success clears the streak.

## Closeness

A birthday film of a child is worth more than one of someone you met twice, however many pictures each has.
Birthdays, spotlights, pairs and saved groups are scored by how close the [people list](https://sam-dumont.github.io/immich-memories/docs/get-started/who-is-who.md)
says each person is:

| Who | Weight |
| - | - |
| inner tier, or a partner, child or parent you confirmed | 1.0 |
| recurring | 0.6 |
| episodic | 0.3 |
| event | 0.15 |

A pair or a group takes the average of its people. Someone the list says nothing about keeps the full
weight, so a library that never ran the people scan scores everyone at 1.0. The same list decides who gets a monthly film:
inner tier or a confirmed partner, child or parent.

Hand-made films count. A season, holiday, month or per-person month you made yourself with `generate` is the
same memory as the one `auto` would propose, so it is not proposed again. An album film made by hand is matched
by the album's dates, and an automatic one carries the album's picture count, so the album comes back only after it
grows again.

```yaml
advanced:
  automation:
    detect_seasons: true          # all five on by default
    detect_holidays: true
    detect_albums: true
    detect_person_monthly: true
    backfill_months: true
    extra_holidays:               # your own days, "MM-DD: name"
      - "12-06: Saint Nicholas"
    include_shared_albums: false  # albums other people shared with you
```

The thresholds above are fixed. Holidays come from the country the home base is in, as Immich's own
geodata names it. With no known country, the detector proposes Christmas, New Year's Day, Easter and
your `extra_holidays`.

## Across accounts, and saved groups

With a [second Immich account](https://sam-dumont.github.io/immich-memories/docs/run/multi-account.md) connected, name the accounts automation reads:

```yaml
advanced:
  automation:
    accounts: ["primary", "partner"]  # empty reads the primary alone
    detect_groups: true               # the default
```

The list is exactly what is read: `["partner"]` alone leaves the primary library out, and trips with it. Every
candidate but a trip or an album carries that scope to its `generate --accounts` run; trips always come from
the primary account, and an album film reads that one album.

`detect_groups` proposes one `multi_person` film of last year for each saved group (`people group add`). A
group's film is not proposed again once made, and a group none of whose people is among the most-pictured
people discovery counts is skipped. It shares the multi-person cap and rotation rules. The whole walkthrough:
[A second Immich account](https://sam-dumont.github.io/immich-memories/docs/run/multi-account.md#what-automation-does-across-accounts).

## What auto run does, exactly

One action per run, one memory per invocation: retry the oldest pending upload if there is one, otherwise make the top candidate.

The cooldown (`--cooldown`, default `advanced.automation.cooldown_hours`, 24) runs from the start of the last
completed automatic film that wasn't forced, with 30 minutes of slack so a daily timer fires every day.
`auto status`, the built-in timer and the HTTP trigger read the same cooldown.

| Started by | Skips the cooldown | Starts the next one |
| - | - | - |
| the built-in timer, the installed job, `auto run`, `POST /api/trigger` | no | yes |
| `auto run --force`, `POST /api/trigger?force=true`, **Run this suggestion** | yes | no |
| `generate`, a web UI render | not an automatic run | no |

A forced film still counts for the rotation rules; it just never pushes back the next scheduled film.

`--candidate KEY` runs one exact `memory_key` from `auto suggest --json`. The rotation rules still apply,
`--force` skips only the cooldown, and a key that isn't eligible any more fails rather than making something
else.

**Diagram: Every attempt ends one of four ways, and the lock always comes back.** [(image)](https://sam-dumont.github.io/immich-memories/diagrams/state-scheduled-attempt.svg)

```text
┌─────────────────────────────────┐
│                                 │
│            A trigger            │
│   timer, HTTP, or a suggestion  │
└────────────────┬────────────────┘
                 │
                 │
                 │
                 │
                 ▼
┌─────────────────────────────────┐
│          Take the lock          │
└─────────────────────────────────┘
                 │
                 │
                 ├─────────────────────────────┐
                 │                             │
                 ▼                             ▼
┌─────────────────────────────────┐  ┌───────────────────┐
│                                 │  │                   │
│          held elsewhere         │  │      running      │
│    HTTP: 409, no attempt row    │  │attempt row written│
└─────────────────────────────────┘  └─────────┬─────────┘
                                               │
                                               │
                                               │
                                               │
                                               │
┌─────────────────────────────────┐            │
│                                 │            │
│             skipped             │            │
│cooldown, nothing due, or nothing│            │
│   worth a film (sits out 7 d)   │            │
│             dry_run             │            │
│        auto run --dry-run       │            │
│            completed            │◄───────────┘
│      the film, or a pending     │
│       upload went through       │
│              failed             │
│   timeout, exit code, no film;  │
│      from the 2nd in a row,     │
│      backoff 24 h, 3 d, 7 d     │
└────────────────┬────────────────┘
                 │
                 │
                 │
                 │
                 ▼
┌─────────────────────────────────┐
│                                 │
│          lock released          │
│          in every case          │
└─────────────────────────────────┘
```

Arrows:

- A trigger → Take the lock
- Take the lock → held elsewhere
- Take the lock → running
- running → skipped; dry\_run; completed; failed
- skipped; dry\_run; completed; failed → lock released

The outcomes are `skipped`, `dry_run`, `completed` and `failed`. The first three exit 0, `failed` exits 1.

Quiet output is a stable JSON object with `runtime` as its first key: `auto run --quiet` turns
logging off and prints it as one line. Key a wrapper on `outcome`; `action` is `generation` or
`delivery_retry`.

An attempt killed mid-run reads `failed`, reason `interrupted: …`, as described
[above](#docker-switch-on-the-built-in-timer).

```json
{"runtime": {"version": "<running version>", "checkout": null, "commit": null, "upstream": null, "commits_behind": null, "stale": false}, "outcome": "dry_run", "action": "generation", "reason": "dry run", "candidate_key": "trip:2026-07-02:2026-07-09:", "category": "trip", "run_id": null, "error": null, "output_path": null, "recent_categories": ["monthly_review", "birthday"], "rejections": []}
```

An upload that keeps failing is dropped after `automation.max_delivery_attempts` (5) tries, with a
notification carrying the error; the video stays on disk.

When the output or cache volume runs low (`output.min_free_space_gb`, 5 GB by default), a completed run's
notification carries the warning, and a film that would not fit fails the attempt with the same message
before anything renders. On a headless cron deployment, that notification is the only place you see it.

Every attempt writes its full output to `automation-output/<attempt-id>.private.log` under the cache:
owner-readable, credentials redacted, downloadable from the **Runs** page.

`auto status` shows the running code's version and commit, the scheduler in use, the last attempt, the
cooldown, notification health and pending deliveries. It refreshes discovery and puts the outcome and
error under `suggestion` without naming the next candidate: `auto suggest` does that.

## Check on it

```bash
immich-memories auto status             # timer state, last attempt, cooldown and delivery health
immich-memories auto status --json      # the same, for a script or jq
immich-memories auto history --limit 5  # the last five films it made on its own
```

The `Scheduler:` line lists everything that wakes automation: `built-in timer (enabled, daily at 07:45 CEST,
next firing 2026-10-08 07:45)`, an installed `launchd`, `systemd` or `cron` unit, and
`external trigger (POST /api/trigger), last trigger 2026-10-07 07:45` once a trigger token is set or the
trigger API has been called. With none of them it starts with `none`. `--json` carries the same under
`scheduler.in_use` and `scheduler.summary`. The last trigger time is kept per host, beside the
automation lock.

While a run works, its log carries a `Phase …` line for each step, and at least one every 30 seconds or so.
Counted steps (preparation, the family-viewing check, the render) show `n/N`; a step that has gone quiet
repeats itself with `process alive; no new progress (Nm in this step)`.

`auto history` lists only completed automatic runs; a film you made with `generate` or the web UI is in
`runs list` ([runs](https://sam-dumont.github.io/immich-memories/docs/make/cli/runs.md)). In Docker, prefix each with `docker compose exec immich-memories`.

## Get told when it runs

Notifications go through [Apprise](https://github.com/caronc/apprise), so one URL per target covers ntfy,
Discord, Telegram, email and more than a hundred others. They are off by default. Use `ntfys` for HTTPS,
and a private, authenticated topic: anyone can read a public ntfy topic.

```yaml
advanced:
  notifications:
    enabled: true
    urls:
      - "ntfys://ntfy.sh/my-topic"
    on_success: true
    on_failure: true
```

```bash
immich-memories auto test-notification
```

`auto test-notification` sends one message to every URL and says whether it went through. It ignores the
pause that follows a failed delivery (`notifications.cooldown_hours`, 24), and a test that succeeds ends it.

Every rendered film sends a completion message: `auto run`, the Docker timer, plain `generate`, the web
UI's **Render** and `runs render`. Saving a cut without rendering sends none. The message carries the
memory type, the outcome, the duration, the output path and, once the film is uploaded, a direct Immich
link. A failure adds the last 300 characters of the redacted output, which is the error itself. No picture
unless you set `attach_thumbnail: true`. The URLs hold credentials, so `config show` masks them and the
database stores them encrypted.
Every key is in the [config reference](https://sam-dumont.github.io/immich-memories/docs/reference/config-reference.md#notifications).

## Trigger it over HTTP

One POST starts the decision `auto run` would have made, with the same detectors, rules, cooldown and
history. You choose when, the app chooses what: an Immich workflow when an album fills up, a cron on
another box, a phone shortcut, Home Assistant.

This process holds your Immich API key, so the app serves the route only when something can
authenticate the caller.

| `auth.enabled` | `server.trigger_token` | `POST /api/trigger` |
| - | - | - |
| off | unset | **404**: the route is not enabled |
| off | set | token required |
| on | unset | logged-in session required (browsers only) |
| on | set | token **or** session |

```bash
export IMMICH_MEMORIES_SERVER__TRIGGER_TOKEN="$(openssl rand -hex 32)"

curl -X POST https://memories.example.com/api/trigger \
  -H "x-api-key: $IMMICH_MEMORIES_SERVER__TRIGGER_TOKEN"
```

The token goes in `x-api-key` or in `Authorization: Bearer <token>`. For Docker, put
`IMMICH_MEMORIES_SERVER__TRIGGER_TOKEN=your-generated-token` in `.env` and run `docker compose up -d`: the
shipped Compose file forwards it.

Keep the token in the environment. `server` doesn't expand `${VAR}`, so `"${SOMETHING}"` in `config.yaml`
is those literal characters. The token needs 32 random characters or more and no placeholder words like
`change-me`; a weaker one stops the app at startup. It is compared in constant time and redacted from
logs, `/health` and the config viewer. Send it only over HTTPS, behind the same reverse proxy as the web UI.

A caller that sends no `Origin` header (curl, a CronJob, Home Assistant) needs no change. One that sends an
`Origin` naming another site gets **403**. With auth off, the app answers only a local host or one in
`server.allowed_hosts`; the shipped Kubernetes CronJobs send `Host: localhost` for that reason. See
[Allowed hosts](https://sam-dumont.github.io/immich-memories/docs/run/network-security.md#allowed-hosts).

| Status | Body | Means |
| - | - | - |
| **202** | `status: "accepted"`, `attempt_id`, `status_url`, `forced` | the run has started |
| **401** | `{"detail": "invalid trigger token"}` | authentication failed |
| **404** | `{"detail": "trigger API is not enabled"}` | neither auth nor a token is set |
| **409** | `{"detail": "a run is already active", "attempt_id": …}` | a run is already going |

`GET` the `status_url` (`/api/trigger/<attempt_id>`, same authentication) for `attempt_id`, `state`,
`reason`, `started_at`, `finished_at`, `phase`, `memory_type`, `error` and `run`. `state` is `running`
until it ends `completed`, `failed`, `skipped` or `dry_run`. `run` is null until the attempt has a run,
then holds `run_id`, `status`, `created_at`, `completed_at`, `last_phase`, `output_duration_seconds`,
`delivery_status` and `immich_asset_id`. An unknown id gets **404**.

Add `?force=true` for a film you're asking for by hand:

```bash
curl -X POST "https://memories.example.com/api/trigger?force=true" \
  -H "x-api-key: $IMMICH_MEMORIES_SERVER__TRIGGER_TOKEN"
```

That call is `auto run --force` over HTTP: it skips the cooldown, and the film it makes doesn't start
one, so the next scheduled film still comes on time. The rotation rules still apply, and a run already
going still gets **409**. Only `true`, `1` or `yes` count (any case); anything else, a typo included, is a
normal call, and `forced` in the `202` body says which one it got. Anyone holding the token can force a
film this way. Leave the parameter off a schedule: a scheduled call that forced would make a film every
time it fired.

`skipped` is a normal answer: a workflow that fires on every upload mostly gets it back. One that fires on
a trip album asks for the best candidate right now, not for that album. For a specific film, use the CLI
or the web UI.

## Kubernetes

`deploy/kubernetes/base/cronjobs.yaml` holds two CronJobs that call `POST /api/trigger` on the running
Deployment: `immich-memories-auto` daily at 09:00 and `immich-memories-monthly` at 02:00 on the 1st. They
read only the trigger token from `immich-memories-secrets` and mount no application PVCs. Both make the
normal `auto run` decision: the monthly one does not force a monthly film.

Set the trigger token and add `- cronjobs.yaml` to `base/kustomization.yaml` (the setup builder does both
when you tick **Scheduled films (CronJobs)**), then render and apply:

```bash
kubectl kustomize deploy/kubernetes/base
kubectl apply -k deploy/kubernetes/base
```

A `Complete` Job only means the trigger was accepted (`202`); the running app makes the film. Follow it
with `GET /api/trigger/<attempt_id>` and the token, as shown under
[Batch jobs](https://sam-dumont.github.io/immich-memories/docs/run/reference/kubernetes-operations.md#batch-jobs). `concurrencyPolicy: Forbid` does not
stop overlapping runs; the run lease does, by answering a second trigger with `409`. The base
NetworkPolicy lets the CronJobs reach the app pod on 8080, the Service's port 80 after translation.

`base/job.yaml` is different: it runs a one-off `generate` and mounts the app's PVCs, so include it only
with the Deployment scaled to zero. For a fixed recipe while the app runs, use
`kubectl exec ... -- immich-memories generate ...`, so there is never a second writer on the store.

## A named memory on a named date

`auto` can't say "a year in review every 15 January". A cron line that runs `generate` can. Replace
`/absolute/path/to/immich-memories` with the installed executable, and set cron’s `PATH` so it finds
FFmpeg:

```bash
# 15 January, 09:00: last year's review, uploaded to an album
0 9 15 1 * /absolute/path/to/immich-memories generate --memory-type year_in_review --year $(( $(date +\%Y) - 1 )) --upload-to-immich --album "Memories"
```
