🔧 API Reference

Integrate VoidSEO data in your own workflows — auth, endpoints, rate limits, and code examples

Base URL: https://api.voidseo.dev/v1
Format: JSON REST API
Auth: Bearer Token

Quick Start

1

Get Your API Key

Sign up for a free account to get your API key:

Get API Key
2

Make Your First Request

curl -X POST https://api.voidseo.dev/v1/paa/scrape \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keywords": ["seo tools"], "locale": "en-US"}'
3

Process the Response

{
  "status": "success",
  "data": {
    "clusters": [...],
    "total_questions": 45,
    "processing_time": "2.3s"
  }
}

Authentication

🔑 API Key Authentication

All API requests require authentication using your API key in the Authorization header as a Bearer token.

Header Format

Authorization: Bearer YOUR_API_KEY

Example Request

curl -H "Authorization: Bearer sk-void-..." \
     https://api.voidseo.dev/v1/paa/scrape

Getting Your API Key

  1. Sign up for a VoidSEO account
  2. Go to your dashboard
  3. Navigate to API Keys section
  4. Generate a new API key
🔒 Security Best Practices
  • Never expose API keys in client-side code
  • Use environment variables
  • Rotate keys regularly
  • Monitor usage in your dashboard

Endpoints

🔍 PAA Explorer API

POST /paa/scrape

Scrape People Also Ask questions for given keywords and return clustered results.

Request Body

{
  "keywords": ["seo tools", "keyword research"],
  "locale": "en-US",
  "max_questions": 10,
  "cluster_method": "auto"
}

Parameters

keywords
array
required
List of keywords to analyze (max 10)
locale
string
optional
Search locale (default: "en-US")
max_questions
integer
optional
Max questions per keyword (default: 10, max: 20)
cluster_method
string
optional
"auto", "kmeans", or "hierarchical" (default: "auto")

Response

{
  "status": "success",
  "data": {
    "clusters": [
      {
        "id": 1,
        "label": "SEO Tools Comparison",
        "questions": [
          "What are the best SEO tools?",
          "Free vs paid SEO tools",
          "SEO tools for beginners"
        ],
        "intent": "informational",
        "confidence": 0.87
      }
    ],
    "total_questions": 45,
    "total_clusters": 6,
    "processing_time": "2.3s"
  }
}

🤖 AI Overview Detector API

POST /ai-overview/detect

Check if queries trigger AI Overviews and analyze their impact on organic results.

Request Body

{
  "queries": ["best seo tools 2025", "technical seo audit"],
  "locale": "en-US",
  "include_screenshots": false
}

Response

{
  "status": "success",
  "data": {
    "results": [
      {
        "query": "best seo tools 2025",
        "ai_overview_detected": true,
        "position": 1,
        "content_sources": 3,
        "organic_results_pushed_down": true,
        "estimated_ctr_impact": -0.23
      }
    ],
    "detection_accuracy": 0.95,
    "timestamp": "2025-01-19T10:30:00Z"
  }
}

🔗 Keyword Clusterer API

POST /keywords/cluster Beta

Cluster keywords by semantic similarity and search intent using advanced embeddings.

🚧 Beta Endpoint

This endpoint is currently in beta. Contact support for access.

Rate Limits

📊 Current Rate Limits

Rate limits are applied per API key and reset every hour. Limits vary by subscription tier.

🆓 Free Tier

PAA Scraping 50 requests/hour
AI Overview Detection 25 requests/hour
Max keywords per request 5 keywords

💎 Builder Tier

PAA Scraping 500 requests/hour
AI Overview Detection 250 requests/hour
Max keywords per request 20 keywords

Rate Limit Headers

Every API response includes rate limit information in the headers:

X-RateLimit-Limit: 50
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1642680000

Error Handling

⚠️ Error Response Format

All errors follow a consistent JSON format with HTTP status codes and detailed error messages.

Standard Error Response

{
  "status": "error",
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or expired",
    "details": {
      "timestamp": "2025-01-19T10:30:00Z",
      "request_id": "req_abc123"
    }
  }
}

Common Error Codes

400
Bad Request
Invalid request parameters or malformed JSON
401
Unauthorized
Missing or invalid API key
429
Rate Limited
Too many requests, rate limit exceeded
500
Server Error
Internal server error, try again later

Code Examples

Python Example

import requests
import json

# VoidSEO API client
class VoidSEOClient:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = "https://api.voidseo.dev/v1"
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        }
    
    def scrape_paa(self, keywords, locale="en-US", max_questions=10):
        """Scrape PAA questions for keywords"""
        url = f"{self.base_url}/paa/scrape"
        data = {
            "keywords": keywords,
            "locale": locale,
            "max_questions": max_questions
        }
        
        response = requests.post(url, headers=self.headers, json=data)
        response.raise_for_status()
        return response.json()

# Usage
client = VoidSEOClient("your-api-key-here")
result = client.scrape_paa(["seo tools", "keyword research"])
print(f"Found {result['data']['total_questions']} questions in {result['data']['total_clusters']} clusters")

JavaScript Example

class VoidSEOClient {
    constructor(apiKey) {
        this.apiKey = apiKey;
        this.baseUrl = 'https://api.voidseo.dev/v1';
    }
    
    async scrapePAA(keywords, locale = 'en-US', maxQuestions = 10) {
        const response = await fetch(`${this.baseUrl}/paa/scrape`, {
            method: 'POST',
            headers: {
                'Authorization': `Bearer ${this.apiKey}`,
                'Content-Type': 'application/json'
            },
            body: JSON.stringify({
                keywords,
                locale,
                max_questions: maxQuestions
            })
        });
        
        if (!response.ok) {
            throw new Error(`API Error: ${response.status}`);
        }
        
        return await response.json();
    }
}

// Usage
const client = new VoidSEOClient('your-api-key-here');
client.scrapePAA(['seo tools', 'keyword research'])
    .then(result => {
        console.log(`Found ${result.data.total_questions} questions`);
    })
    .catch(error => {
        console.error('Error:', error);
    });

cURL Example

# PAA Scraping
curl -X POST https://api.voidseo.dev/v1/paa/scrape \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keywords": ["seo tools", "keyword research"],
    "locale": "en-US",
    "max_questions": 10
  }'

# AI Overview Detection
curl -X POST https://api.voidseo.dev/v1/ai-overview/detect \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": ["best seo tools 2025"],
    "locale": "en-US"
  }'

SDKs & Libraries

🐍

Python SDK

Official Python library with full API coverage and type hints.

pip install voidseo
View on GitHub
📦

Node.js SDK

TypeScript-first Node.js library for seamless integration.

npm install @voidseo/sdk
View on GitHub
🔷

Go SDK

High-performance Go library for enterprise applications.

Coming Soon
Q2 2025