Description

n8n-nodes-lucidlink

This is an n8n community node for LucidLink. It lets you interact with the self-hosted LucidLink LucidAPI from your n8n workflows.

LucidLink is a cloud-native file system that lets teams work with large files stored in object storage (e.g. Amazon S3) as if they were local. The LucidAPI is a REST API that ships with self-hosted LucidLink deployments and gives programmatic control over filespaces, entries, groups, members, permissions, and more.

n8n is a fair-code licensed workflow automation platform.

Installation
Operations
Credentials
Compatibility
Usage
Resources
Version history

—

Installation

Follow the installation guide in the n8n community nodes documentation.

The package name is n8n-nodes-lucidlink.

—

Operations

This node covers 12 resources and 48 operations against the LucidLink LucidAPI v1.5.0.

Direct Link

| Operation | Description |
| ——— | ——————————————————————– |
| Generate | Generate a shareable direct link to a filesystem entry by ID or path |

Filespace

| Operation | Description |
| ——— | ———————- |
| Create | Create a new filespace |
| Get Many | List all filespaces |
| Get | Get a filespace by ID |
| Update | Rename a filespace |
| Delete | Delete a filespace |

Entry

| Operation | Description |
| ————- | ————————————— |
| Create | Create a new directory entry |
| Get | Get an entry by ID |
| Resolve | Resolve an entry by its filesystem path |
| List Children | List the children of a directory entry |
| Delete | Delete an entry by ID |

Data Store

| Operation | Description |
| —————— | —————————————— |
| Create | Create a new S3 or HTTP link data store |
| Get Many | List all data stores in a filespace |
| Get | Get a data store by ID |
| Update Credentials | Update the S3 credentials for a data store |
| Delete | Delete a data store |

External Entry

| Operation | Description |
| ——— | —————————————————————– |
| Create | Create a new external entry (SingleObjectFile or HttpLinkFile) |
| Update | Update the URL of an existing HTTP link file entry |
| List IDs | List external entry IDs in a data store |
| Delete | Delete an external entry |

Group

| Operation | Description |
| —————- | ———————————————- |
| Create | Create a new group |
| Get Many | List groups (optionally filter by name) |
| Get | Get a group by ID |
| Update | Update a group |
| Delete | Delete a group |
| Get Members | List members of a group |
| Add Member | Add a single member to a group |
| Bulk Add Members | Add multiple members across groups in one call |
| Remove Member | Remove a member from a group |

Member

| Operation | Description |
| ———– | —————————————– |
| Add | Add a new member |
| Get Many | List members (optionally filter by email) |
| Get | Get a member by ID |
| Update Role | Update a member’s role |
| Delete | Delete a member |
| Get Groups | List the groups a member belongs to |

Permission

| Operation | Description |
| ——— | ——————————————- |
| Grant | Grant a permission on a path to a principal |
| List | List permissions in a filespace |
| Update | Update an existing permission |
| Revoke | Revoke a permission |

Health

| Operation | Description |
| ——— | ———————————————- |
| Check | Check whether the LucidAPI instance is running |

Provider

| Operation | Description |
| ——— | ————————————————– |
| Get Many | List available storage providers and their regions |

Service Account

| Operation | Description |
| ——— | ——————————————————– |
| Create | Create a service account, optionally with an initial key |
| Get Many | List all service accounts in the workspace |
| Get | Get a service account by ID |
| Delete | Delete a service account, revoking all of its keys |

Service Account Key

| Operation | Description |
| ——— | ————————————————- |
| Create | Create a new key for a service account |
| Get Many | List all keys belonging to a service account |
| Delete | Delete a key, immediately revoking its token |

—

Credentials

The LucidLink LucidAPI is self-hosted, so you configure the connection endpoint in n8n’s credential settings rather than using a fixed URL.

Prerequisites

• A running LucidLink API deployment | deployment guide
• A service account bearer token

Setup

1. In n8n, go to Credentials → New and search for LucidLink API.
2. Fill in the two fields:

| Field | Description | Example |
| ————- | ——————————————————- | ———————– |
| Base URL | Full base URL of your LucidAPI instance, including port | http://localhost:7778 |
| API Token | Bearer token for your service account | eyJ... |

3. Click Save — n8n will test the credential by hitting GET /api/v1/health and confirm it can connect.

—

Compatibility

• Minimum n8n version: 1.0.0
• LucidAPI version: 1.5.0
• Tested against n8n 1.x running on Node.js 20+

—

Usage

Self-hosted base URL

