N8N Node

The ReyGrid N8N node is published on npm as the package n8n-nodes-reygrid. It is a community node for n8n. It adds a single ReyGrid node to your workflows that calls the ReyGrid REST API.


npm package	`n8n-nodes-reygrid`
Version documented	1.1.0
API server	`https://reygrid.com/api/v1` (fixed, not configurable)
Authentication	ReyGrid API key sent as a Bearer token

What it does

Chat → Send Message

Sends a message to an agent (POST /agents/{agentId}/chat). AI tools connected to the node are executed automatically until the agent returns its final answer.

Tool Call → Cancel

Cancels a tool call in a conversation.

Install

Open Community nodes

In n8n, go to Settings → Community nodes and click Install a community node.

The n8n Community nodes settings page with the Install a community node button — Settings → Community nodes

Enter the package name

In npm Package Name, enter:

n8n-nodes-reygrid

Tick I understand the risks of installing unverified code from a public source, then click Install.

The Install community nodes dialog with npm Package Name n8n-nodes-reygrid and the risk checkbox ticked — Install community nodes dialog

Find the node

When the installation finishes, open a workflow, click +, and search for ReyGrid.

Community nodes are installed by an n8n instance owner or admin. If you don’t see Community nodes in Settings, ask the person who manages your n8n instance.

Install from the command line instead

On a self-hosted instance you can install the package into n8n’s custom nodes folder and restart n8n:

cd ~/.n8n/nodes
npm install n8n-nodes-reygrid

The folder location can differ depending on how you run n8n (for example in Docker).

Set up credentials

Create a ReyGrid API credential the first time you add the node.

Field	Description
API Key	Your ReyGrid API key. Sent as `Authorization: Bearer <API Key>`.

n8n tests the credential with GET /validate. See Authentication for how keys work.

Use it in a workflow

The example below receives a request on a Webhook node and sends it to a ReyGrid agent. A Calculator tool is connected to the node’s Tools input, so the agent can use it.

An n8n workflow: a Webhook node feeding a ReyGrid node named Send a message to an agent, with a Calculator tool attached to the Tools input — ReyGrid node with a Calculator tool connected to its Tools input

Node reference

Chat → Send Message

Parameter	Required	Description
Agent ID	yes	The ID of the agent.
Message	yes	The message to send. It can’t be empty.
User ID	no	Stable user identifier used as a persistent conversation. When set, Conversation ID is ignored.
Conversation ID	no	An existing conversation. Ignored when User ID is set. Leave both empty to start a new conversation.

Both identifiers behave as described in Persistent conversations. If you use only Conversation ID, the node follows the conversation ID returned by the API for the remaining rounds of the same run. Options

Option	Default	Description
Include Tool Calls in Output	off	Adds a `toolCalls` array (name, arguments, output) describing every tool executed during the run.
Max Tool Iterations	`10`	Maximum number of tool-execution rounds. When exceeded, pending tool calls are cancelled and the node fails.
On Tool Error	Send Error to Agent	Send Error to Agent returns the error text as the tool result so the agent can recover. Cancel Tool Calls and Stop cancels the pending tool calls through the API and returns the last response.

Automatic tool loop

Tools connected to the Tools input are sent to the agent as function tools. The node then repeats the following until the agent has no more tool calls:

Send the message (or the previous tool results) to the agent.
If the response contains tool calls, run the matching connected tools.
Send the tool outputs back as results and continue.

Tool calls are read from output.tool_calls, output.reply.tool_calls, or tool_calls in the response. If the agent asks for a tool that isn’t connected, or a tool fails, the behavior follows On Tool Error. Connected tool names must be unique.

The OpenAPI specification doesn’t describe where a chat response carries tool calls. This page documents what the node does, not a guaranteed API contract. See Tool calling.

Output

{
  "success": true,
  "conversationId": "…",
  "userId": "…",
  "messageId": "…",
  "output": {
    "reply": { "id": "…", "content": "…" },
    "finish_reason": "stop"
  },
  "usage": { "credits": 1 }
}

usage.credits is the sum over every request made during the tool loop.
toolCalls is added when Include Tool Calls in Output is on.
canceledToolCalls (IDs the API confirmed as cancelled) is added when On Tool Error is Cancel Tool Calls and Stop and a tool failed.

Tool Call → Cancel

Cancels a tool call. Calls POST /agents/{agentId}/conversations/{ref}/tool/cancel/{toolCallId}.

Parameter	Required	Description
Agent ID	yes	The ID of the agent.
Conversation ID or User ID	yes	The `conversationRef`: a conversation ID or a persistent user ID.
Tool Call ID	yes	The ID of the tool call to cancel.

The output is the API response, { "success": true, "canceled": true }.

Errors

API failures are shown as n8n node errors. The message comes from the API error body (code: message for most errors, or the error text for 401). Turn on Continue On Fail in the node settings to receive { "error": "…" } for a failed item instead of stopping the workflow. See Errors for the status codes.

Overview

Python SDK

TypeScript SDK

N8N

What it does

Chat → Send Message

Tool Call → Cancel

Install

Set up credentials

Use it in a workflow

Node reference

Chat → Send Message

Automatic tool loop

Output

Tool Call → Cancel

Errors

​What it does

Chat → Send Message

Tool Call → Cancel

​Install

​Set up credentials

​Use it in a workflow

​Node reference

​Chat → Send Message

​Automatic tool loop

​Output

​Tool Call → Cancel

​Errors

What it does

Install

Set up credentials

Use it in a workflow

Node reference

Chat → Send Message

Automatic tool loop

Output

Tool Call → Cancel

Errors