n8n Integration

Overview

n8n is a self-hosted (and cloud-hosted) workflow automation tool. Use the HTTP Request node to connect to Brainpercent's API. This guide covers every field in n8n's node configuration, credential setup, and workflow patterns.

Prerequisites

• An n8n instance, self-hosted (npx n8n or Docker) or n8n.cloud
• A Brainpercent API key (bp_ prefix) with read + write permissions, created at brainpercent.app/chat/developers. Keys cannot be created over the API.
• A project id. Every generation call needs one. Fetch it with GET https://www.brainpercent.app/api/v1/projects or add that call as the first HTTP Request node. Projects are created in the app, not over the API.
• n8n version 0.220+ (for latest HTTP Request node features)

Step 1: Create Header Auth Credential

Before configuring the HTTP Request node, create a reusable credential. Go to Settings → Credentials → Add Credential and search for "Header Auth".

Step 2: HTTP Request Node Configuration

Add an HTTP Request node to your workflow. Here is every field in the node settings panel:

Header Parameters

Under "Header Parameters", add one header (the Authorization is handled by the credential):

JSON Body

In the "JSON" field, paste your request body. Use n8n expressions with {{ }} to reference data from previous nodes:

{
  "topic": "Your Article Topic",
  "project_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "keywords": ["keyword1", "keyword2"],
  "tone": "professional",
  "word_count": 1200
}

Workflow: Content Automation Pipeline

Cron → Generate Article → Wait → Check Status → IF Ready → Generate Social

Node 1: Schedule Trigger

Node 2: HTTP Request (Generate Article)

Configured as shown in the HTTP Request Node Configuration above. POST to /api/v1/articles/generate.

{
  "topic": "Daily SEO insights for {{ $now.format('MMMM D, YYYY') }}",
  "project_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "keywords": ["SEO", "daily insights"],
  "tone": "professional",
  "word_count": 900
}

Node 3: Wait

Node 4: HTTP Request (Check Status)

Node 5: IF (Check Generation Status)

Node 6: HTTP Request (Generate Social)

{
  "source_url": "https://www.brainpercent.app/articles/{{ $json.data.slug }}",
  "platforms": ["twitter", "linkedin"],
  "project_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "angle": "Practical takeaways for busy marketers"
}

Node 7: Publish or Schedule

Loop a Wait plus an HTTP Request on https://www.brainpercent.app/api/v1/social/content/{{ $json.data.content_id }} until data.status is ready or completed, then POST to /api/v1/social/publish. Publishing while the content is still generating returns 412, and so does publishing with no connected social accounts.

{
  "content_id": "{{ $json.data.content_id }}"
}

Only content_id is required. Omit platforms to publish every variant. Without scheduled_at you get a 202 and it publishes immediately; with it, a 200 and it is scheduled.

Workflow: Conditional Generation

Check credits before generating to avoid failures and wasted workflow runs.

For a social job the threshold is the number of platforms times 0.6, since that is what one platform costs. 1 credit equals $1.00 of a single balance that covers every content type.

Workflow: Webhook Listener

Expose an n8n webhook endpoint that triggers article generation when called externally. This webhook is hosted by your n8n instance and is called by your own systems. Brainpercent does not send webhooks: there is no callback registration and no signed payload, so completion still has to be polled.

Webhook Node Configuration

The full webhook URL will be: https://your-n8n-instance.com/webhook/generate-article

n8n Expressions Reference

n8n uses JavaScript expressions inside {{ }} to reference data from previous nodes:

Error Handling & Workflow Settings

Error Trigger Workflow

Create a separate "Error Workflow" in n8n that catches failures from all workflows:

Then in your main workflow's settings (gear icon), set Error Workflow to point to this error handler.

Retry on Failure

Tips & Best Practices

• Use Header Auth credentials. Never hardcode API keys in HTTP Request nodes.
• Enable "Always Output Data" on HTTP Request nodes so subsequent nodes receive data even on error
• Use the Wait node (not Code node with sleep()) for workflow pauses
• Set up an Error Trigger workflow to catch failures across all workflows
• Use "Split In Batches" node when processing large arrays of articles
• Social generation returns one row for every platform, so there is no items array. Read captions from data.platforms.<platform> and images from data.image_urls.
• Store the project_id alongside the API key. It is required on every generate call.
• For self-hosted: use environment variables for secrets, e.g. {{ $env.BRAINPERCENT_API_KEY }}
• For self-hosted: enable queue mode in production for concurrent workflow execution
• Enable "Retry On Fail" on HTTP Request nodes with a 60-second interval for rate limit resilience