Zapier Integration

Overview

Zapier doesn't have a native Brainpercent app yet. Instead, use the "Webhooks by Zapier" premium action to call any Brainpercent API endpoint directly. This guide shows the exact settings for every field in Zapier's interface.

Prerequisites

• A Zapier account on a paid plan (Starter, Professional, or Team)
• A Brainpercent API key with read and write permissions
• Your API key starts with bp_. Create one at brainpercent.app/chat/developers. Keys cannot be created over the API, so this is a one-time manual step.
• A project id. Every generation call needs one. Grab it once with GET https://www.brainpercent.app/api/v1/projects and paste it into your Zap, or add that call as a step. Projects are created in the app, not over the API.

Setting Up "Webhooks by Zapier"

Step 1: Add the Action

In your Zap editor, click the + button to add an action step. Search for "Webhooks by Zapier" and select it. Choose "Custom Request" as the Action Event, not "POST" or "GET": Custom Request gives you full control over all fields.

Step 2: Configure Every Field

Here are the exact values for each field in the Custom Request configuration panel:

Step 3: Headers (Key-Value Pairs)

In the Headers section, click "+ Add Header" to add each row:

Step 4: Data (JSON Body)

In the "Data" field, paste this exact JSON. You can use Zapier template variables from previous trigger steps (shown with {{curly braces}}).

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

Step 5: Test the Action

Click "Test step". Zapier shows the raw API response. You should see:

{
  "success": true,
  "data": {
    "article_id": "a1b2c3d4-e5f6-...",
    "status": "queued",
    "job_id": "job_01hxyz",
    "slug": "your-article-topic-here",
    "language": "en",
    "credits_deducted": 1,
    "credits_remaining": 32,
    "estimated_time": "10-15 minutes",
    "poll_url": "/api/v1/articles/a1b2c3d4-e5f6-.../status"
  }
}

Multi-Step Zap: Full Content Pipeline

Generate an article, wait for it to complete, then auto-generate social media content. This requires 5 Zapier steps:

Step 1: Trigger

Choose any trigger: "RSS by Zapier → New Item in Feed", "Schedule by Zapier → Every Day", or "Google Sheets → New Row".

Step 2: Webhooks by Zapier: Generate Article

Configure exactly as shown in the setup section above. Use trigger data for the topic:

{
  "topic": "{{1. Title}}",
  "project_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "keywords": ["{{1. Category}}"],
  "tone": "professional",
  "word_count": 900
}

Step 3: Delay by Zapier: Wait for Generation

Step 4: Webhooks by Zapier: Check Article Status

Note: Zapier flattens nested JSON keys with double underscores. The data.article_id from Step 2 becomes {{2. data__article_id}} in the Zapier variable picker.

This step returns data.is_complete, data.status, data.progress, data.title, and data.slug. Use {{4. data__is_complete}} in a Filter or Path so the Zap only continues when the article is actually done.

Step 5: Webhooks by Zapier: Generate Social Content

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

Optional Step 6: Publish or Schedule

Add another Custom Request to POST https://www.brainpercent.app/api/v1/social/publish. Wait until the content is ready first (a Delay plus a GET on /social/content/{id}), otherwise the call returns 412.

{
  "content_id": "{{5. data__content_id}}"
}

Only content_id is required. platforms is an optional subset: omit it to publish every variant. With no scheduled_at the API returns 202 and publishes immediately; with one it returns 200 and schedules. A 412 also means the account has no connected social profiles.

Parsing Responses with "Code by Zapier"

While Zapier auto-parses JSON from the Webhooks step, sometimes you need to transform data. Add a "Code by Zapier" step (JavaScript) after your webhook to extract specific fields:

Code Step Configuration

// Code by Zapier: Run Javascript
// inputData.rawResponse contains the API response

const response = JSON.parse(inputData.rawResponse);

if (response.success) {
  output = [{
    articleId: response.data.article_id || response.data.id,
    status: response.data.status,          // 'queued' on create, 'cms' when done
    isComplete: response.data.is_complete === true,
    slug: response.data.slug || '',
    creditsUsed: response.data.credits_deducted || 0,
    creditsLeft: response.data.credits_remaining,
  }];
} else {
  output = [{
    error: response.error?.code || 'UNKNOWN',
    message: response.error?.message || 'Request failed',
  }];
}

Error Handling with Zapier Paths

Use Paths by Zapier (conditional logic) after the Webhooks step to handle success and failure:

Path Configuration

Handling Rate Limits (429)

In the Custom Request settings, check the "Continue On Error" checkbox (under "Show Advanced Options"). This prevents the Zap from halting on 429 responses. Then use a Path step to check the HTTP status code and add a Delay before retrying. Free keys get 100 requests per minute and 5,000 per day; paid plans get 1,000 per minute and 50,000 per day.

Other Codes Worth Branching On

• 402 INSUFFICIENT_CREDITS: do not retry. Alert yourself and top up.
• 400 NO_PROJECT: the project_id is missing or the account has no projects.
• 412 PRECONDITION_FAILED on publish: the content is still generating, or no social accounts are connected. Add a Delay and retry.

Example Zaps

RSS Feed → Article Generation

Google Sheets → Bulk Article Generation

{
  "topic": "{{1. Column A - Topic}}",
  "project_id": "{{1. Column B - Project Id}}",
  "keywords": ["{{1. Column C - Keyword 1}}", "{{1. Column D - Keyword 2}}"],
  "tone": "{{1. Column E - Tone}}",
  "word_count": 1200
}

Daily Schedule → Social Content

Tips & Best Practices

• Store your API key as a Zapier "Custom Value" or in Zapier's Secret Manager for reuse across Zaps
• Always use "Custom Request" (not "POST") to get full control over headers and body
• Enable "Continue On Error" in advanced settings to handle 4xx/5xx without halting
• Use "Formatter by Zapier" to split comma-separated keywords into arrays
• Use Paths after webhook steps for success/failure branching
• Monitor credit balance weekly with a scheduled GET /user/credits Zap. It is one balance for everything: an article costs 1.5 credits, social costs 0.6 credits per platform.
• Zapier uses double underscores for nested JSON: data__article_id
• Hard-code the project_id as a Zapier Custom Value. It rarely changes and it is required on every generate call.
• Filter on data__is_complete, not on a status string. A finished article is cms, never published.