Pipeline Overview

The Boring Marketing pipeline is a progressive enrichment system. Each stage adds depth to the one before it. You can run the entire pipeline in one call, or trigger individual stages when you need finer control.

The pipeline at a glance

The six stage strings emitted during a full /analyze run are: brand_enrichment, competitor_discovery, family_discovery, evidence_collection, leverage_scoring, queue_building. Opportunity synthesis runs inside evidence_collection — it does not emit its own stage string.

Stage breakdown

1. Brand Enrichment (optional)

Crawls up to 30 pages of your brand's website via our crawler. Extracts trust signals, services, certifications, testimonials, and identifies gaps. Produces brand findings — categorized as trust_gap, eeat_gap, content_gap, or technical_gap with severity levels.

These findings feed into leverage scoring later, boosting opportunities that address your brand's actual weaknesses.

Endpoint: POST /brands/{id}/enrich/brand

1b. Technical Enrichment (optional)

Runs a full technical site audit via GemMiner, or accepts an uploaded audit from your own crawler. Persists health score, pages crawled, and categorized issues on the brand's technical_context. Each technical issue becomes an insight that feeds the leverage scoring multiplier for technical_gap category (1.30x).

Endpoint: POST /brands/{id}/enrich/technical

Body accepts either {"trigger": true} to run a fresh crawl or {"audit_data": {...}} to upload existing audit JSON.

2. Competitor Discovery

Automatically identifies competitors in your space using JTBD-framed research. Finds business competitors, SERP competitors, and content competitors — each tagged by type and tier (direct, adjacent, content).

Endpoint: POST /brands/{id}/discover-competitors

3. Family Discovery

The core of the keyword universe. A 10-step Haiku-validated pipeline that:

1. Seeds from your brand context and crawled pages
2. Pulls related keywords from DataForSEO
3. Proposes topic families via LLM
4. Validates each family is grounded in 5+ real keywords
5. Assigns, expands, and cleans up keyword-to-family mappings
6. Final validation: 80% coherence, less than 15% contamination

The output is your keyword universe — hundreds to thousands of keywords organized into coherent topic families.

4. Evidence Collection

For each topic family, the pipeline collects real SERP evidence:

• Organic rankings for each keyword
• AI Overview presence
• People Also Ask questions
• Your brand's current position (or absence)
• Competitor positions

Evidence is parallelized (semaphore of 3 per-keyword) and persisted to the database for full audit trail.

5. Opportunity Synthesis (runs inside evidence collection)

An LLM synthesizes the evidence into strategic opportunities. Each opportunity includes:

• Priority score — 0.5 * immediacy + 0.5 * ceiling
• Immediacy — how easy to win (keyword difficulty inverted, gap boost, greenfield bonus)
• Ceiling — how big the prize (volume, business value, intent, AIO bonus)
• Recommended format — article, comparison post, pillar guide, hub-and-spokes
• Contributing signals — the evidence that produced this opportunity

Synthesis is part of the evidence_collection stage — it does not emit a separate stage string. If you want to re-run synthesis without re-crawling, use POST /brands/{id}/synthesize (~30s vs ~14min for a full discovery).

6. Leverage Scoring

Cross-references brand findings from enrichment with content opportunities. Applies multipliers:

Opportunities that address a brand weakness get boosted. The output is a unified action queue with both brand-fix and content items, sorted by leverage score.

One call vs. individual stages

curl -s -X POST \
  -H "X-API-Key: $BM_API_KEY" \
  "https://api.boringmarketing.com/brands/$BRAND_ID/analyze"

Async pattern

All pipeline endpoints return 202 Accepted with a run_id. Poll GET /brands/{id}/runs/{run_id} for progress. See Polling Runs for implementation patterns.

Data flow

Every recommendation is traceable to the evidence that produced it:

Family → Evidence → Opportunity → Brief → Draft

Use the results endpoints to inspect any layer: