API Reference

Programmatic access to VELRA GEO. Available on Agency and Enterprise plans.

Authentication

All API requests require an API key in the header:

Authorization: Bearer vg_live_xxxxxxxxxxxx

Generate keys in Dashboard → Settings → API Keys.

Base URL

https://api.velrageo.com/v1

Rate Limits

Agency: 100 requests/hour
Enterprise: 1,000 requests/hour

Rate limit headers returned: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Endpoints: Scans

POST /external/scan

Start a new scan.

// Request
{
  "url": "https://example.com",
  "project_id": "proj_xxx"
}

// Response
{
  "scan_id": "scan_xxx",
  "status": "PENDING"
}

GET /external/scan/{scan_id}/status

Check scan progress.

{
  "status": "CRAWLING",
  "total_pages": 45,
  "progress_pct": 60
}

Endpoints: Scores

GET /external/scores/{scan_id}

{
  "total": 52.3,
  "tech": 71.0,
  "content": 45.0,
  "ai_readiness": 32.0,
  "trust": 55.0,
  "ux": 62.0,
  "grade": "D"
}

Endpoints: Fixes

GET /external/fixes/{scan_id}

{
  "total": 23,
  "items": [
    {
      "module": "A1",
      "priority": "CRITICAL",
      "title": "robots.txt blocks GPTBot",
      "fix_code": "..."
    }
  ]
}

Endpoints: Visibility

GET /external/visibility/{project_id}

{
  "mention_rate": 0.34,
  "engines": {
    "chatgpt": 0.4,
    "perplexity": 0.2,
    "google_aio": 0.35
  }
}

Endpoints: Export

GET /external/export/{scan_id}?format=json

Formats: json, csv

MCP Server (Enterprise)

WebSocket endpoint for AI agent integration:

wss://mcp.velrageo.com

Tools exposed: velrageo_scan, velrageo_score, velrageo_fixes, velrageo_visibility.

Allows Claude, ChatGPT, and other AI agents to query VELRA GEO data directly.

Error Codes

401: Invalid or missing API key
403: Feature not available on your plan
404: Resource not found
429: Rate limit exceeded
500: Internal server error