# n8n Integration

> Use PromptRails as a node in your n8n workflows — execute agents, run prompts, manage chat sessions, and more.

Source: https://0.0.0.0:8080/docs/n8n-integration

The official [n8n](https://n8n.io/) community node for PromptRails lets you integrate AI agents, prompts, chat sessions, and data sources into your n8n workflows. Execute agents on schedule, respond to webhooks with AI, monitor costs, and build complex automation pipelines.

## Installation

In your n8n instance:

1. Go to **Settings > Community Nodes**
2. Select **Install a community node**
3. Enter `@promptrails/n8n-nodes-promptrails`
4. Click **Install**

## Configuration

Create a **PromptRails API** credential in n8n with the following fields:

| Field        | Description                                      |
| ------------ | ------------------------------------------------ |
| **Host URL** | `https://api.promptrails.ai` (default)           |
| **API Key**  | Your PromptRails API key (starts with `pr_key_`) |

To create an API key, go to **Settings > API Keys** in the PromptRails dashboard. See [API Keys & Scopes](/docs/api-keys-and-scopes) for required scopes.

## Resources & Operations

| Resource        | Operations                                                              | Required Scopes                             |
| --------------- | ----------------------------------------------------------------------- | ------------------------------------------- |
| **Agent**       | Execute, Preview, Get, List                                             | `agents:read`, `agents:execute`             |
| **Prompt**      | Run, Get, List                                                          | `prompts:read`, `prompts:execute`           |
| **Chat**        | Create Session, Send Message, Get Session, List Sessions, List Messages | `chat:write`, `sessions:read`               |
| **Execution**   | Get, List                                                               | `executions:read`                           |
| **Data Source** | Query, Get, List                                                        | `data_sources:read`, `data_sources:execute` |
| **Trace**       | Get, List                                                               | `traces:read`                               |
| **Cost**        | Workspace Summary, Agent Summary                                        | `executions:read`                           |

## Example Workflows

### Execute an Agent on Schedule

Trigger an agent every hour and send the result to Slack:

1. **Schedule Trigger** — Run every hour
2. **PromptRails** — Resource: Agent, Operation: Execute, provide the Agent ID and variables
3. **Slack** — Post the agent output to a channel

### AI-Powered Webhook Responder

Respond to incoming HTTP requests with an AI agent:

1. **Webhook** — Receive incoming requests
2. **PromptRails** — Resource: Chat, Operation: Send Message
3. **Respond to Webhook** — Return the agent's response

### Multi-Turn Chat Bot

Build a stateful chatbot using chat sessions:

1. **Webhook** — Receive user messages
2. **IF** — Check if session ID exists in the request
3. **PromptRails** — Resource: Chat, Operation: Create Session (if new)
4. **PromptRails** — Resource: Chat, Operation: Send Message
5. **Respond to Webhook** — Return the response

### Daily Cost Monitoring

Monitor your AI spending and get alerts:

1. **Schedule Trigger** — Run daily at 9 AM
2. **PromptRails** — Resource: Cost, Operation: Workspace Summary
3. **IF** — Check if total cost exceeds budget threshold
4. **Email / Slack** — Send an alert notification

### Data Source Query Pipeline

Query a data source and process the results:

1. **Schedule Trigger** or **Webhook** — Trigger the workflow
2. **PromptRails** — Resource: Data Source, Operation: Query
3. **PromptRails** — Resource: Agent, Operation: Execute (analyze the query results)
4. **Google Sheets** — Write the analysis to a spreadsheet

## Tips

- **Variables as JSON**: Agent Execute and Prompt Run accept variables as a JSON object. Use n8n expressions to build dynamic variables from previous nodes: `{{ JSON.stringify({ query: $json.message }) }}`
- **Pagination**: List operations support `page` and `limit` parameters for paginating through results
- **Error handling**: Use n8n's built-in error handling to retry failed operations or route to fallback paths
- **Chaining**: Chain multiple PromptRails operations — e.g., create a chat session, then send messages in sequence

## Related Topics

- [API Keys & Scopes](/docs/api-keys-and-scopes) -- Managing API keys and permissions
- [Webhook Triggers](/docs/webhook-triggers) -- Trigger agents via HTTP webhooks
- [REST API Reference](/docs/rest-api-reference) -- Full API documentation
- [Python SDK](/docs/python-sdk) -- Python SDK alternative
- [JavaScript SDK](/docs/javascript-sdk) -- JavaScript SDK alternative