n8n Integration¶

n8n is an open-source workflow automation platform that lets you connect services through a visual node editor. By integrating n8n with Beyond Retrieval v2, you can automate document ingestion, build RAG-powered chatbots, schedule health monitoring, and collect user feedback — all without writing application code.

Prerequisites¶

Authentication Setup¶

Create a reusable credential in n8n so every HTTP Request node authenticates automatically.

1. Open Settings > Credentials in your n8n instance.
2. Click Add Credential and select Header Auth.
3. Configure the credential:

1. Click Save. This credential can now be selected in any HTTP Request node.

HTTP Request Node — Base Configuration¶

Every API call to Beyond Retrieval follows the same base pattern. Configure your HTTP Request nodes with these defaults:

Parsing the Response Envelope¶

Every Beyond Retrieval endpoint wraps its payload in a standard envelope:

{
  "success": true,
  "data": { ... },
  "error": null
}

In n8n expressions, access the payload like this:

// Get the full data object
{{ $json.data }}

// Get a nested field (e.g., AI response content)
{{ $json.data.assistant_message.content }}

// Check success status
{{ $json.success }}

// Get error message on failure
{{ $json.error }}

Example Workflows¶

1. Auto-Ingest Files from Webhook¶

Receive a file via webhook, upload it to Beyond Retrieval, and trigger ingestion.

graph LR
    A[Webhook Trigger] --> B[HTTP Request: Upload File]
    B --> C[IF: Upload Success?]
    C -->|Yes| D[HTTP Request: Start Ingestion]
    D --> E[Wait 10s]
    E --> F[HTTP Request: Check Stage]
    F --> G[IF: Still Processing?]
    G -->|Yes| E
    G -->|No| H[HTTP Request: Confirm Status]

Node 1 — Webhook Trigger

Node 2 — HTTP Request: Upload File

Node 3 — IF: Upload Success?

Node 4 — HTTP Request: Start Ingestion

Body:

{
  "files": [
    {
      "file_id": "={{ $('Upload File').item.json.data[0].file_id }}",
      "file_name": "={{ $('Upload File').item.json.data[0].file_name }}",
      "file_path": "={{ $('Upload File').item.json.data[0].storage_path }}"
    }
  ],
  "settings": {
    "parser": "Docling Parser",
    "chunking_strategy": "Recursive Chunking",
    "chunk_size": 1000,
    "chunk_overlap": 200
  }
}

Node 5 — Wait

Node 6 — HTTP Request: Check Stage

Node 7 — IF: Still Processing?

Loop the "Yes" branch back to the Wait node. The "No" branch proceeds to confirmation or notification.

2. Scheduled Health Monitoring¶

Run health checks on all notebooks every hour and send alerts for unhealthy ones.

graph LR
    A[Schedule Trigger] --> B[HTTP Request: List Notebooks]
    B --> C[Split In Batches]
    C --> D[HTTP Request: Health Check]
    D --> E[IF: Score < 70?]
    E -->|Yes| F[Slack / Email: Send Alert]
    E -->|No| G[No Op]

Node 1 — Schedule Trigger

Node 2 — HTTP Request: List Notebooks

Node 3 — Split In Batches

Node 4 — HTTP Request: Health Check

Node 5 — IF: Score Below Threshold?

Node 6 — Slack (or Email) Alert

Compose a message with the health details:

Notebook: {{ $('Health Check').item.json.data.notebook_id }}
Health Score: {{ $('Health Check').item.json.data.health_score }}/100
Duplicates: {{ $('Health Check').item.json.data.duplicate_count }}
Orphans: {{ $('Health Check').item.json.data.orphaned_count }}

3. Chat Bot via Telegram or Slack¶

Build a RAG-powered chatbot that answers questions from your knowledge base.

graph LR
    A[Telegram / Slack Trigger] --> B[HTTP Request: Find or Create Conversation]
    B --> C[HTTP Request: Send Message to RAG]
    C --> D[IF: Success?]
    D -->|Yes| E[Telegram / Slack: Reply with Answer]
    D -->|No| F[Telegram / Slack: Reply with Error]

Node 1 — Telegram Trigger (or Slack Trigger)

Node 2 — HTTP Request: Create Conversation

{
  "title": "Telegram Chat {{ $json.message.from.first_name }}",
  "chat_mode": "rag"
}

Node 3 — HTTP Request: Send Message to RAG

{
  "content": "={{ $('Telegram Trigger').item.json.message.text }}",
  "chat_mode": "rag",
  "strategy_id": "fusion",
  "persona": "professional",
  "language": "en"
}

Node 4 — IF: Success?

Node 5 — Telegram: Reply

4. Auto-Feedback Collection¶

Collect user feedback from an external system and post it to Beyond Retrieval.

graph LR
    A[Webhook Trigger] --> B[HTTP Request: Post Feedback]
    B --> C[IF: Success?]
    C -->|Yes| D[Respond to Webhook: 200 OK]
    C -->|No| E[Respond to Webhook: 500 Error]

Node 1 — Webhook Trigger

Expected webhook body:

{
  "notebook_id": "a1b2c3d4-...",
  "message_id": "msg-5678-...",
  "is_positive": true,
  "feedback_text": "Very helpful answer"
}

Node 2 — HTTP Request: Post Feedback

{
  "is_positive": "={{ $json.body.is_positive }}",
  "feedback_text": "={{ $json.body.feedback_text }}"
}

Node 3 — Respond to Webhook

Return the result to the caller with the appropriate status code.

5. Batch Document Processing¶

Watch a folder, upload each file, and ingest them in sequence.

graph LR
    A[Schedule / Manual Trigger] --> B[Read Binary Files]
    B --> C[Split In Batches]
    C --> D[HTTP Request: Upload]
    D --> E[IF: Upload OK?]
    E -->|Yes| F[HTTP Request: Ingest]
    F --> G[Wait 15s]
    G --> H[HTTP Request: Check Stage]
    H --> I[IF: Done?]
    I -->|No| G
    I -->|Yes| J[Next Batch Item]

Node 1 — Read Binary Files

Node 2 — Split In Batches

Process files one at a time to avoid overloading the ingestion pipeline.

Node 3 — HTTP Request: Upload

Node 4 — HTTP Request: Ingest

{
  "files": [
    {
      "file_id": "={{ $('Upload').item.json.data[0].file_id }}",
      "file_name": "={{ $('Upload').item.json.data[0].file_name }}",
      "file_path": "={{ $('Upload').item.json.data[0].storage_path }}"
    }
  ],
  "settings": {
    "parser": "Docling Parser",
    "chunking_strategy": "Recursive Chunking"
  }
}

Node 5 — Wait + Poll Loop

Same pattern as Workflow 1: wait 15 seconds, check the stage endpoint, loop while status is Processing.

Error Handling¶

IF Node Pattern¶

Place an IF node after every HTTP Request to branch on the response:

// Condition
{{ $json.success === true }}

• True branch: continue normal processing
• False branch: log the error, send a notification, or retry

Error Trigger Workflow¶

Create a separate workflow with an Error Trigger node to catch failures globally:

1. Create a new workflow named Error Handler.
2. Add an Error Trigger node as the start node.
3. Add a Slack or Email node to notify on failures.
4. In your main workflows, go to Settings > Error Workflow and select Error Handler.

The Error Trigger receives the full error context including the failed node name and error message.

Retry Logic¶

For transient errors (network timeouts, 429 rate limits), configure retries on the HTTP Request node:

Tips and Best Practices¶

Quick Reference — Common API Calls¶