# RankHub — Complete Platform Documentation

> RankHub is an SEO autopilot platform that researches keywords, generates optimized blog articles, and publishes them to your website via webhook. This document contains the complete v1.0 specification.

## Platform Overview

RankHub automates the entire SEO content pipeline:
1. Keyword Research — AI + DataForSEO powered keyword discovery and scoring
2. Content Calendar — Monthly scheduling based on subscription tier
3. Headline Generation — AI generates SEO-optimized headlines from your keyword pool
4. Your Approval — Email-based approval with 5-day window (or auto-approval)
5. Draft Generation — Full article with featured image, internal links, and HTML formatting
6. Publish & Deliver — Webhook delivery to your endpoint with retry logic

## SEO Autopilot Pipeline

### Monthly Cycle
- Calendar generated 10 days before each month ends
- Headlines created immediately after calendar generation
- Approval email sent with secure token (5-day deadline)
- Drafts generated 1 day before scheduled publish date
- Publishing check runs hourly; articles delivered via webhook

### Content Calendar
- Starter: 4 posts/month (every 7 days)
- Growth: 15 posts/month (every 2 days)
- Scale: 30 posts/month (daily)
- Configurable publish day (Monday through Sunday)

### Headline Approval
- Email with secure approval link
- Select/deselect individual headlines
- Shows: headline, target keyword, search intent, scheduled date, rationale
- Auto-approval mode available (skips email, immediate queue)
- Expired approvals (>5 days) are not generated

### Semantic Safety
- Pre-publish similarity check using vector embeddings
- Articles with >90% similarity to existing content flagged for review
- Prevents duplicate or near-duplicate content publishing

## Article Types

10 article types, auto-selected based on search intent:

| Type | Pattern | Intent | Pillar |
|------|---------|--------|--------|
| HOW_TO | How to [Goal] with [Method] | Informational | No |
| LISTICLE | [N] Ways/Tips to [Goal] | Informational | No |
| ULTIMATE_GUIDE | The Ultimate Guide to [Topic] | Informational | Yes |
| COMPARISON | [A] vs [B]: [Key Factor] | Commercial | No |
| BEST_OF | Best [Solutions] for [Audience] | Commercial | No |
| PROBLEM_SOLUTION | Why [Problem] and How to Fix It | Informational | No |
| CASE_STUDY | How [Entity] Achieved [Result] | Commercial | No |
| EXPERT_TIPS | [N] Expert Tips for [Goal] | Informational | No |
| BEGINNERS_GUIDE | [Topic] for Beginners | Informational | Yes |
| ALTERNATIVES | [Competitor] Alternatives | Commercial | No |

Pillar content (ULTIMATE_GUIDE, BEGINNERS_GUIDE): 1-2 per month, comprehensive hub pages.

## Content Settings

Configurable per website in Settings > Content:

- Article Style: informative, conversational, professional, technical
- Image Style: brand-text, textured-illustration, editorial, minimal-typography
- Internal Links: 0-10 per article (default: 3)
- Brand Color: hex color for featured image text overlays
- Call to Action: include CTA section (default: on)
- YouTube Videos: embed relevant videos (default: off)
- Infographics: generate inline visuals (default: off)
- Emojis: use emojis in content (default: off)
- Global Instructions: free-text instructions applied to every article

## Webhook Integration

### Role
You are helping integrate RankHub webhooks into a web application.

### Context
RankHub sends an HTTP POST request to a configured webhook endpoint whenever a new article is published. The endpoint must verify authentication before processing.

IMPORTANT: Ask the developer what framework/language/CMS they are using before generating code.

### HTTP Headers
- Content-Type: application/json
- Authorization: Bearer <AUTH_TOKEN>
- X-RankHub-Delivery-Id: <unique_delivery_id>

### JSON Payload

```json
{
  "api_version": 1,
  "id": "string (unique post ID, CUID format)",
  "title": "string (article title)",
  "slug": "string (URL-safe, generated from target keyword)",
  "content_html": "string (sanitized HTML with semantic tags)",
  "content_markdown": "string (original markdown source)",
  "meta_description": "string (SEO meta description)",
  "image_url": "string (featured image URL)",
  "css_url": "string (URL to full stylesheet with layout + visual design)",
  "css_base_url": "string (URL to structural-only stylesheet — layout only, no colors/fonts)",
  "tags": ["string (topic tags)"],
  "created_at": "string (ISO 8601 timestamp)",
  "target_keyword": "string (primary SEO keyword)",
  "word_count": "integer",
  "reading_time": "integer (minutes, based on 200 wpm)",
  "schema_json": "array (JSON-LD structured data for BlogPosting rich results)"
}
```

### Task
Build an endpoint AND a blog display page:

#### 1. Webhook endpoint
- Receives POST requests from RankHub
- Verifies the Authorization Bearer token matches the AUTH_TOKEN environment variable
- Creates or updates a blog post in the CMS/database using the payload fields
- Returns HTTP 200 on success

#### 2. Blog article page
- Renders content_html inside a container with class="blog-prose"
- Loads the RankHub stylesheet (REQUIRED for rich components to display correctly)
- Renders image_url as the featured/hero image (handle empty string — hide if empty)
- Injects schema_json as a <script type="application/ld+json"> tag for SEO

### Styling (IMPORTANT)
The content_html includes rich components (callouts, comparison tables, stat highlights, pros/cons, step guides, data bars, checklists, and more) with rh-* CSS class prefixes. These REQUIRE the RankHub stylesheet to render correctly.

Add to the blog layout <head>:

Option A — Full design (layout + colors + fonts):
<link rel="stylesheet" href="https://rankhub.ai/api/blog-spec/styles.css" />

Option B — Structural only (layout only, add your own brand styling):
<link rel="stylesheet" href="https://rankhub.ai/api/blog-spec/styles-base.css" />

Then wrap the article content in: <div class="blog-prose">content_html here</div>

### Constraints
- Verify the Bearer token before processing
- Return 200 quickly — do heavy processing async if needed
- 5xx/429 responses trigger retries (up to 5, exponential backoff, ~51 min window)
- 4xx responses (except 429) are NOT retried — fix configuration errors
- Handle empty image_url gracefully (don't render a broken <img> tag)

## Authentication

Verify the Bearer token in the Authorization header matches the stored auth token. Return 401 if it does not match.

## Retry Behavior

- **2xx**: Success. No retry.
- **429**: Rate limited. Retried up to 5 times.
- **5xx**: Server error. Retried up to 5 times.
- **4xx (except 429)**: Client error. Not retried.
- **Backoff**: 1min, 5min, 15min, 30min, 30min (with +/-10% jitter)
- **Total window**: ~51 minutes

## Allowed HTML Tags in content_html

h2, h3, p, div, blockquote, ul, ol, li, table, thead, tbody, tr, th, td, figure, figcaption, hr, br, a, strong, em, span, small, cite, img, iframe, dl, dt, dd, caption, article, section, aside

Note: h1 tags are auto-converted to h2.

## Code Example (JavaScript/Express)

```javascript
const express = require('express')
const app = express()

app.post('/webhook/rankhub', express.json(), (req, res) => {
  // 1. Verify Bearer token
  const token = req.headers.authorization?.replace('Bearer ', '')
  if (token !== process.env.RANKHUB_AUTH_TOKEN) {
    return res.status(401).json({ error: 'Unauthorized' })
  }

  // 2. Use the payload
  const { title, slug, content_html, meta_description, image_url, tags } = req.body
  // Create your blog post here...

  res.status(200).json({ received: true })
})
```

## Subscription Plans

| Tier | Price | Posts/Month | Cadence | Trial |
|------|-------|-------------|---------|-------|
| Starter | $19.99/mo | 4 | Weekly | Free 7-day trial (card required, $0 today) |
| Growth | $49.99/mo | 15 | Every 2 days | Free 7-day trial (card required, $0 today) |
| Scale | $99.99/mo | 30 | Daily | Free 7-day trial (card required, $0 today) |

All tiers include: AI headline generation, email approval workflow, draft generation, featured image creation, webhook delivery.
Growth and Scale add: priority content queue.
Scale adds: dedicated support.

A 50% early-bird discount (applied at checkout, recurring forever) may be active — see https://rankhub.ai/#pricing for live pricing.

## Google Search Console Integration

- OAuth with read-only scope (webmasters.readonly)
- Daily sync of search performance data (clicks, impressions, CTR, position)
- Data used to optimize keyword selection and track published article performance
- Connect via Settings > Connections

## Credits & Usage

Credits are used for on-demand features outside the autopilot subscription:
- Website Analysis: AI analysis during onboarding
- Keyword Research: Manual or auto research with metrics
- On-demand Content Generation: Blog drafts outside autopilot schedule
- Competitor Analysis: Deep keyword gap analysis

Autopilot content (drafts, images, publishing) is included in the subscription.

## Full Interactive Documentation

For interactive documentation with code examples in 5 languages, payload reference tables, article type details, content settings, and a copy-paste AI prompt for instant setup, visit: https://rankhub.ai/docs