Programmatic access to HubSEO technical crawls, AI search readiness, and webhook event streams.

The HubSEO REST API (v1) enables developers, CLI pipelines, and AI coding agents (Cursor, Claude Code, Copilot, Codex, Aider) to trigger technical audits, inspect Core Web Vitals diagnostics, and stream real-time ranking events.

Base URL: https://hubseo.dev/api/v1
OpenAPI 3.1 Spec: https://hubseo.dev/api/v1/openapi.json
Developer Portal: hubseo.dev/dashboard/developers

Interactive API Explorer

Queue a live technical audit programmatically, inspect request format, and review the JSON response telemetry:

POST/api/v1/audits

200 OK · 142ms

Queue Headless SEO & CWV Audit

Executes a live SSRF-safe crawl with Lighthouse lab metrics and Core Web Vitals diagnostics.

curl -X POST "https://hubseo.dev/api/v1/audits" \
  -H "Authorization: Bearer hub_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "device": "mobile",
    "generate_fix_packs": true,
    "verify_ssl": true
  }'

Authentication

Every API request must include a secret API key via the standard Authorization or X-API-Key HTTP headers:

Authorization: Bearer hub_live_YOUR_API_KEY

X-API-Key: hub_live_YOUR_API_KEY

Zero Plaintext Storage

HubSEO generates 24-byte cryptographically secure keys with a hub_live_ or hub_test_ prefix. Only the SHA-256 hash of each key is stored in PostgreSQL. Raw keys are shown exactly once in the Developer Portal and cannot be recovered if misplaced.

Scopes and Permissions

API keys can be scoped to limit access across individual subsystems. Choose scopes when you create a key in Dashboard → Developers:

Scope	Description
`projects:read`	List your projects (sites) and their ids, which other endpoints take
`audits:read`	Retrieve completed audit reports, CWV metrics, and ranked issues
`audits:write`	Queue on-demand technical audits and Lighthouse lab crawls
`site-health:read`	Read Site Health runs, results and history
`site-health:write`	Start Site Health crawls for your sites (must be granted explicitly)
`geo:read`	Query Generative Engine Optimization (GEO) brand visibility and citation rate
`backlinks:read`	Query live referring domain graphs and authority scores
`webhooks:manage`	Create, configure, and ping webhook endpoint subscriptions

These scopes are used by the API but can't yet be chosen for new keys: keywords:read, experiments:read and experiments:write.

Rate Limits

Rate limits are enforced per API key using a sliding 60-second window:

Plan Tier	Rate Limit	Burst Allowance
Free / Starter	60 req / min	10 req / sec
Growth Pro	120 req / min	20 req / sec
Agency Team	600 req / min	50 req / sec

When a key exceeds its limit, the 429 response includes:

X-RateLimit-Limit: Maximum permitted requests in the current window.
X-RateLimit-Remaining: Remaining allowance in the current window.
X-RateLimit-Reset: Seconds until the window resets.
Retry-After: Seconds to wait before retrying.

Errors and Response Format

All responses follow the RFC 7807 JSON error specification:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key provided.",
    "request_id": "req_01j7x9k1m2n3p4q5r6s7t8u9v0"
  }
}

API Subsystems

Crawl Lab

Audits API

Trigger headless crawls and inspect Core Web Vitals telemetry.

Search Console

Keywords & Rankings

Query live Google Search Console query rankings and movement deltas.

Async runs

Site Health

Crawl a site, then read page health, dead links and a score.

Domains

Projects API

List workspace projects and connected search domain endpoints.

DiD Causal

Experiments API

Evaluate controlled Difference-in-Differences growth experiments.

Perplexity/GPT

AI Visibility (GEO)

Query generative search engine citation frequency and brand share.

HMAC Stream

Webhooks

Stream signed HMAC-SHA256 event notifications into your backend.

REST API Overview