API Reference
Complete API documentation for all HeadlessX endpoints
by saifyxpro
HeadlessX provides RESTful APIs for website scraping and search result extraction. All endpoints require API key authentication.
Authentication
Include your API key in the X-API-Key header:
Generate API Key
- Open Dashboard at http://localhost:3000
- Navigate to Settings → API Keys
- Click Generate New Key
- Copy and store securely
Website Scraping APIs
Get Raw HTML
Extract HTML without JavaScript execution (fastest method).
Endpoint: POST /api/website/html
Request Body:
Response:
Get HTML with JavaScript
Extract HTML after JavaScript execution and rendering.
Endpoint: POST /api/website/html-js
Request Body:
Response:
Get Markdown Content
Extract clean markdown content (great for LLMs and RAG).
Endpoint: POST /api/website/content
Request Body:
Response:
Capture Screenshot
Take full-page or viewport screenshots.
Endpoint: POST /api/website/screenshot
Request Body:
Response:
Real-time Stream (SSE)
Stream scraping progress in real-time via Server-Sent Events.
Endpoint: POST /api/website/stream
Request Body:
Response (SSE Stream):
JavaScript Example:
Google SERP APIs
Extract Search Results
Extract Google search results with zero detection.
Endpoint: POST /api/google-serp/search
Request Body:
Response:
Real-time SERP Stream
Stream Google SERP scraping progress.
Endpoint: GET /api/google-serp/stream?query=your+query
Query Parameters:
query(required): Search querylocation: Location (e.g., "United States")language: Language code (e.g., "en")numResults: Number of results (1-100)
Response (SSE Stream):
Configuration API
Get Configuration
Endpoint: GET /api/config
Response:
Update Configuration
Endpoint: PUT /api/config
Request Body:
Error Responses
All endpoints return consistent error format:
Common Error Codes
| Code | Description |
|---|---|
INVALID_URL | URL format is invalid |
TIMEOUT_ERROR | Request exceeded timeout |
NETWORK_ERROR | Network connection failed |
AUTH_ERROR | Invalid or missing API key |
CAPTCHA_DETECTED | CAPTCHA blocking access |
SERVER_ERROR | Internal server error |
Next Steps
- Integration Examples - Code examples in multiple languages
- N8N Integration - Use with N8N workflows
- Zapier Integration - Automate with Zapier