Description
n8n-nodes-leapter
This is an n8n community node that lets you use Leapter in your n8n workflows.
Leapter is a decision logic platform: business rules live as visual, versioned Blueprints. You describe a rule in plain language and Leapter’s AI agents draft the Blueprint for you — then humans review and approve it. At runtime, the approved Blueprint executes deterministically: the same input always produces the same output, with no LLM anywhere in the execution path. This node lists the public Blueprints deployed to your Leapter Runtime Cluster and runs them from your workflow, either as a regular node or as a tool on an AI Agent.
n8n is a fair-code licensed workflow automation platform.
Table of Contents
- Installation
- Development Setup
- Operations
- Credentials
- Compatibility
- Usage
- Resources
- Version history
- Node.js: Use a version supported by your n8n release: n8n 2.27.5 requires Node 22.22 or later; n8n 2.44.7 requires Node 24 or later.
- pnpm: Package manager
Installation
Follow the installation guide in the n8n community nodes documentation, using the package name n8n-nodes-leapter.
> Renamed in v0.1.4. This package was previously released as @leapter/n8n-nodes-leapter,
> which is now deprecated. Existing installations keep working but do not update automatically —
> reinstall using the new name to receive further releases.
Development Setup
Prerequisites
To check your Node.js version:
node -v
If you need to switch versions using Homebrew:
brew install node@24
brew unlink node
brew link --overwrite node@24
Install Dependencies
pnpm install
Scripts
| Script | Description |
|——–|————-|
| pnpm dev | Start n8n with the node in development mode (with hot reload) |
| pnpm build | Build the node for production |
| pnpm build:watch | Build and watch for changes |
| pnpm lint | Run ESLint |
| pnpm lint:fix | Fix linting issues |
Releases are cut from the GitHub Releases UI: draft a release with a vX.Y.Z tag and publish it. The version is taken from the tag (see .github/workflows/publish.yml); the version field in package.json is a placeholder.
Running Locally
1. Install dependencies:
pnpm install
2. Start the development server:
pnpm dev
3. Open n8n in your browser:
http://localhost:5678
The Leapter node will be available in the n8n node picker.
Operations
The Leapter node provides dynamic operations based on the Blueprints deployed to your Runtime Cluster:
How It Works
1. Select a Project: opening the field lists every deployed project with public Blueprints that your credential reaches. When the credential reaches more than one environment, each project is shown as environment · project.
2. Select a Blueprint: the dropdown lists the project’s public Blueprints
3. Configure input parameters using either:
– Visual Mode: Map fields visually with type hints
– JSON Mode: Provide raw JSON input for advanced use cases
4. Execute and receive results with the run ID
The first use of a project creates its access key automatically; the node starts this as soon as you choose the project. The key takes up to a minute to become active. Once you have chosen the blueprint, a yellow note says “On first use, Leapter activates access to this project. This can take up to a minute; the fields load automatically.”, n8n shows “Fetching parameters”, and the node asks again every 10 s, up to 6 times. The fields then appear by themselves and the note disappears; you do not need to click anything. Only if the key is still not active after a minute does the list say “Access to
Credentials
Choose Service Account Key or OAuth2 in the selector at the top right of the node’s credential section.
n8n service account. Existing workflows keep using this credential without changes.Both credentials create and store a project’s evaluation key on first use. Runs send only that key to the engine; management calls use the service key or the signed-in member’s id token.
Service Account Key
1. Deploy the project in the Leapter Lab to an environment of your Runtime Cluster.
2. Create a key for the n8n service account in the Runtime Cluster’s Admin UI: Service accounts → n8n → Create key. Copy the key (starts with lkmgmt).
3. Create the credential in n8n: add a “Leapter API” credential, paste that key and save; n8n tests it. For a self-hosted or development cluster, turn on Advanced Settings and enter its address as Leapter Server, and Run Address when it answers runs on another address.
#### Service Account Key Fields
| Field | Description | Required |
|——-|————-|———-|
| Service Key | A key of the n8n service account (starts with lkmgmt) | Yes |
| Advanced Settings | Shows the address fields | No |
| Leapter Server | The Leapter Runtime Cluster: the Admin UI’s address without /runtime-management/ui. Default https://runtime.leapter.com; only change for self-hosted clusters or development | No |
| Run Address | Where the cluster answers blueprint runs. Empty means the Leapter Server; a local cluster answers them on http://localhost:3003 | No |
OAuth2 Sign-in
1. For Leapter SaaS, send Leapter your n8n credential’s OAuth Redirect URL to enable sign-in. For self-hosted Leapter, ask your administrator to register this URL with your sign-in server. The consent page shows Leapter for n8n.
2. Select OAuth2 in the Leapter node and create a Leapter OAuth2 API credential.
3. The hosted Leapter settings are already configured. For another cluster, turn on Advanced Settings and enter the fields below. Turning it off switches back to hosted Leapter and clears custom settings when saved.
4. Click Connect, sign in, and allow access. Then pick a project and Blueprint in the node.
| Custom server field | Value |
|————-|——-|
| Leapter Server | Your Runtime Cluster’s address |
| Run Address | Where the cluster answers runs; leave empty to use the Leapter Server |
| Sign-in Server | From your Leapter administrator |
| Client ID | From your Leapter administrator |
The sign-in uses OAuth2 with PKCE and the openid email profile scopes. The id token lasts an hour; token refresh does not renew it. After that, listing projects or Blueprints and granting access to another project requires Reconnect (called Switch account in some n8n versions). Runs for projects with stored evaluation keys keep working, including after an n8n restart. Reconnecting preserves those keys.
Disconnect is different from expiry or reconnect: n8n deletes the credential’s OAuth token data, including its saved evaluation keys for all projects using that credential. Runs then require a new connection and new keys, which may need up to a minute to activate. Disconnect does not revoke the old evaluation keys on the cluster; revoke those separately in the Admin UI when they are no longer needed.
n8n stores evaluation keys encrypted in the credential and does not send them to the editor. For OAuth2 they live inside the stored token data alongside the access, refresh and id tokens. Anyone able to export decrypted credentials can read the keys.
Compatibility
Usage
Visual Mode (Recommended)
Visual mode provides a guided experience with field-by-field mapping:
1. Select your project and Blueprint
2. The node automatically loads available input fields
3. Map values from previous nodes or enter static values
4. Each field shows its type and whether it’s required
JSON Mode
For advanced users or complex payloads:
1. Select your project and Blueprint
2. Switch Input Mode to “JSON”
3. Enter your parameters as a JSON object
4. Refer to the OpenAPI spec for field definitions
As a tool of an AI Agent
Connect the Leapter node to an AI Agent’s Tool input, choose project and blueprint, and describe the tool in Description. The model can supply the inputs:
{{ $fromAI('claimAmount', 'Claim amount', 'number') }}).{{ $fromAI('claim', 'The claim as a JSON object: {...}', 'json') }}; the node takes the object as it is.The run’s result, including _metadata.runId, goes back to the agent.
Example Workflow
Trigger → Leapter (Execute Blueprint) → Process Results
Output
The node returns:
outputData) – runId: Unique identifier for the run
Runs appear in the Admin UI under Runs, with the n8n execution ID as their correlation ID.
Error Handling
| Answer | Message |
|——–|———|
| 403 from the cluster | “The cluster refused the service key. It was revoked or has no rights here. Create a new key in the Admin UI: Service accounts → n8n → Create key.” |
| 401 from a run, after the node’s own retries (6, 10 s apart) | “The project’s access key is not active yet or was revoked. Try again in a minute.” |
| 404 without a JSON body, after the node’s own retries (6, 10 s apart) | “The cluster serves nothing at this address yet. A newly deployed project takes about a minute to be reachable.” |
| 400 | The cluster’s detail, then one line per invalid field:
| 500 | The cluster’s detail, plus the Blueprint’s exception type |
| 429 or 503 | The cluster’s detail, plus “Retry after
| Any other | The cluster’s detail, else its title, else “Request failed with status
While loading the field list, a 401 or 404 is retried the same way; only if it persists does the list show “Access to
With Continue On Fail, a failed item outputs { error, statusCode, ...body }.
