---
title: Pipeline Overview
description: "How the enrichment pipeline works — from brand registration through opportunity scoring. Understand each stage, what data it produces, and which endpoints to call."
---

> **For AI agents:** the complete documentation index is at [llms.txt](https://docs.boringmarketing.com/llms.txt). Append `.md` to any page URL for its markdown version.

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

```mermaid
graph TD
    A[Brand Enrichment] -->|Crawl site, extract identity| B[Competitor Discovery]
    B -->|Find competitive landscape| C[Family Discovery]
    C -->|Build keyword universe| D[Evidence Collection]
    D -->|Evidence-first synthesis| E[Leverage Scoring]
    E -->|Cross-reference with brand gaps| F[Queue Building]
    F --> G[Brief Generation]
    G --> H[Content Drafting]
    H --> I[Outcome Tracking]
    I -->|7/30/90-day learning| A
```

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:

| Finding Category | Multiplier |
|-----------------|-----------|
| Trust gap | 1.20x |
| E-E-A-T gap | 1.25x |
| Content gap | 1.10x |
| Technical gap | 1.30x |

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

<Tabs>
  <Tab title="Full Pipeline (recommended)">
    Run everything end-to-end with a single call:

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

    This triggers all six stages in order: `brand_enrichment`, `competitor_discovery`, `family_discovery`, `evidence_collection`, `leverage_scoring`, `queue_building`.

    Takes 15-30 minutes. Best for first runs on a new brand.
  </Tab>
  <Tab title="Individual Stages">
    Run stages independently when you want control:

    ```bash
    # Just discover keywords and opportunities (skip brand enrichment)
    curl -s -X POST \
      -H "X-API-Key: $BM_API_KEY" \
      "https://api.boringmarketing.com/brands/$BRAND_ID/discover"

    # Re-score after updating brand context
    curl -s -X POST \
      -H "X-API-Key: $BM_API_KEY" \
      "https://api.boringmarketing.com/brands/$BRAND_ID/score"
    ```

    Useful when you want to re-run scoring without re-discovering keywords, or skip enrichment for a quick analysis.
  </Tab>
</Tabs>

## Async pattern

All pipeline endpoints return **202 Accepted** with a `run_id`. Poll `GET /brands/{id}/runs/{run_id}` for progress. See [Polling Runs](https://docs.boringmarketing.com/guides/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:

| Data | Endpoint |
|------|----------|
| Topic families + keywords | `GET /brands/{id}/families` |
| Raw evidence per family | `GET /brands/{id}/evidence` |
| Ranked opportunities | `GET /brands/{id}/opportunities` |
| Brand findings | `GET /brands/{id}/insights` |
| Unified action queue | `GET /brands/{id}/queue` |

<Card title="Signals & Opportunities" icon="lightbulb" href="/concepts/signals-and-opportunities">
  Deep dive into how signals are detected and scored into opportunities.
</Card>