COVEN AI Developer API

Health check endpoint. Returns current API status and version.

Response

List all available audit products with pricing information.

Response

Scan any URL across 7 dimensions — SEO, speed, security, accessibility, mobile, content, and conversion. Returns scores, issues, and passes for each dimension.

Parameters

Request

Response

Place a full AI audit order. The audit is generated asynchronously and delivered via webhook or polling.

Body Parameters

Request

Response

Check the status of an existing audit order. Poll until status is delivered.

Request

Response (when delivered)

Register a site for ongoing monitoring. The site will be scanned on your plan's schedule (daily or weekly) and you'll receive alerts when scores change.

Request

{
  "url": "https://example.com",     // required
  "label": "Client site",           // optional — display name
  "webhook_url": "https://...",     // optional — Growth/Agency only
  "alert_threshold": 10             // optional — points drop to trigger alert (default: 10)
}

Response 201

{
  "id": 42,
  "url": "https://example.com",
  "label": "Client site",
  "status": "active",
  "siteType": "own",
  "nextScanDueAt": 1743200000
}

List all active sites on your subscription, with quota info.

Response 200

{
  "sites": [
    {
      "id": 42,
      "url": "https://example.com",
      "label": "Client site",
      "status": "active",
      "siteType": "own",
      "lastScannedAt": 1743200000,
      "nextScanDueAt": 1743286400
    }
  ],
  "subscription": {
    "tier": "growth",
    "siteQuota": 5,
    "status": "active"
  }
}

Get the most recent scan result for a site, including all 7 dimension scores.

Response 200

{
  "id": 7,
  "siteId": 42,
  "overallScore": 74,
  "dimensionScores": {
    "seo": 80, "speed": 65, "copy": 78,
    "social": 70, "local": 45, "competitor": 82, "ai": 90
  },
  "issues": ["Missing meta description on /pricing", "No alt text on hero image"],
  "scannedAt": 1743200000
}

Side-by-side score comparison between your site and all tracked competitors.

Response 200

{
  "own": {
    "id": 42,
    "url": "https://yoursite.com",
    "label": "Your site",
    "latestScan": { "overallScore": 74, "dimensionScores": { ... } }
  },
  "competitors": [
    {
      "id": 43,
      "url": "https://competitor.com",
      "label": "Competitor A",
      "latestScan": { "overallScore": 68, "dimensionScores": { ... } }
    }
  ]
}

Add a competitor URL to track. Competitors are scanned on the same schedule as your own sites but never trigger alerts — they're intelligence only. Counts toward your site quota.

Request

{
  "url": "https://competitor.com",
  "label": "Competitor A"
}

Response 201

{
  "id": 43,
  "url": "https://competitor.com",
  "label": "Competitor A",
  "siteType": "competitor",
  "status": "active"
}

Webhook Alerts

Growth and Agency plans can register a webhook_url per site. When a score drops by more than your alert threshold, COVEN POSTs to that URL within minutes of the scan completing.

Payload

POST https://yourapp.com/webhook
Content-Type: application/json
X-Coven-Event: monitoring.alert

{
  "event": "monitoring.alert",
  "site": "https://example.com",
  "alert_type": "score_drop",      // score_drop | dimension_drop | site_down | recovered
  "dimension": null,               // populated for dimension_drop events
  "previous_score": 74,
  "current_score": 61,
  "delta": -13,
  "message": "Overall score dropped by 13 points (74 → 61)",
  "scanned_at": "2026-03-29T08:00:00.000Z"
}

Respond with any 2xx status to acknowledge. Failed deliveries are not retried.

curl https://coven-mission-control-production.up.railway.app/api/v1/geo/sites/1/check \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "url": "https://yoursite.com",
  "overallScore": 84,
  "maxScore": 85,
  "grade": "A",
  "summary": "Strong GEO profile — 6/6 signals passing.",
  "signals": [
    { "id": "crawlers", "name": "AI Crawler Access", "status": "pass",
      "score": 20, "maxScore": 20,
      "detail": "GPTBot, ClaudeBot, and PerplexityBot can crawl this site." },
    { "id": "llmstxt", "name": "llms.txt", "status": "pass",
      "score": 15, "maxScore": 15,
      "detail": "Found and well-formed (~366 tokens). Has H1, summary, and links." },
    { "id": "schema", "name": "Schema Markup", "status": "warn",
      "score": 14, "maxScore": 15,
      "detail": "FAQPage, Organization, WebSite, HowTo, Article present.",
      "fix": "Add BreadcrumbList schema for full coverage." }
  ]
}

curl https://coven-mission-control-production.up.railway.app/api/v1/geo/sites/1/citability \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "url": "https://yoursite.com",
  "overall": 71,
  "grade": "B",
  "summary": "Strong statistical density but lacks original research signals.",
  "dimensions": {
    "answerBlockQuality": 72, "selfContainment": 68,
    "structuralReadability": 78, "statisticalDensity": 85, "uniquenessSignals": 45
  },
  "recommendations": [
    "Add expert credentials or author bylines to establish E-E-A-T signals",
    "Include original research or proprietary data to boost uniqueness",
    "Ensure key passages are 134–167 words — optimal range for AI citation"
  ],
  "optimalWordCount": true
}

curl -X POST https://coven-mission-control-production.up.railway.app/api/v1/geo/sites/1/visibility/run \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "platform": "perplexity_heuristic",
  "citedCount": 0, "totalPrompts": 5, "citationRate": 0,
  "results": [
    { "promptId": 1, "label": "SEO audit tool — UK SMB", "cited": false }
  ]
}

{
  "ownSite": { "citationRate": 0, "geoGrade": "A" },
  "competitors": [{ "url": "https://competitor.com", "citationRate": 0 }],
  "yourRank": 1, "gapToLeader": 0,
  "promptBreakdown": [
    { "label": "Best SEO audit tool UK",
      "results": [{ "url": "yoursite.com", "isOwn": true, "cited": false }] }
  ]
}

curl -X POST https://coven-mission-control-production.up.railway.app/api/v1/geo/prompts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "Best SEO audit tool for small businesses UK?", "label": "SEO audit — UK SMB" }'

curl -X POST https://coven-mission-control-production.up.railway.app/api/tools/llmstxt \
  -H "Content-Type: application/json" -d '{ "url": "yoursite.com" }'

curl -X POST https://coven-mission-control-production.up.railway.app/api/tools/citability \
  -H "Content-Type: application/json" -d '{ "url": "yoursite.com" }'