RXJ – AI Workflow Automation Platform

RXJ is a modern AI-native workflow automation platform inspired by tools like n8n, Zapier, and Make.com. It enables users to visually build, automate, and execute workflows using AI models, APIs, messaging systems, productivity tools, webhooks, and realtime execution pipelines.

The platform is designed as a scalable SaaS product with:

• visual workflow automation
• AI-first architecture
• realtime execution monitoring
• secure credential management
• multi-plan subscription system
• usage-based monetization
• onboarding and billing experience
• a public API for running workflows from your own code

---

🚀 Features

🎨 Visual Workflow Builder

• Drag-and-drop workflow editor powered by React Flow
• Dynamic node-based architecture
• Realtime node execution indicators
• Zoom, pan, and edge connection support
• Topological dependency resolution
• Shared execution context between nodes
• Modular execution engine
• Per-node error handling from the node toolbar: On Error (Stop / Continue), Retry On Fail, Execute Once
• Build with AI: describe a workflow, or a change to the one on the canvas, and a model builds it (see "Build with AI")

---

⚡ Workflow Execution Engine

• Branch-aware execution: only connections activated by IF / Switch / Filter / Text Classifier are followed
• Loops that run a sub-flow once per list item
• Per-item execution after list nodes (see below)
• Sub-workflows: one workflow can call another and use its result
• Error handling: Retry On Fail, Continue on error, Error Trigger, Stop and Error
• Wait node: pause a run for a time, until a date, or until its resume URL is called (see "Waiting executions")
• Human approval: AI Agent tools that wait for a person's Approve or Reject, and a Send and Wait for Approval node
• Hosted forms: a Form Trigger with its own public page, multi-step forms with the Form node, and a Wait node that resumes on a form
• Website chat widget: a public Chat Trigger with an embed snippet, a hosted chat page, per-visitor memory and a handoff to a person
• OCR and vision: an Analyze Image / Document node that reads images and PDFs, scanned ones too, with a vision model
• Web Search and Read Web Page nodes, usable as AI Agent tools
• Audio: Transcribe Audio and Text to Speech nodes, and voice messages from the Telegram and WhatsApp triggers
• Inngest background execution system
• Dynamic time-based execution engine via an automated Background Ticker (* * * * * clock matching system)
• Shared execution context
• Dynamic {{variable}} interpolation using Handlebars, plus n8n-style {{ $json.field }} expressions
• Execution persistence in PostgreSQL
• Realtime execution updates
• Retry handling and failure propagation
• Waiting executions can be cancelled

Waiting executions

The Wait node pauses a run and continues it later. While it is paused nothing runs and no request is held open: the pause is an Inngest step.sleepUntil or step.waitForEvent, and the execution has the status Waiting.

Resume	The run continues
After Time Interval	after an amount of seconds, minutes, hours or days
At Specified Time	at a date and time (ISO, e.g. 2026-12-24T09:00:00Z; no time zone means UTC). A time in the past does not wait
On Webhook Call	when the execution's resume URL is called (GET, POST, PUT or PATCH)
On Form Submitted	when the form at {{execution.formUrl}} is submitted (see "Forms"). The answers are at {{wait.form.<field>}}

• Resume URL. Every execution has its own: <app>/api/webhooks/wait/<executionId>/<token>. The token is an HMAC of the execution id made with ENCRYPTION_KEY, so the URL cannot be guessed and nothing is stored for it. It is available from the first node on as {{execution.resumeUrl}} (or {{ $execution.resumeUrl }}), so a node before the Wait node can send it out, for example as an approval link in an email. Whoever has the URL can continue that one execution, so send it only to who should decide.
• What the call sent is under the Wait node's variable (default wait): {{wait.body}}, {{wait.query}}, {{wait.headers}}, {{wait.method}}, and {{wait.resumedBy}} (webhook, timeout or timer).
• Timeout. On Webhook Call takes an optional timeout and what to do when nobody called in time: Continue the workflow ({{wait.timedOut}} is true) or Fail the workflow. Without a timeout it waits the longest the server allows.
• Longest wait. 7 days, which is the most Inngest's free plan can sleep. Set WAIT_MAX_DAYS on a plan that allows more.
• Cancel. A waiting execution has a Cancel button on its page. It is marked Failed with "Cancelled by the user while it was waiting", the Inngest run is stopped, and the nodes after the Wait node never run. The page also shows when the wait ends and, for On Webhook Call, the resume URL.
• The resume URL answers 409 while the execution is not waiting for a call (it has not reached the Wait node yet, was already resumed, or has finished) and 404 for a wrong token. One URL serves every Wait node of the execution, one call per wait.
• The token is replaced by [REDACTED] in stored node input and output, and "All Workflow Data" webhook responses leave the URL out.
• A link opened by a mail scanner or a link preview counts as a call. For approvals that matter, link to a page or form that sends a POST instead.
• Waiting executions are not removed by the retention cleanup, cannot be run again until they finish or are cancelled, and a Wait node cannot be an AI Agent tool. After a list node the Wait node pauses once for the whole list.

Send and Wait for Approval

The Send and Wait for Approval node asks a person a yes/no question in a normal workflow and pauses until they answer. It sends a title and optional details with the same signed, single-use, expiring Approve / Reject links as the AI Agent's tool approvals (see "Human approval for tools"), through the same channels: the app's Approvals page, email, Slack, Telegram or WhatsApp.

• The run continues through the Approved or the Rejected output. Later nodes can also read {{approval.approved}}, {{approval.decision}} (approved, rejected or expired), {{approval.timedOut}} and {{approval.decidedVia}} (link or app).
• Timeout (default 24 hours, at most the longest wait) and When Nobody Answers: continue through Rejected, or fail the workflow.
• While it waits the execution is Waiting and can be cancelled. After a list node it asks once for the whole list.

Forms

A workflow can have its own form: a public page hosted by the app, no sign-in needed.

• Form Trigger. Its settings show the Form URL, <app>/forms/<id> (the id is the trigger node's). The page works while the workflow is active. A submission starts the workflow with the answers at {{form.<field>}} and {{formMeta.submittedAt}}.
• Fields: Text, Email, Number, Dropdown, Date, File Upload and Checkbox, each with a label and a Required switch. A field's value is read by a name made from its label (Your name becomes {{form.your_name}}); the settings show it under each field.
• Title, description, button label, and After Submit: show a thank-you message, or redirect to a URL (http or https only).
• Form node: the next page of a multi-step form. Place it anywhere after the Form Trigger. When the run reaches it, the person who is filling in the form is shown that page next, and the workflow waits for it (the same Inngest wait-for-event as the Wait node: the execution is Waiting, and can be cancelled). Its title, description and messages can use earlier answers, for example Hello {{form.your_name}}. The answers are at {{formPage.<field>}}. The form ends with the After Submit setting of the last page that was submitted.
• Wait node, On Form Submitted: pauses a run of any workflow until a form is filled in. Send the link {{execution.formUrl}} from an earlier node (an email, a chat message). It is different for every execution, cannot be guessed, and is not the resume URL. The execution's page shows it while the run waits.
• Uploaded files are stored like every other workflow file: the same size limit per file (MAX_FILE_SIZE_MB), counted against the workflow owner's storage (MAX_USER_STORAGE_MB), removed after FILE_RETENTION_DAYS, and only ever downloaded as attachments. The value of a file field is a file variable: use form.cv in an email's Attachments, in Extract from File, and so on. Nothing is stored when the submission is not valid.
• Checked on the server: required fields, email and date formats, numbers, that a dropdown value is one of its options, and file sizes. Only the form's own fields are read; anything else that is sent is ignored.
• Rate limit: 30 submissions per minute per form (FORM_RATE_LIMIT_PER_MINUTE), counted before anything else is done.
• CAPTCHA (optional): the Form Trigger's "Require a CAPTCHA" switch adds a Cloudflare Turnstile check, verified on the server before any file is stored. It needs and ; without both keys the form works without the check.

Per-item execution

Like n8n, nodes run once per item after a list node.

• Where it starts: Split Out, Sort, Limit, Remove Duplicates, Summarize, RSS Read, Extract from File (CSV rows), or a Merge that combines lists send their list onward as items.
• What happens next: every following node runs once per item. The item is {{item}} or {{ $json }}, for example {{item.name}} or {{ $json.name }}.
• Routing: IF, Filter, Switch and Text Classifier decide per item, so both IF branches can run, each with its own items.
• Paired data: a later node's reference to an earlier node's variable gives the result for the same item.
• Where it ends: an Aggregate, Loop or Convert to File node. After it, nodes run once again and each per-item node's variable holds { items, count }.
• Execute Once (node toolbar) runs a node for the first item only.

Without a list node nothing changes: every node runs once. An HTTP Request or Code node that returns a list does not split into items by itself; add a Split Out after it. At most 100 items can reach one node (MAX_ITEMS_PER_NODE).

Expressions

Both syntaxes work in every node field, side by side.

Syntax	Meaning
{{webhook.body.name}}	A workflow variable (Handlebars)
{{json myApiCall}}	An object or list as JSON
{{ $json.webhook.body.name }}	The same variable, n8n style. Inside a list, $json is the current item
{{ $json.price * $json.quantity }}	Any JavaScript expression, run in a sandbox
{{ $('myApiCall').item.json.id }}	Another node's result, by its variable name
{{ $now }}, {{ $today }}, {{ $itemIndex }}	Current time, start of today, position in the list
{{$fromAI "city" "The city"}} / {{ $fromAI('city') }}	A value the AI Agent fills in when the node is its tool
{{shellQuote webhook.body.name}}	A value made safe to put into an SSH command

Differences from n8n: $json is the whole set of workflow variables (not the previous node's output) unless the node is running for an item; $('name') looks up a variable name; $now is a plain date with toISO(), not a Luxon object.

---

📜 Execution Logs & Monitoring

RXJ includes a comprehensive execution monitoring system.

Pinned data and partial execution

Two ways to test one part of a workflow in the editor without running the rest again. Both are on a node's toolbar, under the flask button (a pin once the node is pinned).

• Pin a node's output. "Pin latest output" keeps what the node produced in its newest run; "Pin this output" on a line of the Execution Logs keeps the output of the run that is shown. A pinned node has a violet pin on the canvas. In runs started from the editor (Execute workflow, the chat panel, a partial run) a pinned node is not run: its pinned output is put into the workflow's data and the run goes on from there, down the branch that data leads to. Use it for a node that is slow, costs money (an AI Agent) or sends something, and for a trigger whose real event you do not want to wait for. Unpin makes it run again.
• Live runs ignore pins. A webhook, a schedule, the public chat, the API, a retry from the Executions page and a sub-workflow call always run every node. Pins are not copied into templates.
• Run this node only runs just that node. Run from here runs it and everything after it. In both, the nodes before it are not run: each gets its pinned data, or else the data it saved the last time it ran. IF, Filter and Switch nodes before it are the exception: they only decide and cost nothing, so they are evaluated again and every item takes the branch it belongs on. The node you asked for always runs, also when it is pinned; a pinned node after it is still not run. Other branches are not touched.
• What a partial run needs. The workflow has to be saved (the saved version runs), and the nodes before the chosen one need data: run the workflow once with Execute workflow, or pin them. If a node before it has neither, or the saved data took another branch and never reaches the node, the run fails and says which. A trigger, and a model, memory or tool plugged into another node, cannot be run by themselves.
• In the logs a node that was not run is marked "Not run: pinned data" or "Not run: data of its last run", with the data it was given.
• Where the data comes from. From what earlier executions stored, so it has been through the same redaction: a secret that was masked in the execution log is masked in pinned and saved data too. A workflow set to "Don't save node input/output" stores nothing, so it has nothing to pin and cannot be run partially. Saved data disappears with the execution it belongs to (retention); pinned data stays until it is unpinned or its node is deleted. A file in pinned data is a reference to a stored file, which expires as usual.
• What is pinned is what the node added to the workflow's data in that run (its own variables, and for a router its decision), up to 512 KB per node (MAX_PINNED_DATA_KB). For a trigger it is everything the run started with.
• Limits. Inside a Loop, the nodes of the loop body that come before the chosen node give the data of the loop's last round. A Merge set to wait for all inputs does not run in a partial run that covers only one of its branches.

Workflow version history

Every workflow keeps its earlier versions, so a change can be looked at and undone.

• When a version is kept. Every time Save changes the workflow's nodes or connections (a setting, a credential, a node's place, a connection). A save that changes nothing adds no version. A workflow that was changed without the editor's Save (made from a template, by Build with AI or by Create a chatbot, or given a WhatsApp connection on the chatbot's page) gets its version the first time it runs.
• The History button in the editor's header lists the versions, newest first, each with when it was saved and what changed since the one before: nodes added, removed and changed (by node type and variable name, for example "Changed: HTTP Request (myApiCall)"), connections added and removed, or "Layout only" when nodes were just moved. The summary names nodes; it never shows their settings.
• Restore. "Restore" on any version puts the workflow's nodes and connections back to that version, after a confirmation. The restore is itself kept as a new version ("restored from version 4"), so it can be undone the same way. If the workflow was changed without Save since its newest version, what it holds is kept as a version first. Unsaved changes on the canvas are lost, and the editor reloads. The workflow's name, its Active switch and its settings do not change. A restored node is only linked to a credential that still exists and is yours; a node type that no longer exists is left out; pinned data of nodes that are gone is removed. Restoring is in the audit log.
• How long versions are kept. The newest 50 per workflow, and of those the ones saved in the last 30 days (WORKFLOW_VERSION_LIMIT, WORKFLOW_VERSION_DAYS). The newest version always stays, however old. Versions are deleted with their workflow.
• Executions record their version. Each execution's page shows "Workflow version: Version 12": the saved workflow that run used. The number stays on the execution after the version itself was removed. Executions from before this feature say "Not recorded".
• What a version holds. A copy of the nodes and connections as they are stored, including anything typed into a node's fields. It is only readable by the workflow's owner, like the workflow itself, and the list of versions does not carry the nodes.

Sidebar and Settings

