# BrightBean YouTube Intelligence, Full API Documentation

> Packaging scoring (titles + thumbnails), video hook analysis, content gap research, and channel/video benchmarks, delivered via REST API and MCP server.

BrightBean is a marketing platform built around a shared company "brain" (https://brightbean.xyz). This document covers one of its products: **YouTube Intelligence** (https://brightbean.xyz/intelligence/), the intelligence layer for YouTube that vidIQ and TubeBuddy never built. It provides structured, actionable data via REST API and MCP server, designed for AI agents, agencies, and SaaS tools that need programmatic access to YouTube optimization intelligence.

For the platform itself, the brain, composing, scheduling, publishing to 10 social networks and 11 blog/CMS connectors, and analytics feeding back into the brain, see https://brightbean.xyz/features/ and sign up at https://platform.brightbean.xyz/signup.

## Getting Started

### Authentication

All API requests require a Bearer token:

```
Authorization: Bearer bb_YOUR_API_KEY
```

Base URL: `https://api.brightbean.xyz/v1`

### Python SDK

```python
# Install
pip install brightbean

# Initialize
from brightbean import BrightBean
client = BrightBean(api_key="bb_YOUR_API_KEY")
```

### MCP Server

Add to your MCP configuration (Claude Desktop, Cursor, Claude Code, etc.):

```json
{
  "mcpServers": {
    "brightbean": {
      "url": "https://api.brightbean.xyz/mcp",
      "headers": {
        "Authorization": "Bearer bb_YOUR_API_KEY"
      }
    }
  }
}
```

The MCP server exposes all six endpoints as tools that any MCP-compatible AI agent can call directly.

---

## API Endpoints

### 1. GET /v1/research/content-gaps

Find underserved YouTube topics with high search demand and low supply of quality videos.

**Use case:** Content planning, editorial calendars, niche research.

**Request:**

```
GET /v1/research/content-gaps?niche=tech-tutorials&limit=10&min_score=50
```

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| niche | string | yes | Niche slug from `/v1/research/niches` |
| gap_type | array | no | Subset of `["underserved", "stale", "competitive"]` (default `["underserved", "stale"]`) |
| limit | integer | no | Max results (1–50, default 20) |
| min_score | integer | no | Minimum opportunity score filter (0–100) |

**Response:**

```json
{
  "niche": { "slug": "tech-tutorials", "name": "Tech Tutorials" },
  "gaps": [
    {
      "topic": "VS Code extensions for Rust beginners",
      "opportunity_score": 87,
      "gap_type": "underserved",
      "demand": 0.81,
      "supply": 0.22,
      "recency": 0.74,
      "explanation": "High searcher intent with few quality recent videos.",
      "suggested_angles": ["5 must-have extensions", "Rust + VS Code setup walkthrough"],
      "evidence": []
    }
  ]
}
```

---

### 2. GET /v1/research/niches

List all catalogued YouTube niches for the active research run. Returns slugs to use as the `niche` argument for `/v1/research/content-gaps`.

**Use case:** Niche discovery, slug lookup.

**Request:**

```
GET /v1/research/niches
```

**Response:**

```json
{
  "niches": [
    { "slug": "tech-tutorials", "name": "Tech Tutorials", "gap_count": 42 },
    { "slug": "tech-reviews", "name": "Tech Reviews", "gap_count": 31 }
  ]
}
```

---

### 3. POST /v1/score/packaging

Score a YouTube title and/or thumbnail for click-through potential. Provide at least one of `title`, `thumbnail_url`, or `thumbnail_base64`.

**Use case:** Title and thumbnail optimization, A/B test candidate scoring.

**Request:**

```json
POST /v1/score/packaging
{
  "title": "10 Tips to Boost Your Coding Productivity",
  "thumbnail_url": "https://i.ytimg.com/vi/abc123/maxresdefault.jpg"
}
```

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| title | string (≤250) | one of | Video title |
| thumbnail_url | url (≤1024) | one of | Public JPG/PNG/WebP image URL |
| thumbnail_base64 | string (≤12.5 MB) | one of | Base64-encoded image |

**Response:**

```json
{
  "score": 0.81,
  "percentile": 81,
  "raw_score": 1.42,
  "mode": "combined",
  "niche_slug": "tech-tutorials",
  "niche_label": "Tech Tutorials",
  "niche_confidence": 0.93
}
```

---

### 4. POST /v1/score/video-hook

Classify and score the opening of a YouTube video. Transcript and visual summary are extracted automatically from the URL.

**Use case:** Hook optimization, retention analysis, content coaching.

**Request:**

```json
POST /v1/score/video-hook
{
  "youtube_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}
```

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| youtube_url | url | yes | Public YouTube URL (watch, youtu.be, /shorts/, /embed/) |

**Response:**

```json
{
  "primary_archetype": "contrarian_claim",
  "secondary_archetype": "story_open",
  "scores": { "clarity": 0.82, "specificity": 0.71, "tension": 0.66, "visual_energy": 0.58, "pace": 0.74 },
  "overall_score": 0.71,
  "transcript": "...",
  "visual_summary": "...",
  "strengths": [],
  "weaknesses": [],
  "suggestions": [],
  "delta_vs_niche_top": -0.12,
  "key_differences_vs_top": []
}
```

---

### 5. POST /v1/benchmark/channel

Benchmark a YouTube channel against its niche. Returns engagement percentiles, niche match, and a sampled window.

**Use case:** Competitive analysis, channel audits, niche fit.

**Request:**

```json
POST /v1/benchmark/channel
{
  "url": "https://www.youtube.com/@MarquesBrownlee"
}
```

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| url | string (≤1024) | yes | Channel URL or @handle |

**Response:**

```json
{
  "payload": {
    "channel": { "id": "...", "title": "...", "subscriber_count": 0, "video_count": 0 },
    "engagement_percentiles": { "view_to_sub": 0.71, "like_to_view": 0.55, "comment_to_view": 0.42, "overall": 0.62 },
    "niche": { "slug": "tech-reviews", "name": "Tech Reviews", "match_score": 0.91, "match_strength": "strong" },
    "sample_window_days": 90
  }
}
```

---

### 6. POST /v1/benchmark/video

Benchmark a single YouTube video against its niche. Returns engagement percentiles, title pattern analysis, and niche match.

**Use case:** Post-publish performance assessment, niche fit per video.

**Request:**

```json
POST /v1/benchmark/video
{
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}
```

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| url | string (≤1024) | yes | Public YouTube video URL (watch, youtu.be, /shorts/, /embed/) |

**Response:**

```json
{
  "payload": {
    "video": { "id": "...", "title": "...", "channel": {}, "views": 0, "likes": 0, "comments": 0 },
    "engagement_percentiles": {},
    "title_patterns": [],
    "niche": { "slug": "tech-tutorials", "name": "Tech Tutorials", "match_strength": "strong" }
  }
}
```

---

## Pricing

| Plan | Price | API Calls/Month | Support | Best For |
|------|-------|-----------------|---------|----------|
| Free | $0/month | 500 | Community | Testing and personal projects |
| Hobby | $19/month | 3,000 | Community | Side projects and indie creators |
| Standard | $99/month | 100,000 | Priority + Webhooks | Agencies and power users |
| Growth | $399/month | 500,000 | Dedicated + Custom models + Volume SLA | SaaS tools and high-volume platforms |

All plans include access to every endpoint and the MCP server. No credit card required for the Free tier.

---

## Who It's For

- **AI Agent Developers:** Give your content planning agent or video optimization workflow structured YouTube intelligence it can act on.
- **Agencies:** Scale creative decisions (titles, thumbnails, content calendars) across multiple YouTube channels and niches.
- **YouTube SaaS Tools:** Embed optimization intelligence into your scheduling tool, analytics dashboard, or creator CRM without building a scoring engine from scratch.

## Rate Limits

Rate limits are per API key, per minute:

| Plan | Requests/Minute |
|------|----------------|
| Free | 10 |
| Hobby | 30 |
| Standard | 300 |
| Growth | 1,000 |

## Error Codes

| Code | Description |
|------|-------------|
| 400 | Bad request, check required parameters |
| 401 | Unauthorized, invalid or missing API key |
| 402 | Payment Required, out of credits |
| 403 | Forbidden, key lacks endpoint permission |
| 429 | Rate limit exceeded, wait and retry |
| 500 | Internal server error, contact support |

## Links

- Website: https://brightbean.xyz
- YouTube Intelligence: https://brightbean.xyz/intelligence/
- Platform: https://platform.brightbean.xyz
- API Docs: https://brightbean.xyz/intelligence-docs/
- Blog: https://brightbean.xyz/blog/
- GitHub: https://github.com/brightbeanxyz
- Support: support@brightbean.xyz