n8n Integration

Use Orsa with n8n — the open-source workflow automation tool. Self-host or use n8n Cloud with full control over your data and workflows.

Getting Started

1. Set Up Credentials

Open your n8n instance
Go to Credentials → Create New
Select Header Auth
Name: Authorization
Value: Bearer YOUR_API_KEY
Save as "Orsa API"

2. Add HTTP Request Nodes

Use n8n's built-in HTTP Request node to call Orsa endpoints.

Example Workflow: New Lead → Enrich → Notify

Node 1: Trigger

Use any trigger — Webhook, CRM, Google Sheets, or Schedule.

Node 2: Orsa Brand Lookup

{
  "node": "HTTP Request",
  "method": "GET",
  "url": "https://api.orsa.dev/v1/brand/retrieve-by-email",
  "authentication": "genericCredentialType",
  "genericAuthType": "httpHeaderAuth",
  "queryParameters": {
    "email": "={{ $json.email }}"
  },
  "options": {
    "response": {
      "response": {
        "responseFormat": "json"
      }
    }
  }
}

Node 3: IF Node (Brand Found?)

Condition: {{ $json.success }} equals true

Node 4: Slack Notification (True branch)

Message: 🏢 New lead enriched!
Company: {{ $json.data.name }}
Domain: {{ $json.data.domain }}
Industry: {{ $json.data.industry }}

Batch Enrichment Workflow

Google Sheets → Split In Batches → HTTP (Orsa) → Wait (1s) → Loop → Google Sheets

Configuration

{
  "nodes": [
    {
      "name": "Get Leads",
      "type": "Google Sheets",
      "operation": "read",
      "sheetId": "your-sheet-id"
    },
    {
      "name": "Split In Batches",
      "type": "SplitInBatches",
      "batchSize": 1
    },
    {
      "name": "Enrich",
      "type": "HTTP Request",
      "method": "GET",
      "url": "https://api.orsa.dev/v1/brand/retrieve",
      "queryParameters": {
        "domain": "={{ $json.domain }}"
      }
    },
    {
      "name": "Wait",
      "type": "Wait",
      "amount": 1,
      "unit": "seconds"
    }
  ]
}

Available Endpoints

Use Case	Method	URL
Brand by Domain	GET	`https://api.orsa.dev/v1/brand/retrieve?domain={{domain}}`
Brand by Email	GET	`https://api.orsa.dev/v1/brand/retrieve-by-email?email={{email}}`
Scrape Page	GET	`https://api.orsa.dev/v1/web/scrape/markdown?url={{url}}`
Extract Images	GET	`https://api.orsa.dev/v1/web/scrape/images?url={{url}}`
NAICS Classify	GET	`https://api.orsa.dev/v1/brand/naics?domain={{domain}}`
AI Query	POST	`https://api.orsa.dev/v1/brand/ai/query`
Start Crawl	POST	`https://api.orsa.dev/v1/web/crawl`

Error Handling

Use n8n's Error Trigger or IF nodes to handle failures:

HTTP Request → IF (success === true)
                ├── True: Process data
                └── False: IF (error.code === "RATE_LIMITED")
                            ├── True: Wait 30s → Retry
                            └── False: Log error

Retry on Error

Enable retries on the HTTP Request node:

On Error: Continue (return error output)
Max Retries: 3
Wait Between Retries: 5000ms

Community Node

A dedicated n8n community node for Orsa is planned. Follow @orsa_dev (opens in a new tab) for updates.

Tips

Use "Split In Batches" for processing lists — it prevents rate limit issues and memory problems.
Add a Wait node (1-2 seconds) inside batch loops to respect rate limits.
Cache results in a Postgres/Redis node to avoid re-fetching the same domains.
Use expressions like ={{ $json.email.split('@')[1] }} to extract domains from emails inline.
Self-hosting? Set ORSA_BASE_URL if you're using a custom API endpoint.

Make Changelog