Because the LucidAPI is self-hosted, the base URL must be set in your credentials. Every user or team running their own LucidLink deployment will have a different address (e.g. http://192.168.1.10:7778 or https://lucidapi.mycompany.com).

Filespace-scoped resources

Several resources (Direct Link, Entry, Data Store, External Entry, Permission) require a Filespace ID. This appears as a shared field at the top of the node when one of those resources is selected.

Cursor-based pagination

Data Store kinds

When creating a data store, select the Kind:

• S3 Data Store (S3DataStore) — backed by S3 cloud object storage. Requires Access Key, Secret Key and Bucket Name, plus either S3 Region or S3 Endpoint.
• HTTP Link Data Store (HttpLinkDataStore) — for HTTP links. Requires only a name; no S3 fields are shown. Only available on filespace format 3.7 and above — on 3.6 and below the API returns 400 This data store type is not supported, and you don’t need one: create HttpLinkFile external entries with the URL alone and leave HTTP Link Data Store ID empty.

Optional S3 fields left blank (Region, Endpoint) are omitted from the request body rather than sent as empty strings.

External Entry kinds

When creating an external entry, select the Kind:

• Single Object File (S3) — links a file from an S3 bucket. Requires a Data Store ID and S3 Object ID.
• HTTP Link File — links a file accessible via a public HTTP/HTTPS URL. Requires the URL, plus an HTTP Link Data Store ID on filespace format 3.7 and above (leave it empty on 3.6 and below, where the API rejects it). Create that data store with Data Store → Create using kind HttpLinkDataStore.

The Update operation is only applicable to HttpLinkFile entries and updates the linked URL. The new URL’s content size must match the original file size.

Both kinds accept optional fields under Additional Fields that skip the server-side access check (a HEAD request against the bucket or URL): Object Checksum + Object Size for SingleObjectFile (the API requires both together), and File Size for HttpLinkFile. Useful for bulk imports and for objects the API cannot HEAD directly.

Cursor-based pagination

The following operations support cursor-based pagination via limit and Next Cursor fields:

• Entry → List Children
• External Entry → List IDs
• Permission → List

Pass the nextCursor value returned in a previous response into the Next Cursor field to fetch the next page. Use a Loop node to iterate through all pages automatically.

Service accounts and keys

A service account is a non-human identity; a key is a bearer token belonging to one. Together they let you automate credential rotation — create a key, use its token, delete the old one.

The token is returned only once, in the response that creates it (Service Account → Create with Create Initial Key enabled, or Service Account Key → Create). It cannot be retrieved later, so route it straight to wherever it needs to live in the same execution.

Keys can be made Single Use (invalidated after the first request) or given an Expires At timestamp. Leave Expires At empty for a non-expiring token. Deleting a service account revokes every key it owns.

Response format and node versions

The LucidAPI wraps most successful responses in a data envelope. How this node surfaces that depends on the version of the node in your workflow:

| Node version | Output |
| ———— | —— |
| 1 | The raw response, e.g. a single item { "data": [ ... ] }. Reference fields as {{ $json.data.id }}. |
| 2 (default for new nodes) | The envelope is stripped and lists are split into one item per record. Reference fields as {{ $json.id }}. |

Nodes already saved in a workflow keep the version they were created with, so upgrading the package does not change the output of existing workflows. To adopt version 2, replace the node on the canvas and update any downstream expressions that referenced data.

Under version 2, paginated operations (Entry → List Children, External Entry → List IDs, Permission → List) unwrap to a single item holding both the records and nextCursor, so cursor-based loops keep working. Data Store operations are unaffected because the API does not wrap them.

Bulk add group members

The Group → Bulk Add Members operation accepts a list of { groupId, memberId } pairs in a single API call (up to 100 items). Use the Add item button in the node UI to build the list.

Creating a filespace with customer storage

When creating a filespace with storageOwner = customer, an additional set of S3 fields appears: Access Key ID, Secret Access Key, and optional Endpoint and Bucket Name.

—

Resources

• n8n community nodes documentation
• LucidLink website
• LucidLink Knowledge Base
• LucidAPI reference — available at /api/v1/docs/ once your LucidLink API instance is running
• Node source code

—

Version history

0.2.0

Aligned with LucidLink LucidAPI v1.5.0.

New resources

• Service Account: Create (optionally with an initial key), Get Many, Get, Delete
• Service Account Key: Create, Get Many, Delete

Node version 2

• The node now declares versions 1 and 2, defaulting to 2 for newly added nodes. Version 2 strips the LucidAPI data envelope and splits lists into one item per record; version 1 returns the raw response. Nodes already saved in a workflow stay on the version they were created with, so existing workflows and their $json.data... expressions are unaffected.

Fixes

• Data Store → Create: added a Kind selector for S3DataStore and HttpLinkDataStore. The kind is now taken from the node instead of being hard-coded to S3DataStore, and the S3 credential fields are only shown (and only sent) for S3DataStore.
• Data Store → Create: blank optional fields are no longer sent as empty strings — leaving S3 Endpoint or S3 Region empty now omits the key from the request body instead of sending "", which the API rejects
• External Entry → Create: HTTP Link Data Store ID can now be set for HttpLinkFile entries, which the API requires on filespace format 3.7 and above. Previously the field was only available for SingleObjectFile, so HttpLinkFile creates failed on those filespaces with no way to fix it from the node.
• External Entry → Create/Update: added the optional metadata fields that skip the server-side HEAD access check (singleObjectFileParams.metadata checksum and size, httpFileParams.size)
• Filespace → Create: blank Customer Storage: Endpoint and Bucket Name are omitted rather than sent as empty strings. The API requires endpoint to be absent when the region is a known provider region.
• Member → Update Role: a blank Filespace IDs field no longer sends [""]

Documentation

• Documented the response envelope, service account key handling, HttpLinkDataStore, the Update Credentials operation being S3-only, that permission principals may be service accounts, the entry name character restrictions, and the 1–100 range on bulk membership
• Corrected the operation count and added the previously undocumented Health resource

0.1.5

Aligned with LucidLink LucidAPI v1.4.2:

• External Entry → Create: added HttpLinkFile kind support — choose between SingleObjectFile (S3) and HttpLinkFile (public HTTP URL) when creating an external entry
• External Entry → Update: new operation to update the URL of an existing HttpLinkFile entry (PATCH /api/v1/filespaces/{filespaceId}/external/entries/{entryId})
• Data Store → Create: corrected minimum value for URL Expiration (Minutes) from 360 to 4320 (3 days) to match the API spec

0.1.3

• Added Direct Link resource with a Generate operation (GET /api/v1/filespaces/{filespaceId}/direct-links)

0.1.0

Initial release. Covers the full LucidLink LucidAPI v1.3.0 surface:

• 8 resources: Filespace, Entry, Data Store, External Entry, Group, Member, Permission, Provider
• 36 operations
• Configurable base URL and bearer token credentials