API Reference

Not available yet: API keys cannot be issued today, so the REST API and MCP server described here are not reachable by customers. This page documents the intended interface.

Programmatic access to Kenvada GEO. Planned for 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}

{
  "status": "observed",
  "source": { "key": "google_serp", "label": "Google Search (AI Overview + organic)" },
  "methodology_version": "brand-mention-v1",
  "overall_mention_rate": 34.0,
  "by_engine": {
    "google_serp": { "engine_label": "Google Search (AI Overview + organic)", "mention_rate": 34.0, "status": "observed" }
  }
}

overall_mention_rate is null when nothing was observed (status: unavailable). Rows recorded before 2026-09-17 may be keyed chatgpt / perplexity / google_aio; each was this same Google Search observation and is labelled as such on read.

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 Kenvada 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