• Sidebar. The logo and the workspace switcher at the top; Build (Workflows, Templates, Chatbots) and Operate (Executions, Approvals, Credentials); and at the bottom your account button (initials, name, email), which opens Settings, Usage & plan, Billing, API Keys, Docs and Sign out. It shows no usage numbers, and fits a 1366 × 768 window without scrolling. Collapsed, it shows the icons with tooltips; on a phone it opens as a sheet.
• Settings has its own menu (tabs on a phone) and one page per section, /settings/<section>; /settings opens Profile, and the old /api-keys opens Settings → API Keys.
  • Account: Profile, Security (two-factor authentication, sessions), API Keys.
  • Workspace: General (name, invitations for you, leaving), Members & roles, Usage & plan, Audit log (your account's sign-ins and changes).
  • AI: Model prices and RXJ AI included (platform admins), AI budgets (this month's spend; the budget is set by the workspace's owner and admins).
  • Enterprise: Git sync, External secrets (both need the Pro plan on the workspace's owner, and an owner or admin), SSO.
  • A section your role or plan cannot use says so ("Owners and admins only", "Requires Pro", "Admins only") instead of showing its controls. The server checks the same rules.

Teams and roles

Every account has a workspace, and can be a member of other people's. Workflows, credentials, executions, chatbots, evaluations, AI usage and budgets belong to the workspace you are working in; pick it in the sidebar. Your two-factor settings, sessions and API keys are your own.

• Members. Under Settings → Members & roles an admin invites someone by email with a role. No email is sent: the invitation waits until that person signs in to RXJ with that address, sees it under Settings → General and accepts or declines it. Where email verification is on, only a verified address can take an invitation. A member can leave; an admin can change a role or remove a member. What a member built stays in the workspace.

• Roles.

  	Viewer	Editor	Admin	Owner
  See workflows, executions, usage and the names of credentials	yes	yes	yes	yes
  Create, edit, run and delete workflows; chatbots, evaluations, approvals, templates		yes	yes	yes
  Use a credential in a node		yes	yes	yes
  Add, change and delete credentials; AI budgets; execution retention			yes	yes
  Invite, remove and change editors and viewers; rename the workspace			yes	yes
  Make or remove admins				yes

• Credentials are used, never shown. A member picks a credential by its name. Its value is not sent to any browser, the owner's included; only admins can replace or delete it.

• Plan limits are per workspace. A workspace has its owner's plan: the number of workflows and credentials, the month's executions, locked nodes, AI credits and AI budgets are counted for the workspace, whoever of its members acts. Settings → Usage & plan shows the plan of the workspace you are in, its trial, what it used this month against each limit, its AI credits and AI spend; Billing is always about your own account.

• Audit log. What members do in a workspace is in its owner's audit log, with who did it.

• How it is stored. A workspace's data is kept under its owner's account: a workflow a member creates has the owner's user id and the workspace's id. That is why running a workflow, its credentials and its limits work the same for every member. Which workspace a request is for comes from a cookie that only picks among the workspaces the user is a member of; the membership and the role are read from the database on every request.

Enterprise features

Three things for companies, under Settings → Enterprise (Git sync, External secrets, SSO). Git sync and external secrets belong to the workspace and are set up by its admins; they need the Pro plan on the workspace's owner (the free trial does not unlock them). What is already set up keeps working after a downgrade; it can no longer be changed.

Environments and Git sync

A workspace's workflows can be kept as JSON files in a GitHub repository, one file per workflow (workflows/<id>.json).

• Set up. Pick the repository (owner/name), a branch that exists, a folder, and a GitHub credential of the workspace whose token can reach the repository ("Contents: read and write" to push). Say whether the workspace is development or production.
• Push (development only) writes every workflow of the workspace to the branch as one commit, and removes the files of workflows that are gone. Nothing is committed when the branch already holds the same. A push is never forced: when the branch moved in the meantime GitHub refuses it.
• Pull makes the workspace's workflows what the files say: a file of a workflow the workspace has replaces its nodes and connections (kept in version history, so it can be undone), any other file becomes a new, inactive workflow. A workflow whose file is not in the branch is left as it is and listed. The plan's workflow limit applies.
• Production workspaces only pull. Their workflows cannot be created, edited, renamed, deleted or restored by hand ("This workspace is a production environment..."); they can still be run and turned on and off, and their credentials are managed as usual. A typical setup is two accounts' workspaces, one development and one production, on two branches or one, with the team as members of both.
• Credentials are never in the repository. A file names the credential a node uses by type and name. The workspace that pulls links a credential of the same type and name; when it has none, the pull says which is needed and the node is left without one.
• Secrets typed into nodes stop a push. A workflow with an API key in a header or a token in a URL is not written to a repository; the push says which workflow and what kind of secret. Move it to a credential.
• Ids. A workflow keeps the id it was first pushed with. In another workspace its nodes get ids of their own, the same on every pull, so executions and pinned data stay with their node. A node that runs another workflow of the same pull is pointed at the local copy.
• Limits. GitHub only (its API, with a token). Up to 300 workflows and 1 MB per file. Workflow names, the Active switch, settings, AI budgets, pinned data and evaluation datasets are not synced, only nodes and connections (and the name).

External secrets

A credential can read its value from HashiCorp Vault (KV engine, version 1 or 2) or AWS Secrets Manager instead of storing it.

• Add a store under Settings → External secrets with a name (vault, aws...), and what reaches it: for Vault the address, a token, the KV mount and optionally a namespace; for AWS a region and an access key. These are stored encrypted and never shown again. Use a token or key that can only read the secrets that are needed.
• In a credential's field, write a reference instead of the secret: the store's name, the secret's path or name, and after # the field, in double curly braces starting with $secrets.. The External secrets settings show an example. For Vault a field is always named; an AWS secret that is one text is used whole when no field is named. A credential that is JSON (an SMTP server) can use references in any of its fields.
• The value is read when the credential is used, kept in the server's memory for 5 minutes (EXTERNAL_SECRETS_CACHE_SECONDS), and never saved. A rotated secret is picked up after that time. Values that were read are removed from what is stored about a run, like every credential value.
• Test on a store reads one secret and shows the names of its fields, never a value.
• A reference only reaches the stores of the credential's own workspace. Vault is called at the address that was saved, without following redirects; an address in a private network is refused unless the operator allowed it (PRIVATE_NETWORK_ALLOWLIST). AWS is called at Amazon's own address for the region.
• Not supported: "Google account" and Salesforce credentials made by signing in (they hold tokens the app refreshes), AWS binary secrets, and Vault login methods other than a token.

Single sign-on (SSO)

People of a company can sign in through its identity provider with OpenID Connect (OIDC): Okta, Microsoft Entra ID, Google Workspace, Keycloak and others. On the login page they type their work email and press Sign in with SSO.

• Register a provider under Settings → SSO: a short id, the email domain, the provider's issuer URL, a client ID and a client secret. At the provider, register the redirect URI the card shows. An account can register providers when it is on the Pro plan (3), or is a platform admin with two-factor on (10).
• The operator has to allow the provider's address first: its origin (for example the Okta or Entra address) must be in TRUSTED_ORIGINS, or registering fails with "not trusted".
• The domain has to be proved. After registering, the card shows a DNS TXT record. Add it at the domain and press Verify domain. Until then the provider signs nobody in. This is what makes it safe: only who controls a domain's DNS can have its addresses signed in through their provider.
• Accounts. Someone who signs in through a provider for the first time gets an account, and joins the workspace of whoever registered the provider as a Viewer. Someone who already has an account with that address is signed in to it. Two-factor codes of RXJ are not asked for after an SSO sign-in: the provider is trusted to do that.
• SAML is not available yet. The plugin's SAML support in the Better Auth version this app is on depends on a library version with known high-severity advisories; the fixed one needs Better Auth 1.7.7. Until that upgrade the server refuses every SAML request and no SAML provider can be registered.
• The provider's client secret is stored by the sign-on plugin in its own table, not encrypted with ENCRYPTION_KEY like credentials are.

Dependencies. better-auth, @better-auth/sso, @better-auth/core, @better-auth/utils, @better-fetch/fetch and better-call are pinned to exact versions that belong together. Upgrade them together.

Agent evaluations

Test a workflow over a set of inputs, score what it answers, and compare runs. Open it with the Evaluations button in the editor's header (/workflows/<id>/evaluations).

• Datasets. A workflow has up to 20 datasets, each with up to 100 rows. A row is an input and what is expected for it: the expected output, a JSON schema, or grading criteria, depending on how the dataset is scored. Rows are added one at a time or pasted as JSON ([{ "input": "...", "expected": "..." }]).
• How a row runs. Each row is a real execution of the saved workflow, started from the trigger the dataset names: a Chat Trigger gets the input as the message (with a session of its own, so memory does not carry from row to row), a Webhook gets it as the request body, a Manual Trigger and When Executed by Another Workflow get the input's fields as starting data (a plain text is input). Pinned data is not used.
• Output to score names the part of the run's data that is scored, written like a variable: agent.text. Empty means all of the run's data.
• Scorers. Exact match (the same text, or the same JSON whatever the order of its keys), Contains (ignoring case and white space), JSON schema match (the output is JSON that fits the schema; a ```json block is unwrapped), and LLM judge: a model you pick grades each answer from 0 to 1 against the row's expected answer and the dataset's grading criteria, and 0.7 or more passes. The judge uses one of your model credentials or RXJ AI (included), like Build with AI.
• Runs and the comparison. Name a run ("gpt-4o-mini"), run it, change the model or the prompt in the editor, save, and run again. Each run shows its score (the average of its rows, a failed row counts as 0), rows passed, cost (the workflow's own model calls; the judge's cost is listed apart), average time per row, the models that answered and the workflow version. Tick up to four runs to see them side by side, row by row, with the best score, lowest cost and shortest time marked, each row's output and the reason for its score, and a link to its execution.
• What a run costs and does. Rows are executions: they count towards the plan's monthly executions (a run that would go over is refused), their model calls are paid for and count towards AI budgets, and their nodes do what they do, so a workflow that sends a message sends it for every row. One evaluation runs per workflow at a time, rows one after the other, each with 10 minutes to finish; a run can be cancelled. In the executions list these runs have the source "Evaluation".
• Limits. A workflow set to "Don't save node input/output" cannot be evaluated: there is no saved result to score. A row that reaches a Wait, Form or approval node does not finish on its own and counts as failed. Datasets, runs and results are only readable by the workflow's owner and are deleted with the workflow.

Execution Tracking

Every workflow execution stores:

• Execution ID
• Workflow ID
• Trigger source
• Execution timestamps
• Final execution status
• Runtime context data
• Error information

---

Node Execution Logs

Each node execution stores:

Field	Description
nodeId	Unique node identifier
type	Node type
status	Current node state
startedAt	Execution start time
completedAt	Completion timestamp
input	Incoming execution data
output	Node output
error	Failure details

---

Supported Node States

Status	Meaning
initial	Not run yet
loading	Executing, or paused at a Wait node
success	Completed
error	Failed

An execution is Running, Waiting (paused at a Wait node), Success or Failed.

---

Realtime Updates

Realtime workflow updates use:

• Inngest Realtime Channels
• Zustand stores
• React Flow node rendering

---

Error Monitoring

• Sentry integration
• Stack trace monitoring
• Workflow failure propagation
• Node-level diagnostics
• Retry diagnostics

---

🧠 AI Integrations

AI Agent (Tools Agent)

Works like the n8n AI Agent: a chat model that decides which tools to call and loops until it has an answer.

• Chat Model (required): connect an OpenAI, Anthropic, Gemini, DeepSeek, Kimi, Qwen or Chat Model node to the Chat Model port; its credential and model are used. A Model Router can be connected instead, to try a cheap model first (see below).
• Parser (optional): a Structured Output Parser makes the agent answer with JSON in a structure you define; {{output}} becomes an object.
• Memory (optional): a Memory node keeps the last N messages per session and replays them as real chat turns. A Postgres Memory node adds a summary of older messages and long-term facts about each contact (see "Persistent memory").
• Tools (optional): any node connected to the Tools port becomes a tool. Give each one a name and description in the agent's settings. An MCP Client node adds all the tools of an MCP server; an Execute Workflow node makes another workflow a tool; a Vector Store node lets the agent search your documents.
• {{$fromAI "name" "description"}}: write this in any field of a tool node to let the agent fill in that value.
• Prompt source: taken from the trigger ({{chatInput}}, set by the Chat, Telegram and WhatsApp triggers) or defined in the node with {{variables}}.
• Options: System Message, Max Iterations (default 10), Max Tool Calls (default 25), Allow dangerous tools (off), Require approval per tool (see "Human approval for tools"), Return Intermediate Steps.

Tool safety (prompt injection)

The model decides which tools to call, and it acts on text it has read: a chat message, an email, a web page. That text can try to give it orders. These limits apply to every agent:

• Risk levels: each connected tool is shown as Read, Write or Dangerous in the agent's settings.

  Level	What it covers
  Read	Searching, getting and listing; Vector Store search; HTTP GET; Web Search and Read Web Page; calculations and text nodes
  Write	Sending a message; creating or updating a record; HTTP POST/PUT/PATCH; MCP Client; anything not known to be harmless
  Dangerous	SSH; raw SQL (Postgres and MySQL "Execute Query"); every delete operation and HTTP DELETE; Execute Workflow

• Dangerous tools are off by default. With one connected and Allow dangerous tools unchecked, the run fails at the agent with a message naming the tool. Agents saved before this option existed count as unchecked, so a workflow that already uses such a tool needs the option switched on once.

• Max Tool Calls limits how many tool calls one run may make in total. The run fails with a clear error when the model asks for more.

• SSH as a tool: every $fromAI text value in the command is quoted for the shell automatically (inside '...', "..." and $( ) too), so it always arrives as one argument. A value placed inside backticks, $(( )), a # comment, $'...' or after a heredoc cannot be quoted safely and fails the run.

• Tool results are data: the system message tells the model that tool results are untrusted data and never instructions, and each result is handed to the model inside a marked <tool_result> block.

These limits reduce the risk; they do not remove it. Give an agent only the tools and credentials it needs.

Human approval for tools

Each tool in the agent's settings has a Require approval switch. When the model calls such a tool, the tool is not run: the run pauses (the execution shows as Waiting, using the same Inngest wait-for-event as the Wait node), a request with the tool's name and its arguments is sent to a person, and the run continues with their answer.

• Default. On for Write and Dangerous tools, off for Read tools, on AI Agent nodes added to the canvas since this exists. An agent that was already in a workflow keeps running without approvals until a tool's switch is turned on, so nothing that works today starts waiting for a person.

• Send approval requests through (one setting per agent):

  Channel	Needs
  In the app	nothing: the request appears on the Approvals page and on the execution's page
  Email	an SMTP credential and the address to ask
  Slack	an incoming webhook URL
  Telegram	a Telegram bot credential and the chat ID
  WhatsApp	a WhatsApp credential, the Phone Number ID and the number to ask. WhatsApp only delivers free text to someone who wrote to that number in the last 24 hours

  Whatever the channel, the workflow's owner can also answer on the Approvals page.

• Approve / Reject links. <app>/api/approvals/<id>?decision=...&expires=...&signature=.... The signature (HMAC with ENCRYPTION_KEY) covers the request, the decision and the expiry, so a Reject link cannot be changed into an Approve link. A link opens a page that shows the tool and its arguments and asks for a confirmation; only that button answers, so a mail scanner or link preview that opens the link approves nothing. A request is answered once, by whoever is first, and the links stop working when it expires (default 24 hours, set per agent).

• Approved: the tool runs with exactly the arguments that were shown, and the agent goes on with its result.

• Rejected: the tool is not run, the agent is told The user rejected this action and goes on (it usually says so in its answer). A request that expires is treated the same way, with a message saying nobody answered in time.

• Several calls that need approval in one turn are asked one after the other. Calls waiting for approval count toward Max Tool Calls. The tools of an MCP Client node share that node's switch.

• The tool's arguments are shown as plain text everywhere: they are never rendered as HTML or evaluated as a {{template}}.

• Cancelling a waiting execution withdraws its requests. If the request cannot be sent (a wrong credential, say), the run fails with that error instead of waiting.

Think Tool and AI Agent Tool

Two nodes that only belong on an AI Agent's Tools port.

Think Tool lets the agent stop and write down its reasoning or a plan before it goes on, which helps on tasks with several steps or before an action that is hard to undo.

• It has no effect: nothing is stored, sent or changed. The agent is answered "Thought noted." and carries on.
• The thought itself is in the agent's intermediate steps (switch on Return Intermediate Steps to see it).
• It is a "read" tool, so it never asks for approval. Each thought counts as one tool call toward Max Tool Calls.
• Its Description is what the agent is told the tool is for; use it to say when you want the agent to think.

AI Agent Tool is an agent that another agent can hand a task to (multi-agent). It has a Model and a Tools port of its own, a Name and a Description the calling agent sees, and its own System Message.

• It sees only the task. The calling model writes a prompt for it; nothing else of the conversation is passed on, and only its final answer comes back.
• Approval is decided once, at the top. A run can only pause for a person in the agent that is a step of the workflow. So the tools of an AI Agent Tool run without asking, and the whole call is one tool of the calling agent: its risk level is "write", and on agents with the risk-based default it requires approval, showing the task. Switch that off per tool in the calling agent's settings when its tools are harmless.
• Dangerous tools connected to it need its own Allow Dangerous Tools switch.
• Mistakes are found before the run starts: no model on its port, no description, or a dangerous tool that is not allowed fails the calling agent with the reason, instead of reaching the model as a tool that "did not work".
• Its model calls are recorded under its own name in the usage figures and held to the AI budget.
• Agents can call agents up to three deep; two AI Agent Tool nodes that are each other's tool fail with that message.
• It has no Memory or Structured Output Parser port: memory belongs to the agent the user talks to.

Guardrails

Checks a text and sends the run on through its Pass or Fail output. Put it before an AI Agent to check what a user wrote (Text To Check {{chatInput}}), or after one to check the answer ({{output}}); The Text Is says which.

Check	How	When it fails
Personal data	In the app, by pattern: email addresses, phone numbers, card numbers (13 to 19 digits that pass the card check digit) and national IDs (US Social Security number, Pakistan CNIC, India Aadhaar, UK National Insurance number). Each kind has a switch	Only with Block. With Mask each value becomes [EMAIL], [PHONE], [CARD] or [ID] and the text passes
Maximum length	In the app, in characters	The text is longer
Prompt injection	A chat model on the node's Model port judges the text: for a user's message, whether it tries to override the assistant's instructions or bypass its restrictions (a jailbreak); for an answer, whether the assistant was manipulated (it reveals its instructions, drops its rules)	The model says so
Allowed topics	The same model decides whether the text is about one of the topics you list; greetings and thanks pass	It is about something else

• The result is at {{guardrails.passed}}, {{guardrails.reason}} (one line, why it failed), {{json guardrails.violations}} (every failed check) and {{guardrails.text}}, the checked text with personal data masked. Give {{guardrails.text}} to the next node instead of the original. Only the kinds and counts of what was found are reported, never the values.
• Connect the Fail output to what should happen then, for example a node that sends a polite refusal. An output with nothing connected simply ends that branch.
• The model is only called when it has to be: not when the text already failed on length or blocked personal data, and not for an empty text. It is given the masked text, so what was found is not sent to the model provider. Both model checks share one call, which is recorded in the usage figures and held to the AI budget.
• A model check without a model on the port is an error, not a pass. An answer of the model that cannot be read fails the text: a guard that cannot tell does not wave things through. If the model itself cannot be reached, the node fails like any other AI node.
• Use a cheap, fast model for the port; the check is a yes or no question. Of a very long text the model reads the first 6000 and the last 2000 characters.
• What it does not promise. Personal data is found by the usual ways it is written, not every way: a phone number spelled out in words, a name or a street address is not caught, and a ten or eleven digit order number is taken for a phone number. A model's verdict on prompt injection can be wrong in both directions. Guardrails is one layer next to tool approval, tool risk levels and the agent's own instructions, not a replacement for them.
• In a list it checks every item on its own and routes each one.

Persistent memory (Postgres Memory)

A second node for the agent's Memory port, next to the simple Memory node. It keeps everything in the app's own database, so it needs no credential.

• Chat history per session. Every turn is stored under the Session ID (by default {{sessionId}}, which the chat, Telegram, WhatsApp, Messenger and Instagram triggers set). Message Limit (default 20, up to 100) is how many of the latest messages the model is given; older ones stay stored.

• Summarise Older Messages (off by default) keeps a running summary of what no longer fits in the limit and gives it to the model at the start of every turn. It is written by the agent's own model after a turn, once six messages have fallen out of the window, so not every turn pays for one. Its cost is recorded with the agent's. A summary that cannot be written never fails the run; it is tried again after a later turn.

• Long-Term Facts (on by default) are key/value notes about a contact that outlive the conversation: a name, a preference, an order number. The agent gets two built-in tools:

  • recall_facts reads everything saved about the contact;
  • remember_fact saves one fact under a short key, replaces it when the key exists, and removes it when the value is empty.

  What is saved is also shown to the model at the start of every turn, so it does not have to ask first. The two tools only touch the agent's own notes and never ask for approval.

• Contact ID says who the facts are about. Empty means the session. Use something that stays the same for a person, for example {{whatsapp.from}} or a customer ID, so the facts are there in the next conversation too.

• Limits: 50 facts per contact, a key of up to 64 characters (lower case letters, digits and _), a value of one line of up to 500 characters.

• Facts belong to the account, not to one workflow. Every agent of the same account that uses the same Contact ID sees and changes the same facts. Another account never does.

• What the model wrote is treated as notes. The summary and the facts are given to the model marked as data, with the instruction not to follow anything written inside them, and a fact cannot contain line breaks or angle brackets. This lowers, but cannot remove, the risk that a user talks the agent into "remembering" an instruction.

• Facts and summaries hold what people told the agent. They are deleted with the account. There is no screen to view or delete them yet; the agent removes a fact when asked to forget it.

• The older Memory node works as before.

Website chat widget

Switch on Make chat public in the Chat Trigger's settings, save and activate the workflow, and anyone can chat with it:

• Embed snippet: <script src="<app>/widget.js" data-id="<id>" async></script>, shown in the settings to copy. It adds a floating chat button to a website; a click opens the chat window. On a phone the window fills the screen.
• Hosted chat page: <app>/chat/<id>, the same chat on a page of its own. The widget shows this page in a frame, so the website's styles and scripts cannot reach into the conversation.
• Look: title, colour, welcome message (shown first, not sent to the workflow) and an avatar (the https address of an image).
• Urdu and Arabic: the chat's direction is Automatic (from the title and welcome message), left to right, or right to left. Right to left mirrors the layout and puts the button on the left; every message is always shown in the direction of its own text.
• One conversation per visitor. A visitor's browser makes a session id and keeps it in its storage (when storage is blocked the chat still works until the page is closed). The workflow gets it as {{sessionId}}, in the form widget:<id>:<visitor>, so a Buffer Memory node remembers each visitor separately. A returning visitor sees their conversation again; New chat starts a fresh one.
• Allowed domains: a list of sites that may show the widget (example.com, *.example.com). Browsers refuse to frame the chat anywhere else, and widget.js shows no button there. Empty means any site. The hosted chat page itself is always reachable by its link.
• Rate limits: 60 messages per minute per widget (CHAT_WIDGET_RATE_LIMIT_PER_MINUTE) and 10 per minute per visitor (CHAT_VISITOR_RATE_LIMIT_PER_MINUTE), counted both by session id and by address.
• Answers are not streamed. The agent's answer is produced in a background run, so the chat shows a typing indicator and then the whole answer. Only the agent's answer (output) is ever sent to the visitor, never the rest of the run's data. The workflow must keep "Save execution data" on: the answer is read from the run's saved output.
• "Talk to a human" (optional): a button under the chat. The visitor can leave an email or phone number; the conversation is sent to the person you set, by email (SMTP credential), Slack (incoming webhook) or WhatsApp, and the bot stops answering in that conversation. Messages written afterwards are kept and answered with a short note. The person replies through their own channel: there is no agent inbox in the app. If the message cannot be sent, the visitor is told and the bot keeps answering.
• Conversations of the widget are stored for 30 days. Every message is a workflow execution and counts toward the plan's monthly executions. A message has at most 4000 characters.

Model nodes

Node	Description
OpenAI	GPT models with dynamic prompts
Anthropic	Claude models (default claude-sonnet-5-5)
Gemini	Google Gemini models
DeepSeek	DeepSeek models (default deepseek-flash)
Kimi	Moonshot AI's Kimi models (default kimi-k2.6), international or China region
Qwen	Alibaba Cloud's Qwen models (default qwen-plus), international or China region
Chat Model	Any OpenAI-compatible API, with a preset per provider (below) or a custom base URL

Chat Model provider presets

The Chat Model node's Provider dropdown fills in the provider's base URL and suggests its models. The list lives in src/features/executions/lib/chat-model-providers.ts.

Provider	Base URL	Suggested models
OpenRouter	https://openrouter.ai/api/v1	~openai/gpt-sol-latest, ~anthropic/claude-sonnet-latest
Groq	https://api.groq.com/openai/v1	use Load models
Together AI	https://api.together.ai/v1	MiniMaxAI/MiniMax-M3
Mistral	https://api.mistral.ai/v1	mistral-small-latest, mistral-large-latest
DeepSeek	https://api.deepseek.com	deepseek-flash, deepseek-v4-pro
Zhipu Z.ai (international)	https://api.z.ai/api/paas/v4	glm-5.3, glm-5.3-flash, glm-5.2, glm-4.7, glm-4.7-flash, glm-4.5-flash
Zhipu BigModel (China)	https://open.bigmodel.cn/api/paas/v4	the same, and glm-4-flash-250414
MiniMax (international)	https://api.minimax.io/v1	MiniMax-M3, MiniMax-M2.7, MiniMax-M2.7-highspeed
MiniMax (China)	https://api.minimaxi.com/v1	MiniMax-M2.7, MiniMax-M2.7-highspeed
ByteDance Volcengine Ark (Doubao)	https://ark.cn-beijing.volces.com/api/v3	doubao-seed-2-0-pro-260215, doubao-seed-1-6-251015, or an endpoint ID (ep-...) from the console
Xiaomi MiMo	https://api.xiaomimimo.com/v1	mimo-v2.6-pro
SiliconFlow (international)	https://api.siliconflow.com/v1	Qwen/Qwen3-32B
SiliconFlow (China)	https://api.siliconflow.cn/v1	deepseek-ai/DeepSeek-V4-Flash, moonshotai/Kimi-K2.7-Code

• International and China platforms are separate. Zhipu, MiniMax and SiliconFlow each run two platforms with their own accounts: an API key from one does not work on the other. Pick the preset of the platform the key came from.
• Load models (on the Chat Model, DeepSeek, Kimi and Qwen nodes) asks the provider for its current list with the selected credential (GET <base URL>/models) and shows it to pick from. When that fails, for example because the provider has no such list or refuses the key, the reason is shown and the suggested models stay. The model field always accepts a typed ID. The request goes through the same guard against private addresses as the node itself.
• "Data processed in China" appears under the model field when requests go to a provider's servers in mainland China: Zhipu BigModel, MiniMax (China), Volcengine Ark, SiliconFlow (China), DeepSeek, and the China region of the Kimi and Qwen nodes. It follows the address requests are sent to (MAINLAND_CHINA_HOSTS in the same file), so a custom base URL that is not on that list shows nothing, whatever country it is in.
• "Free" marks models the provider offers at no charge: Zhipu's glm-4.7-flash, glm-4.5-flash (and glm-4-flash-250414 on BigModel), and OpenRouter models whose ID ends in :free. The list is src/config/free-models.ts and nothing else: change that file to mark or unmark a model. Free tiers have rate limits, and providers change them: the provider's pricing page is what counts.
• Retired model IDs. Providers retire models. Moonshot discontinued the moonshot-v1 models (the Kimi node's old default) on 31 August 2026, and DeepSeek announced the end of the deepseek-chat and deepseek-reasoner names for 24 July 2026. A node saved with one of those keeps it, and its dialog says so and names a current model; the node is not switched on its own, because another model has another price.
• The model IDs above are what each provider's documentation showed on 10 October 2026. They go out of date; Load models does not.

Fallback models

A Chat Model node can name up to 5 Fallback Models: an ordered list of other models to try when its own model does not answer.

• When the next model is tried: the model timed out (Fallback Timeout, 60 seconds by default), answered HTTP 429 or a 5xx error, or could not be reached. A wrong API key or a bad request (401, 400...) is not passed on to a fallback: that is a mistake in the settings, and the run fails with the provider's own error.
• Each line has a model ID and, optionally, another provider preset and another credential. Left as they are, the node's own provider and credential are used, which is the usual case for a second model at the same provider. Another provider needs its own credential.
• Where it applies: when the node runs as a step, and when it is the model of an AI Agent, a Text Classifier or an Information Extractor. In an agent's loop every call starts with the first model again.
• The last model on the list has no time limit, because nothing can take over from it.
• If every model fails, the error names each one and why: all 3 models failed (openrouter / a: HTTP 429; groq / b: timeout; ...).

The DeepSeek, Kimi, Qwen, OpenAI, Anthropic and Gemini nodes have no fallback list. Put them behind a Model Router, or use a Chat Model node.

Model Router

A sub-node for the AI Agent's Chat Model port. Plug one model node into its Cheap port and another into its Strong port, and connect the router to the agent.

• The agent asks the cheap model first.
• The strong model takes over when the cheap one returns any error (also a wrong key) or takes longer than Cheap Model Timeout (120 seconds by default). If the cheap node is a Chat Model with fallbacks, a timeout, 429 or 5xx tries those first.
• With a Structured Output Parser on the agent: when the cheap model's final answer does not have the required structure, the strong model answers instead (option "Switch when the output parser fails", on by default). The tools are not run a second time: the strong model is given the question, what the tools returned and the cheap model's draft. "Fails validation" means what it meant before: the answer is not JSON that can be read.
• If the strong model fails too, the run fails as it would without a router.

Which model answered

Nodes that can switch models say so in their output:

Field	Meaning
modelUsed, providerUsed	The model that gave the (final) answer
fallbackUsed	true when a model other than the first choice answered at least one call
modelAttempts	Every attempt in order: { provider, model, outcome }, where outcome is answered, timeout, connection error, HTTP 429... The provider's error text is not kept here
modelRoute	AI Agent with a Model Router only: { tier: "cheap" | "strong", reason }

They are on the Chat Model, DeepSeek, Kimi and Qwen nodes ({{chatModel.modelUsed}}) and on the AI Agent ({{aiAgentOutput.modelUsed}}); the Text Classifier and Information Extractor have modelUsed and fallbackUsed. Token usage and cost (see AI token usage and cost) are recorded per model that answered, each at its own price.

AI nodes

Node	Description
Model Router	Plugs into the AI Agent's Chat Model port: a cheap model first, a stronger one when it fails or its answer does not fit the parser
Text Classifier	Sorts text into your categories with a connected model and continues on that category's output
Information Extractor	Pulls named values (name (type): description) out of free text
Analyze Image / Document	Reads an image or a PDF, scans included, with a vision model: all its text (OCR), named fields, or a description. See "Analyze Image / Document"
Structured Output Parser	Plugs into the AI Agent's Parser port to force a JSON structure
Vector Store	Insert, search and delete documents by meaning (RAG), with OpenAI, Gemini or OpenAI-compatible embeddings. Text splitting, metadata filters, reranking, and pgvector when the database has it (see "Vector Store and Document Loader")
Document Loader	Loads a Google Drive folder or a Notion database into a Vector Store collection, skipping documents that have not changed
MCP Client	Gives an AI Agent the tools of an MCP server (Streamable HTTP, or SSE for older servers)
Think Tool	A tool for an AI Agent: it writes down its reasoning; nothing else happens (see "Think Tool and AI Agent Tool")
AI Agent Tool	An agent with its own model, tools and description on another agent's Tools port (multi-agent)
Guardrails	Checks text before or after an agent: personal data (mask or block), maximum length, prompt injection and allowed topics, with Pass and Fail outputs (see "Guardrails")

MCP: client and server

MCP Client gives an AI Agent the tools of an MCP server. Its Transport is Streamable HTTP (the default: one URL, usually ending in /mcp) or SSE for older servers (one URL, usually ending in /sse, that the client keeps open while the answers arrive on it). With SSE the node opens a connection for each tool call and closes it again, so nothing stays open when the agent stops; the credential is only sent to the server's own site. Servers that only run locally over stdio are not supported.

MCP Server Trigger makes a workflow a tool that MCP clients (Claude, Cursor, another agent, or this app's own MCP Client node) can call.

• Address: <app>/api/mcp/<workflow id>, Streamable HTTP, shown in the node. The workflow has to be active.
• Bearer token: callers send Authorization: Bearer <token>. The token is typed into the node, has to be at least 16 characters, is compared in constant time and is never accepted in the address. Requests are rate limited per workflow before the token is checked.
• One trigger node is one tool: a Tool Name, a Tool Description (the calling model decides from it when to use the tool) and its input schema.
  • Parameters are one per line, name (type): description, with the types string, number, integer, boolean, list and object. A parameter is required unless it says optional: includeItems (boolean, optional): Also return the line items.
  • Input Schema (JSON) takes a JSON Schema of type object for what the lines cannot express, and is then used instead.
• Several tools: put several MCP Server Trigger nodes in the workflow, each with its own branch. A call runs only the branch of the tool that was called. Use the same token on all of them; a tool is only offered to callers that have its node's token.
• In the workflow the call is at {{mcp.arguments.<parameter>}}, {{json mcp.arguments}} and {{mcp.tool}}. Arguments are checked against the schema first (required ones present, the right type at the first level); a wrong call is answered to the model as a tool error and does not start a run.
• What the caller gets back, in this order:
  1. the body of a Respond to Webhook node, as soon as one has run;
  2. the variable named in the trigger's Result field, for example agent.output;
  3. everything the run produced, as JSON.
• A failed run is returned as a tool error with the run's error message. A run that reaches a Wait or approval step answers that it is paused. A run that takes longer than 50 seconds (MCP_TOOL_TIMEOUT_MS) answers that it is still running; it carries on, and its result is in the executions list.
• A workflow set to "Don't save node input/output" has no result to return unless it uses a Respond to Webhook node.
• The server is stateless: no sessions, no event stream (a GET is answered 405, as the transport allows), tools only. It speaks protocol versions 2025-06-18, 2025-03-26 and 2024-11-05.

Vector Store and Document Loader (RAG)

The Vector Store keeps text in chunks with an embedding each, per user and collection, and finds the chunks closest in meaning to a query. The Document Loader fills a collection from a Google Drive folder or a Notion database.

Inserting

• Split By cuts long text into chunks: by characters (the default, as before), by tokens, or by Markdown headings. Chunk Size and Chunk Overlap apply to all three; an overlap of 0 means none.
  • Tokens are estimated at four characters each. No tokenizer is bundled, and Urdu, Arabic or Chinese text makes more tokens than that.
  • With Markdown headings every section is a chunk of its own and starts with the headings it sits under ("Guide > Returns"), which are also saved as the chunk's heading metadata. A section longer than Chunk Size is cut further; a # inside a code block is not a heading.
• Document ID (optional) names the document. Inserting the same text again then does nothing (unchanged: true), and a changed text replaces the old chunks instead of adding to them. Without it every insert adds chunks, as before.
• One document can make at most 200 chunks.

Searching

• Metadata Filter is a JSON object, for example {"source": "faq"}. Only chunks whose metadata contains every field of it with the same value are searched (nested objects too; a list in the filter needs each of its entries in the stored list). Values are not converted: 3 does not match "3".
• Rerank With fetches more candidates than Limit (five times as many, between 20 and 50), has a second model read the query together with each one, and returns the best Limit:
  • Cohere Rerank or Jina Reranker, with a Rerank Credential (a Cohere key, or the Jina key also used by Read Web Page). Their calls are not in the AI usage figures, because they are not billed by token.
  • Connected chat model: connect a model node to the Vector Store's Rerank Model port. Its call is recorded like any other. If its answer is not a list of passage numbers, the results keep their order and rerankNote says so.
  • Each match keeps its embedding score and gets a rerankScore; reranked says whether the order came from the reranker.
• engine in the result says who compared the embeddings: pgvector, pgvector-index or app.

pgvector

• When the database has the vector extension, the migration creates it and adds an embeddingVector column next to the existing embedding array, with HNSW indexes for embeddings of 768, 1024, 1536 and 3072 dimensions (cosine distance). Searches are then answered by the database, with no limit on the size of a collection.
• A collection of up to 10,000 chunks is compared exactly, in the database. Above that the index is used when there is one for the model's size and pgvector is 0.8 or newer; if the index finds fewer chunks than asked for, the exact comparison runs after it.
• The old way stays as the fallback. Without the extension, with VECTOR_STORE_ENGINE=app, or when a pgvector query fails, the collection's most recent 5000 chunks are read and compared in the app, as before. Every chunk keeps its plain array for that.
• Existing stores keep working unchanged. Chunks saved before the upgrade get their pgvector value the first time their collection is searched or inserted into.
• If the extension cannot be set up, the migration still succeeds and writes a warning. The drift check then shows the embeddingVector column as missing.

Document Loader

• Google Drive Folder: every Google Doc (exported as Markdown), Sheet (first sheet, as CSV) and Slides file, PDF with a text layer, Word .docx and text file directly in the folder. Sub-folders are not opened; pictures, scanned PDFs and old Office formats are skipped with the reason.
• Notion Database: every row is one document made of its title, its properties as Name: value lines, and the page's blocks as Markdown. Share the database with your Notion integration first.
• Unchanged documents are skipped. Every chunk stores a hash of its document (text, embedding model, split settings and metadata) and the source's own version of it (Drive's modified time and checksum, Notion's last edited time). A document whose version is the same is not even downloaded; one whose text turns out to be the same is not embedded again; a changed one replaces its old chunks in one transaction.
• It needs two credentials: the Source Credential (a Google account, or a Notion integration) and the Embeddings Credential.
• Max Documents (default 25, up to 100) are read per run, most recently changed first. Each document is its own step, and one that fails is reported in documents without stopping the others.
• Remove Deleted Documents (off by default) also removes the chunks of documents that are no longer in the folder or database. It only acts when the run saw the whole source.
• Chunks get source, title, url and documentId metadata, plus your own, so a search can filter on them.
• Put it after a Schedule Trigger to keep a collection up to date.

Analyze Image / Document

OCR and vision for a file a workflow has: a Form Trigger upload, an HTTP Request download, a Google Drive or Gmail file.

• Input: a file variable (form.invoice, download.file) that holds an image (JPEG, PNG, WebP, GIF, TIFF) or a PDF.

• Modes:

  Mode	Result
  Extract All Text	{{analysis.text}}: the document's text in reading order, tables as rows
  Extract Fields	{{analysis.output.<field>}}, from lines of name (type): description, the same format and types as the Information Extractor. A field the document does not have is null
  Describe	{{analysis.description}}; "What To Describe" can ask something specific

• Model: connect a model that can read images to the node's Model port: OpenAI, Gemini or Anthropic, or a Chat Model node with a vision model of its provider (for example GLM-4.6V on Zhipu, or a Qwen-VL model). A model that cannot read images fails with the provider's error and a hint to use a vision model. A Chat Model's fallback models are used as usual, and the call is counted in AI usage and cost.

• PDFs: each page that has text is given to the model as that text. A page without text is a scan: the picture on it is taken out of the PDF and given to the model as an image. So a typed PDF costs text tokens, a scanned one image tokens, and a mixed one each page as it is.

• Max Pages (PDF): how many pages are read, from the first; default 5. The server's limit is 20 (VISION_MAX_PDF_PAGES). The result says how much was read: pages, pagesRead, truncated and scannedPages.

• Images are turned upright and scaled down to 1600 pixels on their longest side before they are sent.

• Text inside the document is treated as content, never as instructions to the model. As an AI Agent tool the node counts as Read.

• Limits: scanned pages are not redrawn, the scanner's picture is used as it is. A page that is only vector drawings without text gives nothing; a scan stored as many small strips is read from its first four pieces. Reading a PDF has the same time limit as Extract from File. HEIC photos are not supported: convert them to JPEG first.

• Templates: two templates in the gallery use it: Invoice to Google Sheets (upload form, extract fields, append a row) and (upload form, extract text, score against your job description, email the result).

---

🔔 Trigger Nodes

Trigger	Description
Manual Trigger	Manual execution on user demand
Schedule Trigger	Time-based automatic triggers evaluated each minute using custom Cron intervals (e.g., */5 * * * *)
Webhook Trigger	Runs on any HTTP request to /api/webhooks/trigger/<workflowId>, protected by a per-node secret. Respond immediately, when the last node finishes, or with a Respond to Webhook node
Chat Trigger	Runs when a message is sent from the editor's chat panel, or (with "Make chat public") from the hosted chat page or the website widget; provides chatInput and sessionId
Telegram Trigger	Runs when your bot receives a message. The bot's webhook is registered when the workflow is activated. A voice message is given as a file at {{telegram.voice}}
WhatsApp Trigger	Runs when your WhatsApp Business number receives a message (verify token + signature check). With a WhatsApp credential selected, a voice message is given as a file at {{whatsapp.voice}}
Gmail Trigger	Runs when a new email arrives; polls every 1, 5, 15 or 60 minutes with an optional Gmail search filter. One poll starts at most 10 runs, oldest email first; when more arrived, the rest follow at 10 a minute until none are waiting (a burst of up to 500 emails is kept)
Messenger Trigger	Runs when someone messages your Facebook Page (verify token + signature check; see "Messenger and Instagram")
Instagram Trigger	Runs when your Instagram professional account receives a direct message (verify token + signature check)
Typeform Trigger	Runs when a typeform is submitted; answers are available by question title
Shopify Trigger	Runs when an order is created, paid, fulfilled or cancelled, a product is created or updated, a customer is created or a checkout changes (HMAC signature check; see "Shopify and WooCommerce")
WooCommerce Trigger	Runs when an order is created, updated or paid, or a product or customer changes (signature check; optional order status filter)
Form Trigger	Runs when someone submits the workflow's own hosted form at /forms/<id> (see "Forms")
MCP Server Trigger	Makes the workflow a tool of an MCP server at /api/mcp/<workflow id>, protected by a bearer token (see "MCP: client and server")

Telegram, WhatsApp, Messenger, Instagram, Typeform, Shopify, WooCommerce and Stripe need NEXT_PUBLIC_APP_URL to be a public https address. Every webhook route is rate limited per workflow.

Duplicate deliveries and retry

Providers re-send an event when they are unsure it arrived. Each trigger remembers the events it accepted for 7 days and ignores a repeat:

Trigger	Recognised by
Stripe	The event id
WhatsApp	The message id
Messenger, Instagram	The message id (mid)
Telegram	The update id
Typeform	The submission's event id
Shopify	The event id Shopify sends with every attempt (X-Shopify-Event-Id), per event type
WooCommerce	The delivery id; for "Order paid" and the order status filter, the order itself, so an order starts one run however often it is updated
Google Form	The response id
Gmail, RSS Feed	The message or item id
Webhook	An optional Idempotency-Key (or X-Idempotency-Key) header sent by the caller; a repeat answers { "duplicate": true }

Every execution also keeps the trigger and the data it started with, so it can be run again: Retry on a failed execution's page (or Run again on a successful one), or POST /api/v1/executions/:id/retry. A retry uses the workflow as it is now, which is how a failed webhook delivery is replayed after the workflow has been fixed.

---

⚙️ Action Nodes

Core and flow

Node	Description
AI Agent	n8n-style Tools Agent with Chat Model, Parser, Memory and Tools sub-nodes
HTTP Request	Call any API: headers, query parameters, Basic / Bearer / Header / Query auth from credentials (Query Auth adds an API key to the URL when the request is sent, for APIs such as ZeroBounce that only take it there; the key is not kept in the node), JSON / form / raw bodies, timeout, Never Error. Response Format "File" stores a download. Private and local addresses are blocked
RSS Read	Read the items of an RSS or Atom feed; the following nodes run once per item
Web Search	Search the web with Tavily, Brave Search or your own SearXNG server; titles, links and snippets. Also an AI Agent tool. See "Web Search and Read Web Page"
Read Web Page	Fetch a page and return its main content as clean Markdown or text, cut to a length you set. Also an AI Agent tool. Private and local addresses are blocked
Transcribe Audio	Turn a voice message or audio file into text with OpenAI Whisper, Groq Whisper or any OpenAI-compatible server. See "Audio"
Text to Speech	Turn text into spoken audio with OpenAI TTS or an OpenAI-compatible server; the result is a file
Respond to Webhook	Answer the HTTP request that started the workflow (JSON, text, redirect, status code, headers)
Webhook Callback	POST the workflow's data to another URL
Execute Workflow	Run another workflow and use its result; also works as an AI Agent tool
SSH	Run a command on your own server and get its output and exit code. Pro plan only
JavaScript Code	Execute custom JavaScript in an isolated QuickJS (WebAssembly) sandbox
Set Variable	Store reusable variables
Filter	Stop the current branch unless a condition is true
IF	Route to a True or False output based on one or more conditions
Switch	Route to one of several outputs based on ordered rules, with a fallback
Merge	Join branches back into one path; optionally append or join two lists
Loop	Run the connected nodes once for every item in a list
Stop and Error	Fail the workflow with your own message

Data transformation

Node	Description
Edit Fields	Set, keep, remove and rename fields (name (type) = value per line). After a list node it reshapes every item, like a map
Split Out	Turn a list inside your data into separate items
Aggregate	Combine a field from many items into one list; ends a per-item section
Sort	Order the items of a list by a field
Limit	Keep only the first or last items
Remove Duplicates	Remove items that repeat an earlier item
Summarize	Count, sum, average, min, max per group, like a pivot table

Files

Files do not travel inside the workflow data. A node that makes or fetches a file stores it and puts a reference in its result: { id, fileName, mimeType, size, url }. To use the file in another node, type its variable into that node's File field, for example pdf.file or myApiCall.httpResponse.file. The url is a download link for the signed-in owner.

Node	Description
PDF Generator	Make a PDF from text with headings (#), bullets (-) and rules (---). Supports Latin, Cyrillic, Greek, Arabic, Urdu and Persian text, including right-to-left layout and mixed lines
Convert to File	Turn a list into an Excel (XLSX) or CSV spreadsheet, any value into JSON, or text into a text file
Extract from File	Read a file back into workflow data: the rows of an Excel or CSV sheet (which continue as items), the text of a PDF or Word (DOCX) file, JSON, or plain text

Files come from PDF Generator, Convert to File, Google Drive (Download) and HTTP Request (Response Format: File). They can be:

• attached to an email with Gmail, Email (SMTP), Resend or SendGrid (the Attachments field takes several, comma-separated)
• sent as a document with Telegram (Attach File) or WhatsApp (Send File; pictures, video and audio show inline)
• uploaded to Google Drive
• read with Extract from File

The PDF Generator uses the fonts built into PDF readers for plain Latin text and switches to the bundled Noto fonts in assets/fonts for other scripts. Text in Arabic script looks right on the page, but copying or searching it inside the PDF is unreliable.

Limits: 10 MB per file (MAX_FILE_SIZE_MB), 200 MB stored per user (MAX_USER_STORAGE_MB), and files are deleted after 7 days (FILE_RETENTION_DAYS).

Download links. The url of a file reference is a signed link, /api/files/<id>?expires=...&signature=.... It works for 15 minutes for anyone who has it, without signing in, so a workflow can hand a file to another service. After that it answers 403; the signed-in owner can still open it, and every node that loads the file gets a fresh link. Files are always sent as downloads (Content-Disposition: attachment), with their stored type and X-Content-Type-Options: nosniff, so a file a workflow made is never shown as a page of the app.

Limits when reading files (Extract from File). A file over a limit fails the node with a message that says which one:

File	Limit	Setting
Excel (XLSX), Word (DOCX)	Unpacks to at most 50 MB, and has at most 2,000 parts. Checked by unpacking with a cap before the file is opened, so a "zip bomb" is refused	MAX_UNCOMPRESSED_FILE_MB, MAX_ZIP_ENTRIES
PDF	The first 200 pages are read (<name>.truncated is true when there were more; <name>.pages is the real count), within 20 seconds	PDF_MAX_PAGES, PDF_EXTRACT_TIMEOUT_SECONDS
CSV	At most 10,000 rows; the node's Max Rows field can lower it. <name>.truncated is true when the file had more	CSV_MAX_ROWS
Excel (XLSX)	The first 5,000 rows of the sheet

Audio

Two nodes that speak the OpenAI audio API, and voice messages on the two chat triggers.

• Providers (each node's Operation): OpenAI, Groq, or OpenAI-compatible (custom base URL) for any service or self-hosted server that offers the same endpoints. OpenAI uses an OpenAI credential; Groq and custom servers use a "Chat Model API Key" credential. A custom base URL goes through the SSRF guard: a server on a private network has to be on PRIVATE_NETWORK_ALLOWLIST.

Transcribe Audio (/audio/transcriptions)

• File: a file variable holding audio: telegram.voice, whatsapp.voice, a Form Trigger upload, an HTTP Request download. MP3, M4A, WAV, OGG, WebM, FLAC or MP4, up to the workflow file size limit.
• Model: whisper-1 on OpenAI and whisper-large-v3-turbo on Groq when left empty; required for a custom server.
• Language (optional, a code such as en, ur, ar) makes the result more accurate; Hint (optional) helps with names and unusual words.
• Result: {{transcript.text}}, and language and duration when the server reports them.

Text to Speech (/audio/speech)

• Text up to 4096 characters, a Model (tts-1 on OpenAI when left empty; required for Groq and custom servers), a Voice (alloy when left empty) and a Format: MP3, Opus (an Ogg file, the format of voice messages) or WAV.
• Result: a file reference at {{speech.file}}, stored like every other workflow file (same size limit and storage quota, removed after the retention period). Use speech.file in a Telegram or WhatsApp node's File field or in an email's Attachments.

Voice messages on the Telegram and WhatsApp triggers

• Telegram Trigger: a voice message (or audio file) is downloaded with the trigger's bot credential and added to the data as a file: {{telegram.voice}}, with its duration.
• WhatsApp Trigger: has a new, optional WhatsApp Credential. With it selected, a voice message is downloaded and added as {{whatsapp.voice}}. Without it everything works as before and text messages need nothing.
• A voice message that cannot be fetched (no credential, larger than the file size limit, a download error) does not fail the run: the message still arrived, and {{telegram.voiceError}} / {{whatsapp.voiceError}} says why there is no file.
• A voice bot: Telegram Trigger → Transcribe Audio (File telegram.voice) → AI Agent (Source for Prompt "Define below", Prompt {{transcript.text}}) → Text to Speech (Text {{aiAgentOutput.output}}, Format Opus) → Telegram (File speech.file). The Telegram node sends the audio as a file, not as a voice note. A voice message has no text, so {{chatInput}} is empty for it: the agent's prompt has to come from the transcript. For a bot that takes both, put an IF on {{telegram.voice.id}} first.
• Transcription and speech are billed by the provider per minute or per character, not per token, so they are not in the AI usage and cost figures. As AI Agent tools both nodes count as Read.

Web Search and Read Web Page

Two nodes that bring the web into a workflow. Both work as ordinary steps and as AI Agent tools: connect them to an agent's Tools port and let the agent fill in the query or the address with {{$fromAI "query"}} / {{$fromAI "url"}}. They count as Read tools, so they need neither "Allow dangerous tools" nor approval.

Web Search

• Providers (the node's Operation): Tavily and Brave Search, each with an API key credential of its own, and SearXNG, your own server, with its address typed into the node and no credential. SearXNG needs its JSON output switched on (json under search.formats in its settings.yml); a server on a private network also has to be on PRIVATE_NETWORK_ALLOWLIST.
• Result: {{search.results}}, a list of { title, url, snippet }, plus {{search.count}}. The three providers come back in the same shape. Connect a Split Out node to handle the results one by one.
• Max Results (default 5, up to 20) and Max Characters Per Result (default 500): each snippet is cut to that length.

Read Web Page

• Built-in reader (default, no account): downloads the page and keeps its main content: the <article> or <main> if there is one, otherwise the block with the most real text. Menus, headers and footers, sidebars, cookie banners, share buttons, comments, scripts and hidden elements are left out. Output is Markdown (headings, lists, links with full addresses, bold, code, quotes, tables as rows) or plain text.
• Jina Reader and Firecrawl (optional, each with its own credential): for pages that build their content with JavaScript, which the built-in reader sees as empty. The built-in reader says so when it finds no text.
• Result: {{page.content}}, {{page.title}}, {{page.description}}, {{page.url}} (after redirects), {{page.truncated}} and {{page.length}} (the length of the whole page).
• Max Characters (default 8000, up to 100000): the text is cut to that length, at the end of a word, and ends with a note that it was cut, so a model reading it knows there was more. Web pages can be very long, and every character is paid for again as model input; this is the setting that controls that cost.
• SSRF guard: the page, and every redirect on the way, goes through the same guard as the HTTP Request node, so private, local and cloud-metadata addresses are refused. The address is also checked before it is handed to Jina Reader or Firecrawl. A download stops at 3 MB and after 20 seconds, and only web pages and text are read (a PDF or image address is refused with a pointer to the HTTP Request node).
• The built-in reader is deliberately small: no JavaScript, no login, no paywalls, and it reads a page as the server sent it. It announces itself as RXJ-PageReader; some sites refuse automated readers.
• What a page says is data. As an agent tool the text is handed to the model inside the same <tool_result> block as every other tool result, marked as untrusted.

Apps and databases

Node	Description
Google Sheets	Append rows (Google account or service account)
Google Calendar	Create, update and delete events (Google account or service account)
Google Drive	Search, upload, download, create folder, delete. Google Docs and Slides download as PDF, Sheets as CSV
Gmail	Send (with file attachments), reply, search, get and mark messages as read. A reply stays in the thread: to a message you received it goes to its sender, to a message you sent yourself (a follow-up) it goes to the people that message was sent to, with its CC only when CC of a Message You Sent is set to Keep
Notion	Create pages, query databases
GitHub	Create issues, comment on issues, list issues, read a repository
Airtable	List, create, update and delete records. List Records returns one page (50 by default, 100 at most); with Return All it follows Airtable's pages up to Max Records (1000 by default, 10,000 at most, and 3 MB). Its output then has truncated (true when the table had more) and a warning text when the list was cut or is longer than MAX_ITEMS_PER_NODE, the most items a node after Split Out handles
Jira	Create issue, get issue, search with JQL, add comment (Jira Cloud)
HubSpot	Create, get, update and search contacts; create deals
Salesforce	Query with SOQL, and create, get, update and delete records of any object
Shopify	Orders, products, customers, inventory levels and abandoned checkouts (see "Shopify and WooCommerce")
WooCommerce	Orders, order notes, products and customers through the REST API
Postgres	Run parameterised SQL, select rows, insert rows. Expressions go in Query Parameters, not in the query text
MySQL	Run parameterised SQL, select rows, insert rows (MySQL and MariaDB). Same rule for expressions

---

Shopify and WooCommerce

Two store nodes and two triggers. The nodes can also be AI Agent tools: reading is "read", creating and updating is "write" (so it asks for approval by default).

Node	Operations
Shopify	Get, list and update orders; get, list, create and update products; get, search, create and update customers; get, set and adjust an inventory level; list locations; list abandoned checkouts
WooCommerce	Get, list and update orders; add an order note; get, list, create and update products (with stock quantity); get, list, create and update customers

• Shopify uses the Admin REST API with a custom app's access token. The node's Shop Domain must be the store's myshopify.com address: the token is sent nowhere else. Shopify calls the REST API "legacy" and is moving to GraphQL, but still serves it; the node asks for version 2025-01, Shopify answers a retired version with its oldest supported one, and API Version can be set on the node.
• WooCommerce uses REST API v3 with a consumer key and secret, sent as HTTP Basic authentication. Store URL must be https. The key is never put in the address. Some hosts remove the Authorization header before WordPress sees it, and the store then answers 401 "cannot list resources" with a correct key; that has to be fixed on the host.
• Lists come back as {{json <name>.items}} and {{<name>.count}}, at most 100 (default 20). Put a Split Out node with Input List <name> after one to run the next nodes once per item. Fields limits what each item contains; an answer over 3 MB is refused with that advice.
• Additional Fields takes a JSON object in the store's own field names, merged into what is sent, for anything the node has no field for.
• A redirect from the store is not followed, because the request carries the key. The error names where the store pointed, so the address can be corrected.
• Inventory in Shopify belongs to an inventory item at a location: take variants.0.inventory_item_id from Get Product and a location from List Locations.
• List Abandoned Checkouts returns checkouts that were started, not completed, and last touched between "at least" and "at most" minutes ago. By default those without an email address and phone number are left out.

Store triggers

Trigger	Set up in the store	Signature
Shopify Trigger	Settings > Notifications > Webhooks: one webhook per event, format JSON, the node's Webhook URL	X-Shopify-Hmac-Sha256, checked with the signing secret shown on that page (or the app's API secret key for a webhook an app created)
WooCommerce Trigger	WooCommerce > Settings > Advanced > Webhooks: status Active, a topic, the node's Webhook URL as Delivery URL, and a Secret	X-WC-Webhook-Signature, checked with the same Secret typed into the node

• Each trigger node listens for one Event (or any). A correctly signed delivery of another event is answered 200 and starts nothing, because both stores switch a webhook off when it keeps failing.
• Shopify events: order created, paid, updated, fulfilled, cancelled; product created, updated; customer created; checkout created, updated.
• WooCommerce events: order created, updated; product created, updated; customer created; and Order paid, which WooCommerce has no topic for. Give the WooCommerce webhook the topic Order updated: the run starts once per order, the first time the order has a payment date.
• Only When The Order Status Is (WooCommerce) starts a run only for orders in that status, once per order and status. WooCommerce often sends "Order updated" several times for one change.
• Activate the workflow before saving the webhook in WooCommerce. WooCommerce checks the address when the webhook is saved and reports an error for a workflow that is not active.
• The run starts with {{shopify.event}}, {{shopify.id}}, {{shopify.email}}, {{shopify.phone}}, {{shopify.customerName}} and the store's whole payload at {{shopify.order}} (or .product, .customer, .checkout); the same names under {{woocommerce...}}. phone and email are taken from wherever the payload has them (an order has a phone number in up to five places).
• Signed events are not refused for being old, unlike Stripe and Typeform: Shopify retries a failed delivery for hours, so an age limit would drop real orders after an outage. A repeat is stopped by the duplicate check for 7 days; a signed request that someone captured could start a run again after that.

---

💬 Messaging Integrations

Integration	Description
Discord	Discord automation
Slack	Slack notifications
Telegram	Bot messaging: text, or a file with a caption, and the Telegram Trigger for incoming messages
WhatsApp	Text, template and file messages via the WhatsApp Business Cloud API, and the WhatsApp Trigger
Messenger	Text and picture replies to people who wrote to your Facebook Page, and the Messenger Trigger
Instagram	Text and picture direct messages, the Instagram Trigger, and photo posts (with the Instagram / Facebook Post node)
Twilio	SMS and WhatsApp messages
Email	SMTP email, with file attachments
Gmail	Email through a connected Google account, with file attachments
Resend	Email through the Resend API, with file attachments
SendGrid	Email through the SendGrid API, with file attachments

Messenger and Instagram

Three nodes and two triggers on Meta's Graph API. As AI Agent tools all three nodes are "write", so they ask for approval by default.

Node	What it does
Messenger	Sends a text or a picture to someone who wrote to your Facebook Page
Instagram	Sends a text or a picture as a direct message from your Instagram professional account
Instagram / Facebook Post	Publishes a photo with a caption on the Instagram account or on the Facebook Page
Messenger Trigger, Instagram Trigger	Start a run for each incoming message, with chatInput and sessionId for an AI Agent

• Who can be written to. A Page or an Instagram account can only message people who wrote to it first, and by their id from the trigger ({{messenger.from}}, {{instagram.from}}), not by name or phone number. A plain reply arrives within 24 hours of the person's last message. Message Type offers Meta's tags for later messages (human agent, post-purchase update and so on); they are not for promotion.
• Two ways an Instagram account is connected, chosen on the node as Account Connected: through a Facebook Page (a Facebook Page credential, calls go to graph.facebook.com) or with Instagram Login (an Instagram credential, calls go to graph.instagram.com). Messenger and Facebook Page posts always use the Facebook Page credential.
• The token is sent in an Authorization header to those two hosts only, never in an address.
• Pictures. Meta does not take an upload for these calls: it downloads the picture from a web address. The Image field takes a public https address, or a file variable. A file is handed over as its signed download link (valid 15 minutes), so the app has to run on a public https address for that. An address on a private network is refused.
• Instagram posts take JPEG only, between 4:5 and 1.91:1 in shape, with a caption of up to 2200 characters. The node makes a container, waits until Instagram has prepared it (up to 20 seconds) and publishes it. With a Facebook Page credential and no Instagram Account ID, the Instagram account connected to the Page is looked up.
• A post is public as soon as the node has run and is not taken back when a later node fails.
• Triggers use the same two checks as the WhatsApp Trigger: Meta's verify token when the webhook is saved, and the X-Hub-Signature-256 signature (made with the app secret) on every event. Echoes of the account's own messages, deleted messages, read and delivery receipts and reactions start nothing. Button taps and quick replies do, with their payload at {{messenger.payload}}. Attachments are given as a list of { type, url }; they are not downloaded.
• One address per Meta app. Meta sends all of an app's Page (or Instagram) events to one Callback URL, so one app feeds one workflow per channel.
• Receiving messages from people who are not testers of the app needs Meta's app review (pages_messaging, instagram_manage_messages or instagram_business_manage_messages); posting needs or / .

---

🔐 Credentials & Security

All credentials are encrypted before database storage using AES encryption.

Supported credential types:

Type	Used By
OPENAI	OpenAI nodes, Vector Store embeddings
ANTHROPIC	Claude nodes
GEMINI	Gemini nodes, Vector Store embeddings
DEEPSEEK	DeepSeek node
KIMI	Kimi node
QWEN	Qwen node
OPENAI_COMPATIBLE	Chat Model node (the API key of whichever provider preset is picked: OpenRouter, Groq, Zhipu, MiniMax, Ollama...)
SMTP	Email node
GOOGLE_OAUTH2	Gmail, Gmail Trigger, Google Drive, Google Sheets, Google Calendar ("Sign in with Google")
GOOGLE_SHEETS	Google Sheets (service account)
GOOGLE_CALENDAR	Google Calendar (service account)
NOTION	Notion nodes
TELEGRAM	Telegram node and Telegram Trigger
WHATSAPP	WhatsApp node (Cloud API access token)
FACEBOOK_PAGE	Messenger node, Facebook Page posts, and Instagram through a Page (Page access token)
INSTAGRAM	Instagram node and posts for an account that uses Instagram Login (Instagram access token)
TWILIO	Twilio node (AccountSID:AuthToken)
RESEND	Resend node (API key)
SENDGRID	SendGrid node (API key)
TAVILY	Web Search node with Tavily (API key)
BRAVE_SEARCH	Web Search node with Brave Search (subscription token)
JINA_READER	Read Web Page node with Jina Reader, and the Vector Store's Jina reranker (API key)
COHERE	The Vector Store's Cohere reranker (API key)
FIRECRAWL	Read Web Page node with Firecrawl (API key)
GITHUB	GitHub node (personal access token)
AIRTABLE	Airtable node (personal access token)
JIRA	Jira node (email:api-token)
HUBSPOT	HubSpot node (private app access token)

Security

• Outbound requests: URLs, database hosts and SSH hosts typed in by users cannot point at private or local addresses (SSRF guard, including redirects and DNS tricks). A self-hosted server that needs to reach something on its own network, for example Ollama, lists exactly that in PRIVATE_NETWORK_ALLOWLIST:

  PRIVATE_NETWORK_ALLOWLIST=127.0.0.1:11434,10.0.0.0/24,db.internal:5432
  

  Entry	Allows
  127.0.0.1:11434	that address on that port only
  10.0.0.5	that address on any port
  10.0.0.0/24	every address of the range, on any port
  ollama.lan:11434, db.internal	that host name (with or without a port), whatever private address it resolves to
  [::1]:11434, fd00:1234::/64	the same for IPv6; an address with a port goes in brackets

  • Everything private that is not listed stays refused, cloud metadata (169.254.169.254) included.
  • A request has to match by what it uses: http://localhost:11434 is allowed by localhost:11434, not by 127.0.0.1:11434, because localhost can also resolve to ::1 and every address of a name has to be allowed. Use the same form in the node as in the list. The Chat Model node's default Ollama address is http://localhost:11434/v1, so for that the entry is localhost:11434.
  • A range with a port (10.0.0.0/24:5432) is not supported. Entries that cannot be read are ignored and named in a warning at startup.
  • ALLOW_PRIVATE_NETWORK_REQUESTS=true still works and opens every private address; the allowlist then has no effect. It logs a warning at startup recommending the allowlist, which is the safer choice.

• Webhooks: per-node secrets or provider signatures (Stripe, WhatsApp, Messenger, Instagram, Typeform, Telegram, Shopify, WooCommerce), a bearer token for the MCP Server Trigger, and a per-workflow rate limit.

  • Every secret, token and signature is compared in constant time (secretsMatch in src/lib/webhook-security.ts, built on crypto.timingSafeEqual).
  • Stripe and Typeform events older than 5 minutes are refused, so a captured request cannot be sent again later. Stripe signs its own timestamp. Typeform's signature has none, so the submission's (which is inside the signed body) is used. A Typeform delivery that is retried more than 5 minutes after the form was submitted, for example after the app was down, is therefore refused and shows as failed in Typeform.

---

Execution logs: redaction and retention

Redaction. A run always works with the real data. What is stored about it is redacted first, with [REDACTED] in place of each secret:

Stored	What is redacted
Each node's input, output, error and stack trace; the execution's error	The values of all your credentials (also inside a longer text, such as a URL or an error message), and the well-known shapes below
The execution's final output	Credential values only. This is also what a webhook that answers "when the last node finishes", the chat panel and GET /api/v1/executions/:id return, so a token a workflow made on purpose is not changed
The data the run started with (kept for Retry)	Nothing: a retry has to start from the same data

The well-known shapes: sk-... keys, AKIA... AWS key ids, Slack xoxb-/xoxp-/xoxa- tokens, GitHub ghp_... tokens, JSON Web Tokens, Bearer ... tokens, the values of Authorization, Proxy-Authorization, Cookie, Set-Cookie and X-API-Key headers, and the password in connection strings like postgresql://user:password@host. Credential values shorter than 6 characters are not matched, and for credentials with several fields (SMTP, SSH, Google, Salesforce) the host, username and similar fields are left readable.

The same redaction of well-known shapes runs on everything sent to Sentry (errors, traces and logs).

Retention. On the Executions page, Execution data retention sets how long your execution data is kept: 7, 30 (default) or 90 days. A nightly job deletes older executions with their node data. An execution from the current month keeps its row (status, times and error message) until the month ends, because the monthly execution limit counts it; everything else about it is deleted. Running executions are not touched.

Don't save node input/output. In the editor, the gear button next to the Active switch has this workflow setting (off by default). When it is on, runs of that workflow store only their status, times and errors (redacted as above). Such runs cannot be retried, the execution page shows no data for them, and a webhook that answers "when the last node finishes" returns an empty object; use a Respond to Webhook node instead.

Credential encryption and key rotation

Everything a credential holds (an API key, a login, or the OAuth tokens of a connected Google or Salesforce account) is stored encrypted in Credential.value. It is decrypted only on the server, at the moment a node needs it. The browser never receives it, encrypted or not: the Credentials pages get the name, type and dates, and the edit form only says that a secret is saved. Leaving the secret empty when editing keeps the saved one.

Format

v1:<base64 of  IV (12 bytes) | auth tag (16 bytes) | ciphertext>

• Cipher: AES-256-GCM. The IV is random for every value, and the auth tag makes a changed or damaged value fail to decrypt instead of giving a wrong secret.
• Key: 256 bits, derived from ENCRYPTION_KEY with scrypt. Use a long random value, for example openssl rand -base64 32.
• v1: is the format version, so the format can change later without guessing.
• Values saved before this format (written by the cryptr package: hex text, no prefix, AES-256-GCM with a 16-byte IV) are still read. The rotation script rewrites them as v1:; run it once after upgrading, without changing any key, to convert them.

Changing the key

1. Back up the database.
2. Set ENCRYPTION_KEY_PREVIOUS to the current key and ENCRYPTION_KEY to the new one, and deploy or restart. From now on new values are written with the new key, and old values are still read with the previous one, so nothing stops working.
3. See what the script would do: npx tsx scripts/rotate-encryption-key.ts --dry-run
4. Run it: npx tsx scripts/rotate-encryption-key.ts (or npm run rotate-encryption-key). It goes through the credentials 100 at a time and re-encrypts each with the new key. Values that are already current are skipped, so it can be stopped and run again. A credential a user saves while it runs is not overwritten.
5. When it ends with "Every credential is encrypted with the current key", activate every workflow that has a Telegram Trigger once more (switch it off and on). Telegram's webhook secret is derived from the key; the old one is only accepted while ENCRYPTION_KEY_PREVIOUS is set.
6. Remove ENCRYPTION_KEY_PREVIOUS and deploy or restart.

If the script lists credentials that "could not be read", they were written with a key that is neither of the two: check ENCRYPTION_KEY_PREVIOUS, and keep it set until the list is empty. The script prints credential ids only, never values, and exits with code 1 in that case.

The script must run with the same ENCRYPTION_KEY, ENCRYPTION_KEY_PREVIOUS and DATABASE_URL as the app. It reads .env when there is one.

---

🔌 Public API

Create a key under Settings → API Keys (account menu at the bottom of the sidebar; Pro plan or free trial) and send it as Authorization: Bearer <key> or X-API-Key: <key>.

Endpoint	Scope	Description
GET /api/v1/workflows	workflows:read	List your workflows
POST /api/v1/workflows/:id/execute	workflows:execute	Run a workflow from its manual trigger; the JSON body becomes the run's variables
GET /api/v1/executions/:id	executions:read	Status and, once finished, the output
GET /api/v1/executions?workflowId=...	executions:read	Recent executions
POST /api/v1/executions/:id/retry	executions:retry	Run an execution again with the same starting data

API keys

• The full key is shown once, when it is created. Only its SHA-256 hash and a short prefix (rxj_ab12cd…) are stored, so a key cannot be read back from the app or the database.
• Each key has scopes and an optional expiry date (the key works until the end of that day, UTC). A request to a route whose scope the key lacks gets 403 with the name of the missing scope; an expired, revoked or unknown key gets 401.
• Each key may make API_RATE_LIMIT_PER_MINUTE requests per minute (default 120); after that it gets 429 with a Retry-After header.
• The API Keys page lists every key with its prefix, scopes, created, last used and expiry, and a Revoke button that stops the key at once.
• Keys created before scopes existed keep every scope and have no expiry.

curl -X POST "$APP_URL/api/v1/workflows/<workflowId>/execute" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"customer":"Ali"}'

---

💳 SaaS Billing & Subscription System

RXJ includes a complete SaaS monetization architecture powered by Polar.

SaaS Features

• Automatic 7-day free trial user allocation upon signup
• Dynamic plan detection and runtime casting via Prisma Enums
• Usage-based monetization
• Workflow usage tracking
• Execution usage tracking
• Credential usage limits
• Plan-locked nodes (scheduling, Google Sheets, Gmail, AI Agent, WhatsApp, SSH) and API access. The free trial unlocks all of them except SSH
• Billing management page
• Polar customer portal integration
• Better Auth Polar webhook sub-plugin lifecycle syncing architecture
• Real-time dynamic tier upgrades and revoked downgrades matching checkout selections
• Dynamic sidebar plan UI with live checkout state cache invalidation

---

📊 Usage Tracking System

RXJ tracks:

• workflow usage
• monthly executions
• credential limits
• current subscription plan
• trial duration

Users can view:

• workflows used
• executions used
• current plan
• remaining trial days

How the numbers are counted (src/lib/subscription/usage-counts.ts). Usage belongs to the workspace, so it is the workspace owner's.

• Workflows are counted from the workflow rows: the same rows the Workflows list shows. Creating a workflow, using a template, Build with AI, creating a chatbot and a Git pull all check the plan's limit against that count, and the sidebar shows it. Nothing is stored, so a workflow deleted in the app or straight in the database is gone from the number at once.
• Executions this month (UTC) are counted by the engine, once per run, whatever started it: manual runs, webhooks and other triggers, schedules, the API, the chat widget, retries, evaluation rows and sub-workflows. The count is in the execution_usage table and only goes up: deleting executions or workflows does not give any back. A run that would go over the limit is refused and not counted. Before the first run of a month the month's existing executions are the count, so the switch to this counter gave none back.
• The old user.workflowCount and user.executionsUsed columns are no longer read or written. They are dropped in a later change.
• scripts/reconcile-usage.ts recomputes the numbers from the rows: npx tsx scripts/reconcile-usage.ts --dry-run prints what it would change, without the flag it changes it. It never lowers an execution count.

Deleting a workflow removes, besides the workflow (whose nodes, connections, executions, versions, pinned data and evaluation datasets go with it by ON DELETE CASCADE), its agent memory, and the webhook of an active Telegram Trigger. For workflows that were deleted straight in the database, scripts/cleanup-orphans.ts finds what was left behind (agent memory, chat widget messages, chatbot documents, duplicate-delivery keys) and Telegram bots whose webhook points at a workflow that no longer exists: npx tsx --conditions=react-server scripts/cleanup-orphans.ts --dry-run reports, without the flag it deletes and removes the webhooks. AI usage rows are kept on purpose: the month's AI spend stays complete.

Page speed. A request reads its session once (src/lib/request-session.ts, shared by the dashboard layout, the page and its tRPC prefetches), and a tRPC batch reads the session and looks up the workspace once for all its procedures. PERF_LOG=1 logs, with [perf] in front, how long each tRPC procedure, session read and database query takes; it is off unless set.

AI token usage and cost

Every call to a language or embedding model is written down with the tokens the provider reported: input, output and cached input. This covers the AI Agent, the model nodes (OpenAI, Anthropic, Gemini, Chat Model, DeepSeek, Kimi, Qwen), the Text Classifier, the Information Extractor, the Vector Store's embeddings and chat-model reranking, and the Document Loader's embeddings, also when one of them runs as an AI Agent tool. Only counts are stored, never prompts or answers, and they are kept after an execution's data is deleted so the month stays complete.

• Price table. An admin with two-factor on sets what each model costs under Settings → AI model prices: provider, model, and US dollars per million input, output and cached input tokens. Provider and model are matched exactly, ignoring case. The provider is openai, anthropic, gemini, the Chat Model preset (openrouter, deepseek, kimi...) or custom. The table starts empty; the card lists the models that ran without a price so they can be added with one click. Price changes are in the audit log.
• Cost is worked out when the call is made, from the price at that moment. Changing a price later does not change calls already recorded. A model without a price shows as "No price": it is not counted as free and not counted as money.
• Execution view. An execution's page has an AI usage table: one line per node and model with calls, tokens and cost, and the total of the run. An AI Agent's calls are one line per model that answered.
• Billing page. AI spend this month shows the total since the 1st (UTC), the tokens, and the spend per workflow.
• Budgets (optional). A monthly AI budget can be set for the account (Billing page) and for a workflow (editor → settings icon → Monthly AI budget). When the month's spend reaches a budget, the next node that calls a model stops the run with "Monthly AI budget reached..." until the budget is raised, removed, or the month ends. The check runs before each AI node, so the month can end slightly over the budget, by what the last node cost.

The amounts are estimates for keeping an eye on spend. You pay your providers directly and their invoice is what counts: tokens written to a provider's cache are priced as normal input, and a model without a price does not count towards a budget.

Built-in AI credits: RXJ AI (included)

A user can run cheap models without an API key of their own. The platform's provider keys do the calling and the user pays with AI credits.

• Credits. One credit is a tenth of a US cent of model cost: 1,000 credits are one dollar. A call's cost comes from the price table above ("AI token usage and cost"), at the price set when the call is made.

• Monthly credits per plan (calendar month, UTC; they do not carry over; a free trial does not change the number):

  Free	Beginner	Intermediate	Pro
  100	1,000	5,000	20,000

  The numbers are in one file, src/config/ai-credits.ts.

• Setting it up (admins). Under Settings → RXJ AI (included) an admin with two-factor on adds a provider (one of the Chat Model presets that has its own address, for example Zhipu GLM or DeepSeek), its API key and the model IDs users may pick. The key is stored encrypted, is never shown again, and is covered by the key rotation script. A provider can be switched off without removing it. Every included model needs a row in the price table: without one it cannot be used, because it would cost no credits; the card says which models are missing a price. Saving and removing a provider is in the audit log. Until a provider is added, users do not see any of this.

• Using it. On a Chat Model node the credential list has RXJ AI (included). With it, Provider and Model have to be one of the included ones (the dialog says which, and "Load models" lists them). It works wherever a Chat Model node works: as a step, as the model of an AI Agent, Text Classifier, Information Extractor, Analyze Image / Document or Guardrails, as a fallback model and behind a Model Router. Build with AI offers it in its credential list too. The platform's key is only ever sent to the provider's own address, never to a Base URL typed into the node.

• What is charged. Each included call is written down like any other (the execution's AI usage table, the Billing page) and its cost is taken from the month's plan credits first, then from bought credits.

• Hard stop. With no plan credits and no bought credits left, a node that uses RXJ AI (included) fails before it calls anything, with: "RXJ AI (included) credits are used up: the Free plan includes 100 credits a month and you have no bought credits left. Upgrade your plan or buy credits at <app>/billing, or pick your own API key credential on the node. The monthly credits start again on the 1st (UTC)." Build with AI shows the same message. The check is made before a node runs, not during it, so the last node (an agent with many steps, for example) can use more than was left; bought credits never go below zero.

---

🏠 Landing page and brand

The page at / is the public marketing page. It is built once and rebuilt at most every hour, and it does not load the workflow editor.

• Where it is. The route is src/app/page.tsx; the sections, the navbar and the hero's workflow canvas are in src/features/marketing/components/, and the words (features, use cases, security, FAQ) in src/features/marketing/lib/content.ts. A claim there is changed together with the feature it describes.
• What comes from the code, not from the page. The number of nodes is counted from the schema's NodeType. The plans and prices are src/config/pricing-plans.ts, which the Pricing page uses too. The limits and AI credits in the FAQ come from src/config/plans.ts and src/config/ai-credits.ts.
• Templates. Up to six published templates of the gallery, most used first, English ones before the others. Hidden templates are never read. A use case links to a template when a published English one matches its name. Without templates (or without a database at build time) the section shows a link to the gallery instead.
• Integrations strip. src/features/marketing/lib/integrations.ts, with glyphs from the simple-icons package. Add an integration only when its node exists.
• Colours and fonts. src/app/marketing.css: the colours are sampled from the logo (violet #9829FD, indigo #401EFB, blue #1568FD, sky #0099FE, ink #03031A), scoped to .mkt, and follow the system light/dark preference. The navbar, hero, security band, final call to action and footer are always dark, because the logo is drawn for a dark background. Headings are Bricolage Grotesque, body text Geist. The app itself keeps its own theme.
• Motion is CSS only (no animation library) and is switched off for prefers-reduced-motion; the hero canvas then shows the finished run.
• Logo. The source is public/logos/RXJ.png and is never edited. node scripts/generate-brand-assets.mjs makes the cropped wordmark (public/brand/rxj-wordmark.png), src/app/favicon.ico, src/app/icon.png and src/app/apple-icon.png from it; run it again when the logo changes. RxjLogo (src/features/marketing/components/rxj-logo.tsx) shows it: plain on a dark surface, with tile on a light one (the sign-in pages).
• Sharing image. src/app/opengraph-image.tsx draws the 1200 × 630 image with the logo and the headline; uses the same one. Their addresses and the canonical URL are built from .

---

🎯 Onboarding System

RXJ includes onboarding UX to improve activation and retention.

Current Features

• First-time onboarding page
• Create workflow CTA
• Workflow templates, with starter templates in English, Urdu and Arabic (see below)
• Build with AI: a workflow from a description (see below)
• One-click chatbot: documents or website pages in, a website widget, share link and WhatsApp out (see below)
• Guided product introduction
• Trial onboarding flow with proactive expiration countdowns

Workflow templates

The Templates page is a gallery of ready-made workflows. "Use template" copies one into the user's account as a new workflow, which opens with its nodes marked "Not Configured" wherever the user has to connect their own account.

• Built-in templates are added by database migrations and can be edited or hidden by an admin like any other: Invoice to Google Sheets, CV screening: score and email, Shopify order paid: WhatsApp confirmation and Shopify abandoned cart: email reminder. The WhatsApp one sends an approved message template, because WhatsApp does not let a business start a conversation with free text; its description says how to set that up and how to switch it to WooCommerce. The abandoned cart one runs every hour and emails the shoppers whose checkout was last touched one to two hours ago.

• Publishing: an admin builds a workflow, then picks it under New template and gives it a name, description, category and the plan it is available from. Editing a template can replace its content with the current version of a workflow; hidden templates are visible to admins only.

• Admins are accounts whose email is in the ADMIN_EMAILS environment variable and is verified. Only they can publish, edit and delete templates. A Google or GitHub sign-in counts as verified; a password account has to confirm its email first, which needs RESEND_API_KEY. Without that key the server logs a warning at startup, and a password account using an admin address stays an ordinary user.

• Admins need two-factor authentication. Publishing, editing and deleting templates is refused until the admin turns it on under Settings; until then the Templates page shows a note with a link there instead of the admin buttons.

• What a template never contains: stored credentials, webhook and signing secrets, WhatsApp verify tokens and app secrets, Slack and Discord webhook URLs, and the workflow an Execute Workflow node pointed at. Anything typed into ordinary fields (a key pasted into a header, a prompt) is copied as it is.

• Secret scan: before a template is published or updated, every field of every node is scanned for the secret shapes the log redaction knows (sk- keys, Bearer tokens, JWTs, AWS, Slack and GitHub tokens, passwords in URLs) and for hand-typed values in Authorization, Cookie and X-API-Key headers. Values made only of {{ }} expressions pass. If anything is found the template is not saved and the dialog lists the node and field (never the value). An admin can tick I checked this, publish anyway to save it regardless. Editing only a template's details scans its stored content again. The scan knows those shapes only, so a secret of another shape still has to be caught by reading the workflow.

Build with AI

Describe a workflow in words and get it on the canvas. The Build with AI button is on the Workflows page (makes a new workflow) and at the top right of the editor (builds on an empty canvas, or changes the workflow that is there).

• Whose model. It calls a chat model with one of the user's own stored credentials, picked in the dialog: OpenAI, Anthropic, Gemini, DeepSeek, Kimi, Qwen, or any provider of the Chat Model node (OpenAI-compatible, with its provider preset and base URL). The Model field is optional where the provider has a default. The choice is remembered in the browser. There is no platform key for it. Its calls are on the AI usage page as their own line, "Build with AI", they count towards the account's monthly AI spend, and a used-up account AI budget stops the builder too.
• The catalogue. The model gets a machine-readable list of every node type: type, description, fields (name, kind, options, required, default), input and output ports, the credential it needs and what its result looks like. The list is made in the browser from the node registry (src/config/node-components.ts), the node selector's descriptions and each node's settings, so a new node made with createIntegrationNode is in it without further work. Nodes with a hand-written dialog are described in src/features/ai-builder/lib/manual-specs.ts; a test fails when a registered node is described nowhere.
• The check. The model has to answer with JSON (name, summary, nodes, connections). The server checks it: known node types, the fields' kinds and options, required fields, that every connection uses ports the nodes really have (including Switch rules and Text Classifier categories), that a model, memory or parser node is on the port made for it, a trigger, one variable name per node, nothing unconnected, and no cycles. When something is wrong the answer goes back to the model once, with the list of problems; if the second answer fails too, the dialog shows the problems and nothing is changed.
• Loops. The engine only runs forward: a Loop node repeats what is on its "Each item" output by itself. A connection from the end of the loop back to the Loop node (how n8n draws it) is dropped; any other cycle is refused.
• Credentials are never filled in. Stored credentials, webhook secrets, Slack and Discord webhook URLs and the like are not sent to the model and cannot be set by it. New nodes open as Not Configured and the dialog lists what is still to set up. Which node types exist and which the user's plan includes is decided on the server; plan-locked nodes are left out of the catalogue.
• Never active. A workflow made from the Workflows page is saved inactive. In the editor nothing is saved at all: the result is put on the canvas, and the user reviews it and clicks Save. Activating is always the user's step.
• Follow-up edits. With nodes on the canvas the request is a change ("send it on WhatsApp instead"). The model gets the current workflow without credentials and secrets and answers with the whole workflow. Nodes it keeps stay the same nodes: same place, same credential, same secrets. A node replaced by one of another type is a new node without a credential. in the dialog puts the canvas back as it was before the last request.

One-click chatbot

Chatbots in the sidebar opens the Create a chatbot page: a chatbot that answers from your own documents, without building the workflow yourself.

• What you give it. A name; documents (PDF, Word .docx, .txt, .md, .csv, up to 3 MB each) and/or website addresses (one per line; each address is one page, links on it are not followed); the model that answers; and an OpenAI or Gemini credential for the embedding model that reads the documents. Optional: a welcome message, extra instructions, and WhatsApp.
• The model. Any of your model credentials (OpenAI, Anthropic, Gemini, DeepSeek, Kimi, Qwen, or an OpenAI-compatible provider), or RXJ AI (included) paid with AI credits. The embedding model is separate, because RXJ AI (included) and most chat providers have none: it needs an OpenAI or a Gemini credential. When the model's own credential is one of those, it is used for both.
• What you get. The chatbot's page, with the website widget snippet, the share link (the hosted chat page), a WhatsApp connection (Webhook URL and Verify Token for Meta, with the steps), an On/Off switch, and the list of what the bot knows, where documents and pages can be added and removed later. Adding a document or page that is already there replaces it; the same text again is not embedded twice.
• Behind the scenes it is a normal workflow you can open and change in the editor: Chat Trigger (with "Make chat public" on) into an AI Agent, with a model node on its Chat Model port, Memory (one history per visitor or WhatsApp number) and a Vector Store (Search Documents) on its Tools port. With WhatsApp there is also a WhatsApp Trigger into the same agent, and after the agent an IF (did the message come from WhatsApp?) and a WhatsApp node that sends the answer back from the number that received the message. The agent is told to answer only from the documents, to say so when it does not know, and never to follow instructions written in a document.
• It is switched on when it is created, unlike a workflow made by Build with AI: the widget and the link only work for an active workflow. Nobody can reach it until you share them. The page reads everything from the workflow's nodes, so a chatbot changed in the editor still works on its page (and any workflow with a Chat Trigger into an AI Agent can be opened as /chatbots/<workflow id>).
• Where the documents go. Into a Vector Store collection of its own (chatbot-...), cut into chunks (by heading for web pages and Markdown) and embedded with the Vector Store node's own settings and credential. The first 400,000 characters of a document are read; a chatbot can have 50 documents and pages. The embedding calls are written down on the Billing page under "Chatbot knowledge" and count towards the account's AI budget, which is checked first. Deleting the workflow does not delete the collection: remove the documents on the chatbot's page first, or use a Vector Store node with Delete Collection.

Account security

The Settings page (sidebar) holds two things.

• Two-factor authentication. Turning it on shows a QR code for an authenticator app (TOTP) and ten backup codes, and asks for a first code before it takes effect. From then on a password sign-in also asks for a code on /two-factor; a backup code works once in its place, and "Do not ask on this device for 30 days" skips the question on that browser. New backup codes can be made, and it can be turned off, after confirming the password. Accounts that only sign in with Google or GitHub have no password to confirm with and are not asked for a code at sign-in: for them the provider's own two-factor is what protects the sign-in.

• Active sessions. Every signed-in browser with its device, IP address and when it was last active, with Sign out for one and Sign out all other sessions. "Last active" is when Better Auth last refreshed the session, which it does about once a day, not the last click.

• Sign-in lockout. Ten wrong passwords for one account within 15 minutes lock password sign-in for that account for 15 minutes, whatever addresses the attempts came from. The answer is the same for addresses that have no account. The lock ends by itself after the 15 minutes, and a correct password then starts the count again; resetting the password does not lift it early. Google and GitHub sign-in are not affected. Anyone who knows an address can lock its password sign-in this way, which is the price of the rule.

• Sign-in rate limit. Password and two-factor code attempts are limited per IP address (SIGN_IN_RATE_LIMIT_PER_MINUTE, default 20). The address is read from the proxy headers Better Auth trusts (x-forwarded-for), so the app has to run behind a proxy that sets it, as it does on Vercel.

• Passkeys are not included: in the installed Better Auth (1.6) they are a separate package, @better-auth/passkey, which is not installed.

• Audit log. The Settings page lists what happened on the account, latest first, with the time and the IP address it came from:

  • credentials created, updated (saying whether the secret was replaced or only the name changed) and deleted, including Google and Salesforce accounts connected through their sign-in;
  • workflows activated, deactivated and deleted;
  • API keys created and revoked (by name and visible prefix);
  • templates published, updated and deleted, saying when one was saved despite the secret scan;
  • sign-ins, with how: password, password and two-factor code or backup code, Google, GitHub, or the email confirmation link. A password that still needs a two-factor code is not a sign-in until the code is accepted. Failed attempts are not listed;

Limits against abuse

A free trial unlocks the paid nodes, so these keep a trial or a cheap plan from being used to send in bulk or to sign up over and over.

• Daily message caps. Each user may send this many messages per day (the day is UTC) through the nodes that reach people outside the app. The numbers are in one file, src/config/message-caps.ts.

  Plan	Email (SMTP, Gmail, Resend, SendGrid)	WhatsApp	Twilio (SMS and WhatsApp)	Telegram
  Free (and the free trial)	20	20	10	50
  Beginner	100	50	25	200
  Intermediate	1,000	500	250	2,000
  Pro	10,000	5,000	2,500	20,000

  • For email every recipient counts (To, Cc and Bcc), so one email to 30 addresses is 30. The four email nodes share one count.
  • Reading mail with the Gmail node does not count; sending and replying do.
  • The cap is the plan's, trial or not, and it holds wherever the node runs: in a workflow, once per item of a list, and as an AI Agent tool.
  • When a send would go over, the node fails before anything is sent, with for example "Daily email limit reached: the Free plan allows 20 emails per day and 20 were sent today. The count starts again at 00:00 UTC. Upgrade your plan to send more."
  • A message is counted when the node is about to send it, so one the provider then refuses still counts.

• Disposable email addresses (mailinator, 10minutemail and the like, and their subdomains) cannot be used to sign up, with a password or through Google or GitHub. The list comes from the disposable-email-domains-js package; npm update disposable-email-domains-js brings in new domains. Accounts that already exist are not affected.

• Cloudflare Turnstile on the password sign-up form, when TURNSTILE_SITE_KEY and TURNSTILE_SECRET_KEY are both set. Without them (or with only one, which logs a warning at startup) sign-up works as before. Google and GitHub sign-ups are not asked: the provider has checked them.

Planned Improvements

• Interactive onboarding checklist
• Guided node setup
• AI workflow generation
• Template marketplace

---

🧰 Setup

npm install
npx prisma migrate deploy   # apply the database migrations
npm run dev:all             # Next.js + Inngest dev server + ngrok

A database set up before 10 October 2026. The 38 migrations that existed until then were replaced by one, 20261010000000_baseline, because the old history could not be replayed on an empty database. A new database needs nothing special: migrate deploy applies the baseline and everything after it. A database that already has the old history must be told once that the baseline is what it holds, or migrate deploy will try to create tables that exist:

1. Make sure it was fully migrated with the old history, up to 20261009150000_execution_retention_and_save_setting, and matches the schema of that time. If it stopped at an older migration, bring it up to date from a checkout made before the change first.

2. Clear Prisma's migration history. This empties Prisma's own bookkeeping table and touches no application table:

   echo 'DELETE FROM "_prisma_migrations";' | npx prisma db execute --stdin --schema prisma/schema.prisma
   

3. Mark the baseline as applied, then apply what came after it:

   npx prisma migrate resolve --applied 20261010000000_baseline
   npx prisma migrate deploy
   

npx prisma migrate status should then report "Database schema is up to date!".

Run the checks that need no database or external service:

npx tsx --conditions=react-server src/inngest/__test__/testCoreNodes.ts
NODE_OPTIONS=--max-old-space-size=8192 npx tsc --noEmit

Step-by-step workflows for testing every node by hand are in docs/TESTING.md.

Continuous integration

.github/workflows/ci.yml runs on every pull request and on every push to main. It has five jobs, each of which fails the run on its own:

Job	What it runs
Type check	npx tsc --noEmit (with the 8 GB heap the project needs)
Core node tests	npx tsx --conditions=react-server src/inngest/__test__/testCoreNodes.ts
Build	npx prisma generate then npx next build, with placeholder env values. Catches what tsc does not, such as a server package (sharp, fs) pulled into the browser bundle by a "use client" import. It runs next build directly, not npm run build, so scripts/migrate-on-deploy.mjs never runs
npm audit	npm audit --audit-level=high: fails on a known vulnerability of high or critical severity in any dependency
Secret scan	gitleaks over the commits of the push or pull request, with .gitleaks.toml

• The jobs only read the repository. None has the database address or any other secret of the app, and none migrates or deploys: DATABASE_URL in the workflow is a placeholder that prisma generate reads without connecting.
• .gitleaks.toml uses gitleaks' own rules and skips two places that hold made-up secrets on purpose: src/inngest/__test__/ and docs/TESTING.md. A real secret must never go into those.
• .github/dependabot.yml has Dependabot open pull requests once a week: one for all minor and patch updates of npm packages, separate ones for major updates, security updates and GitHub Actions. They run through the same CI and are merged by hand, because a merge to main deploys.

Deploying (Vercel)

The live app on Vercel and local development use the same database, so the schema only changes in one controlled way.

• The build command is npm run build: prisma generate, then node scripts/migrate-on-deploy.mjs, then next build.
• Production deploys migrate the database. When Vercel builds a production deployment (VERCEL_ENV=production, which is what a merge to main produces), the script runs prisma migrate deploy before the app is built. Pending migrations are applied; with none pending it changes nothing.
• Preview deployments and local builds never migrate. They use the same database, and a preview is built from a branch that has not been merged. The script prints that it left the database alone and the build goes on.
• A failed migration fails the build. Vercel then keeps serving the previous deployment, so new code is never live on a database it was not migrated for.
• Migrations reach production by merging to main, and no other way. A pull request that adds a folder under prisma/migrations changes the production database the moment it is merged, so read its SQL as part of the review.
• Migrations have to work with the code that is already live. The database is migrated a few minutes before the new code replaces the old, and if the build fails after the migration the old code stays. So migrations only add: new tables, and new columns that are nullable or have a default. Removing or renaming something is done in a later change, once no deployed code uses it.
• DATABASE_URL must be available to the build on Vercel (it already is for prisma generate), and should be a direct connection, not a pooled one: prisma migrate deploy takes a lock that connection poolers can break.
• DATABASE_POOLED_URL (optional) is what the app's own queries use when it is set: Neon's pooled address, the same as DATABASE_URL with -pooler after the endpoint id in the host, and &pgbouncer=true at the end. Serverless functions then share the pooler's connections instead of each opening its own. Migrations keep using DATABASE_URL.
• INNGEST_SIGNING_KEY has to be set in the production environment, or the server does not start (see "Security").

Environment variables

Variable	Purpose
DATABASE_URL	PostgreSQL connection string (direct; migrations use it)
DATABASE_POOLED_URL	Optional. The pooled connection string the app's queries use instead. See "Deploying (Vercel)"
PERF_LOG	Optional. 1 logs timings of tRPC procedures, session reads and database queries, each line starting with [perf]
ENCRYPTION_KEY	Encrypts stored credentials and OAuth tokens. A long random value
ENCRYPTION_KEY_PREVIOUS	Only while changing ENCRYPTION_KEY: the old key, so values written with it can still be read. See "Credential encryption and key rotation"
NEXT_PUBLIC_APP_URL	Public address of the app; used for webhook URLs, OAuth redirects and trusted origins
TRUSTED_ORIGINS	Extra origins allowed to sign in, comma-separated. Also where the address of every SSO identity provider has to be listed before it can be registered
EXTERNAL_SECRETS_CACHE_SECONDS	How long a secret read from Vault or AWS Secrets Manager is used before it is read again, default 300. 0: read every time
ADMIN_EMAILS	Who may publish, edit and delete workflow templates, comma-separated. The account's email must also be verified
GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET	Google sign-in and the "Google account" credential. Add <app URL>/api/oauth/google/callback as an authorised redirect URI
GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET	GitHub sign-in
SALESFORCE_CLIENT_ID, SALESFORCE_CLIENT_SECRET	The Salesforce connected app behind "Connect Salesforce". Its callback URL is <app URL>/api/oauth/salesforce/callback, with the api and refresh_token, offline_access scopes
RESEND_API_KEY	Sends verification and password-reset emails. Email verification is only required when this is set
EMAIL_FROM	Sender of those emails; must be on a domain verified in Resend

---

🗺️ Node Roadmap (Planned)

Nodes that are not built yet. Each new integration is a config passed to createIntegrationNode plus an executor; see src/features/executions/components/apps for the pattern.

Node	What it needs
Google Docs	Creating and editing documents (Drive can already download them as PDF)
More PDF scripts	Chinese, Japanese, Korean, Devanagari and emoji have no bundled font and are rejected; Urdu is drawn in Naskh style, not Nastaliq
Old Office files	Extract from File cannot read the old .xls and .doc formats. (It also cannot read scanned PDFs, but the Analyze Image / Document node now can, with a vision model.)
Rendering PDF pages	Analyze Image / Document takes a scanned page's picture out of the PDF instead of drawing the page, so a page made only of vector drawings without text cannot be read. Drawing pages needs a canvas library on the server
Browser Automation	Deliberately not built: it needs a headless browser service that cannot run on standard serverless functions, and it is easy to abuse. If added, the plan is a node that uses the user's own hosted-browser API key
MongoDB, Redis, Supabase (REST)	More data stores next to Postgres and MySQL
Slack / Discord bots	Bot-token nodes and triggers; today both send through webhook URLs

Also not built: a true n8n items model for every node from the trigger onward (items start at a list node), a real tokenizer for the Vector Store's token splitting, and the stdio transport for MCP (it needs a process on the user's own machine).

For the AI Backlink Outreach agent

Planned, not built. These are the pieces an agent needs to find link prospects, email them from real mailboxes, follow up in the same thread and keep track of who was contacted.

Planned item	What it needs
Google Sheets: row operations	Get Rows (with filter), Lookup Row, Update Row, Append or Update (upsert by a key column) and Delete Row; rows come out as a list so Split Out can take them
IMAP Trigger and IMAP node	A trigger for new email in a folder (polling every 1, 5, 15 or 60 minutes, a search filter, duplicate check by Message-ID) and a node with Search, Get Message, Mark as Read and Move to Folder. Needs a new IMAP credential: host, port, TLS, username, app password
Email (SMTP): headers and replies	Custom Headers (for List-Unsubscribe and List-Unsubscribe-Post), a "Reply To Message" option that sets In-Reply-To and References and adds "Re:", and the sent Message-ID in the output. The Gmail node returns messageId and threadId
Per-item approval and "Approve with edits"	Send and Wait for Approval asks once per item, and each item continues through Approved or Rejected. "Approve with edits" makes the subject and body editable on the approval page and returns them as {{approval.edited.subject}} / {{approval.edited.body}}. Needs default values on Form fields
Delay: random delay and sending window	Random Delay (min–max) per item, and a Sending Window (days, start and end hour, time zone)
Data Table node	A built-in key/value table per workspace with Add, Check Exists, Remove and List, for suppression lists and "already contacted" checks
Mailbox rotation on Gmail / SMTP	Several credentials on one node, picked by Round Robin or Least Used Today, with a daily limit per mailbox that is separate from the plan cap
Text Formatter: more operations	Extract Domain, Extract Root URL, Find Emails in Text, Normalize Email
Integration nodes	Hunter.io (Domain Search, Email Finder, Email Verifier), DataForSEO (SERP, Backlinks, Domain metrics), ZeroBounce / NeverBounce (Verify Email)
Link Checker option	Search the raw HTML (including nav, footer and sidebar) for a domain; return found, anchorText, rel and href
Gallery template	"AI Backlink Outreach" in the template gallery, built from the items above

Note on cold email: Resend and SendGrid are transactional services, and their policies generally forbid unsolicited cold email. Cold outreach should go through Gmail or SMTP mailboxes on a separate outreach domain, include an opt-out line, and follow CAN-SPAM / GDPR.

---

🛠️ Tech Stack

Frontend

• Next.js App Router
• React
• TypeScript
• React Flow
• Tailwind CSS
• Shadcn UI
• Zustand
• TanStack Query
• Jotai
• qrcode.react (the QR code for setting up two-factor authentication)

---

Backend

• Next.js API Routes
• tRPC
• Prisma ORM
• Neon PostgreSQL
• Better Auth
• Polar
• Inngest (Background Workers & Event Streams)
• Nodemailer
• Resend (account emails)
• QuickJS (sandboxed code and expressions)
• disposable-email-domains-js (the list of throwaway email domains refused at sign-up)
• fast-xml-parser (RSS and Atom feeds), mysql2 (MySQL node), ssh2 (SSH node)
• pdf-lib, fontkit and bidi-js (PDF Generator), unpdf, mammoth and exceljs (reading PDF, Word and Excel files)
• Noto Sans and Noto Naskh Arabic fonts (SIL Open Font License), bundled in assets/fonts

---

AI SDKs

• Vercel AI SDK (Agent Orchestration & Tool Calling)
• OpenAI, Anthropic and Google Gemini providers for the Vercel AI SDK

---

Monitoring & Dev Tools

• Sentry
• GitHub
• CodeRabbit
• Vercel

---

🧱 System Architecture

Frontend UI
   ↓
React Flow Workflow Builder
   ↓
Next.js App Router
   ↓
tRPC API Layer            Public API (/api/v1)        Webhook routes
   ↓                            ↓                          ↓
Prisma ORM  ←──────────────────────────────────────────────┘
   ↓
Neon PostgreSQL

Workflow Execution Engine
   ↓
Inngest Background Jobs & Cron Heartbeats
   ↓
Node Executors
   ↓
External APIs / AI Providers / Messaging Services