> For a complete page index of the Captain API documentation, fetch https://docs.filesearch.dev/llms.txt?excludeSpec=true

# n8n

> Install the Captain File Search nodes in n8n Cloud or self-hosted n8n, connect an API key, then index, search and react to jobs from n8n workflows.

## Agent Quick Reference: n8n

* **Package:** `@captain-sdk/n8n-nodes-filesearch` on npm. Source: [https://github.com/runcaptain/n8n-nodes-filesearch](https://github.com/runcaptain/n8n-nodes-filesearch) (MIT).
* **Nodes:** Captain File Search (actions, also usable as an AI Agent tool) and Captain File Search Trigger (job webhooks).
* **n8n Cloud:** turn on **Verified community nodes** in the Cloud console's **Instance settings**, then search `Captain File Search` in the nodes panel and select **Install**. Owner or admin only.
* **Self-hosted:** **Settings → Community Nodes → Install**, package name `@captain-sdk/n8n-nodes-filesearch`. Or `npm install @captain-sdk/n8n-nodes-filesearch` in `~/.n8n/nodes`, then restart n8n.
* **Credential:** Captain File Search API, holding an API key from the Studio. Base URL `https://api.filesearch.dev`.
* **Resources:** Search, Index, Document, Collection, Job, Sync, Parse. Storage sources need their own Captain File Search storage credential.
* **Trigger:** needs n8n reachable over public HTTPS. Deliveries are signature-checked.

The Captain File Search package for [n8n](https://n8n.io) adds two nodes to the workflow editor:

* **Captain File Search** searches collections, indexes files, and manages documents, collections, jobs, syncs and parsing. It also works as a tool for the n8n AI Agent.
* **Captain File Search Trigger** starts a workflow when an indexing or parse job completes, fails, is cancelled or times out.

The package is [`@captain-sdk/n8n-nodes-filesearch`](https://www.npmjs.com/package/@captain-sdk/n8n-nodes-filesearch) on npm. Its source is public at [runcaptain/n8n-nodes-filesearch](https://github.com/runcaptain/n8n-nodes-filesearch).

## Install

Installing community nodes needs the **Owner** or **Admin** role in n8n. Once installed, the nodes are available to every member of the instance.

#### n8n Cloud

1. In the n8n Cloud console, open **Instance settings** and turn on **Verified community nodes**.
2. Open a workflow and open the nodes panel with **+** or the `N` key.
3. Search for `Captain File Search`.
4. Under **More from the community**, select **Captain File Search**.
5. Select **Install**.

#### Self-hosted

1. Open **Settings → Community Nodes**.
2. Select **Install a community node**. When other community nodes are already installed, the button reads **Install**.
3. In **npm Package Name**, enter `@captain-sdk/n8n-nodes-filesearch`.
4. Tick **I understand the risks of installing unverified code from a public source**.
5. Select **Install**.

![The n8n Install community nodes dialog with the Captain File Search package name entered](/_fern-files/_img/8291d0f6a4953463c3a4d811c691f394a174b8a5dc1aa9bbf97120783760ef1b.webp)

The package then appears in the Community Nodes list.

![The Community Nodes settings page listing @captain-sdk/n8n-nodes-filesearch](/_fern-files/_img/d1ac6550df271d0d41b8d523bf24bac2bc27e98929e80916699a4391a03f17d3.webp)

### Install from the command line

Instances without the settings page, such as one built into a custom Docker image, take the package from npm:

```bash
cd ~/.n8n/nodes
npm install @captain-sdk/n8n-nodes-filesearch
```

Restart n8n afterward. In Docker, run the command as the `node` user inside the container, and keep `~/.n8n` on a volume so the package survives restarts.

Community nodes need `N8N_COMMUNITY_PACKAGES_ENABLED`, which is `true` by default.

After installing, search for `Captain File Search` in the nodes panel. One result holds both nodes: select it to see the actions, and the trigger, listed as **On new Captain File Search event**.

![The nodes panel with the Captain File Search result highlighted, next to a Captain File Search Trigger on the canvas](/_fern-files/_img/ad8bc78db53fd23d2a8b83e5c49441adf183a3c974356ddc6e764fc99d92c9e2.webp)

## Connect an API key

1. Create an API key in the [Studio](https://filesearch.dev/studio).
2. Add a **Captain File Search** node to a workflow.
3. Under **Credential**, select **Create new credential**.
4. Paste the API key into **API Key**.
5. Leave **Base URL** as `https://api.filesearch.dev`.
6. Select **Save**.

![The Captain File Search API credential form](/_fern-files/_img/d6d7d495392ebc4b3adf07429afa2674af847843a1d3f268ba304b38240d5461.webp)

The key decides the environment: a `cap_dev_` key reads and writes development collections, and a `cap_prod_` key reads and writes production collections.

### Storage credentials

Indexing from storage also needs a credential for that storage. The node sends these values to Captain File Search with each request, and the same credentials fill the node's bucket, folder and file dropdowns.

| Storage                            | n8n credential                              | What it holds                                                                                         |
| ---------------------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| Amazon S3                          | Captain File Search: Amazon S3              | An access key, or an IAM role ARN and external ID. The bucket and file dropdowns need the access key. |
| Google Cloud Storage, Google Drive | Captain File Search: Google Service Account | The service account JSON key. For Drive, also the Workspace user to read as.                          |
| Azure Blob Storage                 | Captain File Search: Azure Blob Storage     | Storage account name and key                                                                          |
| Cloudflare R2                      | Captain File Search: Cloudflare R2          | Account ID, access key and jurisdiction                                                               |
| Supabase Storage                   | Captain File Search: Supabase Storage       | S3 endpoint URL, region and access key                                                                |
| Backblaze B2                       | Captain File Search: Backblaze B2           | Region and application key                                                                            |
| SharePoint, OneDrive               | Captain File Search: Microsoft 365          | Entra ID tenant ID, client ID and client secret                                                       |
| Dropbox                            | Captain File Search: Dropbox                | An access token with `files.metadata.read` and `files.content.read`                                   |

Every dropdown also has a mode for typing or pasting a name, path, ID or link, for credentials that can read a location but not list it. For S3 with an IAM role, type the bucket and path.

## Example workflows

Each example below is a complete workflow. The screenshot shows the workflow on the n8n canvas, and the steps set up each node.

### Example 1: Index email attachments as they arrive

New Gmail attachments go into a `contracts` collection, tagged with the sender.

![A workflow with a Gmail Trigger connected to Captain File Search Index Uploaded File](/_fern-files/_img/c6571c3c3cd509e1d26b140c61e2c28483c999624ee0e98c75f6429a2969d5df.webp)

Before building the workflow, create the collection once: run **Captain File Search → Create Collection** with the name `contracts` in a separate workflow, or create it in the [Studio](https://filesearch.dev/studio).

1. Add a **Gmail Trigger** and turn off **Simplify**, which shows its **Options**.
2. Under **Options**, turn on **Download Attachments**.
3. Add **Captain File Search → Index Uploaded File** after it.
4. Pick `contracts` under **Collection**.
5. Set **Input Binary Field** to `attachment_0`, the first attachment. Gmail numbers the rest `attachment_1`, `attachment_2` and so on.
6. Under **Options**, add **Custom Metadata** with the key `sender` and the value `{{ $json.from.value[0].address }}`.

Each attachment becomes a document in `contracts`. Captain File Search does the indexing, not n8n. With **Wait for Completion** on (the default), the node waits for the job and returns its result.

### Example 2: Index a storage bucket every night

A schedule checks a folder in Amazon S3 every night and indexes the files added since the last run.

![A workflow with a Schedule Trigger connected to Captain File Search Index Files From Amazon S3](/_fern-files/_img/75d8b32935ad2d2d0f2a89e51fc29510f36b95e1f459d3b0b9245538f92e3f26.webp)

1. Add a **Schedule Trigger** set to run once a day.
2. Add **Captain File Search → Index Files From Amazon S3**.
3. Pick the S3 credential, the **Collection** and the **Bucket**.
4. Set **What to Index** to **Folder**, then pick the folder.
5. Set **If Already Indexed** to **Skip**, so files already in the collection are left alone and only new files are indexed.

The same pattern works for Google Cloud Storage, Azure Blob Storage, Cloudflare R2, Supabase Storage, Backblaze B2, Google Drive, SharePoint, OneDrive and Dropbox. **Skip** matches files by name, so an edited file keeps its old version. **Replace** re-indexes every matching file on every run, which repeats work for the whole folder. To pick up edited and deleted files as well, run **Sync → Create Amazon S3 Sync** once instead of a schedule, and under **Options** set **Check Every (Minutes)**, such as `1440` for once a day. Without that option, the sync only checks for changes when **Run Sync Now** is called.

### Example 3: Search a collection

A question returns the matching passages, one item per passage, for the next node to use.

![A workflow with a Manual Trigger connected to Captain File Search Search Collection](/_fern-files/_img/33307423858593003bc43210739e98e970497f11e6bc41ab9f8e2c128373f99f.webp)

1. Add **Captain File Search → Search Collection** after any trigger.
2. Pick the **Collection**.
3. Enter a question under **Query**, or map one from an earlier node.

![A Search Collection node with the contracts collection picked, a question under Query, and the matching passage in the output](/_fern-files/_img/5b5dbe5241db8cc73bda09d24990d04172c1cc3542bab6dae683a5c3efabc7bc.webp)

**Output** sets how much each passage carries:

* **Simplified** (the default) returns the text, score, file, page, IDs and metadata.
* **Raw** returns every field.
* **Selected Fields** returns only the fields picked, plus the chunk and document IDs.

**Options** add metadata filters, reranking and the balance between keyword and semantic matching. To search up to 10 collections at once, use **Search Multiple Collections**.

### Example 4: Answer questions with an AI Agent

A chat agent searches a collection whenever a question needs it, and answers from the passages it finds.

![A workflow with a Chat Trigger, an AI Agent, a chat model and Captain File Search attached as a tool](/_fern-files/_img/f6e2b56fb69a7a98c0c2e9d2d95b19ed6dc1914a4b35fdb8e3a1aa1f291763c1.webp)

1. Add a **Chat Trigger**.
2. Add an **AI Agent** after it.
3. Under **Chat Model**, attach a chat model, such as **OpenAI Chat Model**.
4. Under **Tool**, attach **Captain File Search**.
5. Set the tool's action to **Search Collection** and pick the collection.
6. Keep **Output** on **Simplified** or **Selected Fields**, so the agent receives short passages.

### Example 5: Act when an indexing job finishes

A job that finishes or fails starts a workflow, such as a Slack message. Large jobs can run for hours, so this continues the work without holding an n8n execution open.

![A workflow with Captain File Search Trigger, an If node and a Slack node](/_fern-files/_img/d3c5ca5474015fab7f91ad9ba6089013ce22ccf0a25a49786044d6d88c853c74.webp)

1. Add **Captain File Search Trigger** as the first node.
2. Under **Event Names or IDs**, choose the job events, such as `job.completed` and `job.failed`.
3. Optionally, under **Options**, limit it to certain collections, or set **Started By** to **API Call** or **Storage Sync**.
4. Add an **If** node to keep only the jobs this workflow cares about.
5. Add the next step, such as **Slack → Send Message**.
6. Activate the workflow.

![The Captain File Search Trigger node with job events selected](/_fern-files/_img/57352e49647dcba132cce64c22984f96e08a612a556c01b77c2a132075a3fda1.webp)

The trigger registers a webhook with Captain File Search when the workflow is activated, and removes it when the workflow is deactivated. It receives every matching job in the organization, not only the jobs one workflow started. To continue one specific job, save the `job_id` the indexing action returns (with **Wait for Completion** off), then compare it with `data.job_id` in the **If** node.

Every delivery is signature-checked, and a request with a missing or wrong signature is rejected. Captain File Search only delivers to public HTTPS URLs, so the n8n instance must be reachable from the internet over HTTPS. See [Webhooks](/guides/webhooks) for the event payloads.

## Actions

| Resource   | Actions                                                                                                                                                                                                                                           |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Search     | Search Collection, Search Multiple Collections (up to 10)                                                                                                                                                                                         |
| Index      | Index Uploaded File, Index File From URL, Index Text, Index YouTube Video, and Index Files From Amazon S3, Google Cloud Storage, Azure Blob Storage, Cloudflare R2, Supabase Storage, Backblaze B2, Google Drive, SharePoint, OneDrive or Dropbox |
| Document   | Get Many Documents, Get Document, Get Document Page, Get Document Chunks, Update Document Metadata, Delete Document, Delete All Documents                                                                                                         |
| Collection | Create Collection, Get Many Collections, Copy Collection, Delete Collection                                                                                                                                                                       |
| Job        | Get Job, Get Many Jobs, Wait for Job to Finish, Cancel Job                                                                                                                                                                                        |
| Sync       | Create a sync for S3, Google Cloud Storage, Azure, R2, Supabase or Backblaze, then Get Sync, Get Many Syncs, Update Sync, Run Sync Now, Delete Sync                                                                                               |
| Parse      | Parse File                                                                                                                                                                                                                                        |

Collections, documents, jobs and syncs are picked from searchable dropdowns that load from the account. Each picker also takes an ID, so a workflow can pass one from an earlier step.