RankForge API Documentation & Testing

Overview

RankForge is a production-ready API-only service that generates 5,000-6,000 word SEO + AEO + GEO optimized articles in ≤5 minutes that rank #1 on Google.

Architecture

The system uses a two-step asynchronous process:

1. Client calls POST /api/v1/generate to queue a job.
2. QStash delivers the job to POST /api/internal/process-job for processing.
3. Client polls GET /api/v1/jobs/[id] for status and results.

graph TD
    A[Client POST /api/v1/generate] --> B[Validate Input & Rate Limit]
    B --> C[Create Job in Supabase]
    C --> D[Enqueue to QStash]
    D --> E[Return 202 + jobId]

    Q[QStash Delivers] --> F[POST /api/internal/process-job]
    F --> G[Run Pipeline Orchestrator]
    G --> H[Phase 1: SERP DataForSEO]
    H --> I[Phase 2: Crawl Bright Data]
    I --> J[Phase 3: N-grams Analysis]
    J --> K[Phase 4: Brief Gemini Flash]
    K --> L[Phase 5: Write Sections Parallel]
    L --> M[Phase 6: Fetch Images Parallel]
    M --> N[Phase 7: Internal Links]
    N --> O[Phase 8: Assemble HTML]
    O --> P[Phase 9: QA Validation]
    P --> Q[Phase 10: Finalize & Store]
    Q --> R[Update Supabase Status/Result]

    S[Client GET /api/v1/jobs/[id]] --> T[Fetch Status/Progress/Result from Supabase]

    U[External APIs: DataForSEO, Bright Data, Gemini] -.-> G
    V[Cache: Redis] -.-> G
    W[DB: Supabase] -.-> C
    W -.-> R
    W -.-> T
    X[Storage: Supabase Bucket] -.-> Q

Note: You will need a Mermaid diagram renderer to see the above graph.

Endpoints

POST /api/v1/generate

Queues a new article generation job.

Response (202 Accepted):

{
  "jobId": "uuid",
  "status": "queued",
  "message": "Job queued for processing. Poll /api/v1/jobs/{jobId} for status.",
  "estimatedCompletionTime": "YYYY-MM-DDTHH:mm:ss.sssZ"
}

GET /api/v1/jobs/[id]

Gets the status and progress of a job.

Response (200 OK):

{
  "jobId": "uuid",
  "status": "completed",
  "progress": 100,
  "createdAt": "YYYY-MM-DDTHH:mm:ss.sssZ",
  "updatedAt": "YYYY-MM-DDTHH:mm:ss.sssZ",
  "completedAt": "YYYY-MM-DDTHH:mm:ss.sssZ"
}

GET /api/v1/jobs/[id]/result

Gets the result of a completed job.

Response (200 OK):

{
  "jobId": "uuid",
  "result": {
    // Full GeneratedArticle object
  },
  "completedAt": "YYYY-MM-DDTHH:mm:ss.sssZ"
}

API Field Reference (Request)

The API has 22 strictly required fields (validation fails without them), 14 fields with defaults (optional to provide), and ~11 purely optional fields.

Required Fields (22 fields - must be provided)

Fields with Defaults (14 fields - optional to provide)

Purely Optional Fields (~11 fields)

cURL Examples

Minimal Request (Required Fields Only)

curl -X POST https://your-domain.com/api/v1/generate \
 -H "Content-Type: application/json" \
 -d '{
   "session_id": "your-session-id",
   "primaryKeyword": "your keyword",
   "wordCount": 5000,
   "contentType": "guide",
   "tone": "professional",
   "targetAudience": "business owners",
   "readingLevel": "college",
   "targetSearchIntent": "informational",
   "language": "en",
   "target_country": "US",
   "DataForSEO_Location_Code": "2840",
   "DataForSEO_Language_Code": "en",
   "client_name": "Your Company",
   "client_website": "https://yourcompany.com",
   "client_description": "Your company description",
   "client_icp": "Your ideal customer profile",
   "author_name": "John Doe",
   "author_title": "SEO Specialist",
   "numImages": 5,
   "tocPlacement": "top",
   "schemaType": "Article",
   "brandColor": "#007bff",
   "sitemapURL": "https://yourcompany.com/sitemap.xml",
   "blogRootURL": "https://yourcompany.com/blog"
 }'

Full Request (All Optional Fields)

curl -X POST https://your-domain.com/api/v1/generate \
 -H "Content-Type: application/json" \
 -d '{
   "session_id": "your-session-id",
   "primaryKeyword": "your keyword",
   "seedKeyword": "secondary keyword",
   "longTailKeyword": "long tail keyword",
   "focusKeyphrases": ["keyphrase1", "keyphrase2"],
   "subTopics": ["topic1", "topic2"],
   "wordCount": 5000,
   "contentType": "guide",
   "tone": "professional",
   "targetAudience": "business owners",
   "readingLevel": "college",
   "targetSearchIntent": "informational",
   "language": "en",
   "target_country": "US",
   "DataForSEO_Location_Code": "2840",
   "DataForSEO_Language_Code": "en",
   "client_name": "Your Company",
   "client_website": "https://yourcompany.com",
   "client_description": "Your company description",
   "client_icp": "Your ideal customer profile",
   "author_name": "John Doe",
   "author_title": "SEO Specialist",
   "author_bio": "Author bio",
   "author_credentials": "PhD in Marketing",
   "numImages": 5,
   "imageStyle": "professional",
   "addInfographics": true,
   "includeFaq": true,
   "includeTables": true,
   "includeStatistics": true,
   "includeExpertQuotes": true,
   "includeReferences": true,
   "addYoutubeVideo": true,
   "youtubeVideoUrl": "https://youtube.com/watch?v=123",
   "youtubeSearchQuery": "your search",
   "youtubeVideoCount": 2,
   "addEmojis": true,
   "emojiDensity": "moderate",
   "addCTA": true,
   "ctaText": "Contact Us",
   "ctaUrl": "https://yourcompany.com/contact",
   "ctaPlacement": "bottom",
   "addExternalLink": true,
   "externalLinksCount": 3,
   "externalLinkDomains": ["example.com"],
   "externalLink": "https://example.com",
   "internalLinksNumber": 5,
   "tocPlacement": "top",
   "mustIncludeSections": ["Introduction", "Conclusion"],
   "excludeTopics": ["topic to avoid"],
   "schemaType": "Article",
   "metaDescriptionGuidelines": "Meta description instructions",
   "aeo": {
     "enableAIOBox": true,
     "faqCount": 5
   },
   "brandColor": "#007bff",
   "sitemapURL": "https://yourcompany.com/sitemap.xml",
   "blogRootURL": "https://yourcompany.com/blog",
   "globalArticleInstructions": "General instructions",
   "bestArticleExampleOne": "https://example.com/article1",
   "bestArticleExampleTwo": "https://example.com/article2",
   "bestArticleExampleThree": "https://example.com/article3",
   "competitorUrls": ["https://competitor.com"]
 }'

🚀 v2 Pipeline — POST /api/v2/generate

The v2 endpoint uses a 4-Burst Parallel Architecture that generates articles in ~2.5-3.5 minutes (vs v1's ~5-6 min). It accepts the same payload as v1 plus additional fields for EEAT, GEO, and advanced schema optimization. The Get Status tab works for both v1 and v2 jobs — they use the same Supabase job storage.

v2 Architecture: 4-Burst Pipeline

v2-Only Fields (all optional with defaults)

v1 vs v2 Comparison