# n8n-workflows — User Guide

A fast, self-hosted **search engine and documentation browser** for a large curated
collection of [n8n](https://n8n.io) workflow files. Point it at a folder of workflow
`.json` exports, run one command, and get an instant web interface to search, filter,
preview, visualize, and download thousands of workflows in milliseconds.

This guide is for **people who want to run the tool and find workflows**. If you operate
the service, tune its database, deploy it to a server, or extend its APIs, see the
companion **Admin Guide**.

---

## 1. What This Tool Does

`n8n-workflows` turns a directory full of n8n workflow `.json` files into a searchable
catalog. It scans every workflow, extracts its metadata (name, trigger type, the services
it integrates with, node count, complexity), stores that in a local SQLite database with
full-text search, and serves a single-page web app plus a JSON API on top.

The bundled collection ships pre-organized into service folders (`workflows/Slack`,
`workflows/Telegram`, `workflows/Github`, and ~200 more). As published, the indexed
catalog contains:

| Metric | Value |
|--------|-------|
| Total workflows | 4,343 |
| Active workflows | 434 |
| Inactive workflows | 3,908 |
| Total automation nodes | 29,528 |
| Unique integrations detected | 268 |
| Service categories | 16 |

> [!NOTE]
> These figures come from the collection's published statistics snapshot. Your own
> numbers will differ if you add, remove, or re-index workflows — the tool recomputes
> them every time it indexes.

**What you can do with it:**

- Full-text search across workflow names, descriptions, integrations, and tags
- Filter by trigger type (Manual, Webhook, Scheduled, Complex), complexity (low/medium/high),
  active status, and service category
- Preview a workflow's metadata and raw JSON
- View an auto-generated **Mermaid diagram** of any workflow's node graph
- Download any workflow's `.json` file to import into your own n8n instance

> [!TIP]
> This is a **documentation and discovery** tool, not an n8n runtime. It does not execute
> workflows. To run a workflow you find here, download its JSON and import it into your own
> n8n installation (**Workflows → Import from File**).

---

## 2. Quick Start

The fastest path from clone to a running search interface.

### Requirements

- **Python 3.9–3.12** (the dependencies are pinned for this range)
- **pip** for installing dependencies
- Roughly **50 MB** of disk for the database once indexed (varies with collection size)
- A modern web browser

> [!IMPORTANT]
> Python **3.13+** is outside the tested range for the pinned dependency versions. If you
> are on 3.13, use the Docker method in Section 3 instead, which controls the runtime for you.

### Run it

```bash
# 1. Clone the repository
git clone https://github.com/Zie619/n8n-workflows.git
cd n8n-workflows

# 2. Install Python dependencies
pip install -r requirements.txt

# 3. Start the server (indexes the database on first run)
python run.py
```

On first launch you will see the indexer build the database, then the server start:

```text
🚀 n8n-workflows Advanced Search Engine
==================================================
✅ Dependencies verified
✅ Directories verified
🔄 Setting up database: database/workflows.db
📚 Indexing workflows...
✅ Indexed 4343 workflows
📊 Database contains 4343 workflows
🌐 Starting server at http://127.0.0.1:8000
📊 API Documentation: http://127.0.0.1:8000/docs
🔍 Workflow Search: http://127.0.0.1:8000/api/workflows
```

Open **http://127.0.0.1:8000** in your browser. The first run indexes every workflow;
subsequent runs reuse the database and start almost instantly.

> [!NOTE]
> By default the server binds to `127.0.0.1` (localhost only). It will **not** be reachable
> from other machines unless you explicitly bind to `0.0.0.0` — see Section 4.

---

## 3. Installation

Choose the method that fits your environment.

=== "Python (local)"

    ```bash
    git clone https://github.com/Zie619/n8n-workflows.git
    cd n8n-workflows
    pip install -r requirements.txt
    python run.py
    ```

    Recommended: use a virtual environment so dependencies stay isolated.

    ```bash
    python -m venv .venv
    source .venv/bin/activate      # Windows: .venv\Scripts\activate
    pip install -r requirements.txt
    python run.py
    ```

=== "Docker (one command)"

    A helper script builds the image, starts the container, waits for health, and opens
    your browser:

    ```bash
    git clone https://github.com/Zie619/n8n-workflows.git
    cd n8n-workflows
    ./run-as-docker-container.sh
    ```

    The script requires **Docker** and **Docker Compose**. When it finishes:

    ```text
    🌐 Access URLs:
       Main Interface: http://localhost:8000
       API Documentation: http://localhost:8000/docs
       API Stats: http://localhost:8000/api/stats
    ```

    Stop it with `docker compose down`; follow logs with `docker compose logs -f`.

=== "Node.js (alternative)"

    The project ships a second implementation of the same core API in Node.js, under
    `src/`. Use it if you prefer a Node runtime.

    ```bash
    npm install
    node src/index-workflows.js      # build the database
    node src/server.js               # start the server
    ```

    The Node server exposes the same core endpoints as the Python server (search, stats,
    detail, download, diagram). See Section 8 for its command-line options.

> [!TIP]
> The Python stack (`run.py`) is the primary, most fully featured way to run the tool.
> Pick the Node stack only if Python isn't available in your environment.

### Verifying the install

```bash
curl http://127.0.0.1:8000/health
```

```text
{"status":"healthy","message":"N8N Workflow API is running"}
```

If you get JSON back, the server is up. Then check the catalog loaded:

```bash
curl http://127.0.0.1:8000/api/stats
```

```text
{"total":4343,"active":434,"inactive":3908,...}
```

---

## 4. Starting the Server (Command-Line Options)

`run.py` is the launcher you'll use most. It checks dependencies, ensures the
`database/`, `static/`, and `workflows/` directories exist, indexes the database if needed,
and starts the web server.

```bash
python run.py [options]
```

| Option | Default | What it does |
|--------|---------|--------------|
| `--host HOST` | `127.0.0.1` | Network interface to bind to. Use `0.0.0.0` to accept connections from other machines. |
| `--port PORT` | `8000` | TCP port to listen on. |
| `--reindex` | off | Force a full re-scan of every workflow file, even unchanged ones. |
| `--dev` | off | Development mode — enables auto-reload when source files change. |
| `--skip-index` | off | Start the server without indexing (useful for CI or quick restarts). |

**Common invocations:**

```bash
python run.py                    # default: localhost:8000, index if needed
python run.py --port 3000        # run on port 3000
python run.py --host 0.0.0.0     # accept connections from your network
python run.py --reindex          # rebuild the database from scratch
python run.py --dev              # auto-reload while developing
```

> [!WARNING]
> Binding to `--host 0.0.0.0` exposes the interface to everyone who can reach your machine
> on that port. The server has no login for browsing, so only do this on a trusted network
> or behind a reverse proxy with authentication. See the Admin Guide for hardening.

> [!TIP]
> Setting the environment variable `CI=true` has the same effect as `--skip-index` — handy
> for automated test environments where you don't want to rebuild the database.

---

## 5. Using the Web Interface

Open the main page (default **http://127.0.0.1:8000**) and you get a single search-first
interface.

### Searching

- Type in the **search box** and results update as you type (the input is debounced, so it
  waits briefly after you stop typing).
- Press <kbd>/</kbd> anywhere on the page to jump straight to the search box.
- Press <kbd>Esc</kbd> to clear the current search.

Search matches against each workflow's **name, description, integrations, and tags**.

### Filtering

Three dropdown filters narrow results, and they combine with your search text:

| Filter | Options |
|--------|---------|
| **Category** | The 15 service categories (AI Agent Development, Communication & Messaging, CRM & Sales, …) plus Uncategorized |
| **Complexity** | `low` (≤5 nodes), `medium` (6–15 nodes), `high` (16+ nodes) |
| **Trigger** | `Manual`, `Webhook`, `Scheduled`, `Complex` |

### Browsing results

Each result is a **workflow card** showing the name, a generated description, its category,
trigger type, complexity, node count, and the first few integrations it uses. Click a card
to open a **detail modal** with the full integration list, tags, active/inactive status,
and filename.

Results load in pages of 20. Click **Load More** to reveal the next batch.

> [!NOTE]
> When you first open the page (before any search), the interface shows a set of **Featured
> Workflows** — workflows that use at least one detected integration — so you have something
> to explore immediately.

### Downloading a workflow

Every card and detail view has a **📥 Download JSON** button. It downloads that workflow's
raw `.json` file. There's also a **📋 Copy ID / Copy Filename** button to copy the filename
to your clipboard.

To use a downloaded workflow:

1. Open your own n8n instance.
2. Go to **Workflows → Import from File** (or paste the JSON via **Import from URL/Clipboard**).
3. Select the downloaded `.json` file.
4. Reconnect any credentials the workflow expects (API keys, OAuth, etc.) — credentials are
   **not** included in the exported files.

> [!CAUTION]
> Always review a workflow before activating it in your own n8n. Check which nodes make
> outbound requests and which credentials they expect. Downloaded workflows are community
> automations — treat them as untrusted until you've read them.

---

## 6. Common Tasks (Recipes)

### Find every workflow for a specific service

Type the service name in the search box — e.g. `slack`, `telegram`, `openai`, `google sheets`.
Or use the API directly:

```bash
curl "http://127.0.0.1:8000/api/workflows?q=slack"
```

### Browse only Scheduled automations

Set the **Trigger** filter to `Scheduled`, or:

```bash
curl "http://127.0.0.1:8000/api/workflows?trigger=Scheduled"
```

### Find simple, beginner-friendly workflows

Set **Complexity** to `low` (5 nodes or fewer):

```bash
curl "http://127.0.0.1:8000/api/workflows?complexity=low"
```

### See only workflows that are marked active

```bash
curl "http://127.0.0.1:8000/api/workflows?active_only=true"
```

### Look at one workflow's full JSON before downloading

```bash
curl "http://127.0.0.1:8000/api/workflows/0720_Schedule_Filter_Create_Scheduled.json"
```

This returns both the stored metadata and the complete raw workflow JSON.

### Visualize a workflow as a diagram

```bash
curl "http://127.0.0.1:8000/api/workflows/0720_Schedule_Filter_Create_Scheduled.json/diagram"
```

You get [Mermaid](https://mermaid.js.org) flowchart code describing the workflow's nodes and
their connections. Triggers are colored blue, conditional nodes (If/Switch) yellow, code
nodes purple, and error handlers red — paste it into any Mermaid renderer to see the graph.

### Browse by category from the API

```bash
curl "http://127.0.0.1:8000/api/categories"                      # list categories
curl "http://127.0.0.1:8000/api/workflows/category/messaging"    # workflows in a category
```

---

## 7. Searching via the JSON API

The same data behind the web UI is available as a JSON API, so you can script against it.
The primary endpoint is `/api/workflows`.

### Search & filter parameters

| Parameter | Type | Default | Notes |
|-----------|------|---------|-------|
| `q` | string | `""` | Full-text query (name, description, integrations, tags) |
| `trigger` | string | `all` | `all`, `Manual`, `Webhook`, `Scheduled`, `Complex` |
| `complexity` | string | `all` | `all`, `low`, `medium`, `high` |
| `active_only` | bool | `false` | `true` to show only active workflows |
| `page` | int | `1` | Page number (≥1) |
| `per_page` | int | `20` | Results per page (1–100) |

**Example — page 2 of webhook workflows mentioning "invoice", 10 per page:**

```bash
curl "http://127.0.0.1:8000/api/workflows?q=invoice&trigger=Webhook&page=2&per_page=10"
```

```text
{
  "workflows": [ ... ],
  "total": 37,
  "page": 2,
  "per_page": 10,
  "pages": 4,
  "query": "invoice",
  "filters": {"trigger": "Webhook", "complexity": "all", "active_only": false}
}
```

### Endpoints you'll use as a consumer

| Method | Endpoint | Purpose |
|--------|----------|---------|
| `GET` | `/api/stats` | Collection-wide counts (totals, triggers, complexity, integrations) |
| `GET` | `/api/workflows` | Search & filter (parameters above) |
| `GET` | `/api/workflows/{filename}` | Metadata + raw JSON for one workflow |
| `GET` | `/api/workflows/{filename}/download` | Download the `.json` file |
| `GET` | `/api/workflows/{filename}/diagram` | Mermaid diagram code |
| `GET` | `/api/workflows/category/{category}` | Workflows in a service category |
| `GET` | `/api/categories` | Available categories |
| `GET` | `/api/integrations` | Integration count summary |
| `GET` | `/health` | Liveness check |

> [!TIP]
> The server publishes interactive API documentation at **`/docs`** (Swagger UI). Open
> **http://127.0.0.1:8000/docs** to try every endpoint from your browser with no extra tools.

> [!NOTE]
> The detail, download, and diagram endpoints are **rate-limited to 60 requests per minute
> per IP address**. If you script bulk downloads, pace your requests or you'll get HTTP 429
> responses (see Troubleshooting).

---

## 8. Running the Node.js Server

If you use the Node.js stack instead of Python, the entry point is `src/server.js`. It
serves the same core search/browse/download API.

```bash
node src/server.js [options]
```

| Option | Description |
|--------|-------------|
| `-p, --port <port>` | Port to run the server on |
| `-h, --host <host>` | Host/interface to bind to |
| `--dev` | Enable development mode |

Build or refresh the database first with the Node indexer:

```bash
node src/index-workflows.js            # index all workflows
node src/index-workflows.js --force    # force a full re-index
node src/index-workflows.js --stats    # show database statistics only
```

| Indexer option | Description |
|----------------|-------------|
| `-f, --force` | Force reindexing of all workflows |
| `--stats` | Show database statistics only |

> [!NOTE]
> The Node and Python servers use the same on-disk SQLite database format and the same
> `workflows/` directory, but pick **one** stack and stick with it for a given deployment to
> avoid confusion about which one indexed the data.

---

## 9. Working With the Database Directly

`workflow_db.py` is a small command-line tool for indexing and searching without starting
the web server — useful for scripting or quick checks.

```bash
python workflow_db.py [options]
```

| Option | Description |
|--------|-------------|
| `--index` | Index all workflows into the database |
| `--force` | Combined with `--index`, force re-indexing of every file |
| `--search "TEXT"` | Run a full-text search and print matches |
| `--stats` | Print database statistics |

**Examples:**

```bash
python workflow_db.py --index                 # build/update the index
python workflow_db.py --index --force          # rebuild everything
python workflow_db.py --search "telegram bot"  # search from the terminal
python workflow_db.py --stats                  # show totals
```

```text
Database Statistics:
  Total workflows: 4343
  Active: 434
  Total nodes: 29528
  Unique integrations: 268
  Trigger types: {'Complex': 1737, 'Manual': 998, 'Scheduled': 477, 'Webhook': 1129}
```

> [!TIP]
> Re-indexing is **incremental by default**. The indexer hashes each file and skips ones
> that haven't changed since the last run, so updating after adding a few workflows is fast.
> Use `--force` only when you want to rebuild everything.

---

## 10. Understanding the Catalog

A few concepts make the search results easier to interpret.

**Trigger type** — how a workflow starts:

Trigger type
: Inferred from the workflow's nodes. `Webhook` = starts on an inbound HTTP call;
  `Scheduled` = starts on a timer/cron; `Manual` = started by hand; `Complex` = a larger
  workflow (more than 10 nodes and more than 3 integrations) that doesn't fit the simpler
  categories.

**Complexity** — a rough size signal based on node count:

Complexity
: `low` = 5 nodes or fewer, `medium` = 6–15 nodes, `high` = 16 or more nodes. It reflects
  structural size, not how hard the workflow is to understand.

**Integrations** — the external services a workflow touches:

Integrations
: Detected from each node's type (e.g. an `n8n-nodes-base.slack` node → "Slack"). Pure
  utility nodes (Set, If, Merge, Code, sticky notes, etc.) are intentionally excluded so the
  integration list reflects real services. The most common integrations in the collection
  are HTTP Request, OpenAI, AI Agent, Webhook, and Form Trigger.

**Active vs. inactive** — taken straight from the workflow's `active` flag in its JSON. Most
workflows in the published collection are inactive (they're examples to import, not running
automations).

---

## 11. Troubleshooting

### Error: `Database setup error: No module named 'workflow_db'`

**Cause:** You ran a command from the wrong directory, so Python couldn't find
`workflow_db.py`. This module lives at the repository root.

**Solution:** Run all commands from the repository root (the folder containing `run.py` and
`workflow_db.py`):

```bash
cd /path/to/n8n-workflows
python run.py
```

**Prevention:** Don't run `run.py` from inside a subfolder, and don't copy it elsewhere
without its sibling modules.

### Error: `Missing dependencies: fastapi, uvicorn`

**Cause:** Dependencies aren't installed (or you're in the wrong virtual environment).

**Solution:**

```bash
pip install -r requirements.txt
```

**Prevention:** Activate your virtual environment before running, and keep dependencies
installed there.

### The page loads but says "Setup Required" / no workflows appear

**Cause:** The server started but the database is empty — usually because indexing was
skipped (`--skip-index` or `CI=true`) or the `workflows/` directory is missing.

**Solution:** Force an index and restart:

```bash
python run.py --reindex
```

**Prevention:** Only use `--skip-index`/`CI` when you intend to start with an existing,
already-populated database.

### Browser console: `Failed to load search index`

**Cause:** This appears on the **static (GitHub Pages-style) front end** when it can't fetch
its pre-built `api/search-index.json` file. It typically means you opened the static `docs/`
page without the data file present.

**Solution:** Use the live server (`python run.py`) and open `http://127.0.0.1:8000`, which
serves data from the API rather than a static file.

### HTTP 429 — `Rate limit exceeded. Please try again later.`

**Cause:** You sent more than **60 requests per minute** from one IP to the detail, download,
or diagram endpoints.

**Solution:** Slow down. Add a short delay between requests when scripting bulk operations.

**Prevention:** Batch your needs — fetch a search page once (which lists many workflows)
instead of hammering per-workflow endpoints.

### HTTP 400 — `Invalid filename format`

**Cause:** The filename you requested isn't a plain `name.json` (the server blocks anything
containing slashes, `..`, or other special characters as a security measure).

**Solution:** Use the exact `filename` returned by `/api/workflows` — e.g.
`0720_Schedule_Filter_Create_Scheduled.json` — with no path in front of it.

### HTTP 404 — `Workflow file not found`

**Cause:** The filename doesn't exist in the `workflows/` directory, or the database is out
of sync with the files on disk.

**Solution:** Confirm the filename via a search, then re-index if you recently changed files:

```bash
python run.py --reindex
```

### Docker container won't start / "trouble using the Docker image"

**Cause:** Docker or Docker Compose isn't installed, or a port is already in use.

**Solution:** Verify both are installed (`docker --version`, `docker compose version`), make
sure nothing else is on port 8000, then re-run `./run-as-docker-container.sh`. Inspect logs
with `docker compose logs -f`.

### Server starts but is unreachable from another computer

**Cause:** The default bind address is `127.0.0.1` (localhost only).

**Solution:** Start with `python run.py --host 0.0.0.0` and open the host machine's IP from
the other computer. Make sure your firewall allows the port.

---

## 12. Frequently Asked Questions

**Q: Does this tool run my workflows?**
No. It only catalogs, searches, and serves workflow files. To run a workflow, download its
JSON and import it into your own n8n instance.

**Q: How fast is search?**
Very. The search engine uses SQLite full-text search (FTS5) with indexes, so queries across
thousands of workflows return in well under a second — typically tens of milliseconds.

**Q: Where does the workflow data come from?**
From the `.json` files in the `workflows/` directory, organized into per-service subfolders.
The bundled collection ships thousands of community workflows already sorted.

**Q: Can I add my own workflows?**
Yes. Drop additional `.json` files into the `workflows/` directory (any subfolder) and
re-index with `python run.py --reindex` or `python workflow_db.py --index`. They'll appear in
search.

**Q: Are credentials/API keys included in downloaded workflows?**
No. Exported workflow JSON contains node configuration but not your secrets. You'll
reconnect credentials inside your own n8n after importing.

**Q: What's the difference between the Python and Node.js servers?**
They implement the same core search/browse/download API over the same database. Python
(`run.py`) is the primary, most complete stack; Node (`src/server.js`) is an alternative for
Node-only environments.

**Q: Why are most workflows marked "inactive"?**
The collection is a library of examples. The `active` flag reflects each workflow's state at
export time; most are templates meant to be imported, not live automations.

**Q: Where's the interactive API documentation?**
At `/docs` on the running server (Swagger UI) — e.g. `http://127.0.0.1:8000/docs`.

**Q: Can I change the port or run multiple instances?**
Yes. Use `--port` to pick a port. Run separate instances on different ports if you want
multiple catalogs.

**Q: How do I update the catalog after the files change?**
Re-index. Indexing is incremental (it skips unchanged files), so updates are quick:
`python run.py --reindex` or `python workflow_db.py --index`.

**Q: Does it work offline?**
Yes. Once dependencies are installed and the database is built, the search engine runs
entirely locally with no internet connection required.

---

## 13. Quick Reference

**Start the server:**

```bash
python run.py [--host H] [--port P] [--reindex] [--dev] [--skip-index]
```

**Index / query the database directly:**

```bash
python workflow_db.py [--index] [--force] [--search "TEXT"] [--stats]
```

**Node.js stack:**

```bash
node src/index-workflows.js [--force] [--stats]
node src/server.js [-p PORT] [-h HOST] [--dev]
```

**Key URLs (default host/port):**

| URL | What |
|-----|------|
| `http://127.0.0.1:8000/` | Web search interface |
| `http://127.0.0.1:8000/docs` | Interactive API docs (Swagger) |
| `http://127.0.0.1:8000/api/stats` | Collection statistics |
| `http://127.0.0.1:8000/api/workflows?q=...` | Search API |
| `http://127.0.0.1:8000/health` | Health check |

**Keyboard shortcuts (web UI):**

| Key | Action |
|-----|--------|
| <kbd>/</kbd> | Focus the search box |
| <kbd>Esc</kbd> | Clear the search |

**Search/filter cheatsheet:**

```bash
?q=slack                 # text search
?trigger=Scheduled       # Manual | Webhook | Scheduled | Complex
?complexity=low          # low | medium | high
?active_only=true        # active workflows only
?page=2&per_page=50      # pagination (per_page max 100)
```

---

_Generated June 2026 from Zie619/n8n-workflows at ed8dd70. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._