> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reygrid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# N8N Node

> Install the ReyGrid community node in n8n to chat with your RAG agents, run connected AI tools automatically, and cancel tool calls.

The ReyGrid N8N node is published on npm as the package `n8n-nodes-reygrid`. It is a community node for [n8n](https://n8n.io). It adds a single **ReyGrid** node to your workflows that calls the [ReyGrid REST API](/rest-api/overview).

| | |
| - | - |
| npm package | [`n8n-nodes-reygrid`](https://www.npmjs.com/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

<CardGroup cols={2}>
  <Card title="Chat → Send Message" icon="message" href="/api-reference/chat-with-an-agent">
    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.
  </Card>

  <Card title="Tool Call → Cancel" icon="ban" href="/api-reference/cancel-a-tool-call">
    Cancels a tool call in a conversation.
  </Card>
</CardGroup>

## Install

<Steps>
  <Step title="Open Community nodes">
    In n8n, go to **Settings → Community nodes** and click **Install a community node**.

    <Frame caption="Settings → Community nodes">
      <img src="https://mintcdn.com/reygrid/lQuFdx2qoyAhj4-S/images/n8n-community-nodes.png?fit=max&auto=format&n=lQuFdx2qoyAhj4-S&q=85&s=0a002d82b1a665cd91cb1c7b242cb3ee" alt="The n8n Community nodes settings page with the Install a community node button" width="1920" height="887" data-path="images/n8n-community-nodes.png" />
    </Frame>
  </Step>

  <Step title="Enter the package name">
    In **npm Package Name**, enter:

    ```text theme={"system"}
    n8n-nodes-reygrid
    ```

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

    <Frame caption="Install community nodes dialog">
      <img src="https://mintcdn.com/reygrid/lQuFdx2qoyAhj4-S/images/n8n-install-dialog.png?fit=max&auto=format&n=lQuFdx2qoyAhj4-S&q=85&s=7a965a86fce4d71ab11a5431c7cefff7" alt="The Install community nodes dialog with npm Package Name n8n-nodes-reygrid and the risk checkbox ticked" width="1920" height="889" data-path="images/n8n-install-dialog.png" />
    </Frame>
  </Step>

  <Step title="Find the node">
    When the installation finishes, open a workflow, click **+**, and search for **ReyGrid**.
  </Step>
</Steps>

<Note>
  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.
</Note>

<Accordion title="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:

  ```bash theme={"system"}
  cd ~/.n8n/nodes
  npm install n8n-nodes-reygrid
  ```

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

## 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](/rest-api/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.

<Frame caption="ReyGrid node with a Calculator tool connected to its Tools input">
  <img src="https://mintcdn.com/reygrid/lQuFdx2qoyAhj4-S/images/n8n-workflow.png?fit=max&auto=format&n=lQuFdx2qoyAhj4-S&q=85&s=46908a469fd03d49cda7bd762f1078ab" alt="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" width="1920" height="894" data-path="images/n8n-workflow.png" />
</Frame>

## 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](/rest-api/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:

1. Send the message (or the previous tool results) to the agent.
2. If the response contains tool calls, run the matching connected tools.
3. 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.

<Info>
  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](/rest-api/tool-calling).
</Info>

#### Output

```json theme={"system"}
{
  "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](/rest-api/errors) for the status codes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.