# n8n

Source: https://frameleaf.app/docs/using/n8n/

The Frameleaf node for n8n lets your own n8n workflows work with the albums you choose. A workflow can search your photos, download them, make albums, add photos and tags, and upload files into Photos or [Boards](https://frameleaf.app/docs/using/boards/).

It needs self-hosted n8n 2.47.5 or later running as a single process. Queue mode, several n8n processes sharing one credential, and n8n Cloud aren't supported.

## Install

The node ships as the `n8n-nodes-frameleaf` package in the Frameleaf source, in `integrations/n8n-nodes-frameleaf`.

1. In that folder, run `npm ci`, `npm run build` and `npm pack`. That makes `n8n-nodes-frameleaf-0.1.0.tgz`.
2. On your n8n server, go to n8n's user nodes folder (usually `~/.n8n/nodes`) and run `npm install /path/to/n8n-nodes-frameleaf-0.1.0.tgz`.
3. Restart n8n. **Frameleaf** now shows in the node list.

Install it as a package like this, not by copying files into n8n's custom extensions folder.

## Register n8n with your server

n8n doesn't register itself. An administrator registers each n8n server once:

1. In n8n, add a **Frameleaf OAuth2 API** credential and copy its **OAuth Redirect URL**. It has to be an HTTPS address.
2. In Frameleaf, open **Settings**, then **Who can sign in**, then **Sign-in methods**. Under **Registered apps**, choose **Set up an app**.
3. Under **Name**, choose **Other** and enter `n8n`. In **Sends you back to**, paste the redirect URL exactly.
4. Choose **Create**, then copy the **App ID**.

## Connect your library

1. In the **Frameleaf OAuth2 API** credential, enter:
   - **Library URL**: your server's address, such as `https://photos.example.com`, with no path;
   - **Client ID**: the App ID from your administrator;
   - **Permissions**: the smallest profile your workflow needs (see below).
2. Choose **Connect**. Frameleaf opens. Sign in if asked.
3. Choose the albums n8n may read, or **Read my whole library**. Separately, choose the albums it may write to and whether it may make new albums.
4. Choose **Allow**.

| Profile | Lets the workflow |
| --- | --- |
| **Read Media** | See and search the albums you chose |
| **Read Media and Originals** | Also download original files |
| **Organize Media** | Also make albums, add photos to albums and add tags |
| **Upload Photos** | Upload photos and videos to the Photos albums you chose |
| **Upload to Boards** | Save files to the Boards you chose |
| **Automate Photos** | Read, organize and upload to Photos |
| **Automate Boards** | Read, organize and save to Boards |

If you change the profile or the Library URL, connect again. The credential won't send its sign-in to a different server.

n8n has to reach your server. At home, your server's home-network address or your own HTTPS address works without a Frameleaf plan. Through Frameleaf's [remote access](https://frameleaf.app/docs/cloud/remote-access/), you need a plan that includes it. Keep n8n's network protection on, and if your server is on a private address, allow just that address in n8n's SSRF allowlist.

## Operations

The **Frameleaf** node has one **Operation** list:

| Operation | What it does |
| --- | --- |
| **List Albums** | Lists the albums the connection can use |
| **Search Media** | Searches photos and videos in those albums |
| **Get Asset** | Gets one photo or video's details |
| **Download Rendition** | Downloads **Thumbnail**, **Preview**, **Display JPEG**, or **Original** (needs original downloads) as n8n binary data |
| **Create Album** | Makes an album in **Photos** or **Boards** |
| **Add Assets to Album** | Adds photos or videos to an album you allowed |
| **Apply Tags** | Adds [tags](https://frameleaf.app/docs/using/tags/) to a photo or video |
| **Upload Media** | Uploads a file from n8n binary data into an album you allowed |
| **Inspect Upload** | Checks an upload by its ID |
| **Cancel Upload** | Cancels an upload that hasn't finished. Finished uploads stay |

The node has no trigger of its own. Start a workflow with n8n's **Schedule**, **Webhook** or any other trigger, then use the Frameleaf node.

**Create Album** and **Upload Media** ask for a **Source ID**, and uploads also ask for a **Source Date**. Use values that stay the same for the same item, such as an ID and date from the earlier step, never the execution ID, the current time or a random value. Then a retried workflow gets the same album or file instead of a copy.

Downloads stop at **Maximum Download Size (MiB)**, 32 by default and up to 512. Uploads go in pieces of up to 8 MiB, and n8n holds the whole file in memory while it uploads. If Frameleaf asks the node to slow down, it waits before trying that server again.

## Disconnect

Open **Settings**, then **Your sign-in & privacy**, then **Connected apps** in Frameleaf and choose **Remove** next to n8n. Then delete the **Frameleaf OAuth2 API** credential in n8n. Deleting the credential on its own doesn't end n8n's access. Files the workflow already saved stay where they went.

To change the albums n8n may use, open **Details** for it in **Connected apps**. You can take albums away there; to add albums, connect again.

The node's labels are in English. Setup help is in the source, in `integrations/help/n8n`, in all eleven Frameleaf languages